Copyright: API32WH.HLP


Appendices (Win32)

Constants

Data Types

Error Codes

Virtual-Key Codes

Locale Identifiers

Multimedia Manufacturer and Product Identifiers

MCI Command String Syntax Summary

Binary and Ternary Raster-Operation Codes


Error Codes

Alphabetical List of Error Codes

Numerical List of Error Codes


Alphabetical List of Error Codes

Error Code	Description

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_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_ADAP_HDW_ERR

A network adapter hardware error occurred.

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_RUNNING_LKG

The system is currently running with the last-known-good configuration.

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_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_CANCEL_VIOLATION

A lock request was not outstanding for the supplied cancel region.

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_CONNECTION_UNAVAIL

The device is not currently connected but is a remembered connection.

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_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_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_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

End of tape mark was reached during an operation.

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_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_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_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_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_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_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_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_PRIMARY_GROUP

Indicates a particular Security ID cannot be assigned as the primary group of an object.

ERROR_INVALID_PRINTER_COMMAND

The printer command is invalid.

ERROR_INVALID_PRINTER_NAME

The printer name 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_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_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_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_LOGON_FAILURE

The attempted logon is invalid. This is due to either a bad username 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_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_META_EXPANSION_TOO_LONG

The global filename characters * or ? are entered incorrectly, or too many global filename characters are specified.

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_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_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_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_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_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_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_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_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_PARTITION_FAILURE

Tape could not be partitioned.

ERROR_PASSWORD_EXPIRED

The user account's password has expired.

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_POSSIBLE_DEADLOCK

A potential deadlock condition has been detected.

ERROR_PRINT_CANCELLED

File waiting to be printed was deleted.

ERROR_PRINTER_ALREADY_EXISTS

The printer already exists.

ERROR_PRINTER_DRIVER_ALREADY_INSTALLED

The specified printer driver is already installed.

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_READ_FAULT

The system cannot read from the specified device.

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_NOT_ENOUGH_QUOTA

Not enough quota is available to process this command.

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_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_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 an 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_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_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_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_STACK_OVERFLOW

Recursion too deep, stack overflowed.

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_SWAPERROR

Error accessing paging file.

ERROR_SYSTEM_TRACE

System trace information not specified in your CONFIG.SYS file, or tracing is not allowed.

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

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_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_BIND

An attempt to bind with the server failed.

RPC_S_CANNOT_SUPPORT

The requested operation is not supported.

RPC_S_CANT_CREATE_ENDPOINT

The endpoint cannot be created.

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_NAF_IF

The network address family 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_INTERFACES_EXPORTED

No interfaces were exported.

RPC_S_NO_MORE_BINDINGS

There are no more bindings.

RPC_S_NO_MORE_MEMBERS

There are no more members.

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_NOTHING_TO_UNEXPORT

There is nothing to unexport.

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_SERVER_NOT_LISTENING

The server is not listening for remote procedure calls.

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


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

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

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

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

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

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

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

1729L RPC_S_CANNOT_BIND

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

1738L RPC_S_SERVER_NOT_LISTENING

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

1754L RPC_S_NO_INTERFACES_EXPORTED

1755L RPC_S_INCOMPLETE_NAME

1756L RPC_S_INVALID_VERS_OPTION

1757L RPC_S_NO_MORE_MEMBERS

1758L RPC_S_NOTHING_TO_UNEXPORT

1759L RPC_S_INTERFACE_NOT_FOUND

1760L RPC_S_ENTRY_ALREADY_EXISTS

1761L RPC_S_ENTRY_NOT_FOUND

1762L RPC_S_NAME_SERVICE_UNAVAILABLE

1763L RPC_S_INVALID_NAF_IF

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

1898L RPC_S_GROUP_MEMBER_NOT_FOUND

1899L EPT_S_CANT_CREATE

1900L RPC_S_INVALID_OBJECT

2138L ERROR_NO_NETWORK

2202L ERROR_BAD_USERNAME

2250L ERROR_NOT_CONNECTED

2401L ERROR_OPEN_FILES

2404L ERROR_DEVICE_IN_USE

6118L ERROR_NO_BROWSER_SERVERS_FOUND


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
ERROR_ACCESS_DENIED  5L  winerror.h

Access is denied.


FN_ERROR_ACCESS_DENIED
ERROR_ACCESS_DENIED  5L  winerror.h


ERROR_ACCOUNT_DISABLED
ERROR_ACCOUNT_DISABLED  1331L  winerror.h

The referenced account is currently disabled and cannot be logged on to.


FN_ERROR_ACCOUNT_DISABLED
ERROR_ACCOUNT_DISABLED  1331L  winerror.h


ERROR_ACCOUNT_EXPIRED
ERROR_ACCOUNT_EXPIRED  1793L  winerror.h

The user's account has expired.


FN_ERROR_ACCOUNT_EXPIRED
ERROR_ACCOUNT_EXPIRED  1793L  winerror.h


ERROR_ACCOUNT_RESTRICTION
ERROR_ACCOUNT_RESTRICTION  1327L  winerror.h

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


FN_ERROR_ACCOUNT_RESTRICTION
ERROR_ACCOUNT_RESTRICTION  1327L  winerror.h


ERROR_ADAP_HDW_ERR
ERROR_ADAP_HDW_ERR  57L  winerror.h

A network adapter hardware error occurred.


FN_ERROR_ADAP_HDW_ERR
ERROR_ADAP_HDW_ERR  57L  winerror.h


ERROR_ALIAS_EXISTS
ERROR_ALIAS_EXISTS  1379L  winerror.h

The specified alias already exists.


FN_ERROR_ALIAS_EXISTS
ERROR_ALIAS_EXISTS  1379L  winerror.h


ERROR_ALLOTTED_SPACE_EXCEEDED
ERROR_ALLOTTED_SPACE_EXCEEDED  1344L  winerror.h

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.


FN_ERROR_ALLOTTED_SPACE_EXCEEDED
ERROR_ALLOTTED_SPACE_EXCEEDED  1344L  winerror.h


ERROR_ALREADY_ASSIGNED
ERROR_ALREADY_ASSIGNED  85L  winerror.h

The local device name is already in use.


FN_ERROR_ALREADY_ASSIGNED
ERROR_ALREADY_ASSIGNED  85L  winerror.h


ERROR_ALREADY_EXISTS
ERROR_ALREADY_EXISTS  183L  winerror.h

Attempt to create file that already exists.


FN_ERROR_ALREADY_EXISTS
ERROR_ALREADY_EXISTS  183L  winerror.h


ERROR_ALREADY_RUNNING_LKG
ERROR_ALREADY_RUNNING_LKG  1074L  winerror.h

The system is currently running with the last-known-good configuration.


FN_ERROR_ALREADY_RUNNING_LKG
ERROR_ALREADY_RUNNING_LKG  1074L  winerror.h


ERROR_ARENA_TRASHED
ERROR_ARENA_TRASHED  7L  winerror.h

The storage control blocks were destroyed.


FN_ERROR_ARENA_TRASHED
ERROR_ARENA_TRASHED  7L  winerror.h


ERROR_ARITHMETIC_OVERFLOW
ERROR_ARITHMETIC_OVERFLOW  534L  winerror.h

Arithmetic result exceeded 32-bits.


FN_ERROR_ARITHMETIC_OVERFLOW
ERROR_ARITHMETIC_OVERFLOW  534L  winerror.h


ERROR_ATOMIC_LOCKS_NOT_SUPPORTED
ERROR_ATOMIC_LOCKS_NOT_SUPPORTED  174L  winerror.h

The file system does not support atomic changing of the lock type.


FN_ERROR_ATOMIC_LOCKS_NOT_SUPPORTED
ERROR_ATOMIC_LOCKS_NOT_SUPPORTED  174L  winerror.h


ERROR_AUTODATASEG_EXCEEDS_64k
ERROR_AUTODATASEG_EXCEEDS_64k  199L  winerror.h

The operating system cannot run this application program.


FN_ERROR_AUTODATASEG_EXCEEDS_64k
ERROR_AUTODATASEG_EXCEEDS_64k  199L  winerror.h


ERROR_BAD_ARGUMENTS
ERROR_BAD_ARGUMENTS  160L  winerror.h

The argument string passed to DosExecPgm is incorrect.


FN_ERROR_BAD_ARGUMENTS
ERROR_BAD_ARGUMENTS  160L  winerror.h


ERROR_BAD_COMMAND
ERROR_BAD_COMMAND  22L  winerror.h

The device does not recognize the command.


FN_ERROR_BAD_COMMAND
ERROR_BAD_COMMAND  22L  winerror.h


ERROR_BAD_DESCRIPTOR_FORMAT
ERROR_BAD_DESCRIPTOR_FORMAT  1361L  winerror.h

Indicates a security descriptor is not in the required format (absolute or self-relative).


FN_ERROR_BAD_DESCRIPTOR_FORMAT
ERROR_BAD_DESCRIPTOR_FORMAT  1361L  winerror.h


ERROR_BAD_DEV_TYPE
ERROR_BAD_DEV_TYPE  66L  winerror.h

The network resource type is incorrect.


FN_ERROR_BAD_DEV_TYPE
ERROR_BAD_DEV_TYPE  66L  winerror.h


ERROR_BAD_DEVICE
ERROR_BAD_DEVICE  1200L  winerror.h

The specified device name is invalid.


FN_ERROR_BAD_DEVICE
ERROR_BAD_DEVICE  1200L  winerror.h


ERROR_BAD_DRIVER_LEVEL
ERROR_BAD_DRIVER_LEVEL  119L  winerror.h

The system does not support the requested command.


FN_ERROR_BAD_DRIVER_LEVEL
ERROR_BAD_DRIVER_LEVEL  119L  winerror.h


ERROR_BAD_ENVIRONMENT
ERROR_BAD_ENVIRONMENT  10L  winerror.h

The environment is incorrect.


FN_ERROR_BAD_ENVIRONMENT
ERROR_BAD_ENVIRONMENT  10L  winerror.h


ERROR_BAD_EXE_FORMAT
ERROR_BAD_EXE_FORMAT  193L  winerror.h

%1 is not a valid Windows-based application.


FN_ERROR_BAD_EXE_FORMAT
ERROR_BAD_EXE_FORMAT  193L  winerror.h


ERROR_BAD_FORMAT
ERROR_BAD_FORMAT  11L  winerror.h

An attempt was made to load a program with an incorrect format.


FN_ERROR_BAD_FORMAT
ERROR_BAD_FORMAT  11L  winerror.h


ERROR_BAD_IMPERSONATION_LEVEL
ERROR_BAD_IMPERSONATION_LEVEL  1346L  winerror.h

A specified impersonation level is invalid. Also used to indicate a required impersonation level was not provided.


FN_ERROR_BAD_IMPERSONATION_LEVEL
ERROR_BAD_IMPERSONATION_LEVEL  1346L  winerror.h


ERROR_BAD_INHERITANCE_ACL
ERROR_BAD_INHERITANCE_ACL  1340L  winerror.h

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.


FN_ERROR_BAD_INHERITANCE_ACL
ERROR_BAD_INHERITANCE_ACL  1340L  winerror.h


ERROR_BAD_LENGTH
ERROR_BAD_LENGTH  24L  winerror.h

The program issued a command but the command length is incorrect.


FN_ERROR_BAD_LENGTH
ERROR_BAD_LENGTH  24L  winerror.h


ERROR_BAD_LOGON_SESSION_STATE
ERROR_BAD_LOGON_SESSION_STATE  1365L  winerror.h

The logon session is not in a state consistent with the requested operation.


FN_ERROR_BAD_LOGON_SESSION_STATE
ERROR_BAD_LOGON_SESSION_STATE  1365L  winerror.h


ERROR_BAD_NET_NAME
ERROR_BAD_NET_NAME  67L  winerror.h

The network name cannot be found.


FN_ERROR_BAD_NET_NAME
ERROR_BAD_NET_NAME  67L  winerror.h


ERROR_BAD_NET_RESP
ERROR_BAD_NET_RESP  58L  winerror.h

The specified server cannot perform the requested operation.


FN_ERROR_BAD_NET_RESP
ERROR_BAD_NET_RESP  58L  winerror.h


ERROR_BAD_NETPATH
ERROR_BAD_NETPATH  53L  winerror.h

The network path was not found.


FN_ERROR_BAD_NETPATH
ERROR_BAD_NETPATH  53L  winerror.h


ERROR_BAD_PATHNAME
ERROR_BAD_PATHNAME  161L  winerror.h

The specified path name is invalid.


FN_ERROR_BAD_PATHNAME
ERROR_BAD_PATHNAME  161L  winerror.h


ERROR_BAD_PIPE
ERROR_BAD_PIPE  230L  winerror.h

The pipe state is invalid.


FN_ERROR_BAD_PIPE
ERROR_BAD_PIPE  230L  winerror.h


ERROR_BAD_PROFILE
ERROR_BAD_PROFILE  1206L  winerror.h

The network connection profile is damaged.


FN_ERROR_BAD_PROFILE
ERROR_BAD_PROFILE  1206L  winerror.h


ERROR_BAD_PROVIDER
ERROR_BAD_PROVIDER  1204L  winerror.h

The specified network provider name is invalid.


FN_ERROR_BAD_PROVIDER
ERROR_BAD_PROVIDER  1204L  winerror.h


ERROR_BAD_REM_ADAP
ERROR_BAD_REM_ADAP  60L  winerror.h

The remote adapter is not compatible.


FN_ERROR_BAD_REM_ADAP
ERROR_BAD_REM_ADAP  60L  winerror.h


ERROR_BAD_THREADID_ADDR
ERROR_BAD_THREADID_ADDR  159L  winerror.h

The address for the thread ID is incorrect.


FN_ERROR_BAD_THREADID_ADDR
ERROR_BAD_THREADID_ADDR  159L  winerror.h


ERROR_BAD_TOKEN_TYPE
ERROR_BAD_TOKEN_TYPE  1349L  winerror.h

The type of token object is inappropriate for its attempted use.


FN_ERROR_BAD_TOKEN_TYPE
ERROR_BAD_TOKEN_TYPE  1349L  winerror.h


ERROR_BAD_UNIT
ERROR_BAD_UNIT  20L  winerror.h

The system cannot find the specified device.


FN_ERROR_BAD_UNIT
ERROR_BAD_UNIT  20L  winerror.h


ERROR_BAD_USERNAME
ERROR_BAD_USERNAME  2202L  winerror.h

The specified user name is invalid.


FN_ERROR_BAD_USERNAME
ERROR_BAD_USERNAME  2202L  winerror.h


ERROR_BAD_VALIDATION_CLASS
ERROR_BAD_VALIDATION_CLASS  1348L  winerror.h

The requested validation information class is invalid.


FN_ERROR_BAD_VALIDATION_CLASS
ERROR_BAD_VALIDATION_CLASS  1348L  winerror.h


ERROR_BADDB
ERROR_BADDB  1009L  winerror.h

The configuration registry database is damaged.


FN_ERROR_BADDB
ERROR_BADDB  1009L  winerror.h


ERROR_BADKEY
ERROR_BADKEY  1010L  winerror.h

The configuration registry key is invalid.


FN_ERROR_BADKEY
ERROR_BADKEY  1010L  winerror.h


ERROR_BEGINNING_OF_MEDIA
ERROR_BEGINNING_OF_MEDIA  1102L  winerror.h

The beginning of the tape or partition was encountered.


FN_ERROR_BEGINNING_OF_MEDIA
ERROR_BEGINNING_OF_MEDIA  1102L  winerror.h


ERROR_BOOT_ALREADY_ACCEPTED
ERROR_BOOT_ALREADY_ACCEPTED  1076L  winerror.h

The current boot has already been accepted for use as the last-known-good control set.


FN_ERROR_BOOT_ALREADY_ACCEPTED
ERROR_BOOT_ALREADY_ACCEPTED  1076L  winerror.h


ERROR_BROKEN_PIPE
ERROR_BROKEN_PIPE  109L  winerror.h

The pipe was ended.


FN_ERROR_BROKEN_PIPE
ERROR_BROKEN_PIPE  109L  winerror.h


ERROR_BUFFER_OVERFLOW
ERROR_BUFFER_OVERFLOW  111L  winerror.h

The file name is too long.


FN_ERROR_BUFFER_OVERFLOW
ERROR_BUFFER_OVERFLOW  111L  winerror.h


ERROR_BUS_RESET
ERROR_BUS_RESET  1111L  winerror.h

The I/O bus was reset.


FN_ERROR_BUS_RESET
ERROR_BUS_RESET  1111L  winerror.h


ERROR_BUSY
ERROR_BUSY  170L  winerror.h

The requested resource is in use.


FN_ERROR_BUSY
ERROR_BUSY  170L  winerror.h


ERROR_BUSY_DRIVE
ERROR_BUSY_DRIVE  142L  winerror.h

The system cannot perform a JOIN or SUBST at this time.


FN_ERROR_BUSY_DRIVE
ERROR_BUSY_DRIVE  142L  winerror.h


ERROR_CALL_NOT_IMPLEMENTED
ERROR_CALL_NOT_IMPLEMENTED  120L  winerror.h

The Application Program Interface (API) entered will only work in Windows/NT mode.


FN_ERROR_CALL_NOT_IMPLEMENTED
ERROR_CALL_NOT_IMPLEMENTED  120L  winerror.h


ERROR_CAN_NOT_COMPLETE
ERROR_CAN_NOT_COMPLETE  1003L  winerror.h

Cannot complete function for some reason.


FN_ERROR_CAN_NOT_COMPLETE
ERROR_CAN_NOT_COMPLETE  1003L  winerror.h


ERROR_CANCEL_VIOLATION
ERROR_CANCEL_VIOLATION  173L  winerror.h

A lock request was not outstanding for the supplied cancel region.


FN_ERROR_CANCEL_VIOLATION
ERROR_CANCEL_VIOLATION  173L  winerror.h


ERROR_CANNOT_COPY
ERROR_CANNOT_COPY  266L  winerror.h

The Copy API cannot be used.


FN_ERROR_CANNOT_COPY
ERROR_CANNOT_COPY  266L  winerror.h


ERROR_CANNOT_FIND_WND_CLASS
ERROR_CANNOT_FIND_WND_CLASS  1407L  winerror.h

Cannot find window class.


FN_ERROR_CANNOT_FIND_WND_CLASS
ERROR_CANNOT_FIND_WND_CLASS  1407L  winerror.h


ERROR_CANNOT_IMPERSONATE
ERROR_CANNOT_IMPERSONATE  1368L  winerror.h

Indicates that an attempt was made to impersonate via a named pipe was not yet read from.


FN_ERROR_CANNOT_IMPERSONATE
ERROR_CANNOT_IMPERSONATE  1368L  winerror.h


ERROR_CANNOT_MAKE
ERROR_CANNOT_MAKE  82L  winerror.h

The directory or file cannot be created.


FN_ERROR_CANNOT_MAKE
ERROR_CANNOT_MAKE  82L  winerror.h


ERROR_CANNOT_OPEN_PROFILE
ERROR_CANNOT_OPEN_PROFILE  1205L  winerror.h

Unable to open the network connection profile.


FN_ERROR_CANNOT_OPEN_PROFILE
ERROR_CANNOT_OPEN_PROFILE  1205L  winerror.h


ERROR_CANT_ACCESS_DOMAIN_INFO
ERROR_CANT_ACCESS_DOMAIN_INFO  1351L  winerror.h

Indicates a domain controller could not be contacted or that objects within the domain are protected and necessary information could not be retrieved.


FN_ERROR_CANT_ACCESS_DOMAIN_INFO
ERROR_CANT_ACCESS_DOMAIN_INFO  1351L  winerror.h


ERROR_CANT_DISABLE_MANDATORY
ERROR_CANT_DISABLE_MANDATORY  1310L  winerror.h

A mandatory group cannot be disabled.


FN_ERROR_CANT_DISABLE_MANDATORY
ERROR_CANT_DISABLE_MANDATORY  1310L  winerror.h


ERROR_CANT_OPEN_ANONYMOUS
ERROR_CANT_OPEN_ANONYMOUS  1347L  winerror.h

An attempt was made to open an anonymous level token. Anonymous tokens cannot be opened.


FN_ERROR_CANT_OPEN_ANONYMOUS
ERROR_CANT_OPEN_ANONYMOUS  1347L  winerror.h


ERROR_CANTOPEN
ERROR_CANTOPEN  1011L  winerror.h

The configuration registry key cannot be opened.


FN_ERROR_CANTOPEN
ERROR_CANTOPEN  1011L  winerror.h


ERROR_CANTREAD
ERROR_CANTREAD  1012L  winerror.h

The configuration registry key cannot be read.


FN_ERROR_CANTREAD
ERROR_CANTREAD  1012L  winerror.h


ERROR_CANTWRITE
ERROR_CANTWRITE  1013L  winerror.h

The configuration registry key cannot be written.


FN_ERROR_CANTWRITE
ERROR_CANTWRITE  1013L  winerror.h


ERROR_CHILD_MUST_BE_VOLATILE
ERROR_CHILD_MUST_BE_VOLATILE  1021L  winerror.h

An attempt was made to create a stable subkey under a volatile parent key.


FN_ERROR_CHILD_MUST_BE_VOLATILE
ERROR_CHILD_MUST_BE_VOLATILE  1021L  winerror.h


ERROR_CHILD_NOT_COMPLETE
ERROR_CHILD_NOT_COMPLETE  129L  winerror.h

The %1 application cannot be run in Windows mode.


FN_ERROR_CHILD_NOT_COMPLETE
ERROR_CHILD_NOT_COMPLETE  129L  winerror.h


ERROR_CHILD_WINDOW_MENU
ERROR_CHILD_WINDOW_MENU  1436L  winerror.h

Child windows can't have menus.


FN_ERROR_CHILD_WINDOW_MENU
ERROR_CHILD_WINDOW_MENU  1436L  winerror.h


ERROR_CIRCULAR_DEPENDENCY
ERROR_CIRCULAR_DEPENDENCY  1059L  winerror.h

Circular service dependency was specified.


FN_ERROR_CIRCULAR_DEPENDENCY
ERROR_CIRCULAR_DEPENDENCY  1059L  winerror.h


ERROR_CLASS_ALREADY_EXISTS
ERROR_CLASS_ALREADY_EXISTS  1410L  winerror.h

Class already exists.


FN_ERROR_CLASS_ALREADY_EXISTS
ERROR_CLASS_ALREADY_EXISTS  1410L  winerror.h


ERROR_CLASS_DOES_NOT_EXIST
ERROR_CLASS_DOES_NOT_EXIST  1411L  winerror.h

Class does not exist.


FN_ERROR_CLASS_DOES_NOT_EXIST
ERROR_CLASS_DOES_NOT_EXIST  1411L  winerror.h


ERROR_CLASS_HAS_WINDOWS
ERROR_CLASS_HAS_WINDOWS  1412L  winerror.h

Class still has open windows.


FN_ERROR_CLASS_HAS_WINDOWS
ERROR_CLASS_HAS_WINDOWS  1412L  winerror.h


ERROR_CLIPBOARD_NOT_OPEN
ERROR_CLIPBOARD_NOT_OPEN  1418L  winerror.h

Thread doesn't have clipboard open.


FN_ERROR_CLIPBOARD_NOT_OPEN
ERROR_CLIPBOARD_NOT_OPEN  1418L  winerror.h


ERROR_CONNECTION_UNAVAIL
ERROR_CONNECTION_UNAVAIL  1201L  winerror.h

The device is not currently connected but is a remembered connection.


FN_ERROR_CONNECTION_UNAVAIL
ERROR_CONNECTION_UNAVAIL  1201L  winerror.h


ERROR_CONTROL_ID_NOT_FOUND
ERROR_CONTROL_ID_NOT_FOUND  1421L  winerror.h

Control ID not found.


FN_ERROR_CONTROL_ID_NOT_FOUND
ERROR_CONTROL_ID_NOT_FOUND  1421L  winerror.h


ERROR_COUNTER_TIMEOUT
ERROR_COUNTER_TIMEOUT  1121L  winerror.h

A serial I/O operation completed because the time-out period expired. (The IOCTL_SERIAL_XOFF_COUNTER did not reach zero.)


FN_ERROR_COUNTER_TIMEOUT
ERROR_COUNTER_TIMEOUT  1121L  winerror.h


ERROR_CRC
ERROR_CRC  23L  winerror.h

Data error (cyclic redundancy check).


FN_ERROR_CRC
ERROR_CRC  23L  winerror.h


ERROR_CURRENT_DIRECTORY
ERROR_CURRENT_DIRECTORY  16L  winerror.h

The directory cannot be removed.


FN_ERROR_CURRENT_DIRECTORY
ERROR_CURRENT_DIRECTORY  16L  winerror.h


ERROR_DATABASE_DOES_NOT_EXIST
ERROR_DATABASE_DOES_NOT_EXIST  1065L  winerror.h

The database specified does not exist.


FN_ERROR_DATABASE_DOES_NOT_EXIST
ERROR_DATABASE_DOES_NOT_EXIST  1065L  winerror.h


ERROR_DC_NOT_FOUND
ERROR_DC_NOT_FOUND  1425L  winerror.h

Invalid HDC passed to ReleaseDC.


FN_ERROR_DC_NOT_FOUND
ERROR_DC_NOT_FOUND  1425L  winerror.h


ERROR_DEPENDENT_SERVICES_RUNNING
ERROR_DEPENDENT_SERVICES_RUNNING  1051L  winerror.h

A stop control has been sent to a service which other running services are dependent on.


FN_ERROR_DEPENDENT_SERVICES_RUNNING
ERROR_DEPENDENT_SERVICES_RUNNING  1051L  winerror.h


ERROR_DESTROY_OBJECT_OF_OTHER_THREAD
ERROR_DESTROY_OBJECT_OF_OTHER_THREAD  1435L  winerror.h

Cannot destroy object created by another thread.


FN_ERROR_DESTROY_OBJECT_OF_OTHER_THREAD
ERROR_DESTROY_OBJECT_OF_OTHER_THREAD  1435L  winerror.h


ERROR_DEV_NOT_EXIST
ERROR_DEV_NOT_EXIST  55L  winerror.h

The specified network resource is no longer available.


FN_ERROR_DEV_NOT_EXIST
ERROR_DEV_NOT_EXIST  55L  winerror.h


ERROR_DEVICE_ALREADY_REMEMBERED
ERROR_DEVICE_ALREADY_REMEMBERED  1202L  winerror.h

An attempt was made to remember a device that was previously remembered.


FN_ERROR_DEVICE_ALREADY_REMEMBERED
ERROR_DEVICE_ALREADY_REMEMBERED  1202L  winerror.h


ERROR_DEVICE_IN_USE
ERROR_DEVICE_IN_USE  2404L  winerror.h

The device is in use by an active process and cannot be disconnected.


FN_ERROR_DEVICE_IN_USE
ERROR_DEVICE_IN_USE  2404L  winerror.h


ERROR_DEVICE_NOT_PARTITIONED
ERROR_DEVICE_NOT_PARTITIONED  1107L  winerror.h

Tape partition information could not be found when loading a tape.


FN_ERROR_DEVICE_NOT_PARTITIONED
ERROR_DEVICE_NOT_PARTITIONED  1107L  winerror.h


ERROR_DIR_NOT_EMPTY
ERROR_DIR_NOT_EMPTY  145L  winerror.h

The directory is not empty.


FN_ERROR_DIR_NOT_EMPTY
ERROR_DIR_NOT_EMPTY  145L  winerror.h


ERROR_DIR_NOT_ROOT
ERROR_DIR_NOT_ROOT  144L  winerror.h

The directory is not a subdirectory of the root directory.


FN_ERROR_DIR_NOT_ROOT
ERROR_DIR_NOT_ROOT  144L  winerror.h


ERROR_DIRECT_ACCESS_HANDLE
ERROR_DIRECT_ACCESS_HANDLE  130L  winerror.h

Attempt to use a file handle to an open disk partition for an operation other than raw disk I/O.


FN_ERROR_DIRECT_ACCESS_HANDLE
ERROR_DIRECT_ACCESS_HANDLE  130L  winerror.h


ERROR_DIRECTORY
ERROR_DIRECTORY  267L  winerror.h

The directory name is invalid.


FN_ERROR_DIRECTORY
ERROR_DIRECTORY  267L  winerror.h


ERROR_DISCARDED
ERROR_DISCARDED  157L  winerror.h

The segment is already discarded and cannot be locked.


FN_ERROR_DISCARDED
ERROR_DISCARDED  157L  winerror.h


ERROR_DISK_CHANGE
ERROR_DISK_CHANGE  107L  winerror.h

Program stopped because alternate disk was not inserted.


FN_ERROR_DISK_CHANGE
ERROR_DISK_CHANGE  107L  winerror.h


ERROR_DISK_CORRUPT
ERROR_DISK_CORRUPT  1393L  winerror.h

The disk structure is damaged and nonreadable.


FN_ERROR_DISK_CORRUPT
ERROR_DISK_CORRUPT  1393L  winerror.h


ERROR_DISK_FULL
ERROR_DISK_FULL  112L  winerror.h

There is not enough space on the disk.


FN_ERROR_DISK_FULL
ERROR_DISK_FULL  112L  winerror.h


ERROR_DISK_OPERATION_FAILED
ERROR_DISK_OPERATION_FAILED  1127L  winerror.h

While accessing the hard disk, a disk operation failed even after retries.


FN_ERROR_DISK_OPERATION_FAILED
ERROR_DISK_OPERATION_FAILED  1127L  winerror.h


ERROR_DISK_RECALIBRATE_FAILED
ERROR_DISK_RECALIBRATE_FAILED  1126L  winerror.h

While accessing the hard disk, a recalibrate operation failed, even after retries.


FN_ERROR_DISK_RECALIBRATE_FAILED
ERROR_DISK_RECALIBRATE_FAILED  1126L  winerror.h


ERROR_DISK_RESET_FAILED
ERROR_DISK_RESET_FAILED  1128L  winerror.h

While accessing the hard disk, a disk controller reset was needed, but even that failed.


FN_ERROR_DISK_RESET_FAILED
ERROR_DISK_RESET_FAILED  1128L  winerror.h


ERROR_DLL_INIT_FAILED
ERROR_DLL_INIT_FAILED  1114L  winerror.h

A DLL initialization routine failed.


FN_ERROR_DLL_INIT_FAILED
ERROR_DLL_INIT_FAILED  1114L  winerror.h


ERROR_DOMAIN_EXISTS
ERROR_DOMAIN_EXISTS  1356L  winerror.h

The specified domain already exists.


FN_ERROR_DOMAIN_EXISTS
ERROR_DOMAIN_EXISTS  1356L  winerror.h


ERROR_DOMAIN_LIMIT_EXCEEDED
ERROR_DOMAIN_LIMIT_EXCEEDED  1357L  winerror.h

An attempt to exceed the limit on the number of domains per server for this release.


FN_ERROR_DOMAIN_LIMIT_EXCEEDED
ERROR_DOMAIN_LIMIT_EXCEEDED  1357L  winerror.h


ERROR_DOMAIN_TRUST_INCONSISTENT
ERROR_DOMAIN_TRUST_INCONSISTENT  1810L  winerror.h

The name or security ID (SID) of the domain specified is inconsistent with the trust information for that domain.


FN_ERROR_DOMAIN_TRUST_INCONSISTENT
ERROR_DOMAIN_TRUST_INCONSISTENT  1810L  winerror.h


ERROR_DRIVE_LOCKED
ERROR_DRIVE_LOCKED  108L  winerror.h

The disk is in use or locked by another process.


FN_ERROR_DRIVE_LOCKED
ERROR_DRIVE_LOCKED  108L  winerror.h


ERROR_DUP_DOMAINNAME
ERROR_DUP_DOMAINNAME  1221L  winerror.h

The workgroup or domain name is already in use by another computer on the network.


FN_ERROR_DUP_DOMAINNAME
ERROR_DUP_DOMAINNAME  1221L  winerror.h


ERROR_DUP_NAME
ERROR_DUP_NAME  52L  winerror.h

A duplicate name exists on the network.


FN_ERROR_DUP_NAME
ERROR_DUP_NAME  52L  winerror.h


ERROR_DUPLICATE_SERVICE_NAME
ERROR_DUPLICATE_SERVICE_NAME  1078L  winerror.h

The name is already in use as either a service name or a service display name.


FN_ERROR_DUPLICATE_SERVICE_NAME
ERROR_DUPLICATE_SERVICE_NAME  1078L  winerror.h


ERROR_DYNLINK_FROM_INVALID_RING
ERROR_DYNLINK_FROM_INVALID_RING  196L  winerror.h

The operating system cannot run this application program.


FN_ERROR_DYNLINK_FROM_INVALID_RING
ERROR_DYNLINK_FROM_INVALID_RING  196L  winerror.h


ERROR_EA_ACCESS_DENIED
ERROR_EA_ACCESS_DENIED  994L  winerror.h

Access to the EA is denied.


FN_ERROR_EA_ACCESS_DENIED
ERROR_EA_ACCESS_DENIED  994L  winerror.h


ERROR_EA_FILE_CORRUPT
ERROR_EA_FILE_CORRUPT  276L  winerror.h

The EA file on the mounted file system is damaged.


FN_ERROR_EA_FILE_CORRUPT
ERROR_EA_FILE_CORRUPT  276L  winerror.h


ERROR_EA_LIST_INCONSISTENT
ERROR_EA_LIST_INCONSISTENT  255L  winerror.h

The EAs are inconsistent.


FN_ERROR_EA_LIST_INCONSISTENT
ERROR_EA_LIST_INCONSISTENT  255L  winerror.h


ERROR_EA_TABLE_FULL
ERROR_EA_TABLE_FULL  277L  winerror.h

The EA table in the EA file on the mounted file system is full.


FN_ERROR_EA_TABLE_FULL
ERROR_EA_TABLE_FULL  277L  winerror.h


ERROR_EAS_DIDNT_FIT
ERROR_EAS_DIDNT_FIT  275L  winerror.h

The EAs did not fit in the buffer.


FN_ERROR_EAS_DIDNT_FIT
ERROR_EAS_DIDNT_FIT  275L  winerror.h


ERROR_EAS_NOT_SUPPORTED
ERROR_EAS_NOT_SUPPORTED  282L  winerror.h

The mounted file system does not support extended attributes.


FN_ERROR_EAS_NOT_SUPPORTED
ERROR_EAS_NOT_SUPPORTED  282L  winerror.h


ERROR_END_OF_MEDIA
ERROR_END_OF_MEDIA  1100L  winerror.h

End of tape mark was reached during an operation.


FN_ERROR_END_OF_MEDIA
ERROR_END_OF_MEDIA  1100L  winerror.h


ERROR_ENVVAR_NOT_FOUND
ERROR_ENVVAR_NOT_FOUND  203L  winerror.h

The system could not find the environment option entered.


FN_ERROR_ENVVAR_NOT_FOUND
ERROR_ENVVAR_NOT_FOUND  203L  winerror.h


ERROR_EOM_OVERFLOW
ERROR_EOM_OVERFLOW  1129L  winerror.h

Physical end of tape encountered.


FN_ERROR_EOM_OVERFLOW
ERROR_EOM_OVERFLOW  1129L  winerror.h


ERROR_EVENTLOG_CANT_START
ERROR_EVENTLOG_CANT_START  1501L  winerror.h

No event log file could be opened, so the event logging service did not start.


FN_ERROR_EVENTLOG_CANT_START
ERROR_EVENTLOG_CANT_START  1501L  winerror.h


ERROR_EVENTLOG_FILE_CHANGED
ERROR_EVENTLOG_FILE_CHANGED  1503L  winerror.h

The event log file has changed between reads.


FN_ERROR_EVENTLOG_FILE_CHANGED
ERROR_EVENTLOG_FILE_CHANGED  1503L  winerror.h


ERROR_EVENTLOG_FILE_CORRUPT
ERROR_EVENTLOG_FILE_CORRUPT  1500L  winerror.h

One of the Eventlog logfiles is damaged.


FN_ERROR_EVENTLOG_FILE_CORRUPT
ERROR_EVENTLOG_FILE_CORRUPT  1500L  winerror.h


ERROR_EXCEPTION_IN_SERVICE
ERROR_EXCEPTION_IN_SERVICE  1064L  winerror.h

An exception occurred in the service when handling the control request.


FN_ERROR_EXCEPTION_IN_SERVICE
ERROR_EXCEPTION_IN_SERVICE  1064L  winerror.h


ERROR_EXCL_SEM_ALREADY_OWNED
ERROR_EXCL_SEM_ALREADY_OWNED  101L  winerror.h

The exclusive semaphore is owned by another process.


FN_ERROR_EXCL_SEM_ALREADY_OWNED
ERROR_EXCL_SEM_ALREADY_OWNED  101L  winerror.h


ERROR_EXE_MARKED_INVALID
ERROR_EXE_MARKED_INVALID  192L  winerror.h

The operating system cannot run %1.


FN_ERROR_EXE_MARKED_INVALID
ERROR_EXE_MARKED_INVALID  192L  winerror.h


ERROR_EXTENDED_ERROR
ERROR_EXTENDED_ERROR  1208L  winerror.h

An extended error has occurred.


FN_ERROR_EXTENDED_ERROR
ERROR_EXTENDED_ERROR  1208L  winerror.h


ERROR_FAIL_I24
ERROR_FAIL_I24  83L  winerror.h

Fail on INT 24.


FN_ERROR_FAIL_I24
ERROR_FAIL_I24  83L  winerror.h


ERROR_FAILED_SERVICE_CONTROLLER_CONNECT
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT  1063L  winerror.h

The service process could not connect to the service controller.


FN_ERROR_FAILED_SERVICE_CONTROLLER_CONNECT
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT  1063L  winerror.h


ERROR_FILE_CORRUPT
ERROR_FILE_CORRUPT  1392L  winerror.h

The file or directory is damaged and nonreadable.


FN_ERROR_FILE_CORRUPT
ERROR_FILE_CORRUPT  1392L  winerror.h


ERROR_FILE_EXISTS
ERROR_FILE_EXISTS  80L  winerror.h

The file exists.


FN_ERROR_FILE_EXISTS
ERROR_FILE_EXISTS  80L  winerror.h


ERROR_FILE_INVALID
ERROR_FILE_INVALID  1006L  winerror.h

The volume for a file was externally altered and the opened file is no longer valid.


FN_ERROR_FILE_INVALID
ERROR_FILE_INVALID  1006L  winerror.h


ERROR_FILE_NOT_FOUND
ERROR_FILE_NOT_FOUND  2L  winerror.h

The system cannot find the file specified.


FN_ERROR_FILE_NOT_FOUND
ERROR_FILE_NOT_FOUND  2L  winerror.h


ERROR_FILEMARK_DETECTED
ERROR_FILEMARK_DETECTED  1101L  winerror.h

A tape access reached a filemark.


FN_ERROR_FILEMARK_DETECTED
ERROR_FILEMARK_DETECTED  1101L  winerror.h


ERROR_FILENAME_EXCED_RANGE
ERROR_FILENAME_EXCED_RANGE  206L  winerror.h

The file name or extension is too long.


FN_ERROR_FILENAME_EXCED_RANGE
ERROR_FILENAME_EXCED_RANGE  206L  winerror.h


ERROR_FLOPPY_BAD_REGISTERS
ERROR_FLOPPY_BAD_REGISTERS  1125L  winerror.h

The floppy disk controller returned inconsistent results in its registers.


FN_ERROR_FLOPPY_BAD_REGISTERS
ERROR_FLOPPY_BAD_REGISTERS  1125L  winerror.h


ERROR_FLOPPY_ID_MARK_NOT_FOUND
ERROR_FLOPPY_ID_MARK_NOT_FOUND  1122L  winerror.h

No ID address mark was found on the floppy disk.


FN_ERROR_FLOPPY_ID_MARK_NOT_FOUND
ERROR_FLOPPY_ID_MARK_NOT_FOUND  1122L  winerror.h


ERROR_FLOPPY_WRONG_CYLINDER
ERROR_FLOPPY_WRONG_CYLINDER  1123L  winerror.h

Mismatch between the floppy disk sector ID field and the floppy disk controller track address.


FN_ERROR_FLOPPY_WRONG_CYLINDER
ERROR_FLOPPY_WRONG_CYLINDER  1123L  winerror.h


ERROR_FLOPPY_UNKNOWN_ERROR
ERROR_FLOPPY_UNKNOWN_ERROR  1124L  winerror.h

The floppy disk controller reported an error that is not recognized by the floppy disk driver.


FN_ERROR_FLOPPY_UNKNOWN_ERROR
ERROR_FLOPPY_UNKNOWN_ERROR  1124L  winerror.h


ERROR_FULLSCREEN_MODE
ERROR_FULLSCREEN_MODE  1007L  winerror.h

The requested operation cannot be performed in full-screen mode.


FN_ERROR_FULLSCREEN_MODE
ERROR_FULLSCREEN_MODE  1007L  winerror.h


ERROR_GEN_FAILURE
ERROR_GEN_FAILURE  31L  winerror.h

A device attached to the system is not functioning.


FN_ERROR_GEN_FAILURE
ERROR_GEN_FAILURE  31L  winerror.h


ERROR_GENERIC_NOT_MAPPED
ERROR_GENERIC_NOT_MAPPED  1360L  winerror.h

Indicates generic access types were contained in an access mask that should already be mapped to non-generic access types.


FN_ERROR_GENERIC_NOT_MAPPED
ERROR_GENERIC_NOT_MAPPED  1360L  winerror.h


ERROR_GLOBAL_ONLY_HOOK
ERROR_GLOBAL_ONLY_HOOK  1429L  winerror.h

This hook can only be set globally.


FN_ERROR_GLOBAL_ONLY_HOOK
ERROR_GLOBAL_ONLY_HOOK  1429L  winerror.h


ERROR_GROUP_EXISTS
ERROR_GROUP_EXISTS  1318L  winerror.h

The specified group already exists.


FN_ERROR_GROUP_EXISTS
ERROR_GROUP_EXISTS  1318L  winerror.h


ERROR_HANDLE_DISK_FULL
ERROR_HANDLE_DISK_FULL  39L  winerror.h

The disk is full.


FN_ERROR_HANDLE_DISK_FULL
ERROR_HANDLE_DISK_FULL  39L  winerror.h


ERROR_HANDLE_EOF
ERROR_HANDLE_EOF  38L  winerror.h

Reached End Of File.


FN_ERROR_HANDLE_EOF
ERROR_HANDLE_EOF  38L  winerror.h


ERROR_HOOK_NEEDS_HMOD
ERROR_HOOK_NEEDS_HMOD  1428L  winerror.h

Cannot set non-local hook without an module handle.


FN_ERROR_HOOK_NEEDS_HMOD
ERROR_HOOK_NEEDS_HMOD  1428L  winerror.h


ERROR_HOOK_NOT_INSTALLED
ERROR_HOOK_NOT_INSTALLED  1431L  winerror.h

Hook is not installed.


FN_ERROR_HOOK_NOT_INSTALLED
ERROR_HOOK_NOT_INSTALLED  1431L  winerror.h


ERROR_HOTKEY_ALREADY_REGISTERED
ERROR_HOTKEY_ALREADY_REGISTERED  1409L  winerror.h

Hotkey is already registered.


FN_ERROR_HOTKEY_ALREADY_REGISTERED
ERROR_HOTKEY_ALREADY_REGISTERED  1409L  winerror.h


ERROR_HOTKEY_NOT_REGISTERED
ERROR_HOTKEY_NOT_REGISTERED  1419L  winerror.h

Hotkey is not registered.


FN_ERROR_HOTKEY_NOT_REGISTERED
ERROR_HOTKEY_NOT_REGISTERED  1419L  winerror.h


ERROR_HWNDS_HAVE_DIFFERENT_PARENT

All DeferWindowPos HWNDs must have same parent.


ERROR_ILL_FORMED_PASSWORD
ERROR_ILL_FORMED_PASSWORD  1324L  winerror.h

When trying to update a password, this return status indicates the value provided for the new password contains values not allowed in passwords.


FN_ERROR_ILL_FORMED_PASSWORD
ERROR_ILL_FORMED_PASSWORD  1324L  winerror.h


ERROR_INFLOOP_IN_RELOC_CHAIN
ERROR_INFLOOP_IN_RELOC_CHAIN  202L  winerror.h

The operating system cannot run %1.


FN_ERROR_INFLOOP_IN_RELOC_CHAIN
ERROR_INFLOOP_IN_RELOC_CHAIN  202L  winerror.h


ERROR_INSUFFICIENT_BUFFER
ERROR_INSUFFICIENT_BUFFER  122L  winerror.h

The data area passed to a system call is too small.


FN_ERROR_INSUFFICIENT_BUFFER
ERROR_INSUFFICIENT_BUFFER  122L  winerror.h


ERROR_INTERNAL_DB_CORRUPTION
ERROR_INTERNAL_DB_CORRUPTION  1358L  winerror.h

This error indicates the requested operation cannot be completed due to a catastrophic media failure or on-disk data structure corruption.


FN_ERROR_INTERNAL_DB_CORRUPTION
ERROR_INTERNAL_DB_CORRUPTION  1358L  winerror.h


ERROR_INTERNAL_DB_ERROR
ERROR_INTERNAL_DB_ERROR  1383L  winerror.h

The Local Security Authority (LSA) database contains in internal inconsistency.


FN_ERROR_INTERNAL_DB_ERROR
ERROR_INTERNAL_DB_ERROR  1383L  winerror.h


ERROR_INTERNAL_ERROR
ERROR_INTERNAL_ERROR  1359L  winerror.h

This error indicates the SAM server has encounterred an internal consistency error in its database. This catastrophic failure prevents further operation of SAM.


FN_ERROR_INTERNAL_ERROR
ERROR_INTERNAL_ERROR  1359L  winerror.h


ERROR_INVALID_ACCEL_HANDLE
ERROR_INVALID_ACCEL_HANDLE  1403L  winerror.h

Invalid accelerator-table handle.


FN_ERROR_INVALID_ACCEL_HANDLE
ERROR_INVALID_ACCEL_HANDLE  1403L  winerror.h


ERROR_INVALID_ACCESS
ERROR_INVALID_ACCESS  12L  winerror.h

The access code is invalid.


FN_ERROR_INVALID_ACCESS
ERROR_INVALID_ACCESS  12L  winerror.h


ERROR_INVALID_ACCOUNT_NAME
ERROR_INVALID_ACCOUNT_NAME  1315L  winerror.h

The name provided is not a properly formed account name.


FN_ERROR_INVALID_ACCOUNT_NAME
ERROR_INVALID_ACCOUNT_NAME  1315L  winerror.h


ERROR_INVALID_ACL
ERROR_INVALID_ACL  1336L  winerror.h

Indicates the ACL structure is not valid.


FN_ERROR_INVALID_ACL
ERROR_INVALID_ACL  1336L  winerror.h


ERROR_INVALID_ADDRESS
ERROR_INVALID_ADDRESS  487L  winerror.h

Attempt to access invalid address.


FN_ERROR_INVALID_ADDRESS
ERROR_INVALID_ADDRESS  487L  winerror.h


ERROR_INVALID_AT_INTERRUPT_TIME
ERROR_INVALID_AT_INTERRUPT_TIME  104L  winerror.h

Cannot request exclusive semaphores at interrupt time.


FN_ERROR_INVALID_AT_INTERRUPT_TIME
ERROR_INVALID_AT_INTERRUPT_TIME  104L  winerror.h


ERROR_INVALID_BLOCK
ERROR_INVALID_BLOCK  9L  winerror.h

The storage control block address is invalid.


FN_ERROR_INVALID_BLOCK
ERROR_INVALID_BLOCK  9L  winerror.h


ERROR_INVALID_BLOCK_LENGTH
ERROR_INVALID_BLOCK_LENGTH  1106L  winerror.h

When accessing a new tape of a multivolume partition, the current block size is incorrect.


FN_ERROR_INVALID_BLOCK_LENGTH
ERROR_INVALID_BLOCK_LENGTH  1106L  winerror.h


ERROR_INVALID_CATEGORY
ERROR_INVALID_CATEGORY  117L  winerror.h

The IOCTL call made by the application program is incorrect.


FN_ERROR_INVALID_CATEGORY
ERROR_INVALID_CATEGORY  117L  winerror.h


ERROR_INVALID_COMBOBOX_MESSAGE
ERROR_INVALID_COMBOBOX_MESSAGE  1422L  winerror.h

Invalid Message, combo box doesn't have an edit control.


FN_ERROR_INVALID_COMBOBOX_MESSAGE
ERROR_INVALID_COMBOBOX_MESSAGE  1422L  winerror.h


ERROR_INVALID_COMPUTERNAME
ERROR_INVALID_COMPUTERNAME  1210L  winerror.h

The format of the specified computer name is invalid.


FN_ERROR_INVALID_COMPUTERNAME
ERROR_INVALID_COMPUTERNAME  1210L  winerror.h


ERROR_INVALID_CURSOR_HANDLE
ERROR_INVALID_CURSOR_HANDLE  1402L  winerror.h

The cursor handle is invalid.


FN_ERROR_INVALID_CURSOR_HANDLE
ERROR_INVALID_CURSOR_HANDLE  1402L  winerror.h


ERROR_INVALID_DATA
ERROR_INVALID_DATA  13L  winerror.h

The data is invalid.


FN_ERROR_INVALID_DATA
ERROR_INVALID_DATA  13L  winerror.h


ERROR_INVALID_DATATYPE
ERROR_INVALID_DATATYPE  1804L  winerror.h

The specified datatype is invalid.


FN_ERROR_INVALID_DATATYPE
ERROR_INVALID_DATATYPE  1804L  winerror.h


ERROR_INVALID_DOMAINNAME
ERROR_INVALID_DOMAINNAME  1212L  winerror.h

The format of the specified domain name is invalid.


FN_ERROR_INVALID_DOMAINNAME
ERROR_INVALID_DOMAINNAME  1212L  winerror.h


ERROR_INVALID_DOMAIN_ROLE
ERROR_INVALID_DOMAIN_ROLE  1354L  winerror.h

Indicates the requested operation cannot be completed with the domain in its present role.


FN_ERROR_INVALID_DOMAIN_ROLE
ERROR_INVALID_DOMAIN_ROLE  1354L  winerror.h


ERROR_INVALID_DOMAIN_STATE
ERROR_INVALID_DOMAIN_STATE  1353L  winerror.h

Indicates the domain is in the wrong state to perform the desired operation.


FN_ERROR_INVALID_DOMAIN_STATE
ERROR_INVALID_DOMAIN_STATE  1353L  winerror.h


ERROR_INVALID_DRIVE
ERROR_INVALID_DRIVE  15L  winerror.h

The system cannot find the specified drive.


FN_ERROR_INVALID_DRIVE
ERROR_INVALID_DRIVE  15L  winerror.h


ERROR_INVALID_DWP_HANDLE
ERROR_INVALID_DWP_HANDLE  1405L  winerror.h

The DeferWindowPos handle is invalid.


FN_ERROR_INVALID_DWP_HANDLE
ERROR_INVALID_DWP_HANDLE  1405L  winerror.h


ERROR_INVALID_EA_HANDLE
ERROR_INVALID_EA_HANDLE  278L  winerror.h

The specified EA handle is invalid.


FN_ERROR_INVALID_EA_HANDLE
ERROR_INVALID_EA_HANDLE  278L  winerror.h


ERROR_INVALID_EA_NAME
ERROR_INVALID_EA_NAME  254L  winerror.h

The specified EA name is invalid.


FN_ERROR_INVALID_EA_NAME
ERROR_INVALID_EA_NAME  254L  winerror.h


ERROR_INVALID_EDIT_HEIGHT
ERROR_INVALID_EDIT_HEIGHT  1424L  winerror.h

Height must be less than 256.


FN_ERROR_INVALID_EDIT_HEIGHT
ERROR_INVALID_EDIT_HEIGHT  1424L  winerror.h


ERROR_INVALID_ENVIRONMENT
ERROR_INVALID_ENVIRONMENT  1805L  winerror.h

The Environment specified is invalid.


FN_ERROR_INVALID_ENVIRONMENT
ERROR_INVALID_ENVIRONMENT  1805L  winerror.h


ERROR_INVALID_EVENT_COUNT
ERROR_INVALID_EVENT_COUNT  151L  winerror.h

The number of specified semaphore events is incorrect.


FN_ERROR_INVALID_EVENT_COUNT
ERROR_INVALID_EVENT_COUNT  151L  winerror.h


ERROR_INVALID_EVENTNAME
ERROR_INVALID_EVENTNAME  1211L  winerror.h

The format of the specified event name is invalid.


FN_ERROR_INVALID_EVENTNAME
ERROR_INVALID_EVENTNAME  1211L  winerror.h


ERROR_INVALID_EXE_SIGNATURE
ERROR_INVALID_EXE_SIGNATURE  191L  winerror.h

%1 cannot be run in Windows/NT mode.


FN_ERROR_INVALID_EXE_SIGNATURE
ERROR_INVALID_EXE_SIGNATURE  191L  winerror.h


ERROR_INVALID_FILTER_PROC
ERROR_INVALID_FILTER_PROC  1427L  winerror.h

The filter proc is invalid.


FN_ERROR_INVALID_FILTER_PROC
ERROR_INVALID_FILTER_PROC  1427L  winerror.h


ERROR_INVALID_FLAG_NUMBER
ERROR_INVALID_FLAG_NUMBER  186L  winerror.h

The flag passed is incorrect.


FN_ERROR_INVALID_FLAG_NUMBER
ERROR_INVALID_FLAG_NUMBER  186L  winerror.h


ERROR_INVALID_FLAGS
ERROR_INVALID_FLAGS  1004L  winerror.h

The flags are invalid.


FN_ERROR_INVALID_FLAGS
ERROR_INVALID_FLAGS  1004L  winerror.h


ERROR_INVALID_FUNCTION
ERROR_INVALID_FUNCTION  1L  winerror.h

The function is incorrect.


FN_ERROR_INVALID_FUNCTION
ERROR_INVALID_FUNCTION  1L  winerror.h


ERROR_INVALID_GROUP_ATTRIBUTES
ERROR_INVALID_GROUP_ATTRIBUTES  1345L  winerror.h

The specified attributes are invalid, or incompatible with the attributes for the group as a whole.


FN_ERROR_INVALID_GROUP_ATTRIBUTES
ERROR_INVALID_GROUP_ATTRIBUTES  1345L  winerror.h


ERROR_INVALID_GROUPNAME
ERROR_INVALID_GROUPNAME  1209L  winerror.h

The format of the specified group name is invalid.


FN_ERROR_INVALID_GROUPNAME
ERROR_INVALID_GROUPNAME  1209L  winerror.h


ERROR_INVALID_GW_COMMAND
ERROR_INVALID_GW_COMMAND  1443L  winerror.h

The GW_* command is invalid.


FN_ERROR_INVALID_GW_COMMAND
ERROR_INVALID_GW_COMMAND  1443L  winerror.h


ERROR_INVALID_HANDLE
ERROR_INVALID_HANDLE  6L  winerror.h

The internal file identifier is incorrect.


FN_ERROR_INVALID_HANDLE
ERROR_INVALID_HANDLE  6L  winerror.h


ERROR_INVALID_HOOK_FILTER
ERROR_INVALID_HOOK_FILTER  1426L  winerror.h

The hook filter type is invalid.


FN_ERROR_INVALID_HOOK_FILTER
ERROR_INVALID_HOOK_FILTER  1426L  winerror.h


ERROR_INVALID_HOOK_HANDLE
ERROR_INVALID_HOOK_HANDLE  1404L  winerror.h

The hook handle is invalid.


FN_ERROR_INVALID_HOOK_HANDLE
ERROR_INVALID_HOOK_HANDLE  1404L  winerror.h


ERROR_INVALID_ICON_HANDLE
ERROR_INVALID_ICON_HANDLE  1414L  winerror.h

The icon handle is invalid.


FN_ERROR_INVALID_ICON_HANDLE
ERROR_INVALID_ICON_HANDLE  1414L  winerror.h


ERROR_INVALID_ID_AUTHORITY
ERROR_INVALID_ID_AUTHORITY  1343L  winerror.h

The value provided is an invalid value for an identifier authority.


FN_ERROR_INVALID_ID_AUTHORITY
ERROR_INVALID_ID_AUTHORITY  1343L  winerror.h


ERROR_INVALID_INDEX
ERROR_INVALID_INDEX  1413L  winerror.h

The index is invalid.


FN_ERROR_INVALID_INDEX
ERROR_INVALID_INDEX  1413L  winerror.h


ERROR_INVALID_LB_MESSAGE
ERROR_INVALID_LB_MESSAGE  1432L  winerror.h

The message for single-selection list box is invalid.


FN_ERROR_INVALID_LB_MESSAGE
ERROR_INVALID_LB_MESSAGE  1432L  winerror.h


ERROR_INVALID_LEVEL
ERROR_INVALID_LEVEL  124L  winerror.h

The system call level is incorrect.


FN_ERROR_INVALID_LEVEL
ERROR_INVALID_LEVEL  124L  winerror.h


ERROR_INVALID_LIST_FORMAT
ERROR_INVALID_LIST_FORMAT  153L  winerror.h

The list is not correct.


FN_ERROR_INVALID_LIST_FORMAT
ERROR_INVALID_LIST_FORMAT  153L  winerror.h


ERROR_INVALID_LOGON_HOURS
ERROR_INVALID_LOGON_HOURS  1328L  winerror.h

The user account has time restrictions and cannot be logged onto at this time.


FN_ERROR_INVALID_LOGON_HOURS
ERROR_INVALID_LOGON_HOURS  1328L  winerror.h


ERROR_INVALID_LOGON_TYPE
ERROR_INVALID_LOGON_TYPE  1367L  winerror.h

Indicates an invalid value has been provided for LogonType has been requested.


FN_ERROR_INVALID_LOGON_TYPE
ERROR_INVALID_LOGON_TYPE  1367L  winerror.h


ERROR_INVALID_MEMBER
ERROR_INVALID_MEMBER  1388L  winerror.h

A new member could not be added to an alias because the member has the wrong account type.


FN_ERROR_INVALID_MEMBER
ERROR_INVALID_MEMBER  1388L  winerror.h


ERROR_INVALID_MENU_HANDLE
ERROR_INVALID_MENU_HANDLE  1401L  winerror.h

The menu handle is invalid.


FN_ERROR_INVALID_MENU_HANDLE
ERROR_INVALID_MENU_HANDLE  1401L  winerror.h


ERROR_INVALID_MESSAGE
ERROR_INVALID_MESSAGE  1002L  winerror.h

Window can't handle sent message.


FN_ERROR_INVALID_MESSAGE
ERROR_INVALID_MESSAGE  1002L  winerror.h


ERROR_INVALID_MESSAGEDEST
ERROR_INVALID_MESSAGEDEST  1218L  winerror.h

The format of the specified message destination is invalid.


FN_ERROR_INVALID_MESSAGEDEST
ERROR_INVALID_MESSAGEDEST  1218L  winerror.h


ERROR_INVALID_MESSAGENAME
ERROR_INVALID_MESSAGENAME  1217L  winerror.h

The format of the specified message name is invalid.


FN_ERROR_INVALID_MESSAGENAME
ERROR_INVALID_MESSAGENAME  1217L  winerror.h


ERROR_INVALID_MINALLOCSIZE
ERROR_INVALID_MINALLOCSIZE  195L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_MINALLOCSIZE
ERROR_INVALID_MINALLOCSIZE  195L  winerror.h


ERROR_INVALID_MODULETYPE
ERROR_INVALID_MODULETYPE  190L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_MODULETYPE
ERROR_INVALID_MODULETYPE  190L  winerror.h


ERROR_INVALID_MSGBOX_STYLE
ERROR_INVALID_MSGBOX_STYLE  1438L  winerror.h

The message box style is invalid.


FN_ERROR_INVALID_MSGBOX_STYLE
ERROR_INVALID_MSGBOX_STYLE  1438L  winerror.h


ERROR_INVALID_NAME
ERROR_INVALID_NAME  123L  winerror.h

The file name, directory name, or volume label is syntactically incorrect.


FN_ERROR_INVALID_NAME
ERROR_INVALID_NAME  123L  winerror.h


ERROR_INVALID_NETNAME
ERROR_INVALID_NETNAME  1214L  winerror.h

The format of the specified network name is invalid.


FN_ERROR_INVALID_NETNAME
ERROR_INVALID_NETNAME  1214L  winerror.h


ERROR_INVALID_ORDINAL
ERROR_INVALID_ORDINAL  182L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_ORDINAL
ERROR_INVALID_ORDINAL  182L  winerror.h


ERROR_INVALID_OWNER
ERROR_INVALID_OWNER  1307L  winerror.h

Indicates a particular Security ID cannot be assigned as the owner of an object.


FN_ERROR_INVALID_OWNER
ERROR_INVALID_OWNER  1307L  winerror.h


ERROR_INVALID_PARAMETER
ERROR_INVALID_PARAMETER  87L  winerror.h

The parameter is incorrect.


FN_ERROR_INVALID_PARAMETER
ERROR_INVALID_PARAMETER  87L  winerror.h


ERROR_INVALID_PASSWORD
ERROR_INVALID_PASSWORD  86L  winerror.h

The specified network password is incorrect.


FN_ERROR_INVALID_PASSWORD
ERROR_INVALID_PASSWORD  86L  winerror.h


ERROR_INVALID_PASSWORDNAME
ERROR_INVALID_PASSWORDNAME  1216L  winerror.h

The format of the specified password is invalid.


FN_ERROR_INVALID_PASSWORDNAME
ERROR_INVALID_PASSWORDNAME  1216L  winerror.h


ERROR_INVALID_PRIMARY_GROUP
ERROR_INVALID_PRIMARY_GROUP  1308L  winerror.h

Indicates a particular Security ID cannot be assigned as the primary group of an object.


FN_ERROR_INVALID_PRIMARY_GROUP
ERROR_INVALID_PRIMARY_GROUP  1308L  winerror.h


ERROR_INVALID_PRINTER_COMMAND
ERROR_INVALID_PRINTER_COMMAND  1803L  winerror.h

The printer command is invalid.


FN_ERROR_INVALID_PRINTER_COMMAND
ERROR_INVALID_PRINTER_COMMAND  1803L  winerror.h


ERROR_INVALID_PRINTER_NAME
ERROR_INVALID_PRINTER_NAME  1801L  winerror.h

The printer name is invalid.


FN_ERROR_INVALID_PRINTER_NAME
ERROR_INVALID_PRINTER_NAME  1801L  winerror.h


ERROR_INVALID_PRIORITY
ERROR_INVALID_PRIORITY  1800L  winerror.h

The specified priority is invalid.


FN_ERROR_INVALID_PRIORITY
ERROR_INVALID_PRIORITY  1800L  winerror.h


ERROR_INVALID_SCROLLBAR_RANGE
ERROR_INVALID_SCROLLBAR_RANGE  1448L  winerror.h

Scrollbar range greater than 0x7FFF.


FN_ERROR_INVALID_SCROLLBAR_RANGE
ERROR_INVALID_SCROLLBAR_RANGE  1448L  winerror.h


ERROR_INVALID_SECURITY_DESCR
ERROR_INVALID_SECURITY_DESCR  1338L  winerror.h

Indicates the SECURITY_DESCRIPTOR structure is invalid.


FN_ERROR_INVALID_SECURITY_DESCR
ERROR_INVALID_SECURITY_DESCR  1338L  winerror.h


ERROR_INVALID_SEGDPL
ERROR_INVALID_SEGDPL  198L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_SEGDPL
ERROR_INVALID_SEGDPL  198L  winerror.h


ERROR_INVALID_SEGMENT_NUMBER
ERROR_INVALID_SEGMENT_NUMBER  180L  winerror.h

The system detected a segment number that is incorrect.


FN_ERROR_INVALID_SEGMENT_NUMBER
ERROR_INVALID_SEGMENT_NUMBER  180L  winerror.h


ERROR_INVALID_SEPARATOR_FILE
ERROR_INVALID_SEPARATOR_FILE  1799L  winerror.h

The specified separator file is invalid.


FN_ERROR_INVALID_SEPARATOR_FILE
ERROR_INVALID_SEPARATOR_FILE  1799L  winerror.h


ERROR_INVALID_SERVER_STATE
ERROR_INVALID_SERVER_STATE  1352L  winerror.h

Indicates the Sam Server was in the wrong state to perform the desired operation.


FN_ERROR_INVALID_SERVER_STATE
ERROR_INVALID_SERVER_STATE  1352L  winerror.h


ERROR_INVALID_SERVICE_ACCOUNT
ERROR_INVALID_SERVICE_ACCOUNT  1057L  winerror.h

The account name is invalid or does not exist.


FN_ERROR_INVALID_SERVICE_ACCOUNT
ERROR_INVALID_SERVICE_ACCOUNT  1057L  winerror.h


ERROR_INVALID_SERVICE_CONTROL
ERROR_INVALID_SERVICE_CONTROL  1052L  winerror.h

The requested control is not valid for this service


FN_ERROR_INVALID_SERVICE_CONTROL
ERROR_INVALID_SERVICE_CONTROL  1052L  winerror.h


ERROR_INVALID_SERVICE_LOCK
ERROR_INVALID_SERVICE_LOCK  1071L  winerror.h

The specified service database lock is invalid.


FN_ERROR_INVALID_SERVICE_LOCK
ERROR_INVALID_SERVICE_LOCK  1071L  winerror.h


ERROR_INVALID_SERVICENAME
ERROR_INVALID_SERVICENAME  1213L  winerror.h

The format of the specified service name is invalid.


FN_ERROR_INVALID_SERVICENAME
ERROR_INVALID_SERVICENAME  1213L  winerror.h


ERROR_INVALID_SHARENAME
ERROR_INVALID_SHARENAME  1215L  winerror.h

The format of the specified share name is invalid.


FN_ERROR_INVALID_SHARENAME
ERROR_INVALID_SHARENAME  1215L  winerror.h


ERROR_INVALID_SHOWWIN_COMMAND
ERROR_INVALID_SHOWWIN_COMMAND  1449L  winerror.h

The ShowWindow command is invalid.


FN_ERROR_INVALID_SHOWWIN_COMMAND
ERROR_INVALID_SHOWWIN_COMMAND  1449L  winerror.h


ERROR_INVALID_SID
ERROR_INVALID_SID  1337L  winerror.h

Indicates the SID structure is invalid.


FN_ERROR_INVALID_SID
ERROR_INVALID_SID  1337L  winerror.h


ERROR_INVALID_SIGNAL_NUMBER
ERROR_INVALID_SIGNAL_NUMBER  209L  winerror.h

The signal being posted is incorrect.


FN_ERROR_INVALID_SIGNAL_NUMBER
ERROR_INVALID_SIGNAL_NUMBER  209L  winerror.h


ERROR_INVALID_SPI_VALUE
ERROR_INVALID_SPI_VALUE  1439L  winerror.h

The SPI_* parameter is invalid.


FN_ERROR_INVALID_SPI_VALUE
ERROR_INVALID_SPI_VALUE  1439L  winerror.h


ERROR_INVALID_STACKSEG
ERROR_INVALID_STACKSEG  189L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_STACKSEG
ERROR_INVALID_STACKSEG  189L  winerror.h


ERROR_INVALID_STARTING_CODESEG
ERROR_INVALID_STARTING_CODESEG  188L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_STARTING_CODESEG
ERROR_INVALID_STARTING_CODESEG  188L  winerror.h


ERROR_INVALID_SUB_AUTHORITY
ERROR_INVALID_SUB_AUTHORITY  1335L  winerror.h

Indicates the sub-authority value is invalid for the particular use.


FN_ERROR_INVALID_SUB_AUTHORITY
ERROR_INVALID_SUB_AUTHORITY  1335L  winerror.h


ERROR_INVALID_TARGET_HANDLE
ERROR_INVALID_TARGET_HANDLE  114L  winerror.h

The target internal file identifier is incorrect.


FN_ERROR_INVALID_TARGET_HANDLE
ERROR_INVALID_TARGET_HANDLE  114L  winerror.h


ERROR_INVALID_THREAD_ID
ERROR_INVALID_THREAD_ID  1444L  winerror.h

The thread ID is invalid.


FN_ERROR_INVALID_THREAD_ID
ERROR_INVALID_THREAD_ID  1444L  winerror.h


ERROR_INVALID_USER_BUFFER
ERROR_INVALID_USER_BUFFER  1784L  winerror.h

The supplied user buffer is invalid for the requested operation.


FN_ERROR_INVALID_USER_BUFFER
ERROR_INVALID_USER_BUFFER  1784L  winerror.h


ERROR_INVALID_VERIFY_SWITCH
ERROR_INVALID_VERIFY_SWITCH  118L  winerror.h

The verify-on-write switch parameter value is incorrect.


FN_ERROR_INVALID_VERIFY_SWITCH
ERROR_INVALID_VERIFY_SWITCH  118L  winerror.h


ERROR_INVALID_WINDOW_HANDLE
ERROR_INVALID_WINDOW_HANDLE  1400L  winerror.h

The window handle invalid.


FN_ERROR_INVALID_WINDOW_HANDLE
ERROR_INVALID_WINDOW_HANDLE  1400L  winerror.h


ERROR_INVALID_WORKSTATION
ERROR_INVALID_WORKSTATION  1329L  winerror.h

The user account is restricted and cannot be used to log on from the source workstation.


FN_ERROR_INVALID_WORKSTATION
ERROR_INVALID_WORKSTATION  1329L  winerror.h


ERROR_IO_DEVICE
ERROR_IO_DEVICE  1117L  winerror.h

The request could not be performed because of an I/O device error.


FN_ERROR_IO_DEVICE
ERROR_IO_DEVICE  1117L  winerror.h


ERROR_IO_INCOMPLETE
ERROR_IO_INCOMPLETE  996L  winerror.h

Overlapped IO event not in signaled state.


FN_ERROR_IO_INCOMPLETE
ERROR_IO_INCOMPLETE  996L  winerror.h


ERROR_IO_PENDING
ERROR_IO_PENDING  997L  winerror.h

Overlapped IO operation in progress.


FN_ERROR_IO_PENDING
ERROR_IO_PENDING  997L  winerror.h


ERROR_IOPL_NOT_ENABLED
ERROR_IOPL_NOT_ENABLED  197L  winerror.h

The operating system is not presently configured to run this application.


FN_ERROR_IOPL_NOT_ENABLED
ERROR_IOPL_NOT_ENABLED  197L  winerror.h


ERROR_IRQ_BUSY
ERROR_IRQ_BUSY  1119L  winerror.h

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.


FN_ERROR_IRQ_BUSY
ERROR_IRQ_BUSY  1119L  winerror.h


ERROR_IS_JOIN_PATH
ERROR_IS_JOIN_PATH  147L  winerror.h

Not enough resources are available to process this command.


FN_ERROR_IS_JOIN_PATH
ERROR_IS_JOIN_PATH  147L  winerror.h


ERROR_IS_JOIN_TARGET
ERROR_IS_JOIN_TARGET  133L  winerror.h

A JOIN or SUBST command cannot be used for a drive that contains previously joined drives.


FN_ERROR_IS_JOIN_TARGET
ERROR_IS_JOIN_TARGET  133L  winerror.h


ERROR_IS_JOINED
ERROR_IS_JOINED  134L  winerror.h

An attempt was made to use a JOIN or SUBST command on a drive that is already joined.


FN_ERROR_IS_JOINED
ERROR_IS_JOINED  134L  winerror.h


ERROR_IS_SUBST_PATH
ERROR_IS_SUBST_PATH  146L  winerror.h

The path specified is being used in a substitute.


FN_ERROR_IS_SUBST_PATH
ERROR_IS_SUBST_PATH  146L  winerror.h


ERROR_IS_SUBST_TARGET
ERROR_IS_SUBST_TARGET  149L  winerror.h

An attempt was made to join or substitute a drive for which a directory on the drive is the target of a previous substitute.


FN_ERROR_IS_SUBST_TARGET
ERROR_IS_SUBST_TARGET  149L  winerror.h


ERROR_IS_SUBSTED
ERROR_IS_SUBSTED  135L  winerror.h

An attempt was made to use a JOIN or SUBST command on a drive already substituted.


FN_ERROR_IS_SUBSTED
ERROR_IS_SUBSTED  135L  winerror.h


ERROR_ITERATED_DATA_EXCEEDS_64k
ERROR_ITERATED_DATA_EXCEEDS_64k  194L  winerror.h

The operating system cannot run %1.


FN_ERROR_ITERATED_DATA_EXCEEDS_64k
ERROR_ITERATED_DATA_EXCEEDS_64k  194L  winerror.h


ERROR_JOIN_TO_JOIN
ERROR_JOIN_TO_JOIN  138L  winerror.h

The system tried to join a drive to a directory on a joined drive.


FN_ERROR_JOIN_TO_JOIN
ERROR_JOIN_TO_JOIN  138L  winerror.h


ERROR_JOIN_TO_SUBST
ERROR_JOIN_TO_SUBST  140L  winerror.h

The system tried to join a drive to a directory on a substituted drive.


FN_ERROR_JOIN_TO_SUBST
ERROR_JOIN_TO_SUBST  140L  winerror.h


ERROR_JOURNAL_HOOK_SET
ERROR_JOURNAL_HOOK_SET  1430L  winerror.h

The journal hook is already installed.


FN_ERROR_JOURNAL_HOOK_SET
ERROR_JOURNAL_HOOK_SET  1430L  winerror.h


ERROR_KEY_DELETED
ERROR_KEY_DELETED  1018L  winerror.h

Illegal operation attempted on a registry key that has been marked for deletion.


FN_ERROR_KEY_DELETED
ERROR_KEY_DELETED  1018L  winerror.h


ERROR_KEY_HAS_CHILDREN
ERROR_KEY_HAS_CHILDREN  1020L  winerror.h

An attempt was made to create a symbolic link in a registry key that already has subkeys or values.


FN_ERROR_KEY_HAS_CHILDREN
ERROR_KEY_HAS_CHILDREN  1020L  winerror.h


ERROR_LABEL_TOO_LONG
ERROR_LABEL_TOO_LONG  154L  winerror.h

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.


FN_ERROR_LABEL_TOO_LONG
ERROR_LABEL_TOO_LONG  154L  winerror.h


ERROR_LAST_ADMIN
ERROR_LAST_ADMIN  1322L  winerror.h

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.


FN_ERROR_LAST_ADMIN
ERROR_LAST_ADMIN  1322L  winerror.h


ERROR_LB_WITHOUT_TABSTOPS
ERROR_LB_WITHOUT_TABSTOPS  1434L  winerror.h

This list box doesn't support tab stops.


FN_ERROR_LB_WITHOUT_TABSTOPS
ERROR_LB_WITHOUT_TABSTOPS  1434L  winerror.h


ERROR_LISTBOX_ID_NOT_FOUND
ERROR_LISTBOX_ID_NOT_FOUND  1416L  winerror.h

List box ID not found.


FN_ERROR_LISTBOX_ID_NOT_FOUND
ERROR_LISTBOX_ID_NOT_FOUND  1416L  winerror.h


ERROR_LM_CROSS_ENCRYPTION_REQUIRED
ERROR_LM_CROSS_ENCRYPTION_REQUIRED  1390L  winerror.h

An attempt was made to change a user password in the security account manager without providing the required LM cross-encrypted password.


FN_ERROR_LM_CROSS_ENCRYPTION_REQUIRED
ERROR_LM_CROSS_ENCRYPTION_REQUIRED  1390L  winerror.h


ERROR_LOCAL_USER_SESSION_KEY
ERROR_LOCAL_USER_SESSION_KEY  1303L  winerror.h

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.


FN_ERROR_LOCAL_USER_SESSION_KEY
ERROR_LOCAL_USER_SESSION_KEY  1303L  winerror.h


ERROR_LOCK_FAILED
ERROR_LOCK_FAILED  167L  winerror.h

Attempt to lock a region of a file failed.


FN_ERROR_LOCK_FAILED
ERROR_LOCK_FAILED  167L  winerror.h


ERROR_LOCK_VIOLATION
ERROR_LOCK_VIOLATION  33L  winerror.h

The process cannot access the file because another process has locked a portion of the file.


FN_ERROR_LOCK_VIOLATION
ERROR_LOCK_VIOLATION  33L  winerror.h


ERROR_LOCKED
ERROR_LOCKED  212L  winerror.h

The segment is locked and cannot be reallocated.


FN_ERROR_LOCKED
ERROR_LOCKED  212L  winerror.h


ERROR_LOG_FILE_FULL
ERROR_LOG_FILE_FULL  1502L  winerror.h

The event log file is full.


FN_ERROR_LOG_FILE_FULL
ERROR_LOG_FILE_FULL  1502L  winerror.h


ERROR_LOGON_FAILURE
ERROR_LOGON_FAILURE  1326L  winerror.h

The attempted logon is invalid. This is due to either a bad username or authentication information.


FN_ERROR_LOGON_FAILURE
ERROR_LOGON_FAILURE  1326L  winerror.h


ERROR_LOGON_NOT_GRANTED
ERROR_LOGON_NOT_GRANTED  1380L  winerror.h

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.


FN_ERROR_LOGON_NOT_GRANTED
ERROR_LOGON_NOT_GRANTED  1380L  winerror.h


ERROR_LOGON_SESSION_COLLISION
ERROR_LOGON_SESSION_COLLISION  1366L  winerror.h

The logon session ID is already in use.


FN_ERROR_LOGON_SESSION_COLLISION
ERROR_LOGON_SESSION_COLLISION  1366L  winerror.h


ERROR_LOGON_SESSION_EXISTS
ERROR_LOGON_SESSION_EXISTS  1363L  winerror.h

An attempt was made to start a new session manager or LSA logon session with an ID already in use.


FN_ERROR_LOGON_SESSION_EXISTS
ERROR_LOGON_SESSION_EXISTS  1363L  winerror.h


ERROR_LOGON_TYPE_NOT_GRANTED
ERROR_LOGON_TYPE_NOT_GRANTED  1385L  winerror.h

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.


FN_ERROR_LOGON_TYPE_NOT_GRANTED
ERROR_LOGON_TYPE_NOT_GRANTED  1385L  winerror.h


ERROR_LUIDS_EXHAUSTED
ERROR_LUIDS_EXHAUSTED  1334L  winerror.h

Indicates there are no more LUID to allocate.


FN_ERROR_LUIDS_EXHAUSTED
ERROR_LUIDS_EXHAUSTED  1334L  winerror.h


ERROR_MAX_THRDS_REACHED
ERROR_MAX_THRDS_REACHED  164L  winerror.h

No more threads can be created in the system.


FN_ERROR_MAX_THRDS_REACHED
ERROR_MAX_THRDS_REACHED  164L  winerror.h


ERROR_MEDIA_CHANGED
ERROR_MEDIA_CHANGED  1110L  winerror.h

Media in drive may have changed.


FN_ERROR_MEDIA_CHANGED
ERROR_MEDIA_CHANGED  1110L  winerror.h


ERROR_MEMBER_IN_ALIAS
ERROR_MEMBER_IN_ALIAS  1378L  winerror.h

The specified account name is not a member of the alias.


FN_ERROR_MEMBER_IN_ALIAS
ERROR_MEMBER_IN_ALIAS  1378L  winerror.h


ERROR_MEMBER_IN_GROUP
ERROR_MEMBER_IN_GROUP  1320L  winerror.h

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.


FN_ERROR_MEMBER_IN_GROUP
ERROR_MEMBER_IN_GROUP  1320L  winerror.h


ERROR_MEMBER_NOT_IN_ALIAS
ERROR_MEMBER_NOT_IN_ALIAS  1377L  winerror.h

The specified account name is not a member of the alias.


FN_ERROR_MEMBER_NOT_IN_ALIAS
ERROR_MEMBER_NOT_IN_ALIAS  1377L  winerror.h


ERROR_MEMBER_NOT_IN_GROUP
ERROR_MEMBER_NOT_IN_GROUP  1321L  winerror.h

The specified user account is not a member of the specified group account.


FN_ERROR_MEMBER_NOT_IN_GROUP
ERROR_MEMBER_NOT_IN_GROUP  1321L  winerror.h


ERROR_MEMBERS_PRIMARY_GROUP
ERROR_MEMBERS_PRIMARY_GROUP  1374L  winerror.h

Indicates a member cannot be removed from a group because the group is currently the member's primary group.


FN_ERROR_MEMBERS_PRIMARY_GROUP
ERROR_MEMBERS_PRIMARY_GROUP  1374L  winerror.h


ERROR_META_EXPANSION_TOO_LONG
ERROR_META_EXPANSION_TOO_LONG  208L  winerror.h

The global filename characters * or ? are entered incorrectly, or too many global filename characters are specified.


FN_ERROR_META_EXPANSION_TOO_LONG
ERROR_META_EXPANSION_TOO_LONG  208L  winerror.h


ERROR_MOD_NOT_FOUND
ERROR_MOD_NOT_FOUND  126L  winerror.h

The specified module cannot be found.


FN_ERROR_MOD_NOT_FOUND
ERROR_MOD_NOT_FOUND  126L  winerror.h


ERROR_MORE_DATA
ERROR_MORE_DATA  234L  winerror.h

More data is available.


FN_ERROR_MORE_DATA
ERROR_MORE_DATA  234L  winerror.h


ERROR_MORE_WRITES
ERROR_MORE_WRITES  1120L  winerror.h

A serial I/O operation was completed by another write to the serial port. (The IOCTL_SERIAL_XOFF_COUNTER reached zero.)


FN_ERROR_MORE_WRITES
ERROR_MORE_WRITES  1120L  winerror.h


ERROR_MR_MID_NOT_FOUND
ERROR_MR_MID_NOT_FOUND  317L  winerror.h

The system cannot find message for message number 0x%1 in message file for %2.


FN_ERROR_MR_MID_NOT_FOUND
ERROR_MR_MID_NOT_FOUND  317L  winerror.h


ERROR_NEGATIVE_SEEK
ERROR_NEGATIVE_SEEK  131L  winerror.h

An attempt was made to move the file pointer before the beginning of the file.


FN_ERROR_NEGATIVE_SEEK
ERROR_NEGATIVE_SEEK  131L  winerror.h


ERROR_NESTING_NOT_ALLOWED
ERROR_NESTING_NOT_ALLOWED  215L  winerror.h

Can't nest calls to LoadModule.


FN_ERROR_NESTING_NOT_ALLOWED
ERROR_NESTING_NOT_ALLOWED  215L  winerror.h


ERROR_NETLOGON_NOT_STARTED
ERROR_NETLOGON_NOT_STARTED  1792L  winerror.h

An attempt was made to logon, but the network logon service was not started.


FN_ERROR_NETLOGON_NOT_STARTED
ERROR_NETLOGON_NOT_STARTED  1792L  winerror.h


ERROR_NET_WRITE_FAULT
ERROR_NET_WRITE_FAULT  88L  winerror.h

A write fault occurred on the network.


FN_ERROR_NET_WRITE_FAULT
ERROR_NET_WRITE_FAULT  88L  winerror.h


ERROR_NETNAME_DELETED
ERROR_NETNAME_DELETED  64L  winerror.h

The specified network name is no longer available.


FN_ERROR_NETNAME_DELETED
ERROR_NETNAME_DELETED  64L  winerror.h


ERROR_NETWORK_ACCESS_DENIED
ERROR_NETWORK_ACCESS_DENIED  65L  winerror.h

Network access is denied.


FN_ERROR_NETWORK_ACCESS_DENIED
ERROR_NETWORK_ACCESS_DENIED  65L  winerror.h


ERROR_NETWORK_BUSY
ERROR_NETWORK_BUSY  54L  winerror.h

The network is busy.


FN_ERROR_NETWORK_BUSY
ERROR_NETWORK_BUSY  54L  winerror.h


ERROR_NO_BROWSER_SERVERS_FOUND
ERROR_NO_BROWSER_SERVERS_FOUND  6118L  winerror.h

The list of servers for this workgroup is not currently available


FN_ERROR_NO_BROWSER_SERVERS_FOUND
ERROR_NO_BROWSER_SERVERS_FOUND  6118L  winerror.h


ERROR_NO_DATA
ERROR_NO_DATA  232L  winerror.h

Pipe close in progress.


FN_ERROR_NO_DATA
ERROR_NO_DATA  232L  winerror.h


ERROR_NO_DATA_DETECTED
ERROR_NO_DATA_DETECTED  1104L  winerror.h

During a tape access, the end of the data marker was reached.


FN_ERROR_NO_DATA_DETECTED
ERROR_NO_DATA_DETECTED  1104L  winerror.h


ERROR_NO_IMPERSONATION_TOKEN
ERROR_NO_IMPERSONATION_TOKEN  1309L  winerror.h

An attempt was made to operate on an impersonation token by a thread was not currently impersonating a client.


FN_ERROR_NO_IMPERSONATION_TOKEN
ERROR_NO_IMPERSONATION_TOKEN  1309L  winerror.h


ERROR_NO_INHERITANCE
ERROR_NO_INHERITANCE  1391L  winerror.h

Indicates an ACL contains no inheritable components.


FN_ERROR_NO_INHERITANCE
ERROR_NO_INHERITANCE  1391L  winerror.h


ERROR_NO_LOG_SPACE
ERROR_NO_LOG_SPACE  1019L  winerror.h

System could not allocate required space in a registry log.


FN_ERROR_NO_LOG_SPACE
ERROR_NO_LOG_SPACE  1019L  winerror.h


ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT
ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT  1807L  winerror.h

The account used is an interdomain trust account. Use your normal user account or remote user account to access this server.


FN_ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT
ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT  1807L  winerror.h


ERROR_NOLOGON_SERVER_TRUST_ACCOUNT
ERROR_NOLOGON_SERVER_TRUST_ACCOUNT  1809L  winerror.h

The account used is an server trust account. Use your normal user account or remote user account to access this server.


FN_ERROR_NOLOGON_SERVER_TRUST_ACCOUNT
ERROR_NOLOGON_SERVER_TRUST_ACCOUNT  1809L  winerror.h


ERROR_NO_LOGON_SERVERS
ERROR_NO_LOGON_SERVERS  1311L  winerror.h

There are currently no logon servers available to service the logon request.


FN_ERROR_NO_LOGON_SERVERS
ERROR_NO_LOGON_SERVERS  1311L  winerror.h


ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT
ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT  1808L  winerror.h

The account used is a workstation trust account. Use your normal user account or remote user account to access this server.


FN_ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT
ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT  1808L  winerror.h


ERROR_NO_MEDIA_IN_DRIVE
ERROR_NO_MEDIA_IN_DRIVE  1112L  winerror.h

Tape query failed because of no media in drive.


FN_ERROR_NO_MEDIA_IN_DRIVE
ERROR_NO_MEDIA_IN_DRIVE  1112L  winerror.h


ERROR_NO_MORE_FILES
ERROR_NO_MORE_FILES  18L  winerror.h

There are no more files.


FN_ERROR_NO_MORE_FILES
ERROR_NO_MORE_FILES  18L  winerror.h


ERROR_NO_MORE_ITEMS
ERROR_NO_MORE_ITEMS  259L  winerror.h

No more data is available.


FN_ERROR_NO_MORE_ITEMS
ERROR_NO_MORE_ITEMS  259L  winerror.h


ERROR_NO_MORE_SEARCH_HANDLES
ERROR_NO_MORE_SEARCH_HANDLES  113L  winerror.h

No more internal file identifiers available.


FN_ERROR_NO_MORE_SEARCH_HANDLES
ERROR_NO_MORE_SEARCH_HANDLES  113L  winerror.h


ERROR_NO_NET_OR_BAD_PATH
ERROR_NO_NET_OR_BAD_PATH  1203L  winerror.h

No network provider accepted the given network path.


FN_ERROR_NO_NET_OR_BAD_PATH
ERROR_NO_NET_OR_BAD_PATH  1203L  winerror.h


ERROR_NO_NETWORK
ERROR_NO_NETWORK  1222L  winerror.h

The network is not present or not started.


FN_ERROR_NO_NETWORK
ERROR_NO_NETWORK  1222L  winerror.h


ERROR_NO_PROC_SLOTS
ERROR_NO_PROC_SLOTS  89L  winerror.h

The system cannot start another process at this time.


FN_ERROR_NO_PROC_SLOTS
ERROR_NO_PROC_SLOTS  89L  winerror.h


ERROR_NO_QUOTAS_FOR_ACCOUNT
ERROR_NO_QUOTAS_FOR_ACCOUNT  1302L  winerror.h

No system quota limits are specifically set for this account.


FN_ERROR_NO_QUOTAS_FOR_ACCOUNT
ERROR_NO_QUOTAS_FOR_ACCOUNT  1302L  winerror.h


ERROR_NO_SCROLLBARS
ERROR_NO_SCROLLBARS  1447L  winerror.h

Window does not have scroll bars.


FN_ERROR_NO_SCROLLBARS
ERROR_NO_SCROLLBARS  1447L  winerror.h


ERROR_NO_SECURITY_ON_OBJECT
ERROR_NO_SECURITY_ON_OBJECT  1350L  winerror.h

Indicates an attempt was made to operate on the security of an object that does not have security associated with it.


FN_ERROR_NO_SECURITY_ON_OBJECT
ERROR_NO_SECURITY_ON_OBJECT  1350L  winerror.h


ERROR_NO_SHUTDOWN_IN_PROGRESS
ERROR_NO_SHUTDOWN_IN_PROGRESS  1116L  winerror.h

An attempt to abort the shutdown of the system failed because no shutdown was in progress.


FN_ERROR_NO_SHUTDOWN_IN_PROGRESS
ERROR_NO_SHUTDOWN_IN_PROGRESS  1116L  winerror.h


ERROR_NO_SIGNAL_SENT
ERROR_NO_SIGNAL_SENT  205L  winerror.h

No process in the command subtree has a signal handler.


FN_ERROR_NO_SIGNAL_SENT
ERROR_NO_SIGNAL_SENT  205L  winerror.h


ERROR_NO_SPOOL_SPACE
ERROR_NO_SPOOL_SPACE  62L  winerror.h

Space to store the file waiting to be printed is not available on the server.


FN_ERROR_NO_SPOOL_SPACE
ERROR_NO_SPOOL_SPACE  62L  winerror.h


ERROR_NO_SUCH_ALIAS
ERROR_NO_SUCH_ALIAS  1376L  winerror.h

The specified alias does not exist.


FN_ERROR_NO_SUCH_ALIAS
ERROR_NO_SUCH_ALIAS  1376L  winerror.h


ERROR_NO_SUCH_DOMAIN
ERROR_NO_SUCH_DOMAIN  1355L  winerror.h

The specified domain does not exist.


FN_ERROR_NO_SUCH_DOMAIN
ERROR_NO_SUCH_DOMAIN  1355L  winerror.h


ERROR_NO_SUCH_GROUP
ERROR_NO_SUCH_GROUP  1319L  winerror.h

The specified group does not exist.


FN_ERROR_NO_SUCH_GROUP
ERROR_NO_SUCH_GROUP  1319L  winerror.h


ERROR_NO_SUCH_LOGON_SESSION
ERROR_NO_SUCH_LOGON_SESSION  1312L  winerror.h

A specified logon session does not exist. It may already have been terminated.


FN_ERROR_NO_SUCH_LOGON_SESSION
ERROR_NO_SUCH_LOGON_SESSION  1312L  winerror.h


ERROR_NO_SUCH_MEMBER
ERROR_NO_SUCH_MEMBER  1387L  winerror.h

A new member cannot be added to an alias because the member does not exist.


FN_ERROR_NO_SUCH_MEMBER
ERROR_NO_SUCH_MEMBER  1387L  winerror.h


ERROR_NO_SUCH_PACKAGE
ERROR_NO_SUCH_PACKAGE  1364L  winerror.h

A specified authentication package is unknown.


FN_ERROR_NO_SUCH_PACKAGE
ERROR_NO_SUCH_PACKAGE  1364L  winerror.h


ERROR_NO_SUCH_PRIVILEGE
ERROR_NO_SUCH_PRIVILEGE  1313L  winerror.h

A specified privilege does not exist.


FN_ERROR_NO_SUCH_PRIVILEGE
ERROR_NO_SUCH_PRIVILEGE  1313L  winerror.h


ERROR_NO_SUCH_USER
ERROR_NO_SUCH_USER  1317L  winerror.h

The specified user does not exist.


FN_ERROR_NO_SUCH_USER
ERROR_NO_SUCH_USER  1317L  winerror.h


ERROR_NO_SYSTEM_MENU
ERROR_NO_SYSTEM_MENU  1437L  winerror.h

Window does not have system menu.


FN_ERROR_NO_SYSTEM_MENU
ERROR_NO_SYSTEM_MENU  1437L  winerror.h


ERROR_NO_TOKEN
ERROR_NO_TOKEN  1008L  winerror.h

An attempt was made to reference a token that does not exist.


FN_ERROR_NO_TOKEN
ERROR_NO_TOKEN  1008L  winerror.h


ERROR_NO_TRUST_LSA_SECRET
ERROR_NO_TRUST_LSA_SECRET  1786L  winerror.h

The workstation does not have a trust secret.


FN_ERROR_NO_TRUST_LSA_SECRET
ERROR_NO_TRUST_LSA_SECRET  1786L  winerror.h


ERROR_NO_TRUST_SAM_ACCOUNT
ERROR_NO_TRUST_SAM_ACCOUNT  1787L  winerror.h

The domain controller does not have an account for this workstation.


FN_ERROR_NO_TRUST_SAM_ACCOUNT
ERROR_NO_TRUST_SAM_ACCOUNT  1787L  winerror.h


ERROR_NO_UNICODE_TRANSLATION
ERROR_NO_UNICODE_TRANSLATION  1113L  winerror.h

No mapping for the Unicode character exists in the target multi-byte code page.


FN_ERROR_NO_UNICODE_TRANSLATION
ERROR_NO_UNICODE_TRANSLATION  1113L  winerror.h


ERROR_NO_USER_SESSION_KEY
ERROR_NO_USER_SESSION_KEY  1394L  winerror.h

There is no user session key for the specified logon session.


FN_ERROR_NO_USER_SESSION_KEY
ERROR_NO_USER_SESSION_KEY  1394L  winerror.h


ERROR_NO_VOLUME_LABEL
ERROR_NO_VOLUME_LABEL  125L  winerror.h

The disk has no volume label.


FN_ERROR_NO_VOLUME_LABEL
ERROR_NO_VOLUME_LABEL  125L  winerror.h


ERROR_NO_WILDCARD_CHARACTERS
ERROR_NO_WILDCARD_CHARACTERS  1417L  winerror.h

No wildcard characters found.


FN_ERROR_NO_WILDCARD_CHARACTERS
ERROR_NO_WILDCARD_CHARACTERS  1417L  winerror.h


ERROR_NOACCESS
ERROR_NOACCESS  998L  winerror.h

Invalid access to memory location.


FN_ERROR_NOACCESS
ERROR_NOACCESS  998L  winerror.h


ERROR_NON_MDICHILD_WINDOW
ERROR_NON_MDICHILD_WINDOW  1445L  winerror.h

DefMDIChildProc called with a non-MDI child window.


FN_ERROR_NON_MDICHILD_WINDOW
ERROR_NON_MDICHILD_WINDOW  1445L  winerror.h


ERROR_NONE_MAPPED
ERROR_NONE_MAPPED  1332L  winerror.h

None of the information to be mapped has been translated.


FN_ERROR_NONE_MAPPED
ERROR_NONE_MAPPED  1332L  winerror.h


ERROR_NOT_ALL_ASSIGNED
ERROR_NOT_ALL_ASSIGNED  1300L  winerror.h

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.


FN_ERROR_NOT_ALL_ASSIGNED
ERROR_NOT_ALL_ASSIGNED  1300L  winerror.h


ERROR_NOT_CHILD_WINDOW
ERROR_NOT_CHILD_WINDOW  1442L  winerror.h

Window is not a child window.


FN_ERROR_NOT_CHILD_WINDOW
ERROR_NOT_CHILD_WINDOW  1442L  winerror.h


ERROR_NOT_CONNECTED
ERROR_NOT_CONNECTED  2250L  winerror.h

This network connection does not exist.


FN_ERROR_NOT_CONNECTED
ERROR_NOT_CONNECTED  2250L  winerror.h


ERROR_NOT_CONTAINER
ERROR_NOT_CONTAINER  1207L  winerror.h

Cannot enumerate a non-container.


FN_ERROR_NOT_CONTAINER
ERROR_NOT_CONTAINER  1207L  winerror.h


ERROR_NOT_DOS_DISK
ERROR_NOT_DOS_DISK  26L  winerror.h

The specified disk cannot be accessed.


FN_ERROR_NOT_DOS_DISK
ERROR_NOT_DOS_DISK  26L  winerror.h


ERROR_NOT_ENOUGH_MEMORY
ERROR_NOT_ENOUGH_MEMORY  8L  winerror.h

Not enough storage is available to process this command.


FN_ERROR_NOT_ENOUGH_MEMORY
ERROR_NOT_ENOUGH_MEMORY  8L  winerror.h


ERROR_NOT_ENOUGH_SERVER_MEMORY
ERROR_NOT_ENOUGH_SERVER_MEMORY  1130L  winerror.h

Not enough server storage is available to process this command.


FN_ERROR_NOT_ENOUGH_SERVER_MEMORY
ERROR_NOT_ENOUGH_SERVER_MEMORY  1130L  winerror.h


ERROR_NOT_JOINED
ERROR_NOT_JOINED  136L  winerror.h

The system attempted to delete the JOIN of a drive not previously joined.


FN_ERROR_NOT_JOINED
ERROR_NOT_JOINED  136L  winerror.h


ERROR_NOT_LOCKED
ERROR_NOT_LOCKED  158L  winerror.h

The segment is already unlocked.


FN_ERROR_NOT_LOCKED
ERROR_NOT_LOCKED  158L  winerror.h


ERROR_NOT_LOGON_PROCESS
ERROR_NOT_LOGON_PROCESS  1362L  winerror.h

The requested action is restricted for use by logon processes only. The calling process has not registered as a logon process.


FN_ERROR_NOT_LOGON_PROCESS
ERROR_NOT_LOGON_PROCESS  1362L  winerror.h


ERROR_NOT_OWNER
ERROR_NOT_OWNER  288L  winerror.h

Attempt to release mutex not owned by caller.


FN_ERROR_NOT_OWNER
ERROR_NOT_OWNER  288L  winerror.h


ERROR_NOT_READY
ERROR_NOT_READY  21L  winerror.h

The drive is not ready.


FN_ERROR_NOT_READY
ERROR_NOT_READY  21L  winerror.h


ERROR_NOT_REGISTRY_FILE
ERROR_NOT_REGISTRY_FILE  1017L  winerror.h

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.


FN_ERROR_NOT_REGISTRY_FILE
ERROR_NOT_REGISTRY_FILE  1017L  winerror.h


ERROR_NOT_SAME_DEVICE
ERROR_NOT_SAME_DEVICE  17L  winerror.h

The system cannot move the file to a different disk drive.


FN_ERROR_NOT_SAME_DEVICE
ERROR_NOT_SAME_DEVICE  17L  winerror.h


ERROR_NOT_SUBSTED
ERROR_NOT_SUBSTED  137L  winerror.h

The system attempted to delete the substitution of a drive not previously substituted.


FN_ERROR_NOT_SUBSTED
ERROR_NOT_SUBSTED  137L  winerror.h


ERROR_NOT_SUPPORTED
ERROR_NOT_SUPPORTED  50L  winerror.h

The network request is not supported.


FN_ERROR_NOT_SUPPORTED
ERROR_NOT_SUPPORTED  50L  winerror.h


ERROR_NOTIFY_ENUM_DIR
ERROR_NOTIFY_ENUM_DIR  1022L  winerror.h

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.


FN_ERROR_NOTIFY_ENUM_DIR
ERROR_NOTIFY_ENUM_DIR  1022L  winerror.h


ERROR_NT_CROSS_ENCRYPTION_REQUIRED
ERROR_NT_CROSS_ENCRYPTION_REQUIRED  1386L  winerror.h

An attempt was made to change a user password in the security account manager without providing the necessary NT cross-encrypted password.


FN_ERROR_NT_CROSS_ENCRYPTION_REQUIRED
ERROR_NT_CROSS_ENCRYPTION_REQUIRED  1386L  winerror.h


ERROR_NULL_LM_PASSWORD
ERROR_NULL_LM_PASSWORD  1304L  winerror.h

The Windows NT password is too complex to be converted to a Windows-networking password. The Windows-networking password returned is a NULL string.


FN_ERROR_NULL_LM_PASSWORD
ERROR_NULL_LM_PASSWORD  1304L  winerror.h


ERROR_OPEN_FAILED
ERROR_OPEN_FAILED  110L  winerror.h

The system cannot open the specified device or file.


FN_ERROR_OPEN_FAILED
ERROR_OPEN_FAILED  110L  winerror.h


ERROR_OPEN_FILES
ERROR_OPEN_FILES  2401L  winerror.h

There are open files or requests pending on this connection.


FN_ERROR_OPEN_FILES
ERROR_OPEN_FILES  2401L  winerror.h


ERROR_OPERATION_ABORTED
ERROR_OPERATION_ABORTED  995L  winerror.h

The I/O operation was aborted due to either thread exit or application request.


FN_ERROR_OPERATION_ABORTED
ERROR_OPERATION_ABORTED  995L  winerror.h


ERROR_OUT_OF_PAPER
ERROR_OUT_OF_PAPER  28L  winerror.h

The printer is out of paper.


FN_ERROR_OUT_OF_PAPER
ERROR_OUT_OF_PAPER  28L  winerror.h


ERROR_OUT_OF_STRUCTURES
ERROR_OUT_OF_STRUCTURES  84L  winerror.h

Storage to process this request is not available.


FN_ERROR_OUT_OF_STRUCTURES
ERROR_OUT_OF_STRUCTURES  84L  winerror.h


ERROR_OUTOFMEMORY
ERROR_OUTOFMEMORY  14L  winerror.h

Not enough storage is available to complete this operation.


FN_ERROR_OUTOFMEMORY
ERROR_OUTOFMEMORY  14L  winerror.h


ERROR_PARTITION_FAILURE
ERROR_PARTITION_FAILURE  1105L  winerror.h

Tape could not be partitioned.


FN_ERROR_PARTITION_FAILURE
ERROR_PARTITION_FAILURE  1105L  winerror.h


ERROR_PASSWORD_EXPIRED
ERROR_PASSWORD_EXPIRED  1330L  winerror.h

The user account's password has expired.


FN_ERROR_PASSWORD_EXPIRED
ERROR_PASSWORD_EXPIRED  1330L  winerror.h


ERROR_PASSWORD_RESTRICTION
ERROR_PASSWORD_RESTRICTION  1325L  winerror.h

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.


FN_ERROR_PASSWORD_RESTRICTION
ERROR_PASSWORD_RESTRICTION  1325L  winerror.h


ERROR_PATH_BUSY
ERROR_PATH_BUSY  148L  winerror.h

The specified path cannot be used at this time.


FN_ERROR_PATH_BUSY
ERROR_PATH_BUSY  148L  winerror.h


ERROR_PATH_NOT_FOUND
ERROR_PATH_NOT_FOUND  3L  winerror.h

The system cannot find the specified path.


FN_ERROR_PATH_NOT_FOUND
ERROR_PATH_NOT_FOUND  3L  winerror.h


ERROR_PIPE_BUSY
ERROR_PIPE_BUSY  231L  winerror.h

All pipe instances busy.


FN_ERROR_PIPE_BUSY
ERROR_PIPE_BUSY  231L  winerror.h


ERROR_PIPE_CONNECTED
ERROR_PIPE_CONNECTED  535L  winerror.h

There is a process on other end of the pipe.


FN_ERROR_PIPE_CONNECTED
ERROR_PIPE_CONNECTED  535L  winerror.h


ERROR_PIPE_LISTENING
ERROR_PIPE_LISTENING  536L  winerror.h

Waiting for a process to open the other end of the pipe.


FN_ERROR_PIPE_LISTENING
ERROR_PIPE_LISTENING  536L  winerror.h


ERROR_PIPE_NOT_CONNECTED
ERROR_PIPE_NOT_CONNECTED  233L  winerror.h

No process on other end of pipe.


FN_ERROR_PIPE_NOT_CONNECTED
ERROR_PIPE_NOT_CONNECTED  233L  winerror.h


ERROR_POPUP_ALREADY_ACTIVE
ERROR_POPUP_ALREADY_ACTIVE  1446L  winerror.h

Pop-up menu already active.


FN_ERROR_POPUP_ALREADY_ACTIVE
ERROR_POPUP_ALREADY_ACTIVE  1446L  winerror.h


ERROR_POSSIBLE_DEADLOCK
ERROR_POSSIBLE_DEADLOCK  1131L  winerror.h

A potential deadlock condition has been detected.


FN_ERROR_POSSIBLE_DEADLOCK
ERROR_POSSIBLE_DEADLOCK  1131L  winerror.h


ERROR_PRINT_CANCELLED
ERROR_PRINT_CANCELLED  63L  winerror.h

File waiting to be printed was deleted.


FN_ERROR_PRINT_CANCELLED
ERROR_PRINT_CANCELLED  63L  winerror.h


ERROR_PRINTER_ALREADY_EXISTS
ERROR_PRINTER_ALREADY_EXISTS  1802L  winerror.h

The printer already exists.


FN_ERROR_PRINTER_ALREADY_EXISTS
ERROR_PRINTER_ALREADY_EXISTS  1802L  winerror.h


ERROR_PRINTER_DRIVER_ALREADY_INSTALLED
ERROR_PRINTER_DRIVER_ALREADY_INSTALLED  1795L  winerror.h

The specified printer driver is already installed.


FN_ERROR_PRINTER_DRIVER_ALREADY_INSTALLED
ERROR_PRINTER_DRIVER_ALREADY_INSTALLED  1795L  winerror.h


ERROR_PRINTQ_FULL
ERROR_PRINTQ_FULL  61L  winerror.h

The printer queue is full.


FN_ERROR_PRINTQ_FULL
ERROR_PRINTQ_FULL  61L  winerror.h


ERROR_PRIVATE_DIALOG_INDEX
ERROR_PRIVATE_DIALOG_INDEX  1415L  winerror.h

Using private DIALOG window words.


FN_ERROR_PRIVATE_DIALOG_INDEX
ERROR_PRIVATE_DIALOG_INDEX  1415L  winerror.h


ERROR_PRIVILEGE_NOT_HELD
ERROR_PRIVILEGE_NOT_HELD  1314L  winerror.h

A required privilege is not held by the client.


FN_ERROR_PRIVILEGE_NOT_HELD
ERROR_PRIVILEGE_NOT_HELD  1314L  winerror.h


ERROR_PROC_NOT_FOUND
ERROR_PROC_NOT_FOUND  127L  winerror.h

The specified procedure could not be found.


FN_ERROR_PROC_NOT_FOUND
ERROR_PROC_NOT_FOUND  127L  winerror.h


ERROR_PROCESS_ABORTED
ERROR_PROCESS_ABORTED  1067L  winerror.h

The process terminated unexpectedly.


FN_ERROR_PROCESS_ABORTED
ERROR_PROCESS_ABORTED  1067L  winerror.h


ERROR_READ_FAULT
ERROR_READ_FAULT  30L  winerror.h

The system cannot read from the specified device.


FN_ERROR_READ_FAULT
ERROR_READ_FAULT  30L  winerror.h


ERROR_REDIR_PAUSED
ERROR_REDIR_PAUSED  72L  winerror.h

The specified printer or disk device has been paused.


FN_ERROR_REDIR_PAUSED
ERROR_REDIR_PAUSED  72L  winerror.h


ERROR_REDIRECTOR_HAS_OPEN_HANDLES
ERROR_REDIRECTOR_HAS_OPEN_HANDLES  1794L  winerror.h

The redirector is in use and cannot be unloaded.


FN_ERROR_REDIRECTOR_HAS_OPEN_HANDLES
ERROR_REDIRECTOR_HAS_OPEN_HANDLES  1794L  winerror.h


ERROR_REGISTRY_CORRUPT
ERROR_REGISTRY_CORRUPT  1015L  winerror.h

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.


FN_ERROR_REGISTRY_CORRUPT
ERROR_REGISTRY_CORRUPT  1015L  winerror.h


ERROR_REGISTRY_IO_FAILED
ERROR_REGISTRY_IO_FAILED  1016L  winerror.h

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.


FN_ERROR_REGISTRY_IO_FAILED
ERROR_REGISTRY_IO_FAILED  1016L  winerror.h


ERROR_REGISTRY_RECOVERED
ERROR_REGISTRY_RECOVERED  1014L  winerror.h

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.


FN_ERROR_REGISTRY_RECOVERED
ERROR_REGISTRY_RECOVERED  1014L  winerror.h


ERROR_RELOC_CHAIN_XEEDS_SEGLIM
ERROR_RELOC_CHAIN_XEEDS_SEGLIM  201L  winerror.h

The operating system cannot run %1.


FN_ERROR_RELOC_CHAIN_XEEDS_SEGLIM
ERROR_RELOC_CHAIN_XEEDS_SEGLIM  201L  winerror.h


ERROR_REM_NOT_LIST
ERROR_REM_NOT_LIST  51L  winerror.h

The remote computer is not available.


FN_ERROR_REM_NOT_LIST
ERROR_REM_NOT_LIST  51L  winerror.h


ERROR_REMOTE_SESSION_LIMIT_EXCEEDED
ERROR_REMOTE_SESSION_LIMIT_EXCEEDED  1220L  winerror.h

An attempt was made to establish a session to a Lan Manager server, but there are already too many sessions established to that server.


FN_ERROR_REMOTE_SESSION_LIMIT_EXCEEDED
ERROR_REMOTE_SESSION_LIMIT_EXCEEDED  1220L  winerror.h


ERROR_REQ_NOT_ACCEP
ERROR_REQ_NOT_ACCEP  71L  winerror.h

The network request was not accepted.


FN_ERROR_REQ_NOT_ACCEP
ERROR_REQ_NOT_ACCEP  71L  winerror.h


ERROR_NOT_ENOUGH_QUOTA
ERROR_NOT_ENOUGH_QUOTA  1816L  winerror.h

Not enough quota is available to process this command.


FN_ERROR_NOT_ENOUGH_QUOTA
ERROR_NOT_ENOUGH_QUOTA  1816L  winerror.h


ERROR_RESOURCE_DATA_NOT_FOUND
ERROR_RESOURCE_DATA_NOT_FOUND  1812L  winerror.h

The specified image file did not contain a resource section.


FN_ERROR_RESOURCE_DATA_NOT_FOUND
ERROR_RESOURCE_DATA_NOT_FOUND  1812L  winerror.h


ERROR_RESOURCE_LANG_NOT_FOUND
ERROR_RESOURCE_LANG_NOT_FOUND  1815L  winerror.h

The specified resource language ID cannot be found in the image file.


FN_ERROR_RESOURCE_LANG_NOT_FOUND
ERROR_RESOURCE_LANG_NOT_FOUND  1815L  winerror.h


ERROR_RESOURCE_NAME_NOT_FOUND
ERROR_RESOURCE_NAME_NOT_FOUND  1814L  winerror.h

The specified resource name can not be found in the image file.


FN_ERROR_RESOURCE_NAME_NOT_FOUND
ERROR_RESOURCE_NAME_NOT_FOUND  1814L  winerror.h


ERROR_RESOURCE_TYPE_NOT_FOUND
ERROR_RESOURCE_TYPE_NOT_FOUND  1813L  winerror.h

The specified resource type can not be found in the image file.


FN_ERROR_RESOURCE_TYPE_NOT_FOUND
ERROR_RESOURCE_TYPE_NOT_FOUND  1813L  winerror.h


ERROR_REVISION_MISMATCH
ERROR_REVISION_MISMATCH  1306L  winerror.h

Indicates two revision levels are incompatible.


FN_ERROR_REVISION_MISMATCH
ERROR_REVISION_MISMATCH  1306L  winerror.h


ERROR_RING2_STACK_IN_USE
ERROR_RING2_STACK_IN_USE  207L  winerror.h

The ring 2 stack is in use.


FN_ERROR_RING2_STACK_IN_USE
ERROR_RING2_STACK_IN_USE  207L  winerror.h


ERROR_RING2SEG_MUST_BE_MOVABLE
ERROR_RING2SEG_MUST_BE_MOVABLE  200L  winerror.h

The code segment cannot be greater than or equal to 64KB.


FN_ERROR_RING2SEG_MUST_BE_MOVABLE
ERROR_RING2SEG_MUST_BE_MOVABLE  200L  winerror.h


ERROR_RXACT_COMMIT_FAILURE
ERROR_RXACT_COMMIT_FAILURE  1370L  winerror.h

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


FN_ERROR_RXACT_COMMIT_FAILURE
ERROR_RXACT_COMMIT_FAILURE  1370L  winerror.h


ERROR_RXACT_INVALID_STATE
ERROR_RXACT_INVALID_STATE  1369L  winerror.h

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


FN_ERROR_RXACT_INVALID_STATE
ERROR_RXACT_INVALID_STATE  1369L  winerror.h


ERROR_SAME_DRIVE
ERROR_SAME_DRIVE  143L  winerror.h

The system cannot join or substitute a drive to or for a directory on the same drive.


FN_ERROR_SAME_DRIVE
ERROR_SAME_DRIVE  143L  winerror.h


ERROR_SCREEN_ALREADY_LOCKED
ERROR_SCREEN_ALREADY_LOCKED  1440L  winerror.h

Screen already locked.


FN_ERROR_SCREEN_ALREADY_LOCKED
ERROR_SCREEN_ALREADY_LOCKED  1440L  winerror.h


ERROR_SECRET_TOO_LONG
ERROR_SECRET_TOO_LONG  1382L  winerror.h

The length of an secret exceeds the maximum length allowed. The length and number of secrets is limited to satisfy the United States State Department export restrictions.


FN_ERROR_SECRET_TOO_LONG
ERROR_SECRET_TOO_LONG  1382L  winerror.h


ERROR_SECTOR_NOT_FOUND
ERROR_SECTOR_NOT_FOUND  27L  winerror.h

The drive cannot find the requested sector.


FN_ERROR_SECTOR_NOT_FOUND
ERROR_SECTOR_NOT_FOUND  27L  winerror.h


ERROR_SEEK
ERROR_SEEK  25L  winerror.h

The drive cannot locate a specific area or track on the disk.


FN_ERROR_SEEK
ERROR_SEEK  25L  winerror.h


ERROR_SEEK_ON_DEVICE
ERROR_SEEK_ON_DEVICE  132L  winerror.h

The file pointer cannot be set on the specified device or file.


FN_ERROR_SEEK_ON_DEVICE
ERROR_SEEK_ON_DEVICE  132L  winerror.h


ERROR_SEM_IS_SET
ERROR_SEM_IS_SET  102L  winerror.h

The semaphore is set and cannot be closed.


FN_ERROR_SEM_IS_SET
ERROR_SEM_IS_SET  102L  winerror.h


ERROR_SEM_NOT_FOUND
ERROR_SEM_NOT_FOUND  187L  winerror.h

The specified system semaphore name was not found.


FN_ERROR_SEM_NOT_FOUND
ERROR_SEM_NOT_FOUND  187L  winerror.h


ERROR_SEM_OWNER_DIED
ERROR_SEM_OWNER_DIED  105L  winerror.h

The previous ownership of this semaphore has ended.


FN_ERROR_SEM_OWNER_DIED
ERROR_SEM_OWNER_DIED  105L  winerror.h


ERROR_SEM_TIMEOUT
ERROR_SEM_TIMEOUT  121L  winerror.h

The semaphore timeout period has expired.


FN_ERROR_SEM_TIMEOUT
ERROR_SEM_TIMEOUT  121L  winerror.h


ERROR_SEM_USER_LIMIT
ERROR_SEM_USER_LIMIT  106L  winerror.h

Insert the disk for drive 1.


FN_ERROR_SEM_USER_LIMIT
ERROR_SEM_USER_LIMIT  106L  winerror.h


ERROR_SERIAL_NO_DEVICE
ERROR_SERIAL_NO_DEVICE  1118L  winerror.h

No serial device was successfully initialized. The serial driver will unload.


FN_ERROR_SERIAL_NO_DEVICE
ERROR_SERIAL_NO_DEVICE  1118L  winerror.h


ERROR_SERVER_DISABLED
ERROR_SERVER_DISABLED  1341L  winerror.h

The GUID allocation server is already disabled at the moment.


FN_ERROR_SERVER_DISABLED
ERROR_SERVER_DISABLED  1341L  winerror.h


ERROR_SERVER_HAS_OPEN_HANDLES
ERROR_SERVER_HAS_OPEN_HANDLES  1811L  winerror.h

The server is in use and cannot be unloaded.


FN_ERROR_SERVER_HAS_OPEN_HANDLES
ERROR_SERVER_HAS_OPEN_HANDLES  1811L  winerror.h


ERROR_SERVER_NOT_DISABLED
ERROR_SERVER_NOT_DISABLED  1342L  winerror.h

The GUID allocation server is already enabled at the moment.


FN_ERROR_SERVER_NOT_DISABLED
ERROR_SERVER_NOT_DISABLED  1342L  winerror.h


ERROR_SERVICE_ALREADY_RUNNING
ERROR_SERVICE_ALREADY_RUNNING  1056L  winerror.h

An instance of the service is already running.


FN_ERROR_SERVICE_ALREADY_RUNNING
ERROR_SERVICE_ALREADY_RUNNING  1056L  winerror.h


ERROR_SERVICE_CANNOT_ACCEPT_CTRL
ERROR_SERVICE_CANNOT_ACCEPT_CTRL  1061L  winerror.h

The service cannot accept control messages at this time.


FN_ERROR_SERVICE_CANNOT_ACCEPT_CTRL
ERROR_SERVICE_CANNOT_ACCEPT_CTRL  1061L  winerror.h


ERROR_SERVICE_DATABASE_LOCKED
ERROR_SERVICE_DATABASE_LOCKED  1055L  winerror.h

The service database is locked.


FN_ERROR_SERVICE_DATABASE_LOCKED
ERROR_SERVICE_DATABASE_LOCKED  1055L  winerror.h


ERROR_SERVICE_DEPENDENCY_DELETED
ERROR_SERVICE_DEPENDENCY_DELETED  1075L  winerror.h

The dependency service does not exist or has been marked for deletion.


FN_ERROR_SERVICE_DEPENDENCY_DELETED
ERROR_SERVICE_DEPENDENCY_DELETED  1075L  winerror.h


ERROR_SERVICE_DEPENDENCY_FAIL
ERROR_SERVICE_DEPENDENCY_FAIL  1068L  winerror.h

The dependency service or group failed to start.


FN_ERROR_SERVICE_DEPENDENCY_FAIL
ERROR_SERVICE_DEPENDENCY_FAIL  1068L  winerror.h


ERROR_SERVICE_DISABLED
ERROR_SERVICE_DISABLED  1058L  winerror.h

The specified service is disabled and cannot be started.


FN_ERROR_SERVICE_DISABLED
ERROR_SERVICE_DISABLED  1058L  winerror.h


ERROR_SERVICE_DOES_NOT_EXIST
ERROR_SERVICE_DOES_NOT_EXIST  1060L  winerror.h

The specified service does not exist as an installed service.


FN_ERROR_SERVICE_DOES_NOT_EXIST
ERROR_SERVICE_DOES_NOT_EXIST  1060L  winerror.h


ERROR_SERVICE_EXISTS
ERROR_SERVICE_EXISTS  1073L  winerror.h

The specified service already exists.


FN_ERROR_SERVICE_EXISTS
ERROR_SERVICE_EXISTS  1073L  winerror.h


ERROR_SERVICE_LOGON_FAILED
ERROR_SERVICE_LOGON_FAILED  1069L  winerror.h

The service did not start due to a logon failure.


FN_ERROR_SERVICE_LOGON_FAILED
ERROR_SERVICE_LOGON_FAILED  1069L  winerror.h


ERROR_SERVICE_MARKED_FOR_DELETE
ERROR_SERVICE_MARKED_FOR_DELETE  1072L  winerror.h

The specified service has been marked for deletion.


FN_ERROR_SERVICE_MARKED_FOR_DELETE
ERROR_SERVICE_MARKED_FOR_DELETE  1072L  winerror.h


ERROR_SERVICE_NEVER_STARTED
ERROR_SERVICE_NEVER_STARTED  1077L  winerror.h

No attempts to start the service have been made since the last boot.


FN_ERROR_SERVICE_NEVER_STARTED
ERROR_SERVICE_NEVER_STARTED  1077L  winerror.h


ERROR_SERVICE_NO_THREAD
ERROR_SERVICE_NO_THREAD  1054L  winerror.h

A thread could not be created for the service.


FN_ERROR_SERVICE_NO_THREAD
ERROR_SERVICE_NO_THREAD  1054L  winerror.h


ERROR_SERVICE_NOT_ACTIVE
ERROR_SERVICE_NOT_ACTIVE  1062L  winerror.h

The service has not been started.


FN_ERROR_SERVICE_NOT_ACTIVE
ERROR_SERVICE_NOT_ACTIVE  1062L  winerror.h


ERROR_SERVICE_REQUEST_TIMEOUT
ERROR_SERVICE_REQUEST_TIMEOUT  1053L  winerror.h

The service did not respond to the start or control request in a timely fashion.


FN_ERROR_SERVICE_REQUEST_TIMEOUT
ERROR_SERVICE_REQUEST_TIMEOUT  1053L  winerror.h


ERROR_SERVICE_SPECIFIC_ERROR
ERROR_SERVICE_SPECIFIC_ERROR  1066L  winerror.h

The service has returned a service-specific error code.


FN_ERROR_SERVICE_SPECIFIC_ERROR
ERROR_SERVICE_SPECIFIC_ERROR  1066L  winerror.h


ERROR_SERVICE_START_HANG
ERROR_SERVICE_START_HANG  1070L  winerror.h

After starting, the service hung in a start-pending state.


FN_ERROR_SERVICE_START_HANG
ERROR_SERVICE_START_HANG  1070L  winerror.h


ERROR_SESSION_CREDENTIAL_CONFLICT
ERROR_SESSION_CREDENTIAL_CONFLICT  1219L  winerror.h

The credentials supplied conflict with an existing set of credentials.


FN_ERROR_SESSION_CREDENTIAL_CONFLICT
ERROR_SESSION_CREDENTIAL_CONFLICT  1219L  winerror.h


ERROR_SETCOUNT_ON_BAD_LB
ERROR_SETCOUNT_ON_BAD_LB  1433L  winerror.h

LB_SETCOUNT sent to non-lazy list box.


FN_ERROR_SETCOUNT_ON_BAD_LB
ERROR_SETCOUNT_ON_BAD_LB  1433L  winerror.h


ERROR_SETMARK_DETECTED
ERROR_SETMARK_DETECTED  1103L  winerror.h

A tape access reached a setmark.


FN_ERROR_SETMARK_DETECTED
ERROR_SETMARK_DETECTED  1103L  winerror.h


ERROR_SHARING_BUFFER_EXCEEDED
ERROR_SHARING_BUFFER_EXCEEDED  36L  winerror.h

Too many files opened for sharing.


FN_ERROR_SHARING_BUFFER_EXCEEDED
ERROR_SHARING_BUFFER_EXCEEDED  36L  winerror.h


ERROR_SHARING_PAUSED
ERROR_SHARING_PAUSED  70L  winerror.h

The remote server is paused or is in the process of being started.


FN_ERROR_SHARING_PAUSED
ERROR_SHARING_PAUSED  70L  winerror.h


ERROR_SHARING_VIOLATION
ERROR_SHARING_VIOLATION  32L  winerror.h

The process cannot access the file because it is being used by another process.


FN_ERROR_SHARING_VIOLATION
ERROR_SHARING_VIOLATION  32L  winerror.h


ERROR_SHUTDOWN_IN_PROGRESS
ERROR_SHUTDOWN_IN_PROGRESS  1115L  winerror.h

A system shutdown is in progress.


FN_ERROR_SHUTDOWN_IN_PROGRESS
ERROR_SHUTDOWN_IN_PROGRESS  1115L  winerror.h


ERROR_SIGNAL_PENDING
ERROR_SIGNAL_PENDING  162L  winerror.h

A signal is already pending.


FN_ERROR_SIGNAL_PENDING
ERROR_SIGNAL_PENDING  162L  winerror.h


ERROR_SIGNAL_REFUSED
ERROR_SIGNAL_REFUSED  156L  winerror.h

The recipient process has refused the signal.


FN_ERROR_SIGNAL_REFUSED
ERROR_SIGNAL_REFUSED  156L  winerror.h


ERROR_SOME_NOT_MAPPED
ERROR_SOME_NOT_MAPPED  1301L  winerror.h

Some of the information to be mapped has not been translated.


FN_ERROR_SOME_NOT_MAPPED
ERROR_SOME_NOT_MAPPED  1301L  winerror.h


ERROR_SPECIAL_ACCOUNT
ERROR_SPECIAL_ACCOUNT  1371L  winerror.h

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.


FN_ERROR_SPECIAL_ACCOUNT
ERROR_SPECIAL_ACCOUNT  1371L  winerror.h


ERROR_SPECIAL_GROUP
ERROR_SPECIAL_GROUP  1372L  winerror.h

The requested operation cannot be performed on the specified group because it is a built-in special group.


FN_ERROR_SPECIAL_GROUP
ERROR_SPECIAL_GROUP  1372L  winerror.h


ERROR_SPECIAL_USER
ERROR_SPECIAL_USER  1373L  winerror.h

The requested operation cannot be performed on the specified user because it is a built-in special user.


FN_ERROR_SPECIAL_USER
ERROR_SPECIAL_USER  1373L  winerror.h


ERROR_STACK_OVERFLOW
ERROR_STACK_OVERFLOW  1001L  winerror.h

Recursion too deep, stack overflowed.


FN_ERROR_STACK_OVERFLOW
ERROR_STACK_OVERFLOW  1001L  winerror.h


ERROR_SUBST_TO_JOIN
ERROR_SUBST_TO_JOIN  141L  winerror.h

The system attempted to SUBST a drive to a directory on a joined drive.


FN_ERROR_SUBST_TO_JOIN
ERROR_SUBST_TO_JOIN  141L  winerror.h


ERROR_SUBST_TO_SUBST
ERROR_SUBST_TO_SUBST  139L  winerror.h

The system attempted to substitute a drive to a directory on a substituted drive.


FN_ERROR_SUBST_TO_SUBST
ERROR_SUBST_TO_SUBST  139L  winerror.h


ERROR_SUCCESS
ERROR_SUCCESS  0L  winerror.h

The operation was successfully completed.


FN_ERROR_SUCCESS
ERROR_SUCCESS  0L  winerror.h


ERROR_SWAPERROR
ERROR_SWAPERROR  999L  winerror.h

Error accessing paging file.


FN_ERROR_SWAPERROR
ERROR_SWAPERROR  999L  winerror.h


ERROR_SYSTEM_TRACE
ERROR_SYSTEM_TRACE  150L  winerror.h

System trace information not specified in your CONFIG.SYS file, or tracing is not allowed.


FN_ERROR_SYSTEM_TRACE
ERROR_SYSTEM_TRACE  150L  winerror.h


ERROR_THREAD_1_INACTIVE
ERROR_THREAD_1_INACTIVE  210L  winerror.h

The signal handler cannot be set.


FN_ERROR_THREAD_1_INACTIVE
ERROR_THREAD_1_INACTIVE  210L  winerror.h


ERROR_TLW_WITH_WSCHILD
ERROR_TLW_WITH_WSCHILD  1406L  winerror.h

CreateWindow failed, creating top-level window with WS_CHILD style.


FN_ERROR_TLW_WITH_WSCHILD
ERROR_TLW_WITH_WSCHILD  1406L  winerror.h


ERROR_TOKEN_ALREADY_IN_USE
ERROR_TOKEN_ALREADY_IN_USE  1375L  winerror.h

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.


FN_ERROR_TOKEN_ALREADY_IN_USE
ERROR_TOKEN_ALREADY_IN_USE  1375L  winerror.h


ERROR_TOO_MANY_CMDS
ERROR_TOO_MANY_CMDS  56L  winerror.h

The network BIOS command limit has been reached.


FN_ERROR_TOO_MANY_CMDS
ERROR_TOO_MANY_CMDS  56L  winerror.h


ERROR_TOO_MANY_CONTEXT_IDS
ERROR_TOO_MANY_CONTEXT_IDS  1384L  winerror.h

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.


FN_ERROR_TOO_MANY_CONTEXT_IDS
ERROR_TOO_MANY_CONTEXT_IDS  1384L  winerror.h


ERROR_TOO_MANY_LUIDS_REQUESTED
ERROR_TOO_MANY_LUIDS_REQUESTED  1333L  winerror.h

The number of LUID requested cannot be allocated with a single allocation.


FN_ERROR_TOO_MANY_LUIDS_REQUESTED
ERROR_TOO_MANY_LUIDS_REQUESTED  1333L  winerror.h


ERROR_TOO_MANY_MODULES
ERROR_TOO_MANY_MODULES  214L  winerror.h

Too many dynamic link modules are attached to this program or dynamic link module.


FN_ERROR_TOO_MANY_MODULES
ERROR_TOO_MANY_MODULES  214L  winerror.h


ERROR_TOO_MANY_MUXWAITERS
ERROR_TOO_MANY_MUXWAITERS  152L  winerror.h

Too many semaphores are already set.


FN_ERROR_TOO_MANY_MUXWAITERS
ERROR_TOO_MANY_MUXWAITERS  152L  winerror.h


ERROR_TOO_MANY_NAMES
ERROR_TOO_MANY_NAMES  68L  winerror.h

The name limit for the local computer network adapter card exceeded.


FN_ERROR_TOO_MANY_NAMES
ERROR_TOO_MANY_NAMES  68L  winerror.h


ERROR_TOO_MANY_OPEN_FILES
ERROR_TOO_MANY_OPEN_FILES  4L  winerror.h

The system cannot open the file.


FN_ERROR_TOO_MANY_OPEN_FILES
ERROR_TOO_MANY_OPEN_FILES  4L  winerror.h


ERROR_TOO_MANY_POSTS
ERROR_TOO_MANY_POSTS  298L  winerror.h

Too many posts made to a semaphore.


FN_ERROR_TOO_MANY_POSTS
ERROR_TOO_MANY_POSTS  298L  winerror.h


ERROR_TOO_MANY_SECRETS
ERROR_TOO_MANY_SECRETS  1381L  winerror.h

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.


FN_ERROR_TOO_MANY_SECRETS
ERROR_TOO_MANY_SECRETS  1381L  winerror.h


ERROR_TOO_MANY_SEM_REQUESTS
ERROR_TOO_MANY_SEM_REQUESTS  103L  winerror.h

The semaphore cannot be set again.


FN_ERROR_TOO_MANY_SEM_REQUESTS
ERROR_TOO_MANY_SEM_REQUESTS  103L  winerror.h


ERROR_TOO_MANY_SEMAPHORES
ERROR_TOO_MANY_SEMAPHORES  100L  winerror.h

Cannot create another system semaphore.


FN_ERROR_TOO_MANY_SEMAPHORES
ERROR_TOO_MANY_SEMAPHORES  100L  winerror.h


ERROR_TOO_MANY_SESS
ERROR_TOO_MANY_SESS  69L  winerror.h

The network BIOS session limit exceeded.


FN_ERROR_TOO_MANY_SESS
ERROR_TOO_MANY_SESS  69L  winerror.h


ERROR_TOO_MANY_SIDS
ERROR_TOO_MANY_SIDS  1389L  winerror.h

Too many SIDs specified.


FN_ERROR_TOO_MANY_SIDS
ERROR_TOO_MANY_SIDS  1389L  winerror.h


ERROR_TOO_MANY_TCBS
ERROR_TOO_MANY_TCBS  155L  winerror.h

Cannot create another thread.


FN_ERROR_TOO_MANY_TCBS
ERROR_TOO_MANY_TCBS  155L  winerror.h


ERROR_TRUST_FAILURE
ERROR_TRUST_FAILURE  1790L  winerror.h

The network logon failed.


FN_ERROR_TRUST_FAILURE
ERROR_TRUST_FAILURE  1790L  winerror.h


ERROR_TRUSTED_DOMAIN_FAILURE
ERROR_TRUSTED_DOMAIN_FAILURE  1788L  winerror.h

The trust relationship between the primary domain and the trusted domain failed.


FN_ERROR_TRUSTED_DOMAIN_FAILURE
ERROR_TRUSTED_DOMAIN_FAILURE  1788L  winerror.h


ERROR_TRUSTED_RELATIONSHIP_FAILURE
ERROR_TRUSTED_RELATIONSHIP_FAILURE  1789L  winerror.h

The trust relationship between this workstation and the primary domain failed.


FN_ERROR_TRUSTED_RELATIONSHIP_FAILURE
ERROR_TRUSTED_RELATIONSHIP_FAILURE  1789L  winerror.h


ERROR_UNABLE_TO_LOCK_MEDIA
ERROR_UNABLE_TO_LOCK_MEDIA  1108L  winerror.h

Attempt to lock the eject media mechanism failed.


FN_ERROR_UNABLE_TO_LOCK_MEDIA
ERROR_UNABLE_TO_LOCK_MEDIA  1108L  winerror.h


ERROR_UNABLE_TO_UNLOAD_MEDIA
ERROR_UNABLE_TO_UNLOAD_MEDIA  1109L  winerror.h

Unload media failed.


FN_ERROR_UNABLE_TO_UNLOAD_MEDIA
ERROR_UNABLE_TO_UNLOAD_MEDIA  1109L  winerror.h


ERROR_UNEXP_NET_ERR
ERROR_UNEXP_NET_ERR  59L  winerror.h

An unexpected network error occurred.


FN_ERROR_UNEXP_NET_ERR
ERROR_UNEXP_NET_ERR  59L  winerror.h


ERROR_UNKNOWN_PORT
ERROR_UNKNOWN_PORT  1796L  winerror.h

The specified port is unknown.


FN_ERROR_UNKNOWN_PORT
ERROR_UNKNOWN_PORT  1796L  winerror.h


ERROR_UNKNOWN_PRINTPROCESSOR
ERROR_UNKNOWN_PRINTPROCESSOR  1798L  winerror.h

The print processor is unknown.


FN_ERROR_UNKNOWN_PRINTPROCESSOR
ERROR_UNKNOWN_PRINTPROCESSOR  1798L  winerror.h


ERROR_UNKNOWN_PRINTER_DRIVER
ERROR_UNKNOWN_PRINTER_DRIVER  1797L  winerror.h

The printer driver is unknown.


FN_ERROR_UNKNOWN_PRINTER_DRIVER
ERROR_UNKNOWN_PRINTER_DRIVER  1797L  winerror.h


ERROR_UNKNOWN_REVISION
ERROR_UNKNOWN_REVISION  1305L  winerror.h

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.


FN_ERROR_UNKNOWN_REVISION
ERROR_UNKNOWN_REVISION  1305L  winerror.h


ERROR_UNRECOGNIZED_MEDIA
ERROR_UNRECOGNIZED_MEDIA  1785L  winerror.h

The disk media is not recognized. It may not be formatted.


FN_ERROR_UNRECOGNIZED_MEDIA
ERROR_UNRECOGNIZED_MEDIA  1785L  winerror.h


ERROR_UNRECOGNIZED_VOLUME
ERROR_UNRECOGNIZED_VOLUME  1005L  winerror.h

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.


FN_ERROR_UNRECOGNIZED_VOLUME
ERROR_UNRECOGNIZED_VOLUME  1005L  winerror.h


ERROR_USER_EXISTS
ERROR_USER_EXISTS  1316L  winerror.h

The specified user already exists.


FN_ERROR_USER_EXISTS
ERROR_USER_EXISTS  1316L  winerror.h


ERROR_VC_DISCONNECTED
ERROR_VC_DISCONNECTED  240L  winerror.h

The session was canceled.


FN_ERROR_VC_DISCONNECTED
ERROR_VC_DISCONNECTED  240L  winerror.h


ERROR_WAIT_NO_CHILDREN
ERROR_WAIT_NO_CHILDREN  128L  winerror.h

There are no child processes to wait for.


FN_ERROR_WAIT_NO_CHILDREN
ERROR_WAIT_NO_CHILDREN  128L  winerror.h


ERROR_WINDOW_NOT_COMBOBOX
ERROR_WINDOW_NOT_COMBOBOX  1423L  winerror.h

The window is not a combo box.


FN_ERROR_WINDOW_NOT_COMBOBOX
ERROR_WINDOW_NOT_COMBOBOX  1423L  winerror.h


ERROR_WINDOW_NOT_DIALOG
ERROR_WINDOW_NOT_DIALOG  1420L  winerror.h

The window is not a valid dialog window.


FN_ERROR_WINDOW_NOT_DIALOG
ERROR_WINDOW_NOT_DIALOG  1420L  winerror.h


ERROR_WINDOW_OF_OTHER_THREAD
ERROR_WINDOW_OF_OTHER_THREAD  1408L  winerror.h

Invalid window, belongs to other thread.


FN_ERROR_WINDOW_OF_OTHER_THREAD
ERROR_WINDOW_OF_OTHER_THREAD  1408L  winerror.h


ERROR_WRITE_FAULT
ERROR_WRITE_FAULT  29L  winerror.h

The system cannot write to the specified device.


FN_ERROR_WRITE_FAULT
ERROR_WRITE_FAULT  29L  winerror.h


ERROR_WRITE_PROTECT
ERROR_WRITE_PROTECT  19L  winerror.h

The media is write protected.


FN_ERROR_WRITE_PROTECT
ERROR_WRITE_PROTECT  19L  winerror.h


ERROR_WRONG_DISK
ERROR_WRONG_DISK  34L  winerror.h

The wrong disk is in the drive. Insert %2 (Volume Serial Number: %3) into drive %1.


FN_ERROR_WRONG_DISK
ERROR_WRONG_DISK  34L  winerror.h


ERROR_WRONG_PASSWORD
ERROR_WRONG_PASSWORD  1323L  winerror.h

When trying to update a password, this return status indicates the value provided as the current password is incorrect.


FN_ERROR_WRONG_PASSWORD
ERROR_WRONG_PASSWORD  1323L  winerror.h


LZERROR_BADINHANDLE
LZERROR_BADINHANDLE  (-1)    lzexpand.h

Invalid input handle.


FN_LZERROR_BADINHANDLE
LZERROR_BADINHANDLE  (-1)    lzexpand.h


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.


RPC_S_ADDRESS_ERROR
RPC_S_ADDRESS_ERROR  1768L  winerror.h

An addressing error occurred in the server.


FN_RPC_S_ADDRESS_ERROR
RPC_S_ADDRESS_ERROR  1768L  winerror.h


RPC_S_ALREADY_LISTENING
RPC_S_ALREADY_LISTENING  1713L  winerror.h

The server is already listening.


FN_RPC_S_ALREADY_LISTENING
RPC_S_ALREADY_LISTENING  1713L  winerror.h


RPC_S_ALREADY_REGISTERED
RPC_S_ALREADY_REGISTERED  1711L  winerror.h

The object UUID already registered.


FN_RPC_S_ALREADY_REGISTERED
RPC_S_ALREADY_REGISTERED  1711L  winerror.h


RPC_S_BINDING_HAS_NO_AUTH
RPC_S_BINDING_HAS_NO_AUTH  1746L  winerror.h

The binding does not contain any authentication information.


FN_RPC_S_BINDING_HAS_NO_AUTH
RPC_S_BINDING_HAS_NO_AUTH  1746L  winerror.h


RPC_S_CALL_FAILED
RPC_S_CALL_FAILED  1726L  winerror.h

The remote procedure call failed.


FN_RPC_S_CALL_FAILED
RPC_S_CALL_FAILED  1726L  winerror.h


RPC_S_CALL_FAILED_DNE
RPC_S_CALL_FAILED_DNE  1727L  winerror.h

The remote procedure call failed and did not execute.


FN_RPC_S_CALL_FAILED_DNE
RPC_S_CALL_FAILED_DNE  1727L  winerror.h


RPC_S_CALL_IN_PROGRESS
RPC_S_CALL_IN_PROGRESS  1791L  winerror.h

A remote procedure call is already in progress for this thread.


FN_RPC_S_CALL_IN_PROGRESS
RPC_S_CALL_IN_PROGRESS  1791L  winerror.h


RPC_S_CANNOT_BIND

An attempt to bind with the server failed.


RPC_S_CANNOT_SUPPORT
RPC_S_CANNOT_SUPPORT  1764L  winerror.h

The requested operation is not supported.


FN_RPC_S_CANNOT_SUPPORT
RPC_S_CANNOT_SUPPORT  1764L  winerror.h


RPC_S_CANT_CREATE_ENDPOINT
RPC_S_CANT_CREATE_ENDPOINT  1720L  winerror.h

The endpoint cannot be created.


FN_RPC_S_CANT_CREATE_ENDPOINT
RPC_S_CANT_CREATE_ENDPOINT  1720L  winerror.h


RPC_S_DUPLICATE_ENDPOINT
RPC_S_DUPLICATE_ENDPOINT  1740L  winerror.h

The endpoint is a duplicate.


FN_RPC_S_DUPLICATE_ENDPOINT
RPC_S_DUPLICATE_ENDPOINT  1740L  winerror.h


RPC_S_ENTRY_ALREADY_EXISTS
RPC_S_ENTRY_ALREADY_EXISTS  1760L  winerror.h

The entry already exists.


FN_RPC_S_ENTRY_ALREADY_EXISTS
RPC_S_ENTRY_ALREADY_EXISTS  1760L  winerror.h


RPC_S_ENTRY_NOT_FOUND
RPC_S_ENTRY_NOT_FOUND  1761L  winerror.h

The entry is not found.


FN_RPC_S_ENTRY_NOT_FOUND
RPC_S_ENTRY_NOT_FOUND  1761L  winerror.h


RPC_S_FP_DIV_ZERO
RPC_S_FP_DIV_ZERO  1769L  winerror.h

A floating point operation at the server caused a divide by zero.


FN_RPC_S_FP_DIV_ZERO
RPC_S_FP_DIV_ZERO  1769L  winerror.h


RPC_S_FP_OVERFLOW
RPC_S_FP_OVERFLOW  1771L  winerror.h

A floating point overflow occurred at the server.


FN_RPC_S_FP_OVERFLOW
RPC_S_FP_OVERFLOW  1771L  winerror.h


RPC_S_FP_UNDERFLOW
RPC_S_FP_UNDERFLOW  1770L  winerror.h

A floating point underflow occurred at the server.


FN_RPC_S_FP_UNDERFLOW
RPC_S_FP_UNDERFLOW  1770L  winerror.h


RPC_S_GROUP_MEMBER_NOT_FOUND
RPC_S_GROUP_MEMBER_NOT_FOUND  1898L  winerror.h

The group member was not found.


FN_RPC_S_GROUP_MEMBER_NOT_FOUND
RPC_S_GROUP_MEMBER_NOT_FOUND  1898L  winerror.h


RPC_S_INCOMPLETE_NAME
RPC_S_INCOMPLETE_NAME  1755L  winerror.h

The entry name is incomplete.


FN_RPC_S_INCOMPLETE_NAME
RPC_S_INCOMPLETE_NAME  1755L  winerror.h


RPC_S_INTERFACE_NOT_FOUND
RPC_S_INTERFACE_NOT_FOUND  1759L  winerror.h

The interface was not found.


FN_RPC_S_INTERFACE_NOT_FOUND
RPC_S_INTERFACE_NOT_FOUND  1759L  winerror.h


RPC_S_INTERNAL_ERROR
RPC_S_INTERNAL_ERROR  1766L  winerror.h

An internal error occurred in RPC.


FN_RPC_S_INTERNAL_ERROR
RPC_S_INTERNAL_ERROR  1766L  winerror.h


RPC_S_INVALID_AUTH_IDENTITY
RPC_S_INVALID_AUTH_IDENTITY  1749L  winerror.h

The security context is invalid.


FN_RPC_S_INVALID_AUTH_IDENTITY
RPC_S_INVALID_AUTH_IDENTITY  1749L  winerror.h


RPC_S_INVALID_BINDING
RPC_S_INVALID_BINDING  1702L  winerror.h

The binding handle is invalid.


FN_RPC_S_INVALID_BINDING
RPC_S_INVALID_BINDING  1702L  winerror.h


RPC_S_INVALID_BOUND
RPC_S_INVALID_BOUND  1734L  winerror.h

The array bounds are invalid.


FN_RPC_S_INVALID_BOUND
RPC_S_INVALID_BOUND  1734L  winerror.h


RPC_S_INVALID_ENDPOINT_FORMAT
RPC_S_INVALID_ENDPOINT_FORMAT  1706L  winerror.h

The endpoint format is invalid.


FN_RPC_S_INVALID_ENDPOINT_FORMAT
RPC_S_INVALID_ENDPOINT_FORMAT  1706L  winerror.h


RPC_S_INVALID_NAF_IF

The network address family is invalid.


RPC_S_INVALID_NAME_SYNTAX
RPC_S_INVALID_NAME_SYNTAX  1736L  winerror.h

The name syntax is invalid.


FN_RPC_S_INVALID_NAME_SYNTAX
RPC_S_INVALID_NAME_SYNTAX  1736L  winerror.h


RPC_S_INVALID_NET_ADDR
RPC_S_INVALID_NET_ADDR  1707L  winerror.h

The network address is invalid.


FN_RPC_S_INVALID_NET_ADDR
RPC_S_INVALID_NET_ADDR  1707L  winerror.h


RPC_S_INVALID_NETWORK_OPTIONS
RPC_S_INVALID_NETWORK_OPTIONS  1724L  winerror.h

The network options are invalid.


FN_RPC_S_INVALID_NETWORK_OPTIONS
RPC_S_INVALID_NETWORK_OPTIONS  1724L  winerror.h


RPC_S_INVALID_OBJECT
RPC_S_INVALID_OBJECT  1900L  winerror.h

The object universal unique identifier (UUID) is the nil UUID.


FN_RPC_S_INVALID_OBJECT
RPC_S_INVALID_OBJECT  1900L  winerror.h


RPC_S_INVALID_RPC_PROTSEQ
RPC_S_INVALID_RPC_PROTSEQ  1704L  winerror.h

The RPC protocol sequence is invalid.


FN_RPC_S_INVALID_RPC_PROTSEQ
RPC_S_INVALID_RPC_PROTSEQ  1704L  winerror.h


RPC_S_INVALID_STRING_BINDING
RPC_S_INVALID_STRING_BINDING  1700L  winerror.h

The string binding is invalid.


FN_RPC_S_INVALID_STRING_BINDING
RPC_S_INVALID_STRING_BINDING  1700L  winerror.h


RPC_S_INVALID_STRING_UUID
RPC_S_INVALID_STRING_UUID  1705L  winerror.h

The string UUID is invalid.


FN_RPC_S_INVALID_STRING_UUID
RPC_S_INVALID_STRING_UUID  1705L  winerror.h


RPC_S_INVALID_TAG
RPC_S_INVALID_TAG  1733L  winerror.h

The tag is invalid.


FN_RPC_S_INVALID_TAG
RPC_S_INVALID_TAG  1733L  winerror.h


RPC_S_INVALID_TIMEOUT
RPC_S_INVALID_TIMEOUT  1709L  winerror.h

The timeout value is invalid.


FN_RPC_S_INVALID_TIMEOUT
RPC_S_INVALID_TIMEOUT  1709L  winerror.h


RPC_S_INVALID_VERS_OPTION
RPC_S_INVALID_VERS_OPTION  1756L  winerror.h

The version option is invalid.


FN_RPC_S_INVALID_VERS_OPTION
RPC_S_INVALID_VERS_OPTION  1756L  winerror.h


RPC_S_MAX_CALLS_TOO_SMALL
RPC_S_MAX_CALLS_TOO_SMALL  1742L  winerror.h

The maximum number of calls is too small.


FN_RPC_S_MAX_CALLS_TOO_SMALL
RPC_S_MAX_CALLS_TOO_SMALL  1742L  winerror.h


RPC_S_NAME_SERVICE_UNAVAILABLE
RPC_S_NAME_SERVICE_UNAVAILABLE  1762L  winerror.h

The name service is unavailable.


FN_RPC_S_NAME_SERVICE_UNAVAILABLE
RPC_S_NAME_SERVICE_UNAVAILABLE  1762L  winerror.h


RPC_S_NO_BINDINGS
RPC_S_NO_BINDINGS  1718L  winerror.h

There are no bindings.


FN_RPC_S_NO_BINDINGS
RPC_S_NO_BINDINGS  1718L  winerror.h


RPC_S_NO_CALL_ACTIVE
RPC_S_NO_CALL_ACTIVE  1725L  winerror.h

There is not a remote procedure call active in this thread.


FN_RPC_S_NO_CALL_ACTIVE
RPC_S_NO_CALL_ACTIVE  1725L  winerror.h


RPC_S_NO_CONTEXT_AVAILABLE
RPC_S_NO_CONTEXT_AVAILABLE  1765L  winerror.h

No security context is available to allow impersonation.


FN_RPC_S_NO_CONTEXT_AVAILABLE
RPC_S_NO_CONTEXT_AVAILABLE  1765L  winerror.h


RPC_S_NO_ENDPOINT_FOUND
RPC_S_NO_ENDPOINT_FOUND  1708L  winerror.h

No endpoint was found.


FN_RPC_S_NO_ENDPOINT_FOUND
RPC_S_NO_ENDPOINT_FOUND  1708L  winerror.h


RPC_S_NO_ENTRY_NAME
RPC_S_NO_ENTRY_NAME  1735L  winerror.h

The binding does not contain an entry name.


FN_RPC_S_NO_ENTRY_NAME
RPC_S_NO_ENTRY_NAME  1735L  winerror.h


RPC_S_NO_INTERFACES_EXPORTED

No interfaces were exported.


RPC_S_NO_MORE_BINDINGS
RPC_S_NO_MORE_BINDINGS  1806L  winerror.h

There are no more bindings.


FN_RPC_S_NO_MORE_BINDINGS
RPC_S_NO_MORE_BINDINGS  1806L  winerror.h


RPC_S_NO_MORE_MEMBERS
RPC_S_NO_MORE_MEMBERS  1757L  winerror.h

There are no more members.


FN_RPC_S_NO_MORE_MEMBERS
RPC_S_NO_MORE_MEMBERS  1757L  winerror.h


RPC_S_NO_PROTSEQS
RPC_S_NO_PROTSEQS  1719L  winerror.h

There are no protocol sequences.


FN_RPC_S_NO_PROTSEQS
RPC_S_NO_PROTSEQS  1719L  winerror.h


RPC_S_NO_PROTSEQS_REGISTERED
RPC_S_NO_PROTSEQS_REGISTERED  1714L  winerror.h

No protocol sequences were registered.


FN_RPC_S_NO_PROTSEQS_REGISTERED
RPC_S_NO_PROTSEQS_REGISTERED  1714L  winerror.h


RPC_S_NOT_LISTENING
RPC_S_NOT_LISTENING  1715L  winerror.h

The server is not listening.


FN_RPC_S_NOT_LISTENING
RPC_S_NOT_LISTENING  1715L  winerror.h


RPC_S_NOTHING_TO_UNEXPORT

There is nothing to unexport.


RPC_S_OBJECT_NOT_FOUND
RPC_S_OBJECT_NOT_FOUND  1710L  winerror.h

The object UUID was not found.


FN_RPC_S_OBJECT_NOT_FOUND
RPC_S_OBJECT_NOT_FOUND  1710L  winerror.h


RPC_S_OUT_OF_RESOURCES
RPC_S_OUT_OF_RESOURCES  1721L  winerror.h

Not enough resources are available to complete this operation.


FN_RPC_S_OUT_OF_RESOURCES
RPC_S_OUT_OF_RESOURCES  1721L  winerror.h


RPC_S_PROCNUM_OUT_OF_RANGE
RPC_S_PROCNUM_OUT_OF_RANGE  1745L  winerror.h

The procedure number is out of range.


FN_RPC_S_PROCNUM_OUT_OF_RANGE
RPC_S_PROCNUM_OUT_OF_RANGE  1745L  winerror.h


RPC_S_PROTOCOL_ERROR
RPC_S_PROTOCOL_ERROR  1728L  winerror.h

An RPC protocol error occurred.


FN_RPC_S_PROTOCOL_ERROR
RPC_S_PROTOCOL_ERROR  1728L  winerror.h


RPC_S_PROTSEQ_NOT_FOUND
RPC_S_PROTSEQ_NOT_FOUND  1744L  winerror.h

The RPC protocol sequence was not found.


FN_RPC_S_PROTSEQ_NOT_FOUND
RPC_S_PROTSEQ_NOT_FOUND  1744L  winerror.h


RPC_S_PROTSEQ_NOT_SUPPORTED
RPC_S_PROTSEQ_NOT_SUPPORTED  1703L  winerror.h

The RPC protocol sequence is not supported.


FN_RPC_S_PROTSEQ_NOT_SUPPORTED
RPC_S_PROTSEQ_NOT_SUPPORTED  1703L  winerror.h


RPC_S_SERVER_NOT_LISTENING

The server is not listening for remote procedure calls.


RPC_S_SERVER_OUT_OF_MEMORY
RPC_S_SERVER_OUT_OF_MEMORY  ERROR_NOT_ENOUGH_SERVER_MEMORY  rpcnterr.h

The server has insufficient memory to complete this operation.


FN_RPC_S_SERVER_OUT_OF_MEMORY
RPC_S_SERVER_OUT_OF_MEMORY  ERROR_NOT_ENOUGH_SERVER_MEMORY  rpcnterr.h


RPC_S_SERVER_TOO_BUSY
RPC_S_SERVER_TOO_BUSY  1723L  winerror.h

The server is too busy to complete this operation.


FN_RPC_S_SERVER_TOO_BUSY
RPC_S_SERVER_TOO_BUSY  1723L  winerror.h


RPC_S_SERVER_UNAVAILABLE
RPC_S_SERVER_UNAVAILABLE  1722L  winerror.h

The server is unavailable.


FN_RPC_S_SERVER_UNAVAILABLE
RPC_S_SERVER_UNAVAILABLE  1722L  winerror.h


RPC_S_STRING_TOO_LONG
RPC_S_STRING_TOO_LONG  1743L  winerror.h

The string is too long.


FN_RPC_S_STRING_TOO_LONG
RPC_S_STRING_TOO_LONG  1743L  winerror.h


RPC_S_TYPE_ALREADY_REGISTERED
RPC_S_TYPE_ALREADY_REGISTERED  1712L  winerror.h

The type UUID is already registered.


FN_RPC_S_TYPE_ALREADY_REGISTERED
RPC_S_TYPE_ALREADY_REGISTERED  1712L  winerror.h


RPC_S_UNKNOWN_AUTHN_LEVEL
RPC_S_UNKNOWN_AUTHN_LEVEL  1748L  winerror.h

The authentication level is unknown.


FN_RPC_S_UNKNOWN_AUTHN_LEVEL
RPC_S_UNKNOWN_AUTHN_LEVEL  1748L  winerror.h


RPC_S_UNKNOWN_AUTHN_SERVICE
RPC_S_UNKNOWN_AUTHN_SERVICE  1747L  winerror.h

The authentication service is unknown.


FN_RPC_S_UNKNOWN_AUTHN_SERVICE
RPC_S_UNKNOWN_AUTHN_SERVICE  1747L  winerror.h


RPC_S_UNKNOWN_AUTHN_TYPE
RPC_S_UNKNOWN_AUTHN_TYPE  1741L  winerror.h

The authentication type is unknown.


FN_RPC_S_UNKNOWN_AUTHN_TYPE
RPC_S_UNKNOWN_AUTHN_TYPE  1741L  winerror.h


RPC_S_UNKNOWN_AUTHZ_SERVICE
RPC_S_UNKNOWN_AUTHZ_SERVICE  1750L  winerror.h

The authorization service is unknown.


FN_RPC_S_UNKNOWN_AUTHZ_SERVICE
RPC_S_UNKNOWN_AUTHZ_SERVICE  1750L  winerror.h


RPC_S_UNKNOWN_IF
RPC_S_UNKNOWN_IF  1717L  winerror.h

The interface is unknown.


FN_RPC_S_UNKNOWN_IF
RPC_S_UNKNOWN_IF  1717L  winerror.h


RPC_S_UNKNOWN_MGR_TYPE
RPC_S_UNKNOWN_MGR_TYPE  1716L  winerror.h

The manager type is unknown.


FN_RPC_S_UNKNOWN_MGR_TYPE
RPC_S_UNKNOWN_MGR_TYPE  1716L  winerror.h


RPC_S_UNSUPPORTED_NAME_SYNTAX
RPC_S_UNSUPPORTED_NAME_SYNTAX  1737L  winerror.h

The name syntax is not supported.


FN_RPC_S_UNSUPPORTED_NAME_SYNTAX
RPC_S_UNSUPPORTED_NAME_SYNTAX  1737L  winerror.h


RPC_S_UNSUPPORTED_TRANS_SYN
RPC_S_UNSUPPORTED_TRANS_SYN  1730L  winerror.h

The transfer syntax is not supported by the server.


FN_RPC_S_UNSUPPORTED_TRANS_SYN
RPC_S_UNSUPPORTED_TRANS_SYN  1730L  winerror.h


RPC_S_UNSUPPORTED_TYPE
RPC_S_UNSUPPORTED_TYPE  1732L  winerror.h

The type UUID is not supported.


FN_RPC_S_UNSUPPORTED_TYPE
RPC_S_UNSUPPORTED_TYPE  1732L  winerror.h


RPC_S_UUID_NO_ADDRESS
RPC_S_UUID_NO_ADDRESS  1739L  winerror.h

No network address is available to use to construct a UUID.


FN_RPC_S_UUID_NO_ADDRESS
RPC_S_UUID_NO_ADDRESS  1739L  winerror.h


RPC_S_WRONG_KIND_OF_BINDING
RPC_S_WRONG_KIND_OF_BINDING  1701L  winerror.h

The binding handle is the incorrect type.


FN_RPC_S_WRONG_KIND_OF_BINDING
RPC_S_WRONG_KIND_OF_BINDING  1701L  winerror.h


RPC_S_ZERO_DIVIDE
RPC_S_ZERO_DIVIDE  1767L  winerror.h

The server attempted an integer divide by zero.


FN_RPC_S_ZERO_DIVIDE
RPC_S_ZERO_DIVIDE  1767L  winerror.h


RPC_X_BAD_STUB_DATA
RPC_X_BAD_STUB_DATA  1783L  winerror.h

The stub received bad data.


FN_RPC_X_BAD_STUB_DATA
RPC_X_BAD_STUB_DATA  1783L  winerror.h


RPC_X_BYTE_COUNT_TOO_SMALL
RPC_X_BYTE_COUNT_TOO_SMALL  1782L  winerror.h

The byte count is too small.


FN_RPC_X_BYTE_COUNT_TOO_SMALL
RPC_X_BYTE_COUNT_TOO_SMALL  1782L  winerror.h


RPC_X_ENUM_VALUE_OUT_OF_RANGE
RPC_X_ENUM_VALUE_OUT_OF_RANGE  1781L  winerror.h

The enumeration value is out of range.


FN_RPC_X_ENUM_VALUE_OUT_OF_RANGE
RPC_X_ENUM_VALUE_OUT_OF_RANGE  1781L  winerror.h


RPC_X_NO_MORE_ENTRIES
RPC_X_NO_MORE_ENTRIES  1772L  winerror.h

The list of servers available for auto_handle binding was exhausted.


FN_RPC_X_NO_MORE_ENTRIES
RPC_X_NO_MORE_ENTRIES  1772L  winerror.h


RPC_X_NULL_REF_POINTER
RPC_X_NULL_REF_POINTER  1780L  winerror.h

A null reference pointer was passed to the stub.


FN_RPC_X_NULL_REF_POINTER
RPC_X_NULL_REF_POINTER  1780L  winerror.h


RPC_X_SS_CANNOT_GET_CALL_HANDLE
RPC_X_SS_CANNOT_GET_CALL_HANDLE  1779L  winerror.h

The stub is unable to get the call handle.


FN_RPC_X_SS_CANNOT_GET_CALL_HANDLE
RPC_X_SS_CANNOT_GET_CALL_HANDLE  1779L  winerror.h


RPC_X_SS_CHAR_TRANS_OPEN_FAIL
RPC_X_SS_CHAR_TRANS_OPEN_FAIL  1773L  winerror.h

The file designated by DCERPCCHARTRANS cannot be opened.


FN_RPC_X_SS_CHAR_TRANS_OPEN_FAIL
RPC_X_SS_CHAR_TRANS_OPEN_FAIL  1773L  winerror.h


RPC_X_SS_CHAR_TRANS_SHORT_FILE
RPC_X_SS_CHAR_TRANS_SHORT_FILE  1774L  winerror.h

The file containing the character translation table has fewer than 512 bytes.


FN_RPC_X_SS_CHAR_TRANS_SHORT_FILE
RPC_X_SS_CHAR_TRANS_SHORT_FILE  1774L  winerror.h


RPC_X_SS_CONTEXT_DAMAGED
RPC_X_SS_CONTEXT_DAMAGED  1777L  winerror.h

The context handle changed during a call.


FN_RPC_X_SS_CONTEXT_DAMAGED
RPC_X_SS_CONTEXT_DAMAGED  1777L  winerror.h


RPC_X_SS_CONTEXT_MISMATCH
RPC_X_SS_CONTEXT_MISMATCH  ERROR_INVALID_HANDLE  rpcnterr.h

The context handle does not match any known context handles.


FN_RPC_X_SS_CONTEXT_MISMATCH
RPC_X_SS_CONTEXT_MISMATCH  ERROR_INVALID_HANDLE  rpcnterr.h


RPC_X_SS_HANDLES_MISMATCH
RPC_X_SS_HANDLES_MISMATCH  1778L  winerror.h

The binding handles passed to a remote procedure call do not match.


FN_RPC_X_SS_HANDLES_MISMATCH
RPC_X_SS_HANDLES_MISMATCH  1778L  winerror.h


RPC_X_SS_IN_NULL_CONTEXT
RPC_X_SS_IN_NULL_CONTEXT  1775L  winerror.h

A null context handle is passed as an [in] parameter.


FN_RPC_X_SS_IN_NULL_CONTEXT
RPC_X_SS_IN_NULL_CONTEXT  1775L  winerror.h


Virtual Key Codes

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 name	Value (in hex)	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

--	5B-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

--	F6-FE	Unassigned


Locale Identifiers

™. The information presented here pertains to locale identifiers, LCTYPE constants, country codes, and language identifiers.

Locale Identifiers (LCIDs)

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

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:

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:

Identifier	Sublanguage/Locale	Language Code

0x0419	Russian	RUS

The following sublanguage/locale uses an other script:

Identifier	Sublanguage/Locale	Language Code

0x0408	Greek	ELL

The following special identifiers are also defined:

Identifier	Sublanguage/Locale

0x0000	Language-Neutral

0x0400	Process Default Language


Multimedia Manufacturer and Product Identifiers

Introduction

This appendix provides lists of the manufacturer and product identifiers currently used with the Microsoft® Windows™ operating system with Multimedia Extensions. This list will grow as more manufacturers create multimedia products for Windows.

To get a current list of manufacturer and product identifiers for the Multimedia Extensions, and to register new ones, request a Multimedia Developer Registration Kit from the following group:

Microsoft Corporation

Multimedia Systems Group

Product Marketing

One Microsoft Way

Redmond, WA 98052-6399

Manufacturer Identifiers

Following are the current manufacturer identifiers for the Multimedia Extensions.

Constant	Value	Description

MM_MICROSOFT	1	Drivers developed by Microsoft Corporation

Product Identifiers

Following are the current product identifiers for the Multimedia Extensions.

Constant	Value	Description

MM_MIDI_MAPPER	1	Microsoft MIDI Mapper

MM_SNDBLST_MIDIOUT	3	Sound Blaster™ MIDI output port

MM_SNDBLST_MIDIIN	4	Sound Blaster MIDI input port

MM_SNDBLST_SYNTH	5	Sound Blaster internal synthesizer

MM_SNDBLST_WAVEOUT	6	Sound Blaster waveform output port

MM_SNDBLST_WAVEIN	7	Sound Blaster waveform input port

MM_ADLIB	9	Ad Lib® (or compatible) synthesizer

MM_MPU401_MIDIOUT	10	Roland® MPU-401 MIDI output port

MM_MPU401_MIDIIN	11	Roland MPU-401 MIDI input port

MM_PC_JOYSTICK	12	IBM® Game Control Adapter


MCI Command String Syntax Summary

Introduction

This appendix provides a summary of the syntax of the MCI command strings.

The following topics are included in this appendix:

About the Command Tables

System Command Set

Required Command Set

Basic Command Set

Animation Command Set

CD Audio Command Set

MIDI Sequencer Command Set

Videodisc Command Set

Video Overlay Command Set

Waveform Audio Command Set


About the Command Tables

Each command table has a Command column and an Arguments column. The Command column contains the MCI commands available for a device type. The Arguments column contains the options available for each MCI command. For example, the following table contains the MCI commands all devices support.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can save

| compound device

| device type

| has audio

| has video

| uses files}

close device_name

info device_name	[product]

open device_name	[alias device_alias]

[shareable]

[type device_type]

status device_name	[mode | ready]

Each command also has a notify and wait flag that does not appear in the tables. These flags can be added to any command.

The following conventions are used in the previous example and for the other MCI command tables.

Type style	Used for

Bold	A specific term intended to be used literally. When used in the command column, it represents the MCI string command. When used in the arguments column, it represents a flag. For example, the capability command and the can play flag must be typed as shown.

Italics	Placeholders for information you must provide. The MCI command or flag associated with the information must precede it. For example, to use the alias words for the device_name with the capability command, type "capability words can play."

|	Divider for mutually exclusive arguments. When multiple arguments are separated by this symbol, only one of them can be used for each command. For example, the items in the list can eject, can play, can record, can save, compound device, device type, has audio, has video, uses files are mutually exclusive and you must select only one to use with the capability command. (Do not type the | with the argument.)

{}	Required argument. You must include an argument enclosed by braces. For example, you must use one of the arguments can eject, can play, can record, can save, compound device, device type, has audio, has video, uses files with the capability command. (Do not type the braces with the argument.)

[ ]	Optional argument. For example, the alias, type and shareable flags are optional for the open command. You can use any combination of these flags. You can also use optional arguments with a required argument. (Do not type the brackets with the argument.)


System Command Set

The following table summarizes the MCI system commands. These commands are interpreted directly by MCI. System commands also support notify and wait as optional flags. You can add either or both of these flags to any system command.

Command	Arguments

break device_name	{off | on virtual key code}

sound sound_name

sysinfo device_name	{installname

| name index

| name index open

| quantity

| quantity open}


Required Command Set

The following table lists the commands recognized by all devices. Extended commands can add other options to these commands. Required commands also support notify and wait as optional flags. You can add either or both of these flags to any required command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can save

| compound device

| device type

| has audio

| has video

| uses files}

close device_name

info device_name	[product]

open device_name	[alias device_alias]

[shareable]

[type device_type]

status device_name	[mode | ready]


Basic Command Set

In addition to supporting the commands described previously, each device supports a set of commands specific to its device type. Although these commands are optional for a device, if a command is used it must support the options listed in this table as a minimum set of capabilities. Basic commands also support notify and wait as optional flags. You can add either or both of these flags to any basic command.

Command	Arguments

load device_name	{file_name}

pause device_name

play device_name	[from position]

[to position]

[insert | overwrite]

resume device_name

save device_name	[file_name]

seek device_name	{to position | to start | to end}

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[door closed | door open]

[time format milliseconds | time format ms]

status device_name	{current track

| length

| length track track_number

| mode

| number of tracks

| position

| position track track_number

| ready

| start position

| time format}

stop device name


Animation Command Set

Animation devices support the following set of commands. These devices also supporty notify and wait as optional flags. You can add either or both of these flags to any animation command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can reverse

| can save

| can stretch

| compound device

| device type

| fast play rate

| has audio

| has video

| normal play rate

| slow play rate

| uses files

| uses palettes

| windows}

close device_name

info device_name	[file | product | window text]

open device_name	[alias device_alias]

[nostatic]

[parent hwnd]

[shareable]

[style child

| style overlapped

| style popup]

[type device_type]

pause device_name

play device_name	[fast | slow | speed fps]

[from position]

[to position | reverse]

[scan]

put device_name	{destination

| destination at destination_rectangle

| source

| source at source_rectangle}

realize device_name	{background | normal}

resume device_name

seek device_name	[to position | to start | to end]

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[time format milliseconds

| time format ms

| time format frames]

status device_name	{current track

| forward

| length

| length track track_number

| media present

| mode

| number of tracks

| palette handle

| position

| position track track_number

| ready

| speed

| start position

| stretch

| time format

| window handle}

step device_name	[by frames]

stop device_name

update device_name	[at update_rect]

[hdc hdc]

where device_name	{destination | source}

window device_name	[handle window_handle | handle default]

[stretch | fixed]

[state hide

| state iconic

| state maximized

| state minimize

| state minimized

| state no action

| state no active

| state normal

| state show]

[text caption_text]


Audio CD Command Set

Audio CD devices support the following core set of commands. Audio CD devices also support notify and wait as option flags. You can add either or both of these flags to any audio CD command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can save

| compound device

| device type

| has audio

| has video

| uses files}

close device_name	[product]

info device_name

open device_name	[alias device_name]

[shareable]

pause device_name

play device_name	[from position]

[to position]

resume device_name

seek device_name	[to position to start | to end]

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[door closed | door open]

[time format milliseconds

| time format ms

| time format msf

| time format tmsf]

status device_name	{current track

| length

| length track track_number

| media present

| mode

| number of tracks

| position

| position track track_number

| ready

| start position

| time format}

stop device_name


MIDI Sequencer Command Set

The MIDI sequencer supports the following set of commands. MIDI sequencers also support notify and wait as optional flags. You can add either or both of these flags to any MIDI sequencer command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can save

| compound device

| device type

| has audio

| has video

| uses files}

close device_name

info device_name	[file | product]

open device_name	[alias device_alias]

[shareable]

[type device_type]

pause device_name

play device_name	[from position]

[to position]

record device_name	[from position]

[to position]

[insert | overwrite]

save device_name	[file_name]

seek device_name	[to position | to start | to end]

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[master MIDI

| master none

| master SMPTE]

[offset hmsf_value]

[port port_number

| port mapper

| port none]

[slave file

| slave MIDI

| slave none

| slave SMPTE]

[tempo tempo_value]

[time format milliseconds

| time format ms

| time format smpte 24

| time format smpte 25

| time format smpte 30

| time format smpte 30 drop

| time format song pointer]

status device_name	{current track

| division type

| length

| length track track_number

| master

| media present

| mode

| number of tracks

| offset

| port

| position

| position track track_number

| ready

| slave

| start position

| tempo

| time format}

stop device_name


Videodisc Command Set

Videodisc players support the following set of commands. Videodisc devices also support notify and wait as optional flags. You can add either or both of these flags to any videodisc command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can reverse

| can save

| compound device

| device type

| fast play rate

| has audio

| has video

| normal play rate

| slow play rate

| uses files}

[CAV | CLV]

close device_name

escape device_name	{command_string}

info device_name	[product]

open device_name	[alias device_alias]

[shareable]

pause device_name

play device_name	[fast | slow | speed fps]

[from position]

[scan]

[to position | reverse]

resume device_name

seek device_name	[reverse | to position | to start | to end]

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[door closed | door open]

[time format milliseconds

| time format ms

| time format frames

| time format hms

| time format track]

spin device_name	[down | up]

status device_name	{current track

| disc size

| forward

| length

| length track track_number

| media present

| media type

| mode

| number of tracks

| position

| position track track_number

| ready

| side

| speed

| start position

| time format}

step device_name	[by] position

[reverse]

stop device_name


Video Overlay Command Set

Video overlay devices support the following set of commands. Video overlay devices also support notify and wait as optional flags. You can add either or both of these flags to any video overlay command.

Command	Arguments

capability device_name	{can eject

| can freeze

| can play

| can record

| can save

| can stretch

| compound device

| device type

| has audio

| has video

| uses files

| windows}

close device_name

freeze device_name	[at rectangle]

info device_name	[product | file | window text]

load device_name	[file_name]

at  buffer_rectangle

open device_name	[alias device_alias]

[parent hwnd]

[shareable]

[style style_type

| style child

| style overlapped

| style popup]

[type device_type]

put device_name	{destination | at destination_rectangle

| frame

| frame at frame_rectangle

| source

| source at source_rectangle

| video

| video at video_rectangle}

save device_name	[file_name]

at buffer_rectangle

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[time format milliseconds

| time format ms]

status device_name	{current track

| length

| length track track_number

| media present

| mode

| number of tracks

| position

| position track track_number

| ready

| start position

| stretch

| time format

| window handle}

unfreeze device_name	[at freeze_rectangle]

where device_name	{destination | frame | source | video}

window device_name	[handle window_handle | handle default]

| [stretch | fixed]

[state hide

| state iconic

| state maximized

| state minimized

| state no action

| state no activate

| state normal

| state show]

[text caption_text]


Waveform Audio Command Set

Wave audio devices support the following set of commands. Wave audio devices also support notify and wait as optional flags. You can add either or both of these flags to any wave audio command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can save

| compound device

| device type

| has audio

| has video

| inputs

| outputs

| uses files}

close device_name

cue device_name	[input | output]

delete device_name	[from position]

[to position]

info device_name	[file

| input

| output

| product]

open device_name	[alias device_alias]

[buffer buffer_size]

[shareable]

[type device_type]

pause device_name

play device_name	[from position]

[to position]

record device_name	[from position]

[to position]

[insert | overwrite]

resume device_name

save device_name	[file_name]

seek device_name	[to position | to start | to end]

set device_name	[alignment block_alignment]

[any input]

[any output]

[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[bitspersample bit_count]

[bytespersec byte_rate]

[channels channel_count]

[format tag tag | format tag pcm]

[input device_number]

[output device_number]

[samplespersec sample_rate]

[timeformat milliseconds

| time format ms

| time format bytes

| time format samples]

status device_name	{alignment

| bitspersample

| bytespersec

| channels

| current track

| format tag

| input

| length

| length track track_number

| level

| media present

| mode

| number of tracks

| output

| position

| position track track_number

| ready

| samplespersec

| start position

| time format}

stop device_name


Raster Operation Codes

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 the RGB structure in Chapter 3, "Structures."

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


Constants
Constants (Win32)

Constants A-M

Constants N-Z


Constants A-M
Constants A-M (Win32)

Constant	Meaning

ACCESS_ALLOWED_ACE_TYPE

Access-allowed ACE (defined by the ACCESS_ALLOWED_ACE structure)

See ACE_HEADER.

ACCESS_DENIED_ACE_TYPE

Access-denied ACE (defined by the ACCESS_DENIED_ACE structure)

See ACE_HEADER.

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 other timing considerations. This return code does not mean that the command completed successfully. The caller must check the uchDlcStatus field in the CCB to determine whether the request succeeded or failed.

See AcsLan

ACSLAN_STATUS_INVALID_CCB_POINTER

A pointer in the CCB structure or the parameter table is invalid.

See AcsLan

ACSLAN_STATUS_CCB_IN_ERROR

A problem was detected with the CCB. The caller should check the values in the CCB and resubmit it.

See AcsLan

ACSLAN_STATUS_CHAINED_CCB_IN_ERROR

A problem was detected with a CCB in a chain of CCBs.

See AcsLan

ACSLAN_STATUS_SYSTEM_ERROR

This code is not used.

See AcsLan

ACSLAN_STATUS_SYSTEM_STATUS

This code is not used.

See AcsLan

ACSLAN_STATUS_INVALID_COMMAND

The command in the uchDlcCommand field of the CCB is unrecognized

See AcsLan

AD_CLOCKWISE

Figures drawn clockwise.

See GetArcDirection, SetArcDirection.

AD_COUNTERCLOCKWISE

Figures drawn counterclockwise.

See GetArcDirection, SetArcDirection.

ALTERNATE

Selects alternate mode (fills area between odd-numbered and even-numbered polygon sides on each scan line).

See CreatePolygonRgn, CreatePolyPolygonRgn, GetPolyFillMode, SetPolyFillMode.

ANSI_FIXED_FONT

Windows fixed-pitch system font

See GetStockObject.

ANSI_VAR_FONT

Windows variable-pitch system font

See GetStockObject.

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 Comments section.

See DdeInitialize.

APPCLASS_STANDARD

Registers the application as a standard (nonmonitoring) DDEML application.

See DdeInitialize.

APPCMD_CLIENTONLY

Prevents the application from becoming a server in a DDE conversation. The application can be only a client. This flag reduces resource consumption by the DDEML. It includes the functionality of the CBF_FAIL_ALLSVRXACTIONS flag.

See DdeInitialize.

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 this flag. On subsequent calls to DdeInitialize, not specifying this flag turns off the application's service-name filters; specifying this flag turns on the application's service-name filters.

See DdeInitialize.

ASPECTX

Relative width of a device pixel used for line drawing.

See GetDeviceCaps.

ASPECTXY

Diagonal width of the device pixel used for line drawing.

See GetDeviceCaps.

ASPECTY

Relative height of a device pixel used for line drawing.

See GetDeviceCaps.

AUX_MAPPER

Auxiliary audio mapper. The function will return an error if no auxiliary audio mapper is installed.

See auxGetDevCaps, auxOutMessage.

AUXCAPS_AUXIN

Audio output from auxiliary input jacks.

See AUXCAPS.

AUXCAPS_CDAUDIO

Audio output from an internal CD-ROM drive.

See AUXCAPS.

AUXCAPS_LRVOLUME

Supports separate left and right volume control.

See AUXCAPS.

AUXCAPS_VOLUME

Supports volume control.

See AUXCAPS.

BACKUP_ALTERNATE_DATA

Alternate data streams

See WIN32_STREAM_ID.

BACKUP_DATA

Standard data

See WIN32_STREAM_ID.

BACKUP_EA_DATA

Extended attribute data

See WIN32_STREAM_ID.

BACKUP_LINK

Hard link information

See WIN32_STREAM_ID.

BACKUP_SECURITY_DATA

NT security descriptor data

See WIN32_STREAM_ID.

BI_RGB

Specifies that the bitmap is not compressed.

See BITMAPINFOHEADER.

BI_RLE4

Specifies a run-length encoded 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 indexes. For more information, see the following Comments section.

See BITMAPINFOHEADER.

BI_RLE8

Specifies a run-length encoded 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. See the Comments section for more information.

See BITMAPINFOHEADER.

BITSPIXEL

Number of adjacent color bits for each pixel.

See GetDeviceCaps.

BLACK_BRUSH

Black brush

See GetStockObject.

BLACK_PEN

Black pen

See GetStockObject.

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

See BitBlt, PatBlt.

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.

See SetStretchBltMode.

BMF_DIB

The first scanline in the buffer at which lppBits points is the bottom scanline.

See CreateDIBSection.

BMF_TOPDOWN

The first scanline in the buffer at which lppBits points is the top scanline.

See CreateDIBSection.

BS_DIBPATTERN

Specifies a pattern brush defined by a device-independent bitmap (DIB) specification.

See EXTLOGPEN, LOGBRUSH.

BS_HATCHED

Specifies a hatched brush.

See EXTLOGPEN, LOGBRUSH.

BS_HOLLOW

Specifies a hollow or NULL brush.

See EXTLOGPEN, LOGBRUSH.

BS_NULL

Specifies a hollow or NULL brush. Same as BS_HOLLOW.

See LOGBRUSH.

BS_PATTERN

Specifies a pattern brush defined by a memory bitmap.

See EXTLOGPEN, LOGBRUSH.

BS_SOLID

Specifies a solid brush.

See EXTLOGPEN, LOGBRUSH.

BUTTON

Designates a small rectangular child window that represents a button the user can turn on or off by clicking. You can use button controls alone or in groups, and they can either be labeled or appear without text. Button controls typically change appearance when the user clicks them.

See CreateWindow.

CALL_PENDING

The session is attempting to connect to a remote computer.

See SESSION_BUFFER.

CALLBACK_FUNCTION

If this flag is specified, dwCallback is assumed to be a callback procedure address.

See midiInOpen, midiOutOpen, waveInOpen, waveOutOpen.

CALLBACK_WINDOW

If this flag is specified, dwCallback is assumed to be a window handle.

See midiInOpen, midiOutOpen, waveInOpen, waveOutOpen.

CAPSLOCK_ON

The CAPS LOCK light is on.

See KEY_EVENT_RECORD.

CB_OKAY

A combo-box message return value that indicates success.

CB_ERR

A combo box message return value that indicates that an error occurred.

CB_ERRSPACE

A combo box message return value that indicates the occurrence of an error related to insufficient string storage space.

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.

See DdeInitialize.

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.

See DdeInitialize.

CBF_FAIL_CONNECTIONS

Prevents the callback function from receiving XTYP_CONNECT and XTYP_WILDCONNECT transactions.

See DdeInitialize.

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.

See DdeInitialize.

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.

See DdeInitialize.

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.

See DdeInitialize.

CBF_FAIL_SELFCONNECTIONS

Prevents the callback function from receiving XTYP_CONNECT transactions from the application's own instance. This 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.

See DdeInitialize.

CBF_SKIP_ALLNOTIFICATIONS

Prevents the callback function from receiving any notifications. This flag is equivalent combining all CBF_SKIP_ flags.

See DdeInitialize.

CBF_SKIP_CONNECT_CONFIRMS

Prevents the callback function from receiving XTYP_CONNECT_CONFIRM notifications.

See DdeInitialize.

CBF_SKIP_DISCONNECTS

Prevents the callback function from receiving XTYP_DISCONNECT notifications.

See DdeInitialize.

CBF_SKIP_REGISTRATIONS

Prevents the callback function from receiving XTYP_REGISTER notifications.

See DdeInitialize.

CBF_SKIP_UNREGISTRATIONS

Prevents the callback function from receiving XTYP_UNREGISTER notifications.

See DdeInitialize.

CC_ENABLEHOOK

Enables the hook function specified in the lpfnHook member.

See CHOOSECOLOR.

CC_ENABLETEMPLATE

Causes the system to create the dialog box by using the dialog template identified by the hInstance and lpTemplateName members.

See CHOOSECOLOR.

CC_ENABLETEMPLATEHANDLE

Indicates that the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpTemplateName member if this flag is specified.

See CHOOSECOLOR.

CC_FULLOPEN

Causes the entire dialog box to appear when the dialog box is created, including the portion that allows the user to create custom colors. Without this flag, the user must select the "Define Custom Color..." push button to see this portion of the dialog box.

See CHOOSECOLOR.

CC_PREVENTFULLOPEN

Disables the "Define Custom Colors..." push button, preventing the user from creating custom colors.

See CHOOSECOLOR.

CC_RGBINIT

Causes the dialog box to use the color specified in the rgbResult member as the initial color selection.

See CHOOSECOLOR.

CC_SHOWHELP

Causes the dialog box to show the Help push button. The hwndOwner member must not be NULL if this option is specified.

See CHOOSECOLOR.

CDERR_FINDRESFAILURE

Specifies the common dialog box procedure failed to find a specified resource.

See CommDlgExtendedError.

CDERR_INITIALIZATION

Specifies the common dialog box procedure failed during initialization. This error often occurs when insufficient memory is found.

See CommDlgExtendedError.

CDERR_LOADRESFAILURE

Specifies the common dialog box procedure failed to load a specified resource.

See CommDlgExtendedError.

CDERR_LOADSTRFAILURE

Specifies the common dialog box procedure failed to load a specified string.

See CommDlgExtendedError.

CDERR_LOCKRESFAILURE

Specifies the common dialog box procedure failed to lock a specified resource.

See CommDlgExtendedError.

CDERR_MEMALLOCFAILURE

Specifies the common dialog box procedure was unable to allocate memory for internal structures.

See CommDlgExtendedError.

CDERR_MEMLOCKFAILURE

Specifies the common dialog box procedure was unable to lock the memory associated with a handle.

See CommDlgExtendedError.

CDERR_NOHINSTANCE

Specifies the ENABLETEMPLATE flag was set in the Flags member of a structure for the corresponding common dialog box but the application failed to provide a corresponding instance handle.

See CommDlgExtendedError.

CDERR_NOHOOK

Specifies the ENABLEHOOK flag was set in the Flags member of a structure for the corresponding common dialog box but the application failed to provide a pointer to a corresponding hook function.

See CommDlgExtendedError.

CDERR_NOTEMPLATE

Specifies the ENABLETEMPLATE flag was set in the Flags member of a structure for the corresponding common dialog box but the application failed to provide a corresponding template.

See CommDlgExtendedError.

CDERR_REGISTERMSGFAIL

Specifies the RegisterWindowMessage function returned an error value when called by the common dialog box procedure.

See CommDlgExtendedError.

CDERR_STRUCTSIZE

Specifies as invalid the lStructSize member of a structure for the corresponding common dialog box.

See CommDlgExtendedError.

CF_ANSIONLY

Specifies the ChooseFont function should only allow the selection of fonts using the ANSI character set. (If this flag is set, the user will not be able to select a font that only contains symbols.)

See CHOOSEFONT.

CF_APPLY

Specifies the ChooseFont function should enable the Apply button.

See CHOOSEFONT.

CF_BITMAP

A handle of a bitmap (HBITMAP).

See SetClipboardData.

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.

See CHOOSEFONT.

CF_DIB

A memory object containing a BITMAPINFO structure followed by the bitmap bits.

See SetClipboardData.

CF_DIF

Software Arts' Data Interchange Format.

See SetClipboardData.

CF_DSPBITMAP

Bitmap display format associated with private format. The hData parameter must be a handle to data that can be displayed in bitmap format in lieu of the privately formatted data.

See SetClipboardData.

CF_DSPENHMETAFILE

Enhanced metafile display format associated with private format. The hData parameter must be a handle to data that can be displayed in enhanced metafile format in lieu of the privately formatted data.

See SetClipboardData.

CF_DSPMETAFILEPICT

Metafile-picture display format associated with private format. The hData parameter must be a handle to data that can be displayed in metafile-picture format in lieu of the privately formatted data.

See SetClipboardData.

CF_DSPTEXT

Text display format associated with private format. The hData parameter must be a handle to data that can be displayed in text format in lieu of the privately formatted data.

See SetClipboardData.

CF_EFFECTS

Specifies the ChooseFont function should enable strikeout, underline, and color effects.

See CHOOSEFONT.

CF_ENABLEHOOK

Enables the hook function specified in the lpfnHook member of this structure.

See CHOOSEFONT.

CF_ENABLETEMPLATE

Indicates the hInstance member identifies a data block that contains a dialog template identified by lpTemplateName.

See CHOOSEFONT.

CF_ENABLETEMPLATEHANDLE

Indicates the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpTemplateName member if this flag is specified.

See CHOOSEFONT.

CF_ENHMETAFILE

A handle to an enhanced metafile (HEMF).

See SetClipboardData.

CF_FIXEDPITCHONLY

Specifies the ChooseFont function should only select fixed-pitch fonts.

See CHOOSEFONT.

CF_FORCEFONTEXIST

Specifies the ChooseFont function should indicate an error condition if the user attempts to select a font or style that does not exist.

See CHOOSEFONT.

CF_INITTOLOGFONTSTRUCT

Specifies the ChooseFont function should use the LOGFONT structure, pointed to by lpLogFont, to initialize the dialog controls.

See CHOOSEFONT.

CF_LIMITSIZE

Specifies the ChooseFont function should only select font sizes within the range specified by the nSizeMin and nSizeMax fields.

See CHOOSEFONT.

CF_METAFILEPICT

Handle to 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 hData should also free the metafile referred to by the CF_METAFILEPICT handle.

See SetClipboardData.

CF_NOFACESEL

Specifies the ChooseFont function should not allow facename selections.

See CHOOSEFONT.

CF_NOOEMFONTS

See CF_NOVECTORFONTS description.

See CHOOSEFONT.

CF_NOSIMULATIONS

Specifies the ChooseFont function should not allow GDI font simulations.

See CHOOSEFONT.

CF_NOSIZESEL

Specifies the ChooseFont function should not allow size selections.

See CHOOSEFONT.

CF_NOSTYLESEL

Specifies the ChooseFont function should not allow style selections.

See CHOOSEFONT.

CF_NOVECTORFONTS

Specifies the ChooseFont function should not allow vector-font selections.

See CHOOSEFONT.

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.

See SetClipboardData.

CF_OWNERDISPLAY

Owner display format. The clipboard owner must display and update the clipboard viewer window, and will receive the messages WM_ASKCBFORMATNAME, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, WM_SIZECLIPBOARD, and WM_VSCROLLCLIPBOARD. The hData parameter must be NULL.

See SetClipboardData.

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

See SetClipboardData.

CF_PENDATA

Data for the pen extensions to the Windows operating system.

See SetClipboardData.

CF_PRINTERFONTS

Causes the dialog box to only list the fonts supported by the printer associated with device context (or information context) identified by the hDC member.

See CHOOSEFONT.

CF_PRIVATEFIRST

Beginning of range (ending at CF_PRIVATELAST) of integer values for private clipboard formats. Handles associated with private clipboard formats are not automatically freed; the clipboard owner must free such data handles, typically in response to the WM_DESTROYCLIPBOARD message.

See SetClipboardData.

CF_PRIVATELAST

End of range (beginning at CF_PRIVATEFIRST) of integer values for private clipboard formats. Handles associated with private clipboard formats are not automatically freed; the clipboard owner must free such data handles, typically in response to the WM_DESTROYCLIPBOARD message.

See SetClipboardData.

CF_SCALABLEONLY

Specifies the ChooseFont function should only allow the selection of scalable fonts. (Scalable fonts include: vector fonts, scalable printer fonts, TrueType fonts, and fonts scaled by other algorithms or technologies.)

See CHOOSEFONT.

CF_SCREENFONTS

Causes the dialog box to only list the screen fonts supported by the system.

See CHOOSEFONT.

CF_SHOWHELP

Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified.

See CHOOSEFONT.

CF_SYLK

Microsoft symbolic link (SYLK) format.

See SetClipboardData.

CF_TEXT

Text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.

See SetClipboardData.

CF_TIFF

Tag image file format.

See SetClipboardData.

CF_TTONLY

Specifies the ChooseFont function should only enumerate and allow the selection of TrueType fonts.

See CHOOSEFONT.

CF_UNICODETEXT

Unicode text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.

See SetClipboardData.

CF_USESTYLE

Specifies the lpszStyle member points to a buffer that contains style data the ChooseFont function should use to initialize the Font Style selection. When the user dismisses the dialog, the ChooseFont function copies style data for the user's selection to this buffer.

See CHOOSEFONT.

CF_WYSIWYG

Specifies the ChooseFont function should only allow the selection of fonts available on both the printer and the display. If this flag is set, the CF_BOTH and CF_SCALABLEONLY flags should also be set.

See CHOOSEFONT.

CFERR_MAXLESSTHANMIN

Specifies the size specified in the nSizeMax member of the CHOOSEFONT structure is less than the size specified in the nSizeMin member.

See CommDlgExtendedError.

CFERR_NOFONTS

Specifies no fonts exist.

See CommDlgExtendedError.

CLIPCAPS

Flag that indicates the clipping capabilities of the device. If the device can clip to a rectangle, it is 1. Otherwise, it is zero.

See GetDeviceCaps.

COLOR_ACTIVEBORDER

Active window border.

See SetSysColors.

COLOR_ACTIVECAPTION

Active window caption.

See SetSysColors.

COLOR_APPWORKSPACE

Background color of multiple document interface (MDI) applications.

See SetSysColors.

COLOR_BACKGROUND

Desktop.

See SetSysColors.

COLOR_BTNFACE

Face shading on push buttons.

See SetSysColors.

COLOR_BTNSHADOW

Edge shading on push buttons.

See SetSysColors.

COLOR_BTNTEXT

Text on push buttons.

See SetSysColors.

COLOR_CAPTIONTEXT

Text in caption, size box, scroll-bar arrow box.

See SetSysColors.

COLOR_GRAYTEXT

Grayed (disabled) text. This color is set to 0 if the current display driver does not support a solid gray color.

See SetSysColors.

COLOR_HIGHLIGHT

Items selected item in a control.

See SetSysColors.

COLOR_HIGHLIGHTTEXT

Text of item selected in a control.

See SetSysColors.

COLOR_INACTIVEBORDER

Inactive window border.

See SetSysColors.

COLOR_INACTIVECAPTION

Inactive window caption.

See SetSysColors.

COLOR_INACTIVECAPTIONTEXT

Color of text in an inactive caption.

See SetSysColors.

COLOR_MENU

Menu background.

See SetSysColors.

COLOR_MENUTEXT

Text in menus.

See SetSysColors.

COLOR_SCROLLBAR

Scroll-bar gray area.

See SetSysColors.

COLOR_SHADOW

Color of automatic window shadows.

See SetSysColors.

COLOR_WINDOW

Window background.

See SetSysColors.

COLOR_WINDOWFRAME

Window frame.

See SetSysColors.

COLOR_WINDOWTEXT

Text in windows.

See SetSysColors.

COLORONCOLOR

Deletes the pixels. This mode deletes all eliminated lines of pixels without trying to preserve their information.

See SetStretchBltMode.

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 version is 3.0 or later.

See GetDeviceCaps.

COMBOBOX

Designates a control consisting of a list box and a selection field similar to an edit control. Display the list box at all times or drop it down when the user selects a pop-up list box next to the selection field. 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 box will highlight 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.

See CreateWindow.

COMPLEXREGION

Region is more than a single rectangle.

See CombineRgn, ExtSelectClipRgn, GetRgnBox, IntersectClipRect, OffsetClipRgn, SelectClipRgn, SelectObject, SetMetaRgn.

COMPLEXREGION

Region has overlapping borders.

See OffsetRgn.

COMPLEXREGION

The region has overlapping borders.

See ExcludeUpdateRgn.

COMPLEXREGION

Region has overlapping borders.

See ExcludeClipRect.

COMPLEXREGION

Region is more than a single rectangle.

See GetClipBox.

CONNECT_UPDATE_PROFILE

Information about the connection is stored in the user profile.

See WNetAddConnection2, WNetCancelConnection2.

CONTAINER_INHERIT_ACE

The ACE is inherited by containers (for example, subdirectories).

See ACE_HEADER.

CP_ACP

ANSI code page

See GetCPInfo, MultiByteToWideChar, WideCharToMultiByte.

CP_OEMCP

OEM code page

See GetCPInfo, MultiByteToWideChar, WideCharToMultiByte.

CREATE_ALWAYS

Creates a new file. Overwrites the file if it exists.

See CreateFile.

CREATE_NEW

Creates a new file. Fails if the specified file already exists.

See CreateFile.

CREATE_NEW_CONSOLE

The new process will have a new console, instead of inheriting the parent's console. This flag cannot be used with the DETACHED_PROCESS flag.

See CreateProcess.

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 group ID of the new process group is the same as the process ID, which is returned in the lppiProcInfo structure. Process groups are used by the GenerateConsoleCtrlEvent function to enable sending a Ctrl-C or Ctrl-Break signal to a group of console processes.

See CreateProcess.

CREATE_NO_WINDOW

The created process will have a console, but no window. This flag should not be used by application programs. It is intended only for internal use to implement VDM code.

See CreateProcess.

CREATE_PROCESS_DEBUG_EVENT

Reports a create process debugging event. The value of u.CreateProcess specifies a CREATE_PROCESS_DEBUG_INFO structure.

See DEBUG_EVENT.

CREATE_SUSPENDED

The thread is created in a suspended state, and will not run until the ResumeThread function is called.

See CreateProcess, CreateThread.

CREATE_THREAD_DEBUG_EVENT

Reports a create thread debugging event. The value of u.CreateThread specifies a CREATE_THREAD_DEBUG_INFO structure.

See DEBUG_EVENT.

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.

See WNDCLASS.

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.

See WNDCLASS.

CS_CLASSDC

Allocates one device context (DC) to be shared by all windows in the class. Because Window classes are process-specific, it is possible for multiple threads of a multi-threaded application to create a window of the same class. It is also possible for the threads to attempt to use the DC simultaneously. When this happens, the system allows only one of the threads to successfully complete its drawing operation.

See WNDCLASS.

CS_DBLCLKS

Instructs Windows to send 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.

See WNDCLASS.

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 DLL and listing the name of the DLL in the registration database under the following keys: Whenever a process starts, the 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.

See WNDCLASS.

CS_GREEK

Supports the Greek character set.

See CHARSET.

CS_HREDRAW

Specifies that the entire window is to be redrawn if a movement or size adjustment changes the width of the client area.

See WNDCLASS.

CS_LATIN

Supports the Latin character set.

See CHARSET.

CS_NOCLOSE

Disables the Close command on the System menu.

See WNDCLASS.

CS_OWNDC

Allocates a unique device context for each window in the class.

See WNDCLASS.

CS_PARENTDC

Gives the parent window's device context to the child windows. Specifying CS_PARENTDC enhances an application's performance. When an application calls the GetDC function, passing the handle of a window that belongs to a class with the CS_PARENTDC style, the system searches for a device context that has been precalculated for the window's parent window. If all child windows of a particular parent window specify this style, the system need not recalculate a device context for any of the child windows.

See WNDCLASS.

CS_SAVEBITS

Saves, as a bitmap, the portion of the screen image that is 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 that had been 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 that you display briefly and then remove before other screen activity takes place (for example, menus or dialog boxes). This style increases the time required to display the window since the system must first allocate memory to store the bitmap.

See WNDCLASS.

CS_UGL

Supports the UGL character set.

See CHARSET.

CS_VREDRAW

Specifies that the entire window is to be redrawn if a movement or size adjustment changes the height of the client area.

See WNDCLASS.

CS_WIN30

Supports the Windows 3.0 character set.

See CHARSET.

CTRL_BREAK_EVENT

Generate Ctrl-Break signal

See GenerateConsoleCtrlEvent.

CTRL_C_EVENT

Generate Ctrl-C signal

See GenerateConsoleCtrlEvent.

CURVECAPS

A bitmask that indicates the curve capabilities of the device. The bits have the following meanings:

See GetDeviceCaps.

DACL_SECURITY_INFORMATION

When set, this bit indicates the discretionary access-control list of the object is being referenced.

See SECURITY_INFORMATION.

DC_BINNAMES

Specifies that the function enumerates the paper bins on the given device. If a device driver supports this constant, the array identified by lpOutput contains a data structure that contains two members. The first member is an array identifying valid paper bins: The second member is an array of characters strings specifying the bin names: If a device driver does not support this value, the array identified by lpOutput is empty and the return value is NULL. If lpOutput is NULL, the return value specifies the number of bins supported.

See DeviceCapabilities.

DC_BINS

Specifies that the function retrieves a list of constants that identify the available bins. The function copies the list to the array identified by lpOutput. If this array is NULL, the function returns the number of supported bins. The following list contains the bin identifiers which may be returned:

See DeviceCapabilities.

DC_DRIVER

Specifies that the function returns the driver version number.

See DeviceCapabilities.

DC_DUPLEX

Specifies that the funciton returns the level of duplex support. The return value is 1 if the function supports duplex output; otherwise it is zero.

See DeviceCapabilities.

DC_ENUMRESOLUTIONS

Specifies that the function returns a list of available printer resolutions in the array identified by lpOutput. The resolutions are returned as pairs of LONG integers; the first value of the pair specifies the horizontal resolution and the second value specifies the vertical resolution. If lpOutput is NULL, the function returns the number of supported resolutions.

See DeviceCapabilities.

DC_EXTRA

Specifies that the function returns the number of bytes required for the device-specific data that is appended to the DEVMODE structure.

See DeviceCapabilities.

DC_FIELDS

Specifies that the function returns a value indicating which members of the DEVMODE structure are set by the device driver. This value can be one or more of the following constants:

See DeviceCapabilities.

DC_FILEDEPENDENCIES

Specifies that the function returns a list of files that must be loaded when the device driver is installed. If lpOutput is NULL and this value is specified, the function returns the number of filenames that must be loaded. If lpOutput is a valid pointer, the function returns the specified number of 64-character filenames.

See DeviceCapabilities.

DC_MAXEXTENT

Specifies that the function returns the maximum supported paper-size. These dimensions are returned in a POINT structure; the x member of this structure specifies the maximum paper width and the y member of this structure specifies the maximum paper length.

See DeviceCapabilities.

DC_MINEXTENT

Specifies that the function returns the minimum supported paper-size. These dimensions are returned in a POINT structure; the x member of this structure specifies the minimum paper width and the y member of this structure specifies the minimum paper length.

See DeviceCapabilities.

DC_PAPERS

Specifies that the function returns a list of supported paper sizes. The paper sizes are returned in the array at which lpOutput points. The function return value specifies the number of sizes identified in the array. If lpOutput is NULL, the function returns the number of supported paper sizes.

See DeviceCapabilities.

DC_PAPERSIZE

Specifies that the function returns the supported paper sizes in the array at which lpOutput points. These dimensions are specified in .1 millimeter units.

See DeviceCapabilities.

DC_SIZE

Specifies that the function returns the size of the DEVMODE structure that is required by the device driver.

See DeviceCapabilities.

DC_VERSION

Specifies that the function returns a version number that identifies the specification to which the device driver conforms.

See DeviceCapabilities.

DCB_ACCUMULATE

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

See SetBoundsRect.

DCB_DISABLE

Bounds accumulation is off. DCB_DISABLE Turn off bounds accumulation. DCB_DISABLE Bounds accumulation is off.

See GetBoundsRect, SetBoundsRect.

DCB_ENABLE

Bounds accumulation is on. DCB_ENABLE and DCB_DISABLE are mutually exclusive.

See GetBoundsRect, SetBoundsRect.

DCB_RESET

Clear the bounding rectangle after returning it.

See GetBoundsRect, SetBoundsRect.

DCB_SET

The bounds rectangle is not empty. DCB_SET and DCB_RESET are mutually exclusive.

See GetBoundsRect, SetBoundsRect.

DCB_WINDOWMGR

Return the Windows bounding rectangle. If this value is not given, the function returns the bounding rectangle associated with the application.

See GetBoundsRect.

DCTT_BITMAP

A device is capable of printing TrueType fonts as graphics. (For example, dot-matrix and PCL printers.)

See DeviceCapabilities.

DCTT_DOWNLOAD

A device is capable of downloading TrueType fonts. (For example, PCL and PostScript printers.)

See DeviceCapabilities.

DCTT_SUBDEV

Device is capable of substituting device fonts for TrueType fonts. (For example, PostScript printers.)

See DeviceCapabilities.

DCX_CACHE

Returns a DC from the cache, rather than the OWNDC or CLASSDC window. Essentially overrides CS_OWNDC and CS_CLASSDC.

See GetDCEx.

DCX_CLIPCHILDREN

Exclude the visible regions of all child windows below the window specified by the hwnd parameter.

See GetDCEx.

DCX_CLIPSIBLINGS

Exclude the visible regions of all sibling windows above the window specified by the hwnd parameter.

See GetDCEx.

DCX_DEFAULTCLIP

Returns a DC by using the default clipping flags specified by WS_CLIPCHILDREN, WS_CLIPSIBLINGS, and CS_PARENTDC.

See GetDCEx.

DCX_EXCLUDERGN

The clip region specified by the hrgnClip is excluded from the visible region of the returned DC.

See GetDCEx.

DCX_INTERSECTRGN

The clip region specified by the hrgnClip parameter is intersected with the visible region of the returned DC.

See GetDCEx.

DCX_LOCKWINDOWUPDATE

Allow drawing even if there is a LockWindowUpdate() call in effect that would otherwise exclude this window. Used for drawing during tracking.

See GetDCEx.

DCX_NORECOMPUTE

If an exact match in the cache is not found, return NULL rather than creating a new DC. When used with DCX_NORESETATTRS, this gives applications a way to determine whether they need to reselect any special attributes.

See GetDCEx.

DCX_NORESETATTRS

Do not reset the attributes of this DC to the default attributes when this DC is released.

See GetDCEx.

DCX_PARENTCLIP

Use the visible region of the parent window. The parent's WS_CLIPCHILDREN and CS_PARENTDC style bits are ignored. The DC origin is set to the upper left corner of the the window specified by the hwnd parameter.

See GetDCEx.

DCX_VALIDATE

When specified with DCX_INTERSECTUPDATE, this flag causes the DC to be completely validated. Using this function with both DCX_INTERSECTUPDATE and DCX_VALIDATE is identical to using the BeginPaint function.

See GetDCEx.

DCX_WINDOW

Returns a DC corresponding to the window rectangle rather than the client rectangle.

See GetDCEx.

DDD_EXACT_MATCH_ON_REMOVE

If set, along with DDD_REMOVE_DEFINITION, then DefineDosDevice uses an exact match to determine which mapping to remove. Use this flag to insure that you don't delete something that you did not define.

See DefineDosDevice.

DDD_RAW_TARGET_PATH

If specified, DefineDosDevice does not convert the lpTargetPath string from a DOS path to an NT path, but takes it as is.

See DefineDosDevice.

DDD_REMOVE_DEFINITION

If specified, DefineDosDevice removes the specified definition for the specified device.

See DefineDosDevice.

DDL_ARCHIVE

Includes archived files.

See DlgDirList.

DDL_DIRECTORY

Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).

See DlgDirList.

DDL_DRIVES

Includes drives. Drives are listed in the form [-x-], where x is the drive letter.

See DlgDirList.

DDL_EXCLUSIVE

Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.

See DlgDirList.

DDL_HIDDEN

Includes hidden files.

See DlgDirList.

DDL_POSTMSGS

Posts messages to the application's message queue. By default, the function sends messages directly to the dialog box procedure.

See DlgDirList.

DDL_READONLY

Includes read-only files.

See DlgDirList.

DDL_READWRITE

Includes read-write files with no additional attributes.

See DlgDirList.

DDL_SYSTEM

Includes system files.

See DlgDirList.

DEBUG_ONLY_THIS_PROCESS

If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. If the new process creates additional processes, the kernel will not notify the debugger of any debug events that occur in the additional processes.

See CreateProcess.

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 kernel notifies the debugger of all debug events that occur in the process being debugged. If this flag is not set and the calling process is being debugged, then the new process becomes another process being debugged by the calling process' debugger. If this bit is not set and the calling process is not a process being debugged, no debugging-related actions occur.

See CreateProcess.

DEFAULT_PALETTE

Default color palette. This palette consists of the static colors in the system palette.

See GetStockObject.

DEFAULT_QUALITY

Appearance of the font does not matter.

See CreateFont, LOGFONT.

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.

See NAME_BUFFER.

DETACHED_PROCESS

For console processes, the new process will not have access to the console of the parent process. The new process can call AllocConsole if it later wants to create a new console. This flag cannot be used with the CREATE_NEW_CONSOLE flag.

See CreateProcess.

DEVICE_DEFAULT_FONT

Device-dependent font

See GetStockObject.

DIB_PAL_COLORS

The color table consists of an array of 16-bit indices into the currently selected logical palette.

See CreateDIBitmap, CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateDIBSection, GetDIBits, SetDIBits, SetDIBitsToDevice, StretchDIBits, EXTLOGPEN, LOGBRUSH.

DIB_PAL_INDICES

There is no color table for the bitmap. The bitmap bits are indices into the device's physical palette, (not the currently selected logical palette).

See CreateDIBitmap, CreateDIBPatternBrush, CreateDIBPatternBrushPt, GetDIBits, SetDIBits, SetDIBitsToDevice, StretchDIBits.

DIB_RGB_COLORS

The color table is provided and contains literal RGB values.

See CreateDIBitmap, CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateDIBSection, GetDIBits, SetDIBits, SetDIBitsToDevice, StretchDIBits, EXTLOGPEN, LOGBRUSH.

DKGRAY_BRUSH

Dark gray brush

See GetStockObject.

DLGC_BUTTON

Button

See WM_GETDLGCODE.

DLGC_DEFPUSHBUTTON

Default push button

See WM_GETDLGCODE.

DLGC_HASSETSEL

EM_SETSEL messages

See WM_GETDLGCODE.

DLGC_RADIOBUTTON

Radio button

See WM_GETDLGCODE.

DLGC_STATIC

Static control

See WM_GETDLGCODE.

DLGC_UNDEFPUSHBUTTON

Non-default push button

See WM_GETDLGCODE.

DLGC_WANTALLKEYS

All keyboard input

See WM_GETDLGCODE.

DLGC_WANTARROWS

DIRECTION keys

See WM_GETDLGCODE.

DLGC_WANTCHARS

WM_CHAR messages

See WM_GETDLGCODE.

DLGC_WANTMESSAGE

All keyboard input (the application passes this message on to control)

See WM_GETDLGCODE.

DLGC_WANTTAB

TAB key

See WM_GETDLGCODE.

DM_INTERLACED

Specifies that the display mode is interlaced. If the flag is not set, NON-interlaced is assumed.

See DEVMODE.

DMLERR_ADVACKTIMEOUT

A request for a synchronous advise transaction has timed out.

See DdeGetLastError.

DMLERR_BUSY

The response to the transaction caused the DDE_FBUSY bit to be set.

See DdeGetLastError.

DMLERR_DATAACKTIMEOUT

A request for a synchronous data transaction has timed out.

See DdeGetLastError.

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.

See DdeGetLastError.

DMLERR_DLL_USAGE

An application initialized as APPCLASS_MONITOR has attempted to perform a DDE transaction, or an application initialized as APPCMD_CLIENTONLY has attempted to perform server transactions.

See DdeGetLastError.

DMLERR_EXECACKTIMEOUT

A request for a synchronous execute transaction has timed out.

See DdeGetLastError.

DMLERR_INVALIDPARAMETER

A parameter failed to be validated by the DDEML. Some of the possible causes are as follows: The application used a data handle initialized with a different item-name handle than required by the transaction. The application used a data handle that was initialized with a different clipboard data format than required by the transaction. The application used a client-side conversation handle with a server-side function or vise versa. The application used a freed data handle or string handle. More than one instance of the application used the same object.

See DdeGetLastError.

DMLERR_LOW_MEMORY

Memory is low--advise, poke, or execute data may be lost, or the system may fail.

See XTYP_ERROR.

DMPAPER_A4

210-by-297-millimeter paper

See DEVMODE.

DMPAPER_CSHEET

17-by-22-inch paper

See DEVMODE.

DMPAPER_DSHEET

22-by-34-inch paper

See DEVMODE.

DMPAPER_ENV_10

4 1/8 short dm 8 -by-9 1/5 short dm 8 -inch #10 envelope

See DEVMODE.

DMPAPER_ENV_11

4 1/2 short dm 8 -by-10 3/8 short dm 8 -inch #11 envelope

See DEVMODE.

DMPAPER_ENV_12

4 3/4 short dm 8 -by-11-inch #12 envelope

See DEVMODE.

DMPAPER_ENV_14

5-by-11 1/2 short dm 8 -inch #14 envelope

See DEVMODE.

DMPAPER_ENV_9

3 7/8 short dm 8 -by-8 7/8 short dm 8 -inch #9 envelope

See DEVMODE.

DMPAPER_ESHEET

34-by-44-inch paper

See DEVMODE.

DMPAPER_LEGAL

8 1/2 short dm 8 -by-14-inch paper

See DEVMODE.

DMPAPER_LETTER

8 1/2 short dm 8 -by-11-inch paper

See DEVMODE.

DMTT_BITMAP

Prints TrueType fonts as graphics. This is the default action for dot-matrix printers.

See DEVMODE.

DMTT_DOWNLOAD

Downloads TrueType fonts as soft fonts. This is the default action for Hewlett-Packard printers that use Printer Control Language (PCL).

See DEVMODE.

DMTT_SUBDEV

Substitute device fonts for TrueType fonts. This is the default action for PostScript® printers.

See DEVMODE.

DNS_FILTEROFF

Turns off service-name initiation filtering. If this flag is set, the server receives an XTYP_CONNECT transaction whenever another DDE application calls the DdeConnect function, regardless of the service name.

See DdeNameService.

DNS_FILTERON

Turns on service-name initiation filtering. This 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.

See DdeNameService.

DNS_REGISTER

Registers the given service name.

See DdeNameService.

DNS_UNREGISTER

Unregisters the given service name. If the hsz1 parameter is NULL, all service names registered by the server will be unregistered.

See DdeNameService.

DOUBLE_CLICK

Indicates the second click (button press) of a double click. The first click is returned as a regular button-press event.

See MOUSE_EVENT_RECORD.

DRAFT_QUALITY

Appearance of the font is less important than when the PROOF_QUALITY value is used. For GDI raster fonts, scaling is enabled. Bold, italic, underline, and strikeout fonts are synthesized if necessary.

See CreateFont, LOGFONT.

DRIVE_CDROM

Drive is a CD ROM drive.

See GetDriveType.

DRIVE_FIXED

Disk cannot be removed from the drive.

See GetDriveType.

DRIVE_RAMDISK

Drive is a RAM disk.

See GetDriveType.

DRIVE_REMOTE

Drive is a remote (network) drive.

See GetDriveType.

DRIVE_REMOVABLE

Disk can be removed from the drive.

See GetDriveType.

DS_ABSALIGN

Specifies that the dialog box position is relative to the upper-left corner of the screen. If this style is not given, the position is relative to the upper-left corner of the owner window's client area.

See CreateWindow, DLGTEMPLATE.

DS_LOCALEDIT

Applies to 16-bit applications only. 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.

See CreateWindow.

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.

See CreateWindow, DLGTEMPLATE.

DS_NOIDLEMSG

Suppresses WM_ENTERIDLE messages that Windows would otherwise send to the owner of the dialog box while the dialog box is displayed.

See CreateWindow, DLGTEMPLATE.

DS_SETFONT

Indicates the dialog-box template (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_SETFONT Specifies that a font other than the system font is to be used to draw text in the dialog box and its controls. If this value is given, the dialog box template must specify a point size and typeface name as described in the "Comments" section.

See CreateWindow, DLGTEMPLATE.

DS_SETFOREGROUND

Specifies that the application creating the dialog box is to be made the foreground task. Windows calls the SetForegroundWindow function to set the foreground task.

See CreateWindow, DLGTEMPLATE.

DS_SYSMODAL

Creates a system-modal dialog box.

See CreateWindow.

DSTINVERT

Inverts the destination rectangle or bitmap.

See BitBlt, PatBlt.

DT_BOTTOM

Specifies bottom-justified text. This value must be combined with DT_SINGLELINE.

See DrawText.

DT_CALCRECT

Determines the width and height of the rectangle. If there are multiple lines of text, DrawText will use the width of the rectangle pointed to by the lprc parameter and extend the base of the rectangle to bound the last line of text. If there is only one line of text, DrawText will modify 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.

See DrawText.

DT_CENTER

Centers text horizontally.

See DrawText.

DT_CHARSTREAM

Character stream

See GetDeviceCaps.

DT_DISPFILE

Display file

See GetDeviceCaps.

DT_EXPANDTABS

Expands tab characters. The default number of characters per tab is eight.

See DrawText.

DT_EXTERNALLEADING

Includes the font external leading in line height. Normally, external leading is not included in the height of a line of text.

See DrawText.

DT_LEFT

Aligns text to the left.

See DrawText.

DT_METAFILE

Metafile

See GetDeviceCaps.

DT_NOCLIP

Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is used.

See DrawText.

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.

See DrawText.

DT_PLOTTER

Vector plotter

See GetDeviceCaps.

DT_RASCAMERA

Raster camera

See GetDeviceCaps.

DT_RASDISPLAY

Raster display

See GetDeviceCaps.

DT_RASPRINTER

Raster printer

See GetDeviceCaps.

DT_RIGHT

Aligns text to the right.

See DrawText.

DT_SINGLELINE

Specifies single line only. Carriage returns and linefeeds do not break the line.

See DrawText.

DT_TABSTOP

Sets tab stops. Bits 15-8 (high-order byte of the low-order word) of the wFormat parameter is the number of characters for each tab. The default number of characters per tab is eight.

See DrawText.

DT_TOP

Specifies top-justified text (single line only).

See DrawText.

DT_VCENTER

Specifies vertically centered text (single line only).

See DrawText.

DT_WORDBREAK

Specifies word breaking. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lprc parameter. A carriage return/linefeed sequence will also break the line.

See DrawText.

DTR_CONTROL_DISABLE

Disable the DTR line on device open and leave it disabled.

See DCB.

DTR_CONTROL_ENABLE

Enable the DTR line on device open and leave it on.

See DCB.

DTR_CONTROL_HANDSHAKE

Enable DTR handshaking. Note that if handshaking is enabled, it is an error for the application to adjust the line using the EscapeCommFunction function.

See DCB.

DUPLICATE

A duplicate name was detected during registration.

See NAME_BUFFER.

DUPLICATE_CLOSE_SOURCE

Close the source handle. This occurs regardless of any error status returned.

See DuplicateHandle.

DUPLICATE_DEREG

A duplicate name was detected with a pending deregistration.

See NAME_BUFFER.

DUPLICATE_SAME_ACCESS

Ignore the fdwAccess parameter. The duplicate handle has the same access as the source handle.

See DuplicateHandle.

DWL_DLGPROC

Specifies the address of the dialog box procedure.

See GetWindowLong, SetWindowLong.

DWL_MSGRESULT

Specifies the return value of a message processed in the dialog box procedure.

See GetWindowLong, SetWindowLong.

DWL_USER

Specifies extra information that is private to the application, such as handles or pointers.

See GetWindowLong, SetWindowLong.

EC_DISABLE

Disables all blockable transactions for the specified conversation. A server application can disable the following transactions: A client application can disable the following transactions:

See DdeEnableCallback.

EC_ENABLEALL

Enables all transactions for the specified conversation.

See DdeEnableCallback.

EC_ENABLEONE

Enables one transaction for the specified conversation.

See DdeEnableCallback.

EC_QUERYWAITING

Determines whether any transactions are in the queue for the specified conversation.

See DdeEnableCallback.

EDIT

Designates a rectangular child window in 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 control displays a flashing caret. The mouse can be used to move the cursor, select characters to be replaced, or position the cursor for inserting characters. The BACKSPACE key can be used to delete characters. Edit controls use the variable-pitch system font and display characters from the Windows character set. Applications compiled to run with earlier versions of Windows display text with a fixed-pitch system font unless they have been marked by the Windows 3.0 MARK utility (specified with the MEMORY FONT option). You can also send the WM_SETFONT message 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.

See CreateWindow.

ENABLE_ECHO_INPUT

Characters read by ReadFile or ReadConsole are written to the screen as they are read. Can only be used if ENABLE_LINE_INPUT is also enabled.

See GetConsoleMode.

ENABLE_LINE_INPUT

ReadFile or ReadConsole return only when a CR (carriage return) character is read. If disabled, ReadFile or ReadConsole return when one or more characters are available.

See GetConsoleMode.

ENABLE_MOUSE_INPUT

Mouse events generated by mouse movement and button presses are placed in the input buffer, if the mouse pointer is within the borders of the console window and the window has the keyboard focus. These events are discarded by ReadFile or ReadConsole, even when ENABLE_MOUSE_INPUT is enabled.

See GetConsoleMode.

ENABLE_PROCESSED_INPUT

Ctrl-C is processed by the system and 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 not returned in the ReadFile or ReadConsole buffer. If ENABLE_LINE_INPUT is also enabled, BKSP (backspace), CR (carriage return), and LF (linefeed) are handled by the system.

See GetConsoleMode.

ENABLE_PROCESSED_OUTPUT

Characters written by WriteFile or WriteConsole or echoed by ReadFile or ReadConsole are parsed for ASCII control sequences and the correct action is performed. BKSP (backspace), TAB, bell, CR (carriage return) and LF (linefeed) characters are processed.

See GetConsoleMode.

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 ReadConsoleInput, but not by those using ReadFile or ReadConsole.

See GetConsoleMode.

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 line when it reaches the end of the current row. This can result in scrolling the lines displayed in the window, or in scrolling the contents of the screen buffer and discarding the top line (when the cursor goes beyond the bottom, right cell). If disabled, the last character in the row is overwritten.

See GetConsoleMode.

ENHANCED_KEY

The key is enhanced.

See KEY_EVENT_RECORD.

ERROR

Error occurred.

See CombineRgn, ExtSelectClipRgn, IntersectClipRect, OffsetClipRgn, SelectClipRgn, SetMetaRgn.

ESB_DISABLE_BOTH

Disables both arrows on a scroll bar.

See EnableScrollBar.

ESB_DISABLE_LTUP

Disables the left arrow on a horizontal scroll bar or the up arrow of a vertical scroll bar.

See EnableScrollBar.

ESB_DISABLE_RTDN

Disables the right arrow on a horizontal scroll bar or the down arrow of a vertical scroll bar.

See EnableScrollBar.

ESB_ENABLE_BOTH

Enables both arrows on a scroll bar.

See EnableScrollBar.

ETO_CLIPPED

Each string will be clipped to its given rectangle.

See ExtTextOut, POLYTEXT.

ETO_DELTAVECTOR

Each string is accompanied by an array of character widths, as in ExtTextOut.

See POLYTEXT.

ETO_OPAQUE

Specifies that the current background color should be used to fill the rectangle.

See ExtTextOut, POLYTEXT.

EVENPARITY

Even parity.

See DCB.

EVENTLOG_AUDIT_FAILURE

Security audit failure

See ReportEvent.

EVENTLOG_AUDIT_SUCCESS

Security audit success

See ReportEvent.

EVENTLOG_BACKWARDS_READ

Specifies that the log is read in reverse chronological order.

See ReadEventLog.

EVENTLOG_ERROR_TYPE

Error event

See ReportEvent.

EVENTLOG_FORWARDS_READ

Specifies that the log is read in forward chronological order.

See ReadEventLog.

EVENTLOG_INFORMATION_TYPE

Information event

See ReportEvent.

EVENTLOG_SEEK_READ

Specifies that the read operation proceeds from the record specified by dwRecordNumber. If this flag is used, fdwRead must also specify either EVENTLOG_FORWARDS_READ or EVENTLOG_BACKWARDS_READ. If the buffer is large enough, more than one record may be read at the specified seek position; the additional flag indicates the direction for successive read operations.

See ReadEventLog.

EVENTLOG_SEQUENTIAL_READ

Specifies that the read operation proceeds sequentially from the last call to the ReadEventLog function using this handle.

See ReadEventLog.

EVENTLOG_WARNING_TYPE

Warning event

See ReportEvent.

EWX_FORCE

Forces processes to terminate. Instead of bringing up the "application not responding" dialog for the user, this flag forces an application to terminate if it does not respond.

See ExitWindowsEx.

EWX_LOGOFF

Logoff the user. Involves shutting down all processes running in the security context of the process which called ExitWindowsEx. It then logs the user off.

See ExitWindowsEx.

EWX_REBOOT

Shuts down the system and then reboots the system. The application must have the SE_SHUTDOWN_NAME privilege (see the Comments section for details).

See ExitWindowsEx.

EWX_SHUTDOWN

Shuts down the system to a point where it is safe to turn off the power. All file buffers have been flushed to disk, and all running processes have stopped. The application must have the SE_SHUTDOWN_NAME privilege (see the Comments section for details).

See ExitWindowsEx.

EXCEPTION_CONTINUE_EXECUTION

Execution was continued at the instruction that caused the exception. This typically occurs after an exception handler modifies the context record so that the faulting instruction does not fail again.

See UnhandledExceptionFilter.

EXCEPTION_CONTINUE_SEARCH

The process is being debugged, so this exception should be passed (as second chance) to the application's debugger.

See UnhandledExceptionFilter.

EXCEPTION_DEBUG_EVENT

Reports an exception debugging event. The value of u.Exception specifies an EXCEPTION_DEBUG_INFO structure.

See DEBUG_EVENT.

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.

See UnhandledExceptionFilter.

EXIT_PROCESS_DEBUG_EVENT

Reports an exit process debugging event. The value of u.ExitProcess specifies an EXIT_PROCESS_DEBUG_INFO structure.

See DEBUG_EVENT.

EXIT_THREAD_DEBUG_EVENT

Reports an exit thread debugging event. The value of u.ExitThread specifies an EXIT_THREAD_DEBUG_INFO structure.

See DEBUG_EVENT.

FAILED_ACCESS_ACE_FLAG

Used with system-audit and system-alarm ACEs to indicate that a message is generated for failed access attempts.

See ACE_HEADER.

FALT

The ALT key must be held down when the accelerator key is pressed.

See ACCEL.

FCONTROL

The CONTROL key must be held down when the accelerator key is pressed.

See ACCEL.

FF_DECORATIVE

Novelty fonts. Old English, for example.

See CreateFont, LOGFONT.

FF_DONTCARE

Don't care or don't know.

See CreateFont, LOGFONT.

FF_MODERN

Fonts with constant stroke width (fixed-pitch), with or without serifs. Fixed-pitch fonts are usually modern. Pica, Elite, and Courier, for example.

See CreateFont, LOGFONT.

FF_ROMAN

Fonts with variable stroke width (proportionally spaced) and with serifs. Times Roman, Palatino, and Century Schoolbook, for example.

See CreateFont, LOGFONT.

FF_SCRIPT

Fonts designed to look like handwriting. Script and Cursive, for example.

See CreateFont, LOGFONT.

FF_SWISS

Fonts with variable stroke width (proportionally spaced) and without serifs. Helvetica and Swiss(TM), for example.

See CreateFont, LOGFONT.

FILE_ATTRIBUTE_ARCHIVE

The file is an archive file. Applications use this flag to mark files for backup or removal.

See CreateFile, GetFileAttributes.

FILE_ATTRIBUTE_ATOMIC_WRITE

Reserved for future use. Do not specify.

See CreateFile, GetFileAttributes.

FILE_ATTRIBUTE_DIRECTORY

The file is a directory.

See GetFileAttributes.

FILE_ATTRIBUTE_HIDDEN

The file is hidden. It will not be included in an ordinary directory listing.

See CreateFile, GetFileAttributes.

FILE_ATTRIBUTE_NORMAL

The file has no other attributes set. This attribute is valid only if used alone.

See CreateFile, GetFileAttributes.

FILE_ATTRIBUTE_READONLY

The file is read-only. Applications can read the file, but cannot write to it or delete it.

See CreateFile, GetFileAttributes.

FILE_ATTRIBUTE_SYSTEM

The file is part of or used exclusively by the operating system.

See CreateFile, GetFileAttributes.

FILE_ATTRIBUTE_TEMPORARY

The file is a temporary file. 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.

See CreateFile, GetFileAttributes.

FILE_ATTRIBUTE_XACTION_WRITE

Reserved for future use. Do not specify.

See CreateFile, GetFileAttributes.

FILE_BEGIN

The starting point is zero or the beginning of the file. If FILE_BEGIN is specified, then DistanceToMove is interpreted as an unsigned location for the new file pointer.

See SetFilePointer.

FILE_CURRENT

The current value of the file pointer is the starting point.

See SetFilePointer.

FILE_END

The current end-of-file position is the starting point.

See SetFilePointer.

FILE_FLAG_BACKUP_SEMANTICS

Indicates that the file is being opened or created for a backup or restore operation. The system should ensure that the caller overrides file security checks, provided that the caller has permission to do so.

See CreateFile.

FILE_FLAG_DELETE_ON_CLOSE

Indicates that the system should immediately delete the file after all of its handles have been closed.

See CreateFile.

FILE_FLAG_NO_BUFFERING

Indicates that the file is to be opened with no intermediate buffering or caching done by the system. Reads and writes to the file must be done on sector boundaries. Buffer addresses for reads and writes must be aligned on disk sector boundaries in memory. You can determine sector size with the GetDiskFreeSpace function.

See CreateFile.

FILE_FLAG_OVERLAPPED

Instructs the system to initialize the file so that ReadFile, WriteFile, ConnectNamedPipe, and TransactNamedPipe operations which take a significant time to process return ERROR_IO_PENDING. When the operation is finished, an event is set to the signaled state. When FILE_FLAG_OVERLAPPED is specified, the system does not maintain the file pointer. The file position must be passed as part of the OVERLAPPED structure argument to ReadFile and WriteFile. If this flag is specified, the ReadFile and WriteFile functions must specify an OVERLAPPED structure. This flag also enables more than one operation to be simultaneously performed with the handle (a simultaneous read and write, for example).

See CreateFile.

FILE_FLAG_POSIX_SEMANTICS

Indicates that the file should be accessed according to POSIX rules. This includes allowing multiple files with the same name, differing only in case, for file systems that support such naming. Developers must use care when using this option because files created with this flag may not be accessible from DOS, Win16, or Win32 applications.

See CreateFile.

FILE_FLAG_RANDOM_ACCESS

Indicates that the file is accessed randomly. The Win32 API uses this flag to optimize file caching.

See CreateFile.

FILE_FLAG_SEQUENTIAL_SCAN

Indicates that the file is to be accessed sequentially from beginning to end; the file pointer is not moved. The Win32 API uses this flag to optimize file caching. If an application moves the file pointer, optimum caching cannot occur.

See CreateFile.

FILE_FLAG_WRITE_THROUGH

Instructs the system to always write through any intermediate cache and go directly to the file. The system can still cache writes, but cannot lazily flush the writes.

See CreateFile.

FILE_MAP_ALL_ACCESS

Same as FILE_MAP_WRITE.

See DuplicateHandle, MapViewOfFile, MapViewOfFileEx.

FILE_MAP_COPY

Copy-on-write access. A copy-on-write view of the file is mapped.

See MapViewOfFile, MapViewOfFileEx

FILE_MAP_READ

Read-only access. A read-only view of the file is mapped.

See DuplicateHandle, MapViewOfFile, MapViewOfFileEx.

FILE_MAP_WRITE

Read and write access. A read and write view of the file is mapped.

See DuplicateHandle, MapViewOfFile, MapViewOfFileEx.

FILE_NOTIFY_CHANGE_ATTRIBUTES

Any attribute change in the watched directory or subtree satisfies a change notification wait.

See FindFirstChangeNotification.

FILE_NOTIFY_CHANGE_DIR_NAME

Any directory-name change in the watched directory or subtree satisfies a change notification wait. This includes directory creations and deletions.

See FindFirstChangeNotification.

FILE_NOTIFY_CHANGE_FILE_NAME

Any filename change in the watched directory or subtree satisfies a change notification wait. This includes renames, creations, and deletes.

See FindFirstChangeNotification.

FILE_NOTIFY_CHANGE_LAST_WRITE

Any change to the last write time of files in the watched directory or subtree satisfies a change notification wait. The system detects a change to the last write time only when the last write time changes on disk. For systems with extensive caching this can only occur when the system cache is sufficiently flushed.

See FindFirstChangeNotification.

FILE_NOTIFY_CHANGE_SECURITY

Any security-descriptor change in the watched directory or subtree satisfies a change notification wait.

See FindFirstChangeNotification.

FILE_NOTIFY_CHANGE_SIZE

Any file-size change in the watched directory or subtree satisfies a change notification wait. The system detects a change in file size only when the file size changes on disk. For systems with extensive caching this can only occur when the system cache is sufficiently flushed.

See FindFirstChangeNotification.

FILE_SHARE_READ

Other open operations may be performed on the file or console screen buffer for read access.

See CreateConsoleScreenBuffer, CreateFile.

FILE_SHARE_WRITE

Other open operations may be performed on the file or console screen buffer for write access.

See CreateConsoleScreenBuffer, CreateFile.

FILE_TYPE_CHAR

The specified file is a character file (typically an LPT device or a console).

See GetFileType.

FILE_TYPE_DISK

The specified file is a disk file.

See GetFileType.

FILE_TYPE_PIPE

The specified file is a pipe (either a named or anonymous pipe).

See GetFileType.

FILE_TYPE_UNKNOWN

The type of the specified file is unknown.

See GetFileType.

FLOODFILLBORDER

The fill area is bounded by the color specified by clrref. This style is identical to the filling performed by the FloodFill function.

See ExtFloodFill.

FLOODFILLSURFACE

The fill area is defined by the color that is specified by clrref. Filling continues outward in all directions as long as the color is encountered. This style is useful for filling areas with multicolored boundaries.

See ExtFloodFill.

FMFOCUS_DIR

Directory portion of a directory window

See FM_GETFOCUS.

FMFOCUS_DRIVES

Drive bar of a directory window

See FM_GETFOCUS.

FMFOCUS_SEARCH

Search Results window

See FM_GETFOCUS.

FMFOCUS_TREE

Tree portion of a directory window

See FM_GETFOCUS.

FNERR_BUFFERTOOSMALL

Specifies the buffer for a filename is too small. (This buffer is pointed to by the lpstrFile member of the structure for a common dialog box.)

See CommDlgExtendedError.

FNERR_INVALIDFILENAME

Specifies a filename is invalid.

See CommDlgExtendedError.

FNERR_SUBCLASSFAILURE

Specifies an attempt to subclass a list box failed due to insufficient memory.

See CommDlgExtendedError.

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.

See ACCEL.

FORMAT_MESSAGE_ALLOCATE_BUFFER

Specifies that lpBuffer is the address of a VOID pointer and nSize specifies the minimum number of bytes to allocate for the formatted message. This function will allocate a buffer large enough to hold the formatted message and place a pointer to the buffer at lpBuffer. The caller should use the LocalFree function to free this pointer when it is no longer needed.

See FormatMessage.

FORMAT_MESSAGE_FROM_HMODULE

Specifies that lpSource is a module handle that contains the message table resource or resources to search. If this handle is NULL, the current application's image file will be searched.

See FormatMessage.

FORMAT_MESSAGE_FROM_STRING

Specifies that lpSource is a pointer to a null-terminated message definition that may contain insert sequences.

See FormatMessage.

FORMAT_MESSAGE_FROM_SYSTEM

Specifies that the function should search the system message table resource(s) for the requested message. This flag should only be used if fdwOptions does not include FORMAT_MESSAGE_FROM_STRING or FORMAT_MESSAGE_FROM_HMODULE.

See FormatMessage.

FORMAT_MESSAGE_IGNORE_INSERTS

Specifies that insert sequences in the message definition should be ignored and passed through to the output buffer as is. This flag can be used to fetch a message for later formatting. If this flag is set, the lpArguments parameter is ignored.

See FormatMessage.

FR_DIALOGTERM

Indicates the dialog box is terminating. The window handle returned by the FindText or ReplaceText function is not valid if with flag bit set.

See FINDREPLACE.

FR_DOWN

Determines the direction of searches through a document. If the flag is set, the search direction is down; if the flag is clear, the search direction is up. Initially, this flag specifies the state of the up/down checkbox; after the user closes the dialog, this flag specifies the user's selection.

See FINDREPLACE.

FR_ENABLEHOOK

Enables the hook function specified in the lpfnHook member of this structure. This flag is only used to initialize the dialog.

See FINDREPLACE.

FR_ENABLETEMPLATE

Causes the system to create the dialog box by using the dialog template identified by the hInstance and lpTemplateName members. This flag is only used to initialize the dialog.

See FINDREPLACE.

FR_ENABLETEMPLATEHANDLE

Indicates the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpTemplateName member if this flag is specified.

See FINDREPLACE.

FR_FINDNEXT

Indicates the application should search for the next occurrence of the string specified by the lpstrFindWhat member.

See FINDREPLACE.

FR_HIDEMATCHCASE

Causes the system to hide the Match Case box.

See FINDREPLACE.

FR_HIDEUPDOWN

Causes the system to hide the Direction box and the Up and Down controls.

See FINDREPLACE.

FR_HIDEWHOLEWORD

Causes the system to hide the Match Whole Word Only box.

See FINDREPLACE.

FR_MATCHCASE

Set for case sensitive searches.

See FINDREPLACE.

FR_NOMATCHCASE

Disables the "Match Case" checkbox. This flag is only used to initialize the dialog.

See FINDREPLACE.

FR_NOUPDOWN

Disables the direction radio buttons. This flag is only used to initialize the dialog.

See FINDREPLACE.

FR_NOWHOLEWORD

Disables the "Whole Word" checkbox. This flag is only used to initialize the dialog.

See FINDREPLACE.

FR_REPLACE

Indicates the application should replace the current occurrence of the string specified in the lpstrFindWhat member with the string specified in the lpstrReplaceWith member.

See FINDREPLACE.

FR_REPLACEALL

Indicates the application should replace all occurrences of the string specified in the lpstrFindWhat member with the string specified in the lpstrReplaceWith member.

See FINDREPLACE.

FR_SHOWHELP

Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified.

See FINDREPLACE.

FR_WHOLEWORD

Checks the 'Whole Word' checkbox. Only whole words matching the search string will be considered.

See FINDREPLACE.

FRERR_BUFFERLENGTHZERO

Specifies a member in a structure for the corresponding common dialog box points to an invalid buffer.

See CommDlgExtendedError.

FS_CASE_IS_PRESERVED

The case of filenames is preserved when the name is placed on disk.

See GetVolumeInformation.

FS_CASE_SENSITIVE

The file system supports case sensitive filename lookup.

See GetVolumeInformation.

FS_UNICODE_STORED_ON_DISK

The file system supports Unicode in filenames as they appear on disk.

See GetVolumeInformation.

FSHIFT

The SHIFT key must be held down when the accelerator key is pressed.

See ACCEL.

FVIRTKEY

The key member specifies a virtual-key code. If this flag is not specified, the key is assumed to specify an ASCII character code.

See ACCEL.

FW_BOLD

700

See CreateFont.

FW_DONTCARE

0

See CreateFont.

FW_EXTRABOLD

800

See CreateFont.

FW_EXTRALIGHT

200

See CreateFont.

FW_HEAVY

900

See CreateFont.

FW_LIGHT

300

See CreateFont.

FW_MEDIUM

500

See CreateFont.

FW_NORMAL

400

See CreateFont.

FW_SEMIBOLD

600

See CreateFont.

FW_THIN

100

See CreateFont.

GCL_CBCLSEXTRA

Retrieves or sets the size, in bytes, of the extra memory associated with the class.

See GetClassLong, SetClassLong.

GCL_CBWNDEXTRA

Retrieves or sets 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 the descriptions of the GetWindowLong and GetWindowWord functions.

See GetClassLong, SetClassLong.

GCL_HBRBACKGROUND

Retrieves the handle of the background brush associated with the class.

See GetClassLong, SetClassLong.

GCL_HCURSOR

Retrieves the handle of the cursor associated with the class.

See GetClassLong, SetClassLong.

GCL_HICON

Retrieves the handle of the icon associated with the class.

See GetClassLong, SetClassLong.

GCL_HMODULE

Retrieves the handle of the module that registered the class.

See GetClassLong, SetClassLong.

GCL_MENUNAME

Retrieves the address of the menu-name string. The string identifies the menu resource associated with the class.

See GetClassLong, SetClassLong.

GCL_STYLE

Retrieves the window-class style bits.

See GetClassLong, SetClassLong.

GCL_WNDPROC

Retrieves the address of the window procedure associated with the class.

See GetClassLong, SetClassLong.

GDICOMMENT_IDENTIFIER

Indicates the start of an enhanced metafile public comment.

See GdiComment.

GDICOMMENT_WINDOWS_METAFILE

Indicates an enhanced metafile public comment that contains a Windows-format metafile that is equivalent to the enhanced-format metafile.

See GdiComment.

GDICOMMENT_BEGINGROUP

Indicates an enhanced metafile public comment that identifies the beginning of a group of drawing records. Requires a matching GDICOMMENT_ENDGROUP.

See GdiComment.

GDICOMMENT_ENDGROUP

Indicates an enhanced metafile public comment that identifies the end of a group of drawing records. Requires a matching GDICOMMENT_BEGINGROUP.

See GdiComment.

GDICOMMENT_MULTIFORMATS

Indicates an enhanced metafile public comment that allows multiple definitions of a picture to be included in an enhanced metafile. For example, this comment lets an application include an encapsulated PostScript definition as well as an enhanced metafile definition of a picture.

See GdiComment.

GENERIC_EXECUTE

Specifies execution access. A file can be executed.

GENERIC_READ

Specifies read access to the file or console screen buffer. Data can be read from the file and the file pointer can be moved.

See CreateConsoleScreenBuffer, CreateFile, DuplicateHandle.

GENERIC_WRITE

Write access to the file or console screen buffer is requested. This allows data to be written to the console screen buffer.

See CreateConsoleScreenBuffer, CreateFile, DuplicateHandle.

GET_TAPE_DRIVE_INFORMATION

Retrieve or set information about the tape device.

See GetTapeParameters, SetTapeParameters.

GET_TAPE_MEDIA_INFORMATION

Retrieve information about the tape in the tape device.

See GetTapeParameters.

GRAY_BRUSH

Gray brush

See GetStockObject.

GROUP_NAME

The name specified by the name member was created using the NCBADDGRNAME command.

See NAME_BUFFER.

GROUP_SECURITY_INFORMATION

When set, this bit indicates the primary group ID of the object is being referenced.

See SECURITY_INFORMATION.

GW_CHILD

The retrieved handle identifies the child window at the top of the Z order, if the given window is a parent window; otherwise, the retrieved handle is NULL. The function examines only child windows of the given window. It does not examine descendant windows.

See GetWindow.

GW_HWNDFIRST

The retrieved handle identifies the window at the top of the Z order. If the given window is a topmost window, the handle identifies the topmost window at the top of the Z order. If the given window is a top-level window, the handle identifies the top-level window at the top of the Z order. If the given window is a child window, the handle identifies the sibling window at the bottom of the Z order.

See GetWindow.

GW_HWNDLAST

The retrieved handle identifies the window at the bottom of the Z order. If the given window is a topmost window, the handle identifies the topmost window at the bottom of the Z order. If the given window is a top-level window, the handle identifies the top-level window at the bottom of the Z order. If the given window is a child window, the handle identifies the sibling window at the bottom of the Z order.

See GetWindow.

GW_HWNDNEXT

The retrieved handle identifies the window below the given window in the Z order. If the given window is a topmost window, the handle identifies the topmost window below the given window. If the given window is a top-level window, the handle identifies the top-level window below the given window. If the given window is a child window, the handle identifies the sibling window below the given window.

See GetNextWindow, GetWindow.

GW_HWNDPREV

Returns the handle of the window above the given window. GW_HWNDPREV The retrieved handle identifies the window above the given window in the Z order. If the given window is a topmost window, the handle identifies the topmost window above the given window. If the given window is a top-level window, the handle identifies the top-level window above the given window. If the given window is a child window, the handle identifies the sibling window above the given window.

See GetNextWindow, GetWindow.

GW_OWNER

The retrieved handle identifies the given window's owner window, if any.

See GetWindow.

GWL_EXSTYLE

Retrieves or sets the extended window styles.

See GetWindowLong, SetWindowLong.

GWL_HINSTANCE

Retrieves or sets the handle of the application instance.

See GetWindowLong, SetWindowLong.

GWL_HWNDPARENT

Retrieves the handle of the parent window, if any.

See GetWindowLong.

GWL_ID

Retrieves or sets the identifier of the window.

See GetWindowLong, SetWindowLong.

GWL_STYLE

Retrieves or sets the window styles.

See GetWindowLong, SetWindowLong.

GWL_USERDATA

Retrieves or sets the long value associated with the window. Each window has a corresponding long value intended for use by the application that created the window.

See GetWindowLong, SetWindowLong.

GWL_WNDPROC

Retrieves or sets the address of the window procedure.

See GetWindowLong, SetWindowLong.

HALFTONE

Maps pixels from the source into blocks of pixels in the destination. The average color over the destination block of pixels approximates the color of the source pixels.

See SetStretchBltMode.

HANGUP_COMPLETE

The session was deleted due to a command by the local user.

See SESSION_BUFFER.

HANGUP_PENDING

The session is being deleted due to a command by the local user.

See SESSION_BUFFER.

HC_ACTION

JournalRecordProc: Indicates 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.

KeyboardProc: Indicates the wParam and lParam parameters contain information about a keystroke message.

MouseProc: Indicates the wParam and lParam parameters contain information about a mouse message.

HC_GETNEXT

Indicates the hook procedure must copy the current mouse or keyboard message to the EVENTMSG structure pointed to by the lParam parameter.

See JournalPlaybackProc.

HC_NOREMOVE

KeyboardProc: Indicates 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.)

MouseProc: Indicates 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.)

HC_SKIP

Indicates the hook procedure must prepare to copy the next mouse or keyboard message to the EVENTMSG structure pointed to by the lParam parameter. Upon receiving the HC_GETNEXT code, the hook procedure must copy the message to the structure.

See JournalPlaybackProc.

HC_SYSMODALOFF

Indicates a system-modal dialog box has been destroyed. The hook procedure must resume playing back the messages.

See JournalPlaybackProc, JournalRecordProc.

HC_SYSMODALON

Indicates a system-modal dialog box is being displayed. Until the dialog box is destroyed, the hook procedure must stop recording.

See JournalPlaybackProc, JournalRecordProc.

HCBT_ACTIVATE

Indicates that the system is about to activate a window.

See CBTProc, SetWindowsHook.

HCBT_CLICKSKIPPED

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

See CBTProc, SetWindowsHook.

HCBT_CREATEWND

Indicates 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 nonzero, 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's also possible to change the Z-order of the newly created window by modifying the hwndInsertAfter member of the CBT_CREATEWND structure. HCBT_CREATEWND Indicates that a window is about to be created. The system calls the filter function before sending the WM_CREATE message to the window. If the filter function returns TRUE, the system will destroy the window--the system will not send the WM_DESTROY message to the window.

See CBTProc, SetWindowsHook.

HCBT_DESTROYWND

Indicates that a window is about to be destroyed.

See CBTProc, SetWindowsHook.

HCBT_KEYSKIPPED

Indicates 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 procedure in response to the keyboard message.

See CBTProc, SetWindowsHook.

HCBT_MINMAX

Indicates that a window is about to be minimized or maximized.

See CBTProc, SetWindowsHook.

HCBT_MOVESIZE

Indicates that a window is about to be moved or sized.

See CBTProc, SetWindowsHook.

HCBT_QS

Indicates that the system has retrieved a WM_QUEUESYNC message from the system message queue.

See CBTProc, SetWindowsHook.

HCBT_SETFOCUS

Indicates a window is about to receive the keyboard focus.

See CBTProc.

HCBT_SYSCOMMAND

Indicates that a system command is about to be carried out. This allows a CBT application to prevent task switching by hot keys.

See CBTProc, SetWindowsHook.

HKEY_CLASSES_ROOT

This is a predefined standard registry handle. Registry entries subordinate to this handle define types (or classes) of documents and the properties associated with these classes. This handle is an alias for HKEY_LOCAL_MACHINE, SoftwareClasses.

HKEY_CURRENT_USER

This is a predefined standard registry handle. Registry entries subordinate to this handle contain configuration information specific to the current user. This kind of information was previously stored in the WIN.INI initialization file. This handle is an alias to the profile of the current user, stored under HKEY_USERS.

HKEY_LOCAL_MACHINE

This is a predefined standard registry handle. Registry entries subordinate to this handle define the configuration state of the system, including information about the bus type, system memory, and installed hardware and software.

HKEY_PERFORMANCE_DATA

This is a predefined registry handle that provides access to system performance information.

HKEY_USERS

This is a predefined standard registry handle. Registry entries subordinate to this handle define the default user configuration for users on the local computer and the user configuration for the current user. User profiles appear as subtrees under this handle; the HKEY_CURRENT_USER handle is an alias to the profile of the current user.

HOLLOW_BRUSH

Hollow brush (Equivalent to NULL_BRUSH)

See GetStockObject.

HORZRES

Width of the display, in pixels.

See GetDeviceCaps.

HORZSIZE

Width of the physical display, in millimeters.

See GetDeviceCaps.

HS_BDIAGONAL

45-degree upward hatch (left to right)

See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.

HS_CROSS

Horizontal and vertical cross-hatch

See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.

HS_DIAGCROSS

45-degree crosshatch

See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.

HS_FDIAGONAL

45-degree upward hatch (left to right)

See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.

HS_HORIZONTAL

Horizontal hatch

See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.

HS_VERTICAL

Vertical hatch

See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.

HSHELL_WINDOWCREATED

Indicates a top-level, unowned window has been created. The window exists when the system calls a ShellProc function.

See ShellProc.

HSHELL_WINDOWDESTROYED

Indicates a top-level, unowned window is about to be destroyed. The window still exists when the system calls a ShellProc function.

See ShellProc.

HTBORDER

In the border of a window that does not have a sizing border

See WM_NCHITTEST.

HTBOTTOM

In the lower horizontal border of a window

See WM_NCHITTEST.

HTBOTTOMLEFT

In the lower-left corner of a window border

See WM_NCHITTEST.

HTBOTTOMRIGHT

In the lower-right corner of a window border

See WM_NCHITTEST.

HTCAPTION

In a title bar area

See WM_NCHITTEST.

HTCLIENT

In a client area

See WM_NCHITTEST.

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)

See WM_NCHITTEST.

HTGROWBOX

In a size box (same as HTSIZE)

See WM_NCHITTEST.

HTHSCROLL

In a horizontal scroll bar

See WM_NCHITTEST.

HTLEFT

In the left border of a window

See WM_NCHITTEST.

HTMENU

In a menu area

See WM_NCHITTEST.

HTNOWHERE

On the screen background or on a dividing line between windows

See WM_NCHITTEST.

HTREDUCE

In a Minimize button

See WM_NCHITTEST.

HTRIGHT

In the right border of a window

See WM_NCHITTEST.

HTSIZE

In a size box (same as HTGROWBOX)

See WM_NCHITTEST.

HTSYSMENU

In a System menu or in a Close button in a child window

See WM_NCHITTEST.

HTTOP

In the upper horizontal border of a window

See WM_NCHITTEST.

HTTOPLEFT

In the upper-left corner of a window border

See WM_NCHITTEST.

HTTOPRIGHT

In the upper-right corner of a window border

See WM_NCHITTEST.

HTTRANSPARENT

In a window currently covered by another window

See WM_NCHITTEST.

HTVSCROLL

In the vertical scroll bar

See WM_NCHITTEST.

HTZOOM

In a Maximize button

See WM_NCHITTEST.

HWND_BOTTOM

Places the window at the bottom of the Z order. If hwnd identifies a topmost window, the window loses its topmost status; the system places the window at the bottom of all other windows.

See SetWindowPos.

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.

See SetWindowPos.

HWND_TOP

Places the window at the top of the Z order.

See SetWindowPos.

HWND_TOPMOST

Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated.

See SetWindowPos.

IDABORT

Abort button was selected.

See MessageBox.

IDC_APPSTARTING

Standard arrow and small hourglass

See LoadCursor.

IDC_ARROW

Standard arrow

See LoadCursor.

IDC_CROSS

Crosshair

See LoadCursor.

IDC_IBEAM

Text I-beam

See LoadCursor.

IDC_ICON

Empty icon

See LoadCursor.

IDC_NO

Slashed circle

See LoadCursor.

IDC_SIZE

Four-pointed arrow

See LoadCursor.

IDC_SIZEALL

Same as IDC_SIZE

See LoadCursor.

IDC_SIZENESW

Double-pointed arrow pointing northeast and southwest

See LoadCursor.

IDC_SIZENS

Double-pointed arrow pointing north and south

See LoadCursor.

IDC_SIZENWSE

Double-pointed arrow pointing northwest and southeast

See LoadCursor.

IDC_SIZEWE

Double-pointed arrow pointing west and east

See LoadCursor.

IDC_UPARROW

Vertical arrow

See LoadCursor.

IDC_WAIT

Hourglass

See LoadCursor.

IDCANCEL

No file was undeleted.

See UndeleteFile.

IDCANCEL

Cancel button was selected.

See MessageBox.

IDHOT_SNAPDESKTOP

The 'snap desktop' hot key was pressed.

See WM_HOTKEY.

IDHOT_SNAPWINDOW

The 'snap window' hot key was pressed.

See WM_HOTKEY.

IDI_APPLICATION

Default application icon.

See LoadIcon.

IDI_ASTERISK

Asterisk (used in informative messages).

See LoadIcon.

IDI_EXCLAMATION

Exclamation point (used in warning messages).

See LoadIcon.

IDI_HAND

Hand-shaped icon (used in serious warning messages).

See LoadIcon.

IDI_QUESTION

Question mark (used in prompting messages).

See LoadIcon.

IDIGNORE

Ignore button was selected.

See MessageBox.

IDNO

No button was selected.

See MessageBox.

IDOK

UndeleteFile: A file was undeleted. File Manager will repaint its windows.

MessageBox: OK button was selected.

IDRETRY

Retry button was selected.

See MessageBox.

IDYES

Yes button was selected.

See MessageBox.

INHERIT_ONLY_ACE

The ACE does not apply to the containing object, but is applied to subobjects.

See ACE_HEADER.

JOB_CONTROL_CANCEL

Delete the print job.

See SetJob.

JOB_CONTROL_PAUSE

Pause the print job.

See SetJob.

JOB_CONTROL_RESTART

Restart a print job. A job can only be restarted if it was printing.

See SetJob.

JOB_CONTROL_RESUME

Resume a paused print job.

See SetJob.

JOY_BUTTON1

Set if first joystick button is pressed.

See MM_JOY1MOVE, MM_JOY1ZMOVE, MM_JOY2MOVE, MM_JOY2ZMOVE, JOYINFO.

JOY_BUTTON1CHG

Set if first joystick button has changed.

See MM_JOY1BUTTONDOWN, MM_JOY1BUTTONUP, MM_JOY2BUTTONDOWN, MM_JOY2BUTTONUP.

JOY_BUTTON2

Set if second joystick button is pressed.

See MM_JOY1MOVE, MM_JOY1ZMOVE, MM_JOY2MOVE, MM_JOY2ZMOVE, JOYINFO.

JOY_BUTTON2CHG

Set if second joystick button has changed.

See MM_JOY1BUTTONDOWN, MM_JOY1BUTTONUP, MM_JOY2BUTTONDOWN, MM_JOY2BUTTONUP.

JOY_BUTTON3

Set if third joystick button is pressed.

See MM_JOY1MOVE, MM_JOY1ZMOVE, MM_JOY2MOVE, MM_JOY2ZMOVE, JOYINFO.

JOY_BUTTON3CHG

Set if third joystick button has changed.

See MM_JOY1BUTTONDOWN, MM_JOY1BUTTONUP, MM_JOY2BUTTONDOWN, MM_JOY2BUTTONUP.

JOY_BUTTON4

Set if fourth joystick button is pressed.

See MM_JOY1MOVE, MM_JOY1ZMOVE, MM_JOY2MOVE, MM_JOY2ZMOVE, JOYINFO.

JOY_BUTTON4CHG

Set if fourth joystick button has changed.

See MM_JOY1BUTTONDOWN, MM_JOY1BUTTONUP, MM_JOY2BUTTONDOWN, MM_JOY2BUTTONUP.

JOYERR_NOCANDO

Cannot capture joystick input because some required service (for example, a Windows timer) is unavailable.

See joySetCapture.

JOYERR_PARMS

The specified joystick device ID IDDevice is invalid.

See joyGetDevCaps, joyGetPos, joyGetThreshold, joyReleaseCapture, joySetCapture,  joySetThreshold.

JOYERR_UNPLUGGED

The specified joystick is not connected to the system.

See joyGetPos, joySetCapture.

KEY_ALL_ACCESS

Combines query value, enumerate subkey, notify, create subkey and set value access.

See RegCreateKeyEx.

KEY_CREATE_SUB_KEY

Permission to create subkeys.

See RegCreateKeyEx.

KEY_ENUMERATE_SUB_KEYS

Permission to enumerate subkeys.

See RegCreateKeyEx.

KEY_EXECUTE

Read access.

See RegCreateKeyEx.

KEY_NOTIFY

Change notification will occur.

See RegCreateKeyEx.

KEY_QUERY_VALUE

Permission to query subkey data.

See RegCreateKeyEx.

KEY_READ

Combines query value, enumerate subkey, and notify access.

See RegCreateKeyEx.

KEY_SET_VALUE

Permission to set subkey data.

See RegCreateKeyEx.

KEY_WRITE

Combines set value and create subkey access.

See RegCreateKeyEx.

KEYEVENTF_EXTENDEDKEY

Indicates that a scan code was preceded by a prefix byte having the value 0xE0.

See keybd_event.

KEYEVENTF_KEYUP

Indicates that a key is being released. If not specified, indicates that a key is being depressed.

See keybd_event.

LANG_ALBANIAN

See MAKELANGID.

LANG_ARABIC

See MAKELANGID.

LANG_BAHASA

See MAKELANGID.

LANG_BULGARIAN

See MAKELANGID.

LANG_CATALAN

See MAKELANGID.

LANG_CHINESE

See MAKELANGID.

LANG_CZECH

See MAKELANGID.

LANG_DANISH

See MAKELANGID.

LANG_DUTCH

See MAKELANGID.

LANG_ENGLISH

See MAKELANGID.

LANG_FINNISH

See MAKELANGID.

LANG_FRENCH

See MAKELANGID.

LANG_GERMAN

See MAKELANGID.

LANG_GREEK

See MAKELANGID.

LANG_HEBREW

See MAKELANGID.

LANG_HUNGARIAN

See MAKELANGID.

LANG_ICELANDIC

See MAKELANGID.

LANG_ITALIAN

See MAKELANGID.

LANG_JAPANESE

See MAKELANGID.

LANG_KOREAN

See MAKELANGID.

LANG_NEUTRAL

See MAKELANGID.

LANG_NORWEGIAN

See MAKELANGID.

LANG_POLISH

See MAKELANGID.

LANG_PORTUGUESE

See MAKELANGID.

LANG_RHAETO_ROMAN

See MAKELANGID.

LANG_ROMANIAN

See MAKELANGID.

LANG_RUSSIAN

See MAKELANGID.

LANG_SERBO_CROATIAN

See MAKELANGID.

LANG_SLOVAK

See MAKELANGID.

LANG_SPANISH

See MAKELANGID.

LANG_SWEDISH

See MAKELANGID.

LANG_THAI

See MAKELANGID.

LANG_TURKISH

See MAKELANGID.

LANG_URDU

See MAKELANGID.

LB_OKAY

Listbox message return value: everything is okay.

LB_ERR

Listbox message return value: an error has occurred.

See LB_SETCOUNT, LB_SETCURSEL, LB_ADDFILE, LB_ADDSTRING, LB_DELETESTRING, LB_DIR, LB_FINDSTRING, LB_FINDSTRINGEXACT, LB_GETCOUNT, LB_GETCURSEL, LB_INSERTSTRING, LB_SELECTSTRING, LB_SELITEMRANGE, LB_SETCARETINDEX, LB_SETSEL

LB_ERRSPACE

Listbox message return value: insufficient space to store the new string.

See LB_ADDSTRING, LB_DIR, LB_INSERTSTRING, LB_SETCOUNT, WM_SETTEXT

LCMAP_BYTEREV

Byte reversal.

See LCMapStringW.

LCMAP_LOWERCASE

Lowercase. This option cannot be used with LCMAP_UPPERCASE.

See LCMapStringW.

LCMAP_SORTKEY

Wide character sort key (normalize).

See LCMapStringW.

LCMAP_UPPERCASE

Uppercase. This option cannot be used with LCMAP_LOWERCASE.

See LCMapStringW.

LEFT_ALT_PRESSED

The left-hand ALT key is pressed.

See KEY_EVENT_RECORD.

LEFT_CTRL_PRESSED

The left-hand CTRL key is pressed.

See KEY_EVENT_RECORD.

LINECAPS

A bitmask that indicates the line capabilities of the device. The bits have the following meanings:

See GetDeviceCaps.

LISTBOX

Designates a list of character strings. Use 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.

See CreateWindow.

LISTEN_OUTSTANDING

The session is waiting for a call from a remote computer.

See SESSION_BUFFER.

LOAD_DLL_DEBUG_EVENT

Reports a load DLL debugging event. The value of u.LoadDll specifies a LOAD_DLL_DEBUG_INFO structure.

See DEBUG_EVENT.

LOCALE_STIME

Character(s) for the time separator.

See Locale Identifiers.

LOCALE_STIMEFORMAT

Time formatting strings for this locale.

See Locale Identifiers.

LOGPIXELSX

Number of pixels per logical inch along the display width.

See GetDeviceCaps.

LOGPIXELSY

Number of pixels per logical inch along the display height.

See GetDeviceCaps.

LTGRAY_BRUSH

Light gray brush

See GetStockObject.

LZERROR_BADINHANDLE

The handle identifying the source file was not valid.

See CopyLZFile, LZCopy, LZInit, LZRead, LZSeek.

LZERROR_BADOUTHANDLE

The handle identifying the destination file was not valid.

See CopyLZFile, LZCopy, LZInit, LZRead.

LZERROR_BADVALUE

One of the input parameters was not valid.

See CopyLZFile, LZCopy, LZInit, LZRead, LZSeek.

LZERROR_GLOBALLOC

There is insufficient memory for the required buffers.

See CopyLZFile, LZCopy, LZInit, LZRead.

LZERROR_GLOBLOCK

A global handle was not valid.

See CopyLZFile, LZCopy, LZInit, LZRead, LZSeek.

LZERROR_READ

The source file format was not valid.

See CopyLZFile, LZCopy, LZInit, LZRead.

LZERROR_UNKNOWNALG

The file was compressed with an unrecognized compression algorithm.

See CopyLZFile, LZCopy, LZInit, LZRead.

LZERROR_WRITE

There is insufficient space for the output file.

See CopyLZFile, LZCopy, LZInit, LZRead.

MA_ACTIVATE

Activate the window, and do not discard the mouse message.

See WM_MOUSEACTIVATE.

MA_ACTIVATEANDEAT

Activate the window, and discard the mouse message.

See WM_MOUSEACTIVATE.

MA_NOACTIVATE

Do not activate the window, and do not discard the mouse message.

See WM_MOUSEACTIVATE.

MA_NOACTIVATEANDEAT

Do not activate the window, but do discard the mouse message.

See WM_MOUSEACTIVATE.

MAILSLOT_NO_MESSAGE

There is no next message.

See GetMailslotInfo.

MAILSLOT_WAIT_FOREVER

Waits forever for a message.

See CreateMailslot.

MAP_COMPOSITE

Canonicalize accented characters to composite. This value cannot be combined with MAP_PRECOMPOSED.

See FoldStringW.

MAP_FOLDCZONE

Fold compatibility zone characters.

See FoldStringW.

MAP_FOLDDIGITS

Canonicalize all digits to Unicode ASCII "0"-"9".

See FoldStringW.

MAP_PRECOMPOSED

Canonicalize accented characters to precomposed. This value cannot be combined with MAP_COMPOSITE.

See FoldStringW.

MARKPARITY

Mark

See DCB.

MB_ABORTRETRYIGNORE

The message box contains three push buttons: Abort, Retry, and Ignore.

See MessageBox.

MB_APPLMODAL

The user must respond to the message box before continuing work in the window identified by the hwndOwner parameter. However, the user can move to the windows of other applications and work in those windows. MB_APPLMODAL is the default if neither MB_SYSTEMMODAL nor MB_TASKMODAL is specified.

See MessageBox.

MB_COMPOSITE

Always use composite characters.

See MultiByteToWideChar.

MB_DEFAULT_DESKTOP_ONLY

The desktop currently receiving input must be a default desktop; otherwise, the function fails. A default desktop is a desktop that an application runs on once the user has logged on.

See MessageBox.

MB_DEFBUTTON1

The first button is the default. Note that the first button is always the default unless MB_DEFBUTTON2 or MB_DEFBUTTON3 is specified.

See MessageBox.

MB_DEFBUTTON2

The second button is the default.

See MessageBox.

MB_DEFBUTTON3

The third button is the default.

See MessageBox.

MB_ICONASTERISK

SystemAsterisk; same as MB_ICONINFORMATION.

See MessageBeep, MessageBox.

MB_ICONEXCLAMATION

An exclamation-point icon appears in the message box.

See MessageBeep, MessageBox.

MB_ICONHAND

SystemHand; same as MB_ICONSTOP.

See MessageBeep, MessageBox.

MB_ICONINFORMATION

An icon consisting of a lowercase letter "I" in a circle appears in the message box.

See MessageBox.

MB_ICONQUESTION

A question-mark icon appears in the message box.

See MessageBeep, MessageBox.

MB_ICONSTOP

A stop-sign icon appears in the message box.

See MessageBox.

MB_OK

SystemDefault MB_OK The message box contains one push button: OK.

See MessageBeep, MessageBox.

MB_OKCANCEL

The message box contains two push buttons: OK and Cancel.

See MessageBox.

MB_PRECOMPOSED

Always use precomposed characters. This is the default translation option.

See MultiByteToWideChar.

MB_RETRYCANCEL

The message box contains two push buttons: Retry and Cancel.

See MessageBox.

MB_SETFOREGROUND

The message box becomes the foreground window. Internally, Windows calls the SetForegroundWindow function for the message box.

See MessageBox.

MB_SYSTEMMODAL

All applications are suspended until the user responds to the message box. Unless the application specifies MB_ICONHAND, the message box does not become modal until after it is created; consequently, the owner window and other windows continue to receive messages resulting from its activation. System-modal message boxes are used to notify the user of serious, potentially damaging errors that require immediate attention (for example, running out of memory).

See MessageBox.

MB_TASKMODAL

Same as MB_APPLMODAL except that all the top-level windows belonging to the current task are disabled if the hwndOwner parameter is NULL. This flag should be used 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.

See MessageBox.

MB_USEGLYPHCHARS

Use glyph characters instead of control characters.

See MultiByteToWideChar.

MB_YESNO

The message box contains two push buttons: Yes and No.

See MessageBox.

MB_YESNOCANCEL

The message box contains three push buttons: Yes, No, and Cancel.

See MessageBox.

MCI_ANIM_GETDEVCAPS_CAN_REVERSE

The dwReturn member is set to TRUE if the device can play in reverse; otherwise, it is set to FALSE.

See MCI_GETDEVCAPS.

MCI_ANIM_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. MCIMMP returns FALSE.

See MCI_GETDEVCAPS.

MCI_ANIM_GETDEVCAPS_FAST_RATE

The dwReturn member is set to the standard fast play rate in frames per second. MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.

See MCI_GETDEVCAPS.

MCI_ANIM_GETDEVCAPS_MAX_WINDOWS

The dwReturn member is set to the maximum number of windows that the device can handle simultaneously.

See MCI_GETDEVCAPS.

MCI_ANIM_GETDEVCAPS_NORMAL_RATE

The dwReturn member is set to the normal rate of play in frames per second. MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.

See MCI_GETDEVCAPS.

MCI_ANIM_GETDEVCAPS_PALETTES

The dwReturn member is set to TRUE if the device can return a palette handle; otherwise, it is set to FALSE. MCIMMP returns TRUE.

See MCI_GETDEVCAPS.

MCI_ANIM_GETDEVCAPS_SLOW_RATE

The dwReturn member is set to the standard slow play rate in frames per second. MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.

See MCI_GETDEVCAPS.

MCI_ANIM_INFO_TEXT

Obtains the window caption.

See MCI_INFO.

MCI_ANIM_OPEN_NOSTATIC

Specifies that the device should reduce the number of static (system) colors in the palette to two.

See MCI_OPEN.

MCI_ANIM_OPEN_PARENT

Indicates the parent window handle is specified in the hWndParent member of the data structure identified by lpOpen. The parent window handle is required for some window styles.

See MCI_OPEN.

MCI_ANIM_OPEN_WS

Indicates a window style is specified in the dwStyle member of the data 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 which defines the window style. These constants are the same as the ones in WINDOWS.H (such as WS_CHILD, WS_OVERLAPPEDWINDOW, or WS_POPUP).

See MCI_OPEN.

MCI_ANIM_PLAY_FAST

Specifies to play fast.

See MCI_PLAY.

MCI_ANIM_PLAY_REVERSE

Specifies to play in reverse.

See MCI_PLAY.

MCI_ANIM_PLAY_SCAN

Specifies to scan quickly.

See MCI_PLAY.

MCI_ANIM_PLAY_SLOW

Specifies to play slowly.

See MCI_PLAY.

MCI_ANIM_PLAY_SPEED

Specifies that the play speed is included in the dwSpeed member in the data structure identified by lpPlay.

See MCI_PLAY.

MCI_ANIM_PUT_DESTINATION

Indicates the rectangle defined for MCI_ANIM_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.

See MCI_PUT.

MCI_ANIM_PUT_SOURCE

Indicates the rectangle defined for MCI_ANIM_RECT specifies a clipping rectangle for the animation image. The rectangle contains the offset and extent of the image relative to the image origin.

See MCI_PUT.

MCI_ANIM_RECT

Specifies that the rc member of the data structure identified by lpDest contains a valid rectangle. If this flag is not specified, the default rectangle matches the coordinates of the image or window being clipped.

See MCI_PUT.

MCI_ANIM_STATUS_FORWARD

The dwReturn member is set to TRUE if playing forward; otherwise, it is set to FALSE.

See MCI_STATUS.

MCI_ANIM_STATUS_HPAL

The dwReturn member is set to the handle of the movie palette.

See MCI_STATUS.

MCI_ANIM_STATUS_HWND

The dwReturn member is set to the handle of the playback window.

See MCI_STATUS.

MCI_ANIM_STATUS_SPEED

The dwReturn member is set to the animation speed.

See MCI_STATUS.

MCI_ANIM_STEP_FRAMES

Indicates that the dwFrames member of the data structure identified by lpStep specifies the number of frames to step.

See MCI_STEP.

MCI_ANIM_STEP_REVERSE

Steps in reverse.

See MCI_STEP.

MCI_ANIM_WHERE_DESTINATION

Obtains the destination display rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery.

See MCI_WHERE.

MCI_ANIM_WHERE_SOURCE

Obtains the animation source rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery.

See MCI_WHERE.

MCI_ANIM_WINDOW_HWND

Indicates the handle of the window to use for the destination is included in the hWnd member of the data structure identified by lpWindow. Set this to MCI_ANIM_WINDOW_DEFAULT to return to the default window.

See MCI_WINDOW.

MCI_ANIM_WINDOW_STATE

Indicates the nCmdShow member of the MCI_ANIM_WINDOW_PARMS data 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 the ones in WINDOWS.H (such as SW_HIDE, SW_MINIMIZE, or SW_SHOWNORMAL.)

See MCI_WINDOW.

MCI_ANIM_WINDOW_TEXT

Indicates the lpstrText member of the MCI_ANIM_WINDOW_PARMS data structure contains a pointer to a buffer containing the caption used for the window.

See MCI_WINDOW.

MCI_BREAK_HWND

Indicates the hwndBreak member of the data structure identified by lpBreak contains a window handle which 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.

See MCI_BREAK.

MCI_BREAK_KEY

Indicates the nVirtKey member of the data 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.

See MCI_BREAK.

MCI_BREAK_OFF

Used to disable any existing break key for the indicated device

See MCI_BREAK.

MCI_FORMAT_BYTES

Changes the time format to bytes for input or output.

See MCI_SET.

MCI_FORMAT_CHAPTERS

Changes the time format to chapters.

See MCI_SET.

MCI_FORMAT_FRAMES

Changes the time format to frames. MCI_FORMAT_FRAMES Changes the time format to frames.

See MCI_SET.

MCI_FORMAT_HMS

Changes the time format to hours, minutes, and seconds.

See MCI_SET.

MCI_FORMAT_MILLISECONDS

Changes the time format to milliseconds.

See MCI_SET,

MCI_FORMAT_MSF

Changes the time format to minutes, seconds, and frames.

See MCI_SET.

MCI_FORMAT_SAMPLES

Changes the time format to samples for input or output.

See MCI_SET.

MCI_FORMAT_SMPTE_24

Sets the time format to 24 frame SMPTE.

See MCI_SET.

MCI_FORMAT_SMPTE_25

Sets the time format to 25 frame SMPTE.

See MCI_SET.

MCI_FORMAT_SMPTE_30

Sets the time format to 30 frame SMPTE.

See MCI_SET.

MCI_FORMAT_SMPTE_30DROP

Sets the time format to 30 drop-frame SMPTE.

See MCI_SET.

MCI_FORMAT_TMSF

Changes the time format to tracks, minutes, seconds, and frames. (MCI uses continuous track numbers.)

See MCI_SET.

MCI_FROM

Specifies that a beginning position is included in the dwFrom member of the data structure identified by lpDelete. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

See MCI_DELETE, MCI_PLAY, MCI_RECORD.

MCI_GETDEVCAPS_CAN_EJECT

The dwReturn member is set to TRUE if the device can eject the media; otherwise, it is set to FALSE.

See MCI_GETDEVCAPS.

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 MCI_PAUSE and MCI_STOP as well as MCI_PLAY.

See MCI_GETDEVCAPS.

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 MCI_PAUSE and MCI_STOP as well as MCI_RECORD.

See MCI_GETDEVCAPS.

MCI_GETDEVCAPS_CAN_SAVE

The dwReturn member is set to TRUE if the device can save a file; otherwise, it is set to FALSE.

See MCI_GETDEVCAPS.

MCI_GETDEVCAPS_COMPOUND_DEVICE

The dwReturn member is set to TRUE if the device uses device elements; otherwise, it is set to FALSE.

See MCI_GETDEVCAPS.

MCI_GETDEVCAPS_DEVICE_TYPE

The dwReturn member is set to one of the following values indicating the device type:

See MCI_GETDEVCAPS.

MCI_GETDEVCAPS_HAS_AUDIO

The dwReturn member is set to TRUE if the device has audio output; otherwise, it is set to FALSE.

See MCI_GETDEVCAPS.

MCI_GETDEVCAPS_HAS_VIDEO

The dwReturn member is set to TRUE if the device has video output; otherwise, it is set to FALSE. For example, the member is set to TRUE for devices that support the animation or videodisc command set.

See MCI_GETDEVCAPS.

MCI_GETDEVCAPS_ITEM

Specifies that the dwItem member of the data structure identified by lpCapsParms contains a constant specifying which device capability to obtain.

See MCI_GETDEVCAPS.

MCI_GETDEVCAPS_USES_FILES

The dwReturn member is set to TRUE if the device requires a filename as its element name; otherwise, it is set to FALSE. Only compound devices use files.

See MCI_GETDEVCAPS.

MCI_INFO_FILE

Obtains the filename of the current file. This flag is only supported by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES query. MCI_INFO_FILE Obtains the filename of the current file. This flag is only supported by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES query. MCI_INFO_FILE Obtains the filename of the current file. This flag is supported by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES query.

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

See MCI_INFO.

MCI_LOAD_FILE

Indicates the lpfilename member of the data structure identified by lpLoad contains a pointer to a buffer containing the file name.

See MCI_LOAD.

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the data structure identified by lpWindow.

See MCI_BREAK, MCI_CLOSE, MCI_COPY, MCI_CUE, MCI_CUT, MCI_DELETE, MCI_FREEZE, MCI_GETDEVCAPS, MCI_INFO, MCI_LOAD, MCI_OPEN, MCI_PASTE, MCI_PAUSE, MCI_PLAY, MCI_PUT, MCI_RECORD, MCI_RESUME, MCI_SAVE, MCI_SEEK, MCI_SET, MCI_SOUND, MCI_STATUS, MCI_STEP, MCI_STOP, MCI_UNFREEZE, MCI_WHERE, MCI_WINDOW.

MCI_NOTIFY_ABORTED

Specifies that the device received a command that prevented the current conditions for initiating the callback from being met. If a new command interrupts the current command and it also requests notification, the device sends only this message and not MCI_NOTIFY_SUPERCEDED.

See MM_MCINOTIFY.

MCI_NOTIFY_FAILURE

Specifies that a device error occurred while the device was executing the command.

See MM_MCINOTIFY.

MCI_NOTIFY_SUCCESSFUL

Specifies that the conditions initiating the callback have been met.

See MM_MCINOTIFY.

MCI_NOTIFY_SUPERSEDED

Specifies that the device received another command with the MCI_NOTIFY flag set and the current conditions for initiating the callback have been superseded.

See MM_MCINOTIFY.

MCI_OPEN_ALIAS

Specifies that an alias is included in the lpstrAlias member of the data structure identified by lpOpen.

See MCI_OPEN.

MCI_OPEN_ELEMENT

Specifies that an element name is included in the lpstrElementName member of the data structure identified by lpOpen.

See MCI_OPEN.

MCI_OPEN_ELEMENT_ID

Specifies that the lpstrElementName member of the data structure identified by lpOpen is interpreted as a DWORD and has meaning internal to the device. Use this flag with the MCI_OPEN_ELEMENT flag.

See MCI_OPEN.

MCI_OPEN_SHAREABLE

Specifies that the device or device element should be opened as shareable.

See MCI_OPEN.

MCI_OPEN_TYPE

Specifies that a device type name or constant is included in the lpstrDeviceType member of the data structure identified by lpOpen.

See MCI_OPEN.

MCI_OPEN_TYPE_ID

Specifies that the low-order word of the lpstrDeviceType member of the associated data structure contains a standard MCI device type ID and the high-order word optionally contains the ordinal index for the device. Use this flag with the MCI_OPEN_TYPE flag.

See MCI_OPEN.

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.

See MCI_GETDEVCAPS.

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.

See MCI_GETDEVCAPS.

MCI_OVLY_GETDEVCAPS_MAX_WINDOWS

The dwReturn member is set to the maximum number of windows that the device can handle simultaneously.

See MCI_GETDEVCAPS.

MCI_OVLY_INFO_TEXT

Obtains the caption of the window associated with the overlay device.

See MCI_INFO.

MCI_OVLY_OPEN_PARENT

Indicates the parent window handle is specified in the hWndParent member of the data structure identified by lpOpen.

See MCI_OPEN.

MCI_OVLY_OPEN_WS

Indicates a window style is specified in the dwStyle member of the data 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 those in WINDOWS.H (for example, WS_CHILD, WS_OVERLAPPEDWINDOW, or WS_POPUP).

See MCI_OPEN.

MCI_OVLY_PUT_DESTINATION

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

See MCI_PUT.

MCI_OVLY_PUT_FRAME

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

See MCI_PUT.

MCI_OVLY_PUT_SOURCE

Indicates that 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.

See MCI_PUT.

MCI_OVLY_PUT_VIDEO

Indicates that 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.

See MCI_PUT.

MCI_OVLY_RECT

Specifies that the rc member of the data structure identified by lpFreeze contains a valid rectangle. If this flag is not specified, the device driver will freeze the entire frame. MCI_OVLY_RECT Specifies that the rc member of the data structure identified by lpLoad contains a valid display rectangle that identifies the area of the video buffer to update. MCI_OVLY_RECT Specifies that the rc member of the data 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. MCI_OVLY_RECT Specifies that the rc member of the data structure identified by lpSave contains a valid display rectangle indicating the area of the video buffer to save. MCI_OVLY_RECT Specifies that the rc member of the data structure identified by lpFreeze contains a valid display rectangle. This is a required parameter.

See MCI_FREEZE, MCI_LOAD, MCI_PUT, MCI_SAVE, MCI_UNFREEZE.

MCI_OVLY_STATUS_HWND

The dwReturn member is set to the handle of the window associated with the video overlay device.

See MCI_STATUS.

MCI_OVLY_WHERE_DESTINATION

Obtains the destination display rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery.

See MCI_WHERE.

MCI_OVLY_WHERE_FRAME

Obtains the overlay frame rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery.

See MCI_WHERE.

MCI_OVLY_WHERE_SOURCE

Obtains the source rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery.

See MCI_WHERE.

MCI_OVLY_WHERE_VIDEO

Obtains the video rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery.

See MCI_WHERE.

MCI_OVLY_WINDOW_HWND

Indicates the handle of the window used for the destination is included in the hWnd member of the MCI_OVLY_WINDOW_PARMS data structure. Set this to MCI_OVLY_WINDOW_DEFAULT to return to the default window.

See MCI_WINDOW.

MCI_OVLY_WINDOW_STATE

Indicates the nCmdShow member of the lpWindow data structure contains parameters for setting the window state. This flag It 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.)

See MCI_WINDOW.

MCI_OVLY_WINDOW_TEXT

Indicates the lpstrText member of the MCI_OVLY_WINDOW_PARMS data structure contains a pointer to buffer containing the caption used for the window.

See MCI_WINDOW.

MCI_RECORD_INSERT

Indicates that newly recorded information should be inserted or pasted into the existing data. (Some devices may not support this.) If supported, this is the default.

See MCI_RECORD.

MCI_RECORD_OVERWRITE

Specifies that data should overwrite existing data. MCIWAVE returns MCIERR_UNSUPPORTED_FUNCTION in response to this flag.

See MCI_RECORD.

MCI_SAVE_FILE

Indicates the lpfilename member of the data structure identified by lpSave contains a pointer to a buffer containing the destination file name.

See MCI_SAVE.

MCI_SEEK_TO_END

Specifies to seek to the end of the media.

See MCI_SEEK.

MCI_SEEK_TO_START

Specifies to seek to the start of the media.

See MCI_SEEK.

MCI_SEQ_FILE

Sets the sequencer to receive synchronization data contained in the MIDI file.

See MCI_SET.

MCI_SEQ_FORMAT_SONGPTR

Sets the time format to song-pointer units.

See MCI_SET.

MCI_SEQ_MIDI

The sequencer will send MIDI format synchronization data.

See MCI_SET.

MCI_SEQ_NONE

The sequencer will not send synchronization data.

See MCI_SET.

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 data structure identified by lpSet. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION. The following constants are defined for the synchronization type:

See MCI_SET.

MCI_SEQ_SET_OFFSET

Changes the SMPTE offset of a sequence to that specified by the dwOffset member of the data structure identified by lpSet. This only affects sequences with a SMPTE division type.

See MCI_SET.

MCI_SEQ_SET_PORT

Sets the output MIDI port of a sequence to that specified by the MIDI device ID in the dwPort member of the data structure identified by lpSet. The device will close the previous port (if any), and attempt to open and use the new port. If it fails, it will return an error and re-open the previously used port (if any). The following constants are defined for the ports:

See MCI_SET.

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 data structure identified by lpSet. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION. The following constants are defined for the synchronization type:

See MCI_SET.

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.

See MCI_SET.

MCI_SEQ_SMPTE

The sequencer will send SMPTE format synchronization data.

See MCI_SET.

MCI_SEQ_STATUS_DIVTYPE

The dwReturn member is set to one of the following values indicating the current division type of a sequence:

See MCI_STATUS.

MCI_SEQ_STATUS_MASTER

The dwReturn member is set to the synchronization type used for master operation.

See MCI_STATUS.

MCI_SEQ_STATUS_OFFSET

The dwReturn member is set to the current SMPTE offset of a sequence.

See MCI_STATUS.

MCI_SEQ_STATUS_PORT

The dwReturn member is set to the MIDI device ID for the current port used by the sequence.

See MCI_STATUS.

MCI_SEQ_STATUS_SLAVE

The dwReturn member is set to the synchronization type used for slave operation.

See MCI_STATUS.

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.

See MCI_STATUS.

MCI_SET_AUDIO

Specifies an audio channel number is included in the dwAudio member of the data 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:

See MCI_SET.

MCI_SET_AUDIO_ALL

Specifies all audio channels.

See MCI_SET.

MCI_SET_AUDIO_LEFT

Specifies the left channel.

See MCI_SET.

MCI_SET_AUDIO_RIGHT

Specifies the right channel.

See MCI_SET.

MCI_SET_DOOR_CLOSED

Instructs the device to close the media cover (if any).

See MCI_SET.

MCI_SET_DOOR_OPEN

Instructs the device to open the media cover (if any).

See MCI_SET.

MCI_SET_OFF

Disables the specified video or audio channel.

See MCI_SET.

MCI_SET_ON

Enables the specified video or audio channel.

See MCI_SET.

MCI_SET_TIME_FORMAT

Specifies a time format parameter that is used with the dwTimeFormat members of MCI_SET_PARMS and MCI_SEQ_SET_PARMS data structures. Possible values, depending upon the usage context, include MCI_FORMAT_BYTES, MCI_FORMAT_CHAPTERS, MCI_FORMAT_FRAMES, MCI_FORMAT_HMS, MCI_FORMAT_MILLISECONDS, MCI_FORMAT_MSF, MCI_FORMAT_SAMPLES, MCI_FORMAT_SMPTE_24, MCI_FORMAT_SMPTE_25, MCI_FORMAT_SMPTE_30, MCI_FORMAT_SMPTE_30DROP, MCI_SEQ_FORMAT_SONGPTR,  MCI_FORMAT_TMSF, and MCI_VD_FORMAT_TRACK.

See MCI_SET, MCI_SET_PARMS, MCI_SEQ_SET_PARMS.

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.

See MCI_SET.

MCI_SOUND_NAME

Indicates that the name of a sound to play is included in the lpstrSoundName of the data structure identified by lpSound. If omitted, the default sound is played.

See MCI_SOUND.

MCI_STATUS_CURRENT_TRACK

The dwReturn member is set to the current track number. MCI uses continuous track numbers.

See MCI_STATUS.

MCI_STATUS_ITEM

Specifies that the dwItem member of the data 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 data structure:

See MCI_STATUS.

MCI_STATUS_LENGTH

The dwReturn member is set to the total media length.

See MCI_STATUS.

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; otherwise, it is set to FALSE.

See MCI_STATUS.

MCI_STATUS_MODE

The dwReturn member is set to the current mode of the device. All devices can return the following constants to indicate the current mode:

See MCI_STATUS.

MCI_STATUS_NUMBER_OF_TRACKS

The dwReturn member is set to the total number of playable tracks.

See MCI_STATUS.

MCI_STATUS_POSITION

The dwReturn member is set to the current position.

See MCI_STATUS.

MCI_STATUS_READY

The dwReturn member is set to TRUE if the device is ready; otherwise, it is set to FALSE.

See MCI_STATUS.

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 data structure identified by lpStatus to MCI_STATUS_POSITION.

See MCI_STATUS.

MCI_STATUS_TIME_FORMAT

The dwReturn member is set to the current time format of the device. The time formats include:

See MCI_STATUS.

MCI_SYSINFO_INSTALLNAME

Obtains the name (listed in the registry) used to install the device.

See MCI_SYSINFO.

MCI_SYSINFO_NAME

Obtains a device name corresponding to the device number specified in the dwNumbermember of the data structure identified by lpSysInfo . If the MCI_SYSINFO_OPEN flag is set, MCI returns the names of open devices.

See MCI_SYSINFO.

MCI_SYSINFO_OPEN

Obtains the quantity or name of open devices.

See MCI_SYSINFO.

MCI_SYSINFO_QUANTITY

Obtains the number of devices of the specified type that are listed in the [mci] section of the registry file. If the MCI_SYSINFO_OPEN flag is set, the number of open devices is returned.

See MCI_SYSINFO.

MCI_TO

Specifies that an ending position is included in the dwTo member of the data structure identified by lpDelete. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. MCI_TO Specifies that an ending position is included in the dwTo member of the data structure identified by lpPlay. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_TO is not specified, the end position defaults to the end of the media. MCI_TO Specifies that an ending position is included in the dwTo member of the data structure identified by lpRecord. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_TO is not specified, the ending position defaults to the end of the media. MCI_TO Specifies a position is included in the dwTo member of the MCI_SEEK_PARMS data structure. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. Do not use this flag with MCI_SEEK_END or MCI_SEEK_START.

See MCI_DELETE, MCI_PLAY, MCI_RECORD, MCI_SEEK.

MCI_TRACK

Indicates a status track parameter is included in the dwTrack member of the data 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.

See MCI_STATUS.

MCI_VD_FORMAT_TRACK

Changes the time format to tracks. MCI uses continuous track numbers.

See MCI_SET.

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.

See MCI_GETDEVCAPS.

MCI_VD_GETDEVCAPS_CAV

Indicates the information requested applies to CAV format discs. By default, the capabilities apply to the current disc.

See MCI_GETDEVCAPS.

MCI_VD_GETDEVCAPS_CLV

Indicates the information requested applies to CLV format discs. By default, the capabilities apply to the current disc.

See MCI_GETDEVCAPS.

MCI_VD_GETDEVCAPS_FAST_RATE

The dwReturn member is set to the standard fast play rate in frames per second.

See MCI_GETDEVCAPS.

MCI_VD_GETDEVCAPS_NORMAL_RATE

The dwReturn member is set to the normal play rate in frames per second.

See MCI_GETDEVCAPS.

MCI_VD_GETDEVCAPS_SLOW_RATE

The dwReturn member is set to the standard slow play rate in frames per second.

See MCI_GETDEVCAPS.

MCI_VD_PLAY_FAST

Specifies to play fast.

See MCI_PLAY.

MCI_VD_PLAY_REVERSE

Specifies to play in reverse.

See MCI_PLAY.

MCI_VD_PLAY_SCAN

Specifies to scan quickly.

See MCI_PLAY.

MCI_VD_PLAY_SLOW

Specifies to play slowly.

See MCI_PLAY.

MCI_VD_PLAY_SPEED

Specifies that the play speed is included in the dwSpeed member in the data structure identified by lpPlay.

See MCI_PLAY.

MCI_VD_SEEK_REVERSE

Specifies to seek backward.

See MCI_SEEK.

MCI_VD_STATUS_DISC_SIZE

The dwReturn member is set to the size of the loaded disc in inches (8 or 12).

See MCI_STATUS.

MCI_VD_STATUS_FORWARD

The dwReturn member is set to TRUE if playing forward; otherwise, it is set to FALSE.

See MCI_STATUS.

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:

See MCI_STATUS.

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.

See MCI_STATUS.

MCI_VD_STATUS_SPEED

The dwReturn member is set to the play speed in frames per second. MCIPIONR returns MCIERR_UNSUPPORTED_FUNCTION.

See MCI_STATUS.

MCI_VD_STEP_FRAMES

Indicates that the dwFrames member of the data structure identified by lpStep specifies the number of frames to step.

See MCI_STEP.

MCI_VD_STEP_REVERSE

Steps in reverse.

See MCI_STEP.

MCI_WAIT

Specifies that the operation should finish before MCI returns control to the application.

See MCI_BREAK, MCI_CLOSE, MCI_COPY, MCI_CUE, MCI_CUT, MCI_DELETE, MCI_FREEZE, MCI_GETDEVCAPS, MCI_INFO, MCI_LOAD, MCI_OPEN, MCI_PASTE, MCI_PAUSE, MCI_PLAY, MCI_PUT, MCI_RECORD, MCI_RESUME, MCI_SAVE, MCI_SEEK, MCI_SET, MCI_SOUND, MCI_STATUS, MCI_STEP, MCI_STOP, MCI_UNFREEZE, MCI_WHERE, MCI_WINDOW.

MCI_WAVE_GETDEVCAPS_INPUT

The dwReturn member is set to the total number of waveform input (recording) devices.

See MCI_GETDEVCAPS.

MCI_WAVE_GETDEVCAPS_OUTPUT

The dwReturn member is set to the total number of waveform output (playback) devices.

See MCI_GETDEVCAPS.

MCI_WAVE_INPUT

Specifies that a wave input device should be cued.

See MCI_CUE, MCI_INFO, MCI_SET, MCI_STATUS.

MCI_WAVE_OPEN_BUFFER

Indicates a buffer length is specified in the dwBuffer member of the data structure identified by lpOpen.

See MCI_OPEN.

MCI_WAVE_OUTPUT

Specifies that a wave output device should be cued. This is the default flag if a flag is not specified.

See MCI_CUE, MCI_INFO, MCI_SET, MCI_STATUS.

MCI_WAVE_SET_ANYINPUT

Specifies that any wave input compatible with the current format can be used for recording.

See MCI_SET.

MCI_WAVE_SET_ANYOUTPUT

Specifies that any wave output compatible with the current format can be used for playing.

See MCI_SET.

MCI_WAVE_SET_AVGBYTESPERSEC

Sets the bytes per second used for playing, recording, and saving to the nAvgBytesPerSec member of the data structure identified by lpSet.

See MCI_SET.

MCI_WAVE_SET_BITSPERSAMPLE

Sets the bits per sample used for playing, recording, and saving to the nBitsPerSample member of the data structure identified by lpSet.

See MCI_SET.

MCI_WAVE_SET_BLOCKALIGN

Sets the block alignment used for playing, recording, and saving to the nBlockAlign member of the data structure identified by lpSet.

See MCI_SET.

MCI_WAVE_SET_CHANNELS

Specifies the number of channels is indicated in the nChannels member of the data structure identified by lpSet.

See MCI_SET.

MCI_WAVE_SET_FORMATTAG

Sets the format type used for playing, recording, and saving to the wFormatTag member of the data structure identified by lpSet. Specifying WAVE_FORMAT_PCM changes the format to PCM.

See MCI_SET.

MCI_WAVE_SET_SAMPLESPERSEC

Sets the samples per second used for playing, recording, and saving to the nSamplesPerSec member of the data structure identified by lpSet.

See MCI_SET.

MCI_WAVE_STATUS_AVGBYTESPERSEC

The dwReturn member is set to the current bytes per second used for playing, recording, and saving.

See MCI_STATUS.

MCI_WAVE_STATUS_BITSPERSAMPLE

The dwReturn member is set to the current bits per sample used for playing, recording, and saving.

See MCI_STATUS.

MCI_WAVE_STATUS_BLOCKALIGN

The dwReturn member is set to the current block alignment used for playing, recording, and saving.

See MCI_STATUS.

MCI_WAVE_STATUS_CHANNELS

The dwReturn member is set to the current channel count used for playing, recording, and saving.

See MCI_STATUS.

MCI_WAVE_STATUS_FORMATTAG

The dwReturn member is set to the current format tag used for playing, recording, and saving.

See MCI_STATUS.

MCI_WAVE_STATUS_LEVEL

The dwReturn member is set to the current record or playback level. 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.

See MCI_STATUS.

MCI_WAVE_STATUS_SAMPLESPERSEC

The dwReturn member is set to the current samples per second used for playing, recording, and saving.

See MCI_STATUS.

MCIERR_BAD_CONSTANT

Unknown value for parameter.

See mciSendString.

MCIERR_BAD_INTEGER

Invalid or missing integer in command.

See mciSendString.

MCIERR_BAD_TIME_FORMAT

Illegal value for time format.

See mciSendCommand.

MCIERR_CANNOT_LOAD_DRIVER

Error loading media device driver.

See MCI_OPEN.

MCIERR_CANNOT_USE_ALL

The device name "all" is not allowed for this command.

See mciSendCommand.

MCIERR_CREATEWINDOW

Could not create or use window.

See mciSendCommand.

MCIERR_DEVICE_LOCKED

The device is locked until it is closed automatically.

See mciSendCommand.

MCIERR_DEVICE_NOT_READY

Device not ready.

See mciSendCommand.

MCIERR_DEVICE_OPEN

The device name is in use by this task. Use a unique alias.

See MCI_OPEN.

MCIERR_DEVICE_TYPE_REQUIRED

The device name must be a valid device type.

See mciSendCommand.

MCIERR_DRIVER

Unspecified device error.

See mciSendCommand.

MCIERR_DRIVER_INTERNAL

Internal driver error.

See mciSendCommand.

MCIERR_DUPLICATE_ALIAS

The specified alias is an open device in this task.

See MCI_OPEN.

MCIERR_DUPLICATE_FLAGS

A flag or value was specified twice.

See mciSendString.

MCIERR_EXTENSION_NOT_FOUND

Cannot deduce a device type from the given extension.

See MCI_OPEN.

MCIERR_FILE_NOT_FOUND

Requested file not found.

See mciSendCommand.

MCIERR_FILE_NOT_SAVED

The file was not saved.

See mciSendCommand.

MCIERR_FILE_READ

A read from the file failed.

See mciSendCommand.

MCIERR_FILE_WRITE

A write to the file failed.

See mciSendCommand.

MCIERR_FILENAME_REQUIRED

A valid filename is required.

See MCI_OPEN.

MCIERR_FLAGS_NOT_COMPATIBLE

Incompatible parameters were specified.

See mciSendCommand.

MCIERR_HARDWARE

Hardware error on media device.

See mciSendCommand.

MCIERR_INTERNAL

Internal error.

See mciSendCommand.

MCIERR_INVALID_DEVICE_ID

Invalid device ID.

See mciSendCommand.

MCIERR_INVALID_DEVICE_NAME

The device is not open or is not known.

See mciSendCommand.

MCIERR_INVALID_FILE

Invalid file format.

See mciSendCommand.

MCIERR_MISSING_COMMAND_STRING

No command was specified.

See mciSendString.

MCIERR_MISSING_DEVICE_NAME

No device name was specified.

See mciSendString.

MCIERR_MISSING_PARAMETER

Required parameter is missing.

See MCI_OPEN.

MCIERR_MISSING_STRING_ARGUMENT

A string value was missing from the command.

See mciSendString.

MCIERR_MULTIPLE

Errors occurred in more than one device.

See mciSendCommand.

MCIERR_MUST_USE_SHAREABLE

The device is already open; use the shareable flag with each open.

See MCI_OPEN.

MCIERR_NEW_REQUIRES_ALIAS

An alias must be used with the "new" device name.

See mciSendString.

MCIERR_NO_CLOSING_QUOTE

A closing quotation mark is missing.

See mciSendString.

MCIERR_NO_ELEMENT_ALLOWED

An element name cannot be used with this device.

See MCI_OPEN.

MCIERR_NO_WINDOW

There is no display window.

See mciSendCommand.

MCIERR_NOTIFY_ON_AUTO_OPEN

The "notify" flag is illegal with auto-open.

See mciSendString.

MCIERR_NULL_PARAMETER_BLOCK

Parameter block pointer was NULL.

See mciSendCommand.

MCIERR_OUT_OF_MEMORY

Not enough memory for requested operation.

See mciSendCommand.

MCIERR_OUTOFRANGE

Parameter value out of range.

See mciSendCommand.

MCIERR_PARAM_OVERFLOW

The output string was not long enough.

See mciSendString.

MCIERR_PARSER_INTERNAL

Internal parser error.

See mciSendString.

MCIERR_SEQ_DIV_INCOMPATIBLE

Set Song Pointer incompatible with SMPTE files.

See mciSendCommand.

MCIERR_SEQ_NOMIDIPRESENT

No MIDI ports present.

See mciSendCommand.

MCIERR_SEQ_PORT_INUSE

Specified port is in use.

See mciSendCommand.

MCIERR_SEQ_PORT_MAPNODEVICE

Current map uses non-existent device.

See mciSendCommand.

MCIERR_SEQ_PORT_MISCERROR

Miscellaneous error with specified port.

See mciSendCommand.

MCIERR_SEQ_PORT_NONEXISTENT

Specified port does not exist.

See mciSendCommand.

MCIERR_SEQ_PORTUNSPECIFIED

No current MIDI port.

See mciSendCommand.

MCIERR_SEQ_TIMER

Timer error.

See mciSendCommand.

MCIERR_UNNAMED_RESOURCE

Attempt to save unnamed file.

See mciSendCommand.

MCIERR_UNRECOGNIZED_COMMAND

Unknown command.

See mciSendCommand.

MCIERR_UNRECOGNIZED_KEYWORD

Unknown command parameter.

See mciSendString.

MCIERR_UNSUPPORTED_FUNCTION

Action not available for this device.

See mciSendCommand.

MCIERR_WAVE_INPUTSINUSE

No compatible waveform recording device is free.

See mciSendCommand.

MCIERR_WAVE_INPUTSUNSUITABLE

No compatible waveform recording devices.

See mciSendCommand.

MCIERR_WAVE_INPUTUNSPECIFIED

Any compatible waveform recording device may be used.

See mciSendCommand.

MCIERR_WAVE_OUTPUTSINUSE

No compatible waveform playback device is free.

See mciSendCommand.

MCIERR_WAVE_OUTPUTSUNSUITABLE

No compatible waveform playback devices.

See mciSendCommand.

MCIERR_WAVE_OUTPUTUNSPECIFIED

Any compatible waveform playback device may be used.

See mciSendCommand.

MCIERR_WAVE_SETINPUTINUSE

Set waveform recording device is in use.

See mciSendCommand.

MCIERR_WAVE_SETINPUTUNSUITABLE

Set waveform recording device is incompatible with set format.

See mciSendCommand.

MCIERR_WAVE_SETOUTPUTINUSE

Set waveform playback device is in use.

See mciSendCommand.

MCIERR_WAVE_SETOUTPUTUNSUITABLE

Set waveform playback device is incompatible with set format.

See mciSendCommand.

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. To create an MDI client window that enables the user to scroll MDI child windows into view, you can also use the WS_HSCROLL and WS_VSCROLL styles.

See CreateWindow.

MDITILE_HORIZONTAL

Tiles MDI child windows so that they are wide rather than tall.

See WM_MDITILE.

MDITILE_SKIPDISABLED

Prevents disabled MDI child windows from being tiled.

See WM_MDITILE.

MDITILE_VERTICAL

Tiles MDI child windows so that they are tall rather than wide.

See WM_MDITILE.

MEM_COMMIT

Indicates that the specified region of pages is to be committed, or that its state is committed.

See VirtualAlloc, VirtualQuery, VirtualQueryEx

MEM_DECOMMIT

Indicates that the specified region of pages is to be decommitted.

See VirtualFree

MEM_FREE

Indicates that the state of the pages within the specified region is free.

See VirtualQuery, VirtualQueryEx

MEM_IMAGE

Indicates that the memory pages within the region are mapped into the view of an image section.

See VirtualQuery, VirtualQueryEx

MEM_MAPPED

Indicates that the memory pages within the region are mapped into the view of a section.

See VirtualQuery, VirtualQueryEx

MEM_PRIVATE

Indicates that the memory pages within the region are private.

See VirtualQuery, VirtualQueryEx

MEM_RELEASE

Indicates that the specified region of pages is to be released.

See VirtualFree

MEM_RESERVE

Indicates that specified region of pages is to be reserved, or that the state of the pages within the region is reserved.

See VirtualAlloc, VirtualQuery, VirtualQueryEx

MEM_TOP_DOWN

Indicates that the operating system should allocate virtual memory at the highest-possible address.

See VirtualAlloc

MERGECOPY

Merges the colors of the source rectangle with the specified pattern using the Boolean AND operator.

See BitBlt.

MERGEPAINT

Merges the colors of the inverted source-rectangle with the colors of the destination rectangle by using the Boolean OR operator.

See BitBlt.

MF_BITMAP

Contains a bitmap handle.

See AppendMenu, InsertMenu, ModifyMenu, WM_MENUSELECT.

MF_BYCOMMAND

See CheckMenuItem, DeleteMenu, EnableMenuItem, GetMenuState, GetMenuString, HiliteMenuItem, InsertMenu, ModifyMenu, RemoveMenu, SetMenuItemBitmaps.

MF_BYPOSITION

See CheckMenuItem, DeleteMenu, EnableMenuItem, GetMenuState, GetMenuString, HiliteMenuItem, InsertMenu, ModifyMenu, RemoveMenu, SetMenuItemBitmaps.

MF_CALLBACKS

Notifies the callback function whenever a transaction is sent to any DDE callback function in the system.

See DdeInitialize, XTYP_MONITOR.

MF_CHECKED

Places a check mark next to the item. If the application provides check mark bitmaps (see the SetMenuItemBitmaps function), this flag displays the checked bitmap next to the menu item.

See AppendMenu, CheckMenuItem, GetMenuState, InsertMenu, ModifyMenu, WM_MENUSELECT, MENUITEMTEMPLATE.

MF_CONV

Notifies the callback function whenever a conversation is established or terminated.

See DdeInitialize, XTYP_MONITOR.

MF_DISABLED

Disables the menu item so it cannot be selected, but does not gray it.

See AppendMenu, EnableMenuItem, GetMenuState, InsertMenu, ModifyMenu, WM_MENUSELECT.

MF_ENABLED

Enables the menu item so it can be selected and restores it from its grayed state.

See AppendMenu, EnableMenuItem, InsertMenu, ModifyMenu.

MF_ERRORS

A DDE error occurred. The DDE data object contains a MONERRSTRUCT structure that provides information about the error.

See DdeInitialize, XTYP_MONITOR.

MF_GRAYED

Disables the menu item and grays it so it cannot be selected.

See AppendMenu, EnableMenuItem, GetMenuState, InsertMenu, ModifyMenu, WM_MENUSELECT, MENUITEMTEMPLATE.

MF_HELP

Indicates that the item has a vertical separator to its left.

See MENUITEMTEMPLATE.

MF_HILITE

Highlights the menu item. If this value is not given, the highlighting is removed from the item.

See GetMenuState, HiliteMenuItem.

MF_HSZ_INFO

Notifies the callback function whenever a DDE application creates, frees, or increments the use count of a string handle or whenever a string handle is freed as a result of a call to the DdeUninitialize function.

See DdeInitialize, XTYP_MONITOR.

MF_LINKS

Notifies the callback function whenever an advise loop is started or ended.

See DdeInitialize, XTYP_MONITOR.

MF_MENUBARBREAK

Functions the same as MF_MENUBREAK except for pop-up menus, where the new column is separated from the old column by a vertical line.

See AppendMenu, GetMenuState, InsertMenu, ModifyMenu, MENUITEMTEMPLATE.

MF_MENUBREAK

Places the item on a new line (menu bars) or in a new column (pop-up menus) without separating columns.

See AppendMenu, GetMenuState, InsertMenu, ModifyMenu, MENUITEMTEMPLATE.

MF_MOUSESELECT

Item was selected with the mouse.

See WM_MENUSELECT.

MF_OWNERDRAW

Contains a 32-bit value supplied by your application that you can use to maintain additional data related to the menu item. The value is in the itemData member of the structire pointed to by the Iparam parameter of the WM_MEASURE or WM_DRAWITEM messages sent when you create the menu item or update its appearance.

See AppendMenu, InsertMenu, ModifyMenu, WM_MENUSELECT, MENUITEMTEMPLATE.

MF_POPUP

Specifies that the menu item is a pop-up item; that is, selecting it invokes a pop-up menu. The idNewItem parameter specifies the handle of the pop-up menu. Use this flag to add a pop-up item to a menu bar or to a pop-up menu.

See AppendMenu, InsertMenu, ModifyMenu, WM_MENUCHAR, WM_MENUSELECT, MENUITEMTEMPLATE.

MF_POSTMSGS

Notifies the callback function whenever the system or an application posts a DDE message.

See DdeInitialize, XTYP_MONITOR.

MF_SENDMSGS

Notifies the callback function whenever the system or an application sends a DDE message.

See DdeInitialize, XTYP_MONITOR.

MF_SEPARATOR

Draws a horizontal dividing line. Use this flag only in a pop-up menu. You cannot gray, disable, or highlight this line. The lpszNewItem and idNewItem parameters are ignored.

See AppendMenu, GetMenuState, InsertMenu, ModifyMenu.

MF_STRING

Contains a pointer to a null-terminated string.

See AppendMenu, InsertMenu, ModifyMenu.

MF_SYSMENU

The menu is a System menu.

See WM_MENUCHAR, WM_MENUSELECT.

MF_UNCHECKED

Does not place a checkmark next to the item (default). If the application supplies check mark bitmaps (see the SetMenuItemBitmaps function), this flag displays the unchecked bitmap next to the menu item.

See AppendMenu, CheckMenuItem, InsertMenu, ModifyMenu.

MF_UNHILITE

Removes the highlighting from the menu item.

See HiliteMenuItem.

MH_CLEANUP

An application is freeing its DDE resources, causing the system to delete string handles that the application had created. (The application called the DdeUninitialize function.)

See MONHSZSTRUCT.

MH_CREATE

An application is creating a string handle. (The application called the DdeCreateStringHandle function.)

See MONHSZSTRUCT.

MH_DELETE

An application is deleting a string handle. (The application called the DdeFreeStringHandle function.)

See MONHSZSTRUCT.

MH_KEEP

An application is increasing the use count of a string handle. (The application called the DdeKeepStringHandle function.)

See MONHSZSTRUCT.

MHDR_DONE

Set by the device driver to indicate that it is finished with the data buffer and is returning it to the application.

See MIDIHDR.

MHDR_PREPARED

Set by Windows to indicate that the data buffer has been prepared with midiInPrepareHeader or midiOutPrepareHeader.

See MIDIHDR.

MIDI_CACHE_ALL

Cache all of the specified patches. If they can't all be cached, cache none, clear the KEYARRAY array,and return MMSYSERR_NOMEM.

See midiOutCacheDrumPatches, midiOutCachePatches.

MIDI_CACHE_BESTFIT

Cache all of the specified patches. If all patches can't be cached, cache as many patches as possible, change the KEYARRAY array to reflect which patches were cached, and return MMSYSERR_NOMEM.

See midiOutCacheDrumPatches, midiOutCachePatches.

MIDI_CACHE_QUERY

Change the KEYARRAY or PATCHARRAY array to indicate which patches are currently cached.

See midiOutCacheDrumPatches, midiOutCachePatches.

MIDI_MAPPER

Sets the port opened to the MIDI Mapper.

See MCI_SET.

MIDI_UNCACHE

Uncache the specified patches and clear the KEYARRAY or PATCHARRAY array.

See midiOutCacheDrumPatches, midiOutCachePatches.

MIDICAPS_CACHE

Supports patch caching.

See MIDIOUTCAPS.

MIDICAPS_LRVOLUME

Supports separate left and right volume control.

See MIDIOUTCAPS.

MIDICAPS_VOLUME

Supports volume control.

See MIDIOUTCAPS.

MIDIERR_NODEVICE

A port in the current MIDI map doesn't exist. This occurs only when opening the mapper.

See midiOutOpen.

MIDIERR_NOMAP

There is no current MIDI map. This occurs only when opening the mapper.

See midiOutOpen.

MIDIERR_NOTREADY

The hardware is busy with other data.

See midiOutLongMsg, midiOutShortMsg.

MIDIERR_STILLPLAYING

There are still buffers in the queue.

See midiInClose, midiInUnprepareHeader, midiOutClose, midiOutUnprepareHeader.

MIDIERR_UNPREPARED

lpmidih hasn't been prepared.

See midiInAddBuffer, midiOutLongMsg.

MK_CONTROL

Set if a CTRL key is down.

See WM_LBUTTONDBLCLK, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MOUSEMOVE, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP.

MK_LBUTTON

Set if the left mouse button is down.

See WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MOUSEMOVE, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP.

MK_MBUTTON

Set if the middle mouse button is down.

See WM_LBUTTONDBLCLK, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONDBLCLK, WM_MOUSEMOVE, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP.

MK_RBUTTON

Set if the right mouse button is down.

See WM_LBUTTONDBLCLK, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MOUSEMOVE, WM_RBUTTONDBLCLK.

MK_SHIFT

Set if a SHIFT key is down.

See WM_LBUTTONDBLCLK, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MOUSEMOVE, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP.

MM_ANISOTROPIC

Logical units are mapped to arbitrary units with arbitrarily scaled axes. Use the SetWindowExtEx and SetViewportExtEx functions to specify the desired units, orientation, and scaling.

See SetMapMode.

MM_HIENGLISH

Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is up.

See SetMapMode.

MM_HIMETRIC

Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is up.

See SetMapMode.

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 desired units and the orientation of the axes. Graphics Device Interface (GDI) makes adjustments as necessary to ensure the x and y units remain the same size (e.g. If you set the window extent, the viewport will be adjusted to keep the units isotropic).

See SetMapMode.

MM_LOENGLISH

Each logical unit is mapped to 0.01 inch. Positive x is to the right; positive y is up.

See SetMapMode.

MM_LOMETRIC

Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is up.

See SetMapMode.

MM_TEXT

Each logical unit is mapped to one device pixel. Positive x is to the right; positive y is down.

See SetMapMode.

MM_TWIPS

Each logical unit is mapped to one twentieth of a printer's point (1/1440 inch). Positive x is to the right; positive y is up.

See SetMapMode.

MMIO_ALLOCBUF

Opens a file for buffered I/O. To allocate a buffer larger or smaller than the default buffer size (8K), set the cchBuffer member of the MMIOINFO structure to the desired buffer size. If cchBuffer is zero, then the default buffer size is used. If you are providing your own I/O buffer, then the MMIO_ALLOCBUF flag should not be used.

See mmioOpen, MMIOINFO.

MMIO_COMPAT

Opens the file with compatibility mode,allowing any process on a given machine to open the file any number of times. mmioOpen fails if the file has been opened with any of the other sharing modes.

See mmioOpen, MMIOINFO.

MMIO_CREATE

Creates a new file. If the file already exists, it is truncated to zero length. For memory files, MMIO_CREATE indicates the end of the file is initially at the start of the buffer.

See mmioOpen, MMIOINFO.

MMIO_CREATELIST

Creates a "LIST" chunk.

See mmioCreateChunk.

MMIO_CREATERIFF

Creates a "RIFF" chunk.

See mmioCreateChunk.

MMIO_DELETE

Deletes a file. If this flag is specified, lpszFilename should not be NULL. The return value will be TRUE (cast to HMMIO) if the file was deleted successfully, FALSE otherwise. Do not call mmioClose for a file that has been deleted. If this flag is specified,all other file opening flags are ignored.

See mmioOpen.

MMIO_DENYNONE

Opens the file without denying other processes read or write access to the file. mmioOpen fails if the file has been opened in compatibility mode by any other process.

See mmioOpen, MMIOINFO.

MMIO_DENYREAD

Opens the file and denies other processes read access to the file. mmioOpen fails if the file has been opened in compatibility mode or for read access by any other process.

See mmioOpen, MMIOINFO.

MMIO_DENYWRITE

Opens the file and denies other processes write access to the file. mmioOpen fails if the file has been opened in compatibility or for write access by any other process.

See mmioOpen, MMIOINFO.

MMIO_EXCLUSIVE

Opens the file with exclusive mode,denying other processes both read and write access to the file. mmioOpen fails if the file has been opened in any other mode for read or write access, even by the current process.

See mmioOpen, MMIOINFO.

MMIO_EXIST

Determines whether the specified file exists and creates a fully qualified filename from the path specified in lpszFileName. The fully qualified filename is placed back into lpszFileName. The return value will be TRUE (cast to HMMIO) if the qualification was successful and the file exists, FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file.

See mmioOpen.

MMIO_FHOPEN

If the file was opened by passing the Windows file handle of an already-opened file to mmioOpen, then using this flag tells mmioClose to close the MMIO file handle, but not the Windows file handle. (This is done by the I/O Proc).

See mmioClose.

MMIO_FINDCHUNK

Searches for a chunk with the specified chunk ID.

See mmioDescend.

MMIO_FINDLIST

Searches for a chunk with chunk ID "LIST" and with the specified form type.

See mmioDescend.

MMIO_FINDPROC

Searches for the specified I/O procedure.

See mmioInstallIOProc.

MMIO_FINDRIFF

Searches for a chunk with chunk ID "RIFF" and with the specified form type.

See mmioDescend.

MMIO_GETTEMP

Creates a temporary filename, optionally using the parameters passed in lpszFileName to determine the temporary name. 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 lpszFileName. The return value will be TRUE (cast to HMMIO) if the temporary filename was created successfully,FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file. This flag overrides all other flags.

See mmioOpen.

MMIO_GLOBALPROC

This flag is a modifier to the install flag,and indicates the I/O procedure should be installed for global use. This flag is ignored on removal or find.

See mmioInstallIOProc.

MMIO_INSTALLPROC

Installs the specified I/O procedure.

See mmioInstallIOProc.

MMIO_PARSE

Creates a fully qualified filename from the path specified in lpszFileName. The fully qualified filename is placed back into lpszFileName. The return value will be TRUE (cast to HMMIO) if the qualification was successful, FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file. If this flag is specified, all other file opening flags are ignored.

See mmioOpen.

MMIO_READ

Opens the file for reading only. This is the default, if MMIO_WRITE and MMIO_READWRITE are not specified.

See mmioAdvance, mmioOpen, MMIOINFO.

MMIO_READWRITE

Opens the file for both reading and writing.

See mmioOpen, MMIOINFO.

MMIO_REMOVEPROC

Removes the specified I/O procedure.

See mmioInstallIOProc.

MMIO_TOUPPER

Convert all characters to uppercase.

See mmioStringToFOURCC.

MMIO_WRITE

Opens the file for writing. You should not read from a file opened in this mode.

See mmioAdvance, mmioOpen, MMIOINFO.

MMIOERR_CANNOTCLOSE

There was a Windows file system error when the I/O Proc attempted to close the Windows file.

See mmioClose.

MMIOERR_CANNOTEXPAND

The specified memory file cannot be expanded, probably because the adwInfo[0] member was set to zero in the initial call to mmioOpen.

See mmioAdvance.

MMIOERR_CANNOTREAD

An error occurred while re-filling the buffer.

See mmioAdvance.

MMIOERR_CANNOTSEEK

There was an error while seeking to the end of the chunk.

See mmioAscend, mmioCreateChunk.

MMIOERR_CANNOTWRITE

The contents of the buffer could not be written to disk.

See mmioAdvance, mmioAscend, mmioClose, mmioCreateChunk, mmioFlush, mmioSetBuffer.

MMIOERR_OUTOFMEMORY

There was not enough memory to expand a memory file for further writing.

See mmioAdvance, mmioSetBuffer.

MMIOERR_UNBUFFERED

The specified file is not opened for buffered I/O.

See mmioAdvance.

MMIOM_CANNOTOPEN

Specified file could not be opened.

See MMIOM_OPEN.

MMIOM_OUTOFMEMORY

Not enough memory to perform operation.

See MMIOM_OPEN.

MMSYSERR_ALLOCATED

Specified resource is already allocated.

See midiInOpen, midiOutOpen, waveInOpen, waveOutOpen.

MMSYSERR_BADDEVICEID

Specified device ID is out of range.

See auxGetDevCaps.

MMSYSERR_BADDEVICEID

Specified device ID is out of range.

See auxGetVolume, auxSetVolume, midiInGetDevCaps, midiInOpen, midiOutGetDevCaps, midiOutOpen, waveInGetDevCaps, waveInOpen, waveOutGetDevCaps, waveOutOpen.

MMSYSERR_BADERRNUM

Specified error number is out of range.

See midiInGetErrorText, midiOutGetErrorText, waveInGetErrorText, waveOutGetErrorText.

MMSYSERR_HANDLEBUSY

The handle is in use on another thread.

See waveInAddBuffer, waveInGetID, waveInPrepareHeader, waveInReset, waveInStart, waveInStop, waveInUnprepareHeader, waveOutBreakLoop, waveOutClose, waveOutGetID, waveOutGetPitch, waveOutGetPlaybackRate, waveOutGetPosition, waveOutPause, waveOutPrepareHeader, waveOutReset, waveOutRestart, waveOutSetPitch, waveOutSetPlaybackRate, waveOutUnprepareHeader, waveOutWrite.

MMSYSERR_INVALHANDLE

Specified device handle is invalid.

See midiInAddBuffer, midiInClose, midiInGetID, midiInPrepareHeader, midiInReset, midiInStart, midiInStop, midiInUnprepareHeader, midiOutCacheDrumPatches, midiOutCachePatches, midiOutClose, midiOutGetID, midiOutGetVolume, midiOutLongMsg, midiOutPrepareHeader, midiOutReset, midiOutSetVolume, midiOutShortMsg, midiOutUnprepareHeader, waveInAddBuffer, waveInClose, waveInGetID, waveInGetPosition, waveInPrepareHeader, waveInReset, waveInStart, waveInStop, waveInUnprepareHeader, waveOutBreakLoop, waveOutClose, waveOutGetID, waveOutGetPitch, waveOutGetPlaybackRate, waveOutGetPosition, waveOutGetVolume, waveOutPause, waveOutPrepareHeader, waveOutReset, waveOutRestart, waveOutSetPitch, waveOutSetPlaybackRate, waveOutSetVolume, waveOutUnprepareHeader, waveOutWrite.

MMSYSERR_NODRIVER

The driver failed to install.

See auxGetDevCaps, auxGetVolume, auxSetVolume, joyGetDevCaps, joyGetPos, joyGetThreshold, joyReleaseCapture, joySetCapture, joySetThreshold, midiInGetDevCaps, midiOutGetDevCaps, midiOutGetVolume, midiOutSetVolume, waveInGetDevCaps, waveOutGetDevCaps, waveOutGetVolume, waveOutSetVolume.

MMSYSERR_NOMEM

Unable to allocate or lock memory.

See midiInOpen, midiInPrepareHeader, midiOutCacheDrumPatches, midiOutCachePatches, midiOutGetDevCaps, midiOutOpen, midiOutPrepareHeader, waveInOpen, waveInPrepareHeader, waveOutOpen, waveOutPrepareHeader.

MMSYSERR_NOTSUPPORTED

Function isn't supported.

See midiOutCacheDrumPatches, midiOutCachePatches, midiOutGetVolume, midiOutSetVolume, waveOutGetPitch, waveOutGetPlaybackRate, waveOutGetVolume, waveOutSetPitch, waveOutSetPlaybackRate, waveOutSetVolume.

MOD_ALT

Either ALT key must be held down.

See RegisterHotKey.

MOD_CONTROL

Either CTRL key must be held down.

See RegisterHotKey.

MOD_FMSYNTH

Indicates the device is an FM synthesizer.

See MIDIOUTCAPS.

MOD_MAPPER

Indicates the device is the Microsoft MIDI Mapper.

See MIDIOUTCAPS.

MOD_MIDIPORT

Indicates the device is a MIDI hardware port.

See MIDIOUTCAPS.

MOD_SHIFT

Either SHIFT key must be held down.

See RegisterHotKey.

MOD_SQSYNTH

Indicates the device is a square wave synthesizer.

See MIDIOUTCAPS.

MOUSEEVENTF_MOVE

Indicates that movement occurred.

See mouse_event.

MOUSEEVENTF_LEFTDOWN

Indicates that the left button changed to down.

See mouse_event.

MOUSEEVENTF_LEFTUP

Indicates that the left button changed to up.

See mouse_event.

MOUSEEVENTF_RIGHTDOWN

Indicates that the right button changed to down.

See mouse_event.

MOUSEEVENTF_RIGHTUP

Indicates that the right button changed to up.

See mouse_event.

MOUSEEVENTF_MIDDLEDOWN

Indicates that the middle button changed to down.

See mouse_event.

MOUSEEVENTF_MIDDLEUP

Indicates that the middle button changed to up.

See mouse_event.

MOUSEEVENTF_ABSOLUTE

Indicates that the dx and dy parameters contain normalized absolute coordinates.

See mouse_event.

MOUSE_MOVED

Indicates a change in mouse position.

See MOUSE_EVENT_RECORD.

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.

See MoveFileEx.

MOVEFILE_DELAY_UNTIL_REBOOT

The function will not move the file until the system is rebooted. The system moves the file immediately after AUTOCHK is executed, but before creating any paging files. Therefore, this parameter enables the function to delete paging files from previous boots.

See MoveFileEx.

MOVEFILE_REPLACE_EXISTING

If a file of the name specified by lpszNew already exists, the function replaces its contents with those specified by lpszExisting.

See MoveFileEx.

MS_CTS_ON

Clear-To-Send (CTS) signal is on.

See GetCommModemStatus.

MS_DSR_ON

Data-Set-Ready (DSR) signal is on.

See GetCommModemStatus.

MS_RING_ON

Ring Indicator signal is on.

See GetCommModemStatus.

MS_RLSD_ON

Receive-Line-Signal-Detect (RLSD) signal is on.

See GetCommModemStatus.

MSGF_DDEMGR

Indicates the input event occurred while the Dynamic Data Exchange Management Library (DDEML) was waiting for a synchronous transaction to complete. For more information about DDEML, see DDEML

See MessageProc.

MSGF_DIALOGBOX

Indicates the input event occurred in a message box or dialog box.

See MessageProc, SysMsgProc, WM_ENTERIDLE.

MSGF_MENU

Indicates the input event occurred in a menu.

See MessageProc, SetWindowsHook, SysMsgProc, WM_ENTERIDLE.

MSGF_MESSAGEBOX

Processing messages inside the MessageBox function.

See SetWindowsHook.

MSGF_NEXTWINDOW

Indicates the input event occurred as a result of the user pressing the ALT+TAB key combination to activate a different window.

See MessageProc, SysMsgProc.

MSGF_SCROLLBAR

Indicates the input event occurred in a scroll bar.

See MessageProc, SysMsgProc.

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.

See ModifyWorldTransform.

MWT_LEFTMULTIPLY

Multiplies the current transformation by the data in the XFORM structure. (The data in the XFORM structure becomes the left multiplicand while the data for the current transformation becomes the right multiplicand.)

See ModifyWorldTransform.

MWT_RIGHTMULTIPLY

Multiplies the current transformation by the data in the XFORM structure. (The data in the XFORM structure becomes the right multiplicand while the data for the current transformation becomes the left multiplicand.)

See ModifyWorldTransform.


ACCESS_ALLOWED_ACE_TYPE
ACCESS_ALLOWED_ACE_TYPE  (0x0)  winnt.h

Access-allowed ACE (defined by the ACCESS_ALLOWED_ACE structure) See ACE_HEADER.


FN_ACCESS_ALLOWED_ACE_TYPE
ACCESS_ALLOWED_ACE_TYPE  (0x0)  winnt.h


ACCESS_DENIED_ACE_TYPE
ACCESS_DENIED_ACE_TYPE  (0x1)  winnt.h

Access-denied ACE (defined by the ACCESS_DENIED_ACE structure) See ACE_HEADER.


FN_ACCESS_DENIED_ACE_TYPE
ACCESS_DENIED_ACE_TYPE  (0x1)  winnt.h


ACSLAN_STATUS_COMMAND_ACCEPTED
ACSLAN_STATUS_COMMAND_ACCEPTED  0  dlcapi.h

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 other timing considerations. This return code does not mean that the command completed successfully. The caller must check the uchDlcStatus field in the CCB to determine whether the request succeeded or failed. See AcsLan


FN_ACSLAN_STATUS_COMMAND_ACCEPTED
ACSLAN_STATUS_COMMAND_ACCEPTED  0  dlcapi.h


ACSLAN_STATUS_INVALID_CCB_POINTER
ACSLAN_STATUS_INVALID_CCB_POINTER  1  dlcapi.h

A pointer in the CCB structure or the parameter table is invalid. See AcsLan


FN_ACSLAN_STATUS_INVALID_CCB_POINTER
ACSLAN_STATUS_INVALID_CCB_POINTER  1  dlcapi.h


ACSLAN_STATUS_CCB_IN_ERROR
ACSLAN_STATUS_CCB_IN_ERROR  2  dlcapi.h

A problem was detected with the CCB. The caller should check the values in the CCB and resubmit it. See AcsLan


FN_ACSLAN_STATUS_CCB_IN_ERROR
ACSLAN_STATUS_CCB_IN_ERROR  2  dlcapi.h


ACSLAN_STATUS_CHAINED_CCB_IN_ERROR
ACSLAN_STATUS_CHAINED_CCB_IN_ERROR  3  dlcapi.h

A problem was detected with a CCB in a chain of CCBs. See AcsLan


FN_ACSLAN_STATUS_CHAINED_CCB_IN_ERROR
ACSLAN_STATUS_CHAINED_CCB_IN_ERROR  3  dlcapi.h


ACSLAN_STATUS_SYSTEM_ERROR
ACSLAN_STATUS_SYSTEM_ERROR  4  dlcapi.h

This code is not used. See AcsLan


FN_ACSLAN_STATUS_SYSTEM_ERROR
ACSLAN_STATUS_SYSTEM_ERROR  4  dlcapi.h


ACSLAN_STATUS_SYSTEM_STATUS
ACSLAN_STATUS_SYSTEM_STATUS  5  dlcapi.h

This code is not used. See AcsLan


FN_ACSLAN_STATUS_SYSTEM_STATUS
ACSLAN_STATUS_SYSTEM_STATUS  5  dlcapi.h


ACSLAN_STATUS_INVALID_COMMAND
ACSLAN_STATUS_INVALID_COMMAND  6  dlcapi.h

The command in the uchDlcCommand field of the CCB is unrecognized See AcsLan


FN_ACSLAN_STATUS_INVALID_COMMAND
ACSLAN_STATUS_INVALID_COMMAND  6  dlcapi.h


AD_CLOCKWISE
AD_CLOCKWISE  2  wingdi.h

Figures drawn clockwise. See GetArcDirection, SetArcDirection.


FN_AD_CLOCKWISE
AD_CLOCKWISE  2  wingdi.h


AD_COUNTERCLOCKWISE
AD_COUNTERCLOCKWISE  1  wingdi.h

Figures drawn counterclockwise. See GetArcDirection, SetArcDirection.


FN_AD_COUNTERCLOCKWISE
AD_COUNTERCLOCKWISE  1  wingdi.h


ALTERNATE
ALTERNATE  1  wingdi.h

Selects alternate mode (fills area between odd-numbered and even-numbered polygon sides on each scan line). See CreatePolygonRgn, CreatePolyPolygonRgn, GetPolyFillMode, SetPolyFillMode.


FN_ALTERNATE
ALTERNATE  1  wingdi.h


ANSI_FIXED_FONT
ANSI_FIXED_FONT  11  wingdi.h

Windows fixed-pitch system font See GetStockObject.


FN_ANSI_FIXED_FONT
ANSI_FIXED_FONT  11  wingdi.h


ANSI_VAR_FONT
ANSI_VAR_FONT  12  wingdi.h

Windows variable-pitch system font See GetStockObject.


FN_ANSI_VAR_FONT
ANSI_VAR_FONT  12  wingdi.h


APPCLASS_MONITOR
APPCLASS_MONITOR  0x00000001L  ddeml.h

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 Comments section. See DdeInitialize.


FN_APPCLASS_MONITOR
APPCLASS_MONITOR  0x00000001L  ddeml.h


APPCLASS_STANDARD
APPCLASS_STANDARD  0x00000000L  ddeml.h

Registers the application as a standard (nonmonitoring) DDEML application. See DdeInitialize.


FN_APPCLASS_STANDARD
APPCLASS_STANDARD  0x00000000L  ddeml.h


APPCMD_CLIENTONLY
APPCMD_CLIENTONLY  0x00000010L  ddeml.h

Prevents the application from becoming a server in a DDE conversation. The application can be only a client. This flag reduces resource consumption by the DDEML. It includes the functionality of the CBF_FAIL_ALLSVRXACTIONS flag. See DdeInitialize.


FN_APPCMD_CLIENTONLY
APPCMD_CLIENTONLY  0x00000010L  ddeml.h


APPCMD_FILTERINITS
APPCMD_FILTERINITS  0x00000020L  ddeml.h

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 this flag. On subsequent calls to DdeInitialize, not specifying this flag turns off the application's service-name filters; specifying this flag turns on the application's service-name filters. See DdeInitialize.


FN_APPCMD_FILTERINITS
APPCMD_FILTERINITS  0x00000020L  ddeml.h


ASPECTX
ASPECTX  40  wingdi.h

Relative width of a device pixel used for line drawing. See GetDeviceCaps.


FN_ASPECTX
ASPECTX  40  wingdi.h


ASPECTXY
ASPECTXY  44  wingdi.h

Diagonal width of the device pixel used for line drawing. See GetDeviceCaps.


FN_ASPECTXY
ASPECTXY  44  wingdi.h


ASPECTY
ASPECTY  42  wingdi.h

Relative height of a device pixel used for line drawing. See GetDeviceCaps.


FN_ASPECTY
ASPECTY  42  wingdi.h


AUX_MAPPER
AUX_MAPPER  (-1)    mmsystem.h

Auxiliary audio mapper. The function will return an error if no auxiliary audio mapper is installed. See auxGetDevCaps, auxOutMessage.


FN_AUX_MAPPER
AUX_MAPPER  (-1)    mmsystem.h


AUXCAPS_AUXIN
AUXCAPS_AUXIN  2  mmsystem.h

Audio output from auxiliary input jacks. See AUXCAPS.


FN_AUXCAPS_AUXIN
AUXCAPS_AUXIN  2  mmsystem.h


AUXCAPS_CDAUDIO
AUXCAPS_CDAUDIO  1  mmsystem.h

Audio output from an internal CD-ROM drive. See AUXCAPS.


FN_AUXCAPS_CDAUDIO
AUXCAPS_CDAUDIO  1  mmsystem.h


AUXCAPS_LRVOLUME
AUXCAPS_LRVOLUME  0x00000002  mmsystem.h

Supports separate left and right volume control. See AUXCAPS.


FN_AUXCAPS_LRVOLUME
AUXCAPS_LRVOLUME  0x00000002  mmsystem.h


AUXCAPS_VOLUME
AUXCAPS_VOLUME  0x00000001  mmsystem.h

Supports volume control. See AUXCAPS.


FN_AUXCAPS_VOLUME
AUXCAPS_VOLUME  0x00000001  mmsystem.h


BACKUP_ALTERNATE_DATA
BACKUP_ALTERNATE_DATA  0x00000004  winbase.h

Alternate data streams See WIN32_STREAM_ID.


FN_BACKUP_ALTERNATE_DATA
BACKUP_ALTERNATE_DATA  0x00000004  winbase.h


BACKUP_DATA
BACKUP_DATA  0x00000001  winbase.h

Standard data See WIN32_STREAM_ID.


FN_BACKUP_DATA
BACKUP_DATA  0x00000001  winbase.h


BACKUP_EA_DATA
BACKUP_EA_DATA  0x00000002  winbase.h

Extended attribute data See WIN32_STREAM_ID.


FN_BACKUP_EA_DATA
BACKUP_EA_DATA  0x00000002  winbase.h


BACKUP_LINK
BACKUP_LINK  0x00000005  winbase.h

Hard link information See WIN32_STREAM_ID.


FN_BACKUP_LINK
BACKUP_LINK  0x00000005  winbase.h


BACKUP_SECURITY_DATA
BACKUP_SECURITY_DATA  0x00000003  winbase.h

NT security descriptor data See WIN32_STREAM_ID.


FN_BACKUP_SECURITY_DATA
BACKUP_SECURITY_DATA  0x00000003  winbase.h


BI_RGB
BI_RGB  0L  wingdi.h

Specifies that the bitmap is not compressed. See BITMAPINFOHEADER.


FN_BI_RGB
BI_RGB  0L  wingdi.h


BI_RLE4
BI_RLE4  2L  wingdi.h

Specifies a run-length encoded 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 indexes. For more information, see the following Comments section. See BITMAPINFOHEADER.


FN_BI_RLE4
BI_RLE4  2L  wingdi.h


BI_RLE8
BI_RLE8  1L  wingdi.h

Specifies a run-length encoded 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. See the Comments section for more information. See BITMAPINFOHEADER.


FN_BI_RLE8
BI_RLE8  1L  wingdi.h


BITSPIXEL
BITSPIXEL  12  wingdi.h

Number of adjacent color bits for each pixel. See GetDeviceCaps.


FN_BITSPIXEL
BITSPIXEL  12  wingdi.h


BLACK_BRUSH
BLACK_BRUSH  4  wingdi.h

Black brush See GetStockObject.


FN_BLACK_BRUSH
BLACK_BRUSH  4  wingdi.h


BLACK_PEN
BLACK_PEN  7  wingdi.h

Black pen See GetStockObject.


FN_BLACK_PEN
BLACK_PEN  7  wingdi.h


BLACKNESS
BLACKNESS  (DWORD)0x00000042  wingdi.h

Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.) See BitBlt, PatBlt.


FN_BLACKNESS
BLACKNESS  (DWORD)0x00000042  wingdi.h


BLACKONWHITE
BLACKONWHITE  1  wingdi.h

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. See SetStretchBltMode.


FN_BLACKONWHITE
BLACKONWHITE  1  wingdi.h


BMF_DIB

The first scanline in the buffer at which lppBits points is the bottom scanline. See CreateDIBSection.


BMF_TOPDOWN

The first scanline in the buffer at which lppBits points is the top scanline. See CreateDIBSection.


BS_DIBPATTERN
BS_DIBPATTERN  5  wingdi.h

Specifies a pattern brush defined by a device-independent bitmap (DIB) specification. See EXTLOGPEN, LOGBRUSH.


FN_BS_DIBPATTERN
BS_DIBPATTERN  5  wingdi.h


BS_HATCHED
BS_HATCHED  2  wingdi.h

Specifies a hatched brush. See EXTLOGPEN, LOGBRUSH.


FN_BS_HATCHED
BS_HATCHED  2  wingdi.h


BS_HOLLOW
BS_HOLLOW  BS_NULL  wingdi.h

Specifies a hollow or NULL brush. See EXTLOGPEN, LOGBRUSH.


FN_BS_HOLLOW
BS_HOLLOW  BS_NULL  wingdi.h


BS_NULL
BS_NULL  1  wingdi.h

Specifies a hollow or NULL brush. Same as BS_HOLLOW. See LOGBRUSH.


FN_BS_NULL
BS_NULL  1  wingdi.h


BS_PATTERN
BS_PATTERN  3  wingdi.h

Specifies a pattern brush defined by a memory bitmap. See EXTLOGPEN, LOGBRUSH.


FN_BS_PATTERN
BS_PATTERN  3  wingdi.h


BS_SOLID
BS_SOLID  0  wingdi.h

Specifies a solid brush. See EXTLOGPEN, LOGBRUSH.


FN_BS_SOLID
BS_SOLID  0  wingdi.h


BUTTON

Designates a small rectangular child window that represents a button the user can turn on or off by clicking. You can use button controls alone or in groups, and they can either be labeled or appear without text. Button controls typically change appearance when the user clicks them. See CreateWindow.


CALL_PENDING
CALL_PENDING  0x02  nb30.h

The session is attempting to connect to a remote computer. See SESSION_BUFFER.


FN_CALL_PENDING
CALL_PENDING  0x02  nb30.h


CALLBACK_FUNCTION
CALLBACK_FUNCTION  0x00030000l  mmsystem.h

If this flag is specified, dwCallback is assumed to be a callback procedure address. See midiInOpen, midiOutOpen, waveInOpen, waveOutOpen.


FN_CALLBACK_FUNCTION
CALLBACK_FUNCTION  0x00030000l  mmsystem.h


CALLBACK_WINDOW
CALLBACK_WINDOW  0x00010000l  mmsystem.h

If this flag is specified, dwCallback is assumed to be a window handle. See midiInOpen, midiOutOpen, waveInOpen, waveOutOpen.


FN_CALLBACK_WINDOW
CALLBACK_WINDOW  0x00010000l  mmsystem.h


CAPSLOCK_ON
CAPSLOCK_ON  0x0080  wincon.h

The CAPS LOCK light is on. See KEY_EVENT_RECORD.


FN_CAPSLOCK_ON
CAPSLOCK_ON  0x0080  wincon.h


CB_OKAY
CB_OKAY  0  winuser.h

A combo-box message return value that indicates success.


FN_CB_OKAY
CB_OKAY  0  winuser.h


CB_ERR
CB_ERR  (-1)  winuser.h

A combo box message return value that indicates that an error occurred.


FN_CB_ERR
CB_ERR  (-1)  winuser.h


CB_ERRSPACE
CB_ERRSPACE  (-2)  winuser.h

A combo box message return value that indicates the occurrence of an error related to insufficient string storage space.


FN_CB_ERRSPACE
CB_ERRSPACE  (-2)  winuser.h


CBF_FAIL_ADVISES
CBF_FAIL_ADVISES  0x00004000  ddeml.h

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. See DdeInitialize.


FN_CBF_FAIL_ADVISES
CBF_FAIL_ADVISES  0x00004000  ddeml.h


CBF_FAIL_ALLSVRXACTIONS
CBF_FAIL_ALLSVRXACTIONS  0x0003f000  ddeml.h

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. See DdeInitialize.


FN_CBF_FAIL_ALLSVRXACTIONS
CBF_FAIL_ALLSVRXACTIONS  0x0003f000  ddeml.h


CBF_FAIL_CONNECTIONS
CBF_FAIL_CONNECTIONS  0x00002000  ddeml.h

Prevents the callback function from receiving XTYP_CONNECT and XTYP_WILDCONNECT transactions. See DdeInitialize.


FN_CBF_FAIL_CONNECTIONS
CBF_FAIL_CONNECTIONS  0x00002000  ddeml.h


CBF_FAIL_EXECUTES
CBF_FAIL_EXECUTES  0x00008000  ddeml.h

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. See DdeInitialize.


FN_CBF_FAIL_EXECUTES
CBF_FAIL_EXECUTES  0x00008000  ddeml.h


CBF_FAIL_POKES
CBF_FAIL_POKES  0x00010000  ddeml.h

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. See DdeInitialize.


FN_CBF_FAIL_POKES
CBF_FAIL_POKES  0x00010000  ddeml.h


CBF_FAIL_REQUESTS
CBF_FAIL_REQUESTS  0x00020000  ddeml.h

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. See DdeInitialize.


FN_CBF_FAIL_REQUESTS
CBF_FAIL_REQUESTS  0x00020000  ddeml.h


CBF_FAIL_SELFCONNECTIONS
CBF_FAIL_SELFCONNECTIONS  0x00001000  ddeml.h

Prevents the callback function from receiving XTYP_CONNECT transactions from the application's own instance. This 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. See DdeInitialize.


FN_CBF_FAIL_SELFCONNECTIONS
CBF_FAIL_SELFCONNECTIONS  0x00001000  ddeml.h


CBF_SKIP_ALLNOTIFICATIONS
CBF_SKIP_ALLNOTIFICATIONS  0x003c0000  ddeml.h

Prevents the callback function from receiving any notifications. This flag is equivalent combining all CBF_SKIP_ flags. See DdeInitialize.


FN_CBF_SKIP_ALLNOTIFICATIONS
CBF_SKIP_ALLNOTIFICATIONS  0x003c0000  ddeml.h


CBF_SKIP_CONNECT_CONFIRMS
CBF_SKIP_CONNECT_CONFIRMS  0x00040000  ddeml.h

Prevents the callback function from receiving XTYP_CONNECT_CONFIRM notifications. See DdeInitialize.


FN_CBF_SKIP_CONNECT_CONFIRMS
CBF_SKIP_CONNECT_CONFIRMS  0x00040000  ddeml.h


CBF_SKIP_DISCONNECTS
CBF_SKIP_DISCONNECTS  0x00200000  ddeml.h

Prevents the callback function from receiving XTYP_DISCONNECT notifications. See DdeInitialize.


FN_CBF_SKIP_DISCONNECTS
CBF_SKIP_DISCONNECTS  0x00200000  ddeml.h


CBF_SKIP_REGISTRATIONS
CBF_SKIP_REGISTRATIONS  0x00080000  ddeml.h

Prevents the callback function from receiving XTYP_REGISTER notifications. See DdeInitialize.


FN_CBF_SKIP_REGISTRATIONS
CBF_SKIP_REGISTRATIONS  0x00080000  ddeml.h


CBF_SKIP_UNREGISTRATIONS
CBF_SKIP_UNREGISTRATIONS  0x00100000  ddeml.h

Prevents the callback function from receiving XTYP_UNREGISTER notifications. See DdeInitialize.


FN_CBF_SKIP_UNREGISTRATIONS
CBF_SKIP_UNREGISTRATIONS  0x00100000  ddeml.h


CC_ENABLEHOOK
CC_ENABLEHOOK  0x00000010  commdlg.h

Enables the hook function specified in the lpfnHook member. See CHOOSECOLOR.


FN_CC_ENABLEHOOK
CC_ENABLEHOOK  0x00000010  commdlg.h


CC_ENABLETEMPLATE
CC_ENABLETEMPLATE  0x00000020  commdlg.h

Causes the system to create the dialog box by using the dialog template identified by the hInstance and lpTemplateName members. See CHOOSECOLOR.


FN_CC_ENABLETEMPLATE
CC_ENABLETEMPLATE  0x00000020  commdlg.h


CC_ENABLETEMPLATEHANDLE
CC_ENABLETEMPLATEHANDLE  0x00000040  commdlg.h

Indicates that the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpTemplateName member if this flag is specified. See CHOOSECOLOR.


FN_CC_ENABLETEMPLATEHANDLE
CC_ENABLETEMPLATEHANDLE  0x00000040  commdlg.h


CC_FULLOPEN
CC_FULLOPEN  0x00000002  commdlg.h

Causes the entire dialog box to appear when the dialog box is created, including the portion that allows the user to create custom colors. Without this flag, the user must select the "Define Custom Color..." push button to see this portion of the dialog box. See CHOOSECOLOR.


FN_CC_FULLOPEN
CC_FULLOPEN  0x00000002  commdlg.h


CC_PREVENTFULLOPEN
CC_PREVENTFULLOPEN  0x00000004  commdlg.h

Disables the "Define Custom Colors..." push button, preventing the user from creating custom colors. See CHOOSECOLOR.


FN_CC_PREVENTFULLOPEN
CC_PREVENTFULLOPEN  0x00000004  commdlg.h


CC_RGBINIT
CC_RGBINIT  0x00000001  commdlg.h

Causes the dialog box to use the color specified in the rgbResult member as the initial color selection. See CHOOSECOLOR.


FN_CC_RGBINIT
CC_RGBINIT  0x00000001  commdlg.h


CC_SHOWHELP
CC_SHOWHELP  0x00000008  commdlg.h

Causes the dialog box to show the Help push button. The hwndOwner member must not be NULL if this option is specified. See CHOOSECOLOR.


FN_CC_SHOWHELP
CC_SHOWHELP  0x00000008  commdlg.h


CDERR_FINDRESFAILURE
CDERR_FINDRESFAILURE  0x0006  cderr.h

Specifies the common dialog box procedure failed to find a specified resource. See CommDlgExtendedError.


FN_CDERR_FINDRESFAILURE
CDERR_FINDRESFAILURE  0x0006  cderr.h


CDERR_INITIALIZATION
CDERR_INITIALIZATION  0x0002  cderr.h

Specifies the common dialog box procedure failed during initialization. This error often occurs when insufficient memory is found. See CommDlgExtendedError.


FN_CDERR_INITIALIZATION
CDERR_INITIALIZATION  0x0002  cderr.h


CDERR_LOADRESFAILURE
CDERR_LOADRESFAILURE  0x0007  cderr.h

Specifies the common dialog box procedure failed to load a specified resource. See CommDlgExtendedError.


FN_CDERR_LOADRESFAILURE
CDERR_LOADRESFAILURE  0x0007  cderr.h


CDERR_LOADSTRFAILURE
CDERR_LOADSTRFAILURE  0x0005  cderr.h

Specifies the common dialog box procedure failed to load a specified string. See CommDlgExtendedError.


FN_CDERR_LOADSTRFAILURE
CDERR_LOADSTRFAILURE  0x0005  cderr.h


CDERR_LOCKRESFAILURE
CDERR_LOCKRESFAILURE  0x0008  cderr.h

Specifies the common dialog box procedure failed to lock a specified resource. See CommDlgExtendedError.


FN_CDERR_LOCKRESFAILURE
CDERR_LOCKRESFAILURE  0x0008  cderr.h


CDERR_MEMALLOCFAILURE
CDERR_MEMALLOCFAILURE  0x0009  cderr.h

Specifies the common dialog box procedure was unable to allocate memory for internal structures. See CommDlgExtendedError.


FN_CDERR_MEMALLOCFAILURE
CDERR_MEMALLOCFAILURE  0x0009  cderr.h


CDERR_MEMLOCKFAILURE
CDERR_MEMLOCKFAILURE  0x000A  cderr.h

Specifies the common dialog box procedure was unable to lock the memory associated with a handle. See CommDlgExtendedError.


FN_CDERR_MEMLOCKFAILURE
CDERR_MEMLOCKFAILURE  0x000A  cderr.h


CDERR_NOHINSTANCE
CDERR_NOHINSTANCE  0x0004  cderr.h

Specifies the ENABLETEMPLATE flag was set in the Flags member of a structure for the corresponding common dialog box but the application failed to provide a corresponding instance handle. See CommDlgExtendedError.


FN_CDERR_NOHINSTANCE
CDERR_NOHINSTANCE  0x0004  cderr.h


CDERR_NOHOOK
CDERR_NOHOOK  0x000B  cderr.h

Specifies the ENABLEHOOK flag was set in the Flags member of a structure for the corresponding common dialog box but the application failed to provide a pointer to a corresponding hook function. See CommDlgExtendedError.


FN_CDERR_NOHOOK
CDERR_NOHOOK  0x000B  cderr.h


CDERR_NOTEMPLATE
CDERR_NOTEMPLATE  0x0003  cderr.h

Specifies the ENABLETEMPLATE flag was set in the Flags member of a structure for the corresponding common dialog box but the application failed to provide a corresponding template. See CommDlgExtendedError.


FN_CDERR_NOTEMPLATE
CDERR_NOTEMPLATE  0x0003  cderr.h


CDERR_REGISTERMSGFAIL
CDERR_REGISTERMSGFAIL  0x000C  cderr.h

Specifies the RegisterWindowMessage function returned an error value when called by the common dialog box procedure. See CommDlgExtendedError.


FN_CDERR_REGISTERMSGFAIL
CDERR_REGISTERMSGFAIL  0x000C  cderr.h


CDERR_STRUCTSIZE
CDERR_STRUCTSIZE  0x0001  cderr.h

Specifies as invalid the lStructSize member of a structure for the corresponding common dialog box. See CommDlgExtendedError.


FN_CDERR_STRUCTSIZE
CDERR_STRUCTSIZE  0x0001  cderr.h


CF_ANSIONLY
CF_ANSIONLY  0x00000400L  commdlg.h

Specifies the ChooseFont function should only allow the selection of fonts using the ANSI character set. (If this flag is set, the user will not be able to select a font that only contains symbols.) See CHOOSEFONT.


FN_CF_ANSIONLY
CF_ANSIONLY  0x00000400L  commdlg.h


CF_APPLY
CF_APPLY  0x00000200L  commdlg.h

Specifies the ChooseFont function should enable the Apply button. See CHOOSEFONT.


FN_CF_APPLY
CF_APPLY  0x00000200L  commdlg.h


CF_BITMAP
CF_BITMAP  2  winuser.h

A handle of a bitmap (HBITMAP). See SetClipboardData.


FN_CF_BITMAP
CF_BITMAP  2  winuser.h


CF_BOTH
CF_BOTH  (CF_SCREENFONTS | CF_PRINTERFONTS)  commdlg.h

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. See CHOOSEFONT.


FN_CF_BOTH
CF_BOTH  (CF_SCREENFONTS | CF_PRINTERFONTS)  commdlg.h


CF_DIB
CF_DIB  8  winuser.h

A memory object containing a BITMAPINFO structure followed by the bitmap bits. See SetClipboardData.


FN_CF_DIB
CF_DIB  8  winuser.h


CF_DIF
CF_DIF  5  winuser.h

Software Arts' Data Interchange Format. See SetClipboardData.


FN_CF_DIF
CF_DIF  5  winuser.h


CF_DSPBITMAP
CF_DSPBITMAP  0x0082  winuser.h

Bitmap display format associated with private format. The hData parameter must be a handle to data that can be displayed in bitmap format in lieu of the privately formatted data. See SetClipboardData.


FN_CF_DSPBITMAP
CF_DSPBITMAP  0x0082  winuser.h


CF_DSPENHMETAFILE
CF_DSPENHMETAFILE  0x008E  winuser.h

Enhanced metafile display format associated with private format. The hData parameter must be a handle to data that can be displayed in enhanced metafile format in lieu of the privately formatted data. See SetClipboardData.


FN_CF_DSPENHMETAFILE
CF_DSPENHMETAFILE  0x008E  winuser.h


CF_DSPMETAFILEPICT
CF_DSPMETAFILEPICT  0x0083  winuser.h

Metafile-picture display format associated with private format. The hData parameter must be a handle to data that can be displayed in metafile-picture format in lieu of the privately formatted data. See SetClipboardData.


FN_CF_DSPMETAFILEPICT
CF_DSPMETAFILEPICT  0x0083  winuser.h


CF_DSPTEXT
CF_DSPTEXT  0x0081  winuser.h

Text display format associated with private format. The hData parameter must be a handle to data that can be displayed in text format in lieu of the privately formatted data. See SetClipboardData.


FN_CF_DSPTEXT
CF_DSPTEXT  0x0081  winuser.h


CF_EFFECTS
CF_EFFECTS  0x00000100L  commdlg.h

Specifies the ChooseFont function should enable strikeout, underline, and color effects. See CHOOSEFONT.


FN_CF_EFFECTS
CF_EFFECTS  0x00000100L  commdlg.h


CF_ENABLEHOOK
CF_ENABLEHOOK  0x00000008L  commdlg.h

Enables the hook function specified in the lpfnHook member of this structure. See CHOOSEFONT.


FN_CF_ENABLEHOOK
CF_ENABLEHOOK  0x00000008L  commdlg.h


CF_ENABLETEMPLATE
CF_ENABLETEMPLATE  0x00000010L  commdlg.h

Indicates the hInstance member identifies a data block that contains a dialog template identified by lpTemplateName. See CHOOSEFONT.


FN_CF_ENABLETEMPLATE
CF_ENABLETEMPLATE  0x00000010L  commdlg.h


CF_ENABLETEMPLATEHANDLE
CF_ENABLETEMPLATEHANDLE  0x00000020L  commdlg.h

Indicates the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpTemplateName member if this flag is specified. See CHOOSEFONT.


FN_CF_ENABLETEMPLATEHANDLE
CF_ENABLETEMPLATEHANDLE  0x00000020L  commdlg.h


CF_ENHMETAFILE
CF_ENHMETAFILE  14  winuser.h

A handle to an enhanced metafile (HEMF). See SetClipboardData.


FN_CF_ENHMETAFILE
CF_ENHMETAFILE  14  winuser.h


CF_FIXEDPITCHONLY
CF_FIXEDPITCHONLY  0x00004000L  commdlg.h

Specifies the ChooseFont function should only select fixed-pitch fonts. See CHOOSEFONT.


FN_CF_FIXEDPITCHONLY
CF_FIXEDPITCHONLY  0x00004000L  commdlg.h


CF_FORCEFONTEXIST
CF_FORCEFONTEXIST  0x00010000L  commdlg.h

Specifies the ChooseFont function should indicate an error condition if the user attempts to select a font or style that does not exist. See CHOOSEFONT.


FN_CF_FORCEFONTEXIST
CF_FORCEFONTEXIST  0x00010000L  commdlg.h


CF_INITTOLOGFONTSTRUCT
CF_INITTOLOGFONTSTRUCT  0x00000040L  commdlg.h

Specifies the ChooseFont function should use the LOGFONT structure, pointed to by lpLogFont, to initialize the dialog controls. See CHOOSEFONT.


FN_CF_INITTOLOGFONTSTRUCT
CF_INITTOLOGFONTSTRUCT  0x00000040L  commdlg.h


CF_LIMITSIZE
CF_LIMITSIZE  0x00002000L  commdlg.h

Specifies the ChooseFont function should only select font sizes within the range specified by the nSizeMin and nSizeMax fields. See CHOOSEFONT.


FN_CF_LIMITSIZE
CF_LIMITSIZE  0x00002000L  commdlg.h


CF_METAFILEPICT
CF_METAFILEPICT  3  winuser.h

Handle to 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 hData should also free the metafile referred to by the CF_METAFILEPICT handle. See SetClipboardData.


FN_CF_METAFILEPICT
CF_METAFILEPICT  3  winuser.h


CF_NOFACESEL
CF_NOFACESEL  0x00080000L  commdlg.h

Specifies the ChooseFont function should not allow facename selections. See CHOOSEFONT.


FN_CF_NOFACESEL
CF_NOFACESEL  0x00080000L  commdlg.h


CF_NOOEMFONTS
CF_NOOEMFONTS  CF_NOVECTORFONTS  commdlg.h

See CF_NOVECTORFONTS description. See CHOOSEFONT.


FN_CF_NOOEMFONTS
CF_NOOEMFONTS  CF_NOVECTORFONTS  commdlg.h


CF_NOSIMULATIONS
CF_NOSIMULATIONS  0x00001000L  commdlg.h

Specifies the ChooseFont function should not allow GDI font simulations. See CHOOSEFONT.


FN_CF_NOSIMULATIONS
CF_NOSIMULATIONS  0x00001000L  commdlg.h


CF_NOSIZESEL
CF_NOSIZESEL  0x00200000L  commdlg.h

Specifies the ChooseFont function should not allow size selections. See CHOOSEFONT.


FN_CF_NOSIZESEL
CF_NOSIZESEL  0x00200000L  commdlg.h


CF_NOSTYLESEL
CF_NOSTYLESEL  0x00100000L  commdlg.h

Specifies the ChooseFont function should not allow style selections. See CHOOSEFONT.


FN_CF_NOSTYLESEL
CF_NOSTYLESEL  0x00100000L  commdlg.h


CF_NOVECTORFONTS
CF_NOVECTORFONTS  0x00000800L  commdlg.h

Specifies the ChooseFont function should not allow vector-font selections. See CHOOSEFONT.


FN_CF_NOVECTORFONTS
CF_NOVECTORFONTS  0x00000800L  commdlg.h


CF_OEMTEXT
CF_OEMTEXT  7  winuser.h

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. See SetClipboardData.


FN_CF_OEMTEXT
CF_OEMTEXT  7  winuser.h


CF_OWNERDISPLAY
CF_OWNERDISPLAY  0x0080  winuser.h

Owner display format. The clipboard owner must display and update the clipboard viewer window, and will receive the messages WM_ASKCBFORMATNAME, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, WM_SIZECLIPBOARD, and WM_VSCROLLCLIPBOARD. The hData parameter must be NULL. See SetClipboardData.


FN_CF_OWNERDISPLAY
CF_OWNERDISPLAY  0x0080  winuser.h


CF_PALETTE
CF_PALETTE  9  winuser.h

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 in 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 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. See SetClipboardData.


FN_CF_PALETTE
CF_PALETTE  9  winuser.h


CF_PENDATA
CF_PENDATA  10  winuser.h

Data for the pen extensions to the Windows operating system. See SetClipboardData.


FN_CF_PENDATA
CF_PENDATA  10  winuser.h


CF_PRINTERFONTS
CF_PRINTERFONTS  0x00000002  commdlg.h

Causes the dialog box to only list the fonts supported by the printer associated with device context (or information context) identified by the hDC member. See CHOOSEFONT.


FN_CF_PRINTERFONTS
CF_PRINTERFONTS  0x00000002  commdlg.h


CF_PRIVATEFIRST
CF_PRIVATEFIRST  0x0200  winuser.h

Beginning of range (ending at CF_PRIVATELAST) of integer values for private clipboard formats. Handles associated with private clipboard formats are not automatically freed; the clipboard owner must free such data handles, typically in response to the WM_DESTROYCLIPBOARD message. See SetClipboardData.


FN_CF_PRIVATEFIRST
CF_PRIVATEFIRST  0x0200  winuser.h


CF_PRIVATELAST
CF_PRIVATELAST  0x02FF  winuser.h

End of range (beginning at CF_PRIVATEFIRST) of integer values for private clipboard formats. Handles associated with private clipboard formats are not automatically freed; the clipboard owner must free such data handles, typically in response to the WM_DESTROYCLIPBOARD message. See SetClipboardData.


FN_CF_PRIVATELAST
CF_PRIVATELAST  0x02FF  winuser.h


CF_SCALABLEONLY
CF_SCALABLEONLY  0x00020000L  commdlg.h

Specifies the ChooseFont function should only allow the selection of scalable fonts. (Scalable fonts include: vector fonts, scalable printer fonts, TrueType fonts, and fonts scaled by other algorithms or technologies.) See CHOOSEFONT.


FN_CF_SCALABLEONLY
CF_SCALABLEONLY  0x00020000L  commdlg.h


CF_SCREENFONTS
CF_SCREENFONTS  0x00000001  commdlg.h

Causes the dialog box to only list the screen fonts supported by the system. See CHOOSEFONT.


FN_CF_SCREENFONTS
CF_SCREENFONTS  0x00000001  commdlg.h


CF_SHOWHELP
CF_SHOWHELP  0x00000004L  commdlg.h

Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified. See CHOOSEFONT.


FN_CF_SHOWHELP
CF_SHOWHELP  0x00000004L  commdlg.h


CF_SYLK
CF_SYLK  4  winuser.h

Microsoft symbolic link (SYLK) format. See SetClipboardData.


FN_CF_SYLK
CF_SYLK  4  winuser.h


CF_TEXT
CF_TEXT  1  winuser.h

Text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data. See SetClipboardData.


FN_CF_TEXT
CF_TEXT  1  winuser.h


CF_TIFF
CF_TIFF  6  winuser.h

Tag image file format. See SetClipboardData.


FN_CF_TIFF
CF_TIFF  6  winuser.h


CF_TTONLY
CF_TTONLY  0x00040000L  commdlg.h

Specifies the ChooseFont function should only enumerate and allow the selection of TrueType fonts. See CHOOSEFONT.


FN_CF_TTONLY
CF_TTONLY  0x00040000L  commdlg.h


CF_UNICODETEXT
CF_UNICODETEXT  13  winuser.h

Unicode text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data. See SetClipboardData.


FN_CF_UNICODETEXT
CF_UNICODETEXT  13  winuser.h


CF_USESTYLE
CF_USESTYLE  0x00000080L  commdlg.h

Specifies the lpszStyle member points to a buffer that contains style data the ChooseFont function should use to initialize the Font Style selection. When the user dismisses the dialog, the ChooseFont function copies style data for the user's selection to this buffer. See CHOOSEFONT.


FN_CF_USESTYLE
CF_USESTYLE  0x00000080L  commdlg.h


CF_WYSIWYG
CF_WYSIWYG  0x00008000L  commdlg.h

Specifies the ChooseFont function should only allow the selection of fonts available on both the printer and the display. If this flag is set, the CF_BOTH and CF_SCALABLEONLY flags should also be set. See CHOOSEFONT.


FN_CF_WYSIWYG
CF_WYSIWYG  0x00008000L  commdlg.h


CFERR_MAXLESSTHANMIN
CFERR_MAXLESSTHANMIN  0x2002  cderr.h

Specifies the size specified in the nSizeMax member of the CHOOSEFONT structure is less than the size specified in the nSizeMin member. See CommDlgExtendedError.


FN_CFERR_MAXLESSTHANMIN
CFERR_MAXLESSTHANMIN  0x2002  cderr.h


CFERR_NOFONTS
CFERR_NOFONTS  0x2001  cderr.h

Specifies no fonts exist. See CommDlgExtendedError.


FN_CFERR_NOFONTS
CFERR_NOFONTS  0x2001  cderr.h


CLIPCAPS
CLIPCAPS  36  wingdi.h

Flag that indicates the clipping capabilities of the device. If the device can clip to a rectangle, it is 1. Otherwise, it is zero. See GetDeviceCaps.


FN_CLIPCAPS
CLIPCAPS  36  wingdi.h


COLOR_ACTIVEBORDER
COLOR_ACTIVEBORDER  10  winuser.h

Active window border. See SetSysColors.


FN_COLOR_ACTIVEBORDER
COLOR_ACTIVEBORDER  10  winuser.h


COLOR_ACTIVECAPTION
COLOR_ACTIVECAPTION  2  winuser.h

Active window caption. See SetSysColors.


FN_COLOR_ACTIVECAPTION
COLOR_ACTIVECAPTION  2  winuser.h


COLOR_APPWORKSPACE
COLOR_APPWORKSPACE  12  winuser.h

Background color of multiple document interface (MDI) applications. See SetSysColors.


FN_COLOR_APPWORKSPACE
COLOR_APPWORKSPACE  12  winuser.h


COLOR_BACKGROUND
COLOR_BACKGROUND  1  winuser.h

Desktop. See SetSysColors.


FN_COLOR_BACKGROUND
COLOR_BACKGROUND  1  winuser.h


COLOR_BTNFACE
COLOR_BTNFACE  15  winuser.h

Face shading on push buttons. See SetSysColors.


FN_COLOR_BTNFACE
COLOR_BTNFACE  15  winuser.h


COLOR_BTNSHADOW
COLOR_BTNSHADOW  16  winuser.h

Edge shading on push buttons. See SetSysColors.


FN_COLOR_BTNSHADOW
COLOR_BTNSHADOW  16  winuser.h


COLOR_BTNTEXT
COLOR_BTNTEXT  18  winuser.h

Text on push buttons. See SetSysColors.


FN_COLOR_BTNTEXT
COLOR_BTNTEXT  18  winuser.h


COLOR_CAPTIONTEXT
COLOR_CAPTIONTEXT  9  winuser.h

Text in caption, size box, scroll-bar arrow box. See SetSysColors.


FN_COLOR_CAPTIONTEXT
COLOR_CAPTIONTEXT  9  winuser.h


COLOR_GRAYTEXT
COLOR_GRAYTEXT  17  winuser.h

Grayed (disabled) text. This color is set to 0 if the current display driver does not support a solid gray color. See SetSysColors.


FN_COLOR_GRAYTEXT
COLOR_GRAYTEXT  17  winuser.h


COLOR_HIGHLIGHT
COLOR_HIGHLIGHT  13  winuser.h

Items selected item in a control. See SetSysColors.


FN_COLOR_HIGHLIGHT
COLOR_HIGHLIGHT  13  winuser.h


COLOR_HIGHLIGHTTEXT
COLOR_HIGHLIGHTTEXT  14  winuser.h

Text of item selected in a control. See SetSysColors.


FN_COLOR_HIGHLIGHTTEXT
COLOR_HIGHLIGHTTEXT  14  winuser.h


COLOR_INACTIVEBORDER
COLOR_INACTIVEBORDER  11  winuser.h

Inactive window border. See SetSysColors.


FN_COLOR_INACTIVEBORDER
COLOR_INACTIVEBORDER  11  winuser.h


COLOR_INACTIVECAPTION
COLOR_INACTIVECAPTION  3  winuser.h

Inactive window caption. See SetSysColors.


FN_COLOR_INACTIVECAPTION
COLOR_INACTIVECAPTION  3  winuser.h


COLOR_INACTIVECAPTIONTEXT
COLOR_INACTIVECAPTIONTEXT  19  winuser.h

Color of text in an inactive caption. See SetSysColors.


FN_COLOR_INACTIVECAPTIONTEXT
COLOR_INACTIVECAPTIONTEXT  19  winuser.h


COLOR_MENU
COLOR_MENU  4  winuser.h

Menu background. See SetSysColors.


FN_COLOR_MENU
COLOR_MENU  4  winuser.h


COLOR_MENUTEXT
COLOR_MENUTEXT  7  winuser.h

Text in menus. See SetSysColors.


FN_COLOR_MENUTEXT
COLOR_MENUTEXT  7  winuser.h


COLOR_SCROLLBAR
COLOR_SCROLLBAR  0  winuser.h

Scroll-bar gray area. See SetSysColors.


FN_COLOR_SCROLLBAR
COLOR_SCROLLBAR  0  winuser.h


COLOR_SHADOW

Color of automatic window shadows. See SetSysColors.


COLOR_WINDOW
COLOR_WINDOW  5  winuser.h

Window background. See SetSysColors.


FN_COLOR_WINDOW
COLOR_WINDOW  5  winuser.h


COLOR_WINDOWFRAME
COLOR_WINDOWFRAME  6  winuser.h

Window frame. See SetSysColors.


FN_COLOR_WINDOWFRAME
COLOR_WINDOWFRAME  6  winuser.h


COLOR_WINDOWTEXT
COLOR_WINDOWTEXT  8  winuser.h

Text in windows. See SetSysColors.


FN_COLOR_WINDOWTEXT
COLOR_WINDOWTEXT  8  winuser.h


COLORONCOLOR
COLORONCOLOR  3  wingdi.h

Deletes the pixels. This mode deletes all eliminated lines of pixels without trying to preserve their information. See SetStretchBltMode.


FN_COLORONCOLOR
COLORONCOLOR  3  wingdi.h


COLORRES
COLORRES  108  wingdi.h

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 version is 3.0 or later. See GetDeviceCaps.


FN_COLORRES
COLORRES  108  wingdi.h


COMBOBOX

Designates a control consisting of a list box and a selection field similar to an edit control. Display the list box at all times or drop it down when the user selects a pop-up list box next to the selection field. 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 box will highlight 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. See CreateWindow.


COMPLEXREGION
COMPLEXREGION  3  wingdi.h

Region is more than a single rectangle. See CombineRgn, ExtSelectClipRgn, GetRgnBox, IntersectClipRect, OffsetClipRgn, SelectClipRgn, SelectObject, SetMetaRgn.


FN_COMPLEXREGION
COMPLEXREGION  3  wingdi.h


COMPLEXREGION
COMPLEXREGION  3  wingdi.h

Region has overlapping borders. See OffsetRgn.


FN_COMPLEXREGION
COMPLEXREGION  3  wingdi.h


COMPLEXREGION
COMPLEXREGION  3  wingdi.h

The region has overlapping borders. See ExcludeUpdateRgn.


FN_COMPLEXREGION
COMPLEXREGION  3  wingdi.h


COMPLEXREGION
COMPLEXREGION  3  wingdi.h

Region has overlapping borders. See ExcludeClipRect.


FN_COMPLEXREGION
COMPLEXREGION  3  wingdi.h


COMPLEXREGION
COMPLEXREGION  3  wingdi.h

Region is more than a single rectangle. See GetClipBox.


FN_COMPLEXREGION
COMPLEXREGION  3  wingdi.h


CONNECT_UPDATE_PROFILE
CONNECT_UPDATE_PROFILE  0x00000001  winnetwk.h

Information about the connection is stored in the user profile. See WNetAddConnection2, WNetCancelConnection2.


FN_CONNECT_UPDATE_PROFILE
CONNECT_UPDATE_PROFILE  0x00000001  winnetwk.h


CONTAINER_INHERIT_ACE
CONTAINER_INHERIT_ACE  (0x2)  winnt.h

The ACE is inherited by containers (for example, subdirectories). See ACE_HEADER.


FN_CONTAINER_INHERIT_ACE
CONTAINER_INHERIT_ACE  (0x2)  winnt.h


CP_ACP
CP_ACP  0  winnls.h

ANSI code page See GetCPInfo, MultiByteToWideChar, WideCharToMultiByte.


FN_CP_ACP
CP_ACP  0  winnls.h


CP_OEMCP
CP_OEMCP  1  winnls.h

OEM code page See GetCPInfo, MultiByteToWideChar, WideCharToMultiByte.


FN_CP_OEMCP
CP_OEMCP  1  winnls.h


CREATE_ALWAYS
CREATE_ALWAYS  2  winbase.h

Creates a new file. Overwrites the file if it exists. See CreateFile.


FN_CREATE_ALWAYS
CREATE_ALWAYS  2  winbase.h


CREATE_NEW
CREATE_NEW  1  winbase.h

Creates a new file. Fails if the specified file already exists. See CreateFile.


FN_CREATE_NEW
CREATE_NEW  1  winbase.h


CREATE_NEW_CONSOLE
CREATE_NEW_CONSOLE  0x00000010  winbase.h

The new process will have a new console, instead of inheriting the parent's console. This flag cannot be used with the DETACHED_PROCESS flag. See CreateProcess.


FN_CREATE_NEW_CONSOLE
CREATE_NEW_CONSOLE  0x00000010  winbase.h


CREATE_NEW_PROCESS_GROUP
CREATE_NEW_PROCESS_GROUP  0x00000200  winbase.h

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 group ID of the new process group is the same as the process ID, which is returned in the lppiProcInfo structure. Process groups are used by the GenerateConsoleCtrlEvent function to enable sending a Ctrl-C or Ctrl-Break signal to a group of console processes. See CreateProcess.


FN_CREATE_NEW_PROCESS_GROUP
CREATE_NEW_PROCESS_GROUP  0x00000200  winbase.h


CREATE_NO_WINDOW
CREATE_NO_WINDOW  0x08000000  winbase.h

The created process will have a console, but no window. This flag should not be used by application programs. It is intended only for internal use to implement VDM code. See CreateProcess.


FN_CREATE_NO_WINDOW
CREATE_NO_WINDOW  0x08000000  winbase.h


CREATE_PROCESS_DEBUG_EVENT
CREATE_PROCESS_DEBUG_EVENT  3  winbase.h

Reports a create process debugging event. The value of u.CreateProcess specifies a CREATE_PROCESS_DEBUG_INFO structure. See DEBUG_EVENT.


FN_CREATE_PROCESS_DEBUG_EVENT
CREATE_PROCESS_DEBUG_EVENT  3  winbase.h


CREATE_SUSPENDED
CREATE_SUSPENDED  0x00000004  winbase.h

The thread is created in a suspended state, and will not run until the ResumeThread function is called. See CreateProcess, CreateThread.


FN_CREATE_SUSPENDED
CREATE_SUSPENDED  0x00000004  winbase.h


CREATE_THREAD_DEBUG_EVENT
CREATE_THREAD_DEBUG_EVENT  2  winbase.h

Reports a create thread debugging event. The value of u.CreateThread specifies a CREATE_THREAD_DEBUG_INFO structure. See DEBUG_EVENT.


FN_CREATE_THREAD_DEBUG_EVENT
CREATE_THREAD_DEBUG_EVENT  2  winbase.h


CS_BYTEALIGNCLIENT
CS_BYTEALIGNCLIENT  0x1000  winuser.h

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. See WNDCLASS.


FN_CS_BYTEALIGNCLIENT
CS_BYTEALIGNCLIENT  0x1000  winuser.h


CS_BYTEALIGNWINDOW
CS_BYTEALIGNWINDOW  0x2000  winuser.h

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. See WNDCLASS.


FN_CS_BYTEALIGNWINDOW
CS_BYTEALIGNWINDOW  0x2000  winuser.h


CS_CLASSDC
CS_CLASSDC  0x0040  winuser.h

Allocates one device context (DC) to be shared by all windows in the class. Because Window classes are process-specific, it is possible for multiple threads of a multi-threaded application to create a window of the same class. It is also possible for the threads to attempt to use the DC simultaneously. When this happens, the system allows only one of the threads to successfully complete its drawing operation. See WNDCLASS.


FN_CS_CLASSDC
CS_CLASSDC  0x0040  winuser.h


CS_DBLCLKS
CS_DBLCLKS  0x0008  winuser.h

Instructs Windows to send 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. See WNDCLASS.


FN_CS_DBLCLKS
CS_DBLCLKS  0x0008  winuser.h


CS_GLOBALCLASS
CS_GLOBALCLASS  0x4000  winuser.h

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 DLL and listing the name of the DLL in the registration database under the following keys: Whenever a process starts, the 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. See WNDCLASS.


FN_CS_GLOBALCLASS
CS_GLOBALCLASS  0x4000  winuser.h


CS_GREEK

Supports the Greek character set. See CHARSET.


CS_HREDRAW
CS_HREDRAW  0x0002  winuser.h

Specifies that the entire window is to be redrawn if a movement or size adjustment changes the width of the client area. See WNDCLASS.


FN_CS_HREDRAW
CS_HREDRAW  0x0002  winuser.h


CS_LATIN

Supports the Latin character set. See CHARSET.


CS_NOCLOSE
CS_NOCLOSE  0x0200  winuser.h

Disables the Close command on the System menu. See WNDCLASS.


FN_CS_NOCLOSE
CS_NOCLOSE  0x0200  winuser.h


CS_OWNDC
CS_OWNDC  0x0020  winuser.h

Allocates a unique device context for each window in the class. See WNDCLASS.


FN_CS_OWNDC
CS_OWNDC  0x0020  winuser.h


CS_PARENTDC
CS_PARENTDC  0x0080  winuser.h

Gives the parent window's device context to the child windows. Specifying CS_PARENTDC enhances an application's performance. When an application calls the GetDC function, passing the handle of a window that belongs to a class with the CS_PARENTDC style, the system searches for a device context that has been precalculated for the window's parent window. If all child windows of a particular parent window specify this style, the system need not recalculate a device context for any of the child windows. See WNDCLASS.


FN_CS_PARENTDC
CS_PARENTDC  0x0080  winuser.h


CS_SAVEBITS
CS_SAVEBITS  0x0800  winuser.h

Saves, as a bitmap, the portion of the screen image that is 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 that had been 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 that you display briefly and then remove before other screen activity takes place (for example, menus or dialog boxes). This style increases the time required to display the window since the system must first allocate memory to store the bitmap. See WNDCLASS.


FN_CS_SAVEBITS
CS_SAVEBITS  0x0800  winuser.h


CS_UGL

Supports the UGL character set. See CHARSET.


CS_VREDRAW
CS_VREDRAW  0x0001  winuser.h

Specifies that the entire window is to be redrawn if a movement or size adjustment changes the height of the client area. See WNDCLASS.


FN_CS_VREDRAW
CS_VREDRAW  0x0001  winuser.h


CS_WIN30

Supports the Windows 3.0 character set. See CHARSET.


CTRL_BREAK_EVENT
CTRL_BREAK_EVENT  1  wincon.h

Generate Ctrl-Break signal See GenerateConsoleCtrlEvent.


FN_CTRL_BREAK_EVENT
CTRL_BREAK_EVENT  1  wincon.h


CTRL_C_EVENT
CTRL_C_EVENT  0  wincon.h

Generate Ctrl-C signal See GenerateConsoleCtrlEvent.


FN_CTRL_C_EVENT
CTRL_C_EVENT  0  wincon.h


CURVECAPS
CURVECAPS  28  wingdi.h

A bitmask that indicates the curve capabilities of the device. The bits have the following meanings: See GetDeviceCaps.


FN_CURVECAPS
CURVECAPS  28  wingdi.h


DACL_SECURITY_INFORMATION
DACL_SECURITY_INFORMATION  (0X00000004L)  winnt.h

When set, this bit indicates the discretionary access-control list of the object is being referenced. See SECURITY_INFORMATION.


FN_DACL_SECURITY_INFORMATION
DACL_SECURITY_INFORMATION  (0X00000004L)  winnt.h


DC_BINNAMES
DC_BINNAMES  12  wingdi.h

Specifies that the function enumerates the paper bins on the given device. If a device driver supports this constant, the array identified by lpOutput contains a data structure that contains two members. The first member is an array identifying valid paper bins: The second member is an array of characters strings specifying the bin names: If a device driver does not support this value, the array identified by lpOutput is empty and the return value is NULL. If lpOutput is NULL, the return value specifies the number of bins supported. See DeviceCapabilities.


FN_DC_BINNAMES
DC_BINNAMES  12  wingdi.h


DC_BINS
DC_BINS  6  wingdi.h

Specifies that the function retrieves a list of constants that identify the available bins. The function copies the list to the array identified by lpOutput. If this array is NULL, the function returns the number of supported bins. The following list contains the bin identifiers which may be returned: See DeviceCapabilities.


FN_DC_BINS
DC_BINS  6  wingdi.h


DC_DRIVER
DC_DRIVER  11  wingdi.h

Specifies that the function returns the driver version number. See DeviceCapabilities.


FN_DC_DRIVER
DC_DRIVER  11  wingdi.h


DC_DUPLEX
DC_DUPLEX  7  wingdi.h

Specifies that the funciton returns the level of duplex support. The return value is 1 if the function supports duplex output; otherwise it is zero. See DeviceCapabilities.


FN_DC_DUPLEX
DC_DUPLEX  7  wingdi.h


DC_ENUMRESOLUTIONS
DC_ENUMRESOLUTIONS  13  wingdi.h

Specifies that the function returns a list of available printer resolutions in the array identified by lpOutput. The resolutions are returned as pairs of LONG integers; the first value of the pair specifies the horizontal resolution and the second value specifies the vertical resolution. If lpOutput is NULL, the function returns the number of supported resolutions. See DeviceCapabilities.


FN_DC_ENUMRESOLUTIONS
DC_ENUMRESOLUTIONS  13  wingdi.h


DC_EXTRA
DC_EXTRA  9  wingdi.h

Specifies that the function returns the number of bytes required for the device-specific data that is appended to the DEVMODE structure. See DeviceCapabilities.


FN_DC_EXTRA
DC_EXTRA  9  wingdi.h


DC_FIELDS
DC_FIELDS  1  wingdi.h

Specifies that the function returns a value indicating which members of the DEVMODE structure are set by the device driver. This value can be one or more of the following constants: See DeviceCapabilities.


FN_DC_FIELDS
DC_FIELDS  1  wingdi.h


DC_FILEDEPENDENCIES
DC_FILEDEPENDENCIES  14  wingdi.h

Specifies that the function returns a list of files that must be loaded when the device driver is installed. If lpOutput is NULL and this value is specified, the function returns the number of filenames that must be loaded. If lpOutput is a valid pointer, the function returns the specified number of 64-character filenames. See DeviceCapabilities.


FN_DC_FILEDEPENDENCIES
DC_FILEDEPENDENCIES  14  wingdi.h


DC_MAXEXTENT
DC_MAXEXTENT  5  wingdi.h

Specifies that the function returns the maximum supported paper-size. These dimensions are returned in a POINT structure; the x member of this structure specifies the maximum paper width and the y member of this structure specifies the maximum paper length. See DeviceCapabilities.


FN_DC_MAXEXTENT
DC_MAXEXTENT  5  wingdi.h


DC_MINEXTENT
DC_MINEXTENT  4  wingdi.h

Specifies that the function returns the minimum supported paper-size. These dimensions are returned in a POINT structure; the x member of this structure specifies the minimum paper width and the y member of this structure specifies the minimum paper length. See DeviceCapabilities.


FN_DC_MINEXTENT
DC_MINEXTENT  4  wingdi.h


DC_PAPERS
DC_PAPERS  2  wingdi.h

Specifies that the function returns a list of supported paper sizes. The paper sizes are returned in the array at which lpOutput points. The function return value specifies the number of sizes identified in the array. If lpOutput is NULL, the function returns the number of supported paper sizes. See DeviceCapabilities.


FN_DC_PAPERS
DC_PAPERS  2  wingdi.h


DC_PAPERSIZE
DC_PAPERSIZE  3  wingdi.h

Specifies that the function returns the supported paper sizes in the array at which lpOutput points. These dimensions are specified in .1 millimeter units. See DeviceCapabilities.


FN_DC_PAPERSIZE
DC_PAPERSIZE  3  wingdi.h


DC_SIZE
DC_SIZE  8  wingdi.h

Specifies that the function returns the size of the DEVMODE structure that is required by the device driver. See DeviceCapabilities.


FN_DC_SIZE
DC_SIZE  8  wingdi.h


DC_VERSION
DC_VERSION  10  wingdi.h

Specifies that the function returns a version number that identifies the specification to which the device driver conforms. See DeviceCapabilities.


FN_DC_VERSION
DC_VERSION  10  wingdi.h


DCB_ACCUMULATE
DCB_ACCUMULATE  0x0002  wingdi.h

Add 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. See SetBoundsRect.


FN_DCB_ACCUMULATE
DCB_ACCUMULATE  0x0002  wingdi.h


DCB_DISABLE
DCB_DISABLE  0x0008  wingdi.h

Bounds accumulation is off. DCB_DISABLE Turn off bounds accumulation. DCB_DISABLE Bounds accumulation is off. See GetBoundsRect, SetBoundsRect.


FN_DCB_DISABLE
DCB_DISABLE  0x0008  wingdi.h


DCB_ENABLE
DCB_ENABLE  0x0004  wingdi.h

Bounds accumulation is on. DCB_ENABLE and DCB_DISABLE are mutually exclusive. See GetBoundsRect, SetBoundsRect.


FN_DCB_ENABLE
DCB_ENABLE  0x0004  wingdi.h


DCB_RESET
DCB_RESET  0x0001  wingdi.h

Clear the bounding rectangle after returning it. See GetBoundsRect, SetBoundsRect.


FN_DCB_RESET
DCB_RESET  0x0001  wingdi.h


DCB_SET
DCB_SET  (DCB_RESET | DCB_ACCUMULATE)  wingdi.h

The bounds rectangle is not empty. DCB_SET and DCB_RESET are mutually exclusive. See GetBoundsRect, SetBoundsRect.


FN_DCB_SET
DCB_SET  (DCB_RESET | DCB_ACCUMULATE)  wingdi.h


DCB_WINDOWMGR

Return the Windows bounding rectangle. If this value is not given, the function returns the bounding rectangle associated with the application. See GetBoundsRect.


DCTT_BITMAP
DCTT_BITMAP  0x0000001L  wingdi.h

A device is capable of printing TrueType fonts as graphics. (For example, dot-matrix and PCL printers.) See DeviceCapabilities.


FN_DCTT_BITMAP
DCTT_BITMAP  0x0000001L  wingdi.h


DCTT_DOWNLOAD
DCTT_DOWNLOAD  0x0000002L  wingdi.h

A device is capable of downloading TrueType fonts. (For example, PCL and PostScript printers.) See DeviceCapabilities.


FN_DCTT_DOWNLOAD
DCTT_DOWNLOAD  0x0000002L  wingdi.h


DCTT_SUBDEV
DCTT_SUBDEV  0x0000004L  wingdi.h

Device is capable of substituting device fonts for TrueType fonts. (For example, PostScript printers.) See DeviceCapabilities.


FN_DCTT_SUBDEV
DCTT_SUBDEV  0x0000004L  wingdi.h


DCX_CACHE
DCX_CACHE  0x00000002L  winuser.h

Returns a DC from the cache, rather than the OWNDC or CLASSDC window. Essentially overrides CS_OWNDC and CS_CLASSDC. See GetDCEx.


FN_DCX_CACHE
DCX_CACHE  0x00000002L  winuser.h


DCX_CLIPCHILDREN
DCX_CLIPCHILDREN  0x00000008L  winuser.h

Exclude the visible regions of all child windows below the window specified by the hwnd parameter. See GetDCEx.


FN_DCX_CLIPCHILDREN
DCX_CLIPCHILDREN  0x00000008L  winuser.h


DCX_CLIPSIBLINGS
DCX_CLIPSIBLINGS  0x00000010L  winuser.h

Exclude the visible regions of all sibling windows above the window specified by the hwnd parameter. See GetDCEx.


FN_DCX_CLIPSIBLINGS
DCX_CLIPSIBLINGS  0x00000010L  winuser.h


DCX_DEFAULTCLIP

Returns a DC by using the default clipping flags specified by WS_CLIPCHILDREN, WS_CLIPSIBLINGS, and CS_PARENTDC. See GetDCEx.


DCX_EXCLUDERGN
DCX_EXCLUDERGN  0x00000040L  winuser.h

The clip region specified by the hrgnClip is excluded from the visible region of the returned DC. See GetDCEx.


FN_DCX_EXCLUDERGN
DCX_EXCLUDERGN  0x00000040L  winuser.h


DCX_INTERSECTRGN
DCX_INTERSECTRGN  0x00000080L  winuser.h

The clip region specified by the hrgnClip parameter is intersected with the visible region of the returned DC. See GetDCEx.


FN_DCX_INTERSECTRGN
DCX_INTERSECTRGN  0x00000080L  winuser.h


DCX_LOCKWINDOWUPDATE
DCX_LOCKWINDOWUPDATE  0x00000400L  winuser.h

Allow drawing even if there is a LockWindowUpdate() call in effect that would otherwise exclude this window. Used for drawing during tracking. See GetDCEx.


FN_DCX_LOCKWINDOWUPDATE
DCX_LOCKWINDOWUPDATE  0x00000400L  winuser.h


DCX_NORECOMPUTE
DCX_NORECOMPUTE  0x00100000L  winuser.h

If an exact match in the cache is not found, return NULL rather than creating a new DC. When used with DCX_NORESETATTRS, this gives applications a way to determine whether they need to reselect any special attributes. See GetDCEx.


FN_DCX_NORECOMPUTE
DCX_NORECOMPUTE  0x00100000L  winuser.h


DCX_NORESETATTRS
DCX_NORESETATTRS  0x00000004L  winuser.h

Do not reset the attributes of this DC to the default attributes when this DC is released. See GetDCEx.


FN_DCX_NORESETATTRS
DCX_NORESETATTRS  0x00000004L  winuser.h


DCX_PARENTCLIP
DCX_PARENTCLIP  0x00000020L  winuser.h

Use the visible region of the parent window. The parent's WS_CLIPCHILDREN and CS_PARENTDC style bits are ignored. The DC origin is set to the upper left corner of the the window specified by the hwnd parameter. See GetDCEx.


FN_DCX_PARENTCLIP
DCX_PARENTCLIP  0x00000020L  winuser.h


DCX_VALIDATE
DCX_VALIDATE  0x00200000L  winuser.h

When specified with DCX_INTERSECTUPDATE, this flag causes the DC to be completely validated. Using this function with both DCX_INTERSECTUPDATE and DCX_VALIDATE is identical to using the BeginPaint function. See GetDCEx.


FN_DCX_VALIDATE
DCX_VALIDATE  0x00200000L  winuser.h


DCX_WINDOW
DCX_WINDOW  0x00000001L  winuser.h

Returns a DC corresponding to the window rectangle rather than the client rectangle. See GetDCEx.


FN_DCX_WINDOW
DCX_WINDOW  0x00000001L  winuser.h


DDD_EXACT_MATCH_ON_REMOVE
DDD_EXACT_MATCH_ON_REMOVE  0x00000004  winbase.h

If set, along with DDD_REMOVE_DEFINITION, then DefineDosDevice uses an exact match to determine which mapping to remove. Use this flag to insure that you don't delete something that you did not define. See DefineDosDevice.


FN_DDD_EXACT_MATCH_ON_REMOVE
DDD_EXACT_MATCH_ON_REMOVE  0x00000004  winbase.h


DDD_RAW_TARGET_PATH
DDD_RAW_TARGET_PATH  0x00000001  winbase.h

If specified, DefineDosDevice does not convert the lpTargetPath string from a DOS path to an NT path, but takes it as is. See DefineDosDevice.


FN_DDD_RAW_TARGET_PATH
DDD_RAW_TARGET_PATH  0x00000001  winbase.h


DDD_REMOVE_DEFINITION
DDD_REMOVE_DEFINITION  0x00000002  winbase.h

If specified, DefineDosDevice removes the specified definition for the specified device. See DefineDosDevice.


FN_DDD_REMOVE_DEFINITION
DDD_REMOVE_DEFINITION  0x00000002  winbase.h


DDL_ARCHIVE
DDL_ARCHIVE  0x0020  winuser.h

Includes archived files. See DlgDirList.


FN_DDL_ARCHIVE
DDL_ARCHIVE  0x0020  winuser.h


DDL_DIRECTORY
DDL_DIRECTORY  0x0010  winuser.h

Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]). See DlgDirList.


FN_DDL_DIRECTORY
DDL_DIRECTORY  0x0010  winuser.h


DDL_DRIVES
DDL_DRIVES  0x4000  winuser.h

Includes drives. Drives are listed in the form [-x-], where x is the drive letter. See DlgDirList.


FN_DDL_DRIVES
DDL_DRIVES  0x4000  winuser.h


DDL_EXCLUSIVE
DDL_EXCLUSIVE  0x8000  winuser.h

Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified. See DlgDirList.


FN_DDL_EXCLUSIVE
DDL_EXCLUSIVE  0x8000  winuser.h


DDL_HIDDEN
DDL_HIDDEN  0x0002  winuser.h

Includes hidden files. See DlgDirList.


FN_DDL_HIDDEN
DDL_HIDDEN  0x0002  winuser.h


DDL_POSTMSGS
DDL_POSTMSGS  0x2000  winuser.h

Posts messages to the application's message queue. By default, the function sends messages directly to the dialog box procedure. See DlgDirList.


FN_DDL_POSTMSGS
DDL_POSTMSGS  0x2000  winuser.h


DDL_READONLY
DDL_READONLY  0x0001  winuser.h

Includes read-only files. See DlgDirList.


FN_DDL_READONLY
DDL_READONLY  0x0001  winuser.h


DDL_READWRITE
DDL_READWRITE  0x0000  winuser.h

Includes read-write files with no additional attributes. See DlgDirList.


FN_DDL_READWRITE
DDL_READWRITE  0x0000  winuser.h


DDL_SYSTEM
DDL_SYSTEM  0x0004  winuser.h

Includes system files. See DlgDirList.


FN_DDL_SYSTEM
DDL_SYSTEM  0x0004  winuser.h


DEBUG_ONLY_THIS_PROCESS
DEBUG_ONLY_THIS_PROCESS  0x00000002  winbase.h

If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. If the new process creates additional processes, the kernel will not notify the debugger of any debug events that occur in the additional processes. See CreateProcess.


FN_DEBUG_ONLY_THIS_PROCESS
DEBUG_ONLY_THIS_PROCESS  0x00000002  winbase.h


DEBUG_PROCESS
DEBUG_PROCESS  0x00000001  winbase.h

If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. The kernel notifies the debugger of all debug events that occur in the process being debugged. If this flag is not set and the calling process is being debugged, then the new process becomes another process being debugged by the calling process' debugger. If this bit is not set and the calling process is not a process being debugged, no debugging-related actions occur. See CreateProcess.


FN_DEBUG_PROCESS
DEBUG_PROCESS  0x00000001  winbase.h


DEFAULT_PALETTE
DEFAULT_PALETTE  15  wingdi.h

Default color palette. This palette consists of the static colors in the system palette. See GetStockObject.


FN_DEFAULT_PALETTE
DEFAULT_PALETTE  15  wingdi.h


DEFAULT_QUALITY
DEFAULT_QUALITY  0  wingdi.h

Appearance of the font does not matter. See CreateFont, LOGFONT.


FN_DEFAULT_QUALITY
DEFAULT_QUALITY  0  wingdi.h


DEREGISTERED
DEREGISTERED  0x05  nb30.h

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. See NAME_BUFFER.


FN_DEREGISTERED
DEREGISTERED  0x05  nb30.h


DETACHED_PROCESS
DETACHED_PROCESS  0x00000008  winbase.h

For console processes, the new process will not have access to the console of the parent process. The new process can call AllocConsole if it later wants to create a new console. This flag cannot be used with the CREATE_NEW_CONSOLE flag. See CreateProcess.


FN_DETACHED_PROCESS
DETACHED_PROCESS  0x00000008  winbase.h


DEVICE_DEFAULT_FONT
DEVICE_DEFAULT_FONT  14  wingdi.h

Device-dependent font See GetStockObject.


FN_DEVICE_DEFAULT_FONT
DEVICE_DEFAULT_FONT  14  wingdi.h


DIB_PAL_COLORS
DIB_PAL_COLORS  1  wingdi.h

The color table consists of an array of 16-bit indices into the currently selected logical palette. See CreateDIBitmap, CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateDIBSection, GetDIBits, SetDIBits, SetDIBitsToDevice, StretchDIBits, EXTLOGPEN, LOGBRUSH.


FN_DIB_PAL_COLORS
DIB_PAL_COLORS  1  wingdi.h


DIB_PAL_INDICES
DIB_PAL_INDICES  2  wingdi.h

There is no color table for the bitmap. The bitmap bits are indices into the device's physical palette, (not the currently selected logical palette). See CreateDIBitmap, CreateDIBPatternBrush, CreateDIBPatternBrushPt, GetDIBits, SetDIBits, SetDIBitsToDevice, StretchDIBits.


FN_DIB_PAL_INDICES
DIB_PAL_INDICES  2  wingdi.h


DIB_RGB_COLORS
DIB_RGB_COLORS  0  wingdi.h

The color table is provided and contains literal RGB values. See CreateDIBitmap, CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateDIBSection, GetDIBits, SetDIBits, SetDIBitsToDevice, StretchDIBits, EXTLOGPEN, LOGBRUSH.


FN_DIB_RGB_COLORS
DIB_RGB_COLORS  0  wingdi.h


DKGRAY_BRUSH
DKGRAY_BRUSH  3  wingdi.h

Dark gray brush See GetStockObject.


FN_DKGRAY_BRUSH
DKGRAY_BRUSH  3  wingdi.h


DLGC_BUTTON
DLGC_BUTTON  0x2000  winuser.h

Button See WM_GETDLGCODE.


FN_DLGC_BUTTON
DLGC_BUTTON  0x2000  winuser.h


DLGC_DEFPUSHBUTTON
DLGC_DEFPUSHBUTTON  0x0010  winuser.h

Default push button See WM_GETDLGCODE.


FN_DLGC_DEFPUSHBUTTON
DLGC_DEFPUSHBUTTON  0x0010  winuser.h


DLGC_HASSETSEL
DLGC_HASSETSEL  0x0008  winuser.h

EM_SETSEL messages See WM_GETDLGCODE.


FN_DLGC_HASSETSEL
DLGC_HASSETSEL  0x0008  winuser.h


DLGC_RADIOBUTTON
DLGC_RADIOBUTTON  0x0040  winuser.h

Radio button See WM_GETDLGCODE.


FN_DLGC_RADIOBUTTON
DLGC_RADIOBUTTON  0x0040  winuser.h


DLGC_STATIC
DLGC_STATIC  0x0100  winuser.h

Static control See WM_GETDLGCODE.


FN_DLGC_STATIC
DLGC_STATIC  0x0100  winuser.h


DLGC_UNDEFPUSHBUTTON
DLGC_UNDEFPUSHBUTTON  0x0020  winuser.h

Non-default push button See WM_GETDLGCODE.


FN_DLGC_UNDEFPUSHBUTTON
DLGC_UNDEFPUSHBUTTON  0x0020  winuser.h


DLGC_WANTALLKEYS
DLGC_WANTALLKEYS  0x0004  winuser.h

All keyboard input See WM_GETDLGCODE.


FN_DLGC_WANTALLKEYS
DLGC_WANTALLKEYS  0x0004  winuser.h


DLGC_WANTARROWS
DLGC_WANTARROWS  0x0001  winuser.h

DIRECTION keys See WM_GETDLGCODE.


FN_DLGC_WANTARROWS
DLGC_WANTARROWS  0x0001  winuser.h


DLGC_WANTCHARS
DLGC_WANTCHARS  0x0080  winuser.h

WM_CHAR messages See WM_GETDLGCODE.


FN_DLGC_WANTCHARS
DLGC_WANTCHARS  0x0080  winuser.h


DLGC_WANTMESSAGE
DLGC_WANTMESSAGE  0x0004  winuser.h

All keyboard input (the application passes this message on to control) See WM_GETDLGCODE.


FN_DLGC_WANTMESSAGE
DLGC_WANTMESSAGE  0x0004  winuser.h


DLGC_WANTTAB
DLGC_WANTTAB  0x0002  winuser.h

TAB key See WM_GETDLGCODE.


FN_DLGC_WANTTAB
DLGC_WANTTAB  0x0002  winuser.h


DM_INTERLACED
DM_INTERLACED  0x00000002  wingdi.h

Specifies that the display mode is interlaced. If the flag is not set, NON-interlaced is assumed. See DEVMODE.


FN_DM_INTERLACED
DM_INTERLACED  0x00000002  wingdi.h


DMLERR_ADVACKTIMEOUT
DMLERR_ADVACKTIMEOUT  0x4000  ddeml.h

A request for a synchronous advise transaction has timed out. See DdeGetLastError.


FN_DMLERR_ADVACKTIMEOUT
DMLERR_ADVACKTIMEOUT  0x4000  ddeml.h


DMLERR_BUSY
DMLERR_BUSY  0x4001  ddeml.h

The response to the transaction caused the DDE_FBUSY bit to be set. See DdeGetLastError.


FN_DMLERR_BUSY
DMLERR_BUSY  0x4001  ddeml.h


DMLERR_DATAACKTIMEOUT
DMLERR_DATAACKTIMEOUT  0x4002  ddeml.h

A request for a synchronous data transaction has timed out. See DdeGetLastError.


FN_DMLERR_DATAACKTIMEOUT
DMLERR_DATAACKTIMEOUT  0x4002  ddeml.h


DMLERR_DLL_NOT_INITIALIZED
DMLERR_DLL_NOT_INITIALIZED  0x4003  ddeml.h

A DDEML function was called without first calling the DdeInitialize function, or an invalid instance identifier was passed to a DDEML function. See DdeGetLastError.


FN_DMLERR_DLL_NOT_INITIALIZED
DMLERR_DLL_NOT_INITIALIZED  0x4003  ddeml.h


DMLERR_DLL_USAGE
DMLERR_DLL_USAGE  0x4004  ddeml.h

An application initialized as APPCLASS_MONITOR has attempted to perform a DDE transaction, or an application initialized as APPCMD_CLIENTONLY has attempted to perform server transactions. See DdeGetLastError.


FN_DMLERR_DLL_USAGE
DMLERR_DLL_USAGE  0x4004  ddeml.h


DMLERR_EXECACKTIMEOUT
DMLERR_EXECACKTIMEOUT  0x4005  ddeml.h

A request for a synchronous execute transaction has timed out. See DdeGetLastError.


FN_DMLERR_EXECACKTIMEOUT
DMLERR_EXECACKTIMEOUT  0x4005  ddeml.h


DMLERR_INVALIDPARAMETER
DMLERR_INVALIDPARAMETER  0x4006  ddeml.h

A parameter failed to be validated by the DDEML. Some of the possible causes are as follows: The application used a data handle initialized with a different item-name handle than required by the transaction. The application used a data handle that was initialized with a different clipboard data format than required by the transaction. The application used a client-side conversation handle with a server-side function or vise versa. The application used a freed data handle or string handle. More than one instance of the application used the same object. See DdeGetLastError.


FN_DMLERR_INVALIDPARAMETER
DMLERR_INVALIDPARAMETER  0x4006  ddeml.h


DMLERR_LOW_MEMORY
DMLERR_LOW_MEMORY  0x4007  ddeml.h

Memory is low--advise, poke, or execute data may be lost, or the system may fail. See XTYP_ERROR.


FN_DMLERR_LOW_MEMORY
DMLERR_LOW_MEMORY  0x4007  ddeml.h


DMPAPER_A4
DMPAPER_A4  9  wingdi.h

210-by-297-millimeter paper See DEVMODE.


FN_DMPAPER_A4
DMPAPER_A4  9  wingdi.h


DMPAPER_CSHEET
DMPAPER_CSHEET  24  wingdi.h

17-by-22-inch paper See DEVMODE.


FN_DMPAPER_CSHEET
DMPAPER_CSHEET  24  wingdi.h


DMPAPER_DSHEET
DMPAPER_DSHEET  25  wingdi.h

22-by-34-inch paper See DEVMODE.


FN_DMPAPER_DSHEET
DMPAPER_DSHEET  25  wingdi.h


DMPAPER_ENV_10
DMPAPER_ENV_10  20  wingdi.h

4 1/8 short dm 8 -by-9 1/5 short dm 8 -inch #10 envelope See DEVMODE.


FN_DMPAPER_ENV_10
DMPAPER_ENV_10  20  wingdi.h


DMPAPER_ENV_11
DMPAPER_ENV_11  21  wingdi.h

4 1/2 short dm 8 -by-10 3/8 short dm 8 -inch #11 envelope See DEVMODE.


FN_DMPAPER_ENV_11
DMPAPER_ENV_11  21  wingdi.h


DMPAPER_ENV_12
DMPAPER_ENV_12  22  wingdi.h

4 3/4 short dm 8 -by-11-inch #12 envelope See DEVMODE.


FN_DMPAPER_ENV_12
DMPAPER_ENV_12  22  wingdi.h


DMPAPER_ENV_14
DMPAPER_ENV_14  23  wingdi.h

5-by-11 1/2 short dm 8 -inch #14 envelope See DEVMODE.


FN_DMPAPER_ENV_14
DMPAPER_ENV_14  23  wingdi.h


DMPAPER_ENV_9
DMPAPER_ENV_9  19  wingdi.h

3 7/8 short dm 8 -by-8 7/8 short dm 8 -inch #9 envelope See DEVMODE.


FN_DMPAPER_ENV_9
DMPAPER_ENV_9  19  wingdi.h


DMPAPER_ESHEET
DMPAPER_ESHEET  26  wingdi.h

34-by-44-inch paper See DEVMODE.


FN_DMPAPER_ESHEET
DMPAPER_ESHEET  26  wingdi.h


DMPAPER_LEGAL
DMPAPER_LEGAL  5  wingdi.h

8 1/2 short dm 8 -by-14-inch paper See DEVMODE.


FN_DMPAPER_LEGAL
DMPAPER_LEGAL  5  wingdi.h


DMPAPER_LETTER
DMPAPER_LETTER  1  wingdi.h

8 1/2 short dm 8 -by-11-inch paper See DEVMODE.


FN_DMPAPER_LETTER
DMPAPER_LETTER  1  wingdi.h


DMTT_BITMAP
DMTT_BITMAP  1  wingdi.h

Prints TrueType fonts as graphics. This is the default action for dot-matrix printers. See DEVMODE.


FN_DMTT_BITMAP
DMTT_BITMAP  1  wingdi.h


DMTT_DOWNLOAD
DMTT_DOWNLOAD  2  wingdi.h

Downloads TrueType fonts as soft fonts. This is the default action for Hewlett-Packard printers that use Printer Control Language (PCL). See DEVMODE.


FN_DMTT_DOWNLOAD
DMTT_DOWNLOAD  2  wingdi.h


DMTT_SUBDEV
DMTT_SUBDEV  3  wingdi.h

Substitute device fonts for TrueType fonts. This is the default action for PostScript® printers. See DEVMODE.


FN_DMTT_SUBDEV
DMTT_SUBDEV  3  wingdi.h


DNS_FILTEROFF
DNS_FILTEROFF  0x0008  ddeml.h

Turns off service-name initiation filtering. If this flag is set, the server receives an XTYP_CONNECT transaction whenever another DDE application calls the DdeConnect function, regardless of the service name. See DdeNameService.


FN_DNS_FILTEROFF
DNS_FILTEROFF  0x0008  ddeml.h


DNS_FILTERON
DNS_FILTERON  0x0004  ddeml.h

Turns on service-name initiation filtering. This 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. See DdeNameService.


FN_DNS_FILTERON
DNS_FILTERON  0x0004  ddeml.h


DNS_REGISTER
DNS_REGISTER  0x0001  ddeml.h

Registers the given service name. See DdeNameService.


FN_DNS_REGISTER
DNS_REGISTER  0x0001  ddeml.h


DNS_UNREGISTER
DNS_UNREGISTER  0x0002  ddeml.h

Unregisters the given service name. If the hsz1 parameter is NULL, all service names registered by the server will be unregistered. See DdeNameService.


FN_DNS_UNREGISTER
DNS_UNREGISTER  0x0002  ddeml.h


DOUBLE_CLICK
DOUBLE_CLICK  0x0002  wincon.h

Indicates the second click (button press) of a double click. The first click is returned as a regular button-press event. See MOUSE_EVENT_RECORD.


FN_DOUBLE_CLICK
DOUBLE_CLICK  0x0002  wincon.h


DRAFT_QUALITY
DRAFT_QUALITY  1  wingdi.h

Appearance of the font is less important than when the PROOF_QUALITY value is used. For GDI raster fonts, scaling is enabled. Bold, italic, underline, and strikeout fonts are synthesized if necessary. See CreateFont, LOGFONT.


FN_DRAFT_QUALITY
DRAFT_QUALITY  1  wingdi.h


DRIVE_CDROM
DRIVE_CDROM  5  winbase.h

Drive is a CD ROM drive. See GetDriveType.


FN_DRIVE_CDROM
DRIVE_CDROM  5  winbase.h


DRIVE_FIXED
DRIVE_FIXED  3  winbase.h

Disk cannot be removed from the drive. See GetDriveType.


FN_DRIVE_FIXED
DRIVE_FIXED  3  winbase.h


DRIVE_RAMDISK
DRIVE_RAMDISK  6  winbase.h

Drive is a RAM disk. See GetDriveType.


FN_DRIVE_RAMDISK
DRIVE_RAMDISK  6  winbase.h


DRIVE_REMOTE
DRIVE_REMOTE  4  winbase.h

Drive is a remote (network) drive. See GetDriveType.


FN_DRIVE_REMOTE
DRIVE_REMOTE  4  winbase.h


DRIVE_REMOVABLE
DRIVE_REMOVABLE  2  winbase.h

Disk can be removed from the drive. See GetDriveType.


FN_DRIVE_REMOVABLE
DRIVE_REMOVABLE  2  winbase.h


DS_ABSALIGN
DS_ABSALIGN  0x01L  winuser.h

Specifies that the dialog box position is relative to the upper-left corner of the screen. If this style is not given, the position is relative to the upper-left corner of the owner window's client area. See CreateWindow, DLGTEMPLATE.


FN_DS_ABSALIGN
DS_ABSALIGN  0x01L  winuser.h


DS_LOCALEDIT
DS_LOCALEDIT  0x20L  winuser.h

Applies to 16-bit applications only. 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. See CreateWindow.


FN_DS_LOCALEDIT
DS_LOCALEDIT  0x20L  winuser.h


DS_MODALFRAME
DS_MODALFRAME  0x80L  winuser.h

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. See CreateWindow, DLGTEMPLATE.


FN_DS_MODALFRAME
DS_MODALFRAME  0x80L  winuser.h


DS_NOIDLEMSG
DS_NOIDLEMSG  0x100L  winuser.h

Suppresses WM_ENTERIDLE messages that Windows would otherwise send to the owner of the dialog box while the dialog box is displayed. See CreateWindow, DLGTEMPLATE.


FN_DS_NOIDLEMSG
DS_NOIDLEMSG  0x100L  winuser.h


DS_SETFONT
DS_SETFONT  0x40L  winuser.h

Indicates the dialog-box template (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_SETFONT Specifies that a font other than the system font is to be used to draw text in the dialog box and its controls. If this value is given, the dialog box template must specify a point size and typeface name as described in the "Comments" section. See CreateWindow, DLGTEMPLATE.


FN_DS_SETFONT
DS_SETFONT  0x40L  winuser.h


DS_SETFOREGROUND
DS_SETFOREGROUND  0x200L  winuser.h

Specifies that the application creating the dialog box is to be made the foreground task. Windows calls the SetForegroundWindow function to set the foreground task. See CreateWindow, DLGTEMPLATE.


FN_DS_SETFOREGROUND
DS_SETFOREGROUND  0x200L  winuser.h


DS_SYSMODAL
DS_SYSMODAL  0x02L  winuser.h

Creates a system-modal dialog box. See CreateWindow.


FN_DS_SYSMODAL
DS_SYSMODAL  0x02L  winuser.h


DSTINVERT
DSTINVERT  (DWORD)0x00550009  wingdi.h

Inverts the destination rectangle or bitmap. See BitBlt, PatBlt.


FN_DSTINVERT
DSTINVERT  (DWORD)0x00550009  wingdi.h


DT_BOTTOM
DT_BOTTOM  0x0008  winuser.h

Specifies bottom-justified text. This value must be combined with DT_SINGLELINE. See DrawText.


FN_DT_BOTTOM
DT_BOTTOM  0x0008  winuser.h


DT_CALCRECT
DT_CALCRECT  0x0400  winuser.h

Determines the width and height of the rectangle. If there are multiple lines of text, DrawText will use the width of the rectangle pointed to by the lprc parameter and extend the base of the rectangle to bound the last line of text. If there is only one line of text, DrawText will modify 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. See DrawText.


FN_DT_CALCRECT
DT_CALCRECT  0x0400  winuser.h


DT_CENTER
DT_CENTER  0x0001  winuser.h

Centers text horizontally. See DrawText.


FN_DT_CENTER
DT_CENTER  0x0001  winuser.h


DT_CHARSTREAM
DT_CHARSTREAM  4  wingdi.h

Character stream See GetDeviceCaps.


FN_DT_CHARSTREAM
DT_CHARSTREAM  4  wingdi.h


DT_DISPFILE
DT_DISPFILE  6  wingdi.h

Display file See GetDeviceCaps.


FN_DT_DISPFILE
DT_DISPFILE  6  wingdi.h


DT_EXPANDTABS
DT_EXPANDTABS  0x0040  winuser.h

Expands tab characters. The default number of characters per tab is eight. See DrawText.


FN_DT_EXPANDTABS
DT_EXPANDTABS  0x0040  winuser.h


DT_EXTERNALLEADING
DT_EXTERNALLEADING  0x0200  winuser.h

Includes the font external leading in line height. Normally, external leading is not included in the height of a line of text. See DrawText.


FN_DT_EXTERNALLEADING
DT_EXTERNALLEADING  0x0200  winuser.h


DT_LEFT
DT_LEFT  0x0000  winuser.h

Aligns text to the left. See DrawText.


FN_DT_LEFT
DT_LEFT  0x0000  winuser.h


DT_METAFILE
DT_METAFILE  5  wingdi.h

Metafile See GetDeviceCaps.


FN_DT_METAFILE
DT_METAFILE  5  wingdi.h


DT_NOCLIP
DT_NOCLIP  0x0100  winuser.h

Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is used. See DrawText.


FN_DT_NOCLIP
DT_NOCLIP  0x0100  winuser.h


DT_NOPREFIX
DT_NOPREFIX  0x0800  winuser.h

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. See DrawText.


FN_DT_NOPREFIX
DT_NOPREFIX  0x0800  winuser.h


DT_PLOTTER
DT_PLOTTER  0  wingdi.h

Vector plotter See GetDeviceCaps.


FN_DT_PLOTTER
DT_PLOTTER  0  wingdi.h


DT_RASCAMERA
DT_RASCAMERA  3  wingdi.h

Raster camera See GetDeviceCaps.


FN_DT_RASCAMERA
DT_RASCAMERA  3  wingdi.h


DT_RASDISPLAY
DT_RASDISPLAY  1  wingdi.h

Raster display See GetDeviceCaps.


FN_DT_RASDISPLAY
DT_RASDISPLAY  1  wingdi.h


DT_RASPRINTER
DT_RASPRINTER  2  wingdi.h

Raster printer See GetDeviceCaps.


FN_DT_RASPRINTER
DT_RASPRINTER  2  wingdi.h


DT_RIGHT
DT_RIGHT  0x0002  winuser.h

Aligns text to the right. See DrawText.


FN_DT_RIGHT
DT_RIGHT  0x0002  winuser.h


DT_SINGLELINE
DT_SINGLELINE  0x0020  winuser.h

Specifies single line only. Carriage returns and linefeeds do not break the line. See DrawText.


FN_DT_SINGLELINE
DT_SINGLELINE  0x0020  winuser.h


DT_TABSTOP
DT_TABSTOP  0x0080  winuser.h

Sets tab stops. Bits 15-8 (high-order byte of the low-order word) of the wFormat parameter is the number of characters for each tab. The default number of characters per tab is eight. See DrawText.


FN_DT_TABSTOP
DT_TABSTOP  0x0080  winuser.h


DT_TOP
DT_TOP  0x0000  winuser.h

Specifies top-justified text (single line only). See DrawText.


FN_DT_TOP
DT_TOP  0x0000  winuser.h


DT_VCENTER
DT_VCENTER  0x0004  winuser.h

Specifies vertically centered text (single line only). See DrawText.


FN_DT_VCENTER
DT_VCENTER  0x0004  winuser.h


DT_WORDBREAK
DT_WORDBREAK  0x0010  winuser.h

Specifies word breaking. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lprc parameter. A carriage return/linefeed sequence will also break the line. See DrawText.


FN_DT_WORDBREAK
DT_WORDBREAK  0x0010  winuser.h


DTR_CONTROL_DISABLE
DTR_CONTROL_DISABLE  0x00  winbase.h

Disable the DTR line on device open and leave it disabled. See DCB.


FN_DTR_CONTROL_DISABLE
DTR_CONTROL_DISABLE  0x00  winbase.h


DTR_CONTROL_ENABLE
DTR_CONTROL_ENABLE  0x01  winbase.h

Enable the DTR line on device open and leave it on. See DCB.


FN_DTR_CONTROL_ENABLE
DTR_CONTROL_ENABLE  0x01  winbase.h


DTR_CONTROL_HANDSHAKE
DTR_CONTROL_HANDSHAKE  0x02  winbase.h

Enable DTR handshaking. Note that if handshaking is enabled, it is an error for the application to adjust the line using the EscapeCommFunction function. See DCB.


FN_DTR_CONTROL_HANDSHAKE
DTR_CONTROL_HANDSHAKE  0x02  winbase.h


DUPLICATE
DUPLICATE  0x06  nb30.h

A duplicate name was detected during registration. See NAME_BUFFER.


FN_DUPLICATE
DUPLICATE  0x06  nb30.h


DUPLICATE_CLOSE_SOURCE
DUPLICATE_CLOSE_SOURCE  0x00000001  winnt.h

Close the source handle. This occurs regardless of any error status returned. See DuplicateHandle.


FN_DUPLICATE_CLOSE_SOURCE
DUPLICATE_CLOSE_SOURCE  0x00000001  winnt.h


DUPLICATE_DEREG
DUPLICATE_DEREG  0x07  nb30.h

A duplicate name was detected with a pending deregistration. See NAME_BUFFER.


FN_DUPLICATE_DEREG
DUPLICATE_DEREG  0x07  nb30.h


DUPLICATE_SAME_ACCESS
DUPLICATE_SAME_ACCESS  0x00000002  winnt.h

Ignore the fdwAccess parameter. The duplicate handle has the same access as the source handle. See DuplicateHandle.


FN_DUPLICATE_SAME_ACCESS
DUPLICATE_SAME_ACCESS  0x00000002  winnt.h


DWL_DLGPROC
DWL_DLGPROC  4  winuser.h

Specifies the address of the dialog box procedure. See GetWindowLong, SetWindowLong.


FN_DWL_DLGPROC
DWL_DLGPROC  4  winuser.h


DWL_MSGRESULT
DWL_MSGRESULT  0  winuser.h

Specifies the return value of a message processed in the dialog box procedure. See GetWindowLong, SetWindowLong.


FN_DWL_MSGRESULT
DWL_MSGRESULT  0  winuser.h


DWL_USER
DWL_USER  8  winuser.h

Specifies extra information that is private to the application, such as handles or pointers. See GetWindowLong, SetWindowLong.


FN_DWL_USER
DWL_USER  8  winuser.h


EC_DISABLE
EC_DISABLE  ST_BLOCKED  ddeml.h

Disables all blockable transactions for the specified conversation. A server application can disable the following transactions: A client application can disable the following transactions: See DdeEnableCallback.


FN_EC_DISABLE
EC_DISABLE  ST_BLOCKED  ddeml.h


EC_ENABLEALL
EC_ENABLEALL  0  ddeml.h

Enables all transactions for the specified conversation. See DdeEnableCallback.


FN_EC_ENABLEALL
EC_ENABLEALL  0  ddeml.h


EC_ENABLEONE
EC_ENABLEONE  ST_BLOCKNEXT  ddeml.h

Enables one transaction for the specified conversation. See DdeEnableCallback.


FN_EC_ENABLEONE
EC_ENABLEONE  ST_BLOCKNEXT  ddeml.h


EC_QUERYWAITING
EC_QUERYWAITING  2  ddeml.h

Determines whether any transactions are in the queue for the specified conversation. See DdeEnableCallback.


FN_EC_QUERYWAITING
EC_QUERYWAITING  2  ddeml.h


EDIT

Designates a rectangular child window in 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 control displays a flashing caret. The mouse can be used to move the cursor, select characters to be replaced, or position the cursor for inserting characters. The BACKSPACE key can be used to delete characters. Edit controls use the variable-pitch system font and display characters from the Windows character set. Applications compiled to run with earlier versions of Windows display text with a fixed-pitch system font unless they have been marked by the Windows 3.0 MARK utility (specified with the MEMORY FONT option). You can also send the WM_SETFONT message 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. See CreateWindow.


ENABLE_ECHO_INPUT
ENABLE_ECHO_INPUT  0x0004  wincon.h

Characters read by ReadFile or ReadConsole are written to the screen as they are read. Can only be used if ENABLE_LINE_INPUT is also enabled. See GetConsoleMode.


FN_ENABLE_ECHO_INPUT
ENABLE_ECHO_INPUT  0x0004  wincon.h


ENABLE_LINE_INPUT
ENABLE_LINE_INPUT  0x0002  wincon.h

ReadFile or ReadConsole return only when a CR (carriage return) character is read. If disabled, ReadFile or ReadConsole return when one or more characters are available. See GetConsoleMode.


FN_ENABLE_LINE_INPUT
ENABLE_LINE_INPUT  0x0002  wincon.h


ENABLE_MOUSE_INPUT
ENABLE_MOUSE_INPUT  0x0010  wincon.h

Mouse events generated by mouse movement and button presses are placed in the input buffer, if the mouse pointer is within the borders of the console window and the window has the keyboard focus. These events are discarded by ReadFile or ReadConsole, even when ENABLE_MOUSE_INPUT is enabled. See GetConsoleMode.


FN_ENABLE_MOUSE_INPUT
ENABLE_MOUSE_INPUT  0x0010  wincon.h


ENABLE_PROCESSED_INPUT
ENABLE_PROCESSED_INPUT  0x0001  wincon.h

Ctrl-C is processed by the system and 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 not returned in the ReadFile or ReadConsole buffer. If ENABLE_LINE_INPUT is also enabled, BKSP (backspace), CR (carriage return), and LF (linefeed) are handled by the system. See GetConsoleMode.


FN_ENABLE_PROCESSED_INPUT
ENABLE_PROCESSED_INPUT  0x0001  wincon.h


ENABLE_PROCESSED_OUTPUT
ENABLE_PROCESSED_OUTPUT  0x0001  wincon.h

Characters written by WriteFile or WriteConsole or echoed by ReadFile or ReadConsole are parsed for ASCII control sequences and the correct action is performed. BKSP (backspace), TAB, bell, CR (carriage return) and LF (linefeed) characters are processed. See GetConsoleMode.


FN_ENABLE_PROCESSED_OUTPUT
ENABLE_PROCESSED_OUTPUT  0x0001  wincon.h


ENABLE_WINDOW_INPUT
ENABLE_WINDOW_INPUT  0x0008  wincon.h

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 ReadConsoleInput, but not by those using ReadFile or ReadConsole. See GetConsoleMode.


FN_ENABLE_WINDOW_INPUT
ENABLE_WINDOW_INPUT  0x0008  wincon.h


ENABLE_WRAP_AT_EOL_OUTPUT
ENABLE_WRAP_AT_EOL_OUTPUT  0x0002  wincon.h

When writing with WriteFile or WriteConsole or echoing with ReadFile or ReadConsole, the cursor moves to the beginning of the next line when it reaches the end of the current row. This can result in scrolling the lines displayed in the window, or in scrolling the contents of the screen buffer and discarding the top line (when the cursor goes beyond the bottom, right cell). If disabled, the last character in the row is overwritten. See GetConsoleMode.


FN_ENABLE_WRAP_AT_EOL_OUTPUT
ENABLE_WRAP_AT_EOL_OUTPUT  0x0002  wincon.h


ENHANCED_KEY
ENHANCED_KEY  0x0100  wincon.h

The key is enhanced. See KEY_EVENT_RECORD.


FN_ENHANCED_KEY
ENHANCED_KEY  0x0100  wincon.h


ERROR
ERROR  0  wingdi.h

Error occurred. See CombineRgn, ExtSelectClipRgn, IntersectClipRect, OffsetClipRgn, SelectClipRgn, SetMetaRgn.


FN_ERROR
ERROR  0  wingdi.h


ESB_DISABLE_BOTH
ESB_DISABLE_BOTH  0x0003  winuser.h

Disables both arrows on a scroll bar. See EnableScrollBar.


FN_ESB_DISABLE_BOTH
ESB_DISABLE_BOTH  0x0003  winuser.h


ESB_DISABLE_LTUP
ESB_DISABLE_LTUP  ESB_DISABLE_LEFT  winuser.h

Disables the left arrow on a horizontal scroll bar or the up arrow of a vertical scroll bar. See EnableScrollBar.


FN_ESB_DISABLE_LTUP
ESB_DISABLE_LTUP  ESB_DISABLE_LEFT  winuser.h


ESB_DISABLE_RTDN
ESB_DISABLE_RTDN  ESB_DISABLE_RIGHT  winuser.h

Disables the right arrow on a horizontal scroll bar or the down arrow of a vertical scroll bar. See EnableScrollBar.


FN_ESB_DISABLE_RTDN
ESB_DISABLE_RTDN  ESB_DISABLE_RIGHT  winuser.h


ESB_ENABLE_BOTH
ESB_ENABLE_BOTH  0x0000  winuser.h

Enables both arrows on a scroll bar. See EnableScrollBar.


FN_ESB_ENABLE_BOTH
ESB_ENABLE_BOTH  0x0000  winuser.h


ETO_CLIPPED
ETO_CLIPPED  4  wingdi.h

Each string will be clipped to its given rectangle. See ExtTextOut, POLYTEXT.


FN_ETO_CLIPPED
ETO_CLIPPED  4  wingdi.h


ETO_DELTAVECTOR

Each string is accompanied by an array of character widths, as in ExtTextOut. See POLYTEXT.


ETO_OPAQUE
ETO_OPAQUE  2  wingdi.h

Specifies that the current background color should be used to fill the rectangle. See ExtTextOut, POLYTEXT.


FN_ETO_OPAQUE
ETO_OPAQUE  2  wingdi.h


EVENPARITY
EVENPARITY  2  winbase.h

Even parity. See DCB.


FN_EVENPARITY
EVENPARITY  2  winbase.h


EVENTLOG_AUDIT_FAILURE
EVENTLOG_AUDIT_FAILURE  0x0010  winnt.h

Security audit failure See ReportEvent.


FN_EVENTLOG_AUDIT_FAILURE
EVENTLOG_AUDIT_FAILURE  0x0010  winnt.h


EVENTLOG_AUDIT_SUCCESS
EVENTLOG_AUDIT_SUCCESS  0x0008  winnt.h

Security audit success See ReportEvent.


FN_EVENTLOG_AUDIT_SUCCESS
EVENTLOG_AUDIT_SUCCESS  0x0008  winnt.h


EVENTLOG_BACKWARDS_READ
EVENTLOG_BACKWARDS_READ  0X0008  winnt.h

Specifies that the log is read in reverse chronological order. See ReadEventLog.


FN_EVENTLOG_BACKWARDS_READ
EVENTLOG_BACKWARDS_READ  0X0008  winnt.h


EVENTLOG_ERROR_TYPE
EVENTLOG_ERROR_TYPE  0x0001  winnt.h

Error event See ReportEvent.


FN_EVENTLOG_ERROR_TYPE
EVENTLOG_ERROR_TYPE  0x0001  winnt.h


EVENTLOG_FORWARDS_READ
EVENTLOG_FORWARDS_READ  0X0004  winnt.h

Specifies that the log is read in forward chronological order. See ReadEventLog.


FN_EVENTLOG_FORWARDS_READ
EVENTLOG_FORWARDS_READ  0X0004  winnt.h


EVENTLOG_INFORMATION_TYPE
EVENTLOG_INFORMATION_TYPE  0x0004  winnt.h

Information event See ReportEvent.


FN_EVENTLOG_INFORMATION_TYPE
EVENTLOG_INFORMATION_TYPE  0x0004  winnt.h


EVENTLOG_SEEK_READ
EVENTLOG_SEEK_READ  0X0002  winnt.h

Specifies that the read operation proceeds from the record specified by dwRecordNumber. If this flag is used, fdwRead must also specify either EVENTLOG_FORWARDS_READ or EVENTLOG_BACKWARDS_READ. If the buffer is large enough, more than one record may be read at the specified seek position; the additional flag indicates the direction for successive read operations. See ReadEventLog.


FN_EVENTLOG_SEEK_READ
EVENTLOG_SEEK_READ  0X0002  winnt.h


EVENTLOG_SEQUENTIAL_READ
EVENTLOG_SEQUENTIAL_READ  0X0001  winnt.h

Specifies that the read operation proceeds sequentially from the last call to the ReadEventLog function using this handle. See ReadEventLog.


FN_EVENTLOG_SEQUENTIAL_READ
EVENTLOG_SEQUENTIAL_READ  0X0001  winnt.h


EVENTLOG_WARNING_TYPE
EVENTLOG_WARNING_TYPE  0x0002  winnt.h

Warning event See ReportEvent.


FN_EVENTLOG_WARNING_TYPE
EVENTLOG_WARNING_TYPE  0x0002  winnt.h


EWX_FORCE
EWX_FORCE  4  winuser.h

Forces processes to terminate. Instead of bringing up the "application not responding" dialog for the user, this flag forces an application to terminate if it does not respond. See ExitWindowsEx.


FN_EWX_FORCE
EWX_FORCE  4  winuser.h


EWX_LOGOFF
EWX_LOGOFF  0  winuser.h

Logoff the user. Involves shutting down all processes running in the security context of the process which called ExitWindowsEx. It then logs the user off. See ExitWindowsEx.


FN_EWX_LOGOFF
EWX_LOGOFF  0  winuser.h


EWX_REBOOT
EWX_REBOOT  2  winuser.h

Shuts down the system and then reboots the system. The application must have the SE_SHUTDOWN_NAME privilege (see the Comments section for details). See ExitWindowsEx.


FN_EWX_REBOOT
EWX_REBOOT  2  winuser.h


EWX_SHUTDOWN
EWX_SHUTDOWN  1  winuser.h

Shuts down the system to a point where it is safe to turn off the power. All file buffers have been flushed to disk, and all running processes have stopped. The application must have the SE_SHUTDOWN_NAME privilege (see the Comments section for details). See ExitWindowsEx.


FN_EWX_SHUTDOWN
EWX_SHUTDOWN  1  winuser.h


EXCEPTION_CONTINUE_EXECUTION

Execution was continued at the instruction that caused the exception. This typically occurs after an exception handler modifies the context record so that the faulting instruction does not fail again. See UnhandledExceptionFilter.


EXCEPTION_CONTINUE_SEARCH

The process is being debugged, so this exception should be passed (as second chance) to the application's debugger. See UnhandledExceptionFilter.


EXCEPTION_DEBUG_EVENT
EXCEPTION_DEBUG_EVENT  1  winbase.h

Reports an exception debugging event. The value of u.Exception specifies an EXCEPTION_DEBUG_INFO structure. See DEBUG_EVENT.


FN_EXCEPTION_DEBUG_EVENT
EXCEPTION_DEBUG_EVENT  1  winbase.h


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. See UnhandledExceptionFilter.


EXIT_PROCESS_DEBUG_EVENT
EXIT_PROCESS_DEBUG_EVENT  5  winbase.h

Reports an exit process debugging event. The value of u.ExitProcess specifies an EXIT_PROCESS_DEBUG_INFO structure. See DEBUG_EVENT.


FN_EXIT_PROCESS_DEBUG_EVENT
EXIT_PROCESS_DEBUG_EVENT  5  winbase.h


EXIT_THREAD_DEBUG_EVENT
EXIT_THREAD_DEBUG_EVENT  4  winbase.h

Reports an exit thread debugging event. The value of u.ExitThread specifies an EXIT_THREAD_DEBUG_INFO structure. See DEBUG_EVENT.


FN_EXIT_THREAD_DEBUG_EVENT
EXIT_THREAD_DEBUG_EVENT  4  winbase.h


FAILED_ACCESS_ACE_FLAG
FAILED_ACCESS_ACE_FLAG  (0x80)  winnt.h

Used with system-audit and system-alarm ACEs to indicate that a message is generated for failed access attempts. See ACE_HEADER.


FN_FAILED_ACCESS_ACE_FLAG
FAILED_ACCESS_ACE_FLAG  (0x80)  winnt.h


FALT
FALT  0x10  winuser.h

The ALT key must be held down when the accelerator key is pressed. See ACCEL.


FN_FALT
FALT  0x10  winuser.h


FCONTROL
FCONTROL  0x08  winuser.h

The CONTROL key must be held down when the accelerator key is pressed. See ACCEL.


FN_FCONTROL
FCONTROL  0x08  winuser.h


FF_DECORATIVE
FF_DECORATIVE  (5<<4)  wingdi.h

Novelty fonts. Old English, for example. See CreateFont, LOGFONT.


FN_FF_DECORATIVE
FF_DECORATIVE  (5<<4)  wingdi.h


FF_DONTCARE
FF_DONTCARE  (0<<4)  wingdi.h

Don't care or don't know. See CreateFont, LOGFONT.


FN_FF_DONTCARE
FF_DONTCARE  (0<<4)  wingdi.h


FF_MODERN
FF_MODERN  (3<<4)  wingdi.h

Fonts with constant stroke width (fixed-pitch), with or without serifs. Fixed-pitch fonts are usually modern. Pica, Elite, and Courier, for example. See CreateFont, LOGFONT.


FN_FF_MODERN
FF_MODERN  (3<<4)  wingdi.h


FF_ROMAN
FF_ROMAN  (1<<4)  wingdi.h

Fonts with variable stroke width (proportionally spaced) and with serifs. Times Roman, Palatino, and Century Schoolbook, for example. See CreateFont, LOGFONT.


FN_FF_ROMAN
FF_ROMAN  (1<<4)  wingdi.h


FF_SCRIPT
FF_SCRIPT  (4<<4)  wingdi.h

Fonts designed to look like handwriting. Script and Cursive, for example. See CreateFont, LOGFONT.


FN_FF_SCRIPT
FF_SCRIPT  (4<<4)  wingdi.h


FF_SWISS
FF_SWISS  (2<<4)  wingdi.h

Fonts with variable stroke width (proportionally spaced) and without serifs. Helvetica and Swiss(TM), for example. See CreateFont, LOGFONT.


FN_FF_SWISS
FF_SWISS  (2<<4)  wingdi.h


FILE_ATTRIBUTE_ARCHIVE
FILE_ATTRIBUTE_ARCHIVE  0x00000020  winnt.h

The file is an archive file. Applications use this flag to mark files for backup or removal. See CreateFile, GetFileAttributes.


FN_FILE_ATTRIBUTE_ARCHIVE
FILE_ATTRIBUTE_ARCHIVE  0x00000020  winnt.h


FILE_ATTRIBUTE_ATOMIC_WRITE
FILE_ATTRIBUTE_ATOMIC_WRITE  0x00000200  winnt.h

Reserved for future use. Do not specify. See CreateFile, GetFileAttributes.


FN_FILE_ATTRIBUTE_ATOMIC_WRITE
FILE_ATTRIBUTE_ATOMIC_WRITE  0x00000200  winnt.h


FILE_ATTRIBUTE_DIRECTORY
FILE_ATTRIBUTE_DIRECTORY  0x00000010  winnt.h

The file is a directory. See GetFileAttributes.


FN_FILE_ATTRIBUTE_DIRECTORY
FILE_ATTRIBUTE_DIRECTORY  0x00000010  winnt.h


FILE_ATTRIBUTE_HIDDEN
FILE_ATTRIBUTE_HIDDEN  0x00000002  winnt.h

The file is hidden. It will not be included in an ordinary directory listing. See CreateFile, GetFileAttributes.


FN_FILE_ATTRIBUTE_HIDDEN
FILE_ATTRIBUTE_HIDDEN  0x00000002  winnt.h


FILE_ATTRIBUTE_NORMAL
FILE_ATTRIBUTE_NORMAL  0x00000080  winnt.h

The file has no other attributes set. This attribute is valid only if used alone. See CreateFile, GetFileAttributes.


FN_FILE_ATTRIBUTE_NORMAL
FILE_ATTRIBUTE_NORMAL  0x00000080  winnt.h


FILE_ATTRIBUTE_READONLY
FILE_ATTRIBUTE_READONLY  0x00000001  winnt.h

The file is read-only. Applications can read the file, but cannot write to it or delete it. See CreateFile, GetFileAttributes.


FN_FILE_ATTRIBUTE_READONLY
FILE_ATTRIBUTE_READONLY  0x00000001  winnt.h


FILE_ATTRIBUTE_SYSTEM
FILE_ATTRIBUTE_SYSTEM  0x00000004  winnt.h

The file is part of or used exclusively by the operating system. See CreateFile, GetFileAttributes.


FN_FILE_ATTRIBUTE_SYSTEM
FILE_ATTRIBUTE_SYSTEM  0x00000004  winnt.h


FILE_ATTRIBUTE_TEMPORARY
FILE_ATTRIBUTE_TEMPORARY  0x00000100  winnt.h

The file is a temporary file. 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. See CreateFile, GetFileAttributes.


FN_FILE_ATTRIBUTE_TEMPORARY
FILE_ATTRIBUTE_TEMPORARY  0x00000100  winnt.h


FILE_ATTRIBUTE_XACTION_WRITE
FILE_ATTRIBUTE_XACTION_WRITE  0x00000400  winnt.h

Reserved for future use. Do not specify. See CreateFile, GetFileAttributes.


FN_FILE_ATTRIBUTE_XACTION_WRITE
FILE_ATTRIBUTE_XACTION_WRITE  0x00000400  winnt.h


FILE_BEGIN
FILE_BEGIN  0  winbase.h

The starting point is zero or the beginning of the file. If FILE_BEGIN is specified, then DistanceToMove is interpreted as an unsigned location for the new file pointer. See SetFilePointer.


FN_FILE_BEGIN
FILE_BEGIN  0  winbase.h


FILE_CURRENT
FILE_CURRENT  1  winbase.h

The current value of the file pointer is the starting point. See SetFilePointer.


FN_FILE_CURRENT
FILE_CURRENT  1  winbase.h


FILE_END
FILE_END  2  winbase.h

The current end-of-file position is the starting point. See SetFilePointer.


FN_FILE_END
FILE_END  2  winbase.h


FILE_FLAG_BACKUP_SEMANTICS
FILE_FLAG_BACKUP_SEMANTICS  0x02000000  winbase.h

Indicates that the file is being opened or created for a backup or restore operation. The system should ensure that the caller overrides file security checks, provided that the caller has permission to do so. See CreateFile.


FN_FILE_FLAG_BACKUP_SEMANTICS
FILE_FLAG_BACKUP_SEMANTICS  0x02000000  winbase.h


FILE_FLAG_DELETE_ON_CLOSE
FILE_FLAG_DELETE_ON_CLOSE  0x04000000  winbase.h

Indicates that the system should immediately delete the file after all of its handles have been closed. See CreateFile.


FN_FILE_FLAG_DELETE_ON_CLOSE
FILE_FLAG_DELETE_ON_CLOSE  0x04000000  winbase.h


FILE_FLAG_NO_BUFFERING
FILE_FLAG_NO_BUFFERING  0x20000000  winbase.h

Indicates that the file is to be opened with no intermediate buffering or caching done by the system. Reads and writes to the file must be done on sector boundaries. Buffer addresses for reads and writes must be aligned on disk sector boundaries in memory. You can determine sector size with the GetDiskFreeSpace function. See CreateFile.


FN_FILE_FLAG_NO_BUFFERING
FILE_FLAG_NO_BUFFERING  0x20000000  winbase.h


FILE_FLAG_OVERLAPPED
FILE_FLAG_OVERLAPPED  0x40000000  winbase.h

Instructs the system to initialize the file so that ReadFile, WriteFile, ConnectNamedPipe, and TransactNamedPipe operations which take a significant time to process return ERROR_IO_PENDING. When the operation is finished, an event is set to the signaled state. When FILE_FLAG_OVERLAPPED is specified, the system does not maintain the file pointer. The file position must be passed as part of the OVERLAPPED structure argument to ReadFile and WriteFile. If this flag is specified, the ReadFile and WriteFile functions must specify an OVERLAPPED structure. This flag also enables more than one operation to be simultaneously performed with the handle (a simultaneous read and write, for example). See CreateFile.


FN_FILE_FLAG_OVERLAPPED
FILE_FLAG_OVERLAPPED  0x40000000  winbase.h


FILE_FLAG_POSIX_SEMANTICS
FILE_FLAG_POSIX_SEMANTICS  0x01000000  winbase.h

Indicates that the file should be accessed according to POSIX rules. This includes allowing multiple files with the same name, differing only in case, for file systems that support such naming. Developers must use care when using this option because files created with this flag may not be accessible from DOS, Win16, or Win32 applications. See CreateFile.


FN_FILE_FLAG_POSIX_SEMANTICS
FILE_FLAG_POSIX_SEMANTICS  0x01000000  winbase.h


FILE_FLAG_RANDOM_ACCESS
FILE_FLAG_RANDOM_ACCESS  0x10000000  winbase.h

Indicates that the file is accessed randomly. The Win32 API uses this flag to optimize file caching. See CreateFile.


FN_FILE_FLAG_RANDOM_ACCESS
FILE_FLAG_RANDOM_ACCESS  0x10000000  winbase.h


FILE_FLAG_SEQUENTIAL_SCAN
FILE_FLAG_SEQUENTIAL_SCAN  0x08000000  winbase.h

Indicates that the file is to be accessed sequentially from beginning to end; the file pointer is not moved. The Win32 API uses this flag to optimize file caching. If an application moves the file pointer, optimum caching cannot occur. See CreateFile.


FN_FILE_FLAG_SEQUENTIAL_SCAN
FILE_FLAG_SEQUENTIAL_SCAN  0x08000000  winbase.h


FILE_FLAG_WRITE_THROUGH
FILE_FLAG_WRITE_THROUGH  0x80000000  winbase.h

Instructs the system to always write through any intermediate cache and go directly to the file. The system can still cache writes, but cannot lazily flush the writes. See CreateFile.


FN_FILE_FLAG_WRITE_THROUGH
FILE_FLAG_WRITE_THROUGH  0x80000000  winbase.h


FILE_MAP_ALL_ACCESS
FILE_MAP_ALL_ACCESS  SECTION_ALL_ACCESS  winbase.h

Same as FILE_MAP_WRITE. See DuplicateHandle, MapViewOfFile, MapViewOfFileEx.


FN_FILE_MAP_ALL_ACCESS
FILE_MAP_ALL_ACCESS  SECTION_ALL_ACCESS  winbase.h


FILE_MAP_COPY
FILE_MAP_COPY  SECTION_QUERY  winbase.h

Copy-on-write access. A copy-on-write view of the file is mapped. See MapViewOfFile, MapViewOfFileEx


FN_FILE_MAP_COPY
FILE_MAP_COPY  SECTION_QUERY  winbase.h


FILE_MAP_READ
FILE_MAP_READ  SECTION_MAP_READ  winbase.h

Read-only access. A read-only view of the file is mapped. See DuplicateHandle, MapViewOfFile, MapViewOfFileEx.


FN_FILE_MAP_READ
FILE_MAP_READ  SECTION_MAP_READ  winbase.h


FILE_MAP_WRITE
FILE_MAP_WRITE  SECTION_MAP_WRITE  winbase.h

Read and write access. A read and write view of the file is mapped. See DuplicateHandle, MapViewOfFile, MapViewOfFileEx.


FN_FILE_MAP_WRITE
FILE_MAP_WRITE  SECTION_MAP_WRITE  winbase.h


FILE_NOTIFY_CHANGE_ATTRIBUTES
FILE_NOTIFY_CHANGE_ATTRIBUTES  0x00000004  winnt.h

Any attribute change in the watched directory or subtree satisfies a change notification wait. See FindFirstChangeNotification.


FN_FILE_NOTIFY_CHANGE_ATTRIBUTES
FILE_NOTIFY_CHANGE_ATTRIBUTES  0x00000004  winnt.h


FILE_NOTIFY_CHANGE_DIR_NAME
FILE_NOTIFY_CHANGE_DIR_NAME  0x00000002  winnt.h

Any directory-name change in the watched directory or subtree satisfies a change notification wait. This includes directory creations and deletions. See FindFirstChangeNotification.


FN_FILE_NOTIFY_CHANGE_DIR_NAME
FILE_NOTIFY_CHANGE_DIR_NAME  0x00000002  winnt.h


FILE_NOTIFY_CHANGE_FILE_NAME
FILE_NOTIFY_CHANGE_FILE_NAME  0x00000001  winnt.h

Any filename change in the watched directory or subtree satisfies a change notification wait. This includes renames, creations, and deletes. See FindFirstChangeNotification.


FN_FILE_NOTIFY_CHANGE_FILE_NAME
FILE_NOTIFY_CHANGE_FILE_NAME  0x00000001  winnt.h


FILE_NOTIFY_CHANGE_LAST_WRITE
FILE_NOTIFY_CHANGE_LAST_WRITE  0x00000010  winnt.h

Any change to the last write time of files in the watched directory or subtree satisfies a change notification wait. The system detects a change to the last write time only when the last write time changes on disk. For systems with extensive caching this can only occur when the system cache is sufficiently flushed. See FindFirstChangeNotification.


FN_FILE_NOTIFY_CHANGE_LAST_WRITE
FILE_NOTIFY_CHANGE_LAST_WRITE  0x00000010  winnt.h


FILE_NOTIFY_CHANGE_SECURITY
FILE_NOTIFY_CHANGE_SECURITY  0x00000100  winnt.h

Any security-descriptor change in the watched directory or subtree satisfies a change notification wait. See FindFirstChangeNotification.


FN_FILE_NOTIFY_CHANGE_SECURITY
FILE_NOTIFY_CHANGE_SECURITY  0x00000100  winnt.h


FILE_NOTIFY_CHANGE_SIZE
FILE_NOTIFY_CHANGE_SIZE  0x00000008  winnt.h

Any file-size change in the watched directory or subtree satisfies a change notification wait. The system detects a change in file size only when the file size changes on disk. For systems with extensive caching this can only occur when the system cache is sufficiently flushed. See FindFirstChangeNotification.


FN_FILE_NOTIFY_CHANGE_SIZE
FILE_NOTIFY_CHANGE_SIZE  0x00000008  winnt.h


FILE_SHARE_READ
FILE_SHARE_READ  0x00000001  winnt.h

Other open operations may be performed on the file or console screen buffer for read access. See CreateConsoleScreenBuffer, CreateFile.


FN_FILE_SHARE_READ
FILE_SHARE_READ  0x00000001  winnt.h


FILE_SHARE_WRITE
FILE_SHARE_WRITE  0x00000002  winnt.h

Other open operations may be performed on the file or console screen buffer for write access. See CreateConsoleScreenBuffer, CreateFile.


FN_FILE_SHARE_WRITE
FILE_SHARE_WRITE  0x00000002  winnt.h


FILE_TYPE_CHAR
FILE_TYPE_CHAR  0x0002  winbase.h

The specified file is a character file (typically an LPT device or a console). See GetFileType.


FN_FILE_TYPE_CHAR
FILE_TYPE_CHAR  0x0002  winbase.h


FILE_TYPE_DISK
FILE_TYPE_DISK  0x0001  winbase.h

The specified file is a disk file. See GetFileType.


FN_FILE_TYPE_DISK
FILE_TYPE_DISK  0x0001  winbase.h


FILE_TYPE_PIPE
FILE_TYPE_PIPE  0x0003  winbase.h

The specified file is a pipe (either a named or anonymous pipe). See GetFileType.


FN_FILE_TYPE_PIPE
FILE_TYPE_PIPE  0x0003  winbase.h


FILE_TYPE_UNKNOWN
FILE_TYPE_UNKNOWN  0x0000  winbase.h

The type of the specified file is unknown. See GetFileType.


FN_FILE_TYPE_UNKNOWN
FILE_TYPE_UNKNOWN  0x0000  winbase.h


FLOODFILLBORDER
FLOODFILLBORDER  0  wingdi.h

The fill area is bounded by the color specified by clrref. This style is identical to the filling performed by the FloodFill function. See ExtFloodFill.


FN_FLOODFILLBORDER
FLOODFILLBORDER  0  wingdi.h


FLOODFILLSURFACE
FLOODFILLSURFACE  1  wingdi.h

The fill area is defined by the color that is specified by clrref. Filling continues outward in all directions as long as the color is encountered. This style is useful for filling areas with multicolored boundaries. See ExtFloodFill.


FN_FLOODFILLSURFACE
FLOODFILLSURFACE  1  wingdi.h


FMFOCUS_DIR
FMFOCUS_DIR  1  wfext.h

Directory portion of a directory window See FM_GETFOCUS.


FN_FMFOCUS_DIR
FMFOCUS_DIR  1  wfext.h


FMFOCUS_DRIVES
FMFOCUS_DRIVES  3  wfext.h

Drive bar of a directory window See FM_GETFOCUS.


FN_FMFOCUS_DRIVES
FMFOCUS_DRIVES  3  wfext.h


FMFOCUS_SEARCH
FMFOCUS_SEARCH  4  wfext.h

Search Results window See FM_GETFOCUS.


FN_FMFOCUS_SEARCH
FMFOCUS_SEARCH  4  wfext.h


FMFOCUS_TREE
FMFOCUS_TREE  2  wfext.h

Tree portion of a directory window See FM_GETFOCUS.


FN_FMFOCUS_TREE
FMFOCUS_TREE  2  wfext.h


FNERR_BUFFERTOOSMALL
FNERR_BUFFERTOOSMALL  0x3003  cderr.h

Specifies the buffer for a filename is too small. (This buffer is pointed to by the lpstrFile member of the structure for a common dialog box.) See CommDlgExtendedError.


FN_FNERR_BUFFERTOOSMALL
FNERR_BUFFERTOOSMALL  0x3003  cderr.h


FNERR_INVALIDFILENAME
FNERR_INVALIDFILENAME  0x3002  cderr.h

Specifies a filename is invalid. See CommDlgExtendedError.


FN_FNERR_INVALIDFILENAME
FNERR_INVALIDFILENAME  0x3002  cderr.h


FNERR_SUBCLASSFAILURE
FNERR_SUBCLASSFAILURE  0x3001  cderr.h

Specifies an attempt to subclass a list box failed due to insufficient memory. See CommDlgExtendedError.


FN_FNERR_SUBCLASSFAILURE
FNERR_SUBCLASSFAILURE  0x3001  cderr.h


FNOINVERT
FNOINVERT  0x02  winuser.h

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. See ACCEL.


FN_FNOINVERT
FNOINVERT  0x02  winuser.h


FORMAT_MESSAGE_ALLOCATE_BUFFER
FORMAT_MESSAGE_ALLOCATE_BUFFER  0x00000100  winbase.h

Specifies that lpBuffer is the address of a VOID pointer and nSize specifies the minimum number of bytes to allocate for the formatted message. This function will allocate a buffer large enough to hold the formatted message and place a pointer to the buffer at lpBuffer. The caller should use the LocalFree function to free this pointer when it is no longer needed. See FormatMessage.


FN_FORMAT_MESSAGE_ALLOCATE_BUFFER
FORMAT_MESSAGE_ALLOCATE_BUFFER  0x00000100  winbase.h


FORMAT_MESSAGE_FROM_HMODULE
FORMAT_MESSAGE_FROM_HMODULE  0x00000800  winbase.h

Specifies that lpSource is a module handle that contains the message table resource or resources to search. If this handle is NULL, the current application's image file will be searched. See FormatMessage.


FN_FORMAT_MESSAGE_FROM_HMODULE
FORMAT_MESSAGE_FROM_HMODULE  0x00000800  winbase.h


FORMAT_MESSAGE_FROM_STRING
FORMAT_MESSAGE_FROM_STRING  0x00000400  winbase.h

Specifies that lpSource is a pointer to a null-terminated message definition that may contain insert sequences. See FormatMessage.


FN_FORMAT_MESSAGE_FROM_STRING
FORMAT_MESSAGE_FROM_STRING  0x00000400  winbase.h


FORMAT_MESSAGE_FROM_SYSTEM
FORMAT_MESSAGE_FROM_SYSTEM  0x00001000  winbase.h

Specifies that the function should search the system message table resource(s) for the requested message. This flag should only be used if fdwOptions does not include FORMAT_MESSAGE_FROM_STRING or FORMAT_MESSAGE_FROM_HMODULE. See FormatMessage.


FN_FORMAT_MESSAGE_FROM_SYSTEM
FORMAT_MESSAGE_FROM_SYSTEM  0x00001000  winbase.h


FORMAT_MESSAGE_IGNORE_INSERTS
FORMAT_MESSAGE_IGNORE_INSERTS  0x00000200  winbase.h

Specifies that insert sequences in the message definition should be ignored and passed through to the output buffer as is. This flag can be used to fetch a message for later formatting. If this flag is set, the lpArguments parameter is ignored. See FormatMessage.


FN_FORMAT_MESSAGE_IGNORE_INSERTS
FORMAT_MESSAGE_IGNORE_INSERTS  0x00000200  winbase.h


FR_DIALOGTERM
FR_DIALOGTERM  0x00000040  commdlg.h

Indicates the dialog box is terminating. The window handle returned by the FindText or ReplaceText function is not valid if with flag bit set. See FINDREPLACE.


FN_FR_DIALOGTERM
FR_DIALOGTERM  0x00000040  commdlg.h


FR_DOWN
FR_DOWN  0x00000001  commdlg.h

Determines the direction of searches through a document. If the flag is set, the search direction is down; if the flag is clear, the search direction is up. Initially, this flag specifies the state of the up/down checkbox; after the user closes the dialog, this flag specifies the user's selection. See FINDREPLACE.


FN_FR_DOWN
FR_DOWN  0x00000001  commdlg.h


FR_ENABLEHOOK
FR_ENABLEHOOK  0x00000100  commdlg.h

Enables the hook function specified in the lpfnHook member of this structure. This flag is only used to initialize the dialog. See FINDREPLACE.


FN_FR_ENABLEHOOK
FR_ENABLEHOOK  0x00000100  commdlg.h


FR_ENABLETEMPLATE
FR_ENABLETEMPLATE  0x00000200  commdlg.h

Causes the system to create the dialog box by using the dialog template identified by the hInstance and lpTemplateName members. This flag is only used to initialize the dialog. See FINDREPLACE.


FN_FR_ENABLETEMPLATE
FR_ENABLETEMPLATE  0x00000200  commdlg.h


FR_ENABLETEMPLATEHANDLE
FR_ENABLETEMPLATEHANDLE  0x00002000  commdlg.h

Indicates the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpTemplateName member if this flag is specified. See FINDREPLACE.


FN_FR_ENABLETEMPLATEHANDLE
FR_ENABLETEMPLATEHANDLE  0x00002000  commdlg.h


FR_FINDNEXT
FR_FINDNEXT  0x00000008  commdlg.h

Indicates the application should search for the next occurrence of the string specified by the lpstrFindWhat member. See FINDREPLACE.


FN_FR_FINDNEXT
FR_FINDNEXT  0x00000008  commdlg.h


FR_HIDEMATCHCASE
FR_HIDEMATCHCASE  0x00008000  commdlg.h

Causes the system to hide the Match Case box. See FINDREPLACE.


FN_FR_HIDEMATCHCASE
FR_HIDEMATCHCASE  0x00008000  commdlg.h


FR_HIDEUPDOWN
FR_HIDEUPDOWN  0x00004000  commdlg.h

Causes the system to hide the Direction box and the Up and Down controls. See FINDREPLACE.


FN_FR_HIDEUPDOWN
FR_HIDEUPDOWN  0x00004000  commdlg.h


FR_HIDEWHOLEWORD
FR_HIDEWHOLEWORD  0x00010000  commdlg.h

Causes the system to hide the Match Whole Word Only box. See FINDREPLACE.


FN_FR_HIDEWHOLEWORD
FR_HIDEWHOLEWORD  0x00010000  commdlg.h


FR_MATCHCASE
FR_MATCHCASE  0x00000004  commdlg.h

Set for case sensitive searches. See FINDREPLACE.


FN_FR_MATCHCASE
FR_MATCHCASE  0x00000004  commdlg.h


FR_NOMATCHCASE
FR_NOMATCHCASE  0x00000800  commdlg.h

Disables the "Match Case" checkbox. This flag is only used to initialize the dialog. See FINDREPLACE.


FN_FR_NOMATCHCASE
FR_NOMATCHCASE  0x00000800  commdlg.h


FR_NOUPDOWN
FR_NOUPDOWN  0x00000400  commdlg.h

Disables the direction radio buttons. This flag is only used to initialize the dialog. See FINDREPLACE.


FN_FR_NOUPDOWN
FR_NOUPDOWN  0x00000400  commdlg.h


FR_NOWHOLEWORD
FR_NOWHOLEWORD  0x00001000  commdlg.h

Disables the "Whole Word" checkbox. This flag is only used to initialize the dialog. See FINDREPLACE.


FN_FR_NOWHOLEWORD
FR_NOWHOLEWORD  0x00001000  commdlg.h


FR_REPLACE
FR_REPLACE  0x00000010  commdlg.h

Indicates the application should replace the current occurrence of the string specified in the lpstrFindWhat member with the string specified in the lpstrReplaceWith member. See FINDREPLACE.


FN_FR_REPLACE
FR_REPLACE  0x00000010  commdlg.h


FR_REPLACEALL
FR_REPLACEALL  0x00000020  commdlg.h

Indicates the application should replace all occurrences of the string specified in the lpstrFindWhat member with the string specified in the lpstrReplaceWith member. See FINDREPLACE.


FN_FR_REPLACEALL
FR_REPLACEALL  0x00000020  commdlg.h


FR_SHOWHELP
FR_SHOWHELP  0x00000080  commdlg.h

Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified. See FINDREPLACE.


FN_FR_SHOWHELP
FR_SHOWHELP  0x00000080  commdlg.h


FR_WHOLEWORD
FR_WHOLEWORD  0x00000002  commdlg.h

Checks the 'Whole Word' checkbox. Only whole words matching the search string will be considered. See FINDREPLACE.


FN_FR_WHOLEWORD
FR_WHOLEWORD  0x00000002  commdlg.h


FRERR_BUFFERLENGTHZERO
FRERR_BUFFERLENGTHZERO  0x4001  cderr.h

Specifies a member in a structure for the corresponding common dialog box points to an invalid buffer. See CommDlgExtendedError.


FN_FRERR_BUFFERLENGTHZERO
FRERR_BUFFERLENGTHZERO  0x4001  cderr.h


FS_CASE_IS_PRESERVED
FS_CASE_IS_PRESERVED  FILE_CASE_PRESERVED_NAMES  winbase.h

The case of filenames is preserved when the name is placed on disk. See GetVolumeInformation.


FN_FS_CASE_IS_PRESERVED
FS_CASE_IS_PRESERVED  FILE_CASE_PRESERVED_NAMES  winbase.h


FS_CASE_SENSITIVE
FS_CASE_SENSITIVE  FILE_CASE_SENSITIVE_SEARCH  winbase.h

The file system supports case sensitive filename lookup. See GetVolumeInformation.


FN_FS_CASE_SENSITIVE
FS_CASE_SENSITIVE  FILE_CASE_SENSITIVE_SEARCH  winbase.h


FS_UNICODE_STORED_ON_DISK
FS_UNICODE_STORED_ON_DISK  FILE_UNICODE_ON_DISK  winbase.h

The file system supports Unicode in filenames as they appear on disk. See GetVolumeInformation.


FN_FS_UNICODE_STORED_ON_DISK
FS_UNICODE_STORED_ON_DISK  FILE_UNICODE_ON_DISK  winbase.h


FSHIFT
FSHIFT  0x04  winuser.h

The SHIFT key must be held down when the accelerator key is pressed. See ACCEL.


FN_FSHIFT
FSHIFT  0x04  winuser.h


FVIRTKEY
FVIRTKEY  TRUE  winuser.h

The key member specifies a virtual-key code. If this flag is not specified, the key is assumed to specify an ASCII character code. See ACCEL.


FN_FVIRTKEY
FVIRTKEY  TRUE  winuser.h


FW_BOLD
FW_BOLD  700  wingdi.h

700 See CreateFont.


FN_FW_BOLD
FW_BOLD  700  wingdi.h


FW_DONTCARE
FW_DONTCARE  0  wingdi.h

0 See CreateFont.


FN_FW_DONTCARE
FW_DONTCARE  0  wingdi.h


FW_EXTRABOLD
FW_EXTRABOLD  800  wingdi.h

800 See CreateFont.


FN_FW_EXTRABOLD
FW_EXTRABOLD  800  wingdi.h


FW_EXTRALIGHT
FW_EXTRALIGHT  200  wingdi.h

200 See CreateFont.


FN_FW_EXTRALIGHT
FW_EXTRALIGHT  200  wingdi.h


FW_HEAVY
FW_HEAVY  900  wingdi.h

900 See CreateFont.


FN_FW_HEAVY
FW_HEAVY  900  wingdi.h


FW_LIGHT
FW_LIGHT  300  wingdi.h

300 See CreateFont.


FN_FW_LIGHT
FW_LIGHT  300  wingdi.h


FW_MEDIUM
FW_MEDIUM  500  wingdi.h

500 See CreateFont.


FN_FW_MEDIUM
FW_MEDIUM  500  wingdi.h


FW_NORMAL
FW_NORMAL  400  wingdi.h

400 See CreateFont.


FN_FW_NORMAL
FW_NORMAL  400  wingdi.h


FW_SEMIBOLD
FW_SEMIBOLD  600  wingdi.h

600 See CreateFont.


FN_FW_SEMIBOLD
FW_SEMIBOLD  600  wingdi.h


FW_THIN
FW_THIN  100  wingdi.h

100 See CreateFont.


FN_FW_THIN
FW_THIN  100  wingdi.h


GCL_CBCLSEXTRA
GCL_CBCLSEXTRA  (-20)  winuser.h

Retrieves or sets the size, in bytes, of the extra memory associated with the class. See GetClassLong, SetClassLong.


FN_GCL_CBCLSEXTRA
GCL_CBCLSEXTRA  (-20)  winuser.h


GCL_CBWNDEXTRA
GCL_CBWNDEXTRA  (-18)  winuser.h

Retrieves or sets 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 the descriptions of the GetWindowLong and GetWindowWord functions. See GetClassLong, SetClassLong.


FN_GCL_CBWNDEXTRA
GCL_CBWNDEXTRA  (-18)  winuser.h


GCL_HBRBACKGROUND
GCL_HBRBACKGROUND  (-10)  winuser.h

Retrieves the handle of the background brush associated with the class. See GetClassLong, SetClassLong.


FN_GCL_HBRBACKGROUND
GCL_HBRBACKGROUND  (-10)  winuser.h


GCL_HCURSOR
GCL_HCURSOR  (-12)  winuser.h

Retrieves the handle of the cursor associated with the class. See GetClassLong, SetClassLong.


FN_GCL_HCURSOR
GCL_HCURSOR  (-12)  winuser.h


GCL_HICON
GCL_HICON  (-14)  winuser.h

Retrieves the handle of the icon associated with the class. See GetClassLong, SetClassLong.


FN_GCL_HICON
GCL_HICON  (-14)  winuser.h


GCL_HMODULE
GCL_HMODULE  (-16)  winuser.h

Retrieves the handle of the module that registered the class. See GetClassLong, SetClassLong.


FN_GCL_HMODULE
GCL_HMODULE  (-16)  winuser.h


GCL_MENUNAME
GCL_MENUNAME  (-8)  winuser.h

Retrieves the address of the menu-name string. The string identifies the menu resource associated with the class. See GetClassLong, SetClassLong.


FN_GCL_MENUNAME
GCL_MENUNAME  (-8)  winuser.h


GCL_STYLE
GCL_STYLE  (-26)  winuser.h

Retrieves the window-class style bits. See GetClassLong, SetClassLong.


FN_GCL_STYLE
GCL_STYLE  (-26)  winuser.h


GCL_WNDPROC
GCL_WNDPROC  (-24)  winuser.h

Retrieves the address of the window procedure associated with the class. See GetClassLong, SetClassLong.


FN_GCL_WNDPROC
GCL_WNDPROC  (-24)  winuser.h


GDICOMMENT_IDENTIFIER
GDICOMMENT_IDENTIFIER  (0x43494447)

Indicates the start of an enhanced metafile public comment. See GdiComment.


FN_GDICOMMENT_IDENTIFIER
GDICOMMENT_IDENTIFIER  (0x43494447)


GDICOMMENT_WINDOWS_METAFILE
GDICOMMENT_WINDOWS_METAFILE  (0x80000001)

Indicates an enhanced metafile public comment that contains a Windows-format metafile that is equivalent to the enhanced-format metafile. See GdiComment.


FN_GDICOMMENT_WINDOWS_METAFILE
GDICOMMENT_WINDOWS_METAFILE  (0x80000001)


GDICOMMENT_BEGINGROUP
GDICOMMENT_BEGINGROUP  (0x00000002)

Indicates an enhanced metafile public comment that identifies the beginning of a group of drawing records. Requires a matching GDICOMMENT_ENDGROUP. See GdiComment.


FN_GDICOMMENT_BEGINGROUP
GDICOMMENT_BEGINGROUP  (0x00000002)


GDICOMMENT_ENDGROUP
GDICOMMENT_ENDGROUP  (0x00000003)

Indicates an enhanced metafile public comment that identifies the end of a group of drawing records. Requires a matching GDICOMMENT_BEGINGROUP. See GdiComment.


FN_GDICOMMENT_ENDGROUP
GDICOMMENT_ENDGROUP  (0x00000003)


GDICOMMENT_MULTIFORMATS
GDICOMMENT_MULTIFORMATS  (0x40000004)

Indicates an enhanced metafile public comment that allows multiple definitions of a picture to be included in an enhanced metafile. For example, this comment lets an application include an encapsulated PostScript definition as well as an enhanced metafile definition of a picture. See GdiComment.


FN_GDICOMMENT_MULTIFORMATS
GDICOMMENT_MULTIFORMATS  (0x40000004)


GENERIC_EXECUTE
GENERIC_EXECUTE  (0x20000000L)  winnt.h

Specifies execution access. A file can be executed.


FN_GENERIC_EXECUTE
GENERIC_EXECUTE  (0x20000000L)  winnt.h


GENERIC_READ
GENERIC_READ  (0x80000000L)  winnt.h

Specifies read access to the file or console screen buffer. Data can be read from the file and the file pointer can be moved. See CreateConsoleScreenBuffer, CreateFile, DuplicateHandle.


FN_GENERIC_READ
GENERIC_READ  (0x80000000L)  winnt.h


GENERIC_WRITE
GENERIC_WRITE  (0x40000000L)  winnt.h

Write access to the file or console screen buffer is requested. This allows data to be written to the console screen buffer. See CreateConsoleScreenBuffer, CreateFile, DuplicateHandle.


FN_GENERIC_WRITE
GENERIC_WRITE  (0x40000000L)  winnt.h


GET_TAPE_DRIVE_INFORMATION
GET_TAPE_DRIVE_INFORMATION  1  winbase.h

Retrieve or set information about the tape device. See GetTapeParameters, SetTapeParameters.


FN_GET_TAPE_DRIVE_INFORMATION
GET_TAPE_DRIVE_INFORMATION  1  winbase.h


GET_TAPE_MEDIA_INFORMATION
GET_TAPE_MEDIA_INFORMATION  0  winbase.h

Retrieve information about the tape in the tape device. See GetTapeParameters.


FN_GET_TAPE_MEDIA_INFORMATION
GET_TAPE_MEDIA_INFORMATION  0  winbase.h


GRAY_BRUSH
GRAY_BRUSH  2  wingdi.h

Gray brush See GetStockObject.


FN_GRAY_BRUSH
GRAY_BRUSH  2  wingdi.h


GROUP_NAME
GROUP_NAME  0x80  nb30.h

The name specified by the name member was created using the NCBADDGRNAME command. See NAME_BUFFER.


FN_GROUP_NAME
GROUP_NAME  0x80  nb30.h


GROUP_SECURITY_INFORMATION
GROUP_SECURITY_INFORMATION  (0X00000002L)  winnt.h

When set, this bit indicates the primary group ID of the object is being referenced. See SECURITY_INFORMATION.


FN_GROUP_SECURITY_INFORMATION
GROUP_SECURITY_INFORMATION  (0X00000002L)  winnt.h


GW_CHILD
GW_CHILD  5  winuser.h

The retrieved handle identifies the child window at the top of the Z order, if the given window is a parent window; otherwise, the retrieved handle is NULL. The function examines only child windows of the given window. It does not examine descendant windows. See GetWindow.


FN_GW_CHILD
GW_CHILD  5  winuser.h


GW_HWNDFIRST
GW_HWNDFIRST  0  winuser.h

The retrieved handle identifies the window at the top of the Z order. If the given window is a topmost window, the handle identifies the topmost window at the top of the Z order. If the given window is a top-level window, the handle identifies the top-level window at the top of the Z order. If the given window is a child window, the handle identifies the sibling window at the bottom of the Z order. See GetWindow.


FN_GW_HWNDFIRST
GW_HWNDFIRST  0  winuser.h


GW_HWNDLAST
GW_HWNDLAST  1  winuser.h

The retrieved handle identifies the window at the bottom of the Z order. If the given window is a topmost window, the handle identifies the topmost window at the bottom of the Z order. If the given window is a top-level window, the handle identifies the top-level window at the bottom of the Z order. If the given window is a child window, the handle identifies the sibling window at the bottom of the Z order. See GetWindow.


FN_GW_HWNDLAST
GW_HWNDLAST  1  winuser.h


GW_HWNDNEXT
GW_HWNDNEXT  2  winuser.h

The retrieved handle identifies the window below the given window in the Z order. If the given window is a topmost window, the handle identifies the topmost window below the given window. If the given window is a top-level window, the handle identifies the top-level window below the given window. If the given window is a child window, the handle identifies the sibling window below the given window. See GetNextWindow, GetWindow.


FN_GW_HWNDNEXT
GW_HWNDNEXT  2  winuser.h


GW_HWNDPREV
GW_HWNDPREV  3  winuser.h

Returns the handle of the window above the given window. GW_HWNDPREV The retrieved handle identifies the window above the given window in the Z order. If the given window is a topmost window, the handle identifies the topmost window above the given window. If the given window is a top-level window, the handle identifies the top-level window above the given window. If the given window is a child window, the handle identifies the sibling window above the given window. See GetNextWindow, GetWindow.


FN_GW_HWNDPREV
GW_HWNDPREV  3  winuser.h


GW_OWNER
GW_OWNER  4  winuser.h

The retrieved handle identifies the given window's owner window, if any. See GetWindow.


FN_GW_OWNER
GW_OWNER  4  winuser.h


GWL_EXSTYLE
GWL_EXSTYLE  (-20)  winuser.h

Retrieves or sets the extended window styles. See GetWindowLong, SetWindowLong.


FN_GWL_EXSTYLE
GWL_EXSTYLE  (-20)  winuser.h


GWL_HINSTANCE
GWL_HINSTANCE  (-6)  winuser.h

Retrieves or sets the handle of the application instance. See GetWindowLong, SetWindowLong.


FN_GWL_HINSTANCE
GWL_HINSTANCE  (-6)  winuser.h


GWL_HWNDPARENT
GWL_HWNDPARENT  (-8)  winuser.h

Retrieves the handle of the parent window, if any. See GetWindowLong.


FN_GWL_HWNDPARENT
GWL_HWNDPARENT  (-8)  winuser.h


GWL_ID
GWL_ID  (-12)  winuser.h

Retrieves or sets the identifier of the window. See GetWindowLong, SetWindowLong.


FN_GWL_ID
GWL_ID  (-12)  winuser.h


GWL_STYLE
GWL_STYLE  (-16)  winuser.h

Retrieves or sets the window styles. See GetWindowLong, SetWindowLong.


FN_GWL_STYLE
GWL_STYLE  (-16)  winuser.h


GWL_USERDATA
GWL_USERDATA  (-21)  winuser.h

Retrieves or sets the long value associated with the window. Each window has a corresponding long value intended for use by the application that created the window. See GetWindowLong, SetWindowLong.


FN_GWL_USERDATA
GWL_USERDATA  (-21)  winuser.h


GWL_WNDPROC
GWL_WNDPROC  (-4)  winuser.h

Retrieves or sets the address of the window procedure. See GetWindowLong, SetWindowLong.


FN_GWL_WNDPROC
GWL_WNDPROC  (-4)  winuser.h


HALFTONE
HALFTONE  4  wingdi.h

Maps pixels from the source into blocks of pixels in the destination. The average color over the destination block of pixels approximates the color of the source pixels. See SetStretchBltMode.


FN_HALFTONE
HALFTONE  4  wingdi.h


HANGUP_COMPLETE
HANGUP_COMPLETE  0x05  nb30.h

The session was deleted due to a command by the local user. See SESSION_BUFFER.


FN_HANGUP_COMPLETE
HANGUP_COMPLETE  0x05  nb30.h


HANGUP_PENDING
HANGUP_PENDING  0x04  nb30.h

The session is being deleted due to a command by the local user. See SESSION_BUFFER.


FN_HANGUP_PENDING
HANGUP_PENDING  0x04  nb30.h


HC_ACTION
HC_ACTION  0  winuser.h

JournalRecordProc: Indicates 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. KeyboardProc: Indicates the wParam and lParam parameters contain information about a keystroke message. MouseProc: Indicates the wParam and lParam parameters contain information about a mouse message.


FN_HC_ACTION
HC_ACTION  0  winuser.h


HC_GETNEXT
HC_GETNEXT  1  winuser.h

Indicates the hook procedure must copy the current mouse or keyboard message to the EVENTMSG structure pointed to by the lParam parameter. See JournalPlaybackProc.


FN_HC_GETNEXT
HC_GETNEXT  1  winuser.h


HC_NOREMOVE
HC_NOREMOVE  3  winuser.h

KeyboardProc: Indicates 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.) MouseProc: Indicates 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.)


FN_HC_NOREMOVE
HC_NOREMOVE  3  winuser.h


HC_SKIP
HC_SKIP  2  winuser.h

Indicates the hook procedure must prepare to copy the next mouse or keyboard message to the EVENTMSG structure pointed to by the lParam parameter. Upon receiving the HC_GETNEXT code, the hook procedure must copy the message to the structure. See JournalPlaybackProc.


FN_HC_SKIP
HC_SKIP  2  winuser.h


HC_SYSMODALOFF
HC_SYSMODALOFF  5  winuser.h

Indicates a system-modal dialog box has been destroyed. The hook procedure must resume playing back the messages. See JournalPlaybackProc, JournalRecordProc.


FN_HC_SYSMODALOFF
HC_SYSMODALOFF  5  winuser.h


HC_SYSMODALON
HC_SYSMODALON  4  winuser.h

Indicates a system-modal dialog box is being displayed. Until the dialog box is destroyed, the hook procedure must stop recording. See JournalPlaybackProc, JournalRecordProc.


FN_HC_SYSMODALON
HC_SYSMODALON  4  winuser.h


HCBT_ACTIVATE
HCBT_ACTIVATE  5  winuser.h

Indicates that the system is about to activate a window. See CBTProc, SetWindowsHook.


FN_HCBT_ACTIVATE
HCBT_ACTIVATE  5  winuser.h


HCBT_CLICKSKIPPED
HCBT_CLICKSKIPPED  6  winuser.h

Indicates 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. See CBTProc, SetWindowsHook.


FN_HCBT_CLICKSKIPPED
HCBT_CLICKSKIPPED  6  winuser.h


HCBT_CREATEWND
HCBT_CREATEWND  3  winuser.h

Indicates 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 nonzero, 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's also possible to change the Z-order of the newly created window by modifying the hwndInsertAfter member of the CBT_CREATEWND structure. HCBT_CREATEWND Indicates that a window is about to be created. The system calls the filter function before sending the WM_CREATE message to the window. If the filter function returns TRUE, the system will destroy the window--the system will not send the WM_DESTROY message to the window. See CBTProc, SetWindowsHook.


FN_HCBT_CREATEWND
HCBT_CREATEWND  3  winuser.h


HCBT_DESTROYWND
HCBT_DESTROYWND  4  winuser.h

Indicates that a window is about to be destroyed. See CBTProc, SetWindowsHook.


FN_HCBT_DESTROYWND
HCBT_DESTROYWND  4  winuser.h


HCBT_KEYSKIPPED
HCBT_KEYSKIPPED  7  winuser.h

Indicates 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 procedure in response to the keyboard message. See CBTProc, SetWindowsHook.


FN_HCBT_KEYSKIPPED
HCBT_KEYSKIPPED  7  winuser.h


HCBT_MINMAX
HCBT_MINMAX  1  winuser.h

Indicates that a window is about to be minimized or maximized. See CBTProc, SetWindowsHook.


FN_HCBT_MINMAX
HCBT_MINMAX  1  winuser.h


HCBT_MOVESIZE
HCBT_MOVESIZE  0  winuser.h

Indicates that a window is about to be moved or sized. See CBTProc, SetWindowsHook.


FN_HCBT_MOVESIZE
HCBT_MOVESIZE  0  winuser.h


HCBT_QS
HCBT_QS  2  winuser.h

Indicates that the system has retrieved a WM_QUEUESYNC message from the system message queue. See CBTProc, SetWindowsHook.


FN_HCBT_QS
HCBT_QS  2  winuser.h


HCBT_SETFOCUS
HCBT_SETFOCUS  9  winuser.h

Indicates a window is about to receive the keyboard focus. See CBTProc.


FN_HCBT_SETFOCUS
HCBT_SETFOCUS  9  winuser.h


HCBT_SYSCOMMAND
HCBT_SYSCOMMAND  8  winuser.h

Indicates that a system command is about to be carried out. This allows a CBT application to prevent task switching by hot keys. See CBTProc, SetWindowsHook.


FN_HCBT_SYSCOMMAND
HCBT_SYSCOMMAND  8  winuser.h


HKEY_CLASSES_ROOT
HKEY_CLASSES_ROOT  ((HKEY)0x80000000)  winreg.h

This is a predefined standard registry handle. Registry entries subordinate to this handle define types (or classes) of documents and the properties associated with these classes. This handle is an alias for HKEY_LOCAL_MACHINE, SoftwareClasses.


FN_HKEY_CLASSES_ROOT
HKEY_CLASSES_ROOT  ((HKEY)0x80000000)  winreg.h


HKEY_CURRENT_USER
HKEY_CURRENT_USER  ((HKEY)0x80000001)  winreg.h

This is a predefined standard registry handle. Registry entries subordinate to this handle contain configuration information specific to the current user. This kind of information was previously stored in the WIN.INI initialization file. This handle is an alias to the profile of the current user, stored under HKEY_USERS.


FN_HKEY_CURRENT_USER
HKEY_CURRENT_USER  ((HKEY)0x80000001)  winreg.h


HKEY_LOCAL_MACHINE
HKEY_LOCAL_MACHINE  ((HKEY)0x80000002)  winreg.h

This is a predefined standard registry handle. Registry entries subordinate to this handle define the configuration state of the system, including information about the bus type, system memory, and installed hardware and software.


FN_HKEY_LOCAL_MACHINE
HKEY_LOCAL_MACHINE  ((HKEY)0x80000002)  winreg.h


HKEY_PERFORMANCE_DATA
HKEY_PERFORMANCE_DATA  ((HKEY)0x80000004)  winreg.h

This is a predefined registry handle that provides access to system performance information.


FN_HKEY_PERFORMANCE_DATA
HKEY_PERFORMANCE_DATA  ((HKEY)0x80000004)  winreg.h


HKEY_USERS
HKEY_USERS  ((HKEY)0x80000003)  winreg.h

This is a predefined standard registry handle. Registry entries subordinate to this handle define the default user configuration for users on the local computer and the user configuration for the current user. User profiles appear as subtrees under this handle; the HKEY_CURRENT_USER handle is an alias to the profile of the current user.


FN_HKEY_USERS
HKEY_USERS  ((HKEY)0x80000003)  winreg.h


HOLLOW_BRUSH
HOLLOW_BRUSH  NULL_BRUSH  wingdi.h

Hollow brush (Equivalent to NULL_BRUSH) See GetStockObject.


FN_HOLLOW_BRUSH
HOLLOW_BRUSH  NULL_BRUSH  wingdi.h


HORZRES
HORZRES  8  wingdi.h

Width of the display, in pixels. See GetDeviceCaps.


FN_HORZRES
HORZRES  8  wingdi.h


HORZSIZE
HORZSIZE  4  wingdi.h

Width of the physical display, in millimeters. See GetDeviceCaps.


FN_HORZSIZE
HORZSIZE  4  wingdi.h


HS_BDIAGONAL
HS_BDIAGONAL  3  wingdi.h

45-degree upward hatch (left to right) See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.


FN_HS_BDIAGONAL
HS_BDIAGONAL  3  wingdi.h


HS_CROSS
HS_CROSS  4  wingdi.h

Horizontal and vertical cross-hatch See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.


FN_HS_CROSS
HS_CROSS  4  wingdi.h


HS_DIAGCROSS
HS_DIAGCROSS  5  wingdi.h

45-degree crosshatch See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.


FN_HS_DIAGCROSS
HS_DIAGCROSS  5  wingdi.h


HS_FDIAGONAL
HS_FDIAGONAL  2  wingdi.h

45-degree upward hatch (left to right) See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.


FN_HS_FDIAGONAL
HS_FDIAGONAL  2  wingdi.h


HS_HORIZONTAL
HS_HORIZONTAL  0  wingdi.h

Horizontal hatch See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.


FN_HS_HORIZONTAL
HS_HORIZONTAL  0  wingdi.h


HS_VERTICAL
HS_VERTICAL  1  wingdi.h

Vertical hatch See CreateHatchBrush, EXTLOGPEN, LOGBRUSH.


FN_HS_VERTICAL
HS_VERTICAL  1  wingdi.h


HSHELL_WINDOWCREATED
HSHELL_WINDOWCREATED  1  winuser.h

Indicates a top-level, unowned window has been created. The window exists when the system calls a ShellProc function. See ShellProc.


FN_HSHELL_WINDOWCREATED
HSHELL_WINDOWCREATED  1  winuser.h


HSHELL_WINDOWDESTROYED
HSHELL_WINDOWDESTROYED  2  winuser.h

Indicates a top-level, unowned window is about to be destroyed. The window still exists when the system calls a ShellProc function. See ShellProc.


FN_HSHELL_WINDOWDESTROYED
HSHELL_WINDOWDESTROYED  2  winuser.h


HTBORDER
HTBORDER  18  winuser.h

In the border of a window that does not have a sizing border See WM_NCHITTEST.


FN_HTBORDER
HTBORDER  18  winuser.h


HTBOTTOM
HTBOTTOM  15  winuser.h

In the lower horizontal border of a window See WM_NCHITTEST.


FN_HTBOTTOM
HTBOTTOM  15  winuser.h


HTBOTTOMLEFT
HTBOTTOMLEFT  16  winuser.h

In the lower-left corner of a window border See WM_NCHITTEST.


FN_HTBOTTOMLEFT
HTBOTTOMLEFT  16  winuser.h


HTBOTTOMRIGHT
HTBOTTOMRIGHT  17  winuser.h

In the lower-right corner of a window border See WM_NCHITTEST.


FN_HTBOTTOMRIGHT
HTBOTTOMRIGHT  17  winuser.h


HTCAPTION
HTCAPTION  2  winuser.h

In a title bar area See WM_NCHITTEST.


FN_HTCAPTION
HTCAPTION  2  winuser.h


HTCLIENT
HTCLIENT  1  winuser.h

In a client area See WM_NCHITTEST.


FN_HTCLIENT
HTCLIENT  1  winuser.h


HTERROR
HTERROR  (-2)  winuser.h

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) See WM_NCHITTEST.


FN_HTERROR
HTERROR  (-2)  winuser.h


HTGROWBOX
HTGROWBOX  4  winuser.h

In a size box (same as HTSIZE) See WM_NCHITTEST.


FN_HTGROWBOX
HTGROWBOX  4  winuser.h


HTHSCROLL
HTHSCROLL  6  winuser.h

In a horizontal scroll bar See WM_NCHITTEST.


FN_HTHSCROLL
HTHSCROLL  6  winuser.h


HTLEFT
HTLEFT  10  winuser.h

In the left border of a window See WM_NCHITTEST.


FN_HTLEFT
HTLEFT  10  winuser.h


HTMENU
HTMENU  5  winuser.h

In a menu area See WM_NCHITTEST.


FN_HTMENU
HTMENU  5  winuser.h


HTNOWHERE
HTNOWHERE  0  winuser.h

On the screen background or on a dividing line between windows See WM_NCHITTEST.


FN_HTNOWHERE
HTNOWHERE  0  winuser.h


HTREDUCE
HTREDUCE  HTMINBUTTON  winuser.h

In a Minimize button See WM_NCHITTEST.


FN_HTREDUCE
HTREDUCE  HTMINBUTTON  winuser.h


HTRIGHT
HTRIGHT  11  winuser.h

In the right border of a window See WM_NCHITTEST.


FN_HTRIGHT
HTRIGHT  11  winuser.h


HTSIZE
HTSIZE  HTGROWBOX  winuser.h

In a size box (same as HTGROWBOX) See WM_NCHITTEST.


FN_HTSIZE
HTSIZE  HTGROWBOX  winuser.h


HTSYSMENU
HTSYSMENU  3  winuser.h

In a System menu or in a Close button in a child window See WM_NCHITTEST.


FN_HTSYSMENU
HTSYSMENU  3  winuser.h


HTTOP
HTTOP  12  winuser.h

In the upper horizontal border of a window See WM_NCHITTEST.


FN_HTTOP
HTTOP  12  winuser.h


HTTOPLEFT
HTTOPLEFT  13  winuser.h

In the upper-left corner of a window border See WM_NCHITTEST.


FN_HTTOPLEFT
HTTOPLEFT  13  winuser.h


HTTOPRIGHT
HTTOPRIGHT  14  winuser.h

In the upper-right corner of a window border See WM_NCHITTEST.


FN_HTTOPRIGHT
HTTOPRIGHT  14  winuser.h


HTTRANSPARENT
HTTRANSPARENT  (-1)  winuser.h

In a window currently covered by another window See WM_NCHITTEST.


FN_HTTRANSPARENT
HTTRANSPARENT  (-1)  winuser.h


HTVSCROLL
HTVSCROLL  7  winuser.h

In the vertical scroll bar See WM_NCHITTEST.


FN_HTVSCROLL
HTVSCROLL  7  winuser.h


HTZOOM
HTZOOM  HTMAXBUTTON  winuser.h

In a Maximize button See WM_NCHITTEST.


FN_HTZOOM
HTZOOM  HTMAXBUTTON  winuser.h


HWND_BOTTOM
HWND_BOTTOM  ((HWND)1)   winuser.h

Places the window at the bottom of the Z order. If hwnd identifies a topmost window, the window loses its topmost status; the system places the window at the bottom of all other windows. See SetWindowPos.


FN_HWND_BOTTOM
HWND_BOTTOM  ((HWND)1)   winuser.h


HWND_NOTOPMOST
HWND_NOTOPMOST  ((HWND)-2)  winuser.h

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. See SetWindowPos.


FN_HWND_NOTOPMOST
HWND_NOTOPMOST  ((HWND)-2)  winuser.h


HWND_TOP
HWND_TOP  ((HWND)0)   winuser.h

Places the window at the top of the Z order. See SetWindowPos.


FN_HWND_TOP
HWND_TOP  ((HWND)0)   winuser.h


HWND_TOPMOST
HWND_TOPMOST  ((HWND)-1)  winuser.h

Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated. See SetWindowPos.


FN_HWND_TOPMOST
HWND_TOPMOST  ((HWND)-1)  winuser.h


IDABORT
IDABORT  3  winuser.h

Abort button was selected. See MessageBox.


FN_IDABORT
IDABORT  3  winuser.h


IDC_APPSTARTING
IDC_APPSTARTING  MAKEINTRESOURCE(32650)  winuser.h

Standard arrow and small hourglass See LoadCursor.


FN_IDC_APPSTARTING
IDC_APPSTARTING  MAKEINTRESOURCE(32650)  winuser.h


IDC_ARROW
IDC_ARROW  MAKEINTRESOURCE(32512)  winuser.h

Standard arrow See LoadCursor.


FN_IDC_ARROW
IDC_ARROW  MAKEINTRESOURCE(32512)  winuser.h


IDC_CROSS
IDC_CROSS  MAKEINTRESOURCE(32515)  winuser.h

Crosshair See LoadCursor.


FN_IDC_CROSS
IDC_CROSS  MAKEINTRESOURCE(32515)  winuser.h


IDC_IBEAM
IDC_IBEAM  MAKEINTRESOURCE(32513)  winuser.h

Text I-beam See LoadCursor.


FN_IDC_IBEAM
IDC_IBEAM  MAKEINTRESOURCE(32513)  winuser.h


IDC_ICON
IDC_ICON  MAKEINTRESOURCE(32641)  winuser.h

Empty icon See LoadCursor.


FN_IDC_ICON
IDC_ICON  MAKEINTRESOURCE(32641)  winuser.h


IDC_NO
IDC_NO  MAKEINTRESOURCE(32648)  winuser.h

Slashed circle See LoadCursor.


FN_IDC_NO
IDC_NO  MAKEINTRESOURCE(32648)  winuser.h


IDC_SIZE
IDC_SIZE  MAKEINTRESOURCE(32640)  winuser.h

Four-pointed arrow See LoadCursor.


FN_IDC_SIZE
IDC_SIZE  MAKEINTRESOURCE(32640)  winuser.h


IDC_SIZEALL
IDC_SIZEALL  MAKEINTRESOURCE(32646)  winuser.h

Same as IDC_SIZE See LoadCursor.


FN_IDC_SIZEALL
IDC_SIZEALL  MAKEINTRESOURCE(32646)  winuser.h


IDC_SIZENESW
IDC_SIZENESW  MAKEINTRESOURCE(32643)  winuser.h

Double-pointed arrow pointing northeast and southwest See LoadCursor.


FN_IDC_SIZENESW
IDC_SIZENESW  MAKEINTRESOURCE(32643)  winuser.h


IDC_SIZENS
IDC_SIZENS  MAKEINTRESOURCE(32645)  winuser.h

Double-pointed arrow pointing north and south See LoadCursor.


FN_IDC_SIZENS
IDC_SIZENS  MAKEINTRESOURCE(32645)  winuser.h


IDC_SIZENWSE
IDC_SIZENWSE  MAKEINTRESOURCE(32642)  winuser.h

Double-pointed arrow pointing northwest and southeast See LoadCursor.


FN_IDC_SIZENWSE
IDC_SIZENWSE  MAKEINTRESOURCE(32642)  winuser.h


IDC_SIZEWE
IDC_SIZEWE  MAKEINTRESOURCE(32644)  winuser.h

Double-pointed arrow pointing west and east See LoadCursor.


FN_IDC_SIZEWE
IDC_SIZEWE  MAKEINTRESOURCE(32644)  winuser.h


IDC_UPARROW
IDC_UPARROW  MAKEINTRESOURCE(32516)  winuser.h

Vertical arrow See LoadCursor.


FN_IDC_UPARROW
IDC_UPARROW  MAKEINTRESOURCE(32516)  winuser.h


IDC_WAIT
IDC_WAIT  MAKEINTRESOURCE(32514)  winuser.h

Hourglass See LoadCursor.


FN_IDC_WAIT
IDC_WAIT  MAKEINTRESOURCE(32514)  winuser.h


IDCANCEL
IDCANCEL  2  winuser.h

No file was undeleted. See UndeleteFile.


FN_IDCANCEL
IDCANCEL  2  winuser.h


IDCANCEL
IDCANCEL  2  winuser.h

Cancel button was selected. See MessageBox.


FN_IDCANCEL
IDCANCEL  2  winuser.h


IDHOT_SNAPDESKTOP
IDHOT_SNAPDESKTOP  (-2)  winuser.h

The 'snap desktop' hot key was pressed. See WM_HOTKEY.


FN_IDHOT_SNAPDESKTOP
IDHOT_SNAPDESKTOP  (-2)  winuser.h


IDHOT_SNAPWINDOW
IDHOT_SNAPWINDOW  (-1)  winuser.h

The 'snap window' hot key was pressed. See WM_HOTKEY.


FN_IDHOT_SNAPWINDOW
IDHOT_SNAPWINDOW  (-1)  winuser.h


IDI_APPLICATION
IDI_APPLICATION  MAKEINTRESOURCE(32512)  winuser.h

Default application icon. See LoadIcon.


FN_IDI_APPLICATION
IDI_APPLICATION  MAKEINTRESOURCE(32512)  winuser.h


IDI_ASTERISK
IDI_ASTERISK  MAKEINTRESOURCE(32516)  winuser.h

Asterisk (used in informative messages). See LoadIcon.


FN_IDI_ASTERISK
IDI_ASTERISK  MAKEINTRESOURCE(32516)  winuser.h


IDI_EXCLAMATION
IDI_EXCLAMATION  MAKEINTRESOURCE(32515)  winuser.h

Exclamation point (used in warning messages). See LoadIcon.


FN_IDI_EXCLAMATION
IDI_EXCLAMATION  MAKEINTRESOURCE(32515)  winuser.h


IDI_HAND
IDI_HAND  MAKEINTRESOURCE(32513)  winuser.h

Hand-shaped icon (used in serious warning messages). See LoadIcon.


FN_IDI_HAND
IDI_HAND  MAKEINTRESOURCE(32513)  winuser.h


IDI_QUESTION
IDI_QUESTION  MAKEINTRESOURCE(32514)  winuser.h

Question mark (used in prompting messages). See LoadIcon.


FN_IDI_QUESTION
IDI_QUESTION  MAKEINTRESOURCE(32514)  winuser.h


IDIGNORE
IDIGNORE  5  winuser.h

Ignore button was selected. See MessageBox.


FN_IDIGNORE
IDIGNORE  5  winuser.h


IDNO
IDNO  7  winuser.h

No button was selected. See MessageBox.


FN_IDNO
IDNO  7  winuser.h


IDOK
IDOK  1  winuser.h

UndeleteFile: A file was undeleted. File Manager will repaint its windows. MessageBox: OK button was selected.


FN_IDOK
IDOK  1  winuser.h


IDRETRY
IDRETRY  4  winuser.h

Retry button was selected. See MessageBox.


FN_IDRETRY
IDRETRY  4  winuser.h


IDYES
IDYES  6  winuser.h

Yes button was selected. See MessageBox.


FN_IDYES
IDYES  6  winuser.h


INHERIT_ONLY_ACE
INHERIT_ONLY_ACE  (0x8)  winnt.h

The ACE does not apply to the containing object, but is applied to subobjects. See ACE_HEADER.


FN_INHERIT_ONLY_ACE
INHERIT_ONLY_ACE  (0x8)  winnt.h


JOB_CONTROL_CANCEL
JOB_CONTROL_CANCEL  3  winspool.h

Delete the print job. See SetJob.


FN_JOB_CONTROL_CANCEL
JOB_CONTROL_CANCEL  3  winspool.h


JOB_CONTROL_PAUSE
JOB_CONTROL_PAUSE  1  winspool.h

Pause the print job. See SetJob.


FN_JOB_CONTROL_PAUSE
JOB_CONTROL_PAUSE  1  winspool.h


JOB_CONTROL_RESTART
JOB_CONTROL_RESTART  4  winspool.h

Restart a print job. A job can only be restarted if it was printing. See SetJob.


FN_JOB_CONTROL_RESTART
JOB_CONTROL_RESTART  4  winspool.h


JOB_CONTROL_RESUME
JOB_CONTROL_RESUME  2  winspool.h

Resume a paused print job. See SetJob.


FN_JOB_CONTROL_RESUME
JOB_CONTROL_RESUME  2  winspool.h


JOY_BUTTON1
JOY_BUTTON1  0x0001  mmsystem.h

Set if first joystick button is pressed. See MM_JOY1MOVE, MM_JOY1ZMOVE, MM_JOY2MOVE, MM_JOY2ZMOVE, JOYINFO.


FN_JOY_BUTTON1
JOY_BUTTON1  0x0001  mmsystem.h


JOY_BUTTON1CHG
JOY_BUTTON1CHG  0x0100  mmsystem.h

Set if first joystick button has changed. See MM_JOY1BUTTONDOWN, MM_JOY1BUTTONUP, MM_JOY2BUTTONDOWN, MM_JOY2BUTTONUP.


FN_JOY_BUTTON1CHG
JOY_BUTTON1CHG  0x0100  mmsystem.h


JOY_BUTTON2
JOY_BUTTON2  0x0002  mmsystem.h

Set if second joystick button is pressed. See MM_JOY1MOVE, MM_JOY1ZMOVE, MM_JOY2MOVE, MM_JOY2ZMOVE, JOYINFO.


FN_JOY_BUTTON2
JOY_BUTTON2  0x0002  mmsystem.h


JOY_BUTTON2CHG
JOY_BUTTON2CHG  0x0200  mmsystem.h

Set if second joystick button has changed. See MM_JOY1BUTTONDOWN, MM_JOY1BUTTONUP, MM_JOY2BUTTONDOWN, MM_JOY2BUTTONUP.


FN_JOY_BUTTON2CHG
JOY_BUTTON2CHG  0x0200  mmsystem.h


JOY_BUTTON3
JOY_BUTTON3  0x0004  mmsystem.h

Set if third joystick button is pressed. See MM_JOY1MOVE, MM_JOY1ZMOVE, MM_JOY2MOVE, MM_JOY2ZMOVE, JOYINFO.


FN_JOY_BUTTON3
JOY_BUTTON3  0x0004  mmsystem.h


JOY_BUTTON3CHG
JOY_BUTTON3CHG  0x0400  mmsystem.h

Set if third joystick button has changed. See MM_JOY1BUTTONDOWN, MM_JOY1BUTTONUP, MM_JOY2BUTTONDOWN, MM_JOY2BUTTONUP.


FN_JOY_BUTTON3CHG
JOY_BUTTON3CHG  0x0400  mmsystem.h


JOY_BUTTON4
JOY_BUTTON4  0x0008  mmsystem.h

Set if fourth joystick button is pressed. See MM_JOY1MOVE, MM_JOY1ZMOVE, MM_JOY2MOVE, MM_JOY2ZMOVE, JOYINFO.


FN_JOY_BUTTON4
JOY_BUTTON4  0x0008  mmsystem.h


JOY_BUTTON4CHG
JOY_BUTTON4CHG  0x0800  mmsystem.h

Set if fourth joystick button has changed. See MM_JOY1BUTTONDOWN, MM_JOY1BUTTONUP, MM_JOY2BUTTONDOWN, MM_JOY2BUTTONUP.


FN_JOY_BUTTON4CHG
JOY_BUTTON4CHG  0x0800  mmsystem.h


JOYERR_NOCANDO
JOYERR_NOCANDO  (JOYERR_BASE+6)  mmsystem.h

Cannot capture joystick input because some required service (for example, a Windows timer) is unavailable. See joySetCapture.


FN_JOYERR_NOCANDO
JOYERR_NOCANDO  (JOYERR_BASE+6)  mmsystem.h


JOYERR_PARMS
JOYERR_PARMS  (JOYERR_BASE+5)  mmsystem.h

The specified joystick device ID IDDevice is invalid. See joyGetDevCaps, joyGetPos, joyGetThreshold, joyReleaseCapture, joySetCapture,  joySetThreshold.


FN_JOYERR_PARMS
JOYERR_PARMS  (JOYERR_BASE+5)  mmsystem.h


JOYERR_UNPLUGGED
JOYERR_UNPLUGGED  (JOYERR_BASE+7)  mmsystem.h

The specified joystick is not connected to the system. See joyGetPos, joySetCapture.


FN_JOYERR_UNPLUGGED
JOYERR_UNPLUGGED  (JOYERR_BASE+7)  mmsystem.h


KEY_ALL_ACCESS
KEY_ALL_ACCESS  ((STANDARD_RIGHTS_ALL | KEY_QUERY_VALUE | KEY_SET_VALUE | KEY_CREATE_SUB_KEY | KEY_ENUMERATE_SUB_KEYS | KEY_NOTIFY | KEY_CREATE_LINK) & (~SYNCHRONIZE))  winnt.h

Combines query value, enumerate subkey, notify, create subkey and set value access. See RegCreateKeyEx.


FN_KEY_ALL_ACCESS
KEY_ALL_ACCESS  ((STANDARD_RIGHTS_ALL | KEY_QUERY_VALUE | KEY_SET_VALUE | KEY_CREATE_SUB_KEY | KEY_ENUMERATE_SUB_KEYS | KEY_NOTIFY | KEY_CREATE_LINK) & (~SYNCHRONIZE))  winnt.h


KEY_CREATE_SUB_KEY
KEY_CREATE_SUB_KEY  (0x0004)  winnt.h

Permission to create subkeys. See RegCreateKeyEx.


FN_KEY_CREATE_SUB_KEY
KEY_CREATE_SUB_KEY  (0x0004)  winnt.h


KEY_ENUMERATE_SUB_KEYS
KEY_ENUMERATE_SUB_KEYS  (0x0008)  winnt.h

Permission to enumerate subkeys. See RegCreateKeyEx.


FN_KEY_ENUMERATE_SUB_KEYS
KEY_ENUMERATE_SUB_KEYS  (0x0008)  winnt.h


KEY_EXECUTE
KEY_EXECUTE  ((KEY_READ) & (~SYNCHRONIZE))  winnt.h

Read access. See RegCreateKeyEx.


FN_KEY_EXECUTE
KEY_EXECUTE  ((KEY_READ) & (~SYNCHRONIZE))  winnt.h


KEY_NOTIFY
KEY_NOTIFY  (0x0010)  winnt.h

Change notification will occur. See RegCreateKeyEx.


FN_KEY_NOTIFY
KEY_NOTIFY  (0x0010)  winnt.h


KEY_QUERY_VALUE
KEY_QUERY_VALUE  (0x0001)  winnt.h

Permission to query subkey data. See RegCreateKeyEx.


FN_KEY_QUERY_VALUE
KEY_QUERY_VALUE  (0x0001)  winnt.h


KEY_READ
KEY_READ  ((STANDARD_RIGHTS_READ | KEY_QUERY_VALUE | KEY_ENUMERATE_SUB_KEYS | KEY_NOTIFY) & (~SYNCHRONIZE))   winnt.h

Combines query value, enumerate subkey, and notify access. See RegCreateKeyEx.


FN_KEY_READ
KEY_READ  ((STANDARD_RIGHTS_READ | KEY_QUERY_VALUE | KEY_ENUMERATE_SUB_KEYS | KEY_NOTIFY) & (~SYNCHRONIZE))   winnt.h


KEY_SET_VALUE
KEY_SET_VALUE  (0x0002)  winnt.h

Permission to set subkey data. See RegCreateKeyEx.


FN_KEY_SET_VALUE
KEY_SET_VALUE  (0x0002)  winnt.h


KEY_WRITE
KEY_WRITE  ((STANDARD_RIGHTS_WRITE | KEY_SET_VALUE | KEY_CREATE_SUB_KEY) & (~SYNCHRONIZE))   winnt.h

Combines set value and create subkey access. See RegCreateKeyEx.


FN_KEY_WRITE
KEY_WRITE  ((STANDARD_RIGHTS_WRITE | KEY_SET_VALUE | KEY_CREATE_SUB_KEY) & (~SYNCHRONIZE))   winnt.h


KEYEVENTF_EXTENDEDKEY
KEYEVENTF_EXTENDEDKEY  0x0001  winuser.h

Indicates that a scan code was preceded by a prefix byte having the value 0xE0. See keybd_event.


FN_KEYEVENTF_EXTENDEDKEY
KEYEVENTF_EXTENDEDKEY  0x0001  winuser.h


KEYEVENTF_KEYUP
KEYEVENTF_KEYUP  0x0002  winuser.h

Indicates that a key is being released. If not specified, indicates that a key is being depressed. See keybd_event.


FN_KEYEVENTF_KEYUP
KEYEVENTF_KEYUP  0x0002  winuser.h


LANG_ALBANIAN
LANG_ALBANIAN  0x1c  winnt.h

See MAKELANGID.


FN_LANG_ALBANIAN
LANG_ALBANIAN  0x1c  winnt.h


LANG_ARABIC
LANG_ARABIC  0x01  winnt.h

See MAKELANGID.


FN_LANG_ARABIC
LANG_ARABIC  0x01  winnt.h


LANG_BAHASA
LANG_BAHASA  0x21  winnt.h

See MAKELANGID.


FN_LANG_BAHASA
LANG_BAHASA  0x21  winnt.h


LANG_BULGARIAN
LANG_BULGARIAN  0x02  winnt.h

See MAKELANGID.


FN_LANG_BULGARIAN
LANG_BULGARIAN  0x02  winnt.h


LANG_CATALAN
LANG_CATALAN  0x03  winnt.h

See MAKELANGID.


FN_LANG_CATALAN
LANG_CATALAN  0x03  winnt.h


LANG_CHINESE
LANG_CHINESE  0x04  winnt.h

See MAKELANGID.


FN_LANG_CHINESE
LANG_CHINESE  0x04  winnt.h


LANG_CZECH
LANG_CZECH  0x05  winnt.h

See MAKELANGID.


FN_LANG_CZECH
LANG_CZECH  0x05  winnt.h


LANG_DANISH
LANG_DANISH  0x06  winnt.h

See MAKELANGID.


FN_LANG_DANISH
LANG_DANISH  0x06  winnt.h


LANG_DUTCH
LANG_DUTCH  0x13  winnt.h

See MAKELANGID.


FN_LANG_DUTCH
LANG_DUTCH  0x13  winnt.h


LANG_ENGLISH
LANG_ENGLISH  0x09  winnt.h

See MAKELANGID.


FN_LANG_ENGLISH
LANG_ENGLISH  0x09  winnt.h


LANG_FINNISH
LANG_FINNISH  0x0b  winnt.h

See MAKELANGID.


FN_LANG_FINNISH
LANG_FINNISH  0x0b  winnt.h


LANG_FRENCH
LANG_FRENCH  0x0c  winnt.h

See MAKELANGID.


FN_LANG_FRENCH
LANG_FRENCH  0x0c  winnt.h


LANG_GERMAN
LANG_GERMAN  0x07  winnt.h

See MAKELANGID.


FN_LANG_GERMAN
LANG_GERMAN  0x07  winnt.h


LANG_GREEK
LANG_GREEK  0x08  winnt.h

See MAKELANGID.


FN_LANG_GREEK
LANG_GREEK  0x08  winnt.h


LANG_HEBREW
LANG_HEBREW  0x0d  winnt.h

See MAKELANGID.


FN_LANG_HEBREW
LANG_HEBREW  0x0d  winnt.h


LANG_HUNGARIAN
LANG_HUNGARIAN  0x0e  winnt.h

See MAKELANGID.


FN_LANG_HUNGARIAN
LANG_HUNGARIAN  0x0e  winnt.h


LANG_ICELANDIC
LANG_ICELANDIC  0x0f  winnt.h

See MAKELANGID.


FN_LANG_ICELANDIC
LANG_ICELANDIC  0x0f  winnt.h


LANG_ITALIAN
LANG_ITALIAN  0x10  winnt.h

See MAKELANGID.


FN_LANG_ITALIAN
LANG_ITALIAN  0x10  winnt.h


LANG_JAPANESE
LANG_JAPANESE  0x11  winnt.h

See MAKELANGID.


FN_LANG_JAPANESE
LANG_JAPANESE  0x11  winnt.h


LANG_KOREAN
LANG_KOREAN  0x12  winnt.h

See MAKELANGID.


FN_LANG_KOREAN
LANG_KOREAN  0x12  winnt.h


LANG_NEUTRAL
LANG_NEUTRAL  0x00  winnt.h

See MAKELANGID.


FN_LANG_NEUTRAL
LANG_NEUTRAL  0x00  winnt.h


LANG_NORWEGIAN
LANG_NORWEGIAN  0x14  winnt.h

See MAKELANGID.


FN_LANG_NORWEGIAN
LANG_NORWEGIAN  0x14  winnt.h


LANG_POLISH
LANG_POLISH  0x15  winnt.h

See MAKELANGID.


FN_LANG_POLISH
LANG_POLISH  0x15  winnt.h


LANG_PORTUGUESE
LANG_PORTUGUESE  0x16  winnt.h

See MAKELANGID.


FN_LANG_PORTUGUESE
LANG_PORTUGUESE  0x16  winnt.h


LANG_RHAETO_ROMAN
LANG_RHAETO_ROMAN  0x17  winnt.h

See MAKELANGID.


FN_LANG_RHAETO_ROMAN
LANG_RHAETO_ROMAN  0x17  winnt.h


LANG_ROMANIAN
LANG_ROMANIAN  0x18  winnt.h

See MAKELANGID.


FN_LANG_ROMANIAN
LANG_ROMANIAN  0x18  winnt.h


LANG_RUSSIAN
LANG_RUSSIAN  0x19  winnt.h

See MAKELANGID.


FN_LANG_RUSSIAN
LANG_RUSSIAN  0x19  winnt.h


LANG_SERBO_CROATIAN
LANG_SERBO_CROATIAN  0x1a  winnt.h

See MAKELANGID.


FN_LANG_SERBO_CROATIAN
LANG_SERBO_CROATIAN  0x1a  winnt.h


LANG_SLOVAK
LANG_SLOVAK  0x1b  winnt.h

See MAKELANGID.


FN_LANG_SLOVAK
LANG_SLOVAK  0x1b  winnt.h


LANG_SPANISH
LANG_SPANISH  0x0a  winnt.h

See MAKELANGID.


FN_LANG_SPANISH
LANG_SPANISH  0x0a  winnt.h


LANG_SWEDISH
LANG_SWEDISH  0x1d  winnt.h

See MAKELANGID.


FN_LANG_SWEDISH
LANG_SWEDISH  0x1d  winnt.h


LANG_THAI
LANG_THAI  0x1e  winnt.h

See MAKELANGID.


FN_LANG_THAI
LANG_THAI  0x1e  winnt.h


LANG_TURKISH
LANG_TURKISH  0x1f  winnt.h

See MAKELANGID.


FN_LANG_TURKISH
LANG_TURKISH  0x1f  winnt.h


LANG_URDU
LANG_URDU  0x20  winnt.h

See MAKELANGID.


FN_LANG_URDU
LANG_URDU  0x20  winnt.h


LB_OKAY
LB_OKAY  0  winuser.h

Listbox message return value: everything is okay.


FN_LB_OKAY
LB_OKAY  0  winuser.h


LB_ERR
LB_ERR  (-1)  winuser.h

Listbox message return value: an error has occurred. See LB_SETCOUNT, LB_SETCURSEL, LB_ADDFILE, LB_ADDSTRING, LB_DELETESTRING, LB_DIR, LB_FINDSTRING, LB_FINDSTRINGEXACT, LB_GETCOUNT, LB_GETCURSEL, LB_INSERTSTRING, LB_SELECTSTRING, LB_SELITEMRANGE, LB_SETCARETINDEX, LB_SETSEL


FN_LB_ERR
LB_ERR  (-1)  winuser.h


LB_ERRSPACE
LB_ERRSPACE  (-2)  winuser.h

Listbox message return value: insufficient space to store the new string. See LB_ADDSTRING, LB_DIR, LB_INSERTSTRING, LB_SETCOUNT, WM_SETTEXT


FN_LB_ERRSPACE
LB_ERRSPACE  (-2)  winuser.h


LCMAP_BYTEREV
LCMAP_BYTEREV  0x00000800  winnls.h

Byte reversal. See LCMapStringW.


FN_LCMAP_BYTEREV
LCMAP_BYTEREV  0x00000800  winnls.h


LCMAP_LOWERCASE
LCMAP_LOWERCASE  0x00000100  winnls.h

Lowercase. This option cannot be used with LCMAP_UPPERCASE. See LCMapStringW.


FN_LCMAP_LOWERCASE
LCMAP_LOWERCASE  0x00000100  winnls.h


LCMAP_SORTKEY
LCMAP_SORTKEY  0x00000400  winnls.h

Wide character sort key (normalize). See LCMapStringW.


FN_LCMAP_SORTKEY
LCMAP_SORTKEY  0x00000400  winnls.h


LCMAP_UPPERCASE
LCMAP_UPPERCASE  0x00000200  winnls.h

Uppercase. This option cannot be used with LCMAP_LOWERCASE. See LCMapStringW.


FN_LCMAP_UPPERCASE
LCMAP_UPPERCASE  0x00000200  winnls.h


LEFT_ALT_PRESSED
LEFT_ALT_PRESSED  0x0002  wincon.h

The left-hand ALT key is pressed. See KEY_EVENT_RECORD.


FN_LEFT_ALT_PRESSED
LEFT_ALT_PRESSED  0x0002  wincon.h


LEFT_CTRL_PRESSED
LEFT_CTRL_PRESSED  0x0008  wincon.h

The left-hand CTRL key is pressed. See KEY_EVENT_RECORD.


FN_LEFT_CTRL_PRESSED
LEFT_CTRL_PRESSED  0x0008  wincon.h


LINECAPS
LINECAPS  30  wingdi.h

A bitmask that indicates the line capabilities of the device. The bits have the following meanings: See GetDeviceCaps.


FN_LINECAPS
LINECAPS  30  wingdi.h


LISTBOX

Designates a list of character strings. Use 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. See CreateWindow.


LISTEN_OUTSTANDING
LISTEN_OUTSTANDING  0x01  nb30.h

The session is waiting for a call from a remote computer. See SESSION_BUFFER.


FN_LISTEN_OUTSTANDING
LISTEN_OUTSTANDING  0x01  nb30.h


LOAD_DLL_DEBUG_EVENT
LOAD_DLL_DEBUG_EVENT  6  winbase.h

Reports a load DLL debugging event. The value of u.LoadDll specifies a LOAD_DLL_DEBUG_INFO structure. See DEBUG_EVENT.


FN_LOAD_DLL_DEBUG_EVENT
LOAD_DLL_DEBUG_EVENT  6  winbase.h


LOCALE_STIME
LOCALE_STIME  0x0000001E  winnls.h

Character(s) for the time separator. See Locale Identifiers.


FN_LOCALE_STIME
LOCALE_STIME  0x0000001E  winnls.h


LOCALE_STIMEFORMAT
LOCALE_STIMEFORMAT  0x00001003  winnls.h

Time formatting strings for this locale. See Locale Identifiers.


FN_LOCALE_STIMEFORMAT
LOCALE_STIMEFORMAT  0x00001003  winnls.h


LOGPIXELSX
LOGPIXELSX  88  wingdi.h

Number of pixels per logical inch along the display width. See GetDeviceCaps.


FN_LOGPIXELSX
LOGPIXELSX  88  wingdi.h


LOGPIXELSY
LOGPIXELSY  90  wingdi.h

Number of pixels per logical inch along the display height. See GetDeviceCaps.


FN_LOGPIXELSY
LOGPIXELSY  90  wingdi.h


LTGRAY_BRUSH
LTGRAY_BRUSH  1  wingdi.h

Light gray brush See GetStockObject.


FN_LTGRAY_BRUSH
LTGRAY_BRUSH  1  wingdi.h


LZERROR_BADINHANDLE
LZERROR_BADINHANDLE  (-1)    lzexpand.h

The handle identifying the source file was not valid. See CopyLZFile, LZCopy, LZInit, LZRead, LZSeek.


FN_LZERROR_BADINHANDLE
LZERROR_BADINHANDLE  (-1)    lzexpand.h


LZERROR_BADOUTHANDLE

The handle identifying the destination file was not valid. See CopyLZFile, LZCopy, LZInit, LZRead.


LZERROR_BADVALUE

One of the input parameters was not valid. See CopyLZFile, LZCopy, LZInit, LZRead, LZSeek.


LZERROR_GLOBALLOC

There is insufficient memory for the required buffers. See CopyLZFile, LZCopy, LZInit, LZRead.


LZERROR_GLOBLOCK

A global handle was not valid. See CopyLZFile, LZCopy, LZInit, LZRead, LZSeek.


LZERROR_READ

The source file format was not valid. See CopyLZFile, LZCopy, LZInit, LZRead.


LZERROR_UNKNOWNALG

The file was compressed with an unrecognized compression algorithm. See CopyLZFile, LZCopy, LZInit, LZRead.


LZERROR_WRITE

There is insufficient space for the output file. See CopyLZFile, LZCopy, LZInit, LZRead.


MA_ACTIVATE
MA_ACTIVATE  1  winuser.h

Activate the window, and do not discard the mouse message. See WM_MOUSEACTIVATE.


FN_MA_ACTIVATE
MA_ACTIVATE  1  winuser.h


MA_ACTIVATEANDEAT
MA_ACTIVATEANDEAT  2  winuser.h

Activate the window, and discard the mouse message. See WM_MOUSEACTIVATE.


FN_MA_ACTIVATEANDEAT
MA_ACTIVATEANDEAT  2  winuser.h


MA_NOACTIVATE
MA_NOACTIVATE  3  winuser.h

Do not activate the window, and do not discard the mouse message. See WM_MOUSEACTIVATE.


FN_MA_NOACTIVATE
MA_NOACTIVATE  3  winuser.h


MA_NOACTIVATEANDEAT
MA_NOACTIVATEANDEAT  4  winuser.h

Do not activate the window, but do discard the mouse message. See WM_MOUSEACTIVATE.


FN_MA_NOACTIVATEANDEAT
MA_NOACTIVATEANDEAT  4  winuser.h


MAILSLOT_NO_MESSAGE
MAILSLOT_NO_MESSAGE  -1    winbase.h

There is no next message. See GetMailslotInfo.


FN_MAILSLOT_NO_MESSAGE
MAILSLOT_NO_MESSAGE  -1    winbase.h


MAILSLOT_WAIT_FOREVER
MAILSLOT_WAIT_FOREVER  -1    winbase.h

Waits forever for a message. See CreateMailslot.


FN_MAILSLOT_WAIT_FOREVER
MAILSLOT_WAIT_FOREVER  -1    winbase.h


MAP_COMPOSITE
MAP_COMPOSITE  0x00000040  winnls.h

Canonicalize accented characters to composite. This value cannot be combined with MAP_PRECOMPOSED. See FoldStringW.


FN_MAP_COMPOSITE
MAP_COMPOSITE  0x00000040  winnls.h


MAP_FOLDCZONE
MAP_FOLDCZONE  0x00000010  winnls.h

Fold compatibility zone characters. See FoldStringW.


FN_MAP_FOLDCZONE
MAP_FOLDCZONE  0x00000010  winnls.h


MAP_FOLDDIGITS
MAP_FOLDDIGITS  0x00000080  winnls.h

Canonicalize all digits to Unicode ASCII "0"-"9". See FoldStringW.


FN_MAP_FOLDDIGITS
MAP_FOLDDIGITS  0x00000080  winnls.h


MAP_PRECOMPOSED
MAP_PRECOMPOSED  0x00000020  winnls.h

Canonicalize accented characters to precomposed. This value cannot be combined with MAP_COMPOSITE. See FoldStringW.


FN_MAP_PRECOMPOSED
MAP_PRECOMPOSED  0x00000020  winnls.h


MARKPARITY
MARKPARITY  3  winbase.h

Mark See DCB.


FN_MARKPARITY
MARKPARITY  3  winbase.h


MB_ABORTRETRYIGNORE
MB_ABORTRETRYIGNORE  0x00000002L  winuser.h

The message box contains three push buttons: Abort, Retry, and Ignore. See MessageBox.


FN_MB_ABORTRETRYIGNORE
MB_ABORTRETRYIGNORE  0x00000002L  winuser.h


MB_APPLMODAL
MB_APPLMODAL  0x00000000L  winuser.h

The user must respond to the message box before continuing work in the window identified by the hwndOwner parameter. However, the user can move to the windows of other applications and work in those windows. MB_APPLMODAL is the default if neither MB_SYSTEMMODAL nor MB_TASKMODAL is specified. See MessageBox.


FN_MB_APPLMODAL
MB_APPLMODAL  0x00000000L  winuser.h


MB_COMPOSITE
MB_COMPOSITE  0x00000002  winnls.h

Always use composite characters. See MultiByteToWideChar.


FN_MB_COMPOSITE
MB_COMPOSITE  0x00000002  winnls.h


MB_DEFAULT_DESKTOP_ONLY
MB_DEFAULT_DESKTOP_ONLY  0x00020000L  winuser.h

The desktop currently receiving input must be a default desktop; otherwise, the function fails. A default desktop is a desktop that an application runs on once the user has logged on. See MessageBox.


FN_MB_DEFAULT_DESKTOP_ONLY
MB_DEFAULT_DESKTOP_ONLY  0x00020000L  winuser.h


MB_DEFBUTTON1
MB_DEFBUTTON1  0x00000000L  winuser.h

The first button is the default. Note that the first button is always the default unless MB_DEFBUTTON2 or MB_DEFBUTTON3 is specified. See MessageBox.


FN_MB_DEFBUTTON1
MB_DEFBUTTON1  0x00000000L  winuser.h


MB_DEFBUTTON2
MB_DEFBUTTON2  0x00000100L  winuser.h

The second button is the default. See MessageBox.


FN_MB_DEFBUTTON2
MB_DEFBUTTON2  0x00000100L  winuser.h


MB_DEFBUTTON3
MB_DEFBUTTON3  0x00000200L  winuser.h

The third button is the default. See MessageBox.


FN_MB_DEFBUTTON3
MB_DEFBUTTON3  0x00000200L  winuser.h


MB_ICONASTERISK
MB_ICONASTERISK  0x00000040L  winuser.h

SystemAsterisk; same as MB_ICONINFORMATION. See MessageBeep, MessageBox.


FN_MB_ICONASTERISK
MB_ICONASTERISK  0x00000040L  winuser.h


MB_ICONEXCLAMATION
MB_ICONEXCLAMATION  0x00000030L  winuser.h

An exclamation-point icon appears in the message box. See MessageBeep, MessageBox.


FN_MB_ICONEXCLAMATION
MB_ICONEXCLAMATION  0x00000030L  winuser.h


MB_ICONHAND
MB_ICONHAND  0x00000010L  winuser.h

SystemHand; same as MB_ICONSTOP. See MessageBeep, MessageBox.


FN_MB_ICONHAND
MB_ICONHAND  0x00000010L  winuser.h


MB_ICONINFORMATION
MB_ICONINFORMATION  MB_ICONASTERISK  winuser.h

An icon consisting of a lowercase letter "I" in a circle appears in the message box. See MessageBox.


FN_MB_ICONINFORMATION
MB_ICONINFORMATION  MB_ICONASTERISK  winuser.h


MB_ICONQUESTION
MB_ICONQUESTION  0x00000020L  winuser.h

A question-mark icon appears in the message box. See MessageBeep, MessageBox.


FN_MB_ICONQUESTION
MB_ICONQUESTION  0x00000020L  winuser.h


MB_ICONSTOP
MB_ICONSTOP  MB_ICONHAND  winuser.h

A stop-sign icon appears in the message box. See MessageBox.


FN_MB_ICONSTOP
MB_ICONSTOP  MB_ICONHAND  winuser.h


MB_OK
MB_OK  0x00000000L  winuser.h

SystemDefault MB_OK The message box contains one push button: OK. See MessageBeep, MessageBox.


FN_MB_OK
MB_OK  0x00000000L  winuser.h


MB_OKCANCEL
MB_OKCANCEL  0x00000001L  winuser.h

The message box contains two push buttons: OK and Cancel. See MessageBox.


FN_MB_OKCANCEL
MB_OKCANCEL  0x00000001L  winuser.h


MB_PRECOMPOSED
MB_PRECOMPOSED  0x00000001  winnls.h

Always use precomposed characters. This is the default translation option. See MultiByteToWideChar.


FN_MB_PRECOMPOSED
MB_PRECOMPOSED  0x00000001  winnls.h


MB_RETRYCANCEL
MB_RETRYCANCEL  0x00000005L  winuser.h

The message box contains two push buttons: Retry and Cancel. See MessageBox.


FN_MB_RETRYCANCEL
MB_RETRYCANCEL  0x00000005L  winuser.h


MB_SETFOREGROUND
MB_SETFOREGROUND  0x00010000L  winuser.h

The message box becomes the foreground window. Internally, Windows calls the SetForegroundWindow function for the message box. See MessageBox.


FN_MB_SETFOREGROUND
MB_SETFOREGROUND  0x00010000L  winuser.h


MB_SYSTEMMODAL
MB_SYSTEMMODAL  0x00001000L  winuser.h

All applications are suspended until the user responds to the message box. Unless the application specifies MB_ICONHAND, the message box does not become modal until after it is created; consequently, the owner window and other windows continue to receive messages resulting from its activation. System-modal message boxes are used to notify the user of serious, potentially damaging errors that require immediate attention (for example, running out of memory). See MessageBox.


FN_MB_SYSTEMMODAL
MB_SYSTEMMODAL  0x00001000L  winuser.h


MB_TASKMODAL
MB_TASKMODAL  0x00002000L  winuser.h

Same as MB_APPLMODAL except that all the top-level windows belonging to the current task are disabled if the hwndOwner parameter is NULL. This flag should be used 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. See MessageBox.


FN_MB_TASKMODAL
MB_TASKMODAL  0x00002000L  winuser.h


MB_USEGLYPHCHARS
MB_USEGLYPHCHARS  0x00000004  winnls.h

Use glyph characters instead of control characters. See MultiByteToWideChar.


FN_MB_USEGLYPHCHARS
MB_USEGLYPHCHARS  0x00000004  winnls.h


MB_YESNO
MB_YESNO  0x00000004L  winuser.h

The message box contains two push buttons: Yes and No. See MessageBox.


FN_MB_YESNO
MB_YESNO  0x00000004L  winuser.h


MB_YESNOCANCEL
MB_YESNOCANCEL  0x00000003L  winuser.h

The message box contains three push buttons: Yes, No, and Cancel. See MessageBox.


FN_MB_YESNOCANCEL
MB_YESNOCANCEL  0x00000003L  winuser.h


MCI_ANIM_GETDEVCAPS_CAN_REVERSE
MCI_ANIM_GETDEVCAPS_CAN_REVERSE  0x00004001L  mmsystem.h

The dwReturn member is set to TRUE if the device can play in reverse; otherwise, it is set to FALSE. See MCI_GETDEVCAPS.


FN_MCI_ANIM_GETDEVCAPS_CAN_REVERSE
MCI_ANIM_GETDEVCAPS_CAN_REVERSE  0x00004001L  mmsystem.h


MCI_ANIM_GETDEVCAPS_CAN_STRETCH
MCI_ANIM_GETDEVCAPS_CAN_STRETCH  0x00004007L  mmsystem.h

The dwReturn member is set to TRUE if the device can stretch the image to fill the frame; otherwise, it is set to FALSE. MCIMMP returns FALSE. See MCI_GETDEVCAPS.


FN_MCI_ANIM_GETDEVCAPS_CAN_STRETCH
MCI_ANIM_GETDEVCAPS_CAN_STRETCH  0x00004007L  mmsystem.h


MCI_ANIM_GETDEVCAPS_FAST_RATE
MCI_ANIM_GETDEVCAPS_FAST_RATE  0x00004002L  mmsystem.h

The dwReturn member is set to the standard fast play rate in frames per second. MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION. See MCI_GETDEVCAPS.


FN_MCI_ANIM_GETDEVCAPS_FAST_RATE
MCI_ANIM_GETDEVCAPS_FAST_RATE  0x00004002L  mmsystem.h


MCI_ANIM_GETDEVCAPS_MAX_WINDOWS
MCI_ANIM_GETDEVCAPS_MAX_WINDOWS  0x00004008L  mmsystem.h

The dwReturn member is set to the maximum number of windows that the device can handle simultaneously. See MCI_GETDEVCAPS.


FN_MCI_ANIM_GETDEVCAPS_MAX_WINDOWS
MCI_ANIM_GETDEVCAPS_MAX_WINDOWS  0x00004008L  mmsystem.h


MCI_ANIM_GETDEVCAPS_NORMAL_RATE
MCI_ANIM_GETDEVCAPS_NORMAL_RATE  0x00004004L  mmsystem.h

The dwReturn member is set to the normal rate of play in frames per second. MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION. See MCI_GETDEVCAPS.


FN_MCI_ANIM_GETDEVCAPS_NORMAL_RATE
MCI_ANIM_GETDEVCAPS_NORMAL_RATE  0x00004004L  mmsystem.h


MCI_ANIM_GETDEVCAPS_PALETTES
MCI_ANIM_GETDEVCAPS_PALETTES  0x00004006L  mmsystem.h

The dwReturn member is set to TRUE if the device can return a palette handle; otherwise, it is set to FALSE. MCIMMP returns TRUE. See MCI_GETDEVCAPS.


FN_MCI_ANIM_GETDEVCAPS_PALETTES
MCI_ANIM_GETDEVCAPS_PALETTES  0x00004006L  mmsystem.h


MCI_ANIM_GETDEVCAPS_SLOW_RATE
MCI_ANIM_GETDEVCAPS_SLOW_RATE  0x00004003L  mmsystem.h

The dwReturn member is set to the standard slow play rate in frames per second. MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION. See MCI_GETDEVCAPS.


FN_MCI_ANIM_GETDEVCAPS_SLOW_RATE
MCI_ANIM_GETDEVCAPS_SLOW_RATE  0x00004003L  mmsystem.h


MCI_ANIM_INFO_TEXT
MCI_ANIM_INFO_TEXT  0x00010000L  mmsystem.h

Obtains the window caption. See MCI_INFO.


FN_MCI_ANIM_INFO_TEXT
MCI_ANIM_INFO_TEXT  0x00010000L  mmsystem.h


MCI_ANIM_OPEN_NOSTATIC
MCI_ANIM_OPEN_NOSTATIC  0x00040000L  mmsystem.h

Specifies that the device should reduce the number of static (system) colors in the palette to two. See MCI_OPEN.


FN_MCI_ANIM_OPEN_NOSTATIC
MCI_ANIM_OPEN_NOSTATIC  0x00040000L  mmsystem.h


MCI_ANIM_OPEN_PARENT
MCI_ANIM_OPEN_PARENT  0x00020000L  mmsystem.h

Indicates the parent window handle is specified in the hWndParent member of the data structure identified by lpOpen. The parent window handle is required for some window styles. See MCI_OPEN.


FN_MCI_ANIM_OPEN_PARENT
MCI_ANIM_OPEN_PARENT  0x00020000L  mmsystem.h


MCI_ANIM_OPEN_WS
MCI_ANIM_OPEN_WS  0x00010000L  mmsystem.h

Indicates a window style is specified in the dwStyle member of the data 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 which defines the window style. These constants are the same as the ones in WINDOWS.H (such as WS_CHILD, WS_OVERLAPPEDWINDOW, or WS_POPUP). See MCI_OPEN.


FN_MCI_ANIM_OPEN_WS
MCI_ANIM_OPEN_WS  0x00010000L  mmsystem.h


MCI_ANIM_PLAY_FAST
MCI_ANIM_PLAY_FAST  0x00040000L  mmsystem.h

Specifies to play fast. See MCI_PLAY.


FN_MCI_ANIM_PLAY_FAST
MCI_ANIM_PLAY_FAST  0x00040000L  mmsystem.h


MCI_ANIM_PLAY_REVERSE
MCI_ANIM_PLAY_REVERSE  0x00020000L  mmsystem.h

Specifies to play in reverse. See MCI_PLAY.


FN_MCI_ANIM_PLAY_REVERSE
MCI_ANIM_PLAY_REVERSE  0x00020000L  mmsystem.h


MCI_ANIM_PLAY_SCAN
MCI_ANIM_PLAY_SCAN  0x00100000L  mmsystem.h

Specifies to scan quickly. See MCI_PLAY.


FN_MCI_ANIM_PLAY_SCAN
MCI_ANIM_PLAY_SCAN  0x00100000L  mmsystem.h


MCI_ANIM_PLAY_SLOW
MCI_ANIM_PLAY_SLOW  0x00080000L  mmsystem.h

Specifies to play slowly. See MCI_PLAY.


FN_MCI_ANIM_PLAY_SLOW
MCI_ANIM_PLAY_SLOW  0x00080000L  mmsystem.h


MCI_ANIM_PLAY_SPEED
MCI_ANIM_PLAY_SPEED  0x00010000L  mmsystem.h

Specifies that the play speed is included in the dwSpeed member in the data structure identified by lpPlay. See MCI_PLAY.


FN_MCI_ANIM_PLAY_SPEED
MCI_ANIM_PLAY_SPEED  0x00010000L  mmsystem.h


MCI_ANIM_PUT_DESTINATION
MCI_ANIM_PUT_DESTINATION  0x00040000L  mmsystem.h

Indicates the rectangle defined for MCI_ANIM_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. See MCI_PUT.


FN_MCI_ANIM_PUT_DESTINATION
MCI_ANIM_PUT_DESTINATION  0x00040000L  mmsystem.h


MCI_ANIM_PUT_SOURCE
MCI_ANIM_PUT_SOURCE  0x00020000L  mmsystem.h

Indicates the rectangle defined for MCI_ANIM_RECT specifies a clipping rectangle for the animation image. The rectangle contains the offset and extent of the image relative to the image origin. See MCI_PUT.


FN_MCI_ANIM_PUT_SOURCE
MCI_ANIM_PUT_SOURCE  0x00020000L  mmsystem.h


MCI_ANIM_RECT
MCI_ANIM_RECT  0x00010000L  mmsystem.h

Specifies that the rc member of the data structure identified by lpDest contains a valid rectangle. If this flag is not specified, the default rectangle matches the coordinates of the image or window being clipped. See MCI_PUT.


FN_MCI_ANIM_RECT
MCI_ANIM_RECT  0x00010000L  mmsystem.h


MCI_ANIM_STATUS_FORWARD
MCI_ANIM_STATUS_FORWARD  0x00004002L  mmsystem.h

The dwReturn member is set to TRUE if playing forward; otherwise, it is set to FALSE. See MCI_STATUS.


FN_MCI_ANIM_STATUS_FORWARD
MCI_ANIM_STATUS_FORWARD  0x00004002L  mmsystem.h


MCI_ANIM_STATUS_HPAL
MCI_ANIM_STATUS_HPAL  0x00004004L  mmsystem.h

The dwReturn member is set to the handle of the movie palette. See MCI_STATUS.


FN_MCI_ANIM_STATUS_HPAL
MCI_ANIM_STATUS_HPAL  0x00004004L  mmsystem.h


MCI_ANIM_STATUS_HWND
MCI_ANIM_STATUS_HWND  0x00004003L  mmsystem.h

The dwReturn member is set to the handle of the playback window. See MCI_STATUS.


FN_MCI_ANIM_STATUS_HWND
MCI_ANIM_STATUS_HWND  0x00004003L  mmsystem.h


MCI_ANIM_STATUS_SPEED
MCI_ANIM_STATUS_SPEED  0x00004001L  mmsystem.h

The dwReturn member is set to the animation speed. See MCI_STATUS.


FN_MCI_ANIM_STATUS_SPEED
MCI_ANIM_STATUS_SPEED  0x00004001L  mmsystem.h


MCI_ANIM_STEP_FRAMES
MCI_ANIM_STEP_FRAMES  0x00020000L  mmsystem.h

Indicates that the dwFrames member of the data structure identified by lpStep specifies the number of frames to step. See MCI_STEP.


FN_MCI_ANIM_STEP_FRAMES
MCI_ANIM_STEP_FRAMES  0x00020000L  mmsystem.h


MCI_ANIM_STEP_REVERSE
MCI_ANIM_STEP_REVERSE  0x00010000L  mmsystem.h

Steps in reverse. See MCI_STEP.


FN_MCI_ANIM_STEP_REVERSE
MCI_ANIM_STEP_REVERSE  0x00010000L  mmsystem.h


MCI_ANIM_WHERE_DESTINATION
MCI_ANIM_WHERE_DESTINATION  0x00040000L  mmsystem.h

Obtains the destination display rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery. See MCI_WHERE.


FN_MCI_ANIM_WHERE_DESTINATION
MCI_ANIM_WHERE_DESTINATION  0x00040000L  mmsystem.h


MCI_ANIM_WHERE_SOURCE
MCI_ANIM_WHERE_SOURCE  0x00020000L  mmsystem.h

Obtains the animation source rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery. See MCI_WHERE.


FN_MCI_ANIM_WHERE_SOURCE
MCI_ANIM_WHERE_SOURCE  0x00020000L  mmsystem.h


MCI_ANIM_WINDOW_HWND
MCI_ANIM_WINDOW_HWND  0x00010000L  mmsystem.h

Indicates the handle of the window to use for the destination is included in the hWnd member of the data structure identified by lpWindow. Set this to MCI_ANIM_WINDOW_DEFAULT to return to the default window. See MCI_WINDOW.


FN_MCI_ANIM_WINDOW_HWND
MCI_ANIM_WINDOW_HWND  0x00010000L  mmsystem.h


MCI_ANIM_WINDOW_STATE
MCI_ANIM_WINDOW_STATE  0x00040000L  mmsystem.h

Indicates the nCmdShow member of the MCI_ANIM_WINDOW_PARMS data 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 the ones in WINDOWS.H (such as SW_HIDE, SW_MINIMIZE, or SW_SHOWNORMAL.) See MCI_WINDOW.


FN_MCI_ANIM_WINDOW_STATE
MCI_ANIM_WINDOW_STATE  0x00040000L  mmsystem.h


MCI_ANIM_WINDOW_TEXT
MCI_ANIM_WINDOW_TEXT  0x00080000L  mmsystem.h

Indicates the lpstrText member of the MCI_ANIM_WINDOW_PARMS data structure contains a pointer to a buffer containing the caption used for the window. See MCI_WINDOW.


FN_MCI_ANIM_WINDOW_TEXT
MCI_ANIM_WINDOW_TEXT  0x00080000L  mmsystem.h


MCI_BREAK_HWND
MCI_BREAK_HWND  0x00000200L  mmsystem.h

Indicates the hwndBreak member of the data structure identified by lpBreak contains a window handle which 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. See MCI_BREAK.


FN_MCI_BREAK_HWND
MCI_BREAK_HWND  0x00000200L  mmsystem.h


MCI_BREAK_KEY
MCI_BREAK_KEY  0x00000100L  mmsystem.h

Indicates the nVirtKey member of the data 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. See MCI_BREAK.


FN_MCI_BREAK_KEY
MCI_BREAK_KEY  0x00000100L  mmsystem.h


MCI_BREAK_OFF
MCI_BREAK_OFF  0x00000400L  mmsystem.h

Used to disable any existing break key for the indicated device See MCI_BREAK.


FN_MCI_BREAK_OFF
MCI_BREAK_OFF  0x00000400L  mmsystem.h


MCI_FORMAT_BYTES
MCI_FORMAT_BYTES  8  mmsystem.h

Changes the time format to bytes for input or output. See MCI_SET.


FN_MCI_FORMAT_BYTES
MCI_FORMAT_BYTES  8  mmsystem.h


MCI_FORMAT_CHAPTERS

Changes the time format to chapters. See MCI_SET.


MCI_FORMAT_FRAMES
MCI_FORMAT_FRAMES  3  mmsystem.h

Changes the time format to frames. MCI_FORMAT_FRAMES Changes the time format to frames. See MCI_SET.


FN_MCI_FORMAT_FRAMES
MCI_FORMAT_FRAMES  3  mmsystem.h


MCI_FORMAT_HMS
MCI_FORMAT_HMS  1  mmsystem.h

Changes the time format to hours, minutes, and seconds. See MCI_SET.


FN_MCI_FORMAT_HMS
MCI_FORMAT_HMS  1  mmsystem.h


MCI_FORMAT_MILLISECONDS
MCI_FORMAT_MILLISECONDS  0  mmsystem.h

Changes the time format to milliseconds. See MCI_SET,


FN_MCI_FORMAT_MILLISECONDS
MCI_FORMAT_MILLISECONDS  0  mmsystem.h


MCI_FORMAT_MSF
MCI_FORMAT_MSF  2  mmsystem.h

Changes the time format to minutes, seconds, and frames. See MCI_SET.


FN_MCI_FORMAT_MSF
MCI_FORMAT_MSF  2  mmsystem.h


MCI_FORMAT_SAMPLES
MCI_FORMAT_SAMPLES  9  mmsystem.h

Changes the time format to samples for input or output. See MCI_SET.


FN_MCI_FORMAT_SAMPLES
MCI_FORMAT_SAMPLES  9  mmsystem.h


MCI_FORMAT_SMPTE_24
MCI_FORMAT_SMPTE_24  4  mmsystem.h

Sets the time format to 24 frame SMPTE. See MCI_SET.


FN_MCI_FORMAT_SMPTE_24
MCI_FORMAT_SMPTE_24  4  mmsystem.h


MCI_FORMAT_SMPTE_25
MCI_FORMAT_SMPTE_25  5  mmsystem.h

Sets the time format to 25 frame SMPTE. See MCI_SET.


FN_MCI_FORMAT_SMPTE_25
MCI_FORMAT_SMPTE_25  5  mmsystem.h


MCI_FORMAT_SMPTE_30
MCI_FORMAT_SMPTE_30  6  mmsystem.h

Sets the time format to 30 frame SMPTE. See MCI_SET.


FN_MCI_FORMAT_SMPTE_30
MCI_FORMAT_SMPTE_30  6  mmsystem.h


MCI_FORMAT_SMPTE_30DROP
MCI_FORMAT_SMPTE_30DROP  7  mmsystem.h

Sets the time format to 30 drop-frame SMPTE. See MCI_SET.


FN_MCI_FORMAT_SMPTE_30DROP
MCI_FORMAT_SMPTE_30DROP  7  mmsystem.h


MCI_FORMAT_TMSF
MCI_FORMAT_TMSF  10  mmsystem.h

Changes the time format to tracks, minutes, seconds, and frames. (MCI uses continuous track numbers.) See MCI_SET.


FN_MCI_FORMAT_TMSF
MCI_FORMAT_TMSF  10  mmsystem.h


MCI_FROM
MCI_FROM  0x00000004L  mmsystem.h

Specifies that a beginning position is included in the dwFrom member of the data structure identified by lpDelete. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. See MCI_DELETE, MCI_PLAY, MCI_RECORD.


FN_MCI_FROM
MCI_FROM  0x00000004L  mmsystem.h


MCI_GETDEVCAPS_CAN_EJECT
MCI_GETDEVCAPS_CAN_EJECT  0x00000007L  mmsystem.h

The dwReturn member is set to TRUE if the device can eject the media; otherwise, it is set to FALSE. See MCI_GETDEVCAPS.


FN_MCI_GETDEVCAPS_CAN_EJECT
MCI_GETDEVCAPS_CAN_EJECT  0x00000007L  mmsystem.h


MCI_GETDEVCAPS_CAN_PLAY
MCI_GETDEVCAPS_CAN_PLAY  0x00000008L  mmsystem.h

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 MCI_PAUSE and MCI_STOP as well as MCI_PLAY. See MCI_GETDEVCAPS.


FN_MCI_GETDEVCAPS_CAN_PLAY
MCI_GETDEVCAPS_CAN_PLAY  0x00000008L  mmsystem.h


MCI_GETDEVCAPS_CAN_RECORD
MCI_GETDEVCAPS_CAN_RECORD  0x00000001L  mmsystem.h

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 MCI_PAUSE and MCI_STOP as well as MCI_RECORD. See MCI_GETDEVCAPS.


FN_MCI_GETDEVCAPS_CAN_RECORD
MCI_GETDEVCAPS_CAN_RECORD  0x00000001L  mmsystem.h


MCI_GETDEVCAPS_CAN_SAVE
MCI_GETDEVCAPS_CAN_SAVE  0x00000009L  mmsystem.h

The dwReturn member is set to TRUE if the device can save a file; otherwise, it is set to FALSE. See MCI_GETDEVCAPS.


FN_MCI_GETDEVCAPS_CAN_SAVE
MCI_GETDEVCAPS_CAN_SAVE  0x00000009L  mmsystem.h


MCI_GETDEVCAPS_COMPOUND_DEVICE
MCI_GETDEVCAPS_COMPOUND_DEVICE  0x00000006L  mmsystem.h

The dwReturn member is set to TRUE if the device uses device elements; otherwise, it is set to FALSE. See MCI_GETDEVCAPS.


FN_MCI_GETDEVCAPS_COMPOUND_DEVICE
MCI_GETDEVCAPS_COMPOUND_DEVICE  0x00000006L  mmsystem.h


MCI_GETDEVCAPS_DEVICE_TYPE
MCI_GETDEVCAPS_DEVICE_TYPE  0x00000004L  mmsystem.h

The dwReturn member is set to one of the following values indicating the device type: See MCI_GETDEVCAPS.


FN_MCI_GETDEVCAPS_DEVICE_TYPE
MCI_GETDEVCAPS_DEVICE_TYPE  0x00000004L  mmsystem.h


MCI_GETDEVCAPS_HAS_AUDIO
MCI_GETDEVCAPS_HAS_AUDIO  0x00000002L  mmsystem.h

The dwReturn member is set to TRUE if the device has audio output; otherwise, it is set to FALSE. See MCI_GETDEVCAPS.


FN_MCI_GETDEVCAPS_HAS_AUDIO
MCI_GETDEVCAPS_HAS_AUDIO  0x00000002L  mmsystem.h


MCI_GETDEVCAPS_HAS_VIDEO
MCI_GETDEVCAPS_HAS_VIDEO  0x00000003L  mmsystem.h

The dwReturn member is set to TRUE if the device has video output; otherwise, it is set to FALSE. For example, the member is set to TRUE for devices that support the animation or videodisc command set. See MCI_GETDEVCAPS.


FN_MCI_GETDEVCAPS_HAS_VIDEO
MCI_GETDEVCAPS_HAS_VIDEO  0x00000003L  mmsystem.h


MCI_GETDEVCAPS_ITEM
MCI_GETDEVCAPS_ITEM  0x00000100L  mmsystem.h

Specifies that the dwItem member of the data structure identified by lpCapsParms contains a constant specifying which device capability to obtain. See MCI_GETDEVCAPS.


FN_MCI_GETDEVCAPS_ITEM
MCI_GETDEVCAPS_ITEM  0x00000100L  mmsystem.h


MCI_GETDEVCAPS_USES_FILES
MCI_GETDEVCAPS_USES_FILES  0x00000005L  mmsystem.h

The dwReturn member is set to TRUE if the device requires a filename as its element name; otherwise, it is set to FALSE. Only compound devices use files. See MCI_GETDEVCAPS.


FN_MCI_GETDEVCAPS_USES_FILES
MCI_GETDEVCAPS_USES_FILES  0x00000005L  mmsystem.h


MCI_INFO_FILE
MCI_INFO_FILE  0x00000200L  mmsystem.h

Obtains the filename of the current file. This flag is only supported by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES query. MCI_INFO_FILE Obtains the filename of the current file. This flag is only supported by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES query. MCI_INFO_FILE Obtains the filename of the current file. This flag is supported by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES query. See MCI_INFO.


FN_MCI_INFO_FILE
MCI_INFO_FILE  0x00000200L  mmsystem.h


MCI_INFO_PRODUCT
MCI_INFO_PRODUCT  0x00000100L  mmsystem.h

Obtains a description of the hardware associated with a device. Devices should supply a description that identifies both the driver and the hardware used. See MCI_INFO.


FN_MCI_INFO_PRODUCT
MCI_INFO_PRODUCT  0x00000100L  mmsystem.h


MCI_LOAD_FILE
MCI_LOAD_FILE  0x00000100L  mmsystem.h

Indicates the lpfilename member of the data structure identified by lpLoad contains a pointer to a buffer containing the file name. See MCI_LOAD.


FN_MCI_LOAD_FILE
MCI_LOAD_FILE  0x00000100L  mmsystem.h


MCI_NOTIFY
MCI_NOTIFY  0x00000001L  mmsystem.h

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the data structure identified by lpWindow. See MCI_BREAK, MCI_CLOSE, MCI_COPY, MCI_CUE, MCI_CUT, MCI_DELETE, MCI_FREEZE, MCI_GETDEVCAPS, MCI_INFO, MCI_LOAD, MCI_OPEN, MCI_PASTE, MCI_PAUSE, MCI_PLAY, MCI_PUT, MCI_RECORD, MCI_RESUME, MCI_SAVE, MCI_SEEK, MCI_SET, MCI_SOUND, MCI_STATUS, MCI_STEP, MCI_STOP, MCI_UNFREEZE, MCI_WHERE, MCI_WINDOW.


FN_MCI_NOTIFY
MCI_NOTIFY  0x00000001L  mmsystem.h


MCI_NOTIFY_ABORTED
MCI_NOTIFY_ABORTED  0x0004  mmsystem.h

Specifies that the device received a command that prevented the current conditions for initiating the callback from being met. If a new command interrupts the current command and it also requests notification, the device sends only this message and not MCI_NOTIFY_SUPERCEDED. See MM_MCINOTIFY.


FN_MCI_NOTIFY_ABORTED
MCI_NOTIFY_ABORTED  0x0004  mmsystem.h


MCI_NOTIFY_FAILURE
MCI_NOTIFY_FAILURE  0x0008  mmsystem.h

Specifies that a device error occurred while the device was executing the command. See MM_MCINOTIFY.


FN_MCI_NOTIFY_FAILURE
MCI_NOTIFY_FAILURE  0x0008  mmsystem.h


MCI_NOTIFY_SUCCESSFUL
MCI_NOTIFY_SUCCESSFUL  0x0001  mmsystem.h

Specifies that the conditions initiating the callback have been met. See MM_MCINOTIFY.


FN_MCI_NOTIFY_SUCCESSFUL
MCI_NOTIFY_SUCCESSFUL  0x0001  mmsystem.h


MCI_NOTIFY_SUPERSEDED
MCI_NOTIFY_SUPERSEDED  0x0002  mmsystem.h

Specifies that the device received another command with the MCI_NOTIFY flag set and the current conditions for initiating the callback have been superseded. See MM_MCINOTIFY.


FN_MCI_NOTIFY_SUPERSEDED
MCI_NOTIFY_SUPERSEDED  0x0002  mmsystem.h


MCI_OPEN_ALIAS
MCI_OPEN_ALIAS  0x00000400L  mmsystem.h

Specifies that an alias is included in the lpstrAlias member of the data structure identified by lpOpen. See MCI_OPEN.


FN_MCI_OPEN_ALIAS
MCI_OPEN_ALIAS  0x00000400L  mmsystem.h


MCI_OPEN_ELEMENT
MCI_OPEN_ELEMENT  0x00000200L  mmsystem.h

Specifies that an element name is included in the lpstrElementName member of the data structure identified by lpOpen. See MCI_OPEN.


FN_MCI_OPEN_ELEMENT
MCI_OPEN_ELEMENT  0x00000200L  mmsystem.h


MCI_OPEN_ELEMENT_ID
MCI_OPEN_ELEMENT_ID  0x00000800L  mmsystem.h

Specifies that the lpstrElementName member of the data structure identified by lpOpen is interpreted as a DWORD and has meaning internal to the device. Use this flag with the MCI_OPEN_ELEMENT flag. See MCI_OPEN.


FN_MCI_OPEN_ELEMENT_ID
MCI_OPEN_ELEMENT_ID  0x00000800L  mmsystem.h


MCI_OPEN_SHAREABLE
MCI_OPEN_SHAREABLE  0x00000100L  mmsystem.h

Specifies that the device or device element should be opened as shareable. See MCI_OPEN.


FN_MCI_OPEN_SHAREABLE
MCI_OPEN_SHAREABLE  0x00000100L  mmsystem.h


MCI_OPEN_TYPE
MCI_OPEN_TYPE  0x00002000L  mmsystem.h

Specifies that a device type name or constant is included in the lpstrDeviceType member of the data structure identified by lpOpen. See MCI_OPEN.


FN_MCI_OPEN_TYPE
MCI_OPEN_TYPE  0x00002000L  mmsystem.h


MCI_OPEN_TYPE_ID
MCI_OPEN_TYPE_ID  0x00001000L  mmsystem.h

Specifies that the low-order word of the lpstrDeviceType member of the associated data structure contains a standard MCI device type ID and the high-order word optionally contains the ordinal index for the device. Use this flag with the MCI_OPEN_TYPE flag. See MCI_OPEN.


FN_MCI_OPEN_TYPE_ID
MCI_OPEN_TYPE_ID  0x00001000L  mmsystem.h


MCI_OVLY_GETDEVCAPS_CAN_FREEZE
MCI_OVLY_GETDEVCAPS_CAN_FREEZE  0x00004002L  mmsystem.h

The dwReturn member is set to TRUE if the device can freeze the image; otherwise, it is set to FALSE. See MCI_GETDEVCAPS.


FN_MCI_OVLY_GETDEVCAPS_CAN_FREEZE
MCI_OVLY_GETDEVCAPS_CAN_FREEZE  0x00004002L  mmsystem.h


MCI_OVLY_GETDEVCAPS_CAN_STRETCH
MCI_OVLY_GETDEVCAPS_CAN_STRETCH  0x00004001L  mmsystem.h

The dwReturn member is set to TRUE if the device can stretch the image to fill the frame; otherwise, it is set to FALSE. See MCI_GETDEVCAPS.


FN_MCI_OVLY_GETDEVCAPS_CAN_STRETCH
MCI_OVLY_GETDEVCAPS_CAN_STRETCH  0x00004001L  mmsystem.h


MCI_OVLY_GETDEVCAPS_MAX_WINDOWS
MCI_OVLY_GETDEVCAPS_MAX_WINDOWS  0x00004003L  mmsystem.h

The dwReturn member is set to the maximum number of windows that the device can handle simultaneously. See MCI_GETDEVCAPS.


FN_MCI_OVLY_GETDEVCAPS_MAX_WINDOWS
MCI_OVLY_GETDEVCAPS_MAX_WINDOWS  0x00004003L  mmsystem.h


MCI_OVLY_INFO_TEXT
MCI_OVLY_INFO_TEXT  0x00010000L  mmsystem.h

Obtains the caption of the window associated with the overlay device. See MCI_INFO.


FN_MCI_OVLY_INFO_TEXT
MCI_OVLY_INFO_TEXT  0x00010000L  mmsystem.h


MCI_OVLY_OPEN_PARENT
MCI_OVLY_OPEN_PARENT  0x00020000L  mmsystem.h

Indicates the parent window handle is specified in the hWndParent member of the data structure identified by lpOpen. See MCI_OPEN.


FN_MCI_OVLY_OPEN_PARENT
MCI_OVLY_OPEN_PARENT  0x00020000L  mmsystem.h


MCI_OVLY_OPEN_WS
MCI_OVLY_OPEN_WS  0x00010000L  mmsystem.h

Indicates a window style is specified in the dwStyle member of the data 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 those in WINDOWS.H (for example, WS_CHILD, WS_OVERLAPPEDWINDOW, or WS_POPUP). See MCI_OPEN.


FN_MCI_OVLY_OPEN_WS
MCI_OVLY_OPEN_WS  0x00010000L  mmsystem.h


MCI_OVLY_PUT_DESTINATION
MCI_OVLY_PUT_DESTINATION  0x00040000L  mmsystem.h

Indicates 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. See MCI_PUT.


FN_MCI_OVLY_PUT_DESTINATION
MCI_OVLY_PUT_DESTINATION  0x00040000L  mmsystem.h


MCI_OVLY_PUT_FRAME
MCI_OVLY_PUT_FRAME  0x00080000L  mmsystem.h

Indicates 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. See MCI_PUT.


FN_MCI_OVLY_PUT_FRAME
MCI_OVLY_PUT_FRAME  0x00080000L  mmsystem.h


MCI_OVLY_PUT_SOURCE
MCI_OVLY_PUT_SOURCE  0x00020000L  mmsystem.h

Indicates that 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. See MCI_PUT.


FN_MCI_OVLY_PUT_SOURCE
MCI_OVLY_PUT_SOURCE  0x00020000L  mmsystem.h


MCI_OVLY_PUT_VIDEO
MCI_OVLY_PUT_VIDEO  0x00100000L  mmsystem.h

Indicates that 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. See MCI_PUT.


FN_MCI_OVLY_PUT_VIDEO
MCI_OVLY_PUT_VIDEO  0x00100000L  mmsystem.h


MCI_OVLY_RECT
MCI_OVLY_RECT  0x00010000L  mmsystem.h

Specifies that the rc member of the data structure identified by lpFreeze contains a valid rectangle. If this flag is not specified, the device driver will freeze the entire frame. MCI_OVLY_RECT Specifies that the rc member of the data structure identified by lpLoad contains a valid display rectangle that identifies the area of the video buffer to update. MCI_OVLY_RECT Specifies that the rc member of the data 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. MCI_OVLY_RECT Specifies that the rc member of the data structure identified by lpSave contains a valid display rectangle indicating the area of the video buffer to save. MCI_OVLY_RECT Specifies that the rc member of the data structure identified by lpFreeze contains a valid display rectangle. This is a required parameter. See MCI_FREEZE, MCI_LOAD, MCI_PUT, MCI_SAVE, MCI_UNFREEZE.


FN_MCI_OVLY_RECT
MCI_OVLY_RECT  0x00010000L  mmsystem.h


MCI_OVLY_STATUS_HWND
MCI_OVLY_STATUS_HWND  0x00004001L  mmsystem.h

The dwReturn member is set to the handle of the window associated with the video overlay device. See MCI_STATUS.


FN_MCI_OVLY_STATUS_HWND
MCI_OVLY_STATUS_HWND  0x00004001L  mmsystem.h


MCI_OVLY_WHERE_DESTINATION
MCI_OVLY_WHERE_DESTINATION  0x00040000L  mmsystem.h

Obtains the destination display rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery. See MCI_WHERE.


FN_MCI_OVLY_WHERE_DESTINATION
MCI_OVLY_WHERE_DESTINATION  0x00040000L  mmsystem.h


MCI_OVLY_WHERE_FRAME
MCI_OVLY_WHERE_FRAME  0x00080000L  mmsystem.h

Obtains the overlay frame rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery. See MCI_WHERE.


FN_MCI_OVLY_WHERE_FRAME
MCI_OVLY_WHERE_FRAME  0x00080000L  mmsystem.h


MCI_OVLY_WHERE_SOURCE
MCI_OVLY_WHERE_SOURCE  0x00020000L  mmsystem.h

Obtains the source rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery. See MCI_WHERE.


FN_MCI_OVLY_WHERE_SOURCE
MCI_OVLY_WHERE_SOURCE  0x00020000L  mmsystem.h


MCI_OVLY_WHERE_VIDEO
MCI_OVLY_WHERE_VIDEO  0x00100000L  mmsystem.h

Obtains the video rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery. See MCI_WHERE.


FN_MCI_OVLY_WHERE_VIDEO
MCI_OVLY_WHERE_VIDEO  0x00100000L  mmsystem.h


MCI_OVLY_WINDOW_HWND
MCI_OVLY_WINDOW_HWND  0x00010000L  mmsystem.h

Indicates the handle of the window used for the destination is included in the hWnd member of the MCI_OVLY_WINDOW_PARMS data structure. Set this to MCI_OVLY_WINDOW_DEFAULT to return to the default window. See MCI_WINDOW.


FN_MCI_OVLY_WINDOW_HWND
MCI_OVLY_WINDOW_HWND  0x00010000L  mmsystem.h


MCI_OVLY_WINDOW_STATE
MCI_OVLY_WINDOW_STATE  0x00040000L  mmsystem.h

Indicates the nCmdShow member of the lpWindow data structure contains parameters for setting the window state. This flag It 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.) See MCI_WINDOW.


FN_MCI_OVLY_WINDOW_STATE
MCI_OVLY_WINDOW_STATE  0x00040000L  mmsystem.h


MCI_OVLY_WINDOW_TEXT
MCI_OVLY_WINDOW_TEXT  0x00080000L  mmsystem.h

Indicates the lpstrText member of the MCI_OVLY_WINDOW_PARMS data structure contains a pointer to buffer containing the caption used for the window. See MCI_WINDOW.


FN_MCI_OVLY_WINDOW_TEXT
MCI_OVLY_WINDOW_TEXT  0x00080000L  mmsystem.h


MCI_RECORD_INSERT
MCI_RECORD_INSERT  0x00000100L  mmsystem.h

Indicates that newly recorded information should be inserted or pasted into the existing data. (Some devices may not support this.) If supported, this is the default. See MCI_RECORD.


FN_MCI_RECORD_INSERT
MCI_RECORD_INSERT  0x00000100L  mmsystem.h


MCI_RECORD_OVERWRITE
MCI_RECORD_OVERWRITE  0x00000200L  mmsystem.h

Specifies that data should overwrite existing data. MCIWAVE returns MCIERR_UNSUPPORTED_FUNCTION in response to this flag. See MCI_RECORD.


FN_MCI_RECORD_OVERWRITE
MCI_RECORD_OVERWRITE  0x00000200L  mmsystem.h


MCI_SAVE_FILE
MCI_SAVE_FILE  0x00000100L  mmsystem.h

Indicates the lpfilename member of the data structure identified by lpSave contains a pointer to a buffer containing the destination file name. See MCI_SAVE.


FN_MCI_SAVE_FILE
MCI_SAVE_FILE  0x00000100L  mmsystem.h


MCI_SEEK_TO_END
MCI_SEEK_TO_END  0x00000200L  mmsystem.h

Specifies to seek to the end of the media. See MCI_SEEK.


FN_MCI_SEEK_TO_END
MCI_SEEK_TO_END  0x00000200L  mmsystem.h


MCI_SEEK_TO_START
MCI_SEEK_TO_START  0x00000100L  mmsystem.h

Specifies to seek to the start of the media. See MCI_SEEK.


FN_MCI_SEEK_TO_START
MCI_SEEK_TO_START  0x00000100L  mmsystem.h


MCI_SEQ_FILE
MCI_SEQ_FILE  0x4002  mmsystem.h

Sets the sequencer to receive synchronization data contained in the MIDI file. See MCI_SET.


FN_MCI_SEQ_FILE
MCI_SEQ_FILE  0x4002  mmsystem.h


MCI_SEQ_FORMAT_SONGPTR
MCI_SEQ_FORMAT_SONGPTR  0x4001  mmsystem.h

Sets the time format to song-pointer units. See MCI_SET.


FN_MCI_SEQ_FORMAT_SONGPTR
MCI_SEQ_FORMAT_SONGPTR  0x4001  mmsystem.h


MCI_SEQ_MIDI
MCI_SEQ_MIDI  0x4003  mmsystem.h

The sequencer will send MIDI format synchronization data. See MCI_SET.


FN_MCI_SEQ_MIDI
MCI_SEQ_MIDI  0x4003  mmsystem.h


MCI_SEQ_NONE
MCI_SEQ_NONE  65533  mmsystem.h

The sequencer will not send synchronization data. See MCI_SET.


FN_MCI_SEQ_NONE
MCI_SEQ_NONE  65533  mmsystem.h


MCI_SEQ_SET_MASTER
MCI_SEQ_SET_MASTER  0x00080000L  mmsystem.h

Sets the sequencer as a source of synchronization data and indicates that the type of synchronization is specified in the dwMaster member of the data structure identified by lpSet. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION. The following constants are defined for the synchronization type: See MCI_SET.


FN_MCI_SEQ_SET_MASTER
MCI_SEQ_SET_MASTER  0x00080000L  mmsystem.h


MCI_SEQ_SET_OFFSET
MCI_SEQ_SET_OFFSET  0x01000000L  mmsystem.h

Changes the SMPTE offset of a sequence to that specified by the dwOffset member of the data structure identified by lpSet. This only affects sequences with a SMPTE division type. See MCI_SET.


FN_MCI_SEQ_SET_OFFSET
MCI_SEQ_SET_OFFSET  0x01000000L  mmsystem.h


MCI_SEQ_SET_PORT
MCI_SEQ_SET_PORT  0x00020000L  mmsystem.h

Sets the output MIDI port of a sequence to that specified by the MIDI device ID in the dwPort member of the data structure identified by lpSet. The device will close the previous port (if any), and attempt to open and use the new port. If it fails, it will return an error and re-open the previously used port (if any). The following constants are defined for the ports: See MCI_SET.


FN_MCI_SEQ_SET_PORT
MCI_SEQ_SET_PORT  0x00020000L  mmsystem.h


MCI_SEQ_SET_SLAVE
MCI_SEQ_SET_SLAVE  0x00040000L  mmsystem.h

Sets the sequencer to receive synchronization data and indicates that the type of synchronization is specified in the dwSlave member of the data structure identified by lpSet. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION. The following constants are defined for the synchronization type: See MCI_SET.


FN_MCI_SEQ_SET_SLAVE
MCI_SEQ_SET_SLAVE  0x00040000L  mmsystem.h


MCI_SEQ_SET_TEMPO
MCI_SEQ_SET_TEMPO  0x00010000L  mmsystem.h

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. See MCI_SET.


FN_MCI_SEQ_SET_TEMPO
MCI_SEQ_SET_TEMPO  0x00010000L  mmsystem.h


MCI_SEQ_SMPTE
MCI_SEQ_SMPTE  0x4004  mmsystem.h

The sequencer will send SMPTE format synchronization data. See MCI_SET.


FN_MCI_SEQ_SMPTE
MCI_SEQ_SMPTE  0x4004  mmsystem.h


MCI_SEQ_STATUS_DIVTYPE
MCI_SEQ_STATUS_DIVTYPE  0x0000400AL  mmsystem.h

The dwReturn member is set to one of the following values indicating the current division type of a sequence: See MCI_STATUS.


FN_MCI_SEQ_STATUS_DIVTYPE
MCI_SEQ_STATUS_DIVTYPE  0x0000400AL  mmsystem.h


MCI_SEQ_STATUS_MASTER
MCI_SEQ_STATUS_MASTER  0x00004008L  mmsystem.h

The dwReturn member is set to the synchronization type used for master operation. See MCI_STATUS.


FN_MCI_SEQ_STATUS_MASTER
MCI_SEQ_STATUS_MASTER  0x00004008L  mmsystem.h


MCI_SEQ_STATUS_OFFSET
MCI_SEQ_STATUS_OFFSET  0x00004009L  mmsystem.h

The dwReturn member is set to the current SMPTE offset of a sequence. See MCI_STATUS.


FN_MCI_SEQ_STATUS_OFFSET
MCI_SEQ_STATUS_OFFSET  0x00004009L  mmsystem.h


MCI_SEQ_STATUS_PORT
MCI_SEQ_STATUS_PORT  0x00004003L  mmsystem.h

The dwReturn member is set to the MIDI device ID for the current port used by the sequence. See MCI_STATUS.


FN_MCI_SEQ_STATUS_PORT
MCI_SEQ_STATUS_PORT  0x00004003L  mmsystem.h


MCI_SEQ_STATUS_SLAVE
MCI_SEQ_STATUS_SLAVE  0x00004007L  mmsystem.h

The dwReturn member is set to the synchronization type used for slave operation. See MCI_STATUS.


FN_MCI_SEQ_STATUS_SLAVE
MCI_SEQ_STATUS_SLAVE  0x00004007L  mmsystem.h


MCI_SEQ_STATUS_TEMPO
MCI_SEQ_STATUS_TEMPO  0x00004002L  mmsystem.h

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. See MCI_STATUS.


FN_MCI_SEQ_STATUS_TEMPO
MCI_SEQ_STATUS_TEMPO  0x00004002L  mmsystem.h


MCI_SET_AUDIO
MCI_SET_AUDIO  0x00000800L  mmsystem.h

Specifies an audio channel number is included in the dwAudio member of the data 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: See MCI_SET.


FN_MCI_SET_AUDIO
MCI_SET_AUDIO  0x00000800L  mmsystem.h


MCI_SET_AUDIO_ALL
MCI_SET_AUDIO_ALL  0x00004001L  mmsystem.h

Specifies all audio channels. See MCI_SET.


FN_MCI_SET_AUDIO_ALL
MCI_SET_AUDIO_ALL  0x00004001L  mmsystem.h


MCI_SET_AUDIO_LEFT
MCI_SET_AUDIO_LEFT  0x00004002L  mmsystem.h

Specifies the left channel. See MCI_SET.


FN_MCI_SET_AUDIO_LEFT
MCI_SET_AUDIO_LEFT  0x00004002L  mmsystem.h


MCI_SET_AUDIO_RIGHT
MCI_SET_AUDIO_RIGHT  0x00004003L  mmsystem.h

Specifies the right channel. See MCI_SET.


FN_MCI_SET_AUDIO_RIGHT
MCI_SET_AUDIO_RIGHT  0x00004003L  mmsystem.h


MCI_SET_DOOR_CLOSED
MCI_SET_DOOR_CLOSED  0x00000200L  mmsystem.h

Instructs the device to close the media cover (if any). See MCI_SET.


FN_MCI_SET_DOOR_CLOSED
MCI_SET_DOOR_CLOSED  0x00000200L  mmsystem.h


MCI_SET_DOOR_OPEN
MCI_SET_DOOR_OPEN  0x00000100L  mmsystem.h

Instructs the device to open the media cover (if any). See MCI_SET.


FN_MCI_SET_DOOR_OPEN
MCI_SET_DOOR_OPEN  0x00000100L  mmsystem.h


MCI_SET_OFF
MCI_SET_OFF  0x00004000L  mmsystem.h

Disables the specified video or audio channel. See MCI_SET.


FN_MCI_SET_OFF
MCI_SET_OFF  0x00004000L  mmsystem.h


MCI_SET_ON
MCI_SET_ON  0x00002000L  mmsystem.h

Enables the specified video or audio channel. See MCI_SET.


FN_MCI_SET_ON
MCI_SET_ON  0x00002000L  mmsystem.h


MCI_SET_TIME_FORMAT
MCI_SET_TIME_FORMAT  0x00000400L  mmsystem.h

Specifies a time format parameter that is used with the dwTimeFormat members of MCI_SET_PARMS and MCI_SEQ_SET_PARMS data structures. Possible values, depending upon the usage context, include MCI_FORMAT_BYTES, MCI_FORMAT_CHAPTERS, MCI_FORMAT_FRAMES, MCI_FORMAT_HMS, MCI_FORMAT_MILLISECONDS, MCI_FORMAT_MSF, MCI_FORMAT_SAMPLES, MCI_FORMAT_SMPTE_24, MCI_FORMAT_SMPTE_25, MCI_FORMAT_SMPTE_30, MCI_FORMAT_SMPTE_30DROP, MCI_SEQ_FORMAT_SONGPTR,  MCI_FORMAT_TMSF, and MCI_VD_FORMAT_TRACK. See MCI_SET, MCI_SET_PARMS, MCI_SEQ_SET_PARMS.


FN_MCI_SET_TIME_FORMAT
MCI_SET_TIME_FORMAT  0x00000400L  mmsystem.h


MCI_SET_VIDEO
MCI_SET_VIDEO  0x00001000L  mmsystem.h

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. See MCI_SET.


FN_MCI_SET_VIDEO
MCI_SET_VIDEO  0x00001000L  mmsystem.h


MCI_SOUND_NAME
MCI_SOUND_NAME  0x00000100L  mmsystem.h

Indicates that the name of a sound to play is included in the lpstrSoundName of the data structure identified by lpSound. If omitted, the default sound is played. See MCI_SOUND.


FN_MCI_SOUND_NAME
MCI_SOUND_NAME  0x00000100L  mmsystem.h


MCI_STATUS_CURRENT_TRACK
MCI_STATUS_CURRENT_TRACK  0x00000008L  mmsystem.h

The dwReturn member is set to the current track number. MCI uses continuous track numbers. See MCI_STATUS.


FN_MCI_STATUS_CURRENT_TRACK
MCI_STATUS_CURRENT_TRACK  0x00000008L  mmsystem.h


MCI_STATUS_ITEM
MCI_STATUS_ITEM  0x00000100L  mmsystem.h

Specifies that the dwItem member of the data 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 data structure: See MCI_STATUS.


FN_MCI_STATUS_ITEM
MCI_STATUS_ITEM  0x00000100L  mmsystem.h


MCI_STATUS_LENGTH
MCI_STATUS_LENGTH  0x00000001L  mmsystem.h

The dwReturn member is set to the total media length. See MCI_STATUS.


FN_MCI_STATUS_LENGTH
MCI_STATUS_LENGTH  0x00000001L  mmsystem.h


MCI_STATUS_MEDIA_PRESENT
MCI_STATUS_MEDIA_PRESENT  0x00000005L  mmsystem.h

The dwReturn member is set to TRUE if the media is inserted in the device; otherwise, it is set to FALSE. See MCI_STATUS.


FN_MCI_STATUS_MEDIA_PRESENT
MCI_STATUS_MEDIA_PRESENT  0x00000005L  mmsystem.h


MCI_STATUS_MODE
MCI_STATUS_MODE  0x00000004L  mmsystem.h

The dwReturn member is set to the current mode of the device. All devices can return the following constants to indicate the current mode: See MCI_STATUS.


FN_MCI_STATUS_MODE
MCI_STATUS_MODE  0x00000004L  mmsystem.h


MCI_STATUS_NUMBER_OF_TRACKS
MCI_STATUS_NUMBER_OF_TRACKS  0x00000003L  mmsystem.h

The dwReturn member is set to the total number of playable tracks. See MCI_STATUS.


FN_MCI_STATUS_NUMBER_OF_TRACKS
MCI_STATUS_NUMBER_OF_TRACKS  0x00000003L  mmsystem.h


MCI_STATUS_POSITION
MCI_STATUS_POSITION  0x00000002L  mmsystem.h

The dwReturn member is set to the current position. See MCI_STATUS.


FN_MCI_STATUS_POSITION
MCI_STATUS_POSITION  0x00000002L  mmsystem.h


MCI_STATUS_READY
MCI_STATUS_READY  0x00000007L  mmsystem.h

The dwReturn member is set to TRUE if the device is ready; otherwise, it is set to FALSE. See MCI_STATUS.


FN_MCI_STATUS_READY
MCI_STATUS_READY  0x00000007L  mmsystem.h


MCI_STATUS_START
MCI_STATUS_START  0x00000200L  mmsystem.h

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 data structure identified by lpStatus to MCI_STATUS_POSITION. See MCI_STATUS.


FN_MCI_STATUS_START
MCI_STATUS_START  0x00000200L  mmsystem.h


MCI_STATUS_TIME_FORMAT
MCI_STATUS_TIME_FORMAT  0x00000006L  mmsystem.h

The dwReturn member is set to the current time format of the device. The time formats include: See MCI_STATUS.


FN_MCI_STATUS_TIME_FORMAT
MCI_STATUS_TIME_FORMAT  0x00000006L  mmsystem.h


MCI_SYSINFO_INSTALLNAME
MCI_SYSINFO_INSTALLNAME  0x00000800L  mmsystem.h

Obtains the name (listed in the registry) used to install the device. See MCI_SYSINFO.


FN_MCI_SYSINFO_INSTALLNAME
MCI_SYSINFO_INSTALLNAME  0x00000800L  mmsystem.h


MCI_SYSINFO_NAME
MCI_SYSINFO_NAME  0x00000400L  mmsystem.h

Obtains a device name corresponding to the device number specified in the dwNumbermember of the data structure identified by lpSysInfo . If the MCI_SYSINFO_OPEN flag is set, MCI returns the names of open devices. See MCI_SYSINFO.


FN_MCI_SYSINFO_NAME
MCI_SYSINFO_NAME  0x00000400L  mmsystem.h


MCI_SYSINFO_OPEN
MCI_SYSINFO_OPEN  0x00000200L  mmsystem.h

Obtains the quantity or name of open devices. See MCI_SYSINFO.


FN_MCI_SYSINFO_OPEN
MCI_SYSINFO_OPEN  0x00000200L  mmsystem.h


MCI_SYSINFO_QUANTITY
MCI_SYSINFO_QUANTITY  0x00000100L  mmsystem.h

Obtains the number of devices of the specified type that are listed in the [mci] section of the registry file. If the MCI_SYSINFO_OPEN flag is set, the number of open devices is returned. See MCI_SYSINFO.


FN_MCI_SYSINFO_QUANTITY
MCI_SYSINFO_QUANTITY  0x00000100L  mmsystem.h


MCI_TO
MCI_TO  0x00000008L  mmsystem.h

Specifies that an ending position is included in the dwTo member of the data structure identified by lpDelete. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. MCI_TO Specifies that an ending position is included in the dwTo member of the data structure identified by lpPlay. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_TO is not specified, the end position defaults to the end of the media. MCI_TO Specifies that an ending position is included in the dwTo member of the data structure identified by lpRecord. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_TO is not specified, the ending position defaults to the end of the media. MCI_TO Specifies a position is included in the dwTo member of the MCI_SEEK_PARMS data structure. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. Do not use this flag with MCI_SEEK_END or MCI_SEEK_START. See MCI_DELETE, MCI_PLAY, MCI_RECORD, MCI_SEEK.


FN_MCI_TO
MCI_TO  0x00000008L  mmsystem.h


MCI_TRACK
MCI_TRACK  0x00000010L  mmsystem.h

Indicates a status track parameter is included in the dwTrack member of the data 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. See MCI_STATUS.


FN_MCI_TRACK
MCI_TRACK  0x00000010L  mmsystem.h


MCI_VD_FORMAT_TRACK
MCI_VD_FORMAT_TRACK  0x4001  mmsystem.h

Changes the time format to tracks. MCI uses continuous track numbers. See MCI_SET.


FN_MCI_VD_FORMAT_TRACK
MCI_VD_FORMAT_TRACK  0x4001  mmsystem.h


MCI_VD_GETDEVCAPS_CAN_REVERSE
MCI_VD_GETDEVCAPS_CAN_REVERSE  0x00004002L  mmsystem.h

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. See MCI_GETDEVCAPS.


FN_MCI_VD_GETDEVCAPS_CAN_REVERSE
MCI_VD_GETDEVCAPS_CAN_REVERSE  0x00004002L  mmsystem.h


MCI_VD_GETDEVCAPS_CAV
MCI_VD_GETDEVCAPS_CAV  0x00020000L  mmsystem.h

Indicates the information requested applies to CAV format discs. By default, the capabilities apply to the current disc. See MCI_GETDEVCAPS.


FN_MCI_VD_GETDEVCAPS_CAV
MCI_VD_GETDEVCAPS_CAV  0x00020000L  mmsystem.h


MCI_VD_GETDEVCAPS_CLV
MCI_VD_GETDEVCAPS_CLV  0x00010000L  mmsystem.h

Indicates the information requested applies to CLV format discs. By default, the capabilities apply to the current disc. See MCI_GETDEVCAPS.


FN_MCI_VD_GETDEVCAPS_CLV
MCI_VD_GETDEVCAPS_CLV  0x00010000L  mmsystem.h


MCI_VD_GETDEVCAPS_FAST_RATE
MCI_VD_GETDEVCAPS_FAST_RATE  0x00004003L  mmsystem.h

The dwReturn member is set to the standard fast play rate in frames per second. See MCI_GETDEVCAPS.


FN_MCI_VD_GETDEVCAPS_FAST_RATE
MCI_VD_GETDEVCAPS_FAST_RATE  0x00004003L  mmsystem.h


MCI_VD_GETDEVCAPS_NORMAL_RATE
MCI_VD_GETDEVCAPS_NORMAL_RATE  0x00004005L  mmsystem.h

The dwReturn member is set to the normal play rate in frames per second. See MCI_GETDEVCAPS.


FN_MCI_VD_GETDEVCAPS_NORMAL_RATE
MCI_VD_GETDEVCAPS_NORMAL_RATE  0x00004005L  mmsystem.h


MCI_VD_GETDEVCAPS_SLOW_RATE
MCI_VD_GETDEVCAPS_SLOW_RATE  0x00004004L  mmsystem.h

The dwReturn member is set to the standard slow play rate in frames per second. See MCI_GETDEVCAPS.


FN_MCI_VD_GETDEVCAPS_SLOW_RATE
MCI_VD_GETDEVCAPS_SLOW_RATE  0x00004004L  mmsystem.h


MCI_VD_PLAY_FAST
MCI_VD_PLAY_FAST  0x00020000L  mmsystem.h

Specifies to play fast. See MCI_PLAY.


FN_MCI_VD_PLAY_FAST
MCI_VD_PLAY_FAST  0x00020000L  mmsystem.h


MCI_VD_PLAY_REVERSE
MCI_VD_PLAY_REVERSE  0x00010000L  mmsystem.h

Specifies to play in reverse. See MCI_PLAY.


FN_MCI_VD_PLAY_REVERSE
MCI_VD_PLAY_REVERSE  0x00010000L  mmsystem.h


MCI_VD_PLAY_SCAN
MCI_VD_PLAY_SCAN  0x00080000L  mmsystem.h

Specifies to scan quickly. See MCI_PLAY.


FN_MCI_VD_PLAY_SCAN
MCI_VD_PLAY_SCAN  0x00080000L  mmsystem.h


MCI_VD_PLAY_SLOW
MCI_VD_PLAY_SLOW  0x00100000L  mmsystem.h

Specifies to play slowly. See MCI_PLAY.


FN_MCI_VD_PLAY_SLOW
MCI_VD_PLAY_SLOW  0x00100000L  mmsystem.h


MCI_VD_PLAY_SPEED
MCI_VD_PLAY_SPEED  0x00040000L  mmsystem.h

Specifies that the play speed is included in the dwSpeed member in the data structure identified by lpPlay. See MCI_PLAY.


FN_MCI_VD_PLAY_SPEED
MCI_VD_PLAY_SPEED  0x00040000L  mmsystem.h


MCI_VD_SEEK_REVERSE
MCI_VD_SEEK_REVERSE  0x00010000L  mmsystem.h

Specifies to seek backward. See MCI_SEEK.


FN_MCI_VD_SEEK_REVERSE
MCI_VD_SEEK_REVERSE  0x00010000L  mmsystem.h


MCI_VD_STATUS_DISC_SIZE
MCI_VD_STATUS_DISC_SIZE  0x00004006L  mmsystem.h

The dwReturn member is set to the size of the loaded disc in inches (8 or 12). See MCI_STATUS.


FN_MCI_VD_STATUS_DISC_SIZE
MCI_VD_STATUS_DISC_SIZE  0x00004006L  mmsystem.h


MCI_VD_STATUS_FORWARD
MCI_VD_STATUS_FORWARD  0x00004003L  mmsystem.h

The dwReturn member is set to TRUE if playing forward; otherwise, it is set to FALSE. See MCI_STATUS.


FN_MCI_VD_STATUS_FORWARD
MCI_VD_STATUS_FORWARD  0x00004003L  mmsystem.h


MCI_VD_STATUS_MEDIA_TYPE
MCI_VD_STATUS_MEDIA_TYPE  0x00004004L  mmsystem.h

The dwReturn member is set to the media type of the inserted media. The following media types can be returned: See MCI_STATUS.


FN_MCI_VD_STATUS_MEDIA_TYPE
MCI_VD_STATUS_MEDIA_TYPE  0x00004004L  mmsystem.h


MCI_VD_STATUS_SIDE
MCI_VD_STATUS_SIDE  0x00004005L  mmsystem.h

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. See MCI_STATUS.


FN_MCI_VD_STATUS_SIDE
MCI_VD_STATUS_SIDE  0x00004005L  mmsystem.h


MCI_VD_STATUS_SPEED
MCI_VD_STATUS_SPEED  0x00004002L  mmsystem.h

The dwReturn member is set to the play speed in frames per second. MCIPIONR returns MCIERR_UNSUPPORTED_FUNCTION. See MCI_STATUS.


FN_MCI_VD_STATUS_SPEED
MCI_VD_STATUS_SPEED  0x00004002L  mmsystem.h


MCI_VD_STEP_FRAMES
MCI_VD_STEP_FRAMES  0x00010000L  mmsystem.h

Indicates that the dwFrames member of the data structure identified by lpStep specifies the number of frames to step. See MCI_STEP.


FN_MCI_VD_STEP_FRAMES
MCI_VD_STEP_FRAMES  0x00010000L  mmsystem.h


MCI_VD_STEP_REVERSE
MCI_VD_STEP_REVERSE  0x00020000L  mmsystem.h

Steps in reverse. See MCI_STEP.


FN_MCI_VD_STEP_REVERSE
MCI_VD_STEP_REVERSE  0x00020000L  mmsystem.h


MCI_WAIT
MCI_WAIT  0x00000002L  mmsystem.h

Specifies that the operation should finish before MCI returns control to the application. See MCI_BREAK, MCI_CLOSE, MCI_COPY, MCI_CUE, MCI_CUT, MCI_DELETE, MCI_FREEZE, MCI_GETDEVCAPS, MCI_INFO, MCI_LOAD, MCI_OPEN, MCI_PASTE, MCI_PAUSE, MCI_PLAY, MCI_PUT, MCI_RECORD, MCI_RESUME, MCI_SAVE, MCI_SEEK, MCI_SET, MCI_SOUND, MCI_STATUS, MCI_STEP, MCI_STOP, MCI_UNFREEZE, MCI_WHERE, MCI_WINDOW.


FN_MCI_WAIT
MCI_WAIT  0x00000002L  mmsystem.h


MCI_WAVE_GETDEVCAPS_INPUT

The dwReturn member is set to the total number of waveform input (recording) devices. See MCI_GETDEVCAPS.


MCI_WAVE_GETDEVCAPS_OUTPUT

The dwReturn member is set to the total number of waveform output (playback) devices. See MCI_GETDEVCAPS.


MCI_WAVE_INPUT
MCI_WAVE_INPUT  0x00400000L  mmsystem.h

Specifies that a wave input device should be cued. See MCI_CUE, MCI_INFO, MCI_SET, MCI_STATUS.


FN_MCI_WAVE_INPUT
MCI_WAVE_INPUT  0x00400000L  mmsystem.h


MCI_WAVE_OPEN_BUFFER
MCI_WAVE_OPEN_BUFFER  0x00010000L  mmsystem.h

Indicates a buffer length is specified in the dwBuffer member of the data structure identified by lpOpen. See MCI_OPEN.


FN_MCI_WAVE_OPEN_BUFFER
MCI_WAVE_OPEN_BUFFER  0x00010000L  mmsystem.h


MCI_WAVE_OUTPUT
MCI_WAVE_OUTPUT  0x00800000L  mmsystem.h

Specifies that a wave output device should be cued. This is the default flag if a flag is not specified. See MCI_CUE, MCI_INFO, MCI_SET, MCI_STATUS.


FN_MCI_WAVE_OUTPUT
MCI_WAVE_OUTPUT  0x00800000L  mmsystem.h


MCI_WAVE_SET_ANYINPUT
MCI_WAVE_SET_ANYINPUT  0x04000000L  mmsystem.h

Specifies that any wave input compatible with the current format can be used for recording. See MCI_SET.


FN_MCI_WAVE_SET_ANYINPUT
MCI_WAVE_SET_ANYINPUT  0x04000000L  mmsystem.h


MCI_WAVE_SET_ANYOUTPUT
MCI_WAVE_SET_ANYOUTPUT  0x08000000L  mmsystem.h

Specifies that any wave output compatible with the current format can be used for playing. See MCI_SET.


FN_MCI_WAVE_SET_ANYOUTPUT
MCI_WAVE_SET_ANYOUTPUT  0x08000000L  mmsystem.h


MCI_WAVE_SET_AVGBYTESPERSEC
MCI_WAVE_SET_AVGBYTESPERSEC  0x00080000L  mmsystem.h

Sets the bytes per second used for playing, recording, and saving to the nAvgBytesPerSec member of the data structure identified by lpSet. See MCI_SET.


FN_MCI_WAVE_SET_AVGBYTESPERSEC
MCI_WAVE_SET_AVGBYTESPERSEC  0x00080000L  mmsystem.h


MCI_WAVE_SET_BITSPERSAMPLE
MCI_WAVE_SET_BITSPERSAMPLE  0x00200000L  mmsystem.h

Sets the bits per sample used for playing, recording, and saving to the nBitsPerSample member of the data structure identified by lpSet. See MCI_SET.


FN_MCI_WAVE_SET_BITSPERSAMPLE
MCI_WAVE_SET_BITSPERSAMPLE  0x00200000L  mmsystem.h


MCI_WAVE_SET_BLOCKALIGN
MCI_WAVE_SET_BLOCKALIGN  0x00100000L  mmsystem.h

Sets the block alignment used for playing, recording, and saving to the nBlockAlign member of the data structure identified by lpSet. See MCI_SET.


FN_MCI_WAVE_SET_BLOCKALIGN
MCI_WAVE_SET_BLOCKALIGN  0x00100000L  mmsystem.h


MCI_WAVE_SET_CHANNELS
MCI_WAVE_SET_CHANNELS  0x00020000L  mmsystem.h

Specifies the number of channels is indicated in the nChannels member of the data structure identified by lpSet. See MCI_SET.


FN_MCI_WAVE_SET_CHANNELS
MCI_WAVE_SET_CHANNELS  0x00020000L  mmsystem.h


MCI_WAVE_SET_FORMATTAG
MCI_WAVE_SET_FORMATTAG  0x00010000L  mmsystem.h

Sets the format type used for playing, recording, and saving to the wFormatTag member of the data structure identified by lpSet. Specifying WAVE_FORMAT_PCM changes the format to PCM. See MCI_SET.


FN_MCI_WAVE_SET_FORMATTAG
MCI_WAVE_SET_FORMATTAG  0x00010000L  mmsystem.h


MCI_WAVE_SET_SAMPLESPERSEC
MCI_WAVE_SET_SAMPLESPERSEC  0x00040000L  mmsystem.h

Sets the samples per second used for playing, recording, and saving to the nSamplesPerSec member of the data structure identified by lpSet. See MCI_SET.


FN_MCI_WAVE_SET_SAMPLESPERSEC
MCI_WAVE_SET_SAMPLESPERSEC  0x00040000L  mmsystem.h


MCI_WAVE_STATUS_AVGBYTESPERSEC
MCI_WAVE_STATUS_AVGBYTESPERSEC  0x00004004L  mmsystem.h

The dwReturn member is set to the current bytes per second used for playing, recording, and saving. See MCI_STATUS.


FN_MCI_WAVE_STATUS_AVGBYTESPERSEC
MCI_WAVE_STATUS_AVGBYTESPERSEC  0x00004004L  mmsystem.h


MCI_WAVE_STATUS_BITSPERSAMPLE
MCI_WAVE_STATUS_BITSPERSAMPLE  0x00004006L  mmsystem.h

The dwReturn member is set to the current bits per sample used for playing, recording, and saving. See MCI_STATUS.


FN_MCI_WAVE_STATUS_BITSPERSAMPLE
MCI_WAVE_STATUS_BITSPERSAMPLE  0x00004006L  mmsystem.h


MCI_WAVE_STATUS_BLOCKALIGN
MCI_WAVE_STATUS_BLOCKALIGN  0x00004005L  mmsystem.h

The dwReturn member is set to the current block alignment used for playing, recording, and saving. See MCI_STATUS.


FN_MCI_WAVE_STATUS_BLOCKALIGN
MCI_WAVE_STATUS_BLOCKALIGN  0x00004005L  mmsystem.h


MCI_WAVE_STATUS_CHANNELS
MCI_WAVE_STATUS_CHANNELS  0x00004002L  mmsystem.h

The dwReturn member is set to the current channel count used for playing, recording, and saving. See MCI_STATUS.


FN_MCI_WAVE_STATUS_CHANNELS
MCI_WAVE_STATUS_CHANNELS  0x00004002L  mmsystem.h


MCI_WAVE_STATUS_FORMATTAG
MCI_WAVE_STATUS_FORMATTAG  0x00004001L  mmsystem.h

The dwReturn member is set to the current format tag used for playing, recording, and saving. See MCI_STATUS.


FN_MCI_WAVE_STATUS_FORMATTAG
MCI_WAVE_STATUS_FORMATTAG  0x00004001L  mmsystem.h


MCI_WAVE_STATUS_LEVEL
MCI_WAVE_STATUS_LEVEL  0x00004007L  mmsystem.h

The dwReturn member is set to the current record or playback level. 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. See MCI_STATUS.


FN_MCI_WAVE_STATUS_LEVEL
MCI_WAVE_STATUS_LEVEL  0x00004007L  mmsystem.h


MCI_WAVE_STATUS_SAMPLESPERSEC
MCI_WAVE_STATUS_SAMPLESPERSEC  0x00004003L  mmsystem.h

The dwReturn member is set to the current samples per second used for playing, recording, and saving. See MCI_STATUS.


FN_MCI_WAVE_STATUS_SAMPLESPERSEC
MCI_WAVE_STATUS_SAMPLESPERSEC  0x00004003L  mmsystem.h


MCIERR_BAD_CONSTANT
MCIERR_BAD_CONSTANT  (MCIERR_BASE + 34)  mmsystem.h

Unknown value for parameter. See mciSendString.


FN_MCIERR_BAD_CONSTANT
MCIERR_BAD_CONSTANT  (MCIERR_BASE + 34)  mmsystem.h


MCIERR_BAD_INTEGER
MCIERR_BAD_INTEGER  (MCIERR_BASE + 14)  mmsystem.h

Invalid or missing integer in command. See mciSendString.


FN_MCIERR_BAD_INTEGER
MCIERR_BAD_INTEGER  (MCIERR_BASE + 14)  mmsystem.h


MCIERR_BAD_TIME_FORMAT
MCIERR_BAD_TIME_FORMAT  (MCIERR_BASE + 37)  mmsystem.h

Illegal value for time format. See mciSendCommand.


FN_MCIERR_BAD_TIME_FORMAT
MCIERR_BAD_TIME_FORMAT  (MCIERR_BASE + 37)  mmsystem.h


MCIERR_CANNOT_LOAD_DRIVER
MCIERR_CANNOT_LOAD_DRIVER  (MCIERR_BASE + 10)  mmsystem.h

Error loading media device driver. See MCI_OPEN.


FN_MCIERR_CANNOT_LOAD_DRIVER
MCIERR_CANNOT_LOAD_DRIVER  (MCIERR_BASE + 10)  mmsystem.h


MCIERR_CANNOT_USE_ALL
MCIERR_CANNOT_USE_ALL  (MCIERR_BASE + 23)  mmsystem.h

The device name "all" is not allowed for this command. See mciSendCommand.


FN_MCIERR_CANNOT_USE_ALL
MCIERR_CANNOT_USE_ALL  (MCIERR_BASE + 23)  mmsystem.h


MCIERR_CREATEWINDOW
MCIERR_CREATEWINDOW  (MCIERR_BASE + 91)  mmsystem.h

Could not create or use window. See mciSendCommand.


FN_MCIERR_CREATEWINDOW
MCIERR_CREATEWINDOW  (MCIERR_BASE + 91)  mmsystem.h


MCIERR_DEVICE_LOCKED
MCIERR_DEVICE_LOCKED  (MCIERR_BASE + 32)  mmsystem.h

The device is locked until it is closed automatically. See mciSendCommand.


FN_MCIERR_DEVICE_LOCKED
MCIERR_DEVICE_LOCKED  (MCIERR_BASE + 32)  mmsystem.h


MCIERR_DEVICE_NOT_READY
MCIERR_DEVICE_NOT_READY  (MCIERR_BASE + 20)  mmsystem.h

Device not ready. See mciSendCommand.


FN_MCIERR_DEVICE_NOT_READY
MCIERR_DEVICE_NOT_READY  (MCIERR_BASE + 20)  mmsystem.h


MCIERR_DEVICE_OPEN
MCIERR_DEVICE_OPEN  (MCIERR_BASE + 9)  mmsystem.h

The device name is in use by this task. Use a unique alias. See MCI_OPEN.


FN_MCIERR_DEVICE_OPEN
MCIERR_DEVICE_OPEN  (MCIERR_BASE + 9)  mmsystem.h


MCIERR_DEVICE_TYPE_REQUIRED
MCIERR_DEVICE_TYPE_REQUIRED  (MCIERR_BASE + 31)  mmsystem.h

The device name must be a valid device type. See mciSendCommand.


FN_MCIERR_DEVICE_TYPE_REQUIRED
MCIERR_DEVICE_TYPE_REQUIRED  (MCIERR_BASE + 31)  mmsystem.h


MCIERR_DRIVER
MCIERR_DRIVER  (MCIERR_BASE + 22)  mmsystem.h

Unspecified device error. See mciSendCommand.


FN_MCIERR_DRIVER
MCIERR_DRIVER  (MCIERR_BASE + 22)  mmsystem.h


MCIERR_DRIVER_INTERNAL
MCIERR_DRIVER_INTERNAL  (MCIERR_BASE + 16)  mmsystem.h

Internal driver error. See mciSendCommand.


FN_MCIERR_DRIVER_INTERNAL
MCIERR_DRIVER_INTERNAL  (MCIERR_BASE + 16)  mmsystem.h


MCIERR_DUPLICATE_ALIAS
MCIERR_DUPLICATE_ALIAS  (MCIERR_BASE + 33)  mmsystem.h

The specified alias is an open device in this task. See MCI_OPEN.


FN_MCIERR_DUPLICATE_ALIAS
MCIERR_DUPLICATE_ALIAS  (MCIERR_BASE + 33)  mmsystem.h


MCIERR_DUPLICATE_FLAGS
MCIERR_DUPLICATE_FLAGS  (MCIERR_BASE + 39)  mmsystem.h

A flag or value was specified twice. See mciSendString.


FN_MCIERR_DUPLICATE_FLAGS
MCIERR_DUPLICATE_FLAGS  (MCIERR_BASE + 39)  mmsystem.h


MCIERR_EXTENSION_NOT_FOUND
MCIERR_EXTENSION_NOT_FOUND  (MCIERR_BASE + 25)  mmsystem.h

Cannot deduce a device type from the given extension. See MCI_OPEN.


FN_MCIERR_EXTENSION_NOT_FOUND
MCIERR_EXTENSION_NOT_FOUND  (MCIERR_BASE + 25)  mmsystem.h


MCIERR_FILE_NOT_FOUND
MCIERR_FILE_NOT_FOUND  (MCIERR_BASE + 19)  mmsystem.h

Requested file not found. See mciSendCommand.


FN_MCIERR_FILE_NOT_FOUND
MCIERR_FILE_NOT_FOUND  (MCIERR_BASE + 19)  mmsystem.h


MCIERR_FILE_NOT_SAVED
MCIERR_FILE_NOT_SAVED  (MCIERR_BASE + 30)  mmsystem.h

The file was not saved. See mciSendCommand.


FN_MCIERR_FILE_NOT_SAVED
MCIERR_FILE_NOT_SAVED  (MCIERR_BASE + 30)  mmsystem.h


MCIERR_FILE_READ
MCIERR_FILE_READ  (MCIERR_BASE + 92)  mmsystem.h

A read from the file failed. See mciSendCommand.


FN_MCIERR_FILE_READ
MCIERR_FILE_READ  (MCIERR_BASE + 92)  mmsystem.h


MCIERR_FILE_WRITE
MCIERR_FILE_WRITE  (MCIERR_BASE + 93)  mmsystem.h

A write to the file failed. See mciSendCommand.


FN_MCIERR_FILE_WRITE
MCIERR_FILE_WRITE  (MCIERR_BASE + 93)  mmsystem.h


MCIERR_FILENAME_REQUIRED
MCIERR_FILENAME_REQUIRED  (MCIERR_BASE + 48)  mmsystem.h

A valid filename is required. See MCI_OPEN.


FN_MCIERR_FILENAME_REQUIRED
MCIERR_FILENAME_REQUIRED  (MCIERR_BASE + 48)  mmsystem.h


MCIERR_FLAGS_NOT_COMPATIBLE
MCIERR_FLAGS_NOT_COMPATIBLE  (MCIERR_BASE + 28)  mmsystem.h

Incompatible parameters were specified. See mciSendCommand.


FN_MCIERR_FLAGS_NOT_COMPATIBLE
MCIERR_FLAGS_NOT_COMPATIBLE  (MCIERR_BASE + 28)  mmsystem.h


MCIERR_HARDWARE
MCIERR_HARDWARE  (MCIERR_BASE + 6)  mmsystem.h

Hardware error on media device. See mciSendCommand.


FN_MCIERR_HARDWARE
MCIERR_HARDWARE  (MCIERR_BASE + 6)  mmsystem.h


MCIERR_INTERNAL
MCIERR_INTERNAL  (MCIERR_BASE + 21)  mmsystem.h

Internal error. See mciSendCommand.


FN_MCIERR_INTERNAL
MCIERR_INTERNAL  (MCIERR_BASE + 21)  mmsystem.h


MCIERR_INVALID_DEVICE_ID
MCIERR_INVALID_DEVICE_ID  (MCIERR_BASE + 1)  mmsystem.h

Invalid device ID. See mciSendCommand.


FN_MCIERR_INVALID_DEVICE_ID
MCIERR_INVALID_DEVICE_ID  (MCIERR_BASE + 1)  mmsystem.h


MCIERR_INVALID_DEVICE_NAME
MCIERR_INVALID_DEVICE_NAME  (MCIERR_BASE + 7)  mmsystem.h

The device is not open or is not known. See mciSendCommand.


FN_MCIERR_INVALID_DEVICE_NAME
MCIERR_INVALID_DEVICE_NAME  (MCIERR_BASE + 7)  mmsystem.h


MCIERR_INVALID_FILE
MCIERR_INVALID_FILE  (MCIERR_BASE + 40)  mmsystem.h

Invalid file format. See mciSendCommand.


FN_MCIERR_INVALID_FILE
MCIERR_INVALID_FILE  (MCIERR_BASE + 40)  mmsystem.h


MCIERR_MISSING_COMMAND_STRING
MCIERR_MISSING_COMMAND_STRING  (MCIERR_BASE + 11)  mmsystem.h

No command was specified. See mciSendString.


FN_MCIERR_MISSING_COMMAND_STRING
MCIERR_MISSING_COMMAND_STRING  (MCIERR_BASE + 11)  mmsystem.h


MCIERR_MISSING_DEVICE_NAME
MCIERR_MISSING_DEVICE_NAME  (MCIERR_BASE + 36)  mmsystem.h

No device name was specified. See mciSendString.


FN_MCIERR_MISSING_DEVICE_NAME
MCIERR_MISSING_DEVICE_NAME  (MCIERR_BASE + 36)  mmsystem.h


MCIERR_MISSING_PARAMETER
MCIERR_MISSING_PARAMETER  (MCIERR_BASE + 17)  mmsystem.h

Required parameter is missing. See MCI_OPEN.


FN_MCIERR_MISSING_PARAMETER
MCIERR_MISSING_PARAMETER  (MCIERR_BASE + 17)  mmsystem.h


MCIERR_MISSING_STRING_ARGUMENT
MCIERR_MISSING_STRING_ARGUMENT  (MCIERR_BASE + 13)  mmsystem.h

A string value was missing from the command. See mciSendString.


FN_MCIERR_MISSING_STRING_ARGUMENT
MCIERR_MISSING_STRING_ARGUMENT  (MCIERR_BASE + 13)  mmsystem.h


MCIERR_MULTIPLE
MCIERR_MULTIPLE  (MCIERR_BASE + 24)  mmsystem.h

Errors occurred in more than one device. See mciSendCommand.


FN_MCIERR_MULTIPLE
MCIERR_MULTIPLE  (MCIERR_BASE + 24)  mmsystem.h


MCIERR_MUST_USE_SHAREABLE
MCIERR_MUST_USE_SHAREABLE  (MCIERR_BASE + 35)  mmsystem.h

The device is already open; use the shareable flag with each open. See MCI_OPEN.


FN_MCIERR_MUST_USE_SHAREABLE
MCIERR_MUST_USE_SHAREABLE  (MCIERR_BASE + 35)  mmsystem.h


MCIERR_NEW_REQUIRES_ALIAS
MCIERR_NEW_REQUIRES_ALIAS  (MCIERR_BASE + 43)  mmsystem.h

An alias must be used with the "new" device name. See mciSendString.


FN_MCIERR_NEW_REQUIRES_ALIAS
MCIERR_NEW_REQUIRES_ALIAS  (MCIERR_BASE + 43)  mmsystem.h


MCIERR_NO_CLOSING_QUOTE
MCIERR_NO_CLOSING_QUOTE  (MCIERR_BASE + 38)  mmsystem.h

A closing quotation mark is missing. See mciSendString.


FN_MCIERR_NO_CLOSING_QUOTE
MCIERR_NO_CLOSING_QUOTE  (MCIERR_BASE + 38)  mmsystem.h


MCIERR_NO_ELEMENT_ALLOWED
MCIERR_NO_ELEMENT_ALLOWED  (MCIERR_BASE + 45)  mmsystem.h

An element name cannot be used with this device. See MCI_OPEN.


FN_MCIERR_NO_ELEMENT_ALLOWED
MCIERR_NO_ELEMENT_ALLOWED  (MCIERR_BASE + 45)  mmsystem.h


MCIERR_NO_WINDOW
MCIERR_NO_WINDOW  (MCIERR_BASE + 90)  mmsystem.h

There is no display window. See mciSendCommand.


FN_MCIERR_NO_WINDOW
MCIERR_NO_WINDOW  (MCIERR_BASE + 90)  mmsystem.h


MCIERR_NOTIFY_ON_AUTO_OPEN
MCIERR_NOTIFY_ON_AUTO_OPEN  (MCIERR_BASE + 44)  mmsystem.h

The "notify" flag is illegal with auto-open. See mciSendString.


FN_MCIERR_NOTIFY_ON_AUTO_OPEN
MCIERR_NOTIFY_ON_AUTO_OPEN  (MCIERR_BASE + 44)  mmsystem.h


MCIERR_NULL_PARAMETER_BLOCK
MCIERR_NULL_PARAMETER_BLOCK  (MCIERR_BASE + 41)  mmsystem.h

Parameter block pointer was NULL. See mciSendCommand.


FN_MCIERR_NULL_PARAMETER_BLOCK
MCIERR_NULL_PARAMETER_BLOCK  (MCIERR_BASE + 41)  mmsystem.h


MCIERR_OUT_OF_MEMORY
MCIERR_OUT_OF_MEMORY  (MCIERR_BASE + 8)  mmsystem.h

Not enough memory for requested operation. See mciSendCommand.


FN_MCIERR_OUT_OF_MEMORY
MCIERR_OUT_OF_MEMORY  (MCIERR_BASE + 8)  mmsystem.h


MCIERR_OUTOFRANGE
MCIERR_OUTOFRANGE  (MCIERR_BASE + 26)  mmsystem.h

Parameter value out of range. See mciSendCommand.


FN_MCIERR_OUTOFRANGE
MCIERR_OUTOFRANGE  (MCIERR_BASE + 26)  mmsystem.h


MCIERR_PARAM_OVERFLOW
MCIERR_PARAM_OVERFLOW  (MCIERR_BASE + 12)  mmsystem.h

The output string was not long enough. See mciSendString.


FN_MCIERR_PARAM_OVERFLOW
MCIERR_PARAM_OVERFLOW  (MCIERR_BASE + 12)  mmsystem.h


MCIERR_PARSER_INTERNAL
MCIERR_PARSER_INTERNAL  (MCIERR_BASE + 15)  mmsystem.h

Internal parser error. See mciSendString.


FN_MCIERR_PARSER_INTERNAL
MCIERR_PARSER_INTERNAL  (MCIERR_BASE + 15)  mmsystem.h


MCIERR_SEQ_DIV_INCOMPATIBLE
MCIERR_SEQ_DIV_INCOMPATIBLE  (MCIERR_BASE + 80)  mmsystem.h

Set Song Pointer incompatible with SMPTE files. See mciSendCommand.


FN_MCIERR_SEQ_DIV_INCOMPATIBLE
MCIERR_SEQ_DIV_INCOMPATIBLE  (MCIERR_BASE + 80)  mmsystem.h


MCIERR_SEQ_NOMIDIPRESENT
MCIERR_SEQ_NOMIDIPRESENT  (MCIERR_BASE + 87)  mmsystem.h

No MIDI ports present. See mciSendCommand.


FN_MCIERR_SEQ_NOMIDIPRESENT
MCIERR_SEQ_NOMIDIPRESENT  (MCIERR_BASE + 87)  mmsystem.h


MCIERR_SEQ_PORT_INUSE
MCIERR_SEQ_PORT_INUSE  (MCIERR_BASE + 81)  mmsystem.h

Specified port is in use. See mciSendCommand.


FN_MCIERR_SEQ_PORT_INUSE
MCIERR_SEQ_PORT_INUSE  (MCIERR_BASE + 81)  mmsystem.h


MCIERR_SEQ_PORT_MAPNODEVICE
MCIERR_SEQ_PORT_MAPNODEVICE  (MCIERR_BASE + 83)  mmsystem.h

Current map uses non-existent device. See mciSendCommand.


FN_MCIERR_SEQ_PORT_MAPNODEVICE
MCIERR_SEQ_PORT_MAPNODEVICE  (MCIERR_BASE + 83)  mmsystem.h


MCIERR_SEQ_PORT_MISCERROR
MCIERR_SEQ_PORT_MISCERROR  (MCIERR_BASE + 84)  mmsystem.h

Miscellaneous error with specified port. See mciSendCommand.


FN_MCIERR_SEQ_PORT_MISCERROR
MCIERR_SEQ_PORT_MISCERROR  (MCIERR_BASE + 84)  mmsystem.h


MCIERR_SEQ_PORT_NONEXISTENT
MCIERR_SEQ_PORT_NONEXISTENT  (MCIERR_BASE + 82)  mmsystem.h

Specified port does not exist. See mciSendCommand.


FN_MCIERR_SEQ_PORT_NONEXISTENT
MCIERR_SEQ_PORT_NONEXISTENT  (MCIERR_BASE + 82)  mmsystem.h


MCIERR_SEQ_PORTUNSPECIFIED
MCIERR_SEQ_PORTUNSPECIFIED  (MCIERR_BASE + 86)  mmsystem.h

No current MIDI port. See mciSendCommand.


FN_MCIERR_SEQ_PORTUNSPECIFIED
MCIERR_SEQ_PORTUNSPECIFIED  (MCIERR_BASE + 86)  mmsystem.h


MCIERR_SEQ_TIMER
MCIERR_SEQ_TIMER  (MCIERR_BASE + 85)  mmsystem.h

Timer error. See mciSendCommand.


FN_MCIERR_SEQ_TIMER
MCIERR_SEQ_TIMER  (MCIERR_BASE + 85)  mmsystem.h


MCIERR_UNNAMED_RESOURCE
MCIERR_UNNAMED_RESOURCE  (MCIERR_BASE + 42)  mmsystem.h

Attempt to save unnamed file. See mciSendCommand.


FN_MCIERR_UNNAMED_RESOURCE
MCIERR_UNNAMED_RESOURCE  (MCIERR_BASE + 42)  mmsystem.h


MCIERR_UNRECOGNIZED_COMMAND
MCIERR_UNRECOGNIZED_COMMAND  (MCIERR_BASE + 5)  mmsystem.h

Unknown command. See mciSendCommand.


FN_MCIERR_UNRECOGNIZED_COMMAND
MCIERR_UNRECOGNIZED_COMMAND  (MCIERR_BASE + 5)  mmsystem.h


MCIERR_UNRECOGNIZED_KEYWORD
MCIERR_UNRECOGNIZED_KEYWORD  (MCIERR_BASE + 3)  mmsystem.h

Unknown command parameter. See mciSendString.


FN_MCIERR_UNRECOGNIZED_KEYWORD
MCIERR_UNRECOGNIZED_KEYWORD  (MCIERR_BASE + 3)  mmsystem.h


MCIERR_UNSUPPORTED_FUNCTION
MCIERR_UNSUPPORTED_FUNCTION  (MCIERR_BASE + 18)  mmsystem.h

Action not available for this device. See mciSendCommand.


FN_MCIERR_UNSUPPORTED_FUNCTION
MCIERR_UNSUPPORTED_FUNCTION  (MCIERR_BASE + 18)  mmsystem.h


MCIERR_WAVE_INPUTSINUSE
MCIERR_WAVE_INPUTSINUSE  (MCIERR_BASE + 66)  mmsystem.h

No compatible waveform recording device is free. See mciSendCommand.


FN_MCIERR_WAVE_INPUTSINUSE
MCIERR_WAVE_INPUTSINUSE  (MCIERR_BASE + 66)  mmsystem.h


MCIERR_WAVE_INPUTSUNSUITABLE
MCIERR_WAVE_INPUTSUNSUITABLE  (MCIERR_BASE + 72)  mmsystem.h

No compatible waveform recording devices. See mciSendCommand.


FN_MCIERR_WAVE_INPUTSUNSUITABLE
MCIERR_WAVE_INPUTSUNSUITABLE  (MCIERR_BASE + 72)  mmsystem.h


MCIERR_WAVE_INPUTUNSPECIFIED
MCIERR_WAVE_INPUTUNSPECIFIED  (MCIERR_BASE + 69)  mmsystem.h

Any compatible waveform recording device may be used. See mciSendCommand.


FN_MCIERR_WAVE_INPUTUNSPECIFIED
MCIERR_WAVE_INPUTUNSPECIFIED  (MCIERR_BASE + 69)  mmsystem.h


MCIERR_WAVE_OUTPUTSINUSE
MCIERR_WAVE_OUTPUTSINUSE  (MCIERR_BASE + 64)  mmsystem.h

No compatible waveform playback device is free. See mciSendCommand.


FN_MCIERR_WAVE_OUTPUTSINUSE
MCIERR_WAVE_OUTPUTSINUSE  (MCIERR_BASE + 64)  mmsystem.h


MCIERR_WAVE_OUTPUTSUNSUITABLE
MCIERR_WAVE_OUTPUTSUNSUITABLE  (MCIERR_BASE + 70)  mmsystem.h

No compatible waveform playback devices. See mciSendCommand.


FN_MCIERR_WAVE_OUTPUTSUNSUITABLE
MCIERR_WAVE_OUTPUTSUNSUITABLE  (MCIERR_BASE + 70)  mmsystem.h


MCIERR_WAVE_OUTPUTUNSPECIFIED
MCIERR_WAVE_OUTPUTUNSPECIFIED  (MCIERR_BASE + 68)  mmsystem.h

Any compatible waveform playback device may be used. See mciSendCommand.


FN_MCIERR_WAVE_OUTPUTUNSPECIFIED
MCIERR_WAVE_OUTPUTUNSPECIFIED  (MCIERR_BASE + 68)  mmsystem.h


MCIERR_WAVE_SETINPUTINUSE
MCIERR_WAVE_SETINPUTINUSE  (MCIERR_BASE + 67)  mmsystem.h

Set waveform recording device is in use. See mciSendCommand.


FN_MCIERR_WAVE_SETINPUTINUSE
MCIERR_WAVE_SETINPUTINUSE  (MCIERR_BASE + 67)  mmsystem.h


MCIERR_WAVE_SETINPUTUNSUITABLE
MCIERR_WAVE_SETINPUTUNSUITABLE  (MCIERR_BASE + 73)  mmsystem.h

Set waveform recording device is incompatible with set format. See mciSendCommand.


FN_MCIERR_WAVE_SETINPUTUNSUITABLE
MCIERR_WAVE_SETINPUTUNSUITABLE  (MCIERR_BASE + 73)  mmsystem.h


MCIERR_WAVE_SETOUTPUTINUSE
MCIERR_WAVE_SETOUTPUTINUSE  (MCIERR_BASE + 65)  mmsystem.h

Set waveform playback device is in use. See mciSendCommand.


FN_MCIERR_WAVE_SETOUTPUTINUSE
MCIERR_WAVE_SETOUTPUTINUSE  (MCIERR_BASE + 65)  mmsystem.h


MCIERR_WAVE_SETOUTPUTUNSUITABLE
MCIERR_WAVE_SETOUTPUTUNSUITABLE  (MCIERR_BASE + 71)  mmsystem.h

Set waveform playback device is incompatible with set format. See mciSendCommand.


FN_MCIERR_WAVE_SETOUTPUTUNSUITABLE
MCIERR_WAVE_SETOUTPUTUNSUITABLE  (MCIERR_BASE + 71)  mmsystem.h


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. To create an MDI client window that enables the user to scroll MDI child windows into view, you can also use the WS_HSCROLL and WS_VSCROLL styles. See CreateWindow.


MDITILE_HORIZONTAL
MDITILE_HORIZONTAL  0x0001  winuser.h

Tiles MDI child windows so that they are wide rather than tall. See WM_MDITILE.


FN_MDITILE_HORIZONTAL
MDITILE_HORIZONTAL  0x0001  winuser.h


MDITILE_SKIPDISABLED
MDITILE_SKIPDISABLED  0x0002  winuser.h

Prevents disabled MDI child windows from being tiled. See WM_MDITILE.


FN_MDITILE_SKIPDISABLED
MDITILE_SKIPDISABLED  0x0002  winuser.h


MDITILE_VERTICAL
MDITILE_VERTICAL  0x0000  winuser.h

Tiles MDI child windows so that they are tall rather than wide. See WM_MDITILE.


FN_MDITILE_VERTICAL
MDITILE_VERTICAL  0x0000  winuser.h


MEM_COMMIT
MEM_COMMIT  0x1000  winnt.h

Indicates that the specified region of pages is to be committed, or that its state is committed. See VirtualAlloc, VirtualQuery, VirtualQueryEx


FN_MEM_COMMIT
MEM_COMMIT  0x1000  winnt.h


MEM_DECOMMIT
MEM_DECOMMIT  0x4000  winnt.h

Indicates that the specified region of pages is to be decommitted. See VirtualFree


FN_MEM_DECOMMIT
MEM_DECOMMIT  0x4000  winnt.h


MEM_FREE
MEM_FREE  0x10000  winnt.h

Indicates that the state of the pages within the specified region is free. See VirtualQuery, VirtualQueryEx


FN_MEM_FREE
MEM_FREE  0x10000  winnt.h


MEM_IMAGE
MEM_IMAGE  SEC_IMAGE  winnt.h

Indicates that the memory pages within the region are mapped into the view of an image section. See VirtualQuery, VirtualQueryEx


FN_MEM_IMAGE
MEM_IMAGE  SEC_IMAGE  winnt.h


MEM_MAPPED
MEM_MAPPED  0x40000  winnt.h

Indicates that the memory pages within the region are mapped into the view of a section. See VirtualQuery, VirtualQueryEx


FN_MEM_MAPPED
MEM_MAPPED  0x40000  winnt.h


MEM_PRIVATE
MEM_PRIVATE  0x20000  winnt.h

Indicates that the memory pages within the region are private. See VirtualQuery, VirtualQueryEx


FN_MEM_PRIVATE
MEM_PRIVATE  0x20000  winnt.h


MEM_RELEASE
MEM_RELEASE  0x8000  winnt.h

Indicates that the specified region of pages is to be released. See VirtualFree


FN_MEM_RELEASE
MEM_RELEASE  0x8000  winnt.h


MEM_RESERVE
MEM_RESERVE  0x2000  winnt.h

Indicates that specified region of pages is to be reserved, or that the state of the pages within the region is reserved. See VirtualAlloc, VirtualQuery, VirtualQueryEx


FN_MEM_RESERVE
MEM_RESERVE  0x2000  winnt.h


MEM_TOP_DOWN
MEM_TOP_DOWN  0x100000  winnt.h

Indicates that the operating system should allocate virtual memory at the highest-possible address. See VirtualAlloc


FN_MEM_TOP_DOWN
MEM_TOP_DOWN  0x100000  winnt.h


MERGECOPY
MERGECOPY  (DWORD)0x00C000CA  wingdi.h

Merges the colors of the source rectangle with the specified pattern using the Boolean AND operator. See BitBlt.


FN_MERGECOPY
MERGECOPY  (DWORD)0x00C000CA  wingdi.h


MERGEPAINT
MERGEPAINT  (DWORD)0x00BB0226  wingdi.h

Merges the colors of the inverted source-rectangle with the colors of the destination rectangle by using the Boolean OR operator. See BitBlt.


FN_MERGEPAINT
MERGEPAINT  (DWORD)0x00BB0226  wingdi.h


MF_BITMAP
MF_BITMAP  0x00000004L  winuser.h

Contains a bitmap handle. See AppendMenu, InsertMenu, ModifyMenu, WM_MENUSELECT.


FN_MF_BITMAP
MF_BITMAP  0x00000004L  winuser.h


MF_BYCOMMAND
MF_BYCOMMAND  0x00000000L  winuser.h

See CheckMenuItem, DeleteMenu, EnableMenuItem, GetMenuState, GetMenuString, HiliteMenuItem, InsertMenu, ModifyMenu, RemoveMenu, SetMenuItemBitmaps.


FN_MF_BYCOMMAND
MF_BYCOMMAND  0x00000000L  winuser.h


MF_BYPOSITION
MF_BYPOSITION  0x00000400L  winuser.h

See CheckMenuItem, DeleteMenu, EnableMenuItem, GetMenuState, GetMenuString, HiliteMenuItem, InsertMenu, ModifyMenu, RemoveMenu, SetMenuItemBitmaps.


FN_MF_BYPOSITION
MF_BYPOSITION  0x00000400L  winuser.h


MF_CALLBACKS
MF_CALLBACKS  0x08000000  ddeml.h

Notifies the callback function whenever a transaction is sent to any DDE callback function in the system. See DdeInitialize, XTYP_MONITOR.


FN_MF_CALLBACKS
MF_CALLBACKS  0x08000000  ddeml.h


MF_CHECKED
MF_CHECKED  0x00000008L  winuser.h

Places a check mark next to the item. If the application provides check mark bitmaps (see the SetMenuItemBitmaps function), this flag displays the checked bitmap next to the menu item. See AppendMenu, CheckMenuItem, GetMenuState, InsertMenu, ModifyMenu, WM_MENUSELECT, MENUITEMTEMPLATE.


FN_MF_CHECKED
MF_CHECKED  0x00000008L  winuser.h


MF_CONV
MF_CONV  0x40000000  ddeml.h

Notifies the callback function whenever a conversation is established or terminated. See DdeInitialize, XTYP_MONITOR.


FN_MF_CONV
MF_CONV  0x40000000  ddeml.h


MF_DISABLED
MF_DISABLED  0x00000002L  winuser.h

Disables the menu item so it cannot be selected, but does not gray it. See AppendMenu, EnableMenuItem, GetMenuState, InsertMenu, ModifyMenu, WM_MENUSELECT.


FN_MF_DISABLED
MF_DISABLED  0x00000002L  winuser.h


MF_ENABLED
MF_ENABLED  0x00000000L  winuser.h

Enables the menu item so it can be selected and restores it from its grayed state. See AppendMenu, EnableMenuItem, InsertMenu, ModifyMenu.


FN_MF_ENABLED
MF_ENABLED  0x00000000L  winuser.h


MF_ERRORS
MF_ERRORS  0x10000000  ddeml.h

A DDE error occurred. The DDE data object contains a MONERRSTRUCT structure that provides information about the error. See DdeInitialize, XTYP_MONITOR.


FN_MF_ERRORS
MF_ERRORS  0x10000000  ddeml.h


MF_GRAYED
MF_GRAYED  0x00000001L  winuser.h

Disables the menu item and grays it so it cannot be selected. See AppendMenu, EnableMenuItem, GetMenuState, InsertMenu, ModifyMenu, WM_MENUSELECT, MENUITEMTEMPLATE.


FN_MF_GRAYED
MF_GRAYED  0x00000001L  winuser.h


MF_HELP
MF_HELP  0x00004000L  winuser.h

Indicates that the item has a vertical separator to its left. See MENUITEMTEMPLATE.


FN_MF_HELP
MF_HELP  0x00004000L  winuser.h


MF_HILITE
MF_HILITE  0x00000080L  winuser.h

Highlights the menu item. If this value is not given, the highlighting is removed from the item. See GetMenuState, HiliteMenuItem.


FN_MF_HILITE
MF_HILITE  0x00000080L  winuser.h


MF_HSZ_INFO
MF_HSZ_INFO  0x01000000  ddeml.h

Notifies the callback function whenever a DDE application creates, frees, or increments the use count of a string handle or whenever a string handle is freed as a result of a call to the DdeUninitialize function. See DdeInitialize, XTYP_MONITOR.


FN_MF_HSZ_INFO
MF_HSZ_INFO  0x01000000  ddeml.h


MF_LINKS
MF_LINKS  0x20000000  ddeml.h

Notifies the callback function whenever an advise loop is started or ended. See DdeInitialize, XTYP_MONITOR.


FN_MF_LINKS
MF_LINKS  0x20000000  ddeml.h


MF_MENUBARBREAK
MF_MENUBARBREAK  0x00000020L  winuser.h

Functions the same as MF_MENUBREAK except for pop-up menus, where the new column is separated from the old column by a vertical line. See AppendMenu, GetMenuState, InsertMenu, ModifyMenu, MENUITEMTEMPLATE.


FN_MF_MENUBARBREAK
MF_MENUBARBREAK  0x00000020L  winuser.h


MF_MENUBREAK
MF_MENUBREAK  0x00000040L  winuser.h

Places the item on a new line (menu bars) or in a new column (pop-up menus) without separating columns. See AppendMenu, GetMenuState, InsertMenu, ModifyMenu, MENUITEMTEMPLATE.


FN_MF_MENUBREAK
MF_MENUBREAK  0x00000040L  winuser.h


MF_MOUSESELECT
MF_MOUSESELECT  0x00008000L  winuser.h

Item was selected with the mouse. See WM_MENUSELECT.


FN_MF_MOUSESELECT
MF_MOUSESELECT  0x00008000L  winuser.h


MF_OWNERDRAW
MF_OWNERDRAW  0x00000100L  winuser.h

Contains a 32-bit value supplied by your application that you can use to maintain additional data related to the menu item. The value is in the itemData member of the structire pointed to by the Iparam parameter of the WM_MEASURE or WM_DRAWITEM messages sent when you create the menu item or update its appearance. See AppendMenu, InsertMenu, ModifyMenu, WM_MENUSELECT, MENUITEMTEMPLATE.


FN_MF_OWNERDRAW
MF_OWNERDRAW  0x00000100L  winuser.h


MF_POPUP
MF_POPUP  0x00000010L  winuser.h

Specifies that the menu item is a pop-up item; that is, selecting it invokes a pop-up menu. The idNewItem parameter specifies the handle of the pop-up menu. Use this flag to add a pop-up item to a menu bar or to a pop-up menu. See AppendMenu, InsertMenu, ModifyMenu, WM_MENUCHAR, WM_MENUSELECT, MENUITEMTEMPLATE.


FN_MF_POPUP
MF_POPUP  0x00000010L  winuser.h


MF_POSTMSGS
MF_POSTMSGS  0x04000000  ddeml.h

Notifies the callback function whenever the system or an application posts a DDE message. See DdeInitialize, XTYP_MONITOR.


FN_MF_POSTMSGS
MF_POSTMSGS  0x04000000  ddeml.h


MF_SENDMSGS
MF_SENDMSGS  0x02000000  ddeml.h

Notifies the callback function whenever the system or an application sends a DDE message. See DdeInitialize, XTYP_MONITOR.


FN_MF_SENDMSGS
MF_SENDMSGS  0x02000000  ddeml.h


MF_SEPARATOR
MF_SEPARATOR  0x00000800L  winuser.h

Draws a horizontal dividing line. Use this flag only in a pop-up menu. You cannot gray, disable, or highlight this line. The lpszNewItem and idNewItem parameters are ignored. See AppendMenu, GetMenuState, InsertMenu, ModifyMenu.


FN_MF_SEPARATOR
MF_SEPARATOR  0x00000800L  winuser.h


MF_STRING
MF_STRING  0x00000000L  winuser.h

Contains a pointer to a null-terminated string. See AppendMenu, InsertMenu, ModifyMenu.


FN_MF_STRING
MF_STRING  0x00000000L  winuser.h


MF_SYSMENU
MF_SYSMENU  0x00002000L  winuser.h

The menu is a System menu. See WM_MENUCHAR, WM_MENUSELECT.


FN_MF_SYSMENU
MF_SYSMENU  0x00002000L  winuser.h


MF_UNCHECKED
MF_UNCHECKED  0x00000000L  winuser.h

Does not place a checkmark next to the item (default). If the application supplies check mark bitmaps (see the SetMenuItemBitmaps function), this flag displays the unchecked bitmap next to the menu item. See AppendMenu, CheckMenuItem, InsertMenu, ModifyMenu.


FN_MF_UNCHECKED
MF_UNCHECKED  0x00000000L  winuser.h


MF_UNHILITE
MF_UNHILITE  0x00000000L  winuser.h

Removes the highlighting from the menu item. See HiliteMenuItem.


FN_MF_UNHILITE
MF_UNHILITE  0x00000000L  winuser.h


MH_CLEANUP
MH_CLEANUP  4  ddeml.h

An application is freeing its DDE resources, causing the system to delete string handles that the application had created. (The application called the DdeUninitialize function.) See MONHSZSTRUCT.


FN_MH_CLEANUP
MH_CLEANUP  4  ddeml.h


MH_CREATE
MH_CREATE  1  ddeml.h

An application is creating a string handle. (The application called the DdeCreateStringHandle function.) See MONHSZSTRUCT.


FN_MH_CREATE
MH_CREATE  1  ddeml.h


MH_DELETE
MH_DELETE  3  ddeml.h

An application is deleting a string handle. (The application called the DdeFreeStringHandle function.) See MONHSZSTRUCT.


FN_MH_DELETE
MH_DELETE  3  ddeml.h


MH_KEEP
MH_KEEP  2  ddeml.h

An application is increasing the use count of a string handle. (The application called the DdeKeepStringHandle function.) See MONHSZSTRUCT.


FN_MH_KEEP
MH_KEEP  2  ddeml.h


MHDR_DONE
MHDR_DONE  0x00000001  mmsystem.h

Set by the device driver to indicate that it is finished with the data buffer and is returning it to the application. See MIDIHDR.


FN_MHDR_DONE
MHDR_DONE  0x00000001  mmsystem.h


MHDR_PREPARED
MHDR_PREPARED  0x00000002  mmsystem.h

Set by Windows to indicate that the data buffer has been prepared with midiInPrepareHeader or midiOutPrepareHeader. See MIDIHDR.


FN_MHDR_PREPARED
MHDR_PREPARED  0x00000002  mmsystem.h


MIDI_CACHE_ALL
MIDI_CACHE_ALL  1  mmsystem.h

Cache all of the specified patches. If they can't all be cached, cache none, clear the KEYARRAY array,and return MMSYSERR_NOMEM. See midiOutCacheDrumPatches, midiOutCachePatches.


FN_MIDI_CACHE_ALL
MIDI_CACHE_ALL  1  mmsystem.h


MIDI_CACHE_BESTFIT
MIDI_CACHE_BESTFIT  2  mmsystem.h

Cache all of the specified patches. If all patches can't be cached, cache as many patches as possible, change the KEYARRAY array to reflect which patches were cached, and return MMSYSERR_NOMEM. See midiOutCacheDrumPatches, midiOutCachePatches.


FN_MIDI_CACHE_BESTFIT
MIDI_CACHE_BESTFIT  2  mmsystem.h


MIDI_CACHE_QUERY
MIDI_CACHE_QUERY  3  mmsystem.h

Change the KEYARRAY or PATCHARRAY array to indicate which patches are currently cached. See midiOutCacheDrumPatches, midiOutCachePatches.


FN_MIDI_CACHE_QUERY
MIDI_CACHE_QUERY  3  mmsystem.h


MIDI_MAPPER
MIDI_MAPPER  (-1)    mmsystem.h

Sets the port opened to the MIDI Mapper. See MCI_SET.


FN_MIDI_MAPPER
MIDI_MAPPER  (-1)    mmsystem.h


MIDI_UNCACHE
MIDI_UNCACHE  4  mmsystem.h

Uncache the specified patches and clear the KEYARRAY or PATCHARRAY array. See midiOutCacheDrumPatches, midiOutCachePatches.


FN_MIDI_UNCACHE
MIDI_UNCACHE  4  mmsystem.h


MIDICAPS_CACHE
MIDICAPS_CACHE  0x00000004  mmsystem.h

Supports patch caching. See MIDIOUTCAPS.


FN_MIDICAPS_CACHE
MIDICAPS_CACHE  0x00000004  mmsystem.h


MIDICAPS_LRVOLUME
MIDICAPS_LRVOLUME  0x00000002  mmsystem.h

Supports separate left and right volume control. See MIDIOUTCAPS.


FN_MIDICAPS_LRVOLUME
MIDICAPS_LRVOLUME  0x00000002  mmsystem.h


MIDICAPS_VOLUME
MIDICAPS_VOLUME  0x00000001  mmsystem.h

Supports volume control. See MIDIOUTCAPS.


FN_MIDICAPS_VOLUME
MIDICAPS_VOLUME  0x00000001  mmsystem.h


MIDIERR_NODEVICE
MIDIERR_NODEVICE  (MIDIERR_BASE + 4)  mmsystem.h

A port in the current MIDI map doesn't exist. This occurs only when opening the mapper. See midiOutOpen.


FN_MIDIERR_NODEVICE
MIDIERR_NODEVICE  (MIDIERR_BASE + 4)  mmsystem.h


MIDIERR_NOMAP
MIDIERR_NOMAP  (MIDIERR_BASE + 2)  mmsystem.h

There is no current MIDI map. This occurs only when opening the mapper. See midiOutOpen.


FN_MIDIERR_NOMAP
MIDIERR_NOMAP  (MIDIERR_BASE + 2)  mmsystem.h


MIDIERR_NOTREADY
MIDIERR_NOTREADY  (MIDIERR_BASE + 3)  mmsystem.h

The hardware is busy with other data. See midiOutLongMsg, midiOutShortMsg.


FN_MIDIERR_NOTREADY
MIDIERR_NOTREADY  (MIDIERR_BASE + 3)  mmsystem.h


MIDIERR_STILLPLAYING
MIDIERR_STILLPLAYING  (MIDIERR_BASE + 1)  mmsystem.h

There are still buffers in the queue. See midiInClose, midiInUnprepareHeader, midiOutClose, midiOutUnprepareHeader.


FN_MIDIERR_STILLPLAYING
MIDIERR_STILLPLAYING  (MIDIERR_BASE + 1)  mmsystem.h


MIDIERR_UNPREPARED
MIDIERR_UNPREPARED  (MIDIERR_BASE + 0)  mmsystem.h

lpmidih hasn't been prepared. See midiInAddBuffer, midiOutLongMsg.


FN_MIDIERR_UNPREPARED
MIDIERR_UNPREPARED  (MIDIERR_BASE + 0)  mmsystem.h


MK_CONTROL
MK_CONTROL  0x0008  winuser.h

Set if a CTRL key is down. See WM_LBUTTONDBLCLK, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MOUSEMOVE, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP.


FN_MK_CONTROL
MK_CONTROL  0x0008  winuser.h


MK_LBUTTON
MK_LBUTTON  0x0001  winuser.h

Set if the left mouse button is down. See WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MOUSEMOVE, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP.


FN_MK_LBUTTON
MK_LBUTTON  0x0001  winuser.h


MK_MBUTTON
MK_MBUTTON  0x0010  winuser.h

Set if the middle mouse button is down. See WM_LBUTTONDBLCLK, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONDBLCLK, WM_MOUSEMOVE, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP.


FN_MK_MBUTTON
MK_MBUTTON  0x0010  winuser.h


MK_RBUTTON
MK_RBUTTON  0x0002  winuser.h

Set if the right mouse button is down. See WM_LBUTTONDBLCLK, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MOUSEMOVE, WM_RBUTTONDBLCLK.


FN_MK_RBUTTON
MK_RBUTTON  0x0002  winuser.h


MK_SHIFT
MK_SHIFT  0x0004  winuser.h

Set if a SHIFT key is down. See WM_LBUTTONDBLCLK, WM_LBUTTONDOWN, WM_LBUTTONUP, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MOUSEMOVE, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN, WM_RBUTTONUP.


FN_MK_SHIFT
MK_SHIFT  0x0004  winuser.h


MM_ANISOTROPIC
MM_ANISOTROPIC  8  wingdi.h

Logical units are mapped to arbitrary units with arbitrarily scaled axes. Use the SetWindowExtEx and SetViewportExtEx functions to specify the desired units, orientation, and scaling. See SetMapMode.


FN_MM_ANISOTROPIC
MM_ANISOTROPIC  8  wingdi.h


MM_HIENGLISH
MM_HIENGLISH  5  wingdi.h

Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is up. See SetMapMode.


FN_MM_HIENGLISH
MM_HIENGLISH  5  wingdi.h


MM_HIMETRIC
MM_HIMETRIC  3  wingdi.h

Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is up. See SetMapMode.


FN_MM_HIMETRIC
MM_HIMETRIC  3  wingdi.h


MM_ISOTROPIC
MM_ISOTROPIC  7  wingdi.h

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 desired units and the orientation of the axes. Graphics Device Interface (GDI) makes adjustments as necessary to ensure the x and y units remain the same size (e.g. If you set the window extent, the viewport will be adjusted to keep the units isotropic). See SetMapMode.


FN_MM_ISOTROPIC
MM_ISOTROPIC  7  wingdi.h


MM_LOENGLISH
MM_LOENGLISH  4  wingdi.h

Each logical unit is mapped to 0.01 inch. Positive x is to the right; positive y is up. See SetMapMode.


FN_MM_LOENGLISH
MM_LOENGLISH  4  wingdi.h


MM_LOMETRIC
MM_LOMETRIC  2  wingdi.h

Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is up. See SetMapMode.


FN_MM_LOMETRIC
MM_LOMETRIC  2  wingdi.h


MM_TEXT
MM_TEXT  1  wingdi.h

Each logical unit is mapped to one device pixel. Positive x is to the right; positive y is down. See SetMapMode.


FN_MM_TEXT
MM_TEXT  1  wingdi.h


MM_TWIPS
MM_TWIPS  6  wingdi.h

Each logical unit is mapped to one twentieth of a printer's point (1/1440 inch). Positive x is to the right; positive y is up. See SetMapMode.


FN_MM_TWIPS
MM_TWIPS  6  wingdi.h


MMIO_ALLOCBUF
MMIO_ALLOCBUF  0x00010000  mmsystem.h

Opens a file for buffered I/O. To allocate a buffer larger or smaller than the default buffer size (8K), set the cchBuffer member of the MMIOINFO structure to the desired buffer size. If cchBuffer is zero, then the default buffer size is used. If you are providing your own I/O buffer, then the MMIO_ALLOCBUF flag should not be used. See mmioOpen, MMIOINFO.


FN_MMIO_ALLOCBUF
MMIO_ALLOCBUF  0x00010000  mmsystem.h


MMIO_COMPAT
MMIO_COMPAT  0x00000000  mmsystem.h

Opens the file with compatibility mode,allowing any process on a given machine to open the file any number of times. mmioOpen fails if the file has been opened with any of the other sharing modes. See mmioOpen, MMIOINFO.


FN_MMIO_COMPAT
MMIO_COMPAT  0x00000000  mmsystem.h


MMIO_CREATE
MMIO_CREATE  0x00001000  mmsystem.h

Creates a new file. If the file already exists, it is truncated to zero length. For memory files, MMIO_CREATE indicates the end of the file is initially at the start of the buffer. See mmioOpen, MMIOINFO.


FN_MMIO_CREATE
MMIO_CREATE  0x00001000  mmsystem.h


MMIO_CREATELIST
MMIO_CREATELIST  0x0040  mmsystem.h

Creates a "LIST" chunk. See mmioCreateChunk.


FN_MMIO_CREATELIST
MMIO_CREATELIST  0x0040  mmsystem.h


MMIO_CREATERIFF
MMIO_CREATERIFF  0x0020  mmsystem.h

Creates a "RIFF" chunk. See mmioCreateChunk.


FN_MMIO_CREATERIFF
MMIO_CREATERIFF  0x0020  mmsystem.h


MMIO_DELETE
MMIO_DELETE  0x00000200  mmsystem.h

Deletes a file. If this flag is specified, lpszFilename should not be NULL. The return value will be TRUE (cast to HMMIO) if the file was deleted successfully, FALSE otherwise. Do not call mmioClose for a file that has been deleted. If this flag is specified,all other file opening flags are ignored. See mmioOpen.


FN_MMIO_DELETE
MMIO_DELETE  0x00000200  mmsystem.h


MMIO_DENYNONE
MMIO_DENYNONE  0x00000040  mmsystem.h

Opens the file without denying other processes read or write access to the file. mmioOpen fails if the file has been opened in compatibility mode by any other process. See mmioOpen, MMIOINFO.


FN_MMIO_DENYNONE
MMIO_DENYNONE  0x00000040  mmsystem.h


MMIO_DENYREAD
MMIO_DENYREAD  0x00000030  mmsystem.h

Opens the file and denies other processes read access to the file. mmioOpen fails if the file has been opened in compatibility mode or for read access by any other process. See mmioOpen, MMIOINFO.


FN_MMIO_DENYREAD
MMIO_DENYREAD  0x00000030  mmsystem.h


MMIO_DENYWRITE
MMIO_DENYWRITE  0x00000020  mmsystem.h

Opens the file and denies other processes write access to the file. mmioOpen fails if the file has been opened in compatibility or for write access by any other process. See mmioOpen, MMIOINFO.


FN_MMIO_DENYWRITE
MMIO_DENYWRITE  0x00000020  mmsystem.h


MMIO_EXCLUSIVE
MMIO_EXCLUSIVE  0x00000010  mmsystem.h

Opens the file with exclusive mode,denying other processes both read and write access to the file. mmioOpen fails if the file has been opened in any other mode for read or write access, even by the current process. See mmioOpen, MMIOINFO.


FN_MMIO_EXCLUSIVE
MMIO_EXCLUSIVE  0x00000010  mmsystem.h


MMIO_EXIST
MMIO_EXIST  0x00004000  mmsystem.h

Determines whether the specified file exists and creates a fully qualified filename from the path specified in lpszFileName. The fully qualified filename is placed back into lpszFileName. The return value will be TRUE (cast to HMMIO) if the qualification was successful and the file exists, FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file. See mmioOpen.


FN_MMIO_EXIST
MMIO_EXIST  0x00004000  mmsystem.h


MMIO_FHOPEN
MMIO_FHOPEN  0x0010  mmsystem.h

If the file was opened by passing the Windows file handle of an already-opened file to mmioOpen, then using this flag tells mmioClose to close the MMIO file handle, but not the Windows file handle. (This is done by the I/O Proc). See mmioClose.


FN_MMIO_FHOPEN
MMIO_FHOPEN  0x0010  mmsystem.h


MMIO_FINDCHUNK
MMIO_FINDCHUNK  0x0010  mmsystem.h

Searches for a chunk with the specified chunk ID. See mmioDescend.


FN_MMIO_FINDCHUNK
MMIO_FINDCHUNK  0x0010  mmsystem.h


MMIO_FINDLIST
MMIO_FINDLIST  0x0040  mmsystem.h

Searches for a chunk with chunk ID "LIST" and with the specified form type. See mmioDescend.


FN_MMIO_FINDLIST
MMIO_FINDLIST  0x0040  mmsystem.h


MMIO_FINDPROC
MMIO_FINDPROC  0x00040000  mmsystem.h

Searches for the specified I/O procedure. See mmioInstallIOProc.


FN_MMIO_FINDPROC
MMIO_FINDPROC  0x00040000  mmsystem.h


MMIO_FINDRIFF
MMIO_FINDRIFF  0x0020  mmsystem.h

Searches for a chunk with chunk ID "RIFF" and with the specified form type. See mmioDescend.


FN_MMIO_FINDRIFF
MMIO_FINDRIFF  0x0020  mmsystem.h


MMIO_GETTEMP
MMIO_GETTEMP  0x00020000  mmsystem.h

Creates a temporary filename, optionally using the parameters passed in lpszFileName to determine the temporary name. 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 lpszFileName. The return value will be TRUE (cast to HMMIO) if the temporary filename was created successfully,FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file. This flag overrides all other flags. See mmioOpen.


FN_MMIO_GETTEMP
MMIO_GETTEMP  0x00020000  mmsystem.h


MMIO_GLOBALPROC
MMIO_GLOBALPROC  0x10000000  mmsystem.h

This flag is a modifier to the install flag,and indicates the I/O procedure should be installed for global use. This flag is ignored on removal or find. See mmioInstallIOProc.


FN_MMIO_GLOBALPROC
MMIO_GLOBALPROC  0x10000000  mmsystem.h


MMIO_INSTALLPROC
MMIO_INSTALLPROC  0x00010000  mmsystem.h

Installs the specified I/O procedure. See mmioInstallIOProc.


FN_MMIO_INSTALLPROC
MMIO_INSTALLPROC  0x00010000  mmsystem.h


MMIO_PARSE
MMIO_PARSE  0x00000100  mmsystem.h

Creates a fully qualified filename from the path specified in lpszFileName. The fully qualified filename is placed back into lpszFileName. The return value will be TRUE (cast to HMMIO) if the qualification was successful, FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file. If this flag is specified, all other file opening flags are ignored. See mmioOpen.


FN_MMIO_PARSE
MMIO_PARSE  0x00000100  mmsystem.h


MMIO_READ
MMIO_READ  0x00000000  mmsystem.h

Opens the file for reading only. This is the default, if MMIO_WRITE and MMIO_READWRITE are not specified. See mmioAdvance, mmioOpen, MMIOINFO.


FN_MMIO_READ
MMIO_READ  0x00000000  mmsystem.h


MMIO_READWRITE
MMIO_READWRITE  0x00000002  mmsystem.h

Opens the file for both reading and writing. See mmioOpen, MMIOINFO.


FN_MMIO_READWRITE
MMIO_READWRITE  0x00000002  mmsystem.h


MMIO_REMOVEPROC
MMIO_REMOVEPROC  0x00020000  mmsystem.h

Removes the specified I/O procedure. See mmioInstallIOProc.


FN_MMIO_REMOVEPROC
MMIO_REMOVEPROC  0x00020000  mmsystem.h


MMIO_TOUPPER
MMIO_TOUPPER  0x0010  mmsystem.h

Convert all characters to uppercase. See mmioStringToFOURCC.


FN_MMIO_TOUPPER
MMIO_TOUPPER  0x0010  mmsystem.h


MMIO_WRITE
MMIO_WRITE  0x00000001  mmsystem.h

Opens the file for writing. You should not read from a file opened in this mode. See mmioAdvance, mmioOpen, MMIOINFO.


FN_MMIO_WRITE
MMIO_WRITE  0x00000001  mmsystem.h


MMIOERR_CANNOTCLOSE
MMIOERR_CANNOTCLOSE  (MMIOERR_BASE + 4)  mmsystem.h

There was a Windows file system error when the I/O Proc attempted to close the Windows file. See mmioClose.


FN_MMIOERR_CANNOTCLOSE
MMIOERR_CANNOTCLOSE  (MMIOERR_BASE + 4)  mmsystem.h


MMIOERR_CANNOTEXPAND
MMIOERR_CANNOTEXPAND  (MMIOERR_BASE + 8)  mmsystem.h

The specified memory file cannot be expanded, probably because the adwInfo[0] member was set to zero in the initial call to mmioOpen. See mmioAdvance.


FN_MMIOERR_CANNOTEXPAND
MMIOERR_CANNOTEXPAND  (MMIOERR_BASE + 8)  mmsystem.h


MMIOERR_CANNOTREAD
MMIOERR_CANNOTREAD  (MMIOERR_BASE + 5)  mmsystem.h

An error occurred while re-filling the buffer. See mmioAdvance.


FN_MMIOERR_CANNOTREAD
MMIOERR_CANNOTREAD  (MMIOERR_BASE + 5)  mmsystem.h


MMIOERR_CANNOTSEEK
MMIOERR_CANNOTSEEK  (MMIOERR_BASE + 7)  mmsystem.h

There was an error while seeking to the end of the chunk. See mmioAscend, mmioCreateChunk.


FN_MMIOERR_CANNOTSEEK
MMIOERR_CANNOTSEEK  (MMIOERR_BASE + 7)  mmsystem.h


MMIOERR_CANNOTWRITE
MMIOERR_CANNOTWRITE  (MMIOERR_BASE + 6)  mmsystem.h

The contents of the buffer could not be written to disk. See mmioAdvance, mmioAscend, mmioClose, mmioCreateChunk, mmioFlush, mmioSetBuffer.


FN_MMIOERR_CANNOTWRITE
MMIOERR_CANNOTWRITE  (MMIOERR_BASE + 6)  mmsystem.h


MMIOERR_OUTOFMEMORY
MMIOERR_OUTOFMEMORY  (MMIOERR_BASE + 2)  mmsystem.h

There was not enough memory to expand a memory file for further writing. See mmioAdvance, mmioSetBuffer.


FN_MMIOERR_OUTOFMEMORY
MMIOERR_OUTOFMEMORY  (MMIOERR_BASE + 2)  mmsystem.h


MMIOERR_UNBUFFERED
MMIOERR_UNBUFFERED  (MMIOERR_BASE + 10)  mmsystem.h

The specified file is not opened for buffered I/O. See mmioAdvance.


FN_MMIOERR_UNBUFFERED
MMIOERR_UNBUFFERED  (MMIOERR_BASE + 10)  mmsystem.h


MMIOM_CANNOTOPEN

Specified file could not be opened. See MMIOM_OPEN.


MMIOM_OUTOFMEMORY

Not enough memory to perform operation. See MMIOM_OPEN.


MMSYSERR_ALLOCATED
MMSYSERR_ALLOCATED  (MMSYSERR_BASE + 4)  mmsystem.h

Specified resource is already allocated. See midiInOpen, midiOutOpen, waveInOpen, waveOutOpen.


FN_MMSYSERR_ALLOCATED
MMSYSERR_ALLOCATED  (MMSYSERR_BASE + 4)  mmsystem.h


MMSYSERR_BADDEVICEID
MMSYSERR_BADDEVICEID  (MMSYSERR_BASE + 2)  mmsystem.h

Specified device ID is out of range. See auxGetDevCaps.


FN_MMSYSERR_BADDEVICEID
MMSYSERR_BADDEVICEID  (MMSYSERR_BASE + 2)  mmsystem.h


MMSYSERR_BADDEVICEID
MMSYSERR_BADDEVICEID  (MMSYSERR_BASE + 2)  mmsystem.h

Specified device ID is out of range. See auxGetVolume, auxSetVolume, midiInGetDevCaps, midiInOpen, midiOutGetDevCaps, midiOutOpen, waveInGetDevCaps, waveInOpen, waveOutGetDevCaps, waveOutOpen.


FN_MMSYSERR_BADDEVICEID
MMSYSERR_BADDEVICEID  (MMSYSERR_BASE + 2)  mmsystem.h


MMSYSERR_BADERRNUM
MMSYSERR_BADERRNUM  (MMSYSERR_BASE + 9)  mmsystem.h

Specified error number is out of range. See midiInGetErrorText, midiOutGetErrorText, waveInGetErrorText, waveOutGetErrorText.


FN_MMSYSERR_BADERRNUM
MMSYSERR_BADERRNUM  (MMSYSERR_BASE + 9)  mmsystem.h


MMSYSERR_HANDLEBUSY
MMSYSERR_HANDLEBUSY  (MMSYSERR_BASE + 12)  mmsystem.h

The handle is in use on another thread. See waveInAddBuffer, waveInGetID, waveInPrepareHeader, waveInReset, waveInStart, waveInStop, waveInUnprepareHeader, waveOutBreakLoop, waveOutClose, waveOutGetID, waveOutGetPitch, waveOutGetPlaybackRate, waveOutGetPosition, waveOutPause, waveOutPrepareHeader, waveOutReset, waveOutRestart, waveOutSetPitch, waveOutSetPlaybackRate, waveOutUnprepareHeader, waveOutWrite.


FN_MMSYSERR_HANDLEBUSY
MMSYSERR_HANDLEBUSY  (MMSYSERR_BASE + 12)  mmsystem.h


MMSYSERR_INVALHANDLE
MMSYSERR_INVALHANDLE  (MMSYSERR_BASE + 5)  mmsystem.h

Specified device handle is invalid. See midiInAddBuffer, midiInClose, midiInGetID, midiInPrepareHeader, midiInReset, midiInStart, midiInStop, midiInUnprepareHeader, midiOutCacheDrumPatches, midiOutCachePatches, midiOutClose, midiOutGetID, midiOutGetVolume, midiOutLongMsg, midiOutPrepareHeader, midiOutReset, midiOutSetVolume, midiOutShortMsg, midiOutUnprepareHeader, waveInAddBuffer, waveInClose, waveInGetID, waveInGetPosition, waveInPrepareHeader, waveInReset, waveInStart, waveInStop, waveInUnprepareHeader, waveOutBreakLoop, waveOutClose, waveOutGetID, waveOutGetPitch, waveOutGetPlaybackRate, waveOutGetPosition, waveOutGetVolume, waveOutPause, waveOutPrepareHeader, waveOutReset, waveOutRestart, waveOutSetPitch, waveOutSetPlaybackRate, waveOutSetVolume, waveOutUnprepareHeader, waveOutWrite.


FN_MMSYSERR_INVALHANDLE
MMSYSERR_INVALHANDLE  (MMSYSERR_BASE + 5)  mmsystem.h


MMSYSERR_NODRIVER
MMSYSERR_NODRIVER  (MMSYSERR_BASE + 6)  mmsystem.h

The driver failed to install. See auxGetDevCaps, auxGetVolume, auxSetVolume, joyGetDevCaps, joyGetPos, joyGetThreshold, joyReleaseCapture, joySetCapture, joySetThreshold, midiInGetDevCaps, midiOutGetDevCaps, midiOutGetVolume, midiOutSetVolume, waveInGetDevCaps, waveOutGetDevCaps, waveOutGetVolume, waveOutSetVolume.


FN_MMSYSERR_NODRIVER
MMSYSERR_NODRIVER  (MMSYSERR_BASE + 6)  mmsystem.h


MMSYSERR_NOMEM
MMSYSERR_NOMEM  (MMSYSERR_BASE + 7)  mmsystem.h

Unable to allocate or lock memory. See midiInOpen, midiInPrepareHeader, midiOutCacheDrumPatches, midiOutCachePatches, midiOutGetDevCaps, midiOutOpen, midiOutPrepareHeader, waveInOpen, waveInPrepareHeader, waveOutOpen, waveOutPrepareHeader.


FN_MMSYSERR_NOMEM
MMSYSERR_NOMEM  (MMSYSERR_BASE + 7)  mmsystem.h


MMSYSERR_NOTSUPPORTED
MMSYSERR_NOTSUPPORTED  (MMSYSERR_BASE + 8)  mmsystem.h

Function isn't supported. See midiOutCacheDrumPatches, midiOutCachePatches, midiOutGetVolume, midiOutSetVolume, waveOutGetPitch, waveOutGetPlaybackRate, waveOutGetVolume, waveOutSetPitch, waveOutSetPlaybackRate, waveOutSetVolume.


FN_MMSYSERR_NOTSUPPORTED
MMSYSERR_NOTSUPPORTED  (MMSYSERR_BASE + 8)  mmsystem.h


MOD_ALT
MOD_ALT  0x0001  winuser.h

Either ALT key must be held down. See RegisterHotKey.


FN_MOD_ALT
MOD_ALT  0x0001  winuser.h


MOD_CONTROL
MOD_CONTROL  0x0002  winuser.h

Either CTRL key must be held down. See RegisterHotKey.


FN_MOD_CONTROL
MOD_CONTROL  0x0002  winuser.h


MOD_FMSYNTH
MOD_FMSYNTH  4  mmsystem.h

Indicates the device is an FM synthesizer. See MIDIOUTCAPS.


FN_MOD_FMSYNTH
MOD_FMSYNTH  4  mmsystem.h


MOD_MAPPER
MOD_MAPPER  5  mmsystem.h

Indicates the device is the Microsoft MIDI Mapper. See MIDIOUTCAPS.


FN_MOD_MAPPER
MOD_MAPPER  5  mmsystem.h


MOD_MIDIPORT
MOD_MIDIPORT  1  mmsystem.h

Indicates the device is a MIDI hardware port. See MIDIOUTCAPS.


FN_MOD_MIDIPORT
MOD_MIDIPORT  1  mmsystem.h


MOD_SHIFT
MOD_SHIFT  0x0004  winuser.h

Either SHIFT key must be held down. See RegisterHotKey.


FN_MOD_SHIFT
MOD_SHIFT  0x0004  winuser.h


MOD_SQSYNTH
MOD_SQSYNTH  3  mmsystem.h

Indicates the device is a square wave synthesizer. See MIDIOUTCAPS.


FN_MOD_SQSYNTH
MOD_SQSYNTH  3  mmsystem.h


MOUSEEVENTF_MOVE

Indicates that movement occurred. See mouse_event.


MOUSEEVENTF_LEFTDOWN
MOUSEEVENTF_LEFTDOWN  0x0002  winuser.h

Indicates that the left button changed to down. See mouse_event.


FN_MOUSEEVENTF_LEFTDOWN
MOUSEEVENTF_LEFTDOWN  0x0002  winuser.h


MOUSEEVENTF_LEFTUP
MOUSEEVENTF_LEFTUP  0x0004  winuser.h

Indicates that the left button changed to up. See mouse_event.


FN_MOUSEEVENTF_LEFTUP
MOUSEEVENTF_LEFTUP  0x0004  winuser.h


MOUSEEVENTF_RIGHTDOWN

Indicates that the right button changed to down. See mouse_event.


MOUSEEVENTF_RIGHTUP

Indicates that the right button changed to up. See mouse_event.


MOUSEEVENTF_MIDDLEDOWN
MOUSEEVENTF_MIDDLEDOWN  0x0020  winuser.h

Indicates that the middle button changed to down. See mouse_event.


FN_MOUSEEVENTF_MIDDLEDOWN
MOUSEEVENTF_MIDDLEDOWN  0x0020  winuser.h


MOUSEEVENTF_MIDDLEUP
MOUSEEVENTF_MIDDLEUP  0x0040  winuser.h

Indicates that the middle button changed to up. See mouse_event.


FN_MOUSEEVENTF_MIDDLEUP
MOUSEEVENTF_MIDDLEUP  0x0040  winuser.h


MOUSEEVENTF_ABSOLUTE

Indicates that the dx and dy parameters contain normalized absolute coordinates. See mouse_event.


MOUSE_MOVED

Indicates a change in mouse position. See MOUSE_EVENT_RECORD.


MOVEFILE_COPY_ALLOWED
MOVEFILE_COPY_ALLOWED  0x00000002  winbase.h

If the file is to be moved to a different volume, the function simulates the move by using the CopyFile and DeleteFile functions. See MoveFileEx.


FN_MOVEFILE_COPY_ALLOWED
MOVEFILE_COPY_ALLOWED  0x00000002  winbase.h


MOVEFILE_DELAY_UNTIL_REBOOT
MOVEFILE_DELAY_UNTIL_REBOOT  0x00000004  winbase.h

The function will not move the file until the system is rebooted. The system moves the file immediately after AUTOCHK is executed, but before creating any paging files. Therefore, this parameter enables the function to delete paging files from previous boots. See MoveFileEx.


FN_MOVEFILE_DELAY_UNTIL_REBOOT
MOVEFILE_DELAY_UNTIL_REBOOT  0x00000004  winbase.h


MOVEFILE_REPLACE_EXISTING
MOVEFILE_REPLACE_EXISTING  0x00000001  winbase.h

If a file of the name specified by lpszNew already exists, the function replaces its contents with those specified by lpszExisting. See MoveFileEx.


FN_MOVEFILE_REPLACE_EXISTING
MOVEFILE_REPLACE_EXISTING  0x00000001  winbase.h


MS_CTS_ON
MS_CTS_ON  ((DWORD)0x0010)   winbase.h

Clear-To-Send (CTS) signal is on. See GetCommModemStatus.


FN_MS_CTS_ON
MS_CTS_ON  ((DWORD)0x0010)   winbase.h


MS_DSR_ON
MS_DSR_ON  ((DWORD)0x0020)   winbase.h

Data-Set-Ready (DSR) signal is on. See GetCommModemStatus.


FN_MS_DSR_ON
MS_DSR_ON  ((DWORD)0x0020)   winbase.h


MS_RING_ON
MS_RING_ON  ((DWORD)0x0040)   winbase.h

Ring Indicator signal is on. See GetCommModemStatus.


FN_MS_RING_ON
MS_RING_ON  ((DWORD)0x0040)   winbase.h


MS_RLSD_ON
MS_RLSD_ON  ((DWORD)0x0080)   winbase.h

Receive-Line-Signal-Detect (RLSD) signal is on. See GetCommModemStatus.


FN_MS_RLSD_ON
MS_RLSD_ON  ((DWORD)0x0080)   winbase.h


MSGF_DDEMGR
MSGF_DDEMGR  0x8001  ddeml.h

Indicates the input event occurred while the Dynamic Data Exchange Management Library (DDEML) was waiting for a synchronous transaction to complete. For more information about DDEML, see DDEML See MessageProc.


FN_MSGF_DDEMGR
MSGF_DDEMGR  0x8001  ddeml.h


MSGF_DIALOGBOX
MSGF_DIALOGBOX  0  winuser.h

Indicates the input event occurred in a message box or dialog box. See MessageProc, SysMsgProc, WM_ENTERIDLE.


FN_MSGF_DIALOGBOX
MSGF_DIALOGBOX  0  winuser.h


MSGF_MENU
MSGF_MENU  2  winuser.h

Indicates the input event occurred in a menu. See MessageProc, SetWindowsHook, SysMsgProc, WM_ENTERIDLE.


FN_MSGF_MENU
MSGF_MENU  2  winuser.h


MSGF_MESSAGEBOX
MSGF_MESSAGEBOX  1  winuser.h

Processing messages inside the MessageBox function. See SetWindowsHook.


FN_MSGF_MESSAGEBOX
MSGF_MESSAGEBOX  1  winuser.h


MSGF_NEXTWINDOW
MSGF_NEXTWINDOW  6  winuser.h

Indicates the input event occurred as a result of the user pressing the ALT+TAB key combination to activate a different window. See MessageProc, SysMsgProc.


FN_MSGF_NEXTWINDOW
MSGF_NEXTWINDOW  6  winuser.h


MSGF_SCROLLBAR
MSGF_SCROLLBAR  5  winuser.h

Indicates the input event occurred in a scroll bar. See MessageProc, SysMsgProc.


FN_MSGF_SCROLLBAR
MSGF_SCROLLBAR  5  winuser.h


MWT_IDENTITY
MWT_IDENTITY  1  wingdi.h

Resets the current world transformation by using the identity matrix. If this mode is specified, the XFORM structure pointed to by lpXform is ignored. See ModifyWorldTransform.


FN_MWT_IDENTITY
MWT_IDENTITY  1  wingdi.h


MWT_LEFTMULTIPLY
MWT_LEFTMULTIPLY  2  wingdi.h

Multiplies the current transformation by the data in the XFORM structure. (The data in the XFORM structure becomes the left multiplicand while the data for the current transformation becomes the right multiplicand.) See ModifyWorldTransform.


FN_MWT_LEFTMULTIPLY
MWT_LEFTMULTIPLY  2  wingdi.h


MWT_RIGHTMULTIPLY
MWT_RIGHTMULTIPLY  3  wingdi.h

Multiplies the current transformation by the data in the XFORM structure. (The data in the XFORM structure becomes the right multiplicand while the data for the current transformation becomes the left multiplicand.) See ModifyWorldTransform.


FN_MWT_RIGHTMULTIPLY
MWT_RIGHTMULTIPLY  3  wingdi.h


Constants N-Z
Constants N-Z (Win32)

Constant	Meaning

NCBADDGRNAME

Add a group name to the local name table.

See NCB.

NCBADDNAME

Add a unique name to the local name table.

See NCB.

NCBASTAT

Retrieve the status of the adapter. When this value 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.

See NCB.

NCBCALL

Open a session with another name.

See NCB.

NCBCANCEL

Cancel a previous command.

See NCB.

NCBCHAINSEND

Send the contents of two data buffers to the specified session partner. For Windows NT, this is equivalent to NCBCHAINSENDNA.

See NCB.

NCBCHAINSENDNA

Send the contents of two data buffers to the specified session partner and do not wait for acknowledgment. For Windows NT, this is equivalent to NCBCHAINSEND.

See NCB.

NCBDELNAME

Delete a name from the local name table.

See NCB.

NCBDGRECV

Receive a datagram from any name.

See NCB.

NCBDGRECVBC

Receive broadcast datagram from any host.

See NCB.

NCBDGSEND

Send datagram to a specified name.

See NCB.

NCBDGSENDBC

Send a broadcast datagram to every host on the local area network (LAN).

See NCB.

NCBENUM

Enumerate LAN adapter (LANA) numbers. When this value is specified, the ncb_buffer member points to a buffer to be filled with a LANA_ENUM structure.

See NCB.

NCBFINDNAME

Determine the location of a name on the network.

See NCB.

NCBHANGUP

Close a specified session.

See NCB.

NCBLANSTALERT

Notify the user of LAN failures that last for more than one minute.

See NCB.

NCBLISTEN

Enable a session to be opened with another name.

See NCB.

NCBRECV

Receive data from the specified session partner.

See NCB.

NCBRECVANY

Receive data from any session corresponding to a specified name.

See NCB.

NCBRESET

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

See NCB.

NCBSEND

Send data to the specified session partner. For Windows NT, this is equivalent to NCBSENDNA.

See NCB.

NCBSENDNA

Send data to specified session partner and do not wait for an acknowledgment. For Windows NT, this is equivalent to NCBSEND.

See NCB.

NCBSSTAT

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

See NCB.

NCBTRACE

Activate or deactivate NCB tracing. Support for this command in the system is optional and system-specific.

See NCB.

NCBUNLINK

Unlink the adapter.

See NCB.

NMPWAIT_NOWAIT

Do not wait for a named pipe to become available. If the named pipe is not available, an error is returned.

See WaitNamedPipe, CallNamedPipe

NMPWAIT_USE_DEFAULT_WAIT

Wait the default timeout period specified in a call to CreateNamedPipe for a named pipe to become available.

See WaitNamedPipe, CallNamedPipe, CreateNamedPipe

NMPWAIT_WAIT_FOREVER

Wait indefinitely for a named pipe to become available.

See WaitNamedPipe, CallNamedPipe

NO_PROPAGATE_INHERIT_ACE

The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE.

See ACE_HEADER.

NOPARITY

No parity

See DCB.

NORM_IGNORECASE

Ignore case. This bit is not set by default. This option cannot be used with LCMAP_LOWERCASE or LCMAP_UPPERCASE.

See CompareStringW, LCMapStringW.

NORM_IGNORENONSPACE

Ignore nonspacing. This bit is not set by default. This option cannot be used with LCMAP_LOWERCASE or LCMAP_UPPERCASE.

See CompareStringW, LCMapStringW.

NORM_IGNORESYMBOLS

Ignore symbols. This bit is not set by default. This option cannot be used with LCMAP_LOWERCASE or LCMAP_UPPERCASE.

See CompareStringW, LCMapStringW.

NOTSRCCOPY

Copies the inverted source rectangle to the destination.

See BitBlt.

NOTSRCERASE

Combines the colors of the source and destination rectangles by using the Boolean OR operator and inverted.

See BitBlt.

NRC_ACTSES

The command finished; the name has active sessions and is no longer registered.

See NCB.

NRC_BADDR

The buffer address was illegal.

See NCB.

NRC_BRIDGE

The ncb_lana_num member did not specify a valid network number.

See NCB.

NRC_BUFLEN

An illegal buffer length was supplied.

See NCB.

NRC_CANCEL

The NCBCANCEL command was not valid; the command was not canceled.

See NCB.

NRC_CANOCCR

The command was completed while a cancel operation was occurring.

See NCB.

NRC_CMDCAN

The command was cancelled.

See NCB.

NRC_CMDTMO

The command was timed out.

See NCB.

NRC_DUPENV

The name was defined by another local process.

See NCB.

NRC_DUPNAME

A duplicate name existed in the local name table.

See NCB.

NRC_ENVNOTDEF

The environment was not defined. A reset command must be issued.

See NCB.

NRC_GOODRET

The operation succeeded.

See NCB.

NRC_IFBUSY

The interface was busy.

See NCB.

NRC_ILLCMD

An illegal command was supplied.

See NCB.

NRC_ILLNN

An illegal name number was specified.

See NCB.

NRC_INCOMP

The message was incomplete. The application should issue another command.

See NCB.

NRC_INUSE

The name was already in use on the remote adapter.

See NCB.

NRC_INVADDRESS

The NCB address was not valid. This return code is not part of the IBM Netbios 3.0 specification. This return code is not returned in the NCB; instead, it is returned by the Netbios function.

See NCB.

NRC_INVDDID

The NCB DDID was invalid.

See NCB.

NRC_LOCKFAIL

The attempt to lock the user area failed.

See NCB.

NRC_LOCTFUL

The local session table was full.

See NCB.

NRC_MAXAPPS

The maximum number of applications was exceeded.

See NCB.

NRC_NAMCONF

A name conflict was detected.

See NCB.

NRC_NAMERR

The name was deleted.

See NCB.

NRC_NAMTFUL

The name table was full.

See NCB.

NRC_NOCALL

The system did not find the name that was called.

See NCB.

NRC_NORES

No resource was available.

See NCB.

NRC_NORESOURCES

The requested resources were not available.

See NCB.

NRC_NOSAPS

No SAPs available for netbios.

See NCB.

NRC_NOWILD

Wildcards are not permitted in the ncb_name member.

See NCB.

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.

See NCB.

NRC_OSRESNOTAV

Operating system resources were exhausted. The application should retry the command later.

See NCB.

NRC_PENDING

An asynchronous operation is not yet finished.

See NCB.

NRC_REMTFUL

The remote session table was full. The request to open a session was rejected.

See NCB.

NRC_SABORT

The session ended abnormally.

See NCB.

NRC_SCLOSED

The session was closed.

See NCB.

NRC_SNUMOUT

The session number was out of range.

See NCB.

NRC_SYSTEM

A system error occurred.

See NCB.

NRC_TOOMANY

Too many commands were outstanding; the application should retry the command later.

See NCB.

NULL_BRUSH

Null brush (Equivalent to HOLLOW_BRUSH)

See GetStockObject.

NULL_PEN

Null pen

See GetStockObject.

NULLREGION

Region is empty.

See CombineRgn, ExtSelectClipRgn, GetRgnBox, IntersectClipRect, OffsetClipRgn, SelectClipRgn, SelectObject, SetMetaRgn.

NULLREGION

Region is empty.

See OffsetRgn.

NULLREGION

Region is empty.

See ExcludeClipRect, GetClipBox, ExcludeUpdateRgn.

NUMBRUSHES

Number of device-specific brushes.

See GetDeviceCaps.

NUMCOLORS

Number of entries in the device's color table.

See GetDeviceCaps.

NUMFONTS

Number of device-specific fonts.

See GetDeviceCaps.

NUMLOCK_ON

The NUM LOCK light is on.

See KEY_EVENT_RECORD.

NUMPENS

Number of device-specific pens.

See GetDeviceCaps.

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 version 3.0 or later.

See GetDeviceCaps.

OBJ_BITMAP

Bitmap

See GetObjectType.

OBJ_BITMAP

Returns the current selected bitmap if hdc is a memory DC.

See GetCurrentObject.

OBJ_BRUSH

Brush

See GetObjectType.

OBJ_BRUSH

Returns the current selected brush.

See GetCurrentObject.

OBJ_DC

Device context

See GetObjectType.

OBJ_ENHMETADC

Enhanced metafile device context

See GetObjectType.

OBJ_ENHMETAFILE

Enhanced metafile

See GetObjectType.

OBJ_EXTPEN

Extended pen

See GetObjectType.

OBJ_FONT

Font

See GetObjectType.

OBJ_FONT

Returns the current selected font.

See GetCurrentObject.

OBJ_MEMDC

Memory device context

See GetObjectType.

OBJ_METADC

Metafile device context

See GetObjectType.

OBJ_METAFILE

Metafile

See GetObjectType.

OBJ_PAL

Palette

See GetObjectType.

OBJ_PAL

Returns the current selected palette.

See GetCurrentObject.

OBJ_PEN

Pen

See GetObjectType.

OBJ_PEN

Returns the current selected pen.

See GetCurrentObject.

OBJ_REGION

Region

See GetObjectType.

OBJECT_INHERIT_ACE

The ACE is inherited by non-container objects (for example, files) created within the container object to which the ACE is assigned.

See ACE_HEADER.

ODA_DRAWENTIRE

Indicates the entire control needs to be drawn.

See DRAWITEMSTRUCT.

ODA_FOCUS

Indicates the control has lost or gained the keyboard focus. The itemState member should be checked to determine whether the control has the focus.

See DRAWITEMSTRUCT.

ODA_SELECT

Indicates the selection status has changed. The itemState member should be checked to determine the new selection state.

See DRAWITEMSTRUCT.

ODDPARITY

Odd

See DCB.

ODS_CHECKED

Indicates the menu item is to be checked. This bit is used only in a menu.

See DRAWITEMSTRUCT.

ODS_DISABLED

Indicates the item is to be drawn as disabled.

See DRAWITEMSTRUCT.

ODS_FOCUS

Indicates the item has the keyboard focus.

See DRAWITEMSTRUCT.

ODS_GRAYED

Indicates the item is to be grayed. This bit is used only in a menu.

See DRAWITEMSTRUCT.

ODS_SELECTED

Indicates the item's status is selected.

See DRAWITEMSTRUCT.

ODT_BUTTON

Owner-drawn button

See MEASUREITEMSTRUCT, DRAWITEMSTRUCT.

ODT_COMBOBOX

Owner-drawn combo box

See MEASUREITEMSTRUCT, DRAWITEMSTRUCT.

ODT_LISTBOX

Owner-drawn list box

See MEASUREITEMSTRUCT, DRAWITEMSTRUCT.

ODT_MENU

Owner-drawn menu

See MEASUREITEMSTRUCT, DRAWITEMSTRUCT.

OEM_FIXED_FONT

OEM-dependent fixed font

See GetStockObject.

OF_CANCEL

Ignored. In Win32, the OF_PROMPT style produces a dialog box that contains a Cancel button. OF_CANCEL Ignored. In the Win32 API, the OF_PROMPT style produces a dialog box that contains a Cancel button.

See LZOpenFile, OpenFile.

OF_CREATE

Creates a new file. If the file already exists, it is truncated to zero length.

See LZOpenFile, OpenFile.

OF_DELETE

Deletes the file.

See LZOpenFile, OpenFile.

OF_EXIST

Opens the file, and then closes it. Used to test for file existence.

See LZOpenFile, OpenFile.

OF_PARSE

Fills the OFSTRUCT data structure but carries out no other action.

See LZOpenFile, OpenFile.

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. Pressing the Cancel button directs OpenFile to return a file-not-found error message.

See LZOpenFile, OpenFile.

OF_READ

Opens the file for reading only.

See _lopen, LZOpenFile, OpenFile.

OF_READWRITE

Opens the file for reading and writing.

See _lopen, LZOpenFile, OpenFile.

OF_REOPEN

Opens the file using information in the re-open buffer.

See LZOpenFile, OpenFile.

OF_SHARE_COMPAT

Opens the file in compatibility mode, enabling any process on a given machine to open the file any number of times. _lopen fails if the file has been opened by using any of the other share modes.

See _lopen, OpenFile.

OF_SHARE_DENY_NONE

Opens the file without denying other processes read or write access to the file. _lopen fails if the file has been opened in compatibility mode by any other process.

See _lopen, LZOpenFile, OpenFile.

OF_SHARE_DENY_READ

Opens the file and denies other processes read access to the file. _lopen fails if the file has been opened in compatibility mode or for read access by any other process.

See _lopen, LZOpenFile, OpenFile.

OF_SHARE_DENY_WRITE

Opens the file and denies other processes write access to the file. _lopen fails if the file has been opened in compatibility mode or for write access by any other process.

See _lopen, LZOpenFile, OpenFile.

OF_SHARE_EXCLUSIVE

Opens the file in exclusive mode, denying other processes both read and write access to the file. _lopen fails if the file has been opened in any other mode for read or write access, even by the current process.

See _lopen, LZOpenFile, OpenFile.

OF_VERIFY

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

See OpenFile.

OF_WRITE

Opens the file for writing only.

See _lopen, LZOpenFile, OpenFile.

OFN_ALLOWMULTISELECT

Specifies the File Name listbox allows multiple selections. (If the dialog is created by using a private template, the LBS_EXTENDEDSEL constant must appear in the definition of the File Name listbox.)

See OPENFILENAME.

OFN_CREATEPROMPT

Specifies the dialog function should query the user as to whether or not they wish to create a file that does not currently exist. (This flag automatically sets the OFN_PATHMUSTEXIST and OFN_FILEMUSTEXIST flags.)

See OPENFILENAME.

OFN_ENABLEHOOK

Enables the hook function specified in the lpfnHook member.

See OPENFILENAME.

OFN_ENABLETEMPLATE

Causes the operating system to create the dialog box by using the dialog template identified by the hInstance and lpTemplateName members.

See OPENFILENAME.

OFN_ENABLETEMPLATEHANDLE

Indicates the hInstance member identifies a data block that contains a pre-loaded dialog template. The operating system ignores the lpTemplateName member if this flag is specified.

See OPENFILENAME.

OFN_EXTENSIONDIFFERENT

Specifies the user entered a file extension that differs from the extension specified by lpstrDefExt. The function does not set this flag if lpstrDefExt is NULL.

See OPENFILENAME.

OFN_FILEMUSTEXIST

Specifies the user can only enter names of existing files in the File Name entry field. If this flag is set and the user enters an invalid file name in the File Name entry field, the dialog function displays a warning in a message box. The setting of this flag causes the OFN_PATHMUSTEXIST flag to be set.

See OPENFILENAME.

OFN_HIDEREADONLY

Hides the read only checkbox.

See OPENFILENAME.

OFN_NOCHANGEDIR

Forces the dialog box to set the current directory back to what it was when the dialog was invoked.

See OPENFILENAME.

OFN_NONETWORKBUTTON

Hides and disables the network button.

See OPENFILENAME.

OFN_NOREADONLYRETURN

Specifies the returned file does not have the Read Only attribute set and is not in a write-protected directory.

See OPENFILENAME.

OFN_NOTESTFILECREATE

Specifies the file is not created before the dialog box is closed. This flag should be set if the application saves the file on a create-no-modify network share point. When an application sets this flag, the library does not check against write protection, a full disk, an open drive door, or network protection. Therefore, applications using this flag must perform file operations carefully, a file cannot be reopened once closed.

See OPENFILENAME.

OFN_NOVALIDATE

Specifies the common dialog boxes allow invalid characters in the returned filename. Typically, the calling application uses a hook function that checks the filename by using the FILEOKSTRING registered message. If the text in the edit control is empty or contains nothing but spaces, the lists of files and directories are updated. If the text in the edit control contains anything else, the nFileOffset and nFileExtension members are set to values generated by parsing the text. No default extension is added to the text, nor is text copied to the lpstrFileTitle buffer. If the value specified by the nFileOffset member is negative, the filename is invalid. If the value specified by nFileOffset is not negative, the filename is valid, and nFileOffset and nFileExtension can be used as if the OFN_NOVALIDATE flag had not been set.

See OPENFILENAME.

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.

See OPENFILENAME.

OFN_PATHMUSTEXIST

Specifies the user can only enter valid path names. If this flag is set and the user enters an invalid path name in the File Name entry field, the dialog function displays a warning in a message box.

See OPENFILENAME.

OFN_READONLY

Causes the "Read only" checkbox to be initially checked when the dialog box is created. Indicates the state of the "Read only" checkbox when the dialog box is dismissed.

See OPENFILENAME.

OFN_SHAREAWARE

Specifies if a call to the OpenFile function fails because of a network sharing violation, the error is ignored and the dialog box returns the given filename. If this flag is not set, the registered message for SHAREVISTRING is sent to the hook function, with a pointer to a null-terminated string for the path name in the lParam parameter. The hook function responds with one of the following values:

See OPENFILENAME.

OFN_SHAREFALLTHROUGH

Specifies the filename is returned from the dialog box.

See OPENFILENAME.

OFN_SHARENOWARN

Specifies no further action.

See OPENFILENAME.

OFN_SHAREWARN

Specifies the user receives the standard warning message for this error. The same result if there were no hook function.

See OPENFILENAME.

OFN_SHOWHELP

Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified.

See OPENFILENAME.

ONE5STOPBITS

1.5 stop bits

See DCB.

ONESTOPBIT

1 stop bit

See DCB.

OPAQUE

Background is filled with the current background color before the text, hatched brush, or pen is drawn.

See SetBkMode.

OPEN_ALWAYS

Opens the file if it exists. If the file does not exist, the function creates the file as if fdwCreate were CREATE_NEW.

See CreateFile.

OPEN_EXISTING

Opens the file. Fails if the file does not exist.

See CreateFile.

OUTPUT_DEBUG_STRING_EVENT

Reports an output debugging string debugging event. The value of u.DebugString specifies an OUTPUT_DEBUG_STRING_INFO structure.

See DEBUG_EVENT.

OWNER_SECURITY_INFORMATION

When set, this bit indicates the owner ID of the object is being referenced.

See SECURITY_INFORMATION.

PAGE_EXECUTE

Execute access to the committed region of pages is allowed. An attempt to read or write the committed region results in an access violation.

See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx

PAGE_EXECUTE_READ

Execute and read access to the region of committed pages is allowed. An attempt to write the committed region results in an access violation.

See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx

PAGE_EXECUTE_READWRITE

Execute, read, and write access to the region of committed pages is allowed.

See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx

PAGE_EXECUTE_WRITECOPY

Execute, read, and write access to the region of committed pages is allowed. The pages are shared read-on/copy-on-write.

See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx

PAGE_GUARD

Protect 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 value is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.

See  VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx

PAGE_NOACCESS

No access to the committed region of pages is allowed. An attempt to read, write, or execute the committed region results in an access violation.

See VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx

PAGE_NOCACHE

No cacheing of the committed regions of pages is allowed. 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 no cache.

See VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx

PAGE_READONLY

Gives read access to the committed region of pages. An attempt to write or execute the committed region results in an access violation.

See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx

PAGE_READWRITE

Gives read and write access to the committed region of pages.

See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx

PAGE_WRITECOPY

Gives copy-on-write access to the committed region of pages.

See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx

PAN_ANY

Any

See PANOSE.

PAN_BENT_ARMS_DOUBLE_SERIF

Non-Straight Arms/Double-Serif

See PANOSE.

PAN_BENT_ARMS_HORZ

Non-Straight Arms/Horizontal

See PANOSE.

PAN_BENT_ARMS_SINGLE_SERIF

Non-Straight Arms/Single-Serif

See PANOSE.

PAN_BENT_ARMS_VERT

Non-Straight Arms/Vertical

See PANOSE.

PAN_BENT_ARMS_WEDGE

Non-Straight Arms/Wedge

See PANOSE.

PAN_CONTRAST_HIGH

High

See PANOSE.

PAN_CONTRAST_LOW

Low

See PANOSE.

PAN_CONTRAST_MEDIUM

Medium

See PANOSE.

PAN_CONTRAST_MEDIUM_HIGH

Medium High

See PANOSE.

PAN_CONTRAST_MEDIUM_LOW

Medium Low

See PANOSE.

PAN_CONTRAST_NONE

None

See PANOSE.

PAN_CONTRAST_VERY_HIGH

Very High

See PANOSE.

PAN_CONTRAST_VERY_LOW

Very Low

See PANOSE.

PAN_CULTURE_LATIN

Latin

See PANOSE.

PAN_FAMILY_DECORATIVE

Decorative

See PANOSE.

PAN_FAMILY_PICTORIAL

Pictorial

See PANOSE.

PAN_FAMILY_SCRIPT

Script

See PANOSE.

PAN_FAMILY_TEXT_DISPLAY

Text and Display

See PANOSE.

PAN_LETT_NORMAL_BOXED

Normal/Boxed

See PANOSE.

PAN_LETT_NORMAL_CONTACT

Normal/Contact

See PANOSE.

PAN_LETT_NORMAL_FLATTENED

Normal/Flattened

See PANOSE.

PAN_LETT_NORMAL_OFF_CENTER

Normal/Off Center

See PANOSE.

PAN_LETT_NORMAL_ROUNDED

Normal/Rounded

See PANOSE.

PAN_LETT_NORMAL_SQUARE

Normal/Square

See PANOSE.

PAN_LETT_NORMAL_WEIGHTED

Normal/Weighted

See PANOSE.

PAN_LETT_OBLIQUE_BOXED

Oblique/Boxed

See PANOSE.

PAN_LETT_OBLIQUE_CONTACT

Oblique/Contact

See PANOSE.

PAN_LETT_OBLIQUE_FLATTENED

Oblique/Flattened

See PANOSE.

PAN_LETT_OBLIQUE_OFF_CENTER

Oblique/Off Center

See PANOSE.

PAN_LETT_OBLIQUE_ROUNDED

Oblique/Rounded

See PANOSE.

PAN_LETT_OBLIQUE_SQUARE

Oblique/Square

See PANOSE.

PAN_LETT_OBLIQUE_WEIGHTED

Oblique/Weighted

See PANOSE.

PAN_MIDLINE_CONSTANT_POINTED

Constant/Pointed

See PANOSE.

PAN_MIDLINE_CONSTANT_SERIFED

Constant/Serifed

See PANOSE.

PAN_MIDLINE_CONSTANT_TRIMMED

Constant/Trimmed

See PANOSE.

PAN_MIDLINE_HIGH_POINTED

High/Pointed

See PANOSE.

PAN_MIDLINE_HIGH_SERIFED

High/Serifed

See PANOSE.

PAN_MIDLINE_HIGH_TRIMMED

High/Trimmed

See PANOSE.

PAN_MIDLINE_LOW_POINTED

Low/Pointed

See PANOSE.

PAN_MIDLINE_LOW_SERIFED

Low/Serifed

See PANOSE.

PAN_MIDLINE_LOW_TRIMMED

Low/Trimmed

See PANOSE.

PAN_MIDLINE_STANDARD_POINTED

Standard/Pointed

See PANOSE.

PAN_MIDLINE_STANDARD_SERIFED

Standard/Serifed

See PANOSE.

PAN_MIDLINE_STANDARD_TRIMMED

Standard/Trimmed

See PANOSE.

PAN_NO_FIT

No Fit

See PANOSE.

PAN_NO_FIT

No Fit

See PANOSE.

PAN_PROP_CONDENSED

Condensed

See PANOSE.

PAN_PROP_EVEN_WIDTH

Even Width

See PANOSE.

PAN_PROP_EXPANDED

Expanded

See PANOSE.

PAN_PROP_MODERN

Modern

See PANOSE.

PAN_PROP_MONOSPACED

Monospaced

See PANOSE.

PAN_PROP_OLD_STYLE

Old Style

See PANOSE.

PAN_PROP_VERY_CONDENSED

Very Condensed

See PANOSE.

PAN_PROP_VERY_EXPANDED

Very Expanded

See PANOSE.

PAN_SERIF_BONE

Bone

See PANOSE.

PAN_SERIF_COVE

Cove

See PANOSE.

PAN_SERIF_EXAGGERATED

Exaggerated

See PANOSE.

PAN_SERIF_FLARED

Flared

See PANOSE.

PAN_SERIF_NORMAL_SANS

Normal Sans

See PANOSE.

PAN_SERIF_OBTUSE_COVE

Obtuse Cove

See PANOSE.

PAN_SERIF_OBTUSE_SANS

Obtuse Sans

See PANOSE.

PAN_SERIF_OBTUSE_SQUARE_COVE

Obtuse Square Cove

See PANOSE.

PAN_SERIF_PERP_SANS

Prep Sans

See PANOSE.

PAN_SERIF_ROUNDED

Rounded

See PANOSE.

PAN_SERIF_SQUARE

Square

See PANOSE.

PAN_SERIF_SQUARE_COVE

Square Cove

See PANOSE.

PAN_SERIF_THIN

Thin

See PANOSE.

PAN_SERIF_TRIANGLE

Triangle

See PANOSE.

PAN_STRAIGHT_ARMS_DOUBLE_SERIF

Straight Arms/Double-Serif

See PANOSE.

PAN_STRAIGHT_ARMS_HORZ

Straight Arms/Horizontal

See PANOSE.

PAN_STRAIGHT_ARMS_SINGLE_SERIF

Straight Arms/Single-Serif

See PANOSE.

PAN_STRAIGHT_ARMS_VERT

Straight Arms/Vertical

See PANOSE.

PAN_STRAIGHT_ARMS_WEDGE

Straight Arms/Wedge

See PANOSE.

PAN_STROKE_GRADUAL_DIAG

Gradual/Diagonal

See PANOSE.

PAN_STROKE_GRADUAL_HORZ

Gradual/Horizontal

See PANOSE.

PAN_STROKE_GRADUAL_TRAN

Gradual/Transitional

See PANOSE.

PAN_STROKE_GRADUAL_VERT

Gradual/Vertical

See PANOSE.

PAN_STROKE_INSTANT_VERT

Instant/Vertical

See PANOSE.

PAN_STROKE_RAPID_HORZ

Rapid/Horizontal

See PANOSE.

PAN_STROKE_RAPID_VERT

Rapid/Vertical

See PANOSE.

PAN_WEIGHT_BLACK

Black

See PANOSE.

PAN_WEIGHT_BOLD

Bold

See PANOSE.

PAN_WEIGHT_BOOK

Book

See PANOSE.

PAN_WEIGHT_DEMI

Demi

See PANOSE.

PAN_WEIGHT_HEAVY

Heavy

See PANOSE.

PAN_WEIGHT_LIGHT

Light

See PANOSE.

PAN_WEIGHT_MEDIUM

Medium

See PANOSE.

PAN_WEIGHT_NORD

Nord

See PANOSE.

PAN_WEIGHT_THIN

Thin

See PANOSE.

PAN_WEIGHT_VERY_LIGHT

Very Light

See PANOSE.

PAN_XHEIGHT_CONSTANT_LARGE

Constant/Large

See PANOSE.

PAN_XHEIGHT_CONSTANT_SMALL

Constant/Small

See PANOSE.

PAN_XHEIGHT_CONSTANT_STD

Constant/Standard

See PANOSE.

PAN_XHEIGHT_DUCKING_LARGE

Ducking/Large

See PANOSE.

PAN_XHEIGHT_DUCKING_SMALL

Ducking/Small

See PANOSE.

PAN_XHEIGHT_DUCKING_STD

Ducking/Standard

See PANOSE.

PATCOPY

Copies the specified pattern into the destination bitmap.

See BitBlt, PatBlt.

PATINVERT

Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean XOR operator.

See BitBlt, PatBlt.

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.

See BitBlt.

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.

See PALETTEENTRY.

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.

See PALETTEENTRY.

PC_RESERVED

Specifies that the logical palette entry be used for palette animation; this prevents other windows from matching colors to this palette entry since the color frequently changes. If an unused system-palette entry is available, this color is placed in that entry. Otherwise, the color is available for animation.

See PALETTEENTRY.

PD_ALLPAGES

Indicates the All radio button was selected when the user closed the dialog box. (This value is used as a placeholder, to indicate the PD_PAGENUMS and PD_SELECTION flags are not set. This value can be set on input and on output.)

See PRINTDLG, PrintDlg.

PD_COLLATE

Causes the Collate checkbox to be in the checked state when the dialog box is created. When the PrintDlg function returns, this flag indicates the state the Collate checkbox was left in by the user.

See PRINTDLG, PrintDlg.

PD_DISABLEPRINTTOFILE

Disables the Print to File check box.

See PRINTDLG, PrintDlg.

PD_ENABLEPRINTHOOK

Enables the hook function specified in the lpfnPrintHook member of this structure.

See PRINTDLG, PrintDlg.

PD_ENABLEPRINTTEMPLATE

Causes the operating system to create the dialog box by using the dialog template identified by the hInstance and lpPrintTemplateName members.

See PRINTDLG, PrintDlg.

PD_ENABLEPRINTTEMPLATEHANDLE

Indicates that the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpPrintTemplateName member if this flag is specified.

See PRINTDLG, PrintDlg.

PD_ENABLESETUPHOOK

Enables the hook function specified in the lpfnSetupHook member of this structure.

See PRINTDLG, PrintDlg.

PD_ENABLESETUPTEMPLATE

Causes the operating system to create the dialog box by using the dialog template identified by the hInstance and lpSetupTemplateName members.

See PRINTDLG, PrintDlg.

PD_ENABLESETUPTEMPLATEHANDLE

Indicates the hInstance member identifies a data block that contains a pre-loaded dialog template. The operating system ignores the lpSetupTemplateName member if this flag is specified.

See PRINTDLG, PrintDlg.

PD_HIDEPRINTTOFILE

Hides and disables the Print to File check box.

See PRINTDLG, PrintDlg.

PD_NOPAGENUMS

Disables the Pages radio button and the associated edit control.

See PRINTDLG, PrintDlg.

PD_NOSELECTION

Disables the Selection radio button.

See PRINTDLG, PrintDlg.

PD_NOWARNING

Prevents the warning message from being displayed when there is no default printer.

See PRINTDLG, PrintDlg.

PD_PAGENUMS

Causes the Pages radio button to be in the selected state when the dialog box is created. When the PrintDlg function returns, this flag is set if the Pages radion button is in the selected state.

See PRINTDLG, PrintDlg.

PD_PRINTSETUP

Causes the system to display the Print Setup dialog box rather than the Print dialog box.

See PRINTDLG, PrintDlg.

PD_PRINTTOFILE

Causes the Print to File check box to be in the checked state when the dialog box is created. When the PrintDlg function returns, the pOutput member of the DEVNAMES structure points to the "FILE:" string.

See PRINTDLG, PrintDlg.

PD_RETURNDC

Causes the PrintDlg function to return a device context matching the selections the user made in the dialog box. The device context is returned in the hDC member.

See PRINTDLG, PrintDlg.

PD_RETURNDEFAULT

Causes the PrintDlg function to return DEVMODE and DEVNAME structures that are initialized for the system default printer. It does this without displaying a dialog box. It is assumed that both the hDevNames and the hDevMode members are NULL; otherwise, the function returns an error. If the system default printer is supported by an old printer driver (pre-3.0), only the hDevNames member is returned--the hDevMode member is NULL.

See PRINTDLG, PrintDlg.

PD_RETURNIC

Similar to the PD_RETURNDC flag except this flag returns an information context rather than a device context. If neither PD_RETURNDC nor PD_RETURNIC are specified, the hDC parameter is undefined on output.

See PRINTDLG, PrintDlg.

PD_SELECTION

Causes the Selection radio button to be in the selected state when the dialog box is created. When the PrintDlg function returns, this flag is set if the Selection radio button is in the selected state. If neither PD_PAGENUMS nor PD_SELECTION are specified, the All radio button is in the selected state.

See PRINTDLG, PrintDlg.

PD_SHOWHELP

Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified.

See PRINTDLG, PrintDlg.

PD_USEDEVMODECOPIES

If a printer driver does not support multiple copies, setting this flag disables the Copies edit control; if a driver does support multiple copies, setting this flag indicates the PrintDlg function should store the requested number of copies in the dmCopies member of the DEVMODE data structure and store the value 1 in the nCopies member of the PRINTDLG data structure. If this flag is not set, the PrintDlg structure stores the value 1 in the dmCopies member of the DEVMODE structure and stores the requested number of copies in the nCopies member of the PRINTDLG data structure.

See PRINTDLG, PrintDlg.

PDERR_CREATEICFAILURE

Specifies the PrintDlg function failed when it attempted to create an information context.

See CommDlgExtendedError.

PDERR_DEFAULTDIFFERENT

Specifies an application called the PrintDlg function with the DN_DEFAULTPRN flag set 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 happens when an application stores the DEVNAMES structure and the user changes the default printer by using Control Panel.) To use the printer described by the DEVNAMES structure, the application should clear the DN_DEFAULTPRN flag and call the PrintDlg function again. To use the default printer, the application should replace the DEVNAMES structure (and the DEVMODE structure, if one exists) with NULL; this selects the default printer automatically.

See CommDlgExtendedError.

PDERR_DNDMMISMATCH

Specifies the data in the DEVMODE and DEVNAMES structures describes two different printers.

See CommDlgExtendedError.

PDERR_GETDEVMODEFAIL

Specifies the printer driver failed to initialize a DEVMODE structure. (This error value applies only to printer drivers written for Windows versions 3.0 and later.)

See CommDlgExtendedError.

PDERR_INITFAILURE

Indicates that the PrintDlg function failed during initialization, and that there is no more specific extended error code to describe the failure. Think of this as the generic default error code for that function.

See CommDlgExtendedError.

PDERR_LOADDRVFAILURE

Specifies the PrintDlg function failed to load the device driver for the specified printer.

See CommDlgExtendedError.

PDERR_NODEFAULTPRN

Specifies a default printer does not exist.

See CommDlgExtendedError.

PDERR_NODEVICES

Specifies no printer drivers were found.

See CommDlgExtendedError.

PDERR_PARSEFAILURE

Specifies the PrintDlg function failed to parse the strings in the [devices] section of the WIN.INI file.

See CommDlgExtendedError.

PDERR_PRINTERNOTFOUND

Specifies the [devices] section of the WIN.INI file did not contain an entry for the requested printer.

See CommDlgExtendedError.

PDERR_RETDEFFAILURE

Specifies the PD_RETURNDEFAULT flag was set in the Flags member of the PRINTDLG structure but the hDevMode or hDevNames member was nonzero.

See CommDlgExtendedError.

PDERR_SETUPFAILURE

Specifies the PrintDlg function failed to load the required resources.

See CommDlgExtendedError.

PDEVICESIZE

Reserved.

See GetDeviceCaps.

PERF_100NSEC_MULTI_TIMER

64-bit Timer in 100 nsec units. Display delta divided by delta time. The display suffix is "%". This timer is for multiple instances, so the result can exceed 100%.

See PERF_COUNTER_DEFINITION.

PERF_100NSEC_MULTI_TIMER_INV

64-bit Timer inverse. (That is, idle is measured.) Display 100 * _MULTI_BASE - delta divided by delta time. The display suffix is "%". This timer is for multiple instances, so the result can exceed 100%. Followed by a counter of type PERF_COUNTER_MULTI_BASE.

See PERF_COUNTER_DEFINITION.

PERF_100NSEC_TIMER

64-bit Timer in 100 nsec units. Divide delta by delta time. The display suffix is "%".

See PERF_COUNTER_DEFINITION.

PERF_100NSEC_TIMER_INV

64-bit Timer inverse. (That is, idle is measured.) Display 100 - delta divided by delta time. The display suffix is "%".

See PERF_COUNTER_DEFINITION.

PERF_AVERAGE_BASE

Used as the denominator in the computation of time or count averages. Must directly follow the numerator counter. Do not display this value to the user.

See PERF_COUNTER_DEFINITION.

PERF_AVERAGE_BULK

A bulk count which, when divided by the number of operations, typically provides the number of bytes per operation.

See PERF_COUNTER_DEFINITION.

PERF_AVERAGE_TIMER

A timer which, when divided by an average base, produces a time in seconds which is the average time of some operation. This timer times total operations, and the base is the number of operations. The display suffix is "sec".

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_BULK_COUNT

64-bit Counter. Divide delta by delta time. The display suffix is "/sec".

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_COUNTER

32-bit counter. Divide delta by delta time. The display suffix is "/sec".

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_HISTOGRAM

Counter begins or ends a histogram.

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_MULTI_BASE

Number of instances to which the preceeding PERF_COUNTER_MULTI_TIMER_INV counter applies. This value is used as a factor to get the percentage.

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_MULTI_TIMER

64-bit Timer. Divide delta by delta time. The display suffix is "%". This timer is for multiple instances, so the result can exceed 100%.

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_MULTI_TIMER_INV

64-bit Timer inverse. (That is, idle is measured.) Display 100 * _MULTI_BASE - delta divided by delta time. The display suffix is "%". This timer is for multiple instances, so the result can exceed 100%. Followed by a counter of type PERF_COUNTER_MULTI_BASE.

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_NODATA

A label: no data is associated with this counter (it has 0 length) Do not display.

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_QUEUELEN

Queue Length Space-Time Product. Divide delta by delta time.

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_RAWCOUNT

The data is a counter which should not be time averaged on display, such as an error counter on a serial line.

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_TEXT

The counter is Unicode text, not a counter.

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_TIMER

64-bit Timer. Divide delta by delta time. The display suffix is "%".

See PERF_COUNTER_DEFINITION.

PERF_COUNTER_TIMER_INV

64-bit timer inverse. (That is, idle is measured.) Display 100 - delta divided by delta time. The display suffix is "%".

See PERF_COUNTER_DEFINITION.

PERF_DETAIL_ADVANCED

Data designed for the advanced user.

See PERF_COUNTER_DEFINITION, PERF_OBJECT_TYPE.

PERF_DETAIL_EXPERT

Data designed for the expert user.

See PERF_COUNTER_DEFINITION, PERF_OBJECT_TYPE.

PERF_DETAIL_NOVICE

Data can be understood by the uninformed user.

See PERF_COUNTER_DEFINITION, PERF_OBJECT_TYPE.

PERF_DETAIL_WIZARD

Data designed for the system designer.

See PERF_COUNTER_DEFINITION, PERF_OBJECT_TYPE.

PERF_RAW_BASE

Indicates the data is a base for the preceeding counter which should not be time averaged on display, such as free space over total space.

See PERF_COUNTER_DEFINITION.

PERF_RAW_FRACTION

Indicates the data is a fraction of the following counter which should not be time averaged on display, such as free space over total space. Display the quotient as "%".

See PERF_COUNTER_DEFINITION.

PERF_SAMPLE_BASE

The divisor for a sample, used with the previous counter to form a sampled percentage. You must check for > 0 before dividing by this value. This counter will directly follow the numerator counter and should not be displayed.

See PERF_COUNTER_DEFINITION.

PERF_SAMPLE_COUNTER

A count which is sampled on each sampling interrupt (queue length) Divide delta by delta time.

See PERF_COUNTER_DEFINITION.

PERF_SAMPLE_FRACTION

A count which is either 1 or 0 on each sampling interrupt (% busy) Divide delta by delta base. The display suffix is "%".

See PERF_COUNTER_DEFINITION.

PLANES

Number of color planes.

See GetDeviceCaps.

PM_NOREMOVE

Indicates the message has not been removed from the queue. (An application called the PeekMessage function, specifying the PM_NOREMOVE flag.)

See GetMsgProc, PeekMessage.

PM_REMOVE

Indicates the message has been removed from the queue. (An application called the GetMessage function, or it called the PeekMessage function, specifying the PM_REMOVE flag.)

See GetMsgProc, PeekMessage.

POLYGONALCAPS

A bitmask that indicates the polygonal capabilities of the device.

See GetDeviceCaps.

PRINTER_CONTROL_PAUSE

Pause the printer.

See SetPrinter.

PRINTER_CONTROL_PURGE

Delete all the print jobs in the printer.

See SetPrinter.

PRINTER_CONTROL_RESUME

Resume a paused printer.

See SetPrinter.

PRINTER_ENUM_LOCAL

Enumerate locally installed printers.

See EnumPrinters.

PRINTER_ENUM_NAME

Enumerate the printer identified by lpszName. This could be a server lpszName, or a domain lpszName.

See EnumPrinters.

PRINTER_ENUM_REMOTE

Enumerated network printers.

See EnumPrinters.

PRINTER_ENUM_SHARED

Enumerate printers with the shared attribute.

See EnumPrinters.

PRINTER_FONTTYPE

Specifies that the font is a printer font.

See CHOOSEFONT, ChooseFont.

PRIVILEGE_SET_ALL_NECESSARY

Indicates that all of the specified privileges must be held by the process requesting accesss. If this flag is not set, then the presence of any the privileges in the process's access token grants the access.

See PRIVILEGE_SET.

PROCESS_ALL_ACCESS

Specifies all possible access flags for the process object.

See DuplicateHandle.

PROCESS_CREATE_THREAD

Enables using the process handle in the CreateRemoteThread function to create a thread in the process.

See DuplicateHandle.

PROCESS_DUP_HANDLE

Enables using the process handle as either the source or target process in the DuplicateHandle function to duplicate a handle.

See DuplicateHandle.

PROCESS_QUERY_INFORMATION

Enables using the process handle in the GetExitCodeProcess and GetPriorityClass functions to read information from the process object.

See DuplicateHandle.

PROCESS_SET_INFORMATION

Enables using the process handle in the SetPriorityClass function to set the process's priority class.

See DuplicateHandle.

PROCESS_TERMINATE

Enables using the process handle in the TerminateProcess function to terminate the process.

See DuplicateHandle.

PROCESS_VM_OPERATION

Enables using the process handle in the VirtualProtectEx and WriteProcessMemory functions to modify the virtual memory of the process.

See DuplicateHandle.

PROCESS_VM_READ

Enables using the process handle in the ReadProcessMemory function to read from the virtual memory of the process.

See DuplicateHandle.

PROCESS_VM_WRITE

Enables using the process handle in the WriteProcessMemory function to write to the virtual memory of the process.

See DuplicateHandle.

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. Bold, italic, underline, and strikeout fonts are synthesized if necessary.

See CreateFont, LOGFONT.

PS_ALTERNATE

The pen sets every other pixel. (This style is only applicable for cosmetic pens.)

See ExtCreatePen.

PS_COSMETIC

Creates a cosmetic pen.

See ExtCreatePen, EXTLOGPEN.

PS_DASH

Creates a dashed pen. Valid only when the pen width is one or less in device untis.

See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.

PS_DASHDOT

Creates a pen with alternating dashes and dots. Valid only when the pen width is one or less in device untis.

See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.

PS_DASHDOTDOT

Creates a pen with alternating dashes and double-dots. Valid only when the pen width is one or less in device untis.

See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.

PS_DOT

Creates a dotted pen. Valid only when the pen width is one or less in device units.

See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.

PS_ENDCAP_FLAT

Line end caps are flat.

See ExtCreatePen, EXTLOGPEN.

PS_ENDCAP_ROUND

Line end caps are round.

See ExtCreatePen, EXTLOGPEN.

PS_ENDCAP_SQUARE

Line end caps are square.

See ExtCreatePen, EXTLOGPEN.

PS_GEOMETRIC

Creates a geometric pen.

See ExtCreatePen, EXTLOGPEN.

PS_INSIDEFRAME

Creates a solid pen. When this pen is used in any GDI drawing function that takes a bounding rectangle, the dimensions of the figure will be shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen.

See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.

PS_JOIN_BEVEL

Line joins are beveled.

See ExtCreatePen, EXTLOGPEN.

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.

See ExtCreatePen, EXTLOGPEN.

PS_JOIN_ROUND

Line joins are round.

See ExtCreatePen, EXTLOGPEN.

PS_NULL

Creates a null pen.

See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.

PS_SOLID

Creates a solid pen.

See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.

PS_USERSTYLE

A styling array supplied by the user is to be used.

See ExtCreatePen, EXTLOGPEN.

PT_BEZIERTO

Specifies that the corresponding point in lpPoints is a control point or end point for a Bézier curve. PT_BEZIERTO types 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 end (if hard-coded) point.

See GetPath, PolyDraw.

PT_CLOSEFIGURE

This flag specifies that the figure is automatically closed after the PT_LINETO or PT_BEZIERTO constant for this point is done. A line is to be drawn from this point to the previous PT_MOVETO point. This flag is combined with the PT_LINETO type for a line, or with the PT_BEZIERTO type of the end point for a Bézier curve, by using the bit-wise operator OR.

See GetPath, PolyDraw.

PT_LINETO

Specifies that a line is to be drawn from the current position to this point, which then becomes the new current position.

See GetPath, PolyDraw.

PT_MOVETO

Specifies that the corresponding point in lpPoints starts a disjoint figure.

See GetPath, PolyDraw.

PWR_CRITICALRESUME

Indicates that the system is resuming operation after entering the suspended mode without first sending a PWR_SUSPENDREQUEST notification message to the application. An application should perform any necessary recovery actions.

See WM_POWER.

PWR_SUSPENDREQUEST

Indicates that the system is about to enter the suspended mode.

See WM_POWER.

PWR_SUSPENDRESUME

Indicates that the system is resuming operation after having entered the 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.

See WM_POWER.

QS_ALLINPUT

Any message, including sent messages, is in the queue. This is equivalent to the combination QS_ALLEVENTS | QS_SENDMESSAGE.

See GetQueueStatus.

QS_ALLEVENTS

Any message, other than a sent message, is in the queue. This is equivalent to the combination QS_INPUT | QS_HOTKEY | QS_PAINT | QS_TIMER | QS_POSTMESSAGE.

See GetQueueStatus.

QS_HOTKEY

A WM_HOTKEY message is in the queue.

See GetQueueStatus.

QS_INPUT

An input message is in the queue. This is equivalent to the combination QS_KEY | QS_MOUSE.

See GetQueueStatus.

QS_KEY

A WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, or WM_SYSKEYDOWN message is in the queue.

See GetQueueStatus.

QS_MOUSE

A WM_MOUSEMOVE or WM_*BUTTON* message is in the queue. This is equivalent to the combination QS_MOUSEBUTTON | QS_MOUSEMOVE.

See GetQueueStatus.

QS_MOUSEBUTTON

A WM_*BUTTON* message is in the queue.

See GetQueueStatus.

QS_MOUSEMOVE

A WM_MOUSEMOVE message is in the queue.

See GetQueueStatus.

QS_PAINT

A WM_PAINT message is in the queue.

See GetQueueStatus.

QS_POSTMESSAGE

A posted message (other than those covered by QS_HOTKEY, QS_PAINT, QS_TIMER, QS_MOUSEBUTTON, QS_MOUSEMOVE, and QS_KEY) is in the queue.

See GetQueueStatus.

QS_SENDMESSAGE

A message sent by another thread or process is in the queue.

See GetQueueStatus.

QS_TIMER

A WM_TIMER message is in the queue.

See GetQueueStatus.

R2_BLACK

Pixel is always binary 0.

See SetROP2.

R2_COPYPEN

Pixel is the pen color.

See SetROP2.

R2_MASKNOTPEN

Pixel is a combination of the colors common to both the display and the inverse of the pen.

See SetROP2.

R2_MASKPEN

Pixel is a combination of the colors common to both the pen and the display.

See SetROP2.

R2_MASKPENNOT

Pixel is a combination of the colors common to both the pen and the inverse of the display.

See SetROP2.

R2_MERGENOTPEN

Pixel is a combination of the display color and the inverse of the pen color.

See SetROP2.

R2_MERGEPEN

Pixel is a combination of the pen color and the display color.

See SetROP2.

R2_MERGEPENNOT

Pixel is a combination of the pen color and the inverse of the display color.

See SetROP2.

R2_NOP

Pixel remains unchanged.

See SetROP2.

R2_NOT

Pixel is the inverse of the display color.

See SetROP2.

R2_NOTCOPYPEN

Pixel is the inverse of the pen color.

See SetROP2.

R2_NOTMASKPEN

Pixel is the inverse of the R2_MASKPEN color.

See SetROP2.

R2_NOTMERGEPEN

Pixel is the inverse of the R2_MERGEPEN color.

See SetROP2.

R2_NOTXORPEN

Pixel is the inverse of the R2_XORPEN color.

See SetROP2.

R2_WHITE

Pixel is always binary 1.

See SetROP2.

R2_XORPEN

Pixel is a combination of the colors in the pen and in the display, but not in both.

See SetROP2.

RASTERCAPS

Value that indicates the raster capabilities of the device, as shown in the following list:

See GetDeviceCaps.

RC_BANDING

Requires banding support.

See GetDeviceCaps.

RC_BITBLT

Capable of transferring bitmaps.

See GetDeviceCaps.

RC_BITMAP64

Capable of supporting bitmaps larger than 64K.

See GetDeviceCaps.

RC_DI_BITMAP

Capable of supporting the SetDIBits and GetDIBits functions.

See GetDeviceCaps.

RC_DIBTODEV

Capable of supporting the SetDIBitsToDevice function.

See GetDeviceCaps.

RC_FLOODFILL

Capable of performing flood fills.

See GetDeviceCaps.

RC_GDI20_OUTPUT

Capable of supporting features of Windows 2.0.

See GetDeviceCaps.

RC_PALETTE

Specifies palette-based device.

See GetDeviceCaps.

RC_SCALING

Capable of scaling.

See GetDeviceCaps.

RC_STRETCHBLT

Capable of performing the StretchBlt function.

See GetDeviceCaps.

RC_STRETCHDIB

Capable of performing the StretchDIBits function.

See GetDeviceCaps.

RDW_ALLCHILDREN

Includes child windows, if any, in the repainting operation.

See RedrawWindow.

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.

See RedrawWindow.

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.

See RedrawWindow.

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 the RedrawWindow function unless either RDW_UPDATENOW or RDW_ERASENOW is specified.

See RedrawWindow.

RDW_INTERNALPAINT

Causes a WM_PAINT message to be posted to the window regardless of whether any portion of the window is invalid.

See RedrawWindow.

RDW_INVALIDATE

Invalidate lprcUpdate or hrgnUpdate (only one may be non-NULL). If both are NULL, the entire window is invalidated.

See RedrawWindow.

RDW_NOCHILDREN

Excludes child windows, if any, from the repainting operation.

See RedrawWindow.

RDW_NOERASE

Suppresses any pending WM_ERASEBKGND messages.

See RedrawWindow.

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 from painting properly.

See RedrawWindow.

RDW_NOINTERNALPAINT

Suppresses any pending internal WM_PAINT messages. This flag does not affect WM_PAINT messages resulting from a non-NULL update area.

See RedrawWindow.

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.

See RedrawWindow.

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.

See RedrawWindow.

REG_BINARY

Binary data in any form.

See RegSetValueEx.

REG_CREATED_NEW_KEY

The key did not exist and was created.

See RegCreateKeyEx.

REG_DWORD

A 32-bit number.

See RegSetValueEx.

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

See RegSetValueEx.

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 word. This is the standard format for Intel and Motorola microprocessors.

See RegSetValueEx.

REG_EXPAND_SZ

A null-terminated Unicode string that contains unexpanded references to environment variables (for example, "%PATH%").

See RegSetValueEx.

REG_LINK

A Unicode symbolic link.

See RegSetValueEx.

REG_MULTI_SZ

An array of null-terminated strings, terminated by two null characters.

See RegSetValueEx.

REG_NONE

No defined value type.

See RegSetValueEx.

REG_NOTIFY_CHANGE_ATTRIBUTES

Any attribute changes that occur in a key or subtree being watched cause a change notification.

See RegNotifyChangeKeyValue.

REG_NOTIFY_CHANGE_LAST_SET

Any changes to the last write time that occur in a key or subtree being watched cause a change notification.

See RegNotifyChangeKeyValue.

REG_NOTIFY_CHANGE_NAME

Any changes to key names that occur in a key or subtree being watched cause a change-notification wait. This includes key creations and deletions.

See RegNotifyChangeKeyValue.

REG_NOTIFY_CHANGE_SECURITY

Any security-descriptor changes that occur in a key or subtree being watched cause a change notification.

See RegNotifyChangeKeyValue.

REG_OPENED_EXISTING_KEY

The key existed, and was simply opened without being changed.

See RegCreateKeyEx.

REG_OPTION_NON_VOLATILE

This key is not volatile. The information is stored in a file and is preserved when the system is restarted.

See RegCreateKeyEx.

REG_OPTION_VOLATILE

This key is volatile. The information is stored in memory and is not preserved when the system is restarted.

See RegCreateKeyEx.

REG_RESOURCE_LIST

A device-driver resource list.

See RegSetValueEx.

REG_SZ

A null-terminated string. It will be a UNICODE or ANSI string depending on whether you use the UNICODE or ANSI functions. For example, if you call RegEnumValueW, you get back a UNICODE string, and if you call RegEnumValueA, you get back an ANSI string.

See RegSetValueEx.

REG_WHOLE_HIVE_VOLATILE

Instead of restoring the specified 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. HKEY_LOCAL_MACHINE\Hardware, for example, is a volatile hive.) If this flag is specified, the key identified by the hkey parameter must be either HKEY_USERS or HKEY_LOCAL_MACHINE.

See RegRestoreKey.

REGISTERED

The name specified by the name member has been successfully added to the network.

See NAME_BUFFER.

REGISTERING

The name specified by the name member is being added to the network.

See NAME_BUFFER.

RESOURCE_CONNECTED

All currently connected resources (fdwUsage is ignored).

See WNetOpenEnum, NETRESOURCE.

RESOURCE_GLOBALNET

All resources on the network.

See WNetOpenEnum, NETRESOURCE.

RESOURCE_REMEMBERED

All remembered connections (fdwUsage is ignored).

See WNetOpenEnum, NETRESOURCE.

RESOURCEDISPLAYTYPE_DOMAIN

The object should be displayed as a domain.

See NETRESOURCE.

RESOURCEDISPLAYTYPE_GENERIC

The method used to display the object does not matter.

See NETRESOURCE.

RESOURCEDISPLAYTYPE_SERVER

The object should be displayed as a server.

See NETRESOURCE.

RESOURCEDISPLAYTYPE_SHARE

The object should be displayed as a sharepoint.

See NETRESOURCE.

RESOURCETYPE_ANY

All resources. (This value cannot be combined with RESOURCETYPE_DISK or RESOURCETYPE_PRINT.)

See WNetOpenEnum.

RESOURCETYPE_ANY

All resources

See NETRESOURCE.

RESOURCETYPE_DISK

All disk resources.

See WNetOpenEnum.

RESOURCETYPE_DISK

Connect to disk resources.

See WNetConnectionDialog.

RESOURCETYPE_DISK

Disk resources

See NETRESOURCE.

RESOURCETYPE_PRINT

All print resources.

See WNetOpenEnum.

RESOURCETYPE_PRINT

Connect to print resources.

See WNetConnectionDialog.

RESOURCETYPE_PRINT

Print resources

See NETRESOURCE.

RESOURCEUSAGE_CONNECTABLE

This is a connectable resource; lpRemoteName can be passed to the WNetAddConnection function to make a network connection.

See NETRESOURCE.

RESOURCEUSAGE_CONNECTABLE

All connectable resources.

See WNetOpenEnum.

RESOURCEUSAGE_CONTAINER

This is a container resource; lpRemoteName can be passed to the WNetOpenEnum function to enumerate the resources in the container.

See NETRESOURCE.

RESOURCEUSAGE_CONTAINER

All container resources.

See WNetOpenEnum.

RGN_AND

Creates the intersection of the two combined regions.

See CombineRgn, ExtSelectClipRgn, SelectClipPath.

RGN_COPY

Creates a copy of the region.

See CombineRgn, ExtSelectClipRgn, SelectClipPath.

RGN_DIFF

The new clipping region includes the areas of the current clipping region with those of the current path excluded.

See CombineRgn, ExtSelectClipRgn, SelectClipPath.

RGN_OR

Creates the union of the two combined regions.

See CombineRgn, ExtSelectClipRgn, SelectClipPath.

RGN_XOR

Creates the union of the two combined regions except for the overlapping areas.

See CombineRgn, ExtSelectClipRgn, SelectClipPath.

RIGHT_ALT_PRESSED

The right-hand ALT key is pressed.

See KEY_EVENT_RECORD.

RIGHT_CTRL_PRESSED

The right-hand CTRL key is pressed.

See KEY_EVENT_RECORD.

RT_ACCELERATOR

Accelerator table

See EnumResourceLanguages.

RT_BITMAP

Bitmap resource

See EnumResourceLanguages.

RT_CURSOR

Hardware-dependent cursor resource

See EnumResourceLanguages.

RT_DIALOG

Dialog box

See EnumResourceLanguages.

RT_FONT

Font resource

See EnumResourceLanguages.

RT_FONTDIR

Font directory resource

See EnumResourceLanguages.

RT_GROUP_CURSOR

Hardware-independent cursor resource

See EnumResourceLanguages.

RT_GROUP_ICON

Hardware-independent icon resource

See EnumResourceLanguages.

RT_ICON

Hardware-dependent icon resource

See EnumResourceLanguages.

RT_MENU

Menu resource

See EnumResourceLanguages.

RT_MESSAGETABLE

Message-table entry

See EnumResourceLanguages.

RT_RCDATA

User-defined resource (raw data)

See EnumResourceLanguages.

RT_STRING

String-table entry

See EnumResourceLanguages.

RT_VERSION

Version resource

See EnumResourceLanguages.

RTS_CONTROL_DISABLE

Disable the RTS line on device open and leave it disabled.

See DCB.

RTS_CONTROL_ENABLE

Enable the RTS line on device open and leave it on.

See DCB.

RTS_CONTROL_HANDSHAKE

Enable RTS handshaking. The driver raises the RTS line when the "typeahead" buffer is less than half full and lowers the RTS line when the buffer is more than three-quarters full. Note that if handshaking is enabled, it is an error for the application to adjust the line using the EscapeCommFunction function.

See DCB.

RTS_CONTROL_TOGGLE

Specifies that the RTS line will be high if bytes are available for transmission. After all bytes in queued I/O have been sent, the RTS line will be low.

See DCB.

SACL_SECURITY_INFORMATION

When set, this bit indicates the system access-control list of the object is being referenced.

See SECURITY_INFORMATION.

SB_BOTH

Enables or disables the arrows on the horizontal and vertical scroll bars associated with the given window. The hwnd parameter must be the handle of the window. SB_BOTH Shows or hides a window's standard horizontal and vertical scroll bars.

See EnableScrollBar, ShowScrollBar.

SB_BOTTOM

Scroll to lower right.

See WM_HSCROLL.

SB_CTL

For a number of functions, indicates that an hwnd parameter is the handle of a scroll bar control.

See EnableScrollBar, GetScrollPos, GetScrollRange, SetScrollPos, SetScrollRange, ShowScrollBar.

SB_ENDSCROLL

End scroll.

See WM_HSCROLL.

SB_HORZ

Enables or disables the arrows on the horizontal scroll bar associated with the given window. The hwnd parameter must be the handle of the window.

See EnableScrollBar, GetScrollPos, GetScrollRange, SetScrollPos, SetScrollRange, ShowScrollBar.

SB_LINEDOWN

Scroll down one line.

See EM_SCROLL, WM_HSCROLL.

SB_LINEUP

Scroll up one line.

See EM_SCROLL, WM_HSCROLL.

SB_PAGEDOWN

Scroll down one page.

See EM_SCROLL, WM_HSCROLL.

SB_PAGEUP

Scroll up one page.

See EM_SCROLL, WM_HSCROLL.

SB_THUMBPOSITION

Scroll to absolute position. The current position is specified by the nPos parameter.

See WM_HSCROLL.

SB_THUMBTRACK

Drag scroll box (thumb) to specified position. The current position is specified by the nPos parameter.

See WM_HSCROLL.

SB_TOP

Scroll to upper left.

See WM_HSCROLL.

SB_VERT

Shows or hides a window's standard vertical scroll bar.

See EnableScrollBar, GetScrollPos, GetScrollRange, SetScrollPos, SetScrollRange, ShowScrollBar.

SC_CLOSE

Close the window.

See WM_SYSCOMMAND.

SC_HOTKEY

Activate the window associated with the application-specified hot key. The low-order word of lParam identifies the window to activate.

See WM_SYSCOMMAND.

SC_HSCROLL

Scroll horizontally.

See WM_SYSCOMMAND.

SC_KEYMENU

Retrieve a menu through a keystroke.

See WM_SYSCOMMAND.

SC_MAXIMIZE

Maximize the window.

See WM_SYSCOMMAND.

SC_MINIMIZE

Minimize the window.

See WM_SYSCOMMAND.

SC_MOUSEMENU

Retrieve a menu through a mouse click.

See WM_SYSCOMMAND.

SC_MOVE

Move the window.

See WM_SYSCOMMAND.

SC_NEXTWINDOW

Move to the next window.

See WM_SYSCOMMAND.

SC_PREVWINDOW

Move to the previous window.

See WM_SYSCOMMAND.

SC_RESTORE

Restore window to normal position and size.

See WM_SYSCOMMAND.

SC_SCREENSAVE

Execute the screen-saver application specified in the [boot] section of the SYSTEM.INI file.

See WM_SYSCOMMAND.

SC_SIZE

Size the window.

See WM_SYSCOMMAND.

SC_TASKLIST

Execute or activate the Windows Task Manager application.

See WM_SYSCOMMAND.

SC_VSCROLL

Scroll vertically.

See WM_SYSCOMMAND.

SCREEN_FONTTYPE

Specifies that the font is a screen font.

See CHOOSEFONT, ChooseFont.

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 (also called the "thumb"), 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 and used whenever you need to provide scrolling input 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.

See CreateWindow.

SCROLLLOCK_ON

The SCROLL LOCK light is on.

See KEY_EVENT_RECORD.

SE_DACL_DEFAULTED

This bit flag, when set, indicates that a default mechanism, rather than the the original provider of the security descriptor, provided the discretionary access-control list (ACL). This may affect the treatment of the ACL with respect to inheritance of an ACL. This flag is ignored if the SE_DACL_PRESENT flag is not set. The Windows function that sets this flag is SetSecurityDescriptorDacl.

See SECURITY_DESCRIPTOR_CONTROL.

SE_DACL_PRESENT

This bit flag, when set, indicates that the security descriptor contains a discretionary access-control list (ACL). If this flag is set and the Dacl member is NULL, then a 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 Windows function that sets this flag is SetSecurityDescriptorDacl.

See SECURITY_DESCRIPTOR_CONTROL.

SE_ERR_ASSOCINCOMPLETE

The filename association is incomplete or invalid.

See ShellExecute.

SE_ERR_DDEBUSY

The DDE transaction could not be completed because other DDE transactions were being processed.

See ShellExecute.

SE_ERR_DDEFAIL

The DDE transaction failed.

See ShellExecute.

SE_ERR_DDETIMEOUT

The DDE transaction could not be completed because the request timed out.

See ShellExecute.

SE_ERR_NOASSOC

There is no application associated with the given filename extension.

See ShellExecute.

SE_ERR_SHARE

A sharing violation occurred.

See ShellExecute.

SE_GROUP_DEFAULTED

This bit flag, when set, indicates that a default mechanism, rather than the the original provider of the security descriptor, provided the security descriptor's group SID. This may 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 Windows function that sets this flag is SetSecurityDescriptorGroup.

See SECURITY_DESCRIPTOR_CONTROL.

SE_GROUP_ENABLED

A flag indicating that the group is enabled.

See TOKEN_GROUPS.

SE_GROUP_ENABLED_BY_DEFAULT

A flag indicating that the group is enabled by default.

See TOKEN_GROUPS.

SE_GROUP_LOGON_ID

A flag indicating that the group contains the logon identifier.

See TOKEN_GROUPS.

SE_GROUP_MANDATORY

A flag indicating that the group cannot be disabled.

See TOKEN_GROUPS.

SE_GROUP_OWNER

A flag indicating that the group owns the access token.

See TOKEN_GROUPS.

SE_OWNER_DEFAULTED

This bit flag, when set, indicates that a default mechanism, rather than the original provider of the security descriptor, provided the security descriptor's owner SID. This may affect the treatment of the SID with respect to inheritance of an owner. This flag is ignored if the owner member is NULL. The Windows function that sets this flag is SetSecurityDescriptorOwner.

See SECURITY_DESCRIPTOR_CONTROL.

SE_PRIVILEGE_ENABLED

This flag indicates that the privilege is enabled.

See TOKEN_PRIVILEGES.

SE_PRIVILEGE_ENABLED_BY_DEFAULT

This flag indicates that the privilege is enabled by default.

See TOKEN_PRIVILEGES.

SE_PRIVILEGE_USED_FOR_ACCESS

This flag indicates that the privilege is required to gain access to an object. (This flag is used to identify the relevant privileges in a set passed by a client application, which may contain unnecessary privileges.)

See TOKEN_PRIVILEGES.

SE_SACL_DEFAULTED

This bit flag, when set, indicates that a default mechanism, rather than the the original provider of the security descriptor, provided the system access-control list (ACL). This may affect the treatment of the ACL with respect to inheritance of an ACL. This flag is ignored if the SE_SACL_PRESENT flag is not set. The Windows function that sets this flag is SetSecurityDescriptorSacl.

See SECURITY_DESCRIPTOR_CONTROL.

SE_SACL_PRESENT

This bit flag, when set, indicates that the security descriptor contains a system access-control list (ACL). If this flag is set and the Sacl member is NULL, then 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 Windows function that sets this flag is SetSecurityDescriptorSacl.

See SECURITY_DESCRIPTOR_CONTROL.

SE_SELF_RELATIVE

This bit flag, when set, indicates that the security descriptor is in self-relative form. In this form, all members of the security descriptor are contiguous in memory, and 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. No Windows function currently sets this flag.

See SECURITY_DESCRIPTOR_CONTROL.

SEC_COMMIT

An allocation attribute flag that indicates that all pages of a section are to be set to the commit state, or that all pages of a section were initially set to the commit state.

See CreateFileMapping

SEC_FILE

An allocation attribute flag that indicates that a section is backed by a data file.

See CreateFileMapping

SEC_IMAGE

An allocation attribute flag that indicates that the file specified for a section's file mapping is an executable image file, or that a section was initially mapped as an executable image file.

See CreateFileMapping

SEC_NOCACHE

An allocation attribute flag that indicates that all pages of a section are to be set as non-cacheable.

See CreateFileMapping

SEC_RESERVE

An allocation attribute flag that indicates that all pages of a section are to be set to the reserved state, or that all pages of a section were initially set to the reserved state.

See CreateFileMapping

SECURITY_ANONYMOUS

Specifies that the client should be impersonated at Anonymous impersonation level.

See CreateFile.

SECURITY_CONTEXT_TRACKING

Specifies that the Security Tracking Mode should be Dynamic. If this flag is not specified, Security Tracking Mode is Static.

See CreateFile.

SECURITY_DELEGATION

Specifies that the client should be impersonated at Delegation impersonation level.

See CreateFile.

SECURITY_EFFECTIVE_ONLY

Specifies that only the effective aspects of the client's security context are available to the server. If this flag is not specified, only the effective aspects of the context.

See CreateFile.

SECURITY_IDENTIFICATION

Specifies that the client should be impersonated at Identification impersonation level.

See CreateFile.

SECURITY_IMPERSONATION

Specifies that the client should be impersonated at Impersonation impersonation level.

See CreateFile.

SEEK_CUR

Seeks to lOffset bytes from the current file position.

See mmioSeek, MMIOM_SEEK.

SEEK_END

Seeks to lOffset bytes from the end of the file.

See mmioSeek, MMIOM_SEEK.

SEEK_SET

Seeks to lOffset bytes from the beginning of the file.

See mmioSeek, MMIOM_SEEK.

SEM_FAILCRITICALERRORS

Windows does not display the critical-error-handler message box and returns the error to the calling application.

See SetErrorMode.

SEM_NOGPFAULTERRORBOX

Windows does not display the general-protection-fault message box. This flag should be set only by debugging applications that handle GP faults themselves.

See SetErrorMode.

SEM_NOOPENFILEERRORBOX

Windows does not display a message box when it fails to find a file.

See SetErrorMode.

SEMAPHORE_ALL_ACCESS

Specifies all possible access rights for a semaphore object.

See CreateSemaphore and OpenSemaphore.

SESSION_ABORTED

The session was abandoned due to a network or user problem.

See SESSION_BUFFER.

SESSION_ESTABLISHED

The session connected and is able to transfer data.

See SESSION_BUFFER.

SET_TAPE_MEDIA_INFORMATION

Set the tape-specific information specified by lpTapeInformation.

See SetTapeParameters.

SHIFT_PRESSED

The SHIFT key is pressed.

See KEY_EVENT_RECORD.

SHUTDOWN_NORETRY

If this process takes longer than the specified timeout to shutdown, do not put up a retry dialog for the user. Instead, just cause the process to directly exit.

See GetProcessShutdownParameters, SetProcessShutdownParameters.

SIMPLEREGION

New region is a single rectangle.

See CombineRgn, ExcludeClipRect, ExcludeUpdateRgn. ExtSelectClipRgn, GetClipBox, GetRgnBox, IntersectClipRect, OffsetClipRgn, OffsetRgn, SelectClipRgn, SelectObject, SetMetaRgn.

SIMULATED_FONTTYPE

Specifies that the font is simulated by GDI.

See CHOOSEFONT, ChooseFont.

SIZE_MAXHIDE

Message is sent to all pop-up windows when some other window is maximized.

See WM_SIZE.

SIZE_MAXIMIZED

Window has been maximized.

See WM_SIZE.

SIZE_MAXSHOW

Message is sent to all pop-up windows when some other window has been restored to its former size.

See WM_SIZE.

SIZE_MINIMIZED

Window has been minimized.

See WM_SIZE.

SIZE_RESTORED

Window has been resized, but neither SIZE_MINIMIZED nor SIZE_MAXIMIZED applies.

See WM_SIZE.

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 version 3.0 or later.

See GetDeviceCaps.

SLE_ERROR

Invalid data was passed to the function and complete failure has occurred.

See SetDebugErrorLevel, SetLastErrorEx.

SLE_MINORERROR

Invalid data was passed to the function, but the function has recovered.

See SetDebugErrorLevel, SetLastErrorEx.

SLE_WARNING

Potentially invalid data was passed to the function, but the function has recovered.

See SetDebugErrorLevel, SetLastErrorEx.

SM_CMOUSEBUTTONS

Number of buttons on the mouse.

See GetSystemMetrics.

SM_CXBORDER

Width of window frame that cannot be sized.

See GetSystemMetrics.

SM_CXCURSOR

Width of cursor.

See GetSystemMetrics.

SM_CXDLGFRAME

Width of frame when window has WS_DLGFRAME style.

See GetSystemMetrics.

SM_CXDOUBLECLK

Width of the rectangle around the location of the 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.

See GetSystemMetrics.

SM_CXFRAME

Width of window frame that can be sized.

See GetSystemMetrics.

SM_CXFULLSCREEN

Width of window client area for full-screen window.

See GetSystemMetrics.

SM_CXHSCROLL

Width of arrow bitmap on horizontal scroll bar.

See GetSystemMetrics.

SM_CXHTHUMB

Width of thumb box on horizontal scroll bar.

See GetSystemMetrics.

SM_CXICON

Width of icon.

See GetSystemMetrics.

SM_CXICONSPACING

Width of the rectangles that Program Manager uses to position tiled icons.

See GetSystemMetrics.

SM_CXMIN

Minimum width of window.

See GetSystemMetrics.

SM_CXMINTRACK

Minimum tracking width of window.

See GetSystemMetrics.

SM_CXSCREEN

Width of screen.

See GetSystemMetrics.

SM_CXSIZE

Width of bitmaps contained in the title bar.

See GetSystemMetrics.

SM_CXVSCROLL

Width of arrow bitmap on vertical scroll bar.

See GetSystemMetrics.

SM_CYBORDER

Height of window frame that cannot be sized.

See GetSystemMetrics.

SM_CYCAPTION

Actual caption height plus SM_CYBORDER.

See GetSystemMetrics.

SM_CYCURSOR

Height of cursor.

See GetSystemMetrics.

SM_CYDLGFRAME

Height of frame when window has WS_DLGFRAME style.

See GetSystemMetrics.

SM_CYDOUBLECLK

Height of the rectangle around the location of the 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.

See GetSystemMetrics.

SM_CYFRAME

Height of window frame that can be sized.

See GetSystemMetrics.

SM_CYFULLSCREEN

Height of window client area for full-screen window (equivalent to the height of the screen minus the height of the window caption).

See GetSystemMetrics.

SM_CYHSCROLL

Height of arrow bitmap on horizontal scroll bar.

See GetSystemMetrics.

SM_CYICON

Height of icon.

See GetSystemMetrics.

SM_CYICONSPACING

Height of the rectangles that Program Manager uses to position tiled icons.

See GetSystemMetrics.

SM_CYKANJIWINDOW

Height of Kanji window.

See GetSystemMetrics.

SM_CYMENU

Height of single-line menu bar minus SM_CYBORDER.

See GetSystemMetrics.

SM_CYMIN

Minimum height of window.

See GetSystemMetrics.

SM_CYMINTRACK

Minimum tracking height of window.

See GetSystemMetrics.

SM_CYSCREEN

Height of screen.

See GetSystemMetrics.

SM_CYSIZE

Height of bitmaps contained in the title bar.

See GetSystemMetrics.

SM_CYVSCROLL

Height of arrow bitmap on vertical scroll bar.

See GetSystemMetrics.

SM_CYVTHUMB

Height of thumb box on vertical scroll bar.

See GetSystemMetrics.

SM_DBCSENABLED

Nonzero if double-byte character set enabled.

See GetSystemMetrics.

SM_DEBUG

Nonzero if Windows debugging version.

See GetSystemMetrics.

SM_MENUDROPALIGNMENT

Alignment of popup menus. If this value is 0, the left side of a popup menu is aligned with the left side of the corresponding menu-bar item. If this value is nonzero, the left side of a popup menu is aligned with the right side of the corresponding menu-bar item.

See GetSystemMetrics.

SM_MOUSEPRESENT

Nonzero if mouse hardware installed.

See GetSystemMetrics.

SM_PENWINDOWS

Handle of the Pen Windows dynamic-link library (DLL) if Pen Windows is installed.

See GetSystemMetrics.

SM_SWAPBUTTON

Nonzero if left and right mouse buttons swapped.

See GetSystemMetrics.

SMTO_ABORTIFHUNG

Returns without waiting for the timeout period to elapse if the receiving process appears to be in a hung state.

See SendMessageTimeout.

SMTO_BLOCK

Prevents the calling thread from processing any other requests until the function returns.

See SendMessageTimeout.

SMTO_NORMAL

Allows the calling thread to process other requests while waiting for the function to return.

See SendMessageTimeout

SND_ALIAS

lpszName specifies an entry in the [sounds] section of the registry of the form: alias=pathname. May not be used with either SND_FILENAME or SND_RESOURCE.

See PlaySound.

SND_ASYNC

The sound is played asynchronously and the function returns immediately after beginning the sound. To terminate an asynchronously-played sound, call lpszSoundName set to NULL.

See PlaySound, sndPlaySound.

SND_FILENAME

lpszName specifies the name of a wave file. May not be used with either SND_ALIAS or SND_RESOURCE.

See PlaySound.

SND_LOOP

The sound will continue to play repeatedly until sndPlaySound is called again with the lpszSoundName parameter set to NULL. You must also specify the SND_ASYNC flag to loop sounds.

See sndPlaySound.

SND_MEMORY

The parameter specified by lpszSoundName points to an in-memory image of a waveform sound.

See sndPlaySound.

SND_NODEFAULT

If the sound can't be found, the function returns silently without playing the default sound.

See PlaySound, sndPlaySound.

SND_NOSTOP

If a sound is currently playing, the function will immediately return FALSE without playing the requested sound.

See sndPlaySound.

SND_NOWAIT

When this flag is set, the call to PlaySound will fail if no suitable wave device is available to play the sound.

See PlaySound.

SND_RESOURCE

lpszName specifies the name of a resource. May not be used with either SND_ALIAS or SND_FILENAME.

See PlaySound.

SND_SYNC

The sound is played synchronously and the function does not return until the sound ends.

See PlaySound, sndPlaySound.

SORT_STRINGSORT

Sort using what is called a "string sort", in which the hyphen and apostrophe are treated just like any other non-alphanumeric symbols: they come before the alphanumeric symbols. Specified to override the default "word sort", in which those characters are treated differently than other non-alphanumeric symbols.

See CompareStringW, LCMapStringW

SP_APPABORT

Job was terminated because the application's print-canceling function returned zero.

See EndPage.

SP_ERROR

General error.

See EndPage, Escape.

SP_OUTOFDISK

Not enough disk space is currently available for spooling, and no more space will become available.

See EndPage, Escape.

SP_OUTOFMEMORY

Not enough memory is available for spooling.

See EndPage, Escape.

SP_USERABORT

User terminated the job through Print Manager.

See EndPage, Escape.

SPI_GETBEEP

Retrieves a BOOL value that indicates whether the warning beeper is on or off.

See SystemParametersInfo.

SPI_GETBORDER

Retrieves the border multiplier factor that determines the width of a window's sizing border.

See SystemParametersInfo.

SPI_GETFASTTASKSWITCH

Determines whether fast task-switching is on of off.

See SystemParametersInfo.

SPI_GETGRIDGRANULARITY

Retrieves the current granularity value of the desktop sizing grid.

See SystemParametersInfo.

SPI_GETICONTITLELOGFONT

Retrieves the logical font information for the current icon-title font.

See SystemParametersInfo.

SPI_GETICONTITLEWRAP

Determines whether icon title wrapping is on or off.

See SystemParametersInfo.

SPI_GETKEYBOARDDELAY

Retrieves the keyboard repeat-delay setting.

See SystemParametersInfo.

SPI_GETKEYBOARDSPEED

Retrieves the keyboard repeat-speed setting.

See SystemParametersInfo.

SPI_GETMENUDROPALIGNMENT

Determines whether popup menus are left aligned or right aligned relative to the corresponding menu-bar item.

See SystemParametersInfo.

SPI_GETMOUSE

Retrieves the mouse speed and the x and y mouse threshold values.

See SystemParametersInfo.

SPI_GETSCREENSAVEACTIVE

Retrieves a BOOL value that indicates whether screen saving is on or off.

See SystemParametersInfo.

SPI_GETSCREENSAVETIMEOUT

Retrieves the screen-saver timeout value.

See SystemParametersInfo.

SPI_ICONHORIZONTALSPACING

Sets the width (in pixels) of an icon cell.

See SystemParametersInfo.

SPI_ICONVERTICALSPACING

Sets the height (in pixels) of an icon cell.

See SystemParametersInfo.

SPI_LANGDRIVER

Identifies the language driver.

See SystemParametersInfo.

SPI_SETBEEP

Turns the warning beeper on or off.

See SystemParametersInfo.

SPI_SETBORDER

Sets the border multiplier factor that determines the width of a window's sizing border.

See SystemParametersInfo.

SPI_SETDESKPATTERN

Sets the current desktop pattern by causing the Windows USER.EXE program to read the "Pattern=" parameter from the WIN.INI file.

See SystemParametersInfo.

SPI_SETDESKWALLPAPER

Specifies the filename that contains the bitmap to be used as the desktop wallpaper.

See SystemParametersInfo.

SPI_SETDOUBLECLICKTIME

Sets the double-click time for the mouse. The double-click time is the maximum number of milliseconds that may occur between the first and second clicks of a double-click.

See SystemParametersInfo.

SPI_SETDOUBLECLKHEIGHT

Sets the height of the rectangle within which the second click of a double click must fall for it to be registered as a double click.

See SystemParametersInfo.

SPI_SETDOUBLECLKWIDTH

Sets the width of the rectangle within which the second click of a double click must fall for it to be registered as a double click.

See SystemParametersInfo.

SPI_SETFASTTASKSWITCH

Turns fast task-switching on or off.

See SystemParametersInfo.

SPI_SETGRIDGRANULARITY

Sets the granularity of the desktop sizing grid.

See SystemParametersInfo.

SPI_SETICONTITLELOGFONT

Sets the font that is used for icon titles.

See SystemParametersInfo.

SPI_SETICONTITLEWRAP

Turns icon title wrapping on or off.

See SystemParametersInfo.

SPI_SETKEYBOARDDELAY

Sets the keyboard repeat-delay setting.

See SystemParametersInfo.

SPI_SETKEYBOARDSPEED

Sets the keyboard repeat-speed setting.

See SystemParametersInfo.

SPI_SETMENUDROPALIGNMENT

Sets the alignment value of popup menus.

See SystemParametersInfo.

SPI_SETMOUSE

Sets the mouse speed and the x and y mouse threshold values.

See SystemParametersInfo.

SPI_SETMOUSEBUTTONSWAP

Swaps or restores the meaning of the left and right mouse buttons.

See SystemParametersInfo.

SPI_SETSCREENSAVEACTIVE

Sets the state of the screen saver.

See SystemParametersInfo.

SPI_SETSCREENSAVETIMEOUT

Sets the screen-saver timeout value.

See SystemParametersInfo.

SPIF_SENDWININICHANGE

Broadcasts the WM_WININICHANGE message after updating the user's profile.

See SystemParametersInfo.

SPIF_UPDATEINIFILE

Writes the new system-wide parameter setting to the user's profile.

See SystemParametersInfo.

SRCAND

Combines the colors of the source and destination rectangles are combined by using the Boolean AND operator.

See BitBlt.

SRCCOPY

Copies the source rectangle directly to the destination rectangle.

See BitBlt.

SRCERASE

Combines the inverted colors of the destination rectangle with the colors of the source rectangle by using the Boolean AND operator.

See BitBlt.

SRCINVERT

Combines the colors of the source and destination rectangles by using the Boolean XOR operator.

See BitBlt.

SRCPAINT

Combines the colors of the source and destination rectangles by using the Boolean OR operator.

See BitBlt.

ST_ADVISE

One or more links are in progress.

See CONVINFO.

ST_BLOCKED

The conversation is blocked.

See CONVINFO.

ST_BLOCKNEXT

The conversation will block after calling the next callback.

See CONVINFO.

ST_CLIENT

The conversation handle passed to the DdeQueryConvInfo function is a client side handle. If the handle is 0, the conversation handle passed to the DdeQueryConvInfo function is a server side handle.

See CONVINFO.

ST_CONNECTED

The conversation is connected.

See CONVINFO.

ST_INLIST

The conversation is a member of a conversation list.

See CONVINFO.

ST_ISLOCAL

Both sides of the conversation are using the DDEML.

See CONVINFO.

ST_ISSELF

Both sides of the conversation are using the same instance of the DDEML.

See CONVINFO.

ST_TERMINATED

The conversation has been terminated by the partner.

See CONVINFO.

STARTF_FORCEOFFFEEDBACK

If specified, the feedback cursor is forced off while the application is starting. The normal cursor is displayed. For more information on feedback, see the comments section.

See STARTUPINFO.

STARTF_FORCEONFEEDBACK

If specified, the cursor is in feedback mode for two seconds after CreateProcess is called. If during those two seconds, the application makes the first GUI call, the system gives five more seconds to the application. If during those five seconds, the application shows a window, the system gives five more seconds to the application to finish drawing the window. The system turns the feedback cursor off after the first call to GetMessage, regardless of whether the application is drawing. For more information on feedback, see the comments section.

See STARTUPINFO.

STARTF_SCREENSAVER

If specified, the system will treat this application as a screen saver.

See STARTUPINFO.

STARTF_USECOUNTCHARS

If not specified, the dwXCountChars and dwYCountChars fields are ignored.

See STARTUPINFO.

STARTF_USEFILLATTRIBUTE

If not specified, the dwFillAttribute field is ignored.

See STARTUPINFO.

STARTF_USEPOSITION

If not specified, the dwX and dwY fields are ignored.

See STARTUPINFO.

STARTF_USESHOWWINDOW

If not specified, the wShowWindow field is ignored.

See STARTUPINFO.

STARTF_USESIZE

If not specified, the dwXSize and dwYSize fields are ignored.

See STARTUPINFO.

STARTF_USESTDHANDLES

If not specified, the  hStdInput, hStdOutput, and hStdError fields are ignored.

See STARTUPINFO

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.

See CreateWindow.

STD_ERROR_HANDLE

The standard error handle.

See GetStdHandle.

STD_INPUT_HANDLE

The standard input handle.

See GetStdHandle.

STD_OUTPUT_HANDLE

The standard output handle.

See GetStdHandle.

STREAM_CONTAINS_SECURITY

General attribute that stream contains security data. Allows stream to be ignored on cross OS restores.

See WIN32_STREAM_ID.

STREAM_MODIFIED_WHEN_READ

Attribute set if stream contains data which is modified when read. Allows the backup application to know that verification of data will fail.

See WIN32_STREAM_ID.

SUBLANG_CHINESE_SIMPLIFIED

See MAKELANGID.

SUBLANG_CHINESE_TRADITIONAL

See MAKELANGID.

SUBLANG_DEFAULT

See MAKELANGID.

SUBLANG_DUTCH

See MAKELANGID.

SUBLANG_DUTCH_BELGIAN

See MAKELANGID.

SUBLANG_ENGLISH_AUS

See MAKELANGID.

SUBLANG_ENGLISH_CAN

See MAKELANGID.

SUBLANG_ENGLISH_EIRE

See MAKELANGID.

SUBLANG_ENGLISH_UK

See MAKELANGID.

SUBLANG_ENGLISH_US

See MAKELANGID.

SUBLANG_FRENCH

See MAKELANGID.

SUBLANG_FRENCH_BELGIAN

See MAKELANGID.

SUBLANG_FRENCH_CANADIAN

See MAKELANGID.

SUBLANG_FRENCH_SWISS

See MAKELANGID.

SUBLANG_GERMAN

See MAKELANGID.

SUBLANG_GERMAN_SWISS

See MAKELANGID.

SUBLANG_ITALIAN

See MAKELANGID.

SUBLANG_ITALIAN_SWISS

See MAKELANGID.

SUBLANG_NEUTRAL

See MAKELANGID.

SUBLANG_NORWEGIAN_BOKMAL

See MAKELANGID.

SUBLANG_NORWEGIAN_NYNORSK

See MAKELANGID.

SUBLANG_PORTUGUESE

See MAKELANGID.

SUBLANG_PORTUGUESE_BRAZILIAN

See MAKELANGID.

SUBLANG_SERBO_CROATIAN_CYRILLIC

See MAKELANGID.

SUBLANG_SERBO_CROATIAN_LATIN

See MAKELANGID.

SUBLANG_SPANISH

See MAKELANGID.

SUBLANG_SPANISH_MEXICAN

See MAKELANGID.

SUBLANG_SPANISH_MODERN

See MAKELANGID.

SUBLANG_SYS_DEFAULT

See MAKELANGID.

SUCCESSFUL_ACCESS_ACE_FLAG

Used with system-audit and system-alarm ACEs to indicate that a message is generated for successful access attempts.

See ACE_HEADER.

SW_ERASE

When specified with SW_INVALIDATE, this flag erases the newly invalidated region by sending a WM_ERASEBKGND message to the window.

See ScrollWindowEx.

SW_HIDE

Hides the window and passes activation to another window.

See ShowWindow, HELPWININFO.

SW_INVALIDATE

Invalidates the region identified by the hrgnUpdate parameter after scrolling.

See ScrollWindowEx.

SW_MINIMIZE

Minimizes the specified window and activates the top-level window in the z-order.

See ShowWindow, HELPWININFO.

SW_PARENTCLOSING

The window's owner window is being minimized.

See WM_SHOWWINDOW.

SW_PARENTOPENING

The window's owner window is being restored.

See WM_SHOWWINDOW.

SW_RESTORE

Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_SHOWNORMAL).

See ShowWindow, HELPWININFO.

SW_SCROLLCHILDREN

Scrolls all child windows that intersect the rectangle pointed to by the lprcScroll 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 lprcScroll rectangle, even if they do not move.

See ScrollWindowEx.

SW_SHOW

Activates the window and displays it in its current size and position. However, if the first call by an application to ShowWindow has nCmdShow set to SW_SHOW, the system uses the startup information mentioned in the description of SW_SHOWDEFAULT. See the Comments section for additional information.

See ShowWindow, HELPWININFO.

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.

See ShowWindow.

SW_SHOWMAXIMIZED

Activates the window and displays it as a maximized window.

See ShowWindow, HELPWININFO.

SW_SHOWMINIMIZED

Activates the window and displays it as a minimized window.

See ShowWindow, HELPWININFO.

SW_SHOWMINNOACTIVE

Displays the window as a minimized window. The currently active window remains active.

See ShowWindow, HELPWININFO.

SW_SHOWNA

Displays the window in its current state. The window that is currently active remains active.

See ShowWindow, HELPWININFO.

SW_SHOWNOACTIVATE

Displays a window in its most recent size and position. The window that is currently active remains active.

See ShowWindow, HELPWININFO.

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

See ShowWindow, HELPWININFO.

SW_SHOWSMOOTH

Specifies that a window is shown by first having it update in a bitmap, and then copying those bits directly to the screen. In many cases this will improve the perceived speed because copying from an off-screen bitmap to the screen is very fast, making the window "snap" onto the screen.

See ShowWindow.

SWP_DRAWFRAME

Draws a frame (defined in the window's class description) around the window. The window receives a WM_NCCALCSIZE message.

See DeferWindowPos, SetWindowPos, WINDOWPOS.

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.

See SetWindowPos.

SWP_HIDEWINDOW

Hides the window.

See DeferWindowPos, SetWindowPos, WINDOWPOS.

SWP_NOACTIVATE

Does not activate the window.

See DeferWindowPos, SetWindowPos, WINDOWPOS.

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.

See SetWindowPos, WINDOWPOS.

SWP_NOMOVE

Retains current position (ignores the x and y parameters).

See DeferWindowPos, SetWindowPos, WINDOWPOS.

SWP_NOOWNERZORDER

Does not change owner window's position in the Z order.

See WINDOWPOS.

SWP_NOREDRAW

Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the non-client area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the moved window. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that must be redrawn.

See DeferWindowPos, SetWindowPos, WINDOWPOS.

SWP_NOREPOSITION

Same as SWP_NOOWNERZORDER

See WINDOWPOS.

SWP_NOSIZE

Retains current size (ignores the cx and cy parameters).

See DeferWindowPos, SetWindowPos, WINDOWPOS.

SWP_NOZORDER

Retains the current Z ordering (ignores the hwndInsertAfter parameter).

See DeferWindowPos, SetWindowPos, WINDOWPOS.

SWP_SHOWWINDOW

Displays the window.

See DeferWindowPos, SetWindowPos, WINDOWPOS.

SYNCHRONIZE

Enables using the thread handle in any of the wait functions to wait for the thread to terminate.

See DuplicateHandle.

SYSPAL_ERROR

The given device-context is invalid or does not support a color palette.

See GetSystemPaletteUse.

SYSPAL_NOSTATIC

System palette contains two static colors (black and white).

See GetSystemPaletteUse, SetSystemPaletteUse.

SYSPAL_STATIC

System palette contains static colors that will not change when an application realizes its logical palette.

See GetSystemPaletteUse, SetSystemPaletteUse.

SYSTEM_ALARM_ACE_TYPE

System-alarm ACE (defined by the SYSTEM_ALARM_ACE structure). This ACE type is not supported in the current version of Windows NT.

See ACE_HEADER.

SYSTEM_AUDIT_ACE_TYPE

System-audit ACE (defined by the SYSTEM_AUDIT_ACE structure)

See ACE_HEADER.

SYSTEM_FIXED_FONT

Fixed-pitch system font used in Windows versions earlier than 3.0. This object is available for compatibility with earlier versions of Windows.

See GetStockObject.

SYSTEM_FONT

System font. By default, Windows uses the system font to draw menus, dialog box controls, and other text. In Windows versions 3.0 and later, the system font is a variable-pitch font width; earlier versions of Windows use a fixed-pitch system font.

See GetStockObject.

TA_BASELINE

The reference point will be on the base line of the text.

See GetTextAlign, SetTextAlign.

TA_BOTTOM

The reference point will be on the bottom edge of the bounding rectangle.

See GetTextAlign, SetTextAlign.

TA_CENTER

The reference point will be aligned horizontally with the center of the bounding rectangle.

See GetTextAlign, SetTextAlign.

TA_LEFT

The reference point will be on the left edge of the bounding rectangle.

See GetTextAlign, SetTextAlign.

TA_NOUPDATECP

The current position is not updated after each text output call. The reference point is passed to the text output function.

See GetTextAlign, SetTextAlign.

TA_RIGHT

The reference point will be on the right edge of the bounding rectangle.

See GetTextAlign, SetTextAlign.

TA_TOP

The reference point will be on the top edge of the bounding rectangle.

See GetTextAlign, SetTextAlign.

TA_UPDATECP

The current position is updated after each text output call. The current position is used as the reference point.

See GetTextAlign, SetTextAlign.

TAPE_ABSOLUTE_BLOCK

Moves the tape to the device-specific block address specified by OffsetLow and OffsetHigh. The Partition parameter is ignored.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_ABSOLUTE_BLOCK_IMMED

Same as TAPE_ABSOLUTE_BLOCK, but returns status as soon as the operation begins.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_ABSOLUTE_POSITION

Indicates that the position specified by OffsetLow and OffsetHigh is an absolute number of blocks from the beginning of the partition specified by Partition.

See GetTapePosition, TAPE_GET_POSITION.

TAPE_DRIVE_ABS_BLK_IMMED

Device moves the tape to a device-specific block address and returns as soon as the move begins.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_ABSOLUTE_BLK

Device moves the tape to a device specific block address.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_COMPRESSION

Device supports hardware data compression.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_ECC

Device supports hardware error correction.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_END_OF_DATA

Device moves the tape to the end-of-data in a partition.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_ERASE_BOP_ONLY

Device performs erase operation from the beginning-of-partition only.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_ERASE_LONG

Device performs long erase operation.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_ERASE_SHORT

Device performs short erase operation.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_FILEMARKS

Device moves the tape forward (or backward) a specified number of filemarks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_FIXED

Device creates fixed data partitions.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_FIXED_BLOCK

Device supports fixed-length block mode.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_GET_ABSOLUTE_BLK

Device provides the current device-specific block address.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_GET_LOGICAL_BLK

Device provides the current logical block address (and logical tape partition).

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_INITIATOR

Device creates initiator-defined partitions.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_LOAD_UNLOAD

Device enables and disables the device for further operations.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_LOCK_UNLOCK

Device enables and disables the tape ejection mechanism.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_LOG_BLK_IMMED

Device moves the tape to a logical block address in a partition and returns as soon as the move begins.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_LOGICAL_BLK

Device moves the tape to a logical block address in a partition.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_PADDING

Device supports data padding.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_RELATIVE_BLKS

Device moves the tape forward (or backward) a specified number of blocks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_REPORT_SMKS

Device supports reporting setmarks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_REVERSE_POSITION

Device moves the tape over blocks, filemarks, or setmarks in the reverse direction.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_SELECT

Device creates select data partitions.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_SEQUENTIAL_FMKS

Device moves the tape forward (or backward) to the first occurrence of a specified number of consecutive filemarks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_SEQUENTIAL_SMKS

Device moves the tape forward (or reverse) to the first occurrence of a specified number of consecutive setmarks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_SET_BLOCK_SIZE

Device supports setting the size of a fixed-length logical block or setting the variable-length block mode.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_SET_COMPRESSION

Device enables and disables hardware data compression.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_SET_ECC

Device enables and disables hardware error correction.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_SET_PADDING

Device enables and disables data padding.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_SET_REPORT_SMKS

Device enables and disables the reporting of setmarks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_SETMARKS

Device moves the tape forward (or reverse) a specified number of setmarks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_TAPE_CAPACITY

Device returns the maximum capacity of the tape.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_TAPE_REMAINING

Device returns the remaining capacity of the tape.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_TENSION

Device supports adjusting the tape tension.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_VARIABLE_BLOCK

Device supports variable-length block mode.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_WRITE_FILEMARKS

Device writes filemarks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_WRITE_LONG_FMKS

Device writes long filemarks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_WRITE_PROTECT

Device returns error if the tape is write-enabled or write-protected.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_WRITE_SETMARKS

Device writes setmarks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_DRIVE_WRITE_SHORT_FMKS

Device writes short filemarks.

See TAPE_GET_DRIVE_PARAMETERS.

TAPE_ERASE_LONG

Erases the tape from the current position to the end of the current partition.

See EraseTape, TAPE_ERASE.

TAPE_ERASE_LONG_IMMED

Erases the tape from the current position to the end of the current partition and returns status as soon as the operation begins.

See EraseTape, TAPE_ERASE.

TAPE_ERASE_SHORT

Writes an erase gap or end-of-recorded data marker at the current position.

See EraseTape, TAPE_ERASE.

TAPE_ERASE_SHORT_IMMED

Writes an erase gap or end-of-recorded data marker at the current position and returns status as soon as the operation begins.

See EraseTape, TAPE_ERASE.

TAPE_FILEMARKS

Writes the number of filemarks specified by dwTapemarkCount.

See WriteTapemark.

TAPE_FILEMARKS_IMMED

Same as TAPE_FILEMARKS, but returns status as soon as the operation begins.

See WriteTapemark.

TAPE_FIXED_PARTITIONS

Partitions the tape based on the device's default definition of partitions. The dwCount and dwSize parameters are ignored.

See CreateTapePartition.

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.

See CreateTapePartition.

TAPE_LOAD

Loads the tape and moves the tape to the beginning.

See PrepareTape.

TAPE_LOAD_IMMED

Same as TAPE_LOAD, but returns status as soon as the operation begins.

See PrepareTape.

TAPE_LOCK

Locks the tape ejection mechanism. This prevents the tape from being accidentally ejected.

See PrepareTape, TAPE_PREPARE.

TAPE_LOGICAL_BLOCK

Moves the tape to the block address specified by OffsetLow and OffsetHigh in the partition specified by Partition.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_LOGICAL_BLOCK_IMMED

Same as TAPE_LOGICAL_BLOCK, but returns status as soon as the operation begins.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_LOGICAL_POSITION

Indicates that the position specified by OffsetLow and OffsetHigh is relative to the current position in the partition specified by Partition.

See GetTapePosition, TAPE_GET_POSITION.

TAPE_LONG_FILEMARKS

Write long filemarks.

See WriteTapemark, TAPE_WRITE_MARKS.

TAPE_LONG_FILEMARKS_IMMED

Same as TAPE_LONG_FILEMARKS, but returns status as soon as the operation begins.

See WriteTapemark.

TAPE_PARTITION_FIXED

Indicates that the partition parameters are fixed by the device.

See TAPE_CREATE_PARTITION.

TAPE_PARTITION_INITIATOR

Indicates that the number of partitions is specified by Count and the partition sizes are specified in the Size array.

See TAPE_CREATE_PARTITION.

TAPE_PARTITION_SELECT

Indicates that the number of partitions is specified by Count and the partition sizes are defined by the device.

See TAPE_CREATE_PARTITION.

TAPE_REWIND

Moves the tape to the beginning of the current partition. The Partition, OffsetLow, and OffsetHigh parameters are ignored.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_REWIND_IMMED

Same as TAPE_REWIND, but returns status as soon as the operation begins.

See SetTapePosition, TAPE_SET_POSITION.

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. Refer to your tape device's documentation for more specific information.

See CreateTapePartition.

TAPE_SEQUENTIAL_FILEMARKS

Write sequential filemarks.

See TAPE_WRITE_MARKS.

TAPE_SETMARKS

Write setmarks.

See WriteTapemark, TAPE_WRITE_MARKS.

TAPE_SETMARKS_IMMED

Same as TAPE_SETMARKS, but returns status as soon as the operation begins.

See WriteTapemark.

TAPE_SHORT_FILEMARKS

Write short filemarks.

See WriteTapemark, TAPE_WRITE_MARKS.

TAPE_SHORT_FILEMARKS_IMMED

Same as TAPE_SHORT_FILEMARKS, but returns status as soon as the operation begins.

See WriteTapemark.

TAPE_SPACE_END_OF_DATA

Moves the tape to the end of the data on the partition specified by Partition.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_SPACE_FILEMARKS

Moves the tape forward or reverse the number of filemarks specified by OffsetLow and OffsetHigh in the current partition. The Partition parameter is ignored.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_SPACE_RELATIVE_BLOCKS

Moves the tape forward or reverse the number of blocks specified by OffsetLow and OffsetHigh in the current partition. The Partition parameter is ignored.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_SPACE_SEQUENTIAL_FMKS

Moves the tape forward or reverse 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.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_SPACE_SEQUENTIAL_SMKS

Moves the tape forward or reverse to the first occurrence of 'n' setmarks in the current partition, where 'n' is the number specified by OffsetLow and OffsetHigh. The Partition parameter is ignored.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_SPACE_SETMARKS

Moves the tape forward or reverse the number of setmarks specified by OffsetLow and OffsetHigh in the current partition. The Partition parameter is ignored.

See SetTapePosition, TAPE_SET_POSITION.

TAPE_TENSION

Move to end of the tape and rewind to the beginning of the tape. This value is ignored if the tape device does not support this action.

See PrepareTape, TAPE_PREPARE.

TAPE_TENSION_IMMED

Same as TAPE_TENSION_IMMED, but returns status as soon as the operation begins.

See PrepareTape.

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.

See PrepareTape, TAPE_PREPARE.

TAPE_UNLOAD_IMMED

Rewind and unload the tape, but return as soon as the rewind operation begins.

See PrepareTape, TAPE_PREPARE.

TAPE_UNLOCK

Unlocks the tape ejection mechanism.

See PrepareTape, TAPE_PREPARE.

TECHNOLOGY

Device technology.

See GetDeviceCaps.

TEXTCAPS

A bitmask that indicates the text capabilities of the device.

See GetDeviceCaps.

THREAD_ALL_ACCESS

Specifies all possible access flags for the thread object.

See DuplicateHandle.

THREAD_GET_CONTEXT

Enables using the thread handle in the GetThreadContext function to read the thread's context.

See DuplicateHandle.

THREAD_QUERY_INFORMATION

Enables using the thread handle in the GetExitCodeThread, GetThreadPriority, and GetThreadSelectorEntry functions to read information from the thread object.

See DuplicateHandle.

THREAD_SET_CONTEXT

Enables using the thread handle in the SetThreadContext function to set the thread's context.

See DuplicateHandle.

THREAD_SET_INFORMATION

Enables using the thread handle in the SetThreadPriority function to set the thread's priority.

See DuplicateHandle.

THREAD_SUSPEND_RESUME

Enables using the thread handle in the SuspendThread or ResumeThread functions to suspend or resume a thread.

See DuplicateHandle.

THREAD_TERMINATE

Enables using the thread handle in the TerminateThread function to terminate the thread.

See DuplicateHandle.

TIME_BYTES

Current byte offset.

See MMTIME.

TIME_MIDI

MIDI time.

See MMTIME.

TIME_MS

Time counted in milliseconds.

See MMTIME.

TIME_ONESHOT

Event occurs once, after wPeriod milliseconds.

See timeSetEvent.

TIME_PERIODIC

Event occurs every wPeriod milliseconds.

See timeSetEvent.

TIME_SAMPLES

Number of wave samples.

See MMTIME.

TIME_SMPTE

SMPTE time.

See MMTIME.

TIME_ZONE_ID_DAYLIGHT

The system is operating in the range covered by the DaylightDate member of the structure at lptzi.

See GetTimeZoneInformation.

TIME_ZONE_ID_STANDARD

The system is operating in the range covered by the StandardDate member of the structure at lptzi.

See GetTimeZoneInformation.

TIME_ZONE_ID_UNKNOWN

The system cannot determine the current time zone. This is usually because a previous call to SetTimeZoneInformation supplied only the Bias (and no transition dates).

See GetTimeZoneInformation.

TOKEN_ADJUST_DEFAULT

Changes the default access-control list, primary group, or owner of an access token.

See OpenProcessToken.

TOKEN_ADJUST_GROUPS

Changes the groups specified in an access token.

See OpenProcessToken.

TOKEN_ADJUST_PRIVILEGES

Changes the privileges specified in an access token.

See OpenProcessToken.

TOKEN_ALL_ACCESS

Combines the STANDARD_RIGHTS_REQUIRED standard access rights and all individual access rights for tokens.

See OpenProcessToken.

TOKEN_ASSIGN_PRIMARY

Assigns a primary group in an access token.

See OpenProcessToken.

TOKEN_DUPLICATE

Duplicates an access token.

See OpenProcessToken.

TOKEN_EXECUTE

Combines the STANDARD_RIGHTS_EXECUTE standard access rights and the TOKEN_IMPERSONATE access right.

See OpenProcessToken.

TOKEN_IMPERSONATE

Creates an impersonation access token.

See OpenProcessToken.

TOKEN_QUERY

Queries the contents of an access token.

See OpenProcessToken.

TOKEN_QUERY_SOURCE

Queries the source of an access token.

See OpenProcessToken.

TOKEN_READ

Combines the STANDARD_RIGHTS_READ standard access rights and the TOKEN_QUERY access right.

See OpenProcessToken.

TOKEN_WRITE

Combines the STANDARD_RIGHTS_WRITE standard access rights and the TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS, and TOKEN_ADJUST_DEFAULT access rights.

See OpenProcessToken.

TPM_CENTERALIGN

Centers the pop-up menu horizontally relative to the coordinate specified by the x parameter.

See TrackPopupMenu.

TPM_LEFTALIGN

Positions the pop-up menu so that its left side is aligned with the coordinate specified by the x parameter.

See TrackPopupMenu.

TPM_LEFTBUTTON

Causes the pop-up menu to track the left mouse button.

See TrackPopupMenu.

TPM_RIGHTALIGN

Positions the pop-up menu so that its right side is aligned with the coordinate specified by the x parameter.

See TrackPopupMenu.

TPM_RIGHTBUTTON

Causes the pop-up menu to track the right mouse button.

See TrackPopupMenu.

TRANSPARENT

Background remains untouched.

See SetBkMode.

TRUNCATE_EXISTING

Opens the file. Fails if the file does not exist. 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.

See CreateFile.

TT_PRIM_LINE

Curve is a polyline.

See TTPOLYCURVE.

TT_PRIM_QSPLINE

Curve is a Bézier spline.

See TTPOLYCURVE.

TWOSTOPBITS

2 stop bits

See DCB.

UNIQUE_NAME

The name specified by the name member was created with using the NCBADDNAME command.

See NAME_BUFFER.

UNLOAD_DLL_DEBUG_EVENT

Reports an unload DLL debugging event. The value of u.UnloadDll specifies an UNLOAD_DLL_DEBUG_INFO structure.

See DEBUG_EVENT.

VERTRES

Height of the display, in raster lines.

See GetDeviceCaps.

VERTSIZE

Height of the physical display, in millimeters.

See GetDeviceCaps.

VFF_BUFFTOOSMALL

Indicates at least one of the buffers was too small to contain the corresponding string. An application should check lpszCurDir and lpszDestDir to determine which buffer was too small.

See VerFindFile.

VFF_CURNEDEST

Indicates the currently installed version of the file is not in the recommended destination.

See VerFindFile.

VFF_FILEINUSE

Indicates Windows is using the currently installed version of the file; therefore, the file cannot be overwritten or deleted.

See VerFindFile.

VFFF_ISSHAREDFILE

Indicates the source file may be shared by multiple applications. An application can use this information to determine where the file should be copied.

See VerFindFile.

VFT2_DRV_DISPLAY

Indicates that the file contains a display driver.

See VS_FIXEDFILEINFO.

VFT2_DRV_INSTALLABLE

Indicates that the file contains an installable driver.

See VS_FIXEDFILEINFO.

VFT2_DRV_KEYBOARD

Indicates that the file contains a keyboard driver.

See VS_FIXEDFILEINFO.

VFT2_DRV_LANGUAGE

Indicates that the file contains a language driver.

See VS_FIXEDFILEINFO.

VFT2_DRV_MOUSE

Indicates that the file contains a mouse driver.

See VS_FIXEDFILEINFO.

VFT2_DRV_NETWORK

Indicates that the file contains a network driver.

See VS_FIXEDFILEINFO.

VFT2_DRV_PRINTER

Indicates that the file contains a printer driver.

See VS_FIXEDFILEINFO.

VFT2_DRV_SOUND

Indicates that the file contains a sound driver.

See VS_FIXEDFILEINFO.

VFT2_DRV_SYSTEM

Indicates that the file contains a system driver.

See VS_FIXEDFILEINFO.

VFT2_FONT_RASTER

Indicates that the file contains a raster font.

See VS_FIXEDFILEINFO.

VFT2_FONT_TRUETYPE

Indicates that the file contains a TrueType font.

See VS_FIXEDFILEINFO.

VFT2_FONT_VECTOR

Indicates that the file contains a vector font.

See VS_FIXEDFILEINFO.

VFT2_UNKNOWN

Indicates that the driver or font type is unknown by Windows.

See VS_FIXEDFILEINFO.

VFT_APP

Indicates that the file contains an application.

See VS_FIXEDFILEINFO.

VFT_DLL

Indicates that the file contains a dynamic-link library

See VS_FIXEDFILEINFO.

VFT_DRV

Indicates that the file contains a device driver. If dwFileType is VFT_DRV, dwFileSubtype contains a more specific description of the driver.

See VS_FIXEDFILEINFO.

VFT_FONT

Indicates that the file contains a font. If dwFileType is VFT_FONT, dwFileSubtype contains a more specific description of the font file.

See VS_FIXEDFILEINFO.

VFT_STATIC_LIB

Indicates that the file contains a static-link library.

See VS_FIXEDFILEINFO.

VFT_UNKNOWN

Indicates that the file type is unknown to Windows.

See VS_FIXEDFILEINFO.

VFT_VXD

Indicates that the file contains a virtual device.

See VS_FIXEDFILEINFO.

VIF_ACCESSVIOLATION

Indicates a read, create, delete or rename operation failed due to an access violation.

See VerInstallFile.

VIF_BUFFTOOSMALL

Indicates the szTmpFile buffer was too small to contain the name of the temporary source file. On return, lpdwTmpFileLen contains the size of the buffer required to hold the filename.

See VerInstallFile.

VIF_CANNOTCREATE

Indicates the function cannot create the temporary file. The specific error may be described by another flag.

See VerInstallFile.

VIF_CANNOTDELETE

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

See VerInstallFile.

VIF_CANNOTREADDST

Indicates the function cannot read the destination (existing) files. This prevents the function from examining the file's attributes.

See VerInstallFile.

VIF_CANNOTREADSRC

Indicates the function cannot read the source file. This could mean that the path was not specified properly.

See VerInstallFile.

VIF_CANNOTRENAME

Indicates the function cannot rename the temporary file, but already deleted the destination file.

See VerInstallFile.

VIF_DIFFCODEPG

Indicates the new file requires a code page that cannot be displayed by the currently running version of Windows. This error can be overridden by calling VerInstallFile with the VIFF_FORCEINSTALL flag.

See VerInstallFile.

VIF_DIFFLANG

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

See VerInstallFile.

VIF_DIFFTYPE

Indicates the new file has different type, subtype, or operating system than the preexisting file. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag.

See VerInstallFile.

VIF_FILEINUSE

Indicates the preexisting file is in use by Windows and cannot be deleted.

See VerInstallFile.

VIF_MISMATCH

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

See VerInstallFile.

VIF_OUTOFMEMORY

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

See VerInstallFile.

VIF_OUTOFSPACE

Indicates the function cannot create the temporary file due to insufficient disk space on the destination drive.

See VerInstallFile.

VIF_SHARINGVIOLATION

Indicates a read, create, delete or rename operation failed due to a sharing violation.

See VerInstallFile.

VIF_SRCOLD

Indicates the file to install is older than the preexisting file. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag.

See VerInstallFile.

VIF_TEMPFILE

Indicates the temporary copy of the new file is in the destination directory. The cause of failure is reflected in other flags.

See VerInstallFile.

VIF_WRITEPROT

Indicates the preexisting file is write-protected. This error can be overridden by calling VerInstallFile again the VIFF_FORCEINSTALL flag.

See VerInstallFile.

VIFF_DONTDELETEOLD

Installs the file without deleting the previously installed file, if the previously installed file is not in the destination directory.

See VerInstallFile.

VIFF_FORCEINSTALL

Installs the file regardless of mismatched version numbers. The function will only check for physical errors during installation.

See VerInstallFile.

VOS__PM16

Indicates that the file was designed for 16-bit Presentation Manager.

See VS_FIXEDFILEINFO.

VOS__PM32

Indicates that the file was designed for 32-bit Presentation Manager.

See VS_FIXEDFILEINFO.

VOS__WINDOWS16

Indicates that the file was designed for 16-bit Windows.

See VS_FIXEDFILEINFO.

VOS__WINDOWS32

Indicates that the file was designed for 32-bit Windows.

See VS_FIXEDFILEINFO.

VOS_DOS

Indicates that the file was designed for DOS.

See VS_FIXEDFILEINFO.

VOS_DOS_WINDOWS16

Indicates that the file was designed for 16-bit Windows running on DOS.

See VS_FIXEDFILEINFO.

VOS_DOS_WINDOWS32

Indicates that the file was designed for 32-bit Windows running on DOS.

See VS_FIXEDFILEINFO.

VOS_NT

Indicates that the file was designed for NT.

See VS_FIXEDFILEINFO.

VOS_NT_WINDOWS32

Indicates that the file was designed for 32-bit Windows running on NT.

See VS_FIXEDFILEINFO.

VOS_OS216

Indicates that the file was designed for 16-bit OS/2.

See VS_FIXEDFILEINFO.

VOS_OS216_PM16

Indicates that the file was designed for 16-bit Presentation Manager running on 16-bit OS/2.

See VS_FIXEDFILEINFO.

VOS_OS232

Indicates that the file was designed for 32-bit OS/2.

See VS_FIXEDFILEINFO.

VOS_OS232_PM32

Indicates that the file was designed for 32-bit Presentation Manager running on 32-bit OS/2.

See VS_FIXEDFILEINFO.

VOS_UNKNOWN

Indicates that the operating system for which the file was designed is unknown to Windows.

See VS_FIXEDFILEINFO.

VS_FF_DEBUG

Indicates that the file contains debugging information or is compiled with debugging features enabled.

See VS_FIXEDFILEINFO.

VS_FF_INFOINFERRED

Indicates that the file's version data structure was created dynamically; therefore, some of the fields in this data structure may be empty or incorrect. This flag should never be set in a file's VS_VERSION_INFO data.

See VS_FIXEDFILEINFO.

VS_FF_PATCHED

Indicates that the file has been modified and is not identical to the original shipping file of the same version number.

See VS_FIXEDFILEINFO.

VS_FF_PRERELEASE

Indicates that the file is a development version, not a commercially released product.

See VS_FIXEDFILEINFO.

VS_FF_PRIVATEBUILD

Indicates that the file was not built using standard release procedures. If this flag is set, the StringFileInfo block should contain a PrivateBuild entry.

See VS_FIXEDFILEINFO.

VS_FF_SPECIALBUILD

Indicates that 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 block should contain a SpecialBuild entry.

See VS_FIXEDFILEINFO.

VTA_BASELINE

The reference point will be on the baseline of the text. VTA_BASELINE The reference point will be on the baseline of the text.

See GetTextAlign, SetTextAlign.

VTA_CENTER

The reference point will be aligned vertically with the center of the bounding rectangle.

See GetTextAlign, SetTextAlign.

WA_ACTIVE

The window is being 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).

See WM_ACTIVATE.

WA_CLICKACTIVE

The window is being activated by a mouse click.

See WM_ACTIVATE.

WA_INACTIVE

The window is being deactivated.

See WM_ACTIVATE.

WAVE_ALLOWSYNC

If this flag is not specified, then the device will fail to open if it is a synchronous device.

See waveInOpen, waveOutOpen.

WAVE_FORMAT_1M08

11.025 kHz, Mono, 8-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_1M16

11.025 kHz, Mono, 16-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_1S08

11.025 kHz, Stereo, 8-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_1S16

11.025 kHz, Stereo, 16-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_2M08

22.05 kHz, Mono, 8-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_2M16

22.05 kHz, Mono, 16-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_2S08

22.05 kHz, Stereo, 8-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_2S16

22.05 kHz, Stereo, 16-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_4M08

44.1 kHz, Mono, 8-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_4M16

44.1 kHz, Mono, 16-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_4S08

44.1 kHz, Stereo, 8-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_4S16

44.1 kHz, Stereo, 16-bit

See WAVEINCAPS, WAVEOUTCAPS.

WAVE_FORMAT_PCM

Waveform data is PCM.

See WAVEFORMAT.

WAVE_FORMAT_QUERY

If this flag is specified, the device is queried to determine if it supports the given format but is not actually opened.

See waveInOpen, waveOutOpen.

WAVECAPS_LRVOLUME

Supports separate left and right volume control.

See WAVEOUTCAPS.

WAVECAPS_PITCH

Supports pitch control.

See WAVEOUTCAPS.

WAVECAPS_PLAYBACKRATE

Supports playback rate control.

See WAVEOUTCAPS.

WAVECAPS_VOLUME

Supports volume control.

See WAVEOUTCAPS.

WAVERR_BADFORMAT

Attempted to open with an unsupported wave format.

See waveInOpen, waveOutOpen.

WAVERR_STILLPLAYING

There are still buffers in the queue.

See waveInClose, waveInUnprepareHeader, waveOutClose, waveOutUnprepareHeader.

WAVERR_UNPREPARED

Buffer hasn't been prepared.

See waveInAddBuffer, waveOutWrite.

WB_ISDELIMITER

Check whether the character at the current position is a delimiter.

See EditWordBreakProc.

WB_LEFT

Look for the beginning of a word to the left of the current position.

See EditWordBreakProc.

WB_RIGHT

Look for the beginning of a word to the right of the current position. (This is useful in right-aligned edit controls.)

See EditWordBreakProc.

WC_COMPOSITECHECK

Convert composite characters to precomposed characters.

See WideCharToMultiByte.

WC_DEFAULTCHAR

Replace exceptions with the default character.

See WideCharToMultiByte.

WC_DEFAULTCHECK

Check for the default character and set the lpfUsedDefaultChar flag when necessary.

See WideCharToMultiByte.

WC_DISCARDNS

Discard non-spacing characters.

See WideCharToMultiByte.

WC_SEPCHARS

Generate separate characters. This is the default behavior.

See WideCharToMultiByte.

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.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

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.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

WH_DEBUG

Installs a hook procedure useful for debugging other hook procedures. For more information, see the description of the DebugProc hook procedure.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

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.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

WH_HARDWARE

Installs a hook procedure that monitors messages that are posted by a nonstandard input device such as a pen.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

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.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

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.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

WH_KEYBOARD

Installs a hook procedure that monitors keystroke messages. For more information, see the description of the KeyboardProc hook procedure.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

WH_MOUSE

Installs a hook procedure that monitors mouse messages. For more information, see the description of the MouseProc hook procedure.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

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.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

WH_SHELL

Installs a hook procedure that receives notifications useful to shell applications. For more information, see the description of the ShellProc hook procedure.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

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.

See DebugProc, SetWindowsHook, SetWindowsHookEx.

WHDR_BEGINLOOP

Specifies that this buffer is the first buffer in a loop. This flag is only used with output data buffers.

See WAVEHDR.

WHDR_DONE

Set by the device driver to indicate that it is finished with the data buffer and is returning it to the application.

See WAVEHDR.

WHDR_ENDLOOP

Specifies that this buffer is the last buffer in a loop. This flag is only used with output data buffers.

See WAVEHDR.

WHDR_PREPARED

Set by Windows to indicate that the data buffer has been prepared with waveInPrepareHeader or waveOutPrepareHeader.

See WAVEHDR.

WHITE_BRUSH

White brush

See GetStockObject.

WHITE_PEN

White pen

See GetStockObject.

WHITENESS

Fills the destination rectangle the color associated with index 1 in the physical palette. (This color is white for the default physical palette.)

See BitBlt, PatBlt.

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.

See SetStretchBltMode.

WINDING

Selects winding number mode (fills any region with a non-zero winding number).

See CreatePolygonRgn, CreatePolyPolygonRgn, GetPolyFillMode, SetPolyFillMode.

WPF_RESTORETOMAXIMIZED

Specifies that the restored window will be maximized, regardless of whether it was maximized before it was minimized. This setting is valid only the next time the window is restored. It does not change the default restoration behavior. This flag is valid only when the SW_SHOWMINIMIZED value is specified for the showCmd member.

See WINDOWPLACEMENT.

WPF_SETMINPOSITION

Specifies that the x- and y-positions of the minimized window may be specified. This flag must be specified if the coordinates are set in the ptMinPosition member.

See WINDOWPLACEMENT.

WS_BORDER

Creates a window that has a thin-line border.

See CreateWindow.

WS_CAPTION

Creates a window that has a title bar (includes the WS_BORDER style).

See CreateWindow.

WS_CHILD

Creates a child window. This style cannot be used with the WS_POPUP style.

See CreateWindow.

WS_CHILDWINDOW

Same as the WS_CHILD style.

See CreateWindow.

WS_CLIPCHILDREN

Excludes the area occupied by child windows when drawing within the parent window. Use this style when creating the parent window.

See CreateWindow.

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. For use with the WS_CHILD style only.

See CreateWindow.

WS_DISABLED

Creates a window that is initially disabled. A disabled window cannot receive input from the user.

See CreateWindow.

WS_DLGFRAME

Creates a window with a border of a style typically used with dialog boxes. A window with this style cannot have a title bar.

See CreateWindow.

WS_EX_ACCEPTFILES

Specifies that a window created with this style accepts drag-drop files.

See CreateWindowEx.

WS_EX_DLGMODALFRAME

Creates a window with a double border that can (optionally) be created with a title bar by specifying the WS_CAPTION style in the dwStyle parameter.

See CreateWindowEx.

WS_EX_NOPARENTNOTIFY

Specifies that a child window created by using this style will not send the WM_PARENTNOTIFY message to its parent window when the child window is created or destroyed.

See CreateWindowEx.

WS_EX_TOPMOST

Specifies that a window created with this style should be placed above all non-topmost windows and stay above them even when the window is deactivated. Use the SetWindowPos function to add or remove this style.

See CreateWindowEx.

WS_GROUP

Specifies the first control of a group of controls. The user can change the keyboard focus from one control in the group to the next by using the direction keys. All controls defined with the WS_GROUP style after the first control belong to the same group. The next control with the WS_GROUP style ends the group and starts the next group.

See CreateWindow.

WS_HSCROLL

Creates an MDI child window that has a horizontal scroll bar. WS_HSCROLL Creates a window that has a horizontal scroll bar. WS_HSCROLL Creates an MDI child window that has a horizontal scroll bar.

See CreateMDIWindow, CreateWindow, MDICREATESTRUCT.

WS_MAXIMIZE

Creates a window that is initially maximized.

See CreateMDIWindow, CreateWindow, MDICREATESTRUCT.

WS_MAXIMIZEBOX

Creates a window that has a maximize box.

See CreateWindow.

WS_MINIMIZE

Creates a window that is initially minimized.

See CreateMDIWindow, CreateWindow, MDICREATESTRUCT.

WS_MINIMIZEBOX

Creates a window that has a minimize box.

See CreateWindow.

WS_OVERLAPPED

Creates an overlapped window. An overlapped window has a title bar and a border.

See CreateWindow.

WS_OVERLAPPEDWINDOW

Creates an overlapped window having the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles.

See CreateWindow.

WS_POPUP

Creates a pop-up window. This style cannot be used with the WS_CHILD style.

See CreateWindow.

WS_POPUPWINDOW

Creates a pop-up window having WS_BORDER, WS_POPUP, and WS_SYSMENU styles. You must combine the WS_CAPTION style with the WS_POPUPWINDOW style to make the System menu visible.

See CreateWindow.

WS_SYSMENU

Creates a window that has a System-menu box in its title bar. The WS_CAPTION style must also be specified.

See CreateWindow.

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.

See CreateWindow.

WS_THICKFRAME

Creates a window with a sizing border.

See CreateWindow.

WS_VISIBLE

Creates a window that is initially visible.

See CreateWindow.

WS_VSCROLL

Creates a window that has a vertical scroll bar.

See CreateMDIWindow, CreateWindow, MDICREATESTRUCT.

WVR_REDRAW

This value causes the entire window to be redrawn. It is a combination of WVR_HREDRAW and WVR_VREDRAW.

See WM_NCCALCSIZE.

WVR_VALIDRECTS

This value indicates that, upon return from WM_NCCALCSIZE, the rgrc[1] and rgrc[2] rectangles 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.

See WM_NCCALCSIZE.

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 types consist of the following:

See DdeCallback.

XCLASS_DATA

A DDE callback function should return a DDE data handle, CBR_BLOCK, or NULL when it finishes processing a transaction that belongs to this class. The XCLASS_DATA transaction types consist of the following:

See DdeCallback.

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 types consist of the following:

See DdeCallback.

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 types consist of the following:

See DdeCallback.

XST_ADVACKRCVD

The advise transaction was just completed.

See CONVINFO.

XST_ADVDATAACKRCVD

The advise data transaction was just completed.

See CONVINFO.

XST_ADVDATASENT

Advise data has been sent and is awaiting an acknowledgement.

See CONVINFO.

XST_ADVSENT

An advise transaction is awaiting an acknowledgement.

See CONVINFO.

XST_CONNECTED

The conversation has no active transactions.

See CONVINFO.

XST_DATARCVD

The requested data has just been received.

See CONVINFO.

XST_EXECACKRCVD

An execute transaction just completed.

See CONVINFO.

XST_EXECSENT

An execute transaction is awaiting an acknowledgement.

See CONVINFO.

XST_INCOMPLETE

The last transaction failed.

See CONVINFO.

XST_INIT1

Mid-initiate state 1.

See CONVINFO.

XST_INIT2

Mid-initiate state 2.

See CONVINFO.

XST_NULL

Pre-initiate state.

See CONVINFO.

XST_POKEACKRCVD

A poke transaction was just completed.

See CONVINFO.

XST_POKESENT

A poke transaction is awaiting an acknowledgement.

See CONVINFO.

XST_REQSENT

A request transaction is awaiting an acknowledgement.

See CONVINFO.

XST_UNADVACKRCVD

An unadvise transaction just completed.

See CONVINFO.

XST_UNADVSENT

An unadvise transaction is awaiting an acknowledgement.

See CONVINFO.

XTYPF_ACKREQ

Instructs the server to wait until the client acknowledges 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.

See DdeClientTransaction.

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.

See DdeClientTransaction.


NCBADDGRNAME
NCBADDGRNAME  0x36  nb30.h

Add a group name to the local name table. See NCB.


FN_NCBADDGRNAME
NCBADDGRNAME  0x36  nb30.h


NCBADDNAME
NCBADDNAME  0x30  nb30.h

Add a unique name to the local name table. See NCB.


FN_NCBADDNAME
NCBADDNAME  0x30  nb30.h


NCBASTAT
NCBASTAT  0x33  nb30.h

Retrieve the status of the adapter. When this value 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. See NCB.


FN_NCBASTAT
NCBASTAT  0x33  nb30.h


NCBCALL
NCBCALL  0x10  nb30.h

Open a session with another name. See NCB.


FN_NCBCALL
NCBCALL  0x10  nb30.h


NCBCANCEL
NCBCANCEL  0x35  nb30.h

Cancel a previous command. See NCB.


FN_NCBCANCEL
NCBCANCEL  0x35  nb30.h


NCBCHAINSEND
NCBCHAINSEND  0x17  nb30.h

Send the contents of two data buffers to the specified session partner. For Windows NT, this is equivalent to NCBCHAINSENDNA. See NCB.


FN_NCBCHAINSEND
NCBCHAINSEND  0x17  nb30.h


NCBCHAINSENDNA
NCBCHAINSENDNA  0x72  nb30.h

Send the contents of two data buffers to the specified session partner and do not wait for acknowledgment. For Windows NT, this is equivalent to NCBCHAINSEND. See NCB.


FN_NCBCHAINSENDNA
NCBCHAINSENDNA  0x72  nb30.h


NCBDELNAME
NCBDELNAME  0x31  nb30.h

Delete a name from the local name table. See NCB.


FN_NCBDELNAME
NCBDELNAME  0x31  nb30.h


NCBDGRECV
NCBDGRECV  0x21  nb30.h

Receive a datagram from any name. See NCB.


FN_NCBDGRECV
NCBDGRECV  0x21  nb30.h


NCBDGRECVBC
NCBDGRECVBC  0x23  nb30.h

Receive broadcast datagram from any host. See NCB.


FN_NCBDGRECVBC
NCBDGRECVBC  0x23  nb30.h


NCBDGSEND
NCBDGSEND  0x20  nb30.h

Send datagram to a specified name. See NCB.


FN_NCBDGSEND
NCBDGSEND  0x20  nb30.h


NCBDGSENDBC
NCBDGSENDBC  0x22  nb30.h

Send a broadcast datagram to every host on the local area network (LAN). See NCB.


FN_NCBDGSENDBC
NCBDGSENDBC  0x22  nb30.h


NCBENUM
NCBENUM  0x37  nb30.h

Enumerate LAN adapter (LANA) numbers. When this value is specified, the ncb_buffer member points to a buffer to be filled with a LANA_ENUM structure. See NCB.


FN_NCBENUM
NCBENUM  0x37  nb30.h


NCBFINDNAME
NCBFINDNAME  0x78  nb30.h

Determine the location of a name on the network. See NCB.


FN_NCBFINDNAME
NCBFINDNAME  0x78  nb30.h


NCBHANGUP
NCBHANGUP  0x12  nb30.h

Close a specified session. See NCB.


FN_NCBHANGUP
NCBHANGUP  0x12  nb30.h


NCBLANSTALERT
NCBLANSTALERT  0x73  nb30.h

Notify the user of LAN failures that last for more than one minute. See NCB.


FN_NCBLANSTALERT
NCBLANSTALERT  0x73  nb30.h


NCBLISTEN
NCBLISTEN  0x11  nb30.h

Enable a session to be opened with another name. See NCB.


FN_NCBLISTEN
NCBLISTEN  0x11  nb30.h


NCBRECV
NCBRECV  0x15  nb30.h

Receive data from the specified session partner. See NCB.


FN_NCBRECV
NCBRECV  0x15  nb30.h


NCBRECVANY
NCBRECVANY  0x16  nb30.h

Receive data from any session corresponding to a specified name. See NCB.


FN_NCBRECVANY
NCBRECVANY  0x16  nb30.h


NCBRESET
NCBRESET  0x32  nb30.h

Reset 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. See NCB.


FN_NCBRESET
NCBRESET  0x32  nb30.h


NCBSEND
NCBSEND  0x14  nb30.h

Send data to the specified session partner. For Windows NT, this is equivalent to NCBSENDNA. See NCB.


FN_NCBSEND
NCBSEND  0x14  nb30.h


NCBSENDNA
NCBSENDNA  0x71  nb30.h

Send data to specified session partner and do not wait for an acknowledgment. For Windows NT, this is equivalent to NCBSEND. See NCB.


FN_NCBSENDNA
NCBSENDNA  0x71  nb30.h


NCBSSTAT
NCBSSTAT  0x34  nb30.h

Retrieve 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. See NCB.


FN_NCBSSTAT
NCBSSTAT  0x34  nb30.h


NCBTRACE
NCBTRACE  0x79  nb30.h

Activate or deactivate NCB tracing. Support for this command in the system is optional and system-specific. See NCB.


FN_NCBTRACE
NCBTRACE  0x79  nb30.h


NCBUNLINK
NCBUNLINK  0x70  nb30.h

Unlink the adapter. See NCB.


FN_NCBUNLINK
NCBUNLINK  0x70  nb30.h


NMPWAIT_NOWAIT

Do not wait for a named pipe to become available. If the named pipe is not available, an error is returned. See WaitNamedPipe, CallNamedPipe


NMPWAIT_USE_DEFAULT_WAIT
NMPWAIT_USE_DEFAULT_WAIT  0x00000000  winbase.h

Wait the default timeout period specified in a call to CreateNamedPipe for a named pipe to become available. See WaitNamedPipe, CallNamedPipe, CreateNamedPipe


FN_NMPWAIT_USE_DEFAULT_WAIT
NMPWAIT_USE_DEFAULT_WAIT  0x00000000  winbase.h


NMPWAIT_WAIT_FOREVER
NMPWAIT_WAIT_FOREVER  0xffffffff  winbase.h

Wait indefinitely for a named pipe to become available. See WaitNamedPipe, CallNamedPipe


FN_NMPWAIT_WAIT_FOREVER
NMPWAIT_WAIT_FOREVER  0xffffffff  winbase.h


NO_PROPAGATE_INHERIT_ACE
NO_PROPAGATE_INHERIT_ACE  (0x4)  winnt.h

The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE. See ACE_HEADER.


FN_NO_PROPAGATE_INHERIT_ACE
NO_PROPAGATE_INHERIT_ACE  (0x4)  winnt.h


NOPARITY
NOPARITY  0  winbase.h

No parity See DCB.


FN_NOPARITY
NOPARITY  0  winbase.h


NORM_IGNORECASE
NORM_IGNORECASE  0x00000001  winnls.h

Ignore case. This bit is not set by default. This option cannot be used with LCMAP_LOWERCASE or LCMAP_UPPERCASE. See CompareStringW, LCMapStringW.


FN_NORM_IGNORECASE
NORM_IGNORECASE  0x00000001  winnls.h


NORM_IGNORENONSPACE
NORM_IGNORENONSPACE  0x00000002  winnls.h

Ignore nonspacing. This bit is not set by default. This option cannot be used with LCMAP_LOWERCASE or LCMAP_UPPERCASE. See CompareStringW, LCMapStringW.


FN_NORM_IGNORENONSPACE
NORM_IGNORENONSPACE  0x00000002  winnls.h


NORM_IGNORESYMBOLS
NORM_IGNORESYMBOLS  0x00000004  winnls.h

Ignore symbols. This bit is not set by default. This option cannot be used with LCMAP_LOWERCASE or LCMAP_UPPERCASE. See CompareStringW, LCMapStringW.


FN_NORM_IGNORESYMBOLS
NORM_IGNORESYMBOLS  0x00000004  winnls.h


NOTSRCCOPY
NOTSRCCOPY  (DWORD)0x00330008  wingdi.h

Copies the inverted source rectangle to the destination. See BitBlt.


FN_NOTSRCCOPY
NOTSRCCOPY  (DWORD)0x00330008  wingdi.h


NOTSRCERASE
NOTSRCERASE  (DWORD)0x001100A6  wingdi.h

Combines the colors of the source and destination rectangles by using the Boolean OR operator and inverted. See BitBlt.


FN_NOTSRCERASE
NOTSRCERASE  (DWORD)0x001100A6  wingdi.h


NRC_ACTSES
NRC_ACTSES  0x0f  nb30.h

The command finished; the name has active sessions and is no longer registered. See NCB.


FN_NRC_ACTSES
NRC_ACTSES  0x0f  nb30.h


NRC_BADDR
NRC_BADDR  0x07  nb30.h

The buffer address was illegal. See NCB.


FN_NRC_BADDR
NRC_BADDR  0x07  nb30.h


NRC_BRIDGE
NRC_BRIDGE  0x23  nb30.h

The ncb_lana_num member did not specify a valid network number. See NCB.


FN_NRC_BRIDGE
NRC_BRIDGE  0x23  nb30.h


NRC_BUFLEN
NRC_BUFLEN  0x01  nb30.h

An illegal buffer length was supplied. See NCB.


FN_NRC_BUFLEN
NRC_BUFLEN  0x01  nb30.h


NRC_CANCEL
NRC_CANCEL  0x26  nb30.h

The NCBCANCEL command was not valid; the command was not canceled. See NCB.


FN_NRC_CANCEL
NRC_CANCEL  0x26  nb30.h


NRC_CANOCCR
NRC_CANOCCR  0x24  nb30.h

The command was completed while a cancel operation was occurring. See NCB.


FN_NRC_CANOCCR
NRC_CANOCCR  0x24  nb30.h


NRC_CMDCAN
NRC_CMDCAN  0x0b  nb30.h

The command was cancelled. See NCB.


FN_NRC_CMDCAN
NRC_CMDCAN  0x0b  nb30.h


NRC_CMDTMO
NRC_CMDTMO  0x05  nb30.h

The command was timed out. See NCB.


FN_NRC_CMDTMO
NRC_CMDTMO  0x05  nb30.h


NRC_DUPENV
NRC_DUPENV  0x30  nb30.h

The name was defined by another local process. See NCB.


FN_NRC_DUPENV
NRC_DUPENV  0x30  nb30.h


NRC_DUPNAME
NRC_DUPNAME  0x0d  nb30.h

A duplicate name existed in the local name table. See NCB.


FN_NRC_DUPNAME
NRC_DUPNAME  0x0d  nb30.h


NRC_ENVNOTDEF
NRC_ENVNOTDEF  0x34  nb30.h

The environment was not defined. A reset command must be issued. See NCB.


FN_NRC_ENVNOTDEF
NRC_ENVNOTDEF  0x34  nb30.h


NRC_GOODRET
NRC_GOODRET  0x00  nb30.h

The operation succeeded. See NCB.


FN_NRC_GOODRET
NRC_GOODRET  0x00  nb30.h


NRC_IFBUSY
NRC_IFBUSY  0x21  nb30.h

The interface was busy. See NCB.


FN_NRC_IFBUSY
NRC_IFBUSY  0x21  nb30.h


NRC_ILLCMD
NRC_ILLCMD  0x03  nb30.h

An illegal command was supplied. See NCB.


FN_NRC_ILLCMD
NRC_ILLCMD  0x03  nb30.h


NRC_ILLNN
NRC_ILLNN  0x13  nb30.h

An illegal name number was specified. See NCB.


FN_NRC_ILLNN
NRC_ILLNN  0x13  nb30.h


NRC_INCOMP
NRC_INCOMP  0x06  nb30.h

The message was incomplete. The application should issue another command. See NCB.


FN_NRC_INCOMP
NRC_INCOMP  0x06  nb30.h


NRC_INUSE
NRC_INUSE  0x16  nb30.h

The name was already in use on the remote adapter. See NCB.


FN_NRC_INUSE
NRC_INUSE  0x16  nb30.h


NRC_INVADDRESS
NRC_INVADDRESS  0x39  nb30.h

The NCB address was not valid. This return code is not part of the IBM Netbios 3.0 specification. This return code is not returned in the NCB; instead, it is returned by the Netbios function. See NCB.


FN_NRC_INVADDRESS
NRC_INVADDRESS  0x39  nb30.h


NRC_INVDDID
NRC_INVDDID  0x3B  nb30.h

The NCB DDID was invalid. See NCB.


FN_NRC_INVDDID
NRC_INVDDID  0x3B  nb30.h


NRC_LOCKFAIL
NRC_LOCKFAIL  0x3C  nb30.h

The attempt to lock the user area failed. See NCB.


FN_NRC_LOCKFAIL
NRC_LOCKFAIL  0x3C  nb30.h


NRC_LOCTFUL
NRC_LOCTFUL  0x11  nb30.h

The local session table was full. See NCB.


FN_NRC_LOCTFUL
NRC_LOCTFUL  0x11  nb30.h


NRC_MAXAPPS
NRC_MAXAPPS  0x36  nb30.h

The maximum number of applications was exceeded. See NCB.


FN_NRC_MAXAPPS
NRC_MAXAPPS  0x36  nb30.h


NRC_NAMCONF
NRC_NAMCONF  0x19  nb30.h

A name conflict was detected. See NCB.


FN_NRC_NAMCONF
NRC_NAMCONF  0x19  nb30.h


NRC_NAMERR
NRC_NAMERR  0x17  nb30.h

The name was deleted. See NCB.


FN_NRC_NAMERR
NRC_NAMERR  0x17  nb30.h


NRC_NAMTFUL
NRC_NAMTFUL  0x0e  nb30.h

The name table was full. See NCB.


FN_NRC_NAMTFUL
NRC_NAMTFUL  0x0e  nb30.h


NRC_NOCALL
NRC_NOCALL  0x14  nb30.h

The system did not find the name that was called. See NCB.


FN_NRC_NOCALL
NRC_NOCALL  0x14  nb30.h


NRC_NORES
NRC_NORES  0x09  nb30.h

No resource was available. See NCB.


FN_NRC_NORES
NRC_NORES  0x09  nb30.h


NRC_NORESOURCES
NRC_NORESOURCES  0x38  nb30.h

The requested resources were not available. See NCB.


FN_NRC_NORESOURCES
NRC_NORESOURCES  0x38  nb30.h


NRC_NOSAPS
NRC_NOSAPS  0x37  nb30.h

No SAPs available for netbios. See NCB.


FN_NRC_NOSAPS
NRC_NOSAPS  0x37  nb30.h


NRC_NOWILD
NRC_NOWILD  0x15  nb30.h

Wildcards are not permitted in the ncb_name member. See NCB.


FN_NRC_NOWILD
NRC_NOWILD  0x15  nb30.h


NRC_OPENERR
NRC_OPENERR  0x3f  nb30.h

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. See NCB.


FN_NRC_OPENERR
NRC_OPENERR  0x3f  nb30.h


NRC_OSRESNOTAV
NRC_OSRESNOTAV  0x35  nb30.h

Operating system resources were exhausted. The application should retry the command later. See NCB.


FN_NRC_OSRESNOTAV
NRC_OSRESNOTAV  0x35  nb30.h


NRC_PENDING
NRC_PENDING  0xff  nb30.h

An asynchronous operation is not yet finished. See NCB.


FN_NRC_PENDING
NRC_PENDING  0xff  nb30.h


NRC_REMTFUL
NRC_REMTFUL  0x12  nb30.h

The remote session table was full. The request to open a session was rejected. See NCB.


FN_NRC_REMTFUL
NRC_REMTFUL  0x12  nb30.h


NRC_SABORT
NRC_SABORT  0x18  nb30.h

The session ended abnormally. See NCB.


FN_NRC_SABORT
NRC_SABORT  0x18  nb30.h


NRC_SCLOSED
NRC_SCLOSED  0x0a  nb30.h

The session was closed. See NCB.


FN_NRC_SCLOSED
NRC_SCLOSED  0x0a  nb30.h


NRC_SNUMOUT
NRC_SNUMOUT  0x08  nb30.h

The session number was out of range. See NCB.


FN_NRC_SNUMOUT
NRC_SNUMOUT  0x08  nb30.h


NRC_SYSTEM
NRC_SYSTEM  0x40  nb30.h

A system error occurred. See NCB.


FN_NRC_SYSTEM
NRC_SYSTEM  0x40  nb30.h


NRC_TOOMANY
NRC_TOOMANY  0x22  nb30.h

Too many commands were outstanding; the application should retry the command later. See NCB.


FN_NRC_TOOMANY
NRC_TOOMANY  0x22  nb30.h


NULL_BRUSH
NULL_BRUSH  5  wingdi.h

Null brush (Equivalent to HOLLOW_BRUSH) See GetStockObject.


FN_NULL_BRUSH
NULL_BRUSH  5  wingdi.h


NULL_PEN
NULL_PEN  8  wingdi.h

Null pen See GetStockObject.


FN_NULL_PEN
NULL_PEN  8  wingdi.h


NULLREGION
NULLREGION  1  wingdi.h

Region is empty. See CombineRgn, ExtSelectClipRgn, GetRgnBox, IntersectClipRect, OffsetClipRgn, SelectClipRgn, SelectObject, SetMetaRgn.


FN_NULLREGION
NULLREGION  1  wingdi.h


NULLREGION
NULLREGION  1  wingdi.h

Region is empty. See OffsetRgn.


FN_NULLREGION
NULLREGION  1  wingdi.h


NULLREGION
NULLREGION  1  wingdi.h

Region is empty. See ExcludeClipRect, GetClipBox, ExcludeUpdateRgn.


FN_NULLREGION
NULLREGION  1  wingdi.h


NUMBRUSHES
NUMBRUSHES  16  wingdi.h

Number of device-specific brushes. See GetDeviceCaps.


FN_NUMBRUSHES
NUMBRUSHES  16  wingdi.h


NUMCOLORS
NUMCOLORS  24  wingdi.h

Number of entries in the device's color table. See GetDeviceCaps.


FN_NUMCOLORS
NUMCOLORS  24  wingdi.h


NUMFONTS
NUMFONTS  22  wingdi.h

Number of device-specific fonts. See GetDeviceCaps.


FN_NUMFONTS
NUMFONTS  22  wingdi.h


NUMLOCK_ON
NUMLOCK_ON  0x0020  wincon.h

The NUM LOCK light is on. See KEY_EVENT_RECORD.


FN_NUMLOCK_ON
NUMLOCK_ON  0x0020  wincon.h


NUMPENS
NUMPENS  18  wingdi.h

Number of device-specific pens. See GetDeviceCaps.


FN_NUMPENS
NUMPENS  18  wingdi.h


NUMRESERVED
NUMRESERVED  106  wingdi.h

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 version 3.0 or later. See GetDeviceCaps.


FN_NUMRESERVED
NUMRESERVED  106  wingdi.h


OBJ_BITMAP
OBJ_BITMAP  7  wingdi.h

Bitmap See GetObjectType.


FN_OBJ_BITMAP
OBJ_BITMAP  7  wingdi.h


OBJ_BITMAP
OBJ_BITMAP  7  wingdi.h

Returns the current selected bitmap if hdc is a memory DC. See GetCurrentObject.


FN_OBJ_BITMAP
OBJ_BITMAP  7  wingdi.h


OBJ_BRUSH
OBJ_BRUSH  2  wingdi.h

Brush See GetObjectType.


FN_OBJ_BRUSH
OBJ_BRUSH  2  wingdi.h


OBJ_BRUSH
OBJ_BRUSH  2  wingdi.h

Returns the current selected brush. See GetCurrentObject.


FN_OBJ_BRUSH
OBJ_BRUSH  2  wingdi.h


OBJ_DC
OBJ_DC  3  wingdi.h

Device context See GetObjectType.


FN_OBJ_DC
OBJ_DC  3  wingdi.h


OBJ_ENHMETADC
OBJ_ENHMETADC  12  wingdi.h

Enhanced metafile device context See GetObjectType.


FN_OBJ_ENHMETADC
OBJ_ENHMETADC  12  wingdi.h


OBJ_ENHMETAFILE
OBJ_ENHMETAFILE  13  wingdi.h

Enhanced metafile See GetObjectType.


FN_OBJ_ENHMETAFILE
OBJ_ENHMETAFILE  13  wingdi.h


OBJ_EXTPEN
OBJ_EXTPEN  11  wingdi.h

Extended pen See GetObjectType.


FN_OBJ_EXTPEN
OBJ_EXTPEN  11  wingdi.h


OBJ_FONT
OBJ_FONT  6  wingdi.h

Font See GetObjectType.


FN_OBJ_FONT
OBJ_FONT  6  wingdi.h


OBJ_FONT
OBJ_FONT  6  wingdi.h

Returns the current selected font. See GetCurrentObject.


FN_OBJ_FONT
OBJ_FONT  6  wingdi.h


OBJ_MEMDC
OBJ_MEMDC  10  wingdi.h

Memory device context See GetObjectType.


FN_OBJ_MEMDC
OBJ_MEMDC  10  wingdi.h


OBJ_METADC
OBJ_METADC  4  wingdi.h

Metafile device context See GetObjectType.


FN_OBJ_METADC
OBJ_METADC  4  wingdi.h


OBJ_METAFILE
OBJ_METAFILE  9  wingdi.h

Metafile See GetObjectType.


FN_OBJ_METAFILE
OBJ_METAFILE  9  wingdi.h


OBJ_PAL
OBJ_PAL  5  wingdi.h

Palette See GetObjectType.


FN_OBJ_PAL
OBJ_PAL  5  wingdi.h


OBJ_PAL
OBJ_PAL  5  wingdi.h

Returns the current selected palette. See GetCurrentObject.


FN_OBJ_PAL
OBJ_PAL  5  wingdi.h


OBJ_PEN
OBJ_PEN  1  wingdi.h

Pen See GetObjectType.


FN_OBJ_PEN
OBJ_PEN  1  wingdi.h


OBJ_PEN
OBJ_PEN  1  wingdi.h

Returns the current selected pen. See GetCurrentObject.


FN_OBJ_PEN
OBJ_PEN  1  wingdi.h


OBJ_REGION
OBJ_REGION  8  wingdi.h

Region See GetObjectType.


FN_OBJ_REGION
OBJ_REGION  8  wingdi.h


OBJECT_INHERIT_ACE
OBJECT_INHERIT_ACE  (0x1)  winnt.h

The ACE is inherited by non-container objects (for example, files) created within the container object to which the ACE is assigned. See ACE_HEADER.


FN_OBJECT_INHERIT_ACE
OBJECT_INHERIT_ACE  (0x1)  winnt.h


ODA_DRAWENTIRE
ODA_DRAWENTIRE  0x0001  winuser.h

Indicates the entire control needs to be drawn. See DRAWITEMSTRUCT.


FN_ODA_DRAWENTIRE
ODA_DRAWENTIRE  0x0001  winuser.h


ODA_FOCUS
ODA_FOCUS  0x0004  winuser.h

Indicates the control has lost or gained the keyboard focus. The itemState member should be checked to determine whether the control has the focus. See DRAWITEMSTRUCT.


FN_ODA_FOCUS
ODA_FOCUS  0x0004  winuser.h


ODA_SELECT
ODA_SELECT  0x0002  winuser.h

Indicates the selection status has changed. The itemState member should be checked to determine the new selection state. See DRAWITEMSTRUCT.


FN_ODA_SELECT
ODA_SELECT  0x0002  winuser.h


ODDPARITY
ODDPARITY  1  winbase.h

Odd See DCB.


FN_ODDPARITY
ODDPARITY  1  winbase.h


ODS_CHECKED
ODS_CHECKED  0x0008  winuser.h

Indicates the menu item is to be checked. This bit is used only in a menu. See DRAWITEMSTRUCT.


FN_ODS_CHECKED
ODS_CHECKED  0x0008  winuser.h


ODS_DISABLED
ODS_DISABLED  0x0004  winuser.h

Indicates the item is to be drawn as disabled. See DRAWITEMSTRUCT.


FN_ODS_DISABLED
ODS_DISABLED  0x0004  winuser.h


ODS_FOCUS
ODS_FOCUS  0x0010  winuser.h

Indicates the item has the keyboard focus. See DRAWITEMSTRUCT.


FN_ODS_FOCUS
ODS_FOCUS  0x0010  winuser.h


ODS_GRAYED
ODS_GRAYED  0x0002  winuser.h

Indicates the item is to be grayed. This bit is used only in a menu. See DRAWITEMSTRUCT.


FN_ODS_GRAYED
ODS_GRAYED  0x0002  winuser.h


ODS_SELECTED
ODS_SELECTED  0x0001  winuser.h

Indicates the item's status is selected. See DRAWITEMSTRUCT.


FN_ODS_SELECTED
ODS_SELECTED  0x0001  winuser.h


ODT_BUTTON
ODT_BUTTON  4  winuser.h

Owner-drawn button See MEASUREITEMSTRUCT, DRAWITEMSTRUCT.


FN_ODT_BUTTON
ODT_BUTTON  4  winuser.h


ODT_COMBOBOX
ODT_COMBOBOX  3  winuser.h

Owner-drawn combo box See MEASUREITEMSTRUCT, DRAWITEMSTRUCT.


FN_ODT_COMBOBOX
ODT_COMBOBOX  3  winuser.h


ODT_LISTBOX
ODT_LISTBOX  2  winuser.h

Owner-drawn list box See MEASUREITEMSTRUCT, DRAWITEMSTRUCT.


FN_ODT_LISTBOX
ODT_LISTBOX  2  winuser.h


ODT_MENU
ODT_MENU  1  winuser.h

Owner-drawn menu See MEASUREITEMSTRUCT, DRAWITEMSTRUCT.


FN_ODT_MENU
ODT_MENU  1  winuser.h


OEM_FIXED_FONT
OEM_FIXED_FONT  10  wingdi.h

OEM-dependent fixed font See GetStockObject.


FN_OEM_FIXED_FONT
OEM_FIXED_FONT  10  wingdi.h


OF_CANCEL
OF_CANCEL  0x00000800  winbase.h

Ignored. In Win32, the OF_PROMPT style produces a dialog box that contains a Cancel button. OF_CANCEL Ignored. In the Win32 API, the OF_PROMPT style produces a dialog box that contains a Cancel button. See LZOpenFile, OpenFile.


FN_OF_CANCEL
OF_CANCEL  0x00000800  winbase.h


OF_CREATE
OF_CREATE  0x00001000  winbase.h

Creates a new file. If the file already exists, it is truncated to zero length. See LZOpenFile, OpenFile.


FN_OF_CREATE
OF_CREATE  0x00001000  winbase.h


OF_DELETE
OF_DELETE  0x00000200  winbase.h

Deletes the file. See LZOpenFile, OpenFile.


FN_OF_DELETE
OF_DELETE  0x00000200  winbase.h


OF_EXIST
OF_EXIST  0x00004000  winbase.h

Opens the file, and then closes it. Used to test for file existence. See LZOpenFile, OpenFile.


FN_OF_EXIST
OF_EXIST  0x00004000  winbase.h


OF_PARSE
OF_PARSE  0x00000100  winbase.h

Fills the OFSTRUCT data structure but carries out no other action. See LZOpenFile, OpenFile.


FN_OF_PARSE
OF_PARSE  0x00000100  winbase.h


OF_PROMPT
OF_PROMPT  0x00002000  winbase.h

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. Pressing the Cancel button directs OpenFile to return a file-not-found error message. See LZOpenFile, OpenFile.


FN_OF_PROMPT
OF_PROMPT  0x00002000  winbase.h


OF_READ
OF_READ  0x00000000  winbase.h

Opens the file for reading only. See _lopen, LZOpenFile, OpenFile.


FN_OF_READ
OF_READ  0x00000000  winbase.h


OF_READWRITE
OF_READWRITE  0x00000002  winbase.h

Opens the file for reading and writing. See _lopen, LZOpenFile, OpenFile.


FN_OF_READWRITE
OF_READWRITE  0x00000002  winbase.h


OF_REOPEN
OF_REOPEN  0x00008000  winbase.h

Opens the file using information in the re-open buffer. See LZOpenFile, OpenFile.


FN_OF_REOPEN
OF_REOPEN  0x00008000  winbase.h


OF_SHARE_COMPAT
OF_SHARE_COMPAT  0x00000000  winbase.h

Opens the file in compatibility mode, enabling any process on a given machine to open the file any number of times. _lopen fails if the file has been opened by using any of the other share modes. See _lopen, OpenFile.


FN_OF_SHARE_COMPAT
OF_SHARE_COMPAT  0x00000000  winbase.h


OF_SHARE_DENY_NONE
OF_SHARE_DENY_NONE  0x00000040  winbase.h

Opens the file without denying other processes read or write access to the file. _lopen fails if the file has been opened in compatibility mode by any other process. See _lopen, LZOpenFile, OpenFile.


FN_OF_SHARE_DENY_NONE
OF_SHARE_DENY_NONE  0x00000040  winbase.h


OF_SHARE_DENY_READ
OF_SHARE_DENY_READ  0x00000030  winbase.h

Opens the file and denies other processes read access to the file. _lopen fails if the file has been opened in compatibility mode or for read access by any other process. See _lopen, LZOpenFile, OpenFile.


FN_OF_SHARE_DENY_READ
OF_SHARE_DENY_READ  0x00000030  winbase.h


OF_SHARE_DENY_WRITE
OF_SHARE_DENY_WRITE  0x00000020  winbase.h

Opens the file and denies other processes write access to the file. _lopen fails if the file has been opened in compatibility mode or for write access by any other process. See _lopen, LZOpenFile, OpenFile.


FN_OF_SHARE_DENY_WRITE
OF_SHARE_DENY_WRITE  0x00000020  winbase.h


OF_SHARE_EXCLUSIVE
OF_SHARE_EXCLUSIVE  0x00000010  winbase.h

Opens the file in exclusive mode, denying other processes both read and write access to the file. _lopen fails if the file has been opened in any other mode for read or write access, even by the current process. See _lopen, LZOpenFile, OpenFile.


FN_OF_SHARE_EXCLUSIVE
OF_SHARE_EXCLUSIVE  0x00000010  winbase.h


OF_VERIFY
OF_VERIFY  0x00000400  winbase.h

Verifys 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. See OpenFile.


FN_OF_VERIFY
OF_VERIFY  0x00000400  winbase.h


OF_WRITE
OF_WRITE  0x00000001  winbase.h

Opens the file for writing only. See _lopen, LZOpenFile, OpenFile.


FN_OF_WRITE
OF_WRITE  0x00000001  winbase.h


OFN_ALLOWMULTISELECT
OFN_ALLOWMULTISELECT  0x00000200  commdlg.h

Specifies the File Name listbox allows multiple selections. (If the dialog is created by using a private template, the LBS_EXTENDEDSEL constant must appear in the definition of the File Name listbox.) See OPENFILENAME.


FN_OFN_ALLOWMULTISELECT
OFN_ALLOWMULTISELECT  0x00000200  commdlg.h


OFN_CREATEPROMPT
OFN_CREATEPROMPT  0x00002000  commdlg.h

Specifies the dialog function should query the user as to whether or not they wish to create a file that does not currently exist. (This flag automatically sets the OFN_PATHMUSTEXIST and OFN_FILEMUSTEXIST flags.) See OPENFILENAME.


FN_OFN_CREATEPROMPT
OFN_CREATEPROMPT  0x00002000  commdlg.h


OFN_ENABLEHOOK
OFN_ENABLEHOOK  0x00000020  commdlg.h

Enables the hook function specified in the lpfnHook member. See OPENFILENAME.


FN_OFN_ENABLEHOOK
OFN_ENABLEHOOK  0x00000020  commdlg.h


OFN_ENABLETEMPLATE
OFN_ENABLETEMPLATE  0x00000040  commdlg.h

Causes the operating system to create the dialog box by using the dialog template identified by the hInstance and lpTemplateName members. See OPENFILENAME.


FN_OFN_ENABLETEMPLATE
OFN_ENABLETEMPLATE  0x00000040  commdlg.h


OFN_ENABLETEMPLATEHANDLE
OFN_ENABLETEMPLATEHANDLE  0x00000080  commdlg.h

Indicates the hInstance member identifies a data block that contains a pre-loaded dialog template. The operating system ignores the lpTemplateName member if this flag is specified. See OPENFILENAME.


FN_OFN_ENABLETEMPLATEHANDLE
OFN_ENABLETEMPLATEHANDLE  0x00000080  commdlg.h


OFN_EXTENSIONDIFFERENT
OFN_EXTENSIONDIFFERENT  0x00000400  commdlg.h

Specifies the user entered a file extension that differs from the extension specified by lpstrDefExt. The function does not set this flag if lpstrDefExt is NULL. See OPENFILENAME.


FN_OFN_EXTENSIONDIFFERENT
OFN_EXTENSIONDIFFERENT  0x00000400  commdlg.h


OFN_FILEMUSTEXIST
OFN_FILEMUSTEXIST  0x00001000  commdlg.h

Specifies the user can only enter names of existing files in the File Name entry field. If this flag is set and the user enters an invalid file name in the File Name entry field, the dialog function displays a warning in a message box. The setting of this flag causes the OFN_PATHMUSTEXIST flag to be set. See OPENFILENAME.


FN_OFN_FILEMUSTEXIST
OFN_FILEMUSTEXIST  0x00001000  commdlg.h


OFN_HIDEREADONLY
OFN_HIDEREADONLY  0x00000004  commdlg.h

Hides the read only checkbox. See OPENFILENAME.


FN_OFN_HIDEREADONLY
OFN_HIDEREADONLY  0x00000004  commdlg.h


OFN_NOCHANGEDIR
OFN_NOCHANGEDIR  0x00000008  commdlg.h

Forces the dialog box to set the current directory back to what it was when the dialog was invoked. See OPENFILENAME.


FN_OFN_NOCHANGEDIR
OFN_NOCHANGEDIR  0x00000008  commdlg.h


OFN_NONETWORKBUTTON
OFN_NONETWORKBUTTON  0x00020000  commdlg.h

Hides and disables the network button. See OPENFILENAME.


FN_OFN_NONETWORKBUTTON
OFN_NONETWORKBUTTON  0x00020000  commdlg.h


OFN_NOREADONLYRETURN
OFN_NOREADONLYRETURN  0x00008000  commdlg.h

Specifies the returned file does not have the Read Only attribute set and is not in a write-protected directory. See OPENFILENAME.


FN_OFN_NOREADONLYRETURN
OFN_NOREADONLYRETURN  0x00008000  commdlg.h


OFN_NOTESTFILECREATE
OFN_NOTESTFILECREATE  0x00010000  commdlg.h

Specifies the file is not created before the dialog box is closed. This flag should be set if the application saves the file on a create-no-modify network share point. When an application sets this flag, the library does not check against write protection, a full disk, an open drive door, or network protection. Therefore, applications using this flag must perform file operations carefully, a file cannot be reopened once closed. See OPENFILENAME.


FN_OFN_NOTESTFILECREATE
OFN_NOTESTFILECREATE  0x00010000  commdlg.h


OFN_NOVALIDATE
OFN_NOVALIDATE  0x00000100  commdlg.h

Specifies the common dialog boxes allow invalid characters in the returned filename. Typically, the calling application uses a hook function that checks the filename by using the FILEOKSTRING registered message. If the text in the edit control is empty or contains nothing but spaces, the lists of files and directories are updated. If the text in the edit control contains anything else, the nFileOffset and nFileExtension members are set to values generated by parsing the text. No default extension is added to the text, nor is text copied to the lpstrFileTitle buffer. If the value specified by the nFileOffset member is negative, the filename is invalid. If the value specified by nFileOffset is not negative, the filename is valid, and nFileOffset and nFileExtension can be used as if the OFN_NOVALIDATE flag had not been set. See OPENFILENAME.


FN_OFN_NOVALIDATE
OFN_NOVALIDATE  0x00000100  commdlg.h


OFN_OVERWRITEPROMPT
OFN_OVERWRITEPROMPT  0x00000002  commdlg.h

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. See OPENFILENAME.


FN_OFN_OVERWRITEPROMPT
OFN_OVERWRITEPROMPT  0x00000002  commdlg.h


OFN_PATHMUSTEXIST
OFN_PATHMUSTEXIST  0x00000800  commdlg.h

Specifies the user can only enter valid path names. If this flag is set and the user enters an invalid path name in the File Name entry field, the dialog function displays a warning in a message box. See OPENFILENAME.


FN_OFN_PATHMUSTEXIST
OFN_PATHMUSTEXIST  0x00000800  commdlg.h


OFN_READONLY
OFN_READONLY  0x00000001  commdlg.h

Causes the "Read only" checkbox to be initially checked when the dialog box is created. Indicates the state of the "Read only" checkbox when the dialog box is dismissed. See OPENFILENAME.


FN_OFN_READONLY
OFN_READONLY  0x00000001  commdlg.h


OFN_SHAREAWARE
OFN_SHAREAWARE  0x00004000  commdlg.h

Specifies if a call to the OpenFile function fails because of a network sharing violation, the error is ignored and the dialog box returns the given filename. If this flag is not set, the registered message for SHAREVISTRING is sent to the hook function, with a pointer to a null-terminated string for the path name in the lParam parameter. The hook function responds with one of the following values: See OPENFILENAME.


FN_OFN_SHAREAWARE
OFN_SHAREAWARE  0x00004000  commdlg.h


OFN_SHAREFALLTHROUGH
OFN_SHAREFALLTHROUGH  2  commdlg.h

Specifies the filename is returned from the dialog box. See OPENFILENAME.


FN_OFN_SHAREFALLTHROUGH
OFN_SHAREFALLTHROUGH  2  commdlg.h


OFN_SHARENOWARN
OFN_SHARENOWARN  1  commdlg.h

Specifies no further action. See OPENFILENAME.


FN_OFN_SHARENOWARN
OFN_SHARENOWARN  1  commdlg.h


OFN_SHAREWARN
OFN_SHAREWARN  0  commdlg.h

Specifies the user receives the standard warning message for this error. The same result if there were no hook function. See OPENFILENAME.


FN_OFN_SHAREWARN
OFN_SHAREWARN  0  commdlg.h


OFN_SHOWHELP
OFN_SHOWHELP  0x00000010  commdlg.h

Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified. See OPENFILENAME.


FN_OFN_SHOWHELP
OFN_SHOWHELP  0x00000010  commdlg.h


ONE5STOPBITS
ONE5STOPBITS  1  winbase.h

1.5 stop bits See DCB.


FN_ONE5STOPBITS
ONE5STOPBITS  1  winbase.h


ONESTOPBIT
ONESTOPBIT  0  winbase.h

1 stop bit See DCB.


FN_ONESTOPBIT
ONESTOPBIT  0  winbase.h


OPAQUE
OPAQUE  2  wingdi.h

Background is filled with the current background color before the text, hatched brush, or pen is drawn. See SetBkMode.


FN_OPAQUE
OPAQUE  2  wingdi.h


OPEN_ALWAYS
OPEN_ALWAYS  4  winbase.h

Opens the file if it exists. If the file does not exist, the function creates the file as if fdwCreate were CREATE_NEW. See CreateFile.


FN_OPEN_ALWAYS
OPEN_ALWAYS  4  winbase.h


OPEN_EXISTING
OPEN_EXISTING  3  winbase.h

Opens the file. Fails if the file does not exist. See CreateFile.


FN_OPEN_EXISTING
OPEN_EXISTING  3  winbase.h


OUTPUT_DEBUG_STRING_EVENT
OUTPUT_DEBUG_STRING_EVENT  8  winbase.h

Reports an output debugging string debugging event. The value of u.DebugString specifies an OUTPUT_DEBUG_STRING_INFO structure. See DEBUG_EVENT.


FN_OUTPUT_DEBUG_STRING_EVENT
OUTPUT_DEBUG_STRING_EVENT  8  winbase.h


OWNER_SECURITY_INFORMATION
OWNER_SECURITY_INFORMATION  (0X00000001L)  winnt.h

When set, this bit indicates the owner ID of the object is being referenced. See SECURITY_INFORMATION.


FN_OWNER_SECURITY_INFORMATION
OWNER_SECURITY_INFORMATION  (0X00000001L)  winnt.h


PAGE_EXECUTE
PAGE_EXECUTE  0x10  winnt.h

Execute access to the committed region of pages is allowed. An attempt to read or write the committed region results in an access violation. See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx


FN_PAGE_EXECUTE
PAGE_EXECUTE  0x10  winnt.h


PAGE_EXECUTE_READ
PAGE_EXECUTE_READ  0x20  winnt.h

Execute and read access to the region of committed pages is allowed. An attempt to write the committed region results in an access violation. See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx


FN_PAGE_EXECUTE_READ
PAGE_EXECUTE_READ  0x20  winnt.h


PAGE_EXECUTE_READWRITE
PAGE_EXECUTE_READWRITE  0x40  winnt.h

Execute, read, and write access to the region of committed pages is allowed. See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx


FN_PAGE_EXECUTE_READWRITE
PAGE_EXECUTE_READWRITE  0x40  winnt.h


PAGE_EXECUTE_WRITECOPY
PAGE_EXECUTE_WRITECOPY  0x80  winnt.h

Execute, read, and write access to the region of committed pages is allowed. The pages are shared read-on/copy-on-write. See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx


FN_PAGE_EXECUTE_WRITECOPY
PAGE_EXECUTE_WRITECOPY  0x80  winnt.h


PAGE_GUARD
PAGE_GUARD  0x100  winnt.h

Protect 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 value is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS. See  VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx


FN_PAGE_GUARD
PAGE_GUARD  0x100  winnt.h


PAGE_NOACCESS
PAGE_NOACCESS  0x01  winnt.h

No access to the committed region of pages is allowed. An attempt to read, write, or execute the committed region results in an access violation. See VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx


FN_PAGE_NOACCESS
PAGE_NOACCESS  0x01  winnt.h


PAGE_NOCACHE
PAGE_NOCACHE  0x200  winnt.h

No cacheing of the committed regions of pages is allowed. 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 no cache. See VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx


FN_PAGE_NOCACHE
PAGE_NOCACHE  0x200  winnt.h


PAGE_READONLY
PAGE_READONLY  0x02  winnt.h

Gives read access to the committed region of pages. An attempt to write or execute the committed region results in an access violation. See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx


FN_PAGE_READONLY
PAGE_READONLY  0x02  winnt.h


PAGE_READWRITE
PAGE_READWRITE  0x04  winnt.h

Gives read and write access to the committed region of pages. See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx


FN_PAGE_READWRITE
PAGE_READWRITE  0x04  winnt.h


PAGE_WRITECOPY
PAGE_WRITECOPY  0x08  winnt.h

Gives copy-on-write access to the committed region of pages. See CreateFileMapping, VirtualAlloc, VirtualProtect, VirtualProtectEx, VirtualQuery, VirtualQueryEx


FN_PAGE_WRITECOPY
PAGE_WRITECOPY  0x08  winnt.h


PAN_ANY
PAN_ANY  0  wingdi.h

Any See PANOSE.


FN_PAN_ANY
PAN_ANY  0  wingdi.h


PAN_BENT_ARMS_DOUBLE_SERIF
PAN_BENT_ARMS_DOUBLE_SERIF  11  wingdi.h

Non-Straight Arms/Double-Serif See PANOSE.


FN_PAN_BENT_ARMS_DOUBLE_SERIF
PAN_BENT_ARMS_DOUBLE_SERIF  11  wingdi.h


PAN_BENT_ARMS_HORZ
PAN_BENT_ARMS_HORZ  7  wingdi.h

Non-Straight Arms/Horizontal See PANOSE.


FN_PAN_BENT_ARMS_HORZ
PAN_BENT_ARMS_HORZ  7  wingdi.h


PAN_BENT_ARMS_SINGLE_SERIF
PAN_BENT_ARMS_SINGLE_SERIF  10  wingdi.h

Non-Straight Arms/Single-Serif See PANOSE.


FN_PAN_BENT_ARMS_SINGLE_SERIF
PAN_BENT_ARMS_SINGLE_SERIF  10  wingdi.h


PAN_BENT_ARMS_VERT
PAN_BENT_ARMS_VERT  9  wingdi.h

Non-Straight Arms/Vertical See PANOSE.


FN_PAN_BENT_ARMS_VERT
PAN_BENT_ARMS_VERT  9  wingdi.h


PAN_BENT_ARMS_WEDGE
PAN_BENT_ARMS_WEDGE  8  wingdi.h

Non-Straight Arms/Wedge See PANOSE.


FN_PAN_BENT_ARMS_WEDGE
PAN_BENT_ARMS_WEDGE  8  wingdi.h


PAN_CONTRAST_HIGH
PAN_CONTRAST_HIGH  8  wingdi.h

High See PANOSE.


FN_PAN_CONTRAST_HIGH
PAN_CONTRAST_HIGH  8  wingdi.h


PAN_CONTRAST_LOW
PAN_CONTRAST_LOW  4  wingdi.h

Low See PANOSE.


FN_PAN_CONTRAST_LOW
PAN_CONTRAST_LOW  4  wingdi.h


PAN_CONTRAST_MEDIUM
PAN_CONTRAST_MEDIUM  6  wingdi.h

Medium See PANOSE.


FN_PAN_CONTRAST_MEDIUM
PAN_CONTRAST_MEDIUM  6  wingdi.h


PAN_CONTRAST_MEDIUM_HIGH
PAN_CONTRAST_MEDIUM_HIGH  7  wingdi.h

Medium High See PANOSE.


FN_PAN_CONTRAST_MEDIUM_HIGH
PAN_CONTRAST_MEDIUM_HIGH  7  wingdi.h


PAN_CONTRAST_MEDIUM_LOW
PAN_CONTRAST_MEDIUM_LOW  5  wingdi.h

Medium Low See PANOSE.


FN_PAN_CONTRAST_MEDIUM_LOW
PAN_CONTRAST_MEDIUM_LOW  5  wingdi.h


PAN_CONTRAST_NONE
PAN_CONTRAST_NONE  2  wingdi.h

None See PANOSE.


FN_PAN_CONTRAST_NONE
PAN_CONTRAST_NONE  2  wingdi.h


PAN_CONTRAST_VERY_HIGH
PAN_CONTRAST_VERY_HIGH  9  wingdi.h

Very High See PANOSE.


FN_PAN_CONTRAST_VERY_HIGH
PAN_CONTRAST_VERY_HIGH  9  wingdi.h


PAN_CONTRAST_VERY_LOW
PAN_CONTRAST_VERY_LOW  3  wingdi.h

Very Low See PANOSE.


FN_PAN_CONTRAST_VERY_LOW
PAN_CONTRAST_VERY_LOW  3  wingdi.h


PAN_CULTURE_LATIN
PAN_CULTURE_LATIN  0  wingdi.h

Latin See PANOSE.


FN_PAN_CULTURE_LATIN
PAN_CULTURE_LATIN  0  wingdi.h


PAN_FAMILY_DECORATIVE
PAN_FAMILY_DECORATIVE  4  wingdi.h

Decorative See PANOSE.


FN_PAN_FAMILY_DECORATIVE
PAN_FAMILY_DECORATIVE  4  wingdi.h


PAN_FAMILY_PICTORIAL
PAN_FAMILY_PICTORIAL  5  wingdi.h

Pictorial See PANOSE.


FN_PAN_FAMILY_PICTORIAL
PAN_FAMILY_PICTORIAL  5  wingdi.h


PAN_FAMILY_SCRIPT
PAN_FAMILY_SCRIPT  3  wingdi.h

Script See PANOSE.


FN_PAN_FAMILY_SCRIPT
PAN_FAMILY_SCRIPT  3  wingdi.h


PAN_FAMILY_TEXT_DISPLAY
PAN_FAMILY_TEXT_DISPLAY  2  wingdi.h

Text and Display See PANOSE.


FN_PAN_FAMILY_TEXT_DISPLAY
PAN_FAMILY_TEXT_DISPLAY  2  wingdi.h


PAN_LETT_NORMAL_BOXED
PAN_LETT_NORMAL_BOXED  4  wingdi.h

Normal/Boxed See PANOSE.


FN_PAN_LETT_NORMAL_BOXED
PAN_LETT_NORMAL_BOXED  4  wingdi.h


PAN_LETT_NORMAL_CONTACT
PAN_LETT_NORMAL_CONTACT  2  wingdi.h

Normal/Contact See PANOSE.


FN_PAN_LETT_NORMAL_CONTACT
PAN_LETT_NORMAL_CONTACT  2  wingdi.h


PAN_LETT_NORMAL_FLATTENED
PAN_LETT_NORMAL_FLATTENED  5  wingdi.h

Normal/Flattened See PANOSE.


FN_PAN_LETT_NORMAL_FLATTENED
PAN_LETT_NORMAL_FLATTENED  5  wingdi.h


PAN_LETT_NORMAL_OFF_CENTER
PAN_LETT_NORMAL_OFF_CENTER  7  wingdi.h

Normal/Off Center See PANOSE.


FN_PAN_LETT_NORMAL_OFF_CENTER
PAN_LETT_NORMAL_OFF_CENTER  7  wingdi.h


PAN_LETT_NORMAL_ROUNDED
PAN_LETT_NORMAL_ROUNDED  6  wingdi.h

Normal/Rounded See PANOSE.


FN_PAN_LETT_NORMAL_ROUNDED
PAN_LETT_NORMAL_ROUNDED  6  wingdi.h


PAN_LETT_NORMAL_SQUARE
PAN_LETT_NORMAL_SQUARE  8  wingdi.h

Normal/Square See PANOSE.


FN_PAN_LETT_NORMAL_SQUARE
PAN_LETT_NORMAL_SQUARE  8  wingdi.h


PAN_LETT_NORMAL_WEIGHTED
PAN_LETT_NORMAL_WEIGHTED  3  wingdi.h

Normal/Weighted See PANOSE.


FN_PAN_LETT_NORMAL_WEIGHTED
PAN_LETT_NORMAL_WEIGHTED  3  wingdi.h


PAN_LETT_OBLIQUE_BOXED
PAN_LETT_OBLIQUE_BOXED  11  wingdi.h

Oblique/Boxed See PANOSE.


FN_PAN_LETT_OBLIQUE_BOXED
PAN_LETT_OBLIQUE_BOXED  11  wingdi.h


PAN_LETT_OBLIQUE_CONTACT
PAN_LETT_OBLIQUE_CONTACT  9  wingdi.h

Oblique/Contact See PANOSE.


FN_PAN_LETT_OBLIQUE_CONTACT
PAN_LETT_OBLIQUE_CONTACT  9  wingdi.h


PAN_LETT_OBLIQUE_FLATTENED
PAN_LETT_OBLIQUE_FLATTENED  12  wingdi.h

Oblique/Flattened See PANOSE.


FN_PAN_LETT_OBLIQUE_FLATTENED
PAN_LETT_OBLIQUE_FLATTENED  12  wingdi.h


PAN_LETT_OBLIQUE_OFF_CENTER
PAN_LETT_OBLIQUE_OFF_CENTER  14  wingdi.h

Oblique/Off Center See PANOSE.


FN_PAN_LETT_OBLIQUE_OFF_CENTER
PAN_LETT_OBLIQUE_OFF_CENTER  14  wingdi.h


PAN_LETT_OBLIQUE_ROUNDED
PAN_LETT_OBLIQUE_ROUNDED  13  wingdi.h

Oblique/Rounded See PANOSE.


FN_PAN_LETT_OBLIQUE_ROUNDED
PAN_LETT_OBLIQUE_ROUNDED  13  wingdi.h


PAN_LETT_OBLIQUE_SQUARE
PAN_LETT_OBLIQUE_SQUARE  15  wingdi.h

Oblique/Square See PANOSE.


FN_PAN_LETT_OBLIQUE_SQUARE
PAN_LETT_OBLIQUE_SQUARE  15  wingdi.h


PAN_LETT_OBLIQUE_WEIGHTED
PAN_LETT_OBLIQUE_WEIGHTED  10  wingdi.h

Oblique/Weighted See PANOSE.


FN_PAN_LETT_OBLIQUE_WEIGHTED
PAN_LETT_OBLIQUE_WEIGHTED  10  wingdi.h


PAN_MIDLINE_CONSTANT_POINTED
PAN_MIDLINE_CONSTANT_POINTED  9  wingdi.h

Constant/Pointed See PANOSE.


FN_PAN_MIDLINE_CONSTANT_POINTED
PAN_MIDLINE_CONSTANT_POINTED  9  wingdi.h


PAN_MIDLINE_CONSTANT_SERIFED
PAN_MIDLINE_CONSTANT_SERIFED  10  wingdi.h

Constant/Serifed See PANOSE.


FN_PAN_MIDLINE_CONSTANT_SERIFED
PAN_MIDLINE_CONSTANT_SERIFED  10  wingdi.h


PAN_MIDLINE_CONSTANT_TRIMMED
PAN_MIDLINE_CONSTANT_TRIMMED  8  wingdi.h

Constant/Trimmed See PANOSE.


FN_PAN_MIDLINE_CONSTANT_TRIMMED
PAN_MIDLINE_CONSTANT_TRIMMED  8  wingdi.h


PAN_MIDLINE_HIGH_POINTED
PAN_MIDLINE_HIGH_POINTED  6  wingdi.h

High/Pointed See PANOSE.


FN_PAN_MIDLINE_HIGH_POINTED
PAN_MIDLINE_HIGH_POINTED  6  wingdi.h


PAN_MIDLINE_HIGH_SERIFED
PAN_MIDLINE_HIGH_SERIFED  7  wingdi.h

High/Serifed See PANOSE.


FN_PAN_MIDLINE_HIGH_SERIFED
PAN_MIDLINE_HIGH_SERIFED  7  wingdi.h


PAN_MIDLINE_HIGH_TRIMMED
PAN_MIDLINE_HIGH_TRIMMED  5  wingdi.h

High/Trimmed See PANOSE.


FN_PAN_MIDLINE_HIGH_TRIMMED
PAN_MIDLINE_HIGH_TRIMMED  5  wingdi.h


PAN_MIDLINE_LOW_POINTED
PAN_MIDLINE_LOW_POINTED  12  wingdi.h

Low/Pointed See PANOSE.


FN_PAN_MIDLINE_LOW_POINTED
PAN_MIDLINE_LOW_POINTED  12  wingdi.h


PAN_MIDLINE_LOW_SERIFED
PAN_MIDLINE_LOW_SERIFED  13  wingdi.h

Low/Serifed See PANOSE.


FN_PAN_MIDLINE_LOW_SERIFED
PAN_MIDLINE_LOW_SERIFED  13  wingdi.h


PAN_MIDLINE_LOW_TRIMMED
PAN_MIDLINE_LOW_TRIMMED  11  wingdi.h

Low/Trimmed See PANOSE.


FN_PAN_MIDLINE_LOW_TRIMMED
PAN_MIDLINE_LOW_TRIMMED  11  wingdi.h


PAN_MIDLINE_STANDARD_POINTED
PAN_MIDLINE_STANDARD_POINTED  3  wingdi.h

Standard/Pointed See PANOSE.


FN_PAN_MIDLINE_STANDARD_POINTED
PAN_MIDLINE_STANDARD_POINTED  3  wingdi.h


PAN_MIDLINE_STANDARD_SERIFED
PAN_MIDLINE_STANDARD_SERIFED  4  wingdi.h

Standard/Serifed See PANOSE.


FN_PAN_MIDLINE_STANDARD_SERIFED
PAN_MIDLINE_STANDARD_SERIFED  4  wingdi.h


PAN_MIDLINE_STANDARD_TRIMMED
PAN_MIDLINE_STANDARD_TRIMMED  2  wingdi.h

Standard/Trimmed See PANOSE.


FN_PAN_MIDLINE_STANDARD_TRIMMED
PAN_MIDLINE_STANDARD_TRIMMED  2  wingdi.h


PAN_NO_FIT
PAN_NO_FIT  1  wingdi.h

No Fit See PANOSE.


FN_PAN_NO_FIT
PAN_NO_FIT  1  wingdi.h


PAN_NO_FIT
PAN_NO_FIT  1  wingdi.h

No Fit See PANOSE.


FN_PAN_NO_FIT
PAN_NO_FIT  1  wingdi.h


PAN_PROP_CONDENSED
PAN_PROP_CONDENSED  6  wingdi.h

Condensed See PANOSE.


FN_PAN_PROP_CONDENSED
PAN_PROP_CONDENSED  6  wingdi.h


PAN_PROP_EVEN_WIDTH
PAN_PROP_EVEN_WIDTH  4  wingdi.h

Even Width See PANOSE.


FN_PAN_PROP_EVEN_WIDTH
PAN_PROP_EVEN_WIDTH  4  wingdi.h


PAN_PROP_EXPANDED
PAN_PROP_EXPANDED  5  wingdi.h

Expanded See PANOSE.


FN_PAN_PROP_EXPANDED
PAN_PROP_EXPANDED  5  wingdi.h


PAN_PROP_MODERN
PAN_PROP_MODERN  3  wingdi.h

Modern See PANOSE.


FN_PAN_PROP_MODERN
PAN_PROP_MODERN  3  wingdi.h


PAN_PROP_MONOSPACED
PAN_PROP_MONOSPACED  9  wingdi.h

Monospaced See PANOSE.


FN_PAN_PROP_MONOSPACED
PAN_PROP_MONOSPACED  9  wingdi.h


PAN_PROP_OLD_STYLE
PAN_PROP_OLD_STYLE  2  wingdi.h

Old Style See PANOSE.


FN_PAN_PROP_OLD_STYLE
PAN_PROP_OLD_STYLE  2  wingdi.h


PAN_PROP_VERY_CONDENSED
PAN_PROP_VERY_CONDENSED  8  wingdi.h

Very Condensed See PANOSE.


FN_PAN_PROP_VERY_CONDENSED
PAN_PROP_VERY_CONDENSED  8  wingdi.h


PAN_PROP_VERY_EXPANDED
PAN_PROP_VERY_EXPANDED  7  wingdi.h

Very Expanded See PANOSE.


FN_PAN_PROP_VERY_EXPANDED
PAN_PROP_VERY_EXPANDED  7  wingdi.h


PAN_SERIF_BONE
PAN_SERIF_BONE  8  wingdi.h

Bone See PANOSE.


FN_PAN_SERIF_BONE
PAN_SERIF_BONE  8  wingdi.h


PAN_SERIF_COVE
PAN_SERIF_COVE  2  wingdi.h

Cove See PANOSE.


FN_PAN_SERIF_COVE
PAN_SERIF_COVE  2  wingdi.h


PAN_SERIF_EXAGGERATED
PAN_SERIF_EXAGGERATED  9  wingdi.h

Exaggerated See PANOSE.


FN_PAN_SERIF_EXAGGERATED
PAN_SERIF_EXAGGERATED  9  wingdi.h


PAN_SERIF_FLARED
PAN_SERIF_FLARED  14  wingdi.h

Flared See PANOSE.


FN_PAN_SERIF_FLARED
PAN_SERIF_FLARED  14  wingdi.h


PAN_SERIF_NORMAL_SANS
PAN_SERIF_NORMAL_SANS  11  wingdi.h

Normal Sans See PANOSE.


FN_PAN_SERIF_NORMAL_SANS
PAN_SERIF_NORMAL_SANS  11  wingdi.h


PAN_SERIF_OBTUSE_COVE
PAN_SERIF_OBTUSE_COVE  3  wingdi.h

Obtuse Cove See PANOSE.


FN_PAN_SERIF_OBTUSE_COVE
PAN_SERIF_OBTUSE_COVE  3  wingdi.h


PAN_SERIF_OBTUSE_SANS
PAN_SERIF_OBTUSE_SANS  12  wingdi.h

Obtuse Sans See PANOSE.


FN_PAN_SERIF_OBTUSE_SANS
PAN_SERIF_OBTUSE_SANS  12  wingdi.h


PAN_SERIF_OBTUSE_SQUARE_COVE
PAN_SERIF_OBTUSE_SQUARE_COVE  5  wingdi.h

Obtuse Square Cove See PANOSE.


FN_PAN_SERIF_OBTUSE_SQUARE_COVE
PAN_SERIF_OBTUSE_SQUARE_COVE  5  wingdi.h


PAN_SERIF_PERP_SANS
PAN_SERIF_PERP_SANS  13  wingdi.h

Prep Sans See PANOSE.


FN_PAN_SERIF_PERP_SANS
PAN_SERIF_PERP_SANS  13  wingdi.h


PAN_SERIF_ROUNDED
PAN_SERIF_ROUNDED  15  wingdi.h

Rounded See PANOSE.


FN_PAN_SERIF_ROUNDED
PAN_SERIF_ROUNDED  15  wingdi.h


PAN_SERIF_SQUARE
PAN_SERIF_SQUARE  6  wingdi.h

Square See PANOSE.


FN_PAN_SERIF_SQUARE
PAN_SERIF_SQUARE  6  wingdi.h


PAN_SERIF_SQUARE_COVE
PAN_SERIF_SQUARE_COVE  4  wingdi.h

Square Cove See PANOSE.


FN_PAN_SERIF_SQUARE_COVE
PAN_SERIF_SQUARE_COVE  4  wingdi.h


PAN_SERIF_THIN
PAN_SERIF_THIN  7  wingdi.h

Thin See PANOSE.


FN_PAN_SERIF_THIN
PAN_SERIF_THIN  7  wingdi.h


PAN_SERIF_TRIANGLE
PAN_SERIF_TRIANGLE  10  wingdi.h

Triangle See PANOSE.


FN_PAN_SERIF_TRIANGLE
PAN_SERIF_TRIANGLE  10  wingdi.h


PAN_STRAIGHT_ARMS_DOUBLE_SERIF
PAN_STRAIGHT_ARMS_DOUBLE_SERIF  6  wingdi.h

Straight Arms/Double-Serif See PANOSE.


FN_PAN_STRAIGHT_ARMS_DOUBLE_SERIF
PAN_STRAIGHT_ARMS_DOUBLE_SERIF  6  wingdi.h


PAN_STRAIGHT_ARMS_HORZ
PAN_STRAIGHT_ARMS_HORZ  2  wingdi.h

Straight Arms/Horizontal See PANOSE.


FN_PAN_STRAIGHT_ARMS_HORZ
PAN_STRAIGHT_ARMS_HORZ  2  wingdi.h


PAN_STRAIGHT_ARMS_SINGLE_SERIF
PAN_STRAIGHT_ARMS_SINGLE_SERIF  5  wingdi.h

Straight Arms/Single-Serif See PANOSE.


FN_PAN_STRAIGHT_ARMS_SINGLE_SERIF
PAN_STRAIGHT_ARMS_SINGLE_SERIF  5  wingdi.h


PAN_STRAIGHT_ARMS_VERT
PAN_STRAIGHT_ARMS_VERT  4  wingdi.h

Straight Arms/Vertical See PANOSE.


FN_PAN_STRAIGHT_ARMS_VERT
PAN_STRAIGHT_ARMS_VERT  4  wingdi.h


PAN_STRAIGHT_ARMS_WEDGE
PAN_STRAIGHT_ARMS_WEDGE  3  wingdi.h

Straight Arms/Wedge See PANOSE.


FN_PAN_STRAIGHT_ARMS_WEDGE
PAN_STRAIGHT_ARMS_WEDGE  3  wingdi.h


PAN_STROKE_GRADUAL_DIAG
PAN_STROKE_GRADUAL_DIAG  2  wingdi.h

Gradual/Diagonal See PANOSE.


FN_PAN_STROKE_GRADUAL_DIAG
PAN_STROKE_GRADUAL_DIAG  2  wingdi.h


PAN_STROKE_GRADUAL_HORZ
PAN_STROKE_GRADUAL_HORZ  5  wingdi.h

Gradual/Horizontal See PANOSE.


FN_PAN_STROKE_GRADUAL_HORZ
PAN_STROKE_GRADUAL_HORZ  5  wingdi.h


PAN_STROKE_GRADUAL_TRAN
PAN_STROKE_GRADUAL_TRAN  3  wingdi.h

Gradual/Transitional See PANOSE.


FN_PAN_STROKE_GRADUAL_TRAN
PAN_STROKE_GRADUAL_TRAN  3  wingdi.h


PAN_STROKE_GRADUAL_VERT
PAN_STROKE_GRADUAL_VERT  4  wingdi.h

Gradual/Vertical See PANOSE.


FN_PAN_STROKE_GRADUAL_VERT
PAN_STROKE_GRADUAL_VERT  4  wingdi.h


PAN_STROKE_INSTANT_VERT
PAN_STROKE_INSTANT_VERT  8  wingdi.h

Instant/Vertical See PANOSE.


FN_PAN_STROKE_INSTANT_VERT
PAN_STROKE_INSTANT_VERT  8  wingdi.h


PAN_STROKE_RAPID_HORZ
PAN_STROKE_RAPID_HORZ  7  wingdi.h

Rapid/Horizontal See PANOSE.


FN_PAN_STROKE_RAPID_HORZ
PAN_STROKE_RAPID_HORZ  7  wingdi.h


PAN_STROKE_RAPID_VERT
PAN_STROKE_RAPID_VERT  6  wingdi.h

Rapid/Vertical See PANOSE.


FN_PAN_STROKE_RAPID_VERT
PAN_STROKE_RAPID_VERT  6  wingdi.h


PAN_WEIGHT_BLACK
PAN_WEIGHT_BLACK  10  wingdi.h

Black See PANOSE.


FN_PAN_WEIGHT_BLACK
PAN_WEIGHT_BLACK  10  wingdi.h


PAN_WEIGHT_BOLD
PAN_WEIGHT_BOLD  8  wingdi.h

Bold See PANOSE.


FN_PAN_WEIGHT_BOLD
PAN_WEIGHT_BOLD  8  wingdi.h


PAN_WEIGHT_BOOK
PAN_WEIGHT_BOOK  5  wingdi.h

Book See PANOSE.


FN_PAN_WEIGHT_BOOK
PAN_WEIGHT_BOOK  5  wingdi.h


PAN_WEIGHT_DEMI
PAN_WEIGHT_DEMI  7  wingdi.h

Demi See PANOSE.


FN_PAN_WEIGHT_DEMI
PAN_WEIGHT_DEMI  7  wingdi.h


PAN_WEIGHT_HEAVY
PAN_WEIGHT_HEAVY  9  wingdi.h

Heavy See PANOSE.


FN_PAN_WEIGHT_HEAVY
PAN_WEIGHT_HEAVY  9  wingdi.h


PAN_WEIGHT_LIGHT
PAN_WEIGHT_LIGHT  3  wingdi.h

Light See PANOSE.


FN_PAN_WEIGHT_LIGHT
PAN_WEIGHT_LIGHT  3  wingdi.h


PAN_WEIGHT_MEDIUM
PAN_WEIGHT_MEDIUM  6  wingdi.h

Medium See PANOSE.


FN_PAN_WEIGHT_MEDIUM
PAN_WEIGHT_MEDIUM  6  wingdi.h


PAN_WEIGHT_NORD
PAN_WEIGHT_NORD  11  wingdi.h

Nord See PANOSE.


FN_PAN_WEIGHT_NORD
PAN_WEIGHT_NORD  11  wingdi.h


PAN_WEIGHT_THIN
PAN_WEIGHT_THIN  4  wingdi.h

Thin See PANOSE.


FN_PAN_WEIGHT_THIN
PAN_WEIGHT_THIN  4  wingdi.h


PAN_WEIGHT_VERY_LIGHT
PAN_WEIGHT_VERY_LIGHT  2  wingdi.h

Very Light See PANOSE.


FN_PAN_WEIGHT_VERY_LIGHT
PAN_WEIGHT_VERY_LIGHT  2  wingdi.h


PAN_XHEIGHT_CONSTANT_LARGE
PAN_XHEIGHT_CONSTANT_LARGE  4  wingdi.h

Constant/Large See PANOSE.


FN_PAN_XHEIGHT_CONSTANT_LARGE
PAN_XHEIGHT_CONSTANT_LARGE  4  wingdi.h


PAN_XHEIGHT_CONSTANT_SMALL
PAN_XHEIGHT_CONSTANT_SMALL  2  wingdi.h

Constant/Small See PANOSE.


FN_PAN_XHEIGHT_CONSTANT_SMALL
PAN_XHEIGHT_CONSTANT_SMALL  2  wingdi.h


PAN_XHEIGHT_CONSTANT_STD
PAN_XHEIGHT_CONSTANT_STD  3  wingdi.h

Constant/Standard See PANOSE.


FN_PAN_XHEIGHT_CONSTANT_STD
PAN_XHEIGHT_CONSTANT_STD  3  wingdi.h


PAN_XHEIGHT_DUCKING_LARGE
PAN_XHEIGHT_DUCKING_LARGE  7  wingdi.h

Ducking/Large See PANOSE.


FN_PAN_XHEIGHT_DUCKING_LARGE
PAN_XHEIGHT_DUCKING_LARGE  7  wingdi.h


PAN_XHEIGHT_DUCKING_SMALL
PAN_XHEIGHT_DUCKING_SMALL  5  wingdi.h

Ducking/Small See PANOSE.


FN_PAN_XHEIGHT_DUCKING_SMALL
PAN_XHEIGHT_DUCKING_SMALL  5  wingdi.h


PAN_XHEIGHT_DUCKING_STD
PAN_XHEIGHT_DUCKING_STD  6  wingdi.h

Ducking/Standard See PANOSE.


FN_PAN_XHEIGHT_DUCKING_STD
PAN_XHEIGHT_DUCKING_STD  6  wingdi.h


PATCOPY
PATCOPY  (DWORD)0x00F00021  wingdi.h

Copies the specified pattern into the destination bitmap. See BitBlt, PatBlt.


FN_PATCOPY
PATCOPY  (DWORD)0x00F00021  wingdi.h


PATINVERT
PATINVERT  (DWORD)0x005A0049  wingdi.h

Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean XOR operator. See BitBlt, PatBlt.


FN_PATINVERT
PATINVERT  (DWORD)0x005A0049  wingdi.h


PATPAINT
PATPAINT  (DWORD)0x00FB0A09  wingdi.h

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. See BitBlt.


FN_PATPAINT
PATPAINT  (DWORD)0x00FB0A09  wingdi.h


PC_EXPLICIT
PC_EXPLICIT  0x02  wingdi.h

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. See PALETTEENTRY.


FN_PC_EXPLICIT
PC_EXPLICIT  0x02  wingdi.h


PC_NOCOLLAPSE
PC_NOCOLLAPSE  0x04  wingdi.h

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. See PALETTEENTRY.


FN_PC_NOCOLLAPSE
PC_NOCOLLAPSE  0x04  wingdi.h


PC_RESERVED
PC_RESERVED  0x01  wingdi.h

Specifies that the logical palette entry be used for palette animation; this prevents other windows from matching colors to this palette entry since the color frequently changes. If an unused system-palette entry is available, this color is placed in that entry. Otherwise, the color is available for animation. See PALETTEENTRY.


FN_PC_RESERVED
PC_RESERVED  0x01  wingdi.h


PD_ALLPAGES
PD_ALLPAGES  0x00000000  commdlg.h

Indicates the All radio button was selected when the user closed the dialog box. (This value is used as a placeholder, to indicate the PD_PAGENUMS and PD_SELECTION flags are not set. This value can be set on input and on output.) See PRINTDLG, PrintDlg.


FN_PD_ALLPAGES
PD_ALLPAGES  0x00000000  commdlg.h


PD_COLLATE
PD_COLLATE  0x00000010  commdlg.h

Causes the Collate checkbox to be in the checked state when the dialog box is created. When the PrintDlg function returns, this flag indicates the state the Collate checkbox was left in by the user. See PRINTDLG, PrintDlg.


FN_PD_COLLATE
PD_COLLATE  0x00000010  commdlg.h


PD_DISABLEPRINTTOFILE
PD_DISABLEPRINTTOFILE  0x00080000  commdlg.h

Disables the Print to File check box. See PRINTDLG, PrintDlg.


FN_PD_DISABLEPRINTTOFILE
PD_DISABLEPRINTTOFILE  0x00080000  commdlg.h


PD_ENABLEPRINTHOOK
PD_ENABLEPRINTHOOK  0x00001000  commdlg.h

Enables the hook function specified in the lpfnPrintHook member of this structure. See PRINTDLG, PrintDlg.


FN_PD_ENABLEPRINTHOOK
PD_ENABLEPRINTHOOK  0x00001000  commdlg.h


PD_ENABLEPRINTTEMPLATE
PD_ENABLEPRINTTEMPLATE  0x00004000  commdlg.h

Causes the operating system to create the dialog box by using the dialog template identified by the hInstance and lpPrintTemplateName members. See PRINTDLG, PrintDlg.


FN_PD_ENABLEPRINTTEMPLATE
PD_ENABLEPRINTTEMPLATE  0x00004000  commdlg.h


PD_ENABLEPRINTTEMPLATEHANDLE
PD_ENABLEPRINTTEMPLATEHANDLE  0x00010000  commdlg.h

Indicates that the hInstance member identifies a data block that contains a pre-loaded dialog template. The system ignores the lpPrintTemplateName member if this flag is specified. See PRINTDLG, PrintDlg.


FN_PD_ENABLEPRINTTEMPLATEHANDLE
PD_ENABLEPRINTTEMPLATEHANDLE  0x00010000  commdlg.h


PD_ENABLESETUPHOOK
PD_ENABLESETUPHOOK  0x00002000  commdlg.h

Enables the hook function specified in the lpfnSetupHook member of this structure. See PRINTDLG, PrintDlg.


FN_PD_ENABLESETUPHOOK
PD_ENABLESETUPHOOK  0x00002000  commdlg.h


PD_ENABLESETUPTEMPLATE
PD_ENABLESETUPTEMPLATE  0x00008000  commdlg.h

Causes the operating system to create the dialog box by using the dialog template identified by the hInstance and lpSetupTemplateName members. See PRINTDLG, PrintDlg.


FN_PD_ENABLESETUPTEMPLATE
PD_ENABLESETUPTEMPLATE  0x00008000  commdlg.h


PD_ENABLESETUPTEMPLATEHANDLE
PD_ENABLESETUPTEMPLATEHANDLE  0x00020000  commdlg.h

Indicates the hInstance member identifies a data block that contains a pre-loaded dialog template. The operating system ignores the lpSetupTemplateName member if this flag is specified. See PRINTDLG, PrintDlg.


FN_PD_ENABLESETUPTEMPLATEHANDLE
PD_ENABLESETUPTEMPLATEHANDLE  0x00020000  commdlg.h


PD_HIDEPRINTTOFILE
PD_HIDEPRINTTOFILE  0x00100000  commdlg.h

Hides and disables the Print to File check box. See PRINTDLG, PrintDlg.


FN_PD_HIDEPRINTTOFILE
PD_HIDEPRINTTOFILE  0x00100000  commdlg.h


PD_NOPAGENUMS
PD_NOPAGENUMS  0x00000008  commdlg.h

Disables the Pages radio button and the associated edit control. See PRINTDLG, PrintDlg.


FN_PD_NOPAGENUMS
PD_NOPAGENUMS  0x00000008  commdlg.h


PD_NOSELECTION
PD_NOSELECTION  0x00000004  commdlg.h

Disables the Selection radio button. See PRINTDLG, PrintDlg.


FN_PD_NOSELECTION
PD_NOSELECTION  0x00000004  commdlg.h


PD_NOWARNING
PD_NOWARNING  0x00000080  commdlg.h

Prevents the warning message from being displayed when there is no default printer. See PRINTDLG, PrintDlg.


FN_PD_NOWARNING
PD_NOWARNING  0x00000080  commdlg.h


PD_PAGENUMS
PD_PAGENUMS  0x00000002  commdlg.h

Causes the Pages radio button to be in the selected state when the dialog box is created. When the PrintDlg function returns, this flag is set if the Pages radion button is in the selected state. See PRINTDLG, PrintDlg.


FN_PD_PAGENUMS
PD_PAGENUMS  0x00000002  commdlg.h


PD_PRINTSETUP
PD_PRINTSETUP  0x00000040  commdlg.h

Causes the system to display the Print Setup dialog box rather than the Print dialog box. See PRINTDLG, PrintDlg.


FN_PD_PRINTSETUP
PD_PRINTSETUP  0x00000040  commdlg.h


PD_PRINTTOFILE
PD_PRINTTOFILE  0x00000020  commdlg.h

Causes the Print to File check box to be in the checked state when the dialog box is created. When the PrintDlg function returns, the pOutput member of the DEVNAMES structure points to the "FILE:" string. See PRINTDLG, PrintDlg.


FN_PD_PRINTTOFILE
PD_PRINTTOFILE  0x00000020  commdlg.h


PD_RETURNDC
PD_RETURNDC  0x00000100  commdlg.h

Causes the PrintDlg function to return a device context matching the selections the user made in the dialog box. The device context is returned in the hDC member. See PRINTDLG, PrintDlg.


FN_PD_RETURNDC
PD_RETURNDC  0x00000100  commdlg.h


PD_RETURNDEFAULT
PD_RETURNDEFAULT  0x00000400  commdlg.h

Causes the PrintDlg function to return DEVMODE and DEVNAME structures that are initialized for the system default printer. It does this without displaying a dialog box. It is assumed that both the hDevNames and the hDevMode members are NULL; otherwise, the function returns an error. If the system default printer is supported by an old printer driver (pre-3.0), only the hDevNames member is returned--the hDevMode member is NULL. See PRINTDLG, PrintDlg.


FN_PD_RETURNDEFAULT
PD_RETURNDEFAULT  0x00000400  commdlg.h


PD_RETURNIC
PD_RETURNIC  0x00000200  commdlg.h

Similar to the PD_RETURNDC flag except this flag returns an information context rather than a device context. If neither PD_RETURNDC nor PD_RETURNIC are specified, the hDC parameter is undefined on output. See PRINTDLG, PrintDlg.


FN_PD_RETURNIC
PD_RETURNIC  0x00000200  commdlg.h


PD_SELECTION
PD_SELECTION  0x00000001  commdlg.h

Causes the Selection radio button to be in the selected state when the dialog box is created. When the PrintDlg function returns, this flag is set if the Selection radio button is in the selected state. If neither PD_PAGENUMS nor PD_SELECTION are specified, the All radio button is in the selected state. See PRINTDLG, PrintDlg.


FN_PD_SELECTION
PD_SELECTION  0x00000001  commdlg.h


PD_SHOWHELP
PD_SHOWHELP  0x00000800  commdlg.h

Causes the dialog box to show the Help push button. The hwndOwner must not be NULL if this option is specified. See PRINTDLG, PrintDlg.


FN_PD_SHOWHELP
PD_SHOWHELP  0x00000800  commdlg.h


PD_USEDEVMODECOPIES
PD_USEDEVMODECOPIES  0x00040000  commdlg.h

If a printer driver does not support multiple copies, setting this flag disables the Copies edit control; if a driver does support multiple copies, setting this flag indicates the PrintDlg function should store the requested number of copies in the dmCopies member of the DEVMODE data structure and store the value 1 in the nCopies member of the PRINTDLG data structure. If this flag is not set, the PrintDlg structure stores the value 1 in the dmCopies member of the DEVMODE structure and stores the requested number of copies in the nCopies member of the PRINTDLG data structure. See PRINTDLG, PrintDlg.


FN_PD_USEDEVMODECOPIES
PD_USEDEVMODECOPIES  0x00040000  commdlg.h


PDERR_CREATEICFAILURE
PDERR_CREATEICFAILURE  0x100A  cderr.h

Specifies the PrintDlg function failed when it attempted to create an information context. See CommDlgExtendedError.


FN_PDERR_CREATEICFAILURE
PDERR_CREATEICFAILURE  0x100A  cderr.h


PDERR_DEFAULTDIFFERENT
PDERR_DEFAULTDIFFERENT  0x100C  cderr.h

Specifies an application called the PrintDlg function with the DN_DEFAULTPRN flag set 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 happens when an application stores the DEVNAMES structure and the user changes the default printer by using Control Panel.) To use the printer described by the DEVNAMES structure, the application should clear the DN_DEFAULTPRN flag and call the PrintDlg function again. To use the default printer, the application should replace the DEVNAMES structure (and the DEVMODE structure, if one exists) with NULL; this selects the default printer automatically. See CommDlgExtendedError.


FN_PDERR_DEFAULTDIFFERENT
PDERR_DEFAULTDIFFERENT  0x100C  cderr.h


PDERR_DNDMMISMATCH
PDERR_DNDMMISMATCH  0x1009  cderr.h

Specifies the data in the DEVMODE and DEVNAMES structures describes two different printers. See CommDlgExtendedError.


FN_PDERR_DNDMMISMATCH
PDERR_DNDMMISMATCH  0x1009  cderr.h


PDERR_GETDEVMODEFAIL
PDERR_GETDEVMODEFAIL  0x1005  cderr.h

Specifies the printer driver failed to initialize a DEVMODE structure. (This error value applies only to printer drivers written for Windows versions 3.0 and later.) See CommDlgExtendedError.


FN_PDERR_GETDEVMODEFAIL
PDERR_GETDEVMODEFAIL  0x1005  cderr.h


PDERR_INITFAILURE
PDERR_INITFAILURE  0x1006  cderr.h

Indicates that the PrintDlg function failed during initialization, and that there is no more specific extended error code to describe the failure. Think of this as the generic default error code for that function. See CommDlgExtendedError.


FN_PDERR_INITFAILURE
PDERR_INITFAILURE  0x1006  cderr.h


PDERR_LOADDRVFAILURE
PDERR_LOADDRVFAILURE  0x1004  cderr.h

Specifies the PrintDlg function failed to load the device driver for the specified printer. See CommDlgExtendedError.


FN_PDERR_LOADDRVFAILURE
PDERR_LOADDRVFAILURE  0x1004  cderr.h


PDERR_NODEFAULTPRN
PDERR_NODEFAULTPRN  0x1008  cderr.h

Specifies a default printer does not exist. See CommDlgExtendedError.


FN_PDERR_NODEFAULTPRN
PDERR_NODEFAULTPRN  0x1008  cderr.h


PDERR_NODEVICES
PDERR_NODEVICES  0x1007  cderr.h

Specifies no printer drivers were found. See CommDlgExtendedError.


FN_PDERR_NODEVICES
PDERR_NODEVICES  0x1007  cderr.h


PDERR_PARSEFAILURE
PDERR_PARSEFAILURE  0x1002  cderr.h

Specifies the PrintDlg function failed to parse the strings in the [devices] section of the WIN.INI file. See CommDlgExtendedError.


FN_PDERR_PARSEFAILURE
PDERR_PARSEFAILURE  0x1002  cderr.h


PDERR_PRINTERNOTFOUND
PDERR_PRINTERNOTFOUND  0x100B  cderr.h

Specifies the [devices] section of the WIN.INI file did not contain an entry for the requested printer. See CommDlgExtendedError.


FN_PDERR_PRINTERNOTFOUND
PDERR_PRINTERNOTFOUND  0x100B  cderr.h


PDERR_RETDEFFAILURE
PDERR_RETDEFFAILURE  0x1003  cderr.h

Specifies the PD_RETURNDEFAULT flag was set in the Flags member of the PRINTDLG structure but the hDevMode or hDevNames member was nonzero. See CommDlgExtendedError.


FN_PDERR_RETDEFFAILURE
PDERR_RETDEFFAILURE  0x1003  cderr.h


PDERR_SETUPFAILURE
PDERR_SETUPFAILURE  0x1001  cderr.h

Specifies the PrintDlg function failed to load the required resources. See CommDlgExtendedError.


FN_PDERR_SETUPFAILURE
PDERR_SETUPFAILURE  0x1001  cderr.h


PDEVICESIZE
PDEVICESIZE  26  wingdi.h

Reserved. See GetDeviceCaps.


FN_PDEVICESIZE
PDEVICESIZE  26  wingdi.h


PERF_100NSEC_MULTI_TIMER
PERF_100NSEC_MULTI_TIMER  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_DELTA_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_100NS | PERF_MULTI_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h

64-bit Timer in 100 nsec units. Display delta divided by delta time. The display suffix is "%". This timer is for multiple instances, so the result can exceed 100%. See PERF_COUNTER_DEFINITION.


FN_PERF_100NSEC_MULTI_TIMER
PERF_100NSEC_MULTI_TIMER  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_DELTA_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_100NS | PERF_MULTI_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h


PERF_100NSEC_MULTI_TIMER_INV
PERF_100NSEC_MULTI_TIMER_INV  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_DELTA_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_100NS | PERF_MULTI_COUNTER | PERF_INVERSE_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h

64-bit Timer inverse. (That is, idle is measured.) Display 100 * _MULTI_BASE - delta divided by delta time. The display suffix is "%". This timer is for multiple instances, so the result can exceed 100%. Followed by a counter of type PERF_COUNTER_MULTI_BASE. See PERF_COUNTER_DEFINITION.


FN_PERF_100NSEC_MULTI_TIMER_INV
PERF_100NSEC_MULTI_TIMER_INV  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_DELTA_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_100NS | PERF_MULTI_COUNTER | PERF_INVERSE_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h


PERF_100NSEC_TIMER
PERF_100NSEC_TIMER  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_100NS | PERF_DELTA_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h

64-bit Timer in 100 nsec units. Divide delta by delta time. The display suffix is "%". See PERF_COUNTER_DEFINITION.


FN_PERF_100NSEC_TIMER
PERF_100NSEC_TIMER  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_100NS | PERF_DELTA_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h


PERF_100NSEC_TIMER_INV
PERF_100NSEC_TIMER_INV  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_100NS | PERF_DELTA_COUNTER | PERF_INVERSE_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h

64-bit Timer inverse. (That is, idle is measured.) Display 100 - delta divided by delta time. The display suffix is "%". See PERF_COUNTER_DEFINITION.


FN_PERF_100NSEC_TIMER_INV
PERF_100NSEC_TIMER_INV  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_100NS | PERF_DELTA_COUNTER | PERF_INVERSE_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h


PERF_AVERAGE_BASE
PERF_AVERAGE_BASE  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_BASE | PERF_DISPLAY_NOSHOW | 0x00000002)  winperf.h

Used as the denominator in the computation of time or count averages. Must directly follow the numerator counter. Do not display this value to the user. See PERF_COUNTER_DEFINITION.


FN_PERF_AVERAGE_BASE
PERF_AVERAGE_BASE  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_BASE | PERF_DISPLAY_NOSHOW | 0x00000002)  winperf.h


PERF_AVERAGE_BULK
PERF_AVERAGE_BULK  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_FRACTION | PERF_DISPLAY_NOSHOW)  winperf.h

A bulk count which, when divided by the number of operations, typically provides the number of bytes per operation. See PERF_COUNTER_DEFINITION.


FN_PERF_AVERAGE_BULK
PERF_AVERAGE_BULK  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_FRACTION | PERF_DISPLAY_NOSHOW)  winperf.h


PERF_AVERAGE_TIMER
PERF_AVERAGE_TIMER  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_FRACTION | PERF_DISPLAY_SECONDS)  winperf.h

A timer which, when divided by an average base, produces a time in seconds which is the average time of some operation. This timer times total operations, and the base is the number of operations. The display suffix is "sec". See PERF_COUNTER_DEFINITION.


FN_PERF_AVERAGE_TIMER
PERF_AVERAGE_TIMER  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_FRACTION | PERF_DISPLAY_SECONDS)  winperf.h


PERF_COUNTER_BULK_COUNT
PERF_COUNTER_BULK_COUNT  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_DISPLAY_PER_SEC)  winperf.h

64-bit Counter. Divide delta by delta time. The display suffix is "/sec". See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_BULK_COUNT
PERF_COUNTER_BULK_COUNT  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_DISPLAY_PER_SEC)  winperf.h


PERF_COUNTER_COUNTER
PERF_COUNTER_COUNTER  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_DISPLAY_PER_SEC)  winperf.h

32-bit counter. Divide delta by delta time. The display suffix is "/sec". See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_COUNTER
PERF_COUNTER_COUNTER  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_DISPLAY_PER_SEC)  winperf.h


PERF_COUNTER_HISTOGRAM
PERF_COUNTER_HISTOGRAM  0x00060000  winperf.h

Counter begins or ends a histogram. See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_HISTOGRAM
PERF_COUNTER_HISTOGRAM  0x00060000  winperf.h


PERF_COUNTER_MULTI_BASE
PERF_COUNTER_MULTI_BASE  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_BASE | PERF_MULTI_COUNTER | PERF_DISPLAY_NOSHOW)  winperf.h

Number of instances to which the preceeding PERF_COUNTER_MULTI_TIMER_INV counter applies. This value is used as a factor to get the percentage. See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_MULTI_BASE
PERF_COUNTER_MULTI_BASE  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_BASE | PERF_MULTI_COUNTER | PERF_DISPLAY_NOSHOW)  winperf.h


PERF_COUNTER_MULTI_TIMER
PERF_COUNTER_MULTI_TIMER  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_DELTA_COUNTER | PERF_TIMER_TICK | PERF_MULTI_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h

64-bit Timer. Divide delta by delta time. The display suffix is "%". This timer is for multiple instances, so the result can exceed 100%. See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_MULTI_TIMER
PERF_COUNTER_MULTI_TIMER  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_DELTA_COUNTER | PERF_TIMER_TICK | PERF_MULTI_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h


PERF_COUNTER_MULTI_TIMER_INV
PERF_COUNTER_MULTI_TIMER_INV  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_DELTA_COUNTER | PERF_MULTI_COUNTER | PERF_TIMER_TICK | PERF_INVERSE_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h

64-bit Timer inverse. (That is, idle is measured.) Display 100 * _MULTI_BASE - delta divided by delta time. The display suffix is "%". This timer is for multiple instances, so the result can exceed 100%. Followed by a counter of type PERF_COUNTER_MULTI_BASE. See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_MULTI_TIMER_INV
PERF_COUNTER_MULTI_TIMER_INV  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_DELTA_COUNTER | PERF_MULTI_COUNTER | PERF_TIMER_TICK | PERF_INVERSE_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h


PERF_COUNTER_NODATA
PERF_COUNTER_NODATA  (PERF_SIZE_ZERO | PERF_DISPLAY_NOSHOW)  winperf.h

A label: no data is associated with this counter (it has 0 length) Do not display. See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_NODATA
PERF_COUNTER_NODATA  (PERF_SIZE_ZERO | PERF_DISPLAY_NOSHOW)  winperf.h


PERF_COUNTER_QUEUELEN
PERF_COUNTER_QUEUELEN  0x00050000  winperf.h

Queue Length Space-Time Product. Divide delta by delta time. See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_QUEUELEN
PERF_COUNTER_QUEUELEN  0x00050000  winperf.h


PERF_COUNTER_RAWCOUNT
PERF_COUNTER_RAWCOUNT  (PERF_SIZE_DWORD | PERF_TYPE_NUMBER | PERF_NUMBER_DECIMAL | PERF_DISPLAY_NO_SUFFIX)  winperf.h

The data is a counter which should not be time averaged on display, such as an error counter on a serial line. See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_RAWCOUNT
PERF_COUNTER_RAWCOUNT  (PERF_SIZE_DWORD | PERF_TYPE_NUMBER | PERF_NUMBER_DECIMAL | PERF_DISPLAY_NO_SUFFIX)  winperf.h


PERF_COUNTER_TEXT
PERF_COUNTER_TEXT  (PERF_SIZE_VARIABLE_LEN | PERF_TYPE_TEXT | PERF_TEXT_UNICODE | PERF_DISPLAY_NO_SUFFIX)  winperf.h

The counter is Unicode text, not a counter. See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_TEXT
PERF_COUNTER_TEXT  (PERF_SIZE_VARIABLE_LEN | PERF_TYPE_TEXT | PERF_TEXT_UNICODE | PERF_DISPLAY_NO_SUFFIX)  winperf.h


PERF_COUNTER_TIMER
PERF_COUNTER_TIMER  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h

64-bit Timer. Divide delta by delta time. The display suffix is "%". See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_TIMER
PERF_COUNTER_TIMER  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h


PERF_COUNTER_TIMER_INV
PERF_COUNTER_TIMER_INV  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_INVERSE_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h

64-bit timer inverse. (That is, idle is measured.) Display 100 - delta divided by delta time. The display suffix is "%". See PERF_COUNTER_DEFINITION.


FN_PERF_COUNTER_TIMER_INV
PERF_COUNTER_TIMER_INV  (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_INVERSE_COUNTER | PERF_DISPLAY_PERCENT)  winperf.h


PERF_DETAIL_ADVANCED
PERF_DETAIL_ADVANCED  200  winperf.h

Data designed for the advanced user. See PERF_COUNTER_DEFINITION, PERF_OBJECT_TYPE.


FN_PERF_DETAIL_ADVANCED
PERF_DETAIL_ADVANCED  200  winperf.h


PERF_DETAIL_EXPERT
PERF_DETAIL_EXPERT  300  winperf.h

Data designed for the expert user. See PERF_COUNTER_DEFINITION, PERF_OBJECT_TYPE.


FN_PERF_DETAIL_EXPERT
PERF_DETAIL_EXPERT  300  winperf.h


PERF_DETAIL_NOVICE
PERF_DETAIL_NOVICE  100  winperf.h

Data can be understood by the uninformed user. See PERF_COUNTER_DEFINITION, PERF_OBJECT_TYPE.


FN_PERF_DETAIL_NOVICE
PERF_DETAIL_NOVICE  100  winperf.h


PERF_DETAIL_WIZARD
PERF_DETAIL_WIZARD  400  winperf.h

Data designed for the system designer. See PERF_COUNTER_DEFINITION, PERF_OBJECT_TYPE.


FN_PERF_DETAIL_WIZARD
PERF_DETAIL_WIZARD  400  winperf.h


PERF_RAW_BASE
PERF_RAW_BASE  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_BASE | PERF_DISPLAY_NOSHOW | 0x00000003)  winperf.h

Indicates the data is a base for the preceeding counter which should not be time averaged on display, such as free space over total space. See PERF_COUNTER_DEFINITION.


FN_PERF_RAW_BASE
PERF_RAW_BASE  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_BASE | PERF_DISPLAY_NOSHOW | 0x00000003)  winperf.h


PERF_RAW_FRACTION
PERF_RAW_FRACTION  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_FRACTION | PERF_DISPLAY_PERCENT)  winperf.h

Indicates the data is a fraction of the following counter which should not be time averaged on display, such as free space over total space. Display the quotient as "%". See PERF_COUNTER_DEFINITION.


FN_PERF_RAW_FRACTION
PERF_RAW_FRACTION  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_FRACTION | PERF_DISPLAY_PERCENT)  winperf.h


PERF_SAMPLE_BASE
PERF_SAMPLE_BASE  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_BASE | PERF_DISPLAY_NOSHOW | 0x00000001)  winperf.h

The divisor for a sample, used with the previous counter to form a sampled percentage. You must check for > 0 before dividing by this value. This counter will directly follow the numerator counter and should not be displayed. See PERF_COUNTER_DEFINITION.


FN_PERF_SAMPLE_BASE
PERF_SAMPLE_BASE  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_BASE | PERF_DISPLAY_NOSHOW | 0x00000001)  winperf.h


PERF_SAMPLE_COUNTER
PERF_SAMPLE_COUNTER  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_DISPLAY_NO_SUFFIX)  winperf.h

A count which is sampled on each sampling interrupt (queue length) Divide delta by delta time. See PERF_COUNTER_DEFINITION.


FN_PERF_SAMPLE_COUNTER
PERF_SAMPLE_COUNTER  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_RATE | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_DISPLAY_NO_SUFFIX)  winperf.h


PERF_SAMPLE_FRACTION
PERF_SAMPLE_FRACTION  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_FRACTION | PERF_DELTA_COUNTER | PERF_DELTA_BASE | PERF_DISPLAY_PERCENT)  winperf.h

A count which is either 1 or 0 on each sampling interrupt (% busy) Divide delta by delta base. The display suffix is "%". See PERF_COUNTER_DEFINITION.


FN_PERF_SAMPLE_FRACTION
PERF_SAMPLE_FRACTION  (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_FRACTION | PERF_DELTA_COUNTER | PERF_DELTA_BASE | PERF_DISPLAY_PERCENT)  winperf.h


PLANES
PLANES  14  wingdi.h

Number of color planes. See GetDeviceCaps.


FN_PLANES
PLANES  14  wingdi.h


PM_NOREMOVE
PM_NOREMOVE  0x0000  winuser.h

Indicates the message has not been removed from the queue. (An application called the PeekMessage function, specifying the PM_NOREMOVE flag.) See GetMsgProc, PeekMessage.


FN_PM_NOREMOVE
PM_NOREMOVE  0x0000  winuser.h


PM_REMOVE
PM_REMOVE  0x0001  winuser.h

Indicates the message has been removed from the queue. (An application called the GetMessage function, or it called the PeekMessage function, specifying the PM_REMOVE flag.) See GetMsgProc, PeekMessage.


FN_PM_REMOVE
PM_REMOVE  0x0001  winuser.h


POLYGONALCAPS
POLYGONALCAPS  32  wingdi.h

A bitmask that indicates the polygonal capabilities of the device. See GetDeviceCaps.


FN_POLYGONALCAPS
POLYGONALCAPS  32  wingdi.h


PRINTER_CONTROL_PAUSE
PRINTER_CONTROL_PAUSE  1  winspool.h

Pause the printer. See SetPrinter.


FN_PRINTER_CONTROL_PAUSE
PRINTER_CONTROL_PAUSE  1  winspool.h


PRINTER_CONTROL_PURGE
PRINTER_CONTROL_PURGE  3  winspool.h

Delete all the print jobs in the printer. See SetPrinter.


FN_PRINTER_CONTROL_PURGE
PRINTER_CONTROL_PURGE  3  winspool.h


PRINTER_CONTROL_RESUME
PRINTER_CONTROL_RESUME  2  winspool.h

Resume a paused printer. See SetPrinter.


FN_PRINTER_CONTROL_RESUME
PRINTER_CONTROL_RESUME  2  winspool.h


PRINTER_ENUM_LOCAL
PRINTER_ENUM_LOCAL  0x00000002  winspool.h

Enumerate locally installed printers. See EnumPrinters.


FN_PRINTER_ENUM_LOCAL
PRINTER_ENUM_LOCAL  0x00000002  winspool.h


PRINTER_ENUM_NAME
PRINTER_ENUM_NAME  0x00000008  winspool.h

Enumerate the printer identified by lpszName. This could be a server lpszName, or a domain lpszName. See EnumPrinters.


FN_PRINTER_ENUM_NAME
PRINTER_ENUM_NAME  0x00000008  winspool.h


PRINTER_ENUM_REMOTE
PRINTER_ENUM_REMOTE  0x00000010  winspool.h

Enumerated network printers. See EnumPrinters.


FN_PRINTER_ENUM_REMOTE
PRINTER_ENUM_REMOTE  0x00000010  winspool.h


PRINTER_ENUM_SHARED
PRINTER_ENUM_SHARED  0x00000020  winspool.h

Enumerate printers with the shared attribute. See EnumPrinters.


FN_PRINTER_ENUM_SHARED
PRINTER_ENUM_SHARED  0x00000020  winspool.h


PRINTER_FONTTYPE
PRINTER_FONTTYPE  0x4000  commdlg.h

Specifies that the font is a printer font. See CHOOSEFONT, ChooseFont.


FN_PRINTER_FONTTYPE
PRINTER_FONTTYPE  0x4000  commdlg.h


PRIVILEGE_SET_ALL_NECESSARY
PRIVILEGE_SET_ALL_NECESSARY  (1)  winnt.h

Indicates that all of the specified privileges must be held by the process requesting accesss. If this flag is not set, then the presence of any the privileges in the process's access token grants the access. See PRIVILEGE_SET.


FN_PRIVILEGE_SET_ALL_NECESSARY
PRIVILEGE_SET_ALL_NECESSARY  (1)  winnt.h


PROCESS_ALL_ACCESS
PROCESS_ALL_ACCESS  (STANDARD_RIGHTS_REQUIRED | SYNCHRONIZE | 0xFFF)  winnt.h

Specifies all possible access flags for the process object. See DuplicateHandle.


FN_PROCESS_ALL_ACCESS
PROCESS_ALL_ACCESS  (STANDARD_RIGHTS_REQUIRED | SYNCHRONIZE | 0xFFF)  winnt.h


PROCESS_CREATE_THREAD
PROCESS_CREATE_THREAD  (0x0002)  winnt.h

Enables using the process handle in the CreateRemoteThread function to create a thread in the process. See DuplicateHandle.


FN_PROCESS_CREATE_THREAD
PROCESS_CREATE_THREAD  (0x0002)  winnt.h


PROCESS_DUP_HANDLE
PROCESS_DUP_HANDLE  (0x0040)  winnt.h

Enables using the process handle as either the source or target process in the DuplicateHandle function to duplicate a handle. See DuplicateHandle.


FN_PROCESS_DUP_HANDLE
PROCESS_DUP_HANDLE  (0x0040)  winnt.h


PROCESS_QUERY_INFORMATION
PROCESS_QUERY_INFORMATION  (0x0400)  winnt.h

Enables using the process handle in the GetExitCodeProcess and GetPriorityClass functions to read information from the process object. See DuplicateHandle.


FN_PROCESS_QUERY_INFORMATION
PROCESS_QUERY_INFORMATION  (0x0400)  winnt.h


PROCESS_SET_INFORMATION
PROCESS_SET_INFORMATION  (0x0200)  winnt.h

Enables using the process handle in the SetPriorityClass function to set the process's priority class. See DuplicateHandle.


FN_PROCESS_SET_INFORMATION
PROCESS_SET_INFORMATION  (0x0200)  winnt.h


PROCESS_TERMINATE
PROCESS_TERMINATE  (0x0001)  winnt.h

Enables using the process handle in the TerminateProcess function to terminate the process. See DuplicateHandle.


FN_PROCESS_TERMINATE
PROCESS_TERMINATE  (0x0001)  winnt.h


PROCESS_VM_OPERATION
PROCESS_VM_OPERATION  (0x0008)  winnt.h

Enables using the process handle in the VirtualProtectEx and WriteProcessMemory functions to modify the virtual memory of the process. See DuplicateHandle.


FN_PROCESS_VM_OPERATION
PROCESS_VM_OPERATION  (0x0008)  winnt.h


PROCESS_VM_READ
PROCESS_VM_READ  (0x0010)  winnt.h

Enables using the process handle in the ReadProcessMemory function to read from the virtual memory of the process. See DuplicateHandle.


FN_PROCESS_VM_READ
PROCESS_VM_READ  (0x0010)  winnt.h


PROCESS_VM_WRITE
PROCESS_VM_WRITE  (0x0020)  winnt.h

Enables using the process handle in the WriteProcessMemory function to write to the virtual memory of the process. See DuplicateHandle.


FN_PROCESS_VM_WRITE
PROCESS_VM_WRITE  (0x0020)  winnt.h


PROOF_QUALITY
PROOF_QUALITY  2  wingdi.h

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. Bold, italic, underline, and strikeout fonts are synthesized if necessary. See CreateFont, LOGFONT.


FN_PROOF_QUALITY
PROOF_QUALITY  2  wingdi.h


PS_ALTERNATE
PS_ALTERNATE  8  wingdi.h

The pen sets every other pixel. (This style is only applicable for cosmetic pens.) See ExtCreatePen.


FN_PS_ALTERNATE
PS_ALTERNATE  8  wingdi.h


PS_COSMETIC
PS_COSMETIC  0x00000000  wingdi.h

Creates a cosmetic pen. See ExtCreatePen, EXTLOGPEN.


FN_PS_COSMETIC
PS_COSMETIC  0x00000000  wingdi.h


PS_DASH
PS_DASH  1  wingdi.h

Creates a dashed pen. Valid only when the pen width is one or less in device untis. See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.


FN_PS_DASH
PS_DASH  1  wingdi.h


PS_DASHDOT
PS_DASHDOT  3  wingdi.h

Creates a pen with alternating dashes and dots. Valid only when the pen width is one or less in device untis. See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.


FN_PS_DASHDOT
PS_DASHDOT  3  wingdi.h


PS_DASHDOTDOT
PS_DASHDOTDOT  4  wingdi.h

Creates a pen with alternating dashes and double-dots. Valid only when the pen width is one or less in device untis. See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.


FN_PS_DASHDOTDOT
PS_DASHDOTDOT  4  wingdi.h


PS_DOT
PS_DOT  2  wingdi.h

Creates a dotted pen. Valid only when the pen width is one or less in device units. See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.


FN_PS_DOT
PS_DOT  2  wingdi.h


PS_ENDCAP_FLAT
PS_ENDCAP_FLAT  0x00000200  wingdi.h

Line end caps are flat. See ExtCreatePen, EXTLOGPEN.


FN_PS_ENDCAP_FLAT
PS_ENDCAP_FLAT  0x00000200  wingdi.h


PS_ENDCAP_ROUND
PS_ENDCAP_ROUND  0x00000000  wingdi.h

Line end caps are round. See ExtCreatePen, EXTLOGPEN.


FN_PS_ENDCAP_ROUND
PS_ENDCAP_ROUND  0x00000000  wingdi.h


PS_ENDCAP_SQUARE
PS_ENDCAP_SQUARE  0x00000100  wingdi.h

Line end caps are square. See ExtCreatePen, EXTLOGPEN.


FN_PS_ENDCAP_SQUARE
PS_ENDCAP_SQUARE  0x00000100  wingdi.h


PS_GEOMETRIC
PS_GEOMETRIC  0x00010000  wingdi.h

Creates a geometric pen. See ExtCreatePen, EXTLOGPEN.


FN_PS_GEOMETRIC
PS_GEOMETRIC  0x00010000  wingdi.h


PS_INSIDEFRAME
PS_INSIDEFRAME  6  wingdi.h

Creates a solid pen. When this pen is used in any GDI drawing function that takes a bounding rectangle, the dimensions of the figure will be shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.


FN_PS_INSIDEFRAME
PS_INSIDEFRAME  6  wingdi.h


PS_JOIN_BEVEL
PS_JOIN_BEVEL  0x00001000  wingdi.h

Line joins are beveled. See ExtCreatePen, EXTLOGPEN.


FN_PS_JOIN_BEVEL
PS_JOIN_BEVEL  0x00001000  wingdi.h


PS_JOIN_MITER
PS_JOIN_MITER  0x00002000  wingdi.h

Line joins are mitered when they are within the current SetMiterLimit limit. A join is beveled when it would exceed the limit. See ExtCreatePen, EXTLOGPEN.


FN_PS_JOIN_MITER
PS_JOIN_MITER  0x00002000  wingdi.h


PS_JOIN_ROUND
PS_JOIN_ROUND  0x00000000  wingdi.h

Line joins are round. See ExtCreatePen, EXTLOGPEN.


FN_PS_JOIN_ROUND
PS_JOIN_ROUND  0x00000000  wingdi.h


PS_NULL
PS_NULL  5  wingdi.h

Creates a null pen. See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.


FN_PS_NULL
PS_NULL  5  wingdi.h


PS_SOLID
PS_SOLID  0  wingdi.h

Creates a solid pen. See CreatePen, ExtCreatePen, EXTLOGPEN, LOGPEN.


FN_PS_SOLID
PS_SOLID  0  wingdi.h


PS_USERSTYLE
PS_USERSTYLE  7  wingdi.h

A styling array supplied by the user is to be used. See ExtCreatePen, EXTLOGPEN.


FN_PS_USERSTYLE
PS_USERSTYLE  7  wingdi.h


PT_BEZIERTO
PT_BEZIERTO  0x04  wingdi.h

Specifies that the corresponding point in lpPoints is a control point or end point for a Bézier curve. PT_BEZIERTO types 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 end (if hard-coded) point. See GetPath, PolyDraw.


FN_PT_BEZIERTO
PT_BEZIERTO  0x04  wingdi.h


PT_CLOSEFIGURE
PT_CLOSEFIGURE  0x01  wingdi.h

This flag specifies that the figure is automatically closed after the PT_LINETO or PT_BEZIERTO constant for this point is done. A line is to be drawn from this point to the previous PT_MOVETO point. This flag is combined with the PT_LINETO type for a line, or with the PT_BEZIERTO type of the end point for a Bézier curve, by using the bit-wise operator OR. See GetPath, PolyDraw.


FN_PT_CLOSEFIGURE
PT_CLOSEFIGURE  0x01  wingdi.h


PT_LINETO
PT_LINETO  0x02  wingdi.h

Specifies that a line is to be drawn from the current position to this point, which then becomes the new current position. See GetPath, PolyDraw.


FN_PT_LINETO
PT_LINETO  0x02  wingdi.h


PT_MOVETO
PT_MOVETO  0x06  wingdi.h

Specifies that the corresponding point in lpPoints starts a disjoint figure. See GetPath, PolyDraw.


FN_PT_MOVETO
PT_MOVETO  0x06  wingdi.h


PWR_CRITICALRESUME
PWR_CRITICALRESUME  3  winuser.h

Indicates that the system is resuming operation after entering the suspended mode without first sending a PWR_SUSPENDREQUEST notification message to the application. An application should perform any necessary recovery actions. See WM_POWER.


FN_PWR_CRITICALRESUME
PWR_CRITICALRESUME  3  winuser.h


PWR_SUSPENDREQUEST
PWR_SUSPENDREQUEST  1  winuser.h

Indicates that the system is about to enter the suspended mode. See WM_POWER.


FN_PWR_SUSPENDREQUEST
PWR_SUSPENDREQUEST  1  winuser.h


PWR_SUSPENDRESUME
PWR_SUSPENDRESUME  2  winuser.h

Indicates that the system is resuming operation after having entered the 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. See WM_POWER.


FN_PWR_SUSPENDRESUME
PWR_SUSPENDRESUME  2  winuser.h


QS_ALLINPUT

Any message, including sent messages, is in the queue. This is equivalent to the combination QS_ALLEVENTS | QS_SENDMESSAGE. See GetQueueStatus.


QS_ALLEVENTS
QS_ALLEVENTS  (QS_INPUT | QS_POSTMESSAGE | QS_TIMER | QS_PAINT | QS_HOTKEY)  winuser.h

Any message, other than a sent message, is in the queue. This is equivalent to the combination QS_INPUT | QS_HOTKEY | QS_PAINT | QS_TIMER | QS_POSTMESSAGE. See GetQueueStatus.


FN_QS_ALLEVENTS
QS_ALLEVENTS  (QS_INPUT | QS_POSTMESSAGE | QS_TIMER | QS_PAINT | QS_HOTKEY)  winuser.h


QS_HOTKEY
QS_HOTKEY  0x80  winuser.h

A WM_HOTKEY message is in the queue. See GetQueueStatus.


FN_QS_HOTKEY
QS_HOTKEY  0x80  winuser.h


QS_INPUT
QS_INPUT  (QS_MOUSE | QS_KEY)  winuser.h

An input message is in the queue. This is equivalent to the combination QS_KEY | QS_MOUSE. See GetQueueStatus.


FN_QS_INPUT
QS_INPUT  (QS_MOUSE | QS_KEY)  winuser.h


QS_KEY
QS_KEY  0x01  winuser.h

A WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, or WM_SYSKEYDOWN message is in the queue. See GetQueueStatus.


FN_QS_KEY
QS_KEY  0x01  winuser.h


QS_MOUSE
QS_MOUSE  (QS_MOUSEMOVE | QS_MOUSEBUTTON)  winuser.h

A WM_MOUSEMOVE or WM_*BUTTON* message is in the queue. This is equivalent to the combination QS_MOUSEBUTTON | QS_MOUSEMOVE. See GetQueueStatus.


FN_QS_MOUSE
QS_MOUSE  (QS_MOUSEMOVE | QS_MOUSEBUTTON)  winuser.h


QS_MOUSEBUTTON
QS_MOUSEBUTTON  0x04  winuser.h

A WM_*BUTTON* message is in the queue. See GetQueueStatus.


FN_QS_MOUSEBUTTON
QS_MOUSEBUTTON  0x04  winuser.h


QS_MOUSEMOVE
QS_MOUSEMOVE  0x02  winuser.h

A WM_MOUSEMOVE message is in the queue. See GetQueueStatus.


FN_QS_MOUSEMOVE
QS_MOUSEMOVE  0x02  winuser.h


QS_PAINT
QS_PAINT  0x20  winuser.h

A WM_PAINT message is in the queue. See GetQueueStatus.


FN_QS_PAINT
QS_PAINT  0x20  winuser.h


QS_POSTMESSAGE
QS_POSTMESSAGE  0x08  winuser.h

A posted message (other than those covered by QS_HOTKEY, QS_PAINT, QS_TIMER, QS_MOUSEBUTTON, QS_MOUSEMOVE, and QS_KEY) is in the queue. See GetQueueStatus.


FN_QS_POSTMESSAGE
QS_POSTMESSAGE  0x08  winuser.h


QS_SENDMESSAGE
QS_SENDMESSAGE  0x40  winuser.h

A message sent by another thread or process is in the queue. See GetQueueStatus.


FN_QS_SENDMESSAGE
QS_SENDMESSAGE  0x40  winuser.h


QS_TIMER
QS_TIMER  0x10  winuser.h

A WM_TIMER message is in the queue. See GetQueueStatus.


FN_QS_TIMER
QS_TIMER  0x10  winuser.h


R2_BLACK
R2_BLACK  1  wingdi.h

Pixel is always binary 0. See SetROP2.


FN_R2_BLACK
R2_BLACK  1  wingdi.h


R2_COPYPEN
R2_COPYPEN  13  wingdi.h

Pixel is the pen color. See SetROP2.


FN_R2_COPYPEN
R2_COPYPEN  13  wingdi.h


R2_MASKNOTPEN
R2_MASKNOTPEN  3  wingdi.h

Pixel is a combination of the colors common to both the display and the inverse of the pen. See SetROP2.


FN_R2_MASKNOTPEN
R2_MASKNOTPEN  3  wingdi.h


R2_MASKPEN
R2_MASKPEN  9  wingdi.h

Pixel is a combination of the colors common to both the pen and the display. See SetROP2.


FN_R2_MASKPEN
R2_MASKPEN  9  wingdi.h


R2_MASKPENNOT
R2_MASKPENNOT  5  wingdi.h

Pixel is a combination of the colors common to both the pen and the inverse of the display. See SetROP2.


FN_R2_MASKPENNOT
R2_MASKPENNOT  5  wingdi.h


R2_MERGENOTPEN
R2_MERGENOTPEN  12  wingdi.h

Pixel is a combination of the display color and the inverse of the pen color. See SetROP2.


FN_R2_MERGENOTPEN
R2_MERGENOTPEN  12  wingdi.h


R2_MERGEPEN
R2_MERGEPEN  15  wingdi.h

Pixel is a combination of the pen color and the display color. See SetROP2.


FN_R2_MERGEPEN
R2_MERGEPEN  15  wingdi.h


R2_MERGEPENNOT
R2_MERGEPENNOT  14  wingdi.h

Pixel is a combination of the pen color and the inverse of the display color. See SetROP2.


FN_R2_MERGEPENNOT
R2_MERGEPENNOT  14  wingdi.h


R2_NOP
R2_NOP  11  wingdi.h

Pixel remains unchanged. See SetROP2.


FN_R2_NOP
R2_NOP  11  wingdi.h


R2_NOT
R2_NOT  6  wingdi.h

Pixel is the inverse of the display color. See SetROP2.


FN_R2_NOT
R2_NOT  6  wingdi.h


R2_NOTCOPYPEN
R2_NOTCOPYPEN  4  wingdi.h

Pixel is the inverse of the pen color. See SetROP2.


FN_R2_NOTCOPYPEN
R2_NOTCOPYPEN  4  wingdi.h


R2_NOTMASKPEN
R2_NOTMASKPEN  8  wingdi.h

Pixel is the inverse of the R2_MASKPEN color. See SetROP2.


FN_R2_NOTMASKPEN
R2_NOTMASKPEN  8  wingdi.h


R2_NOTMERGEPEN
R2_NOTMERGEPEN  2  wingdi.h

Pixel is the inverse of the R2_MERGEPEN color. See SetROP2.


FN_R2_NOTMERGEPEN
R2_NOTMERGEPEN  2  wingdi.h


R2_NOTXORPEN
R2_NOTXORPEN  10  wingdi.h

Pixel is the inverse of the R2_XORPEN color. See SetROP2.


FN_R2_NOTXORPEN
R2_NOTXORPEN  10  wingdi.h


R2_WHITE
R2_WHITE  16  wingdi.h

Pixel is always binary 1. See SetROP2.


FN_R2_WHITE
R2_WHITE  16  wingdi.h


R2_XORPEN
R2_XORPEN  7  wingdi.h

Pixel is a combination of the colors in the pen and in the display, but not in both. See SetROP2.


FN_R2_XORPEN
R2_XORPEN  7  wingdi.h


RASTERCAPS
RASTERCAPS  38  wingdi.h

Value that indicates the raster capabilities of the device, as shown in the following list: See GetDeviceCaps.


FN_RASTERCAPS
RASTERCAPS  38  wingdi.h


RC_BANDING
RC_BANDING  2  wingdi.h

Requires banding support. See GetDeviceCaps.


FN_RC_BANDING
RC_BANDING  2  wingdi.h


RC_BITBLT
RC_BITBLT  1  wingdi.h

Capable of transferring bitmaps. See GetDeviceCaps.


FN_RC_BITBLT
RC_BITBLT  1  wingdi.h


RC_BITMAP64
RC_BITMAP64  8  wingdi.h

Capable of supporting bitmaps larger than 64K. See GetDeviceCaps.


FN_RC_BITMAP64
RC_BITMAP64  8  wingdi.h


RC_DI_BITMAP
RC_DI_BITMAP  0x0080  wingdi.h

Capable of supporting the SetDIBits and GetDIBits functions. See GetDeviceCaps.


FN_RC_DI_BITMAP
RC_DI_BITMAP  0x0080  wingdi.h


RC_DIBTODEV
RC_DIBTODEV  0x0200  wingdi.h

Capable of supporting the SetDIBitsToDevice function. See GetDeviceCaps.


FN_RC_DIBTODEV
RC_DIBTODEV  0x0200  wingdi.h


RC_FLOODFILL
RC_FLOODFILL  0x1000  wingdi.h

Capable of performing flood fills. See GetDeviceCaps.


FN_RC_FLOODFILL
RC_FLOODFILL  0x1000  wingdi.h


RC_GDI20_OUTPUT
RC_GDI20_OUTPUT  0x0010  wingdi.h

Capable of supporting features of Windows 2.0. See GetDeviceCaps.


FN_RC_GDI20_OUTPUT
RC_GDI20_OUTPUT  0x0010  wingdi.h


RC_PALETTE
RC_PALETTE  0x0100  wingdi.h

Specifies palette-based device. See GetDeviceCaps.


FN_RC_PALETTE
RC_PALETTE  0x0100  wingdi.h


RC_SCALING
RC_SCALING  4  wingdi.h

Capable of scaling. See GetDeviceCaps.


FN_RC_SCALING
RC_SCALING  4  wingdi.h


RC_STRETCHBLT
RC_STRETCHBLT  0x0800  wingdi.h

Capable of performing the StretchBlt function. See GetDeviceCaps.


FN_RC_STRETCHBLT
RC_STRETCHBLT  0x0800  wingdi.h


RC_STRETCHDIB
RC_STRETCHDIB  0x2000  wingdi.h

Capable of performing the StretchDIBits function. See GetDeviceCaps.


FN_RC_STRETCHDIB
RC_STRETCHDIB  0x2000  wingdi.h


RDW_ALLCHILDREN
RDW_ALLCHILDREN  0x0080  winuser.h

Includes child windows, if any, in the repainting operation. See RedrawWindow.


FN_RDW_ALLCHILDREN
RDW_ALLCHILDREN  0x0080  winuser.h


RDW_ERASE
RDW_ERASE  0x0004  winuser.h

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. See RedrawWindow.


FN_RDW_ERASE
RDW_ERASE  0x0004  winuser.h


RDW_ERASENOW
RDW_ERASENOW  0x0200  winuser.h

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. See RedrawWindow.


FN_RDW_ERASENOW
RDW_ERASENOW  0x0200  winuser.h


RDW_FRAME
RDW_FRAME  0x0400  winuser.h

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 the RedrawWindow function unless either RDW_UPDATENOW or RDW_ERASENOW is specified. See RedrawWindow.


FN_RDW_FRAME
RDW_FRAME  0x0400  winuser.h


RDW_INTERNALPAINT
RDW_INTERNALPAINT  0x0002  winuser.h

Causes a WM_PAINT message to be posted to the window regardless of whether any portion of the window is invalid. See RedrawWindow.


FN_RDW_INTERNALPAINT
RDW_INTERNALPAINT  0x0002  winuser.h


RDW_INVALIDATE
RDW_INVALIDATE  0x0001  winuser.h

Invalidate lprcUpdate or hrgnUpdate (only one may be non-NULL). If both are NULL, the entire window is invalidated. See RedrawWindow.


FN_RDW_INVALIDATE
RDW_INVALIDATE  0x0001  winuser.h


RDW_NOCHILDREN
RDW_NOCHILDREN  0x0040  winuser.h

Excludes child windows, if any, from the repainting operation. See RedrawWindow.


FN_RDW_NOCHILDREN
RDW_NOCHILDREN  0x0040  winuser.h


RDW_NOERASE
RDW_NOERASE  0x0020  winuser.h

Suppresses any pending WM_ERASEBKGND messages. See RedrawWindow.


FN_RDW_NOERASE
RDW_NOERASE  0x0020  winuser.h


RDW_NOFRAME
RDW_NOFRAME  0x0800  winuser.h

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 from painting properly. See RedrawWindow.


FN_RDW_NOFRAME
RDW_NOFRAME  0x0800  winuser.h


RDW_NOINTERNALPAINT
RDW_NOINTERNALPAINT  0x0010  winuser.h

Suppresses any pending internal WM_PAINT messages. This flag does not affect WM_PAINT messages resulting from a non-NULL update area. See RedrawWindow.


FN_RDW_NOINTERNALPAINT
RDW_NOINTERNALPAINT  0x0010  winuser.h


RDW_UPDATENOW
RDW_UPDATENOW  0x0100  winuser.h

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. See RedrawWindow.


FN_RDW_UPDATENOW
RDW_UPDATENOW  0x0100  winuser.h


RDW_VALIDATE
RDW_VALIDATE  0x0008  winuser.h

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. See RedrawWindow.


FN_RDW_VALIDATE
RDW_VALIDATE  0x0008  winuser.h


REG_BINARY
REG_BINARY  ( 3 )  winnt.h

Binary data in any form. See RegSetValueEx.


FN_REG_BINARY
REG_BINARY  ( 3 )  winnt.h


REG_CREATED_NEW_KEY
REG_CREATED_NEW_KEY  (0x00000001L)  winnt.h

The key did not exist and was created. See RegCreateKeyEx.


FN_REG_CREATED_NEW_KEY
REG_CREATED_NEW_KEY  (0x00000001L)  winnt.h


REG_DWORD
REG_DWORD  ( 4 )  winnt.h

A 32-bit number. See RegSetValueEx.


FN_REG_DWORD
REG_DWORD  ( 4 )  winnt.h


REG_DWORD_BIG_ENDIAN
REG_DWORD_BIG_ENDIAN  ( 5 )  winnt.h

A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low word. See RegSetValueEx.


FN_REG_DWORD_BIG_ENDIAN
REG_DWORD_BIG_ENDIAN  ( 5 )  winnt.h


REG_DWORD_LITTLE_ENDIAN
REG_DWORD_LITTLE_ENDIAN  ( 4 )  winnt.h

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 word. This is the standard format for Intel and Motorola microprocessors. See RegSetValueEx.


FN_REG_DWORD_LITTLE_ENDIAN
REG_DWORD_LITTLE_ENDIAN  ( 4 )  winnt.h


REG_EXPAND_SZ
REG_EXPAND_SZ  ( 2 )  winnt.h

A null-terminated Unicode string that contains unexpanded references to environment variables (for example, "%PATH%"). See RegSetValueEx.


FN_REG_EXPAND_SZ
REG_EXPAND_SZ  ( 2 )  winnt.h


REG_LINK
REG_LINK  ( 6 )  winnt.h

A Unicode symbolic link. See RegSetValueEx.


FN_REG_LINK
REG_LINK  ( 6 )  winnt.h


REG_MULTI_SZ
REG_MULTI_SZ  ( 7 )  winnt.h

An array of null-terminated strings, terminated by two null characters. See RegSetValueEx.


FN_REG_MULTI_SZ
REG_MULTI_SZ  ( 7 )  winnt.h


REG_NONE
REG_NONE  ( 0 )  winnt.h

No defined value type. See RegSetValueEx.


FN_REG_NONE
REG_NONE  ( 0 )  winnt.h


REG_NOTIFY_CHANGE_ATTRIBUTES
REG_NOTIFY_CHANGE_ATTRIBUTES  (0x00000002L)  winnt.h

Any attribute changes that occur in a key or subtree being watched cause a change notification. See RegNotifyChangeKeyValue.


FN_REG_NOTIFY_CHANGE_ATTRIBUTES
REG_NOTIFY_CHANGE_ATTRIBUTES  (0x00000002L)  winnt.h


REG_NOTIFY_CHANGE_LAST_SET
REG_NOTIFY_CHANGE_LAST_SET  (0x00000004L)  winnt.h

Any changes to the last write time that occur in a key or subtree being watched cause a change notification. See RegNotifyChangeKeyValue.


FN_REG_NOTIFY_CHANGE_LAST_SET
REG_NOTIFY_CHANGE_LAST_SET  (0x00000004L)  winnt.h


REG_NOTIFY_CHANGE_NAME
REG_NOTIFY_CHANGE_NAME  (0x00000001L)  winnt.h

Any changes to key names that occur in a key or subtree being watched cause a change-notification wait. This includes key creations and deletions. See RegNotifyChangeKeyValue.


FN_REG_NOTIFY_CHANGE_NAME
REG_NOTIFY_CHANGE_NAME  (0x00000001L)  winnt.h


REG_NOTIFY_CHANGE_SECURITY
REG_NOTIFY_CHANGE_SECURITY  (0x00000008L)  winnt.h

Any security-descriptor changes that occur in a key or subtree being watched cause a change notification. See RegNotifyChangeKeyValue.


FN_REG_NOTIFY_CHANGE_SECURITY
REG_NOTIFY_CHANGE_SECURITY  (0x00000008L)  winnt.h


REG_OPENED_EXISTING_KEY
REG_OPENED_EXISTING_KEY  (0x00000002L)  winnt.h

The key existed, and was simply opened without being changed. See RegCreateKeyEx.


FN_REG_OPENED_EXISTING_KEY
REG_OPENED_EXISTING_KEY  (0x00000002L)  winnt.h


REG_OPTION_NON_VOLATILE
REG_OPTION_NON_VOLATILE  (0x00000000L)  winnt.h

This key is not volatile. The information is stored in a file and is preserved when the system is restarted. See RegCreateKeyEx.


FN_REG_OPTION_NON_VOLATILE
REG_OPTION_NON_VOLATILE  (0x00000000L)  winnt.h


REG_OPTION_VOLATILE
REG_OPTION_VOLATILE  (0x00000001L)  winnt.h

This key is volatile. The information is stored in memory and is not preserved when the system is restarted. See RegCreateKeyEx.


FN_REG_OPTION_VOLATILE
REG_OPTION_VOLATILE  (0x00000001L)  winnt.h


REG_RESOURCE_LIST
REG_RESOURCE_LIST  ( 8 )  winnt.h

A device-driver resource list. See RegSetValueEx.


FN_REG_RESOURCE_LIST
REG_RESOURCE_LIST  ( 8 )  winnt.h


REG_SZ
REG_SZ  ( 1 )  winnt.h

A null-terminated string. It will be a UNICODE or ANSI string depending on whether you use the UNICODE or ANSI functions. For example, if you call RegEnumValueW, you get back a UNICODE string, and if you call RegEnumValueA, you get back an ANSI string. See RegSetValueEx.


FN_REG_SZ
REG_SZ  ( 1 )  winnt.h


REG_WHOLE_HIVE_VOLATILE
REG_WHOLE_HIVE_VOLATILE  (0x00000001L)  winnt.h

Instead of restoring the specified 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. HKEY_LOCAL_MACHINE\Hardware, for example, is a volatile hive.) If this flag is specified, the key identified by the hkey parameter must be either HKEY_USERS or HKEY_LOCAL_MACHINE. See RegRestoreKey.


FN_REG_WHOLE_HIVE_VOLATILE
REG_WHOLE_HIVE_VOLATILE  (0x00000001L)  winnt.h


REGISTERED
REGISTERED  0x04  nb30.h

The name specified by the name member has been successfully added to the network. See NAME_BUFFER.


FN_REGISTERED
REGISTERED  0x04  nb30.h


REGISTERING
REGISTERING  0x00  nb30.h

The name specified by the name member is being added to the network. See NAME_BUFFER.


FN_REGISTERING
REGISTERING  0x00  nb30.h


RESOURCE_CONNECTED
RESOURCE_CONNECTED  0x00000001  winnetwk.h

All currently connected resources (fdwUsage is ignored). See WNetOpenEnum, NETRESOURCE.


FN_RESOURCE_CONNECTED
RESOURCE_CONNECTED  0x00000001  winnetwk.h


RESOURCE_GLOBALNET
RESOURCE_GLOBALNET  0x00000002  winnetwk.h

All resources on the network. See WNetOpenEnum, NETRESOURCE.


FN_RESOURCE_GLOBALNET
RESOURCE_GLOBALNET  0x00000002  winnetwk.h


RESOURCE_REMEMBERED
RESOURCE_REMEMBERED  0x00000003  winnetwk.h

All remembered connections (fdwUsage is ignored). See WNetOpenEnum, NETRESOURCE.


FN_RESOURCE_REMEMBERED
RESOURCE_REMEMBERED  0x00000003  winnetwk.h


RESOURCEDISPLAYTYPE_DOMAIN
RESOURCEDISPLAYTYPE_DOMAIN  0x00000001  winnetwk.h

The object should be displayed as a domain. See NETRESOURCE.


FN_RESOURCEDISPLAYTYPE_DOMAIN
RESOURCEDISPLAYTYPE_DOMAIN  0x00000001  winnetwk.h


RESOURCEDISPLAYTYPE_GENERIC
RESOURCEDISPLAYTYPE_GENERIC  0x00000000  winnetwk.h

The method used to display the object does not matter. See NETRESOURCE.


FN_RESOURCEDISPLAYTYPE_GENERIC
RESOURCEDISPLAYTYPE_GENERIC  0x00000000  winnetwk.h


RESOURCEDISPLAYTYPE_SERVER
RESOURCEDISPLAYTYPE_SERVER  0x00000002  winnetwk.h

The object should be displayed as a server. See NETRESOURCE.


FN_RESOURCEDISPLAYTYPE_SERVER
RESOURCEDISPLAYTYPE_SERVER  0x00000002  winnetwk.h


RESOURCEDISPLAYTYPE_SHARE
RESOURCEDISPLAYTYPE_SHARE  0x00000003  winnetwk.h

The object should be displayed as a sharepoint. See NETRESOURCE.


FN_RESOURCEDISPLAYTYPE_SHARE
RESOURCEDISPLAYTYPE_SHARE  0x00000003  winnetwk.h


RESOURCETYPE_ANY
RESOURCETYPE_ANY  0x00000000  winnetwk.h

All resources. (This value cannot be combined with RESOURCETYPE_DISK or RESOURCETYPE_PRINT.) See WNetOpenEnum.


FN_RESOURCETYPE_ANY
RESOURCETYPE_ANY  0x00000000  winnetwk.h


RESOURCETYPE_ANY
RESOURCETYPE_ANY  0x00000000  winnetwk.h

All resources See NETRESOURCE.


FN_RESOURCETYPE_ANY
RESOURCETYPE_ANY  0x00000000  winnetwk.h


RESOURCETYPE_DISK

All disk resources. See WNetOpenEnum.


RESOURCETYPE_DISK

Connect to disk resources. See WNetConnectionDialog.


RESOURCETYPE_DISK

Disk resources See NETRESOURCE.


RESOURCETYPE_PRINT

All print resources. See WNetOpenEnum.


RESOURCETYPE_PRINT

Connect to print resources. See WNetConnectionDialog.


RESOURCETYPE_PRINT

Print resources See NETRESOURCE.


RESOURCEUSAGE_CONNECTABLE

This is a connectable resource; lpRemoteName can be passed to the WNetAddConnection function to make a network connection. See NETRESOURCE.


RESOURCEUSAGE_CONNECTABLE

All connectable resources. See WNetOpenEnum.


RESOURCEUSAGE_CONTAINER

This is a container resource; lpRemoteName can be passed to the WNetOpenEnum function to enumerate the resources in the container. See NETRESOURCE.


RESOURCEUSAGE_CONTAINER

All container resources. See WNetOpenEnum.


RGN_AND
RGN_AND  1  wingdi.h

Creates the intersection of the two combined regions. See CombineRgn, ExtSelectClipRgn, SelectClipPath.


FN_RGN_AND
RGN_AND  1  wingdi.h


RGN_COPY
RGN_COPY  5  wingdi.h

Creates a copy of the region. See CombineRgn, ExtSelectClipRgn, SelectClipPath.


FN_RGN_COPY
RGN_COPY  5  wingdi.h


RGN_DIFF
RGN_DIFF  4  wingdi.h

The new clipping region includes the areas of the current clipping region with those of the current path excluded. See CombineRgn, ExtSelectClipRgn, SelectClipPath.


FN_RGN_DIFF
RGN_DIFF  4  wingdi.h


RGN_OR
RGN_OR  2  wingdi.h

Creates the union of the two combined regions. See CombineRgn, ExtSelectClipRgn, SelectClipPath.


FN_RGN_OR
RGN_OR  2  wingdi.h


RGN_XOR
RGN_XOR  3  wingdi.h

Creates the union of the two combined regions except for the overlapping areas. See CombineRgn, ExtSelectClipRgn, SelectClipPath.


FN_RGN_XOR
RGN_XOR  3  wingdi.h


RIGHT_ALT_PRESSED
RIGHT_ALT_PRESSED  0x0001  wincon.h

The right-hand ALT key is pressed. See KEY_EVENT_RECORD.


FN_RIGHT_ALT_PRESSED
RIGHT_ALT_PRESSED  0x0001  wincon.h


RIGHT_CTRL_PRESSED
RIGHT_CTRL_PRESSED  0x0004  wincon.h

The right-hand CTRL key is pressed. See KEY_EVENT_RECORD.


FN_RIGHT_CTRL_PRESSED
RIGHT_CTRL_PRESSED  0x0004  wincon.h


RT_ACCELERATOR
RT_ACCELERATOR  MAKEINTRESOURCE(9)  winuser.h

Accelerator table See EnumResourceLanguages.


FN_RT_ACCELERATOR
RT_ACCELERATOR  MAKEINTRESOURCE(9)  winuser.h


RT_BITMAP
RT_BITMAP  MAKEINTRESOURCE(2)  winuser.h

Bitmap resource See EnumResourceLanguages.


FN_RT_BITMAP
RT_BITMAP  MAKEINTRESOURCE(2)  winuser.h


RT_CURSOR
RT_CURSOR  MAKEINTRESOURCE(1)  winuser.h

Hardware-dependent cursor resource See EnumResourceLanguages.


FN_RT_CURSOR
RT_CURSOR  MAKEINTRESOURCE(1)  winuser.h


RT_DIALOG
RT_DIALOG  MAKEINTRESOURCE(5)  winuser.h

Dialog box See EnumResourceLanguages.


FN_RT_DIALOG
RT_DIALOG  MAKEINTRESOURCE(5)  winuser.h


RT_FONT
RT_FONT  MAKEINTRESOURCE(8)  winuser.h

Font resource See EnumResourceLanguages.


FN_RT_FONT
RT_FONT  MAKEINTRESOURCE(8)  winuser.h


RT_FONTDIR
RT_FONTDIR  MAKEINTRESOURCE(7)  winuser.h

Font directory resource See EnumResourceLanguages.


FN_RT_FONTDIR
RT_FONTDIR  MAKEINTRESOURCE(7)  winuser.h


RT_GROUP_CURSOR
RT_GROUP_CURSOR  MAKEINTRESOURCE((DWORD)RT_CURSOR + DIFFERENCE)   winuser.h

Hardware-independent cursor resource See EnumResourceLanguages.


FN_RT_GROUP_CURSOR
RT_GROUP_CURSOR  MAKEINTRESOURCE((DWORD)RT_CURSOR + DIFFERENCE)   winuser.h


RT_GROUP_ICON
RT_GROUP_ICON  MAKEINTRESOURCE((DWORD)RT_ICON + DIFFERENCE) winuser.h

Hardware-independent icon resource See EnumResourceLanguages.


FN_RT_GROUP_ICON
RT_GROUP_ICON  MAKEINTRESOURCE((DWORD)RT_ICON + DIFFERENCE) winuser.h


RT_ICON
RT_ICON  MAKEINTRESOURCE(3)  winuser.h

Hardware-dependent icon resource See EnumResourceLanguages.


FN_RT_ICON
RT_ICON  MAKEINTRESOURCE(3)  winuser.h


RT_MENU
RT_MENU  MAKEINTRESOURCE(4)  winuser.h

Menu resource See EnumResourceLanguages.


FN_RT_MENU
RT_MENU  MAKEINTRESOURCE(4)  winuser.h


RT_MESSAGETABLE
RT_MESSAGETABLE  MAKEINTRESOURCE(11)  winuser.h

Message-table entry See EnumResourceLanguages.


FN_RT_MESSAGETABLE
RT_MESSAGETABLE  MAKEINTRESOURCE(11)  winuser.h


RT_RCDATA
RT_RCDATA  MAKEINTRESOURCE(10)  winuser.h

User-defined resource (raw data) See EnumResourceLanguages.


FN_RT_RCDATA
RT_RCDATA  MAKEINTRESOURCE(10)  winuser.h


RT_STRING
RT_STRING  MAKEINTRESOURCE(6)  winuser.h

String-table entry See EnumResourceLanguages.


FN_RT_STRING
RT_STRING  MAKEINTRESOURCE(6)  winuser.h


RT_VERSION
RT_VERSION  MAKEINTRESOURCE(16)  winuser.h

Version resource See EnumResourceLanguages.


FN_RT_VERSION
RT_VERSION  MAKEINTRESOURCE(16)  winuser.h


RTS_CONTROL_DISABLE
RTS_CONTROL_DISABLE  0x00  winbase.h

Disable the RTS line on device open and leave it disabled. See DCB.


FN_RTS_CONTROL_DISABLE
RTS_CONTROL_DISABLE  0x00  winbase.h


RTS_CONTROL_ENABLE
RTS_CONTROL_ENABLE  0x01  winbase.h

Enable the RTS line on device open and leave it on. See DCB.


FN_RTS_CONTROL_ENABLE
RTS_CONTROL_ENABLE  0x01  winbase.h


RTS_CONTROL_HANDSHAKE
RTS_CONTROL_HANDSHAKE  0x02  winbase.h

Enable RTS handshaking. The driver raises the RTS line when the "typeahead" buffer is less than half full and lowers the RTS line when the buffer is more than three-quarters full. Note that if handshaking is enabled, it is an error for the application to adjust the line using the EscapeCommFunction function. See DCB.


FN_RTS_CONTROL_HANDSHAKE
RTS_CONTROL_HANDSHAKE  0x02  winbase.h


RTS_CONTROL_TOGGLE
RTS_CONTROL_TOGGLE  0x03  winbase.h

Specifies that the RTS line will be high if bytes are available for transmission. After all bytes in queued I/O have been sent, the RTS line will be low. See DCB.


FN_RTS_CONTROL_TOGGLE
RTS_CONTROL_TOGGLE  0x03  winbase.h


SACL_SECURITY_INFORMATION
SACL_SECURITY_INFORMATION  (0X00000008L)  winnt.h

When set, this bit indicates the system access-control list of the object is being referenced. See SECURITY_INFORMATION.


FN_SACL_SECURITY_INFORMATION
SACL_SECURITY_INFORMATION  (0X00000008L)  winnt.h


SB_BOTH
SB_BOTH  3  winuser.h

Enables or disables the arrows on the horizontal and vertical scroll bars associated with the given window. The hwnd parameter must be the handle of the window. SB_BOTH Shows or hides a window's standard horizontal and vertical scroll bars. See EnableScrollBar, ShowScrollBar.


FN_SB_BOTH
SB_BOTH  3  winuser.h


SB_BOTTOM
SB_BOTTOM  7  winuser.h

Scroll to lower right. See WM_HSCROLL.


FN_SB_BOTTOM
SB_BOTTOM  7  winuser.h


SB_CTL
SB_CTL  2  winuser.h

For a number of functions, indicates that an hwnd parameter is the handle of a scroll bar control. See EnableScrollBar, GetScrollPos, GetScrollRange, SetScrollPos, SetScrollRange, ShowScrollBar.


FN_SB_CTL
SB_CTL  2  winuser.h


SB_ENDSCROLL
SB_ENDSCROLL  8  winuser.h

End scroll. See WM_HSCROLL.


FN_SB_ENDSCROLL
SB_ENDSCROLL  8  winuser.h


SB_HORZ
SB_HORZ  0  winuser.h

Enables or disables the arrows on the horizontal scroll bar associated with the given window. The hwnd parameter must be the handle of the window. See EnableScrollBar, GetScrollPos, GetScrollRange, SetScrollPos, SetScrollRange, ShowScrollBar.


FN_SB_HORZ
SB_HORZ  0  winuser.h


SB_LINEDOWN
SB_LINEDOWN  1  winuser.h

Scroll down one line. See EM_SCROLL, WM_HSCROLL.


FN_SB_LINEDOWN
SB_LINEDOWN  1  winuser.h


SB_LINEUP
SB_LINEUP  0  winuser.h

Scroll up one line. See EM_SCROLL, WM_HSCROLL.


FN_SB_LINEUP
SB_LINEUP  0  winuser.h


SB_PAGEDOWN
SB_PAGEDOWN  3  winuser.h

Scroll down one page. See EM_SCROLL, WM_HSCROLL.


FN_SB_PAGEDOWN
SB_PAGEDOWN  3  winuser.h


SB_PAGEUP
SB_PAGEUP  2  winuser.h

Scroll up one page. See EM_SCROLL, WM_HSCROLL.


FN_SB_PAGEUP
SB_PAGEUP  2  winuser.h


SB_THUMBPOSITION
SB_THUMBPOSITION  4  winuser.h

Scroll to absolute position. The current position is specified by the nPos parameter. See WM_HSCROLL.


FN_SB_THUMBPOSITION
SB_THUMBPOSITION  4  winuser.h


SB_THUMBTRACK
SB_THUMBTRACK  5  winuser.h

Drag scroll box (thumb) to specified position. The current position is specified by the nPos parameter. See WM_HSCROLL.


FN_SB_THUMBTRACK
SB_THUMBTRACK  5  winuser.h


SB_TOP
SB_TOP  6  winuser.h

Scroll to upper left. See WM_HSCROLL.


FN_SB_TOP
SB_TOP  6  winuser.h


SB_VERT
SB_VERT  1  winuser.h

Shows or hides a window's standard vertical scroll bar. See EnableScrollBar, GetScrollPos, GetScrollRange, SetScrollPos, SetScrollRange, ShowScrollBar.


FN_SB_VERT
SB_VERT  1  winuser.h


SC_CLOSE
SC_CLOSE  0xF060  winuser.h

Close the window. See WM_SYSCOMMAND.


FN_SC_CLOSE
SC_CLOSE  0xF060  winuser.h


SC_HOTKEY
SC_HOTKEY  0xF150  winuser.h

Activate the window associated with the application-specified hot key. The low-order word of lParam identifies the window to activate. See WM_SYSCOMMAND.


FN_SC_HOTKEY
SC_HOTKEY  0xF150  winuser.h


SC_HSCROLL
SC_HSCROLL  0xF080  winuser.h

Scroll horizontally. See WM_SYSCOMMAND.


FN_SC_HSCROLL
SC_HSCROLL  0xF080  winuser.h


SC_KEYMENU
SC_KEYMENU  0xF100  winuser.h

Retrieve a menu through a keystroke. See WM_SYSCOMMAND.


FN_SC_KEYMENU
SC_KEYMENU  0xF100  winuser.h


SC_MAXIMIZE
SC_MAXIMIZE  0xF030  winuser.h

Maximize the window. See WM_SYSCOMMAND.


FN_SC_MAXIMIZE
SC_MAXIMIZE  0xF030  winuser.h


SC_MINIMIZE
SC_MINIMIZE  0xF020  winuser.h

Minimize the window. See WM_SYSCOMMAND.


FN_SC_MINIMIZE
SC_MINIMIZE  0xF020  winuser.h


SC_MOUSEMENU
SC_MOUSEMENU  0xF090  winuser.h

Retrieve a menu through a mouse click. See WM_SYSCOMMAND.


FN_SC_MOUSEMENU
SC_MOUSEMENU  0xF090  winuser.h


SC_MOVE
SC_MOVE  0xF010  winuser.h

Move the window. See WM_SYSCOMMAND.


FN_SC_MOVE
SC_MOVE  0xF010  winuser.h


SC_NEXTWINDOW
SC_NEXTWINDOW  0xF040  winuser.h

Move to the next window. See WM_SYSCOMMAND.


FN_SC_NEXTWINDOW
SC_NEXTWINDOW  0xF040  winuser.h


SC_PREVWINDOW
SC_PREVWINDOW  0xF050  winuser.h

Move to the previous window. See WM_SYSCOMMAND.


FN_SC_PREVWINDOW
SC_PREVWINDOW  0xF050  winuser.h


SC_RESTORE
SC_RESTORE  0xF120  winuser.h

Restore window to normal position and size. See WM_SYSCOMMAND.


FN_SC_RESTORE
SC_RESTORE  0xF120  winuser.h


SC_SCREENSAVE
SC_SCREENSAVE  0xF140  winuser.h

Execute the screen-saver application specified in the [boot] section of the SYSTEM.INI file. See WM_SYSCOMMAND.


FN_SC_SCREENSAVE
SC_SCREENSAVE  0xF140  winuser.h


SC_SIZE
SC_SIZE  0xF000  winuser.h

Size the window. See WM_SYSCOMMAND.


FN_SC_SIZE
SC_SIZE  0xF000  winuser.h


SC_TASKLIST
SC_TASKLIST  0xF130  winuser.h

Execute or activate the Windows Task Manager application. See WM_SYSCOMMAND.


FN_SC_TASKLIST
SC_TASKLIST  0xF130  winuser.h


SC_VSCROLL
SC_VSCROLL  0xF070  winuser.h

Scroll vertically. See WM_SYSCOMMAND.


FN_SC_VSCROLL
SC_VSCROLL  0xF070  winuser.h


SCREEN_FONTTYPE
SCREEN_FONTTYPE  0x2000  commdlg.h

Specifies that the font is a screen font. See CHOOSEFONT, ChooseFont.


FN_SCREEN_FONTTYPE
SCREEN_FONTTYPE  0x2000  commdlg.h


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 (also called the "thumb"), 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 and used whenever you need to provide scrolling input 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. See CreateWindow.


SCROLLLOCK_ON
SCROLLLOCK_ON  0x0040  wincon.h

The SCROLL LOCK light is on. See KEY_EVENT_RECORD.


FN_SCROLLLOCK_ON
SCROLLLOCK_ON  0x0040  wincon.h


SE_DACL_DEFAULTED
SE_DACL_DEFAULTED  (0x0008)  winnt.h

This bit flag, when set, indicates that a default mechanism, rather than the the original provider of the security descriptor, provided the discretionary access-control list (ACL). This may affect the treatment of the ACL with respect to inheritance of an ACL. This flag is ignored if the SE_DACL_PRESENT flag is not set. The Windows function that sets this flag is SetSecurityDescriptorDacl. See SECURITY_DESCRIPTOR_CONTROL.


FN_SE_DACL_DEFAULTED
SE_DACL_DEFAULTED  (0x0008)  winnt.h


SE_DACL_PRESENT
SE_DACL_PRESENT  (0x0004)  winnt.h

This bit flag, when set, indicates that the security descriptor contains a discretionary access-control list (ACL). If this flag is set and the Dacl member is NULL, then a 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 Windows function that sets this flag is SetSecurityDescriptorDacl. See SECURITY_DESCRIPTOR_CONTROL.


FN_SE_DACL_PRESENT
SE_DACL_PRESENT  (0x0004)  winnt.h


SE_ERR_ASSOCINCOMPLETE
SE_ERR_ASSOCINCOMPLETE  27  shellapi.h

The filename association is incomplete or invalid. See ShellExecute.


FN_SE_ERR_ASSOCINCOMPLETE
SE_ERR_ASSOCINCOMPLETE  27  shellapi.h


SE_ERR_DDEBUSY
SE_ERR_DDEBUSY  30  shellapi.h

The DDE transaction could not be completed because other DDE transactions were being processed. See ShellExecute.


FN_SE_ERR_DDEBUSY
SE_ERR_DDEBUSY  30  shellapi.h


SE_ERR_DDEFAIL
SE_ERR_DDEFAIL  29  shellapi.h

The DDE transaction failed. See ShellExecute.


FN_SE_ERR_DDEFAIL
SE_ERR_DDEFAIL  29  shellapi.h


SE_ERR_DDETIMEOUT
SE_ERR_DDETIMEOUT  28  shellapi.h

The DDE transaction could not be completed because the request timed out. See ShellExecute.


FN_SE_ERR_DDETIMEOUT
SE_ERR_DDETIMEOUT  28  shellapi.h


SE_ERR_NOASSOC
SE_ERR_NOASSOC  31  shellapi.h

There is no application associated with the given filename extension. See ShellExecute.


FN_SE_ERR_NOASSOC
SE_ERR_NOASSOC  31  shellapi.h


SE_ERR_SHARE
SE_ERR_SHARE  26  shellapi.h

A sharing violation occurred. See ShellExecute.


FN_SE_ERR_SHARE
SE_ERR_SHARE  26  shellapi.h


SE_GROUP_DEFAULTED
SE_GROUP_DEFAULTED  (0x0002)  winnt.h

This bit flag, when set, indicates that a default mechanism, rather than the the original provider of the security descriptor, provided the security descriptor's group SID. This may 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 Windows function that sets this flag is SetSecurityDescriptorGroup. See SECURITY_DESCRIPTOR_CONTROL.


FN_SE_GROUP_DEFAULTED
SE_GROUP_DEFAULTED  (0x0002)  winnt.h


SE_GROUP_ENABLED
SE_GROUP_ENABLED  (0x00000004L)  winnt.h

A flag indicating that the group is enabled. See TOKEN_GROUPS.


FN_SE_GROUP_ENABLED
SE_GROUP_ENABLED  (0x00000004L)  winnt.h


SE_GROUP_ENABLED_BY_DEFAULT
SE_GROUP_ENABLED_BY_DEFAULT  (0x00000002L)  winnt.h

A flag indicating that the group is enabled by default. See TOKEN_GROUPS.


FN_SE_GROUP_ENABLED_BY_DEFAULT
SE_GROUP_ENABLED_BY_DEFAULT  (0x00000002L)  winnt.h


SE_GROUP_LOGON_ID
SE_GROUP_LOGON_ID  (0xC0000000L)  winnt.h

A flag indicating that the group contains the logon identifier. See TOKEN_GROUPS.


FN_SE_GROUP_LOGON_ID
SE_GROUP_LOGON_ID  (0xC0000000L)  winnt.h


SE_GROUP_MANDATORY
SE_GROUP_MANDATORY  (0x00000001L)  winnt.h

A flag indicating that the group cannot be disabled. See TOKEN_GROUPS.


FN_SE_GROUP_MANDATORY
SE_GROUP_MANDATORY  (0x00000001L)  winnt.h


SE_GROUP_OWNER
SE_GROUP_OWNER  (0x00000008L)  winnt.h

A flag indicating that the group owns the access token. See TOKEN_GROUPS.


FN_SE_GROUP_OWNER
SE_GROUP_OWNER  (0x00000008L)  winnt.h


SE_OWNER_DEFAULTED
SE_OWNER_DEFAULTED  (0x0001)  winnt.h

This bit flag, when set, indicates that a default mechanism, rather than the original provider of the security descriptor, provided the security descriptor's owner SID. This may affect the treatment of the SID with respect to inheritance of an owner. This flag is ignored if the owner member is NULL. The Windows function that sets this flag is SetSecurityDescriptorOwner. See SECURITY_DESCRIPTOR_CONTROL.


FN_SE_OWNER_DEFAULTED
SE_OWNER_DEFAULTED  (0x0001)  winnt.h


SE_PRIVILEGE_ENABLED
SE_PRIVILEGE_ENABLED  (0x00000002L)  winnt.h

This flag indicates that the privilege is enabled. See TOKEN_PRIVILEGES.


FN_SE_PRIVILEGE_ENABLED
SE_PRIVILEGE_ENABLED  (0x00000002L)  winnt.h


SE_PRIVILEGE_ENABLED_BY_DEFAULT
SE_PRIVILEGE_ENABLED_BY_DEFAULT  (0x00000001L)  winnt.h

This flag indicates that the privilege is enabled by default. See TOKEN_PRIVILEGES.


FN_SE_PRIVILEGE_ENABLED_BY_DEFAULT
SE_PRIVILEGE_ENABLED_BY_DEFAULT  (0x00000001L)  winnt.h


SE_PRIVILEGE_USED_FOR_ACCESS
SE_PRIVILEGE_USED_FOR_ACCESS  (0x80000000L)  winnt.h

This flag indicates that the privilege is required to gain access to an object. (This flag is used to identify the relevant privileges in a set passed by a client application, which may contain unnecessary privileges.) See TOKEN_PRIVILEGES.


FN_SE_PRIVILEGE_USED_FOR_ACCESS
SE_PRIVILEGE_USED_FOR_ACCESS  (0x80000000L)  winnt.h


SE_SACL_DEFAULTED
SE_SACL_DEFAULTED  (0x0020)  winnt.h

This bit flag, when set, indicates that a default mechanism, rather than the the original provider of the security descriptor, provided the system access-control list (ACL). This may affect the treatment of the ACL with respect to inheritance of an ACL. This flag is ignored if the SE_SACL_PRESENT flag is not set. The Windows function that sets this flag is SetSecurityDescriptorSacl. See SECURITY_DESCRIPTOR_CONTROL.


FN_SE_SACL_DEFAULTED
SE_SACL_DEFAULTED  (0x0020)  winnt.h


SE_SACL_PRESENT
SE_SACL_PRESENT  (0x0010)  winnt.h

This bit flag, when set, indicates that the security descriptor contains a system access-control list (ACL). If this flag is set and the Sacl member is NULL, then 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 Windows function that sets this flag is SetSecurityDescriptorSacl. See SECURITY_DESCRIPTOR_CONTROL.


FN_SE_SACL_PRESENT
SE_SACL_PRESENT  (0x0010)  winnt.h


SE_SELF_RELATIVE
SE_SELF_RELATIVE  (0x8000)  winnt.h

This bit flag, when set, indicates that the security descriptor is in self-relative form. In this form, all members of the security descriptor are contiguous in memory, and 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. No Windows function currently sets this flag. See SECURITY_DESCRIPTOR_CONTROL.


FN_SE_SELF_RELATIVE
SE_SELF_RELATIVE  (0x8000)  winnt.h


SEC_COMMIT
SEC_COMMIT  0x8000000  winnt.h

An allocation attribute flag that indicates that all pages of a section are to be set to the commit state, or that all pages of a section were initially set to the commit state. See CreateFileMapping


FN_SEC_COMMIT
SEC_COMMIT  0x8000000  winnt.h


SEC_FILE
SEC_FILE  0x800000  winnt.h

An allocation attribute flag that indicates that a section is backed by a data file. See CreateFileMapping


FN_SEC_FILE
SEC_FILE  0x800000  winnt.h


SEC_IMAGE
SEC_IMAGE  0x1000000  winnt.h

An allocation attribute flag that indicates that the file specified for a section's file mapping is an executable image file, or that a section was initially mapped as an executable image file. See CreateFileMapping


FN_SEC_IMAGE
SEC_IMAGE  0x1000000  winnt.h


SEC_NOCACHE
SEC_NOCACHE  0x10000000  winnt.h

An allocation attribute flag that indicates that all pages of a section are to be set as non-cacheable. See CreateFileMapping


FN_SEC_NOCACHE
SEC_NOCACHE  0x10000000  winnt.h


SEC_RESERVE
SEC_RESERVE  0x4000000  winnt.h

An allocation attribute flag that indicates that all pages of a section are to be set to the reserved state, or that all pages of a section were initially set to the reserved state. See CreateFileMapping


FN_SEC_RESERVE
SEC_RESERVE  0x4000000  winnt.h


SECURITY_ANONYMOUS
SECURITY_ANONYMOUS  ( SecurityAnonymous << 16 )  winbase.h

Specifies that the client should be impersonated at Anonymous impersonation level. See CreateFile.


FN_SECURITY_ANONYMOUS
SECURITY_ANONYMOUS  ( SecurityAnonymous << 16 )  winbase.h


SECURITY_CONTEXT_TRACKING
SECURITY_CONTEXT_TRACKING  0x00040000  winbase.h

Specifies that the Security Tracking Mode should be Dynamic. If this flag is not specified, Security Tracking Mode is Static. See CreateFile.


FN_SECURITY_CONTEXT_TRACKING
SECURITY_CONTEXT_TRACKING  0x00040000  winbase.h


SECURITY_DELEGATION
SECURITY_DELEGATION  ( SecurityDelegation << 16 )  winbase.h

Specifies that the client should be impersonated at Delegation impersonation level. See CreateFile.


FN_SECURITY_DELEGATION
SECURITY_DELEGATION  ( SecurityDelegation << 16 )  winbase.h


SECURITY_EFFECTIVE_ONLY
SECURITY_EFFECTIVE_ONLY  0x00080000  winbase.h

Specifies that only the effective aspects of the client's security context are available to the server. If this flag is not specified, only the effective aspects of the context. See CreateFile.


FN_SECURITY_EFFECTIVE_ONLY
SECURITY_EFFECTIVE_ONLY  0x00080000  winbase.h


SECURITY_IDENTIFICATION
SECURITY_IDENTIFICATION  ( SecurityIdentification << 16 )  winbase.h

Specifies that the client should be impersonated at Identification impersonation level. See CreateFile.


FN_SECURITY_IDENTIFICATION
SECURITY_IDENTIFICATION  ( SecurityIdentification << 16 )  winbase.h


SECURITY_IMPERSONATION
SECURITY_IMPERSONATION  ( SecurityImpersonation << 16 )  winbase.h

Specifies that the client should be impersonated at Impersonation impersonation level. See CreateFile.


FN_SECURITY_IMPERSONATION
SECURITY_IMPERSONATION  ( SecurityImpersonation << 16 )  winbase.h


SEEK_CUR
SEEK_CUR  1  mmsystem.h

Seeks to lOffset bytes from the current file position. See mmioSeek, MMIOM_SEEK.


FN_SEEK_CUR
SEEK_CUR  1  mmsystem.h


SEEK_END
SEEK_END  2  mmsystem.h

Seeks to lOffset bytes from the end of the file. See mmioSeek, MMIOM_SEEK.


FN_SEEK_END
SEEK_END  2  mmsystem.h


SEEK_SET
SEEK_SET  0  mmsystem.h

Seeks to lOffset bytes from the beginning of the file. See mmioSeek, MMIOM_SEEK.


FN_SEEK_SET
SEEK_SET  0  mmsystem.h


SEM_FAILCRITICALERRORS
SEM_FAILCRITICALERRORS  0x0001  winbase.h

Windows does not display the critical-error-handler message box and returns the error to the calling application. See SetErrorMode.


FN_SEM_FAILCRITICALERRORS
SEM_FAILCRITICALERRORS  0x0001  winbase.h


SEM_NOGPFAULTERRORBOX
SEM_NOGPFAULTERRORBOX  0x0002  winbase.h

Windows does not display the general-protection-fault message box. This flag should be set only by debugging applications that handle GP faults themselves. See SetErrorMode.


FN_SEM_NOGPFAULTERRORBOX
SEM_NOGPFAULTERRORBOX  0x0002  winbase.h


SEM_NOOPENFILEERRORBOX
SEM_NOOPENFILEERRORBOX  0x8000  winbase.h

Windows does not display a message box when it fails to find a file. See SetErrorMode.


FN_SEM_NOOPENFILEERRORBOX
SEM_NOOPENFILEERRORBOX  0x8000  winbase.h


SEMAPHORE_ALL_ACCESS
SEMAPHORE_ALL_ACCESS  (STANDARD_RIGHTS_REQUIRED|SYNCHRONIZE|0x3)  winnt.h

Specifies all possible access rights for a semaphore object. See CreateSemaphore and OpenSemaphore.


FN_SEMAPHORE_ALL_ACCESS
SEMAPHORE_ALL_ACCESS  (STANDARD_RIGHTS_REQUIRED|SYNCHRONIZE|0x3)  winnt.h


SESSION_ABORTED
SESSION_ABORTED  0x06  nb30.h

The session was abandoned due to a network or user problem. See SESSION_BUFFER.


FN_SESSION_ABORTED
SESSION_ABORTED  0x06  nb30.h


SESSION_ESTABLISHED
SESSION_ESTABLISHED  0x03  nb30.h

The session connected and is able to transfer data. See SESSION_BUFFER.


FN_SESSION_ESTABLISHED
SESSION_ESTABLISHED  0x03  nb30.h


SET_TAPE_MEDIA_INFORMATION
SET_TAPE_MEDIA_INFORMATION  0  winbase.h

Set the tape-specific information specified by lpTapeInformation. See SetTapeParameters.


FN_SET_TAPE_MEDIA_INFORMATION
SET_TAPE_MEDIA_INFORMATION  0  winbase.h


SHIFT_PRESSED
SHIFT_PRESSED  0x0010  wincon.h

The SHIFT key is pressed. See KEY_EVENT_RECORD.


FN_SHIFT_PRESSED
SHIFT_PRESSED  0x0010  wincon.h


SHUTDOWN_NORETRY
SHUTDOWN_NORETRY  0x00000001  winbase.h

If this process takes longer than the specified timeout to shutdown, do not put up a retry dialog for the user. Instead, just cause the process to directly exit. See GetProcessShutdownParameters, SetProcessShutdownParameters.


FN_SHUTDOWN_NORETRY
SHUTDOWN_NORETRY  0x00000001  winbase.h


SIMPLEREGION
SIMPLEREGION  2  wingdi.h

New region is a single rectangle. See CombineRgn, ExcludeClipRect, ExcludeUpdateRgn. ExtSelectClipRgn, GetClipBox, GetRgnBox, IntersectClipRect, OffsetClipRgn, OffsetRgn, SelectClipRgn, SelectObject, SetMetaRgn.


FN_SIMPLEREGION
SIMPLEREGION  2  wingdi.h


SIMULATED_FONTTYPE
SIMULATED_FONTTYPE  0x8000  commdlg.h

Specifies that the font is simulated by GDI. See CHOOSEFONT, ChooseFont.


FN_SIMULATED_FONTTYPE
SIMULATED_FONTTYPE  0x8000  commdlg.h


SIZE_MAXHIDE
SIZE_MAXHIDE  4  winuser.h

Message is sent to all pop-up windows when some other window is maximized. See WM_SIZE.


FN_SIZE_MAXHIDE
SIZE_MAXHIDE  4  winuser.h


SIZE_MAXIMIZED
SIZE_MAXIMIZED  2  winuser.h

Window has been maximized. See WM_SIZE.


FN_SIZE_MAXIMIZED
SIZE_MAXIMIZED  2  winuser.h


SIZE_MAXSHOW
SIZE_MAXSHOW  3  winuser.h

Message is sent to all pop-up windows when some other window has been restored to its former size. See WM_SIZE.


FN_SIZE_MAXSHOW
SIZE_MAXSHOW  3  winuser.h


SIZE_MINIMIZED
SIZE_MINIMIZED  1  winuser.h

Window has been minimized. See WM_SIZE.


FN_SIZE_MINIMIZED
SIZE_MINIMIZED  1  winuser.h


SIZE_RESTORED
SIZE_RESTORED  0  winuser.h

Window has been resized, but neither SIZE_MINIMIZED nor SIZE_MAXIMIZED applies. See WM_SIZE.


FN_SIZE_RESTORED
SIZE_RESTORED  0  winuser.h


SIZEPALETTE
SIZEPALETTE  104  wingdi.h

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 version 3.0 or later. See GetDeviceCaps.


FN_SIZEPALETTE
SIZEPALETTE  104  wingdi.h


SLE_ERROR
SLE_ERROR  0x00000001  winbase.h

Invalid data was passed to the function and complete failure has occurred. See SetDebugErrorLevel, SetLastErrorEx.


FN_SLE_ERROR
SLE_ERROR  0x00000001  winbase.h


SLE_MINORERROR
SLE_MINORERROR  0x00000002  winbase.h

Invalid data was passed to the function, but the function has recovered. See SetDebugErrorLevel, SetLastErrorEx.


FN_SLE_MINORERROR
SLE_MINORERROR  0x00000002  winbase.h


SLE_WARNING
SLE_WARNING  0x00000003  winbase.h

Potentially invalid data was passed to the function, but the function has recovered. See SetDebugErrorLevel, SetLastErrorEx.


FN_SLE_WARNING
SLE_WARNING  0x00000003  winbase.h


SM_CMOUSEBUTTONS
SM_CMOUSEBUTTONS  43  winuser.h

Number of buttons on the mouse. See GetSystemMetrics.


FN_SM_CMOUSEBUTTONS
SM_CMOUSEBUTTONS  43  winuser.h


SM_CXBORDER
SM_CXBORDER  5  winuser.h

Width of window frame that cannot be sized. See GetSystemMetrics.


FN_SM_CXBORDER
SM_CXBORDER  5  winuser.h


SM_CXCURSOR
SM_CXCURSOR  13  winuser.h

Width of cursor. See GetSystemMetrics.


FN_SM_CXCURSOR
SM_CXCURSOR  13  winuser.h


SM_CXDLGFRAME
SM_CXDLGFRAME  7  winuser.h

Width of frame when window has WS_DLGFRAME style. See GetSystemMetrics.


FN_SM_CXDLGFRAME
SM_CXDLGFRAME  7  winuser.h


SM_CXDOUBLECLK
SM_CXDOUBLECLK  36  winuser.h

Width of the rectangle around the location of the 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. See GetSystemMetrics.


FN_SM_CXDOUBLECLK
SM_CXDOUBLECLK  36  winuser.h


SM_CXFRAME
SM_CXFRAME  32  winuser.h

Width of window frame that can be sized. See GetSystemMetrics.


FN_SM_CXFRAME
SM_CXFRAME  32  winuser.h


SM_CXFULLSCREEN
SM_CXFULLSCREEN  16  winuser.h

Width of window client area for full-screen window. See GetSystemMetrics.


FN_SM_CXFULLSCREEN
SM_CXFULLSCREEN  16  winuser.h


SM_CXHSCROLL
SM_CXHSCROLL  21  winuser.h

Width of arrow bitmap on horizontal scroll bar. See GetSystemMetrics.


FN_SM_CXHSCROLL
SM_CXHSCROLL  21  winuser.h


SM_CXHTHUMB
SM_CXHTHUMB  10  winuser.h

Width of thumb box on horizontal scroll bar. See GetSystemMetrics.


FN_SM_CXHTHUMB
SM_CXHTHUMB  10  winuser.h


SM_CXICON
SM_CXICON  11  winuser.h

Width of icon. See GetSystemMetrics.


FN_SM_CXICON
SM_CXICON  11  winuser.h


SM_CXICONSPACING
SM_CXICONSPACING  38  winuser.h

Width of the rectangles that Program Manager uses to position tiled icons. See GetSystemMetrics.


FN_SM_CXICONSPACING
SM_CXICONSPACING  38  winuser.h


SM_CXMIN
SM_CXMIN  28  winuser.h

Minimum width of window. See GetSystemMetrics.


FN_SM_CXMIN
SM_CXMIN  28  winuser.h


SM_CXMINTRACK
SM_CXMINTRACK  34  winuser.h

Minimum tracking width of window. See GetSystemMetrics.


FN_SM_CXMINTRACK
SM_CXMINTRACK  34  winuser.h


SM_CXSCREEN
SM_CXSCREEN  0  winuser.h

Width of screen. See GetSystemMetrics.


FN_SM_CXSCREEN
SM_CXSCREEN  0  winuser.h


SM_CXSIZE
SM_CXSIZE  30  winuser.h

Width of bitmaps contained in the title bar. See GetSystemMetrics.


FN_SM_CXSIZE
SM_CXSIZE  30  winuser.h


SM_CXVSCROLL
SM_CXVSCROLL  2  winuser.h

Width of arrow bitmap on vertical scroll bar. See GetSystemMetrics.


FN_SM_CXVSCROLL
SM_CXVSCROLL  2  winuser.h


SM_CYBORDER
SM_CYBORDER  6  winuser.h

Height of window frame that cannot be sized. See GetSystemMetrics.


FN_SM_CYBORDER
SM_CYBORDER  6  winuser.h


SM_CYCAPTION
SM_CYCAPTION  4  winuser.h

Actual caption height plus SM_CYBORDER. See GetSystemMetrics.


FN_SM_CYCAPTION
SM_CYCAPTION  4  winuser.h


SM_CYCURSOR
SM_CYCURSOR  14  winuser.h

Height of cursor. See GetSystemMetrics.


FN_SM_CYCURSOR
SM_CYCURSOR  14  winuser.h


SM_CYDLGFRAME
SM_CYDLGFRAME  8  winuser.h

Height of frame when window has WS_DLGFRAME style. See GetSystemMetrics.


FN_SM_CYDLGFRAME
SM_CYDLGFRAME  8  winuser.h


SM_CYDOUBLECLK
SM_CYDOUBLECLK  37  winuser.h

Height of the rectangle around the location of the 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. See GetSystemMetrics.


FN_SM_CYDOUBLECLK
SM_CYDOUBLECLK  37  winuser.h


SM_CYFRAME
SM_CYFRAME  33  winuser.h

Height of window frame that can be sized. See GetSystemMetrics.


FN_SM_CYFRAME
SM_CYFRAME  33  winuser.h


SM_CYFULLSCREEN
SM_CYFULLSCREEN  17  winuser.h

Height of window client area for full-screen window (equivalent to the height of the screen minus the height of the window caption). See GetSystemMetrics.


FN_SM_CYFULLSCREEN
SM_CYFULLSCREEN  17  winuser.h


SM_CYHSCROLL
SM_CYHSCROLL  3  winuser.h

Height of arrow bitmap on horizontal scroll bar. See GetSystemMetrics.


FN_SM_CYHSCROLL
SM_CYHSCROLL  3  winuser.h


SM_CYICON
SM_CYICON  12  winuser.h

Height of icon. See GetSystemMetrics.


FN_SM_CYICON
SM_CYICON  12  winuser.h


SM_CYICONSPACING
SM_CYICONSPACING  39  winuser.h

Height of the rectangles that Program Manager uses to position tiled icons. See GetSystemMetrics.


FN_SM_CYICONSPACING
SM_CYICONSPACING  39  winuser.h


SM_CYKANJIWINDOW
SM_CYKANJIWINDOW  18  winuser.h

Height of Kanji window. See GetSystemMetrics.


FN_SM_CYKANJIWINDOW
SM_CYKANJIWINDOW  18  winuser.h


SM_CYMENU
SM_CYMENU  15  winuser.h

Height of single-line menu bar minus SM_CYBORDER. See GetSystemMetrics.


FN_SM_CYMENU
SM_CYMENU  15  winuser.h


SM_CYMIN
SM_CYMIN  29  winuser.h

Minimum height of window. See GetSystemMetrics.


FN_SM_CYMIN
SM_CYMIN  29  winuser.h


SM_CYMINTRACK
SM_CYMINTRACK  35  winuser.h

Minimum tracking height of window. See GetSystemMetrics.


FN_SM_CYMINTRACK
SM_CYMINTRACK  35  winuser.h


SM_CYSCREEN
SM_CYSCREEN  1  winuser.h

Height of screen. See GetSystemMetrics.


FN_SM_CYSCREEN
SM_CYSCREEN  1  winuser.h


SM_CYSIZE
SM_CYSIZE  31  winuser.h

Height of bitmaps contained in the title bar. See GetSystemMetrics.


FN_SM_CYSIZE
SM_CYSIZE  31  winuser.h


SM_CYVSCROLL
SM_CYVSCROLL  20  winuser.h

Height of arrow bitmap on vertical scroll bar. See GetSystemMetrics.


FN_SM_CYVSCROLL
SM_CYVSCROLL  20  winuser.h


SM_CYVTHUMB
SM_CYVTHUMB  9  winuser.h

Height of thumb box on vertical scroll bar. See GetSystemMetrics.


FN_SM_CYVTHUMB
SM_CYVTHUMB  9  winuser.h


SM_DBCSENABLED
SM_DBCSENABLED  42  winuser.h

Nonzero if double-byte character set enabled. See GetSystemMetrics.


FN_SM_DBCSENABLED
SM_DBCSENABLED  42  winuser.h


SM_DEBUG
SM_DEBUG  22  winuser.h

Nonzero if Windows debugging version. See GetSystemMetrics.


FN_SM_DEBUG
SM_DEBUG  22  winuser.h


SM_MENUDROPALIGNMENT
SM_MENUDROPALIGNMENT  40  winuser.h

Alignment of popup menus. If this value is 0, the left side of a popup menu is aligned with the left side of the corresponding menu-bar item. If this value is nonzero, the left side of a popup menu is aligned with the right side of the corresponding menu-bar item. See GetSystemMetrics.


FN_SM_MENUDROPALIGNMENT
SM_MENUDROPALIGNMENT  40  winuser.h


SM_MOUSEPRESENT
SM_MOUSEPRESENT  19  winuser.h

Nonzero if mouse hardware installed. See GetSystemMetrics.


FN_SM_MOUSEPRESENT
SM_MOUSEPRESENT  19  winuser.h


SM_PENWINDOWS
SM_PENWINDOWS  41  winuser.h

Handle of the Pen Windows dynamic-link library (DLL) if Pen Windows is installed. See GetSystemMetrics.


FN_SM_PENWINDOWS
SM_PENWINDOWS  41  winuser.h


SM_SWAPBUTTON
SM_SWAPBUTTON  23  winuser.h

Nonzero if left and right mouse buttons swapped. See GetSystemMetrics.


FN_SM_SWAPBUTTON
SM_SWAPBUTTON  23  winuser.h


SMTO_ABORTIFHUNG
SMTO_ABORTIFHUNG  0x0002  winuser.h

Returns without waiting for the timeout period to elapse if the receiving process appears to be in a hung state. See SendMessageTimeout.


FN_SMTO_ABORTIFHUNG
SMTO_ABORTIFHUNG  0x0002  winuser.h


SMTO_BLOCK
SMTO_BLOCK  0x0001  winuser.h

Prevents the calling thread from processing any other requests until the function returns. See SendMessageTimeout.


FN_SMTO_BLOCK
SMTO_BLOCK  0x0001  winuser.h


SMTO_NORMAL

Allows the calling thread to process other requests while waiting for the function to return. See SendMessageTimeout


SND_ALIAS
SND_ALIAS  0x00010000  mmsystem.h

lpszName specifies an entry in the [sounds] section of the registry of the form: alias=pathname. May not be used with either SND_FILENAME or SND_RESOURCE. See PlaySound.


FN_SND_ALIAS
SND_ALIAS  0x00010000  mmsystem.h


SND_ASYNC
SND_ASYNC  0x00000001  mmsystem.h

The sound is played asynchronously and the function returns immediately after beginning the sound. To terminate an asynchronously-played sound, call lpszSoundName set to NULL. See PlaySound, sndPlaySound.


FN_SND_ASYNC
SND_ASYNC  0x00000001  mmsystem.h


SND_FILENAME
SND_FILENAME  0x00020000  mmsystem.h

lpszName specifies the name of a wave file. May not be used with either SND_ALIAS or SND_RESOURCE. See PlaySound.


FN_SND_FILENAME
SND_FILENAME  0x00020000  mmsystem.h


SND_LOOP
SND_LOOP  0x00000008  mmsystem.h

The sound will continue to play repeatedly until sndPlaySound is called again with the lpszSoundName parameter set to NULL. You must also specify the SND_ASYNC flag to loop sounds. See sndPlaySound.


FN_SND_LOOP
SND_LOOP  0x00000008  mmsystem.h


SND_MEMORY
SND_MEMORY  0x00000004  mmsystem.h

The parameter specified by lpszSoundName points to an in-memory image of a waveform sound. See sndPlaySound.


FN_SND_MEMORY
SND_MEMORY  0x00000004  mmsystem.h


SND_NODEFAULT
SND_NODEFAULT  0x00000002  mmsystem.h

If the sound can't be found, the function returns silently without playing the default sound. See PlaySound, sndPlaySound.


FN_SND_NODEFAULT
SND_NODEFAULT  0x00000002  mmsystem.h


SND_NOSTOP
SND_NOSTOP  0x00000010  mmsystem.h

If a sound is currently playing, the function will immediately return FALSE without playing the requested sound. See sndPlaySound.


FN_SND_NOSTOP
SND_NOSTOP  0x00000010  mmsystem.h


SND_NOWAIT
SND_NOWAIT  0x00002000  mmsystem.h

When this flag is set, the call to PlaySound will fail if no suitable wave device is available to play the sound. See PlaySound.


FN_SND_NOWAIT
SND_NOWAIT  0x00002000  mmsystem.h


SND_RESOURCE
SND_RESOURCE  0x00040004  mmsystem.h

lpszName specifies the name of a resource. May not be used with either SND_ALIAS or SND_FILENAME. See PlaySound.


FN_SND_RESOURCE
SND_RESOURCE  0x00040004  mmsystem.h


SND_SYNC
SND_SYNC  0x00000000  mmsystem.h

The sound is played synchronously and the function does not return until the sound ends. See PlaySound, sndPlaySound.


FN_SND_SYNC
SND_SYNC  0x00000000  mmsystem.h


SORT_STRINGSORT
SORT_STRINGSORT  0x00001000  winnls.h

Sort using what is called a "string sort", in which the hyphen and apostrophe are treated just like any other non-alphanumeric symbols: they come before the alphanumeric symbols. Specified to override the default "word sort", in which those characters are treated differently than other non-alphanumeric symbols. See CompareStringW, LCMapStringW


FN_SORT_STRINGSORT
SORT_STRINGSORT  0x00001000  winnls.h


SP_APPABORT
SP_APPABORT  (-2)  wingdi.h

Job was terminated because the application's print-canceling function returned zero. See EndPage.


FN_SP_APPABORT
SP_APPABORT  (-2)  wingdi.h


SP_ERROR
SP_ERROR  (-1)  wingdi.h

General error. See EndPage, Escape.


FN_SP_ERROR
SP_ERROR  (-1)  wingdi.h


SP_OUTOFDISK
SP_OUTOFDISK  (-4)  wingdi.h

Not enough disk space is currently available for spooling, and no more space will become available. See EndPage, Escape.


FN_SP_OUTOFDISK
SP_OUTOFDISK  (-4)  wingdi.h


SP_OUTOFMEMORY
SP_OUTOFMEMORY  (-5)  wingdi.h

Not enough memory is available for spooling. See EndPage, Escape.


FN_SP_OUTOFMEMORY
SP_OUTOFMEMORY  (-5)  wingdi.h


SP_USERABORT
SP_USERABORT  (-3)  wingdi.h

User terminated the job through Print Manager. See EndPage, Escape.


FN_SP_USERABORT
SP_USERABORT  (-3)  wingdi.h


SPI_GETBEEP
SPI_GETBEEP  1  winuser.h

Retrieves a BOOL value that indicates whether the warning beeper is on or off. See SystemParametersInfo.


FN_SPI_GETBEEP
SPI_GETBEEP  1  winuser.h


SPI_GETBORDER
SPI_GETBORDER  5  winuser.h

Retrieves the border multiplier factor that determines the width of a window's sizing border. See SystemParametersInfo.


FN_SPI_GETBORDER
SPI_GETBORDER  5  winuser.h


SPI_GETFASTTASKSWITCH
SPI_GETFASTTASKSWITCH  35  winuser.h

Determines whether fast task-switching is on of off. See SystemParametersInfo.


FN_SPI_GETFASTTASKSWITCH
SPI_GETFASTTASKSWITCH  35  winuser.h


SPI_GETGRIDGRANULARITY
SPI_GETGRIDGRANULARITY  18  winuser.h

Retrieves the current granularity value of the desktop sizing grid. See SystemParametersInfo.


FN_SPI_GETGRIDGRANULARITY
SPI_GETGRIDGRANULARITY  18  winuser.h


SPI_GETICONTITLELOGFONT
SPI_GETICONTITLELOGFONT  31  winuser.h

Retrieves the logical font information for the current icon-title font. See SystemParametersInfo.


FN_SPI_GETICONTITLELOGFONT
SPI_GETICONTITLELOGFONT  31  winuser.h


SPI_GETICONTITLEWRAP
SPI_GETICONTITLEWRAP  25  winuser.h

Determines whether icon title wrapping is on or off. See SystemParametersInfo.


FN_SPI_GETICONTITLEWRAP
SPI_GETICONTITLEWRAP  25  winuser.h


SPI_GETKEYBOARDDELAY
SPI_GETKEYBOARDDELAY  22  winuser.h

Retrieves the keyboard repeat-delay setting. See SystemParametersInfo.


FN_SPI_GETKEYBOARDDELAY
SPI_GETKEYBOARDDELAY  22  winuser.h


SPI_GETKEYBOARDSPEED
SPI_GETKEYBOARDSPEED  10  winuser.h

Retrieves the keyboard repeat-speed setting. See SystemParametersInfo.


FN_SPI_GETKEYBOARDSPEED
SPI_GETKEYBOARDSPEED  10  winuser.h


SPI_GETMENUDROPALIGNMENT
SPI_GETMENUDROPALIGNMENT  27  winuser.h

Determines whether popup menus are left aligned or right aligned relative to the corresponding menu-bar item. See SystemParametersInfo.


FN_SPI_GETMENUDROPALIGNMENT
SPI_GETMENUDROPALIGNMENT  27  winuser.h


SPI_GETMOUSE
SPI_GETMOUSE  3  winuser.h

Retrieves the mouse speed and the x and y mouse threshold values. See SystemParametersInfo.


FN_SPI_GETMOUSE
SPI_GETMOUSE  3  winuser.h


SPI_GETSCREENSAVEACTIVE
SPI_GETSCREENSAVEACTIVE  16  winuser.h

Retrieves a BOOL value that indicates whether screen saving is on or off. See SystemParametersInfo.


FN_SPI_GETSCREENSAVEACTIVE
SPI_GETSCREENSAVEACTIVE  16  winuser.h


SPI_GETSCREENSAVETIMEOUT
SPI_GETSCREENSAVETIMEOUT  14  winuser.h

Retrieves the screen-saver timeout value. See SystemParametersInfo.


FN_SPI_GETSCREENSAVETIMEOUT
SPI_GETSCREENSAVETIMEOUT  14  winuser.h


SPI_ICONHORIZONTALSPACING
SPI_ICONHORIZONTALSPACING  13  winuser.h

Sets the width (in pixels) of an icon cell. See SystemParametersInfo.


FN_SPI_ICONHORIZONTALSPACING
SPI_ICONHORIZONTALSPACING  13  winuser.h


SPI_ICONVERTICALSPACING
SPI_ICONVERTICALSPACING  24  winuser.h

Sets the height (in pixels) of an icon cell. See SystemParametersInfo.


FN_SPI_ICONVERTICALSPACING
SPI_ICONVERTICALSPACING  24  winuser.h


SPI_LANGDRIVER
SPI_LANGDRIVER  12  winuser.h

Identifies the language driver. See SystemParametersInfo.


FN_SPI_LANGDRIVER
SPI_LANGDRIVER  12  winuser.h


SPI_SETBEEP
SPI_SETBEEP  2  winuser.h

Turns the warning beeper on or off. See SystemParametersInfo.


FN_SPI_SETBEEP
SPI_SETBEEP  2  winuser.h


SPI_SETBORDER
SPI_SETBORDER  6  winuser.h

Sets the border multiplier factor that determines the width of a window's sizing border. See SystemParametersInfo.


FN_SPI_SETBORDER
SPI_SETBORDER  6  winuser.h


SPI_SETDESKPATTERN
SPI_SETDESKPATTERN  21  winuser.h

Sets the current desktop pattern by causing the Windows USER.EXE program to read the "Pattern=" parameter from the WIN.INI file. See SystemParametersInfo.


FN_SPI_SETDESKPATTERN
SPI_SETDESKPATTERN  21  winuser.h


SPI_SETDESKWALLPAPER
SPI_SETDESKWALLPAPER  20  winuser.h

Specifies the filename that contains the bitmap to be used as the desktop wallpaper. See SystemParametersInfo.


FN_SPI_SETDESKWALLPAPER
SPI_SETDESKWALLPAPER  20  winuser.h


SPI_SETDOUBLECLICKTIME
SPI_SETDOUBLECLICKTIME  32  winuser.h

Sets the double-click time for the mouse. The double-click time is the maximum number of milliseconds that may occur between the first and second clicks of a double-click. See SystemParametersInfo.


FN_SPI_SETDOUBLECLICKTIME
SPI_SETDOUBLECLICKTIME  32  winuser.h


SPI_SETDOUBLECLKHEIGHT
SPI_SETDOUBLECLKHEIGHT  30  winuser.h

Sets the height of the rectangle within which the second click of a double click must fall for it to be registered as a double click. See SystemParametersInfo.


FN_SPI_SETDOUBLECLKHEIGHT
SPI_SETDOUBLECLKHEIGHT  30  winuser.h


SPI_SETDOUBLECLKWIDTH
SPI_SETDOUBLECLKWIDTH  29  winuser.h

Sets the width of the rectangle within which the second click of a double click must fall for it to be registered as a double click. See SystemParametersInfo.


FN_SPI_SETDOUBLECLKWIDTH
SPI_SETDOUBLECLKWIDTH  29  winuser.h


SPI_SETFASTTASKSWITCH
SPI_SETFASTTASKSWITCH  36  winuser.h

Turns fast task-switching on or off. See SystemParametersInfo.


FN_SPI_SETFASTTASKSWITCH
SPI_SETFASTTASKSWITCH  36  winuser.h


SPI_SETGRIDGRANULARITY
SPI_SETGRIDGRANULARITY  19  winuser.h

Sets the granularity of the desktop sizing grid. See SystemParametersInfo.


FN_SPI_SETGRIDGRANULARITY
SPI_SETGRIDGRANULARITY  19  winuser.h


SPI_SETICONTITLELOGFONT
SPI_SETICONTITLELOGFONT  34  winuser.h

Sets the font that is used for icon titles. See SystemParametersInfo.


FN_SPI_SETICONTITLELOGFONT
SPI_SETICONTITLELOGFONT  34  winuser.h


SPI_SETICONTITLEWRAP
SPI_SETICONTITLEWRAP  26  winuser.h

Turns icon title wrapping on or off. See SystemParametersInfo.


FN_SPI_SETICONTITLEWRAP
SPI_SETICONTITLEWRAP  26  winuser.h


SPI_SETKEYBOARDDELAY
SPI_SETKEYBOARDDELAY  23  winuser.h

Sets the keyboard repeat-delay setting. See SystemParametersInfo.


FN_SPI_SETKEYBOARDDELAY
SPI_SETKEYBOARDDELAY  23  winuser.h


SPI_SETKEYBOARDSPEED
SPI_SETKEYBOARDSPEED  11  winuser.h

Sets the keyboard repeat-speed setting. See SystemParametersInfo.


FN_SPI_SETKEYBOARDSPEED
SPI_SETKEYBOARDSPEED  11  winuser.h


SPI_SETMENUDROPALIGNMENT
SPI_SETMENUDROPALIGNMENT  28  winuser.h

Sets the alignment value of popup menus. See SystemParametersInfo.


FN_SPI_SETMENUDROPALIGNMENT
SPI_SETMENUDROPALIGNMENT  28  winuser.h


SPI_SETMOUSE
SPI_SETMOUSE  4  winuser.h

Sets the mouse speed and the x and y mouse threshold values. See SystemParametersInfo.


FN_SPI_SETMOUSE
SPI_SETMOUSE  4  winuser.h


SPI_SETMOUSEBUTTONSWAP
SPI_SETMOUSEBUTTONSWAP  33  winuser.h

Swaps or restores the meaning of the left and right mouse buttons. See SystemParametersInfo.


FN_SPI_SETMOUSEBUTTONSWAP
SPI_SETMOUSEBUTTONSWAP  33  winuser.h


SPI_SETSCREENSAVEACTIVE
SPI_SETSCREENSAVEACTIVE  17  winuser.h

Sets the state of the screen saver. See SystemParametersInfo.


FN_SPI_SETSCREENSAVEACTIVE
SPI_SETSCREENSAVEACTIVE  17  winuser.h


SPI_SETSCREENSAVETIMEOUT
SPI_SETSCREENSAVETIMEOUT  15  winuser.h

Sets the screen-saver timeout value. See SystemParametersInfo.


FN_SPI_SETSCREENSAVETIMEOUT
SPI_SETSCREENSAVETIMEOUT  15  winuser.h


SPIF_SENDWININICHANGE
SPIF_SENDWININICHANGE  0x0002  winuser.h

Broadcasts the WM_WININICHANGE message after updating the user's profile. See SystemParametersInfo.


FN_SPIF_SENDWININICHANGE
SPIF_SENDWININICHANGE  0x0002  winuser.h


SPIF_UPDATEINIFILE
SPIF_UPDATEINIFILE  0x0001  winuser.h

Writes the new system-wide parameter setting to the user's profile. See SystemParametersInfo.


FN_SPIF_UPDATEINIFILE
SPIF_UPDATEINIFILE  0x0001  winuser.h


SRCAND
SRCAND  (DWORD)0x008800C6  wingdi.h

Combines the colors of the source and destination rectangles are combined by using the Boolean AND operator. See BitBlt.


FN_SRCAND
SRCAND  (DWORD)0x008800C6  wingdi.h


SRCCOPY
SRCCOPY  (DWORD)0x00CC0020  wingdi.h

Copies the source rectangle directly to the destination rectangle. See BitBlt.


FN_SRCCOPY
SRCCOPY  (DWORD)0x00CC0020  wingdi.h


SRCERASE
SRCERASE  (DWORD)0x00440328  wingdi.h

Combines the inverted colors of the destination rectangle with the colors of the source rectangle by using the Boolean AND operator. See BitBlt.


FN_SRCERASE
SRCERASE  (DWORD)0x00440328  wingdi.h


SRCINVERT
SRCINVERT  (DWORD)0x00660046  wingdi.h

Combines the colors of the source and destination rectangles by using the Boolean XOR operator. See BitBlt.


FN_SRCINVERT
SRCINVERT  (DWORD)0x00660046  wingdi.h


SRCPAINT
SRCPAINT  (DWORD)0x00EE0086  wingdi.h

Combines the colors of the source and destination rectangles by using the Boolean OR operator. See BitBlt.


FN_SRCPAINT
SRCPAINT  (DWORD)0x00EE0086  wingdi.h


ST_ADVISE
ST_ADVISE  0x0002  ddeml.h

One or more links are in progress. See CONVINFO.


FN_ST_ADVISE
ST_ADVISE  0x0002  ddeml.h


ST_BLOCKED
ST_BLOCKED  0x0008  ddeml.h

The conversation is blocked. See CONVINFO.


FN_ST_BLOCKED
ST_BLOCKED  0x0008  ddeml.h


ST_BLOCKNEXT
ST_BLOCKNEXT  0x0080  ddeml.h

The conversation will block after calling the next callback. See CONVINFO.


FN_ST_BLOCKNEXT
ST_BLOCKNEXT  0x0080  ddeml.h


ST_CLIENT
ST_CLIENT  0x0010  ddeml.h

The conversation handle passed to the DdeQueryConvInfo function is a client side handle. If the handle is 0, the conversation handle passed to the DdeQueryConvInfo function is a server side handle. See CONVINFO.


FN_ST_CLIENT
ST_CLIENT  0x0010  ddeml.h


ST_CONNECTED
ST_CONNECTED  0x0001  ddeml.h

The conversation is connected. See CONVINFO.


FN_ST_CONNECTED
ST_CONNECTED  0x0001  ddeml.h


ST_INLIST
ST_INLIST  0x0040  ddeml.h

The conversation is a member of a conversation list. See CONVINFO.


FN_ST_INLIST
ST_INLIST  0x0040  ddeml.h


ST_ISLOCAL
ST_ISLOCAL  0x0004  ddeml.h

Both sides of the conversation are using the DDEML. See CONVINFO.


FN_ST_ISLOCAL
ST_ISLOCAL  0x0004  ddeml.h


ST_ISSELF
ST_ISSELF  0x0100  ddeml.h

Both sides of the conversation are using the same instance of the DDEML. See CONVINFO.


FN_ST_ISSELF
ST_ISSELF  0x0100  ddeml.h


ST_TERMINATED
ST_TERMINATED  0x0020  ddeml.h

The conversation has been terminated by the partner. See CONVINFO.


FN_ST_TERMINATED
ST_TERMINATED  0x0020  ddeml.h


STARTF_FORCEOFFFEEDBACK
STARTF_FORCEOFFFEEDBACK  0x00000080  winbase.h

If specified, the feedback cursor is forced off while the application is starting. The normal cursor is displayed. For more information on feedback, see the comments section. See STARTUPINFO.


FN_STARTF_FORCEOFFFEEDBACK
STARTF_FORCEOFFFEEDBACK  0x00000080  winbase.h


STARTF_FORCEONFEEDBACK
STARTF_FORCEONFEEDBACK  0x00000040  winbase.h

If specified, the cursor is in feedback mode for two seconds after CreateProcess is called. If during those two seconds, the application makes the first GUI call, the system gives five more seconds to the application. If during those five seconds, the application shows a window, the system gives five more seconds to the application to finish drawing the window. The system turns the feedback cursor off after the first call to GetMessage, regardless of whether the application is drawing. For more information on feedback, see the comments section. See STARTUPINFO.


FN_STARTF_FORCEONFEEDBACK
STARTF_FORCEONFEEDBACK  0x00000040  winbase.h


STARTF_SCREENSAVER

If specified, the system will treat this application as a screen saver. See STARTUPINFO.


STARTF_USECOUNTCHARS
STARTF_USECOUNTCHARS  0x00000008  winbase.h

If not specified, the dwXCountChars and dwYCountChars fields are ignored. See STARTUPINFO.


FN_STARTF_USECOUNTCHARS
STARTF_USECOUNTCHARS  0x00000008  winbase.h


STARTF_USEFILLATTRIBUTE
STARTF_USEFILLATTRIBUTE  0x00000010  winbase.h

If not specified, the dwFillAttribute field is ignored. See STARTUPINFO.


FN_STARTF_USEFILLATTRIBUTE
STARTF_USEFILLATTRIBUTE  0x00000010  winbase.h


STARTF_USEPOSITION
STARTF_USEPOSITION  0x00000004  winbase.h

If not specified, the dwX and dwY fields are ignored. See STARTUPINFO.


FN_STARTF_USEPOSITION
STARTF_USEPOSITION  0x00000004  winbase.h


STARTF_USESHOWWINDOW
STARTF_USESHOWWINDOW  0x00000001  winbase.h

If not specified, the wShowWindow field is ignored. See STARTUPINFO.


FN_STARTF_USESHOWWINDOW
STARTF_USESHOWWINDOW  0x00000001  winbase.h


STARTF_USESIZE
STARTF_USESIZE  0x00000002  winbase.h

If not specified, the dwXSize and dwYSize fields are ignored. See STARTUPINFO.


FN_STARTF_USESIZE
STARTF_USESIZE  0x00000002  winbase.h


STARTF_USESTDHANDLES

If not specified, the  hStdInput, hStdOutput, and hStdError fields are ignored. See STARTUPINFO


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. See CreateWindow.


STD_ERROR_HANDLE
STD_ERROR_HANDLE  (DWORD)-12  winbase.h

The standard error handle. See GetStdHandle.


FN_STD_ERROR_HANDLE
STD_ERROR_HANDLE  (DWORD)-12  winbase.h


STD_INPUT_HANDLE
STD_INPUT_HANDLE  (DWORD)-10  winbase.h

The standard input handle. See GetStdHandle.


FN_STD_INPUT_HANDLE
STD_INPUT_HANDLE  (DWORD)-10  winbase.h


STD_OUTPUT_HANDLE
STD_OUTPUT_HANDLE  (DWORD)-11  winbase.h

The standard output handle. See GetStdHandle.


FN_STD_OUTPUT_HANDLE
STD_OUTPUT_HANDLE  (DWORD)-11  winbase.h


STREAM_CONTAINS_SECURITY
STREAM_CONTAINS_SECURITY  0x0002  winbase.h

General attribute that stream contains security data. Allows stream to be ignored on cross OS restores. See WIN32_STREAM_ID.


FN_STREAM_CONTAINS_SECURITY
STREAM_CONTAINS_SECURITY  0x0002  winbase.h


STREAM_MODIFIED_WHEN_READ
STREAM_MODIFIED_WHEN_READ  0x0001  winbase.h

Attribute set if stream contains data which is modified when read. Allows the backup application to know that verification of data will fail. See WIN32_STREAM_ID.


FN_STREAM_MODIFIED_WHEN_READ
STREAM_MODIFIED_WHEN_READ  0x0001  winbase.h


SUBLANG_CHINESE_SIMPLIFIED
SUBLANG_CHINESE_SIMPLIFIED  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_CHINESE_SIMPLIFIED
SUBLANG_CHINESE_SIMPLIFIED  0x02  winnt.h


SUBLANG_CHINESE_TRADITIONAL
SUBLANG_CHINESE_TRADITIONAL  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_CHINESE_TRADITIONAL
SUBLANG_CHINESE_TRADITIONAL  0x01  winnt.h


SUBLANG_DEFAULT
SUBLANG_DEFAULT  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_DEFAULT
SUBLANG_DEFAULT  0x01  winnt.h


SUBLANG_DUTCH
SUBLANG_DUTCH  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_DUTCH
SUBLANG_DUTCH  0x01  winnt.h


SUBLANG_DUTCH_BELGIAN
SUBLANG_DUTCH_BELGIAN  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_DUTCH_BELGIAN
SUBLANG_DUTCH_BELGIAN  0x02  winnt.h


SUBLANG_ENGLISH_AUS
SUBLANG_ENGLISH_AUS  0x03  winnt.h

See MAKELANGID.


FN_SUBLANG_ENGLISH_AUS
SUBLANG_ENGLISH_AUS  0x03  winnt.h


SUBLANG_ENGLISH_CAN
SUBLANG_ENGLISH_CAN  0x04  winnt.h

See MAKELANGID.


FN_SUBLANG_ENGLISH_CAN
SUBLANG_ENGLISH_CAN  0x04  winnt.h


SUBLANG_ENGLISH_EIRE

See MAKELANGID.


SUBLANG_ENGLISH_UK
SUBLANG_ENGLISH_UK  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_ENGLISH_UK
SUBLANG_ENGLISH_UK  0x02  winnt.h


SUBLANG_ENGLISH_US
SUBLANG_ENGLISH_US  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_ENGLISH_US
SUBLANG_ENGLISH_US  0x01  winnt.h


SUBLANG_FRENCH
SUBLANG_FRENCH  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_FRENCH
SUBLANG_FRENCH  0x01  winnt.h


SUBLANG_FRENCH_BELGIAN
SUBLANG_FRENCH_BELGIAN  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_FRENCH_BELGIAN
SUBLANG_FRENCH_BELGIAN  0x02  winnt.h


SUBLANG_FRENCH_CANADIAN
SUBLANG_FRENCH_CANADIAN  0x03  winnt.h

See MAKELANGID.


FN_SUBLANG_FRENCH_CANADIAN
SUBLANG_FRENCH_CANADIAN  0x03  winnt.h


SUBLANG_FRENCH_SWISS
SUBLANG_FRENCH_SWISS  0x04  winnt.h

See MAKELANGID.


FN_SUBLANG_FRENCH_SWISS
SUBLANG_FRENCH_SWISS  0x04  winnt.h


SUBLANG_GERMAN
SUBLANG_GERMAN  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_GERMAN
SUBLANG_GERMAN  0x01  winnt.h


SUBLANG_GERMAN_SWISS
SUBLANG_GERMAN_SWISS  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_GERMAN_SWISS
SUBLANG_GERMAN_SWISS  0x02  winnt.h


SUBLANG_ITALIAN
SUBLANG_ITALIAN  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_ITALIAN
SUBLANG_ITALIAN  0x01  winnt.h


SUBLANG_ITALIAN_SWISS
SUBLANG_ITALIAN_SWISS  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_ITALIAN_SWISS
SUBLANG_ITALIAN_SWISS  0x02  winnt.h


SUBLANG_NEUTRAL
SUBLANG_NEUTRAL  0x00  winnt.h

See MAKELANGID.


FN_SUBLANG_NEUTRAL
SUBLANG_NEUTRAL  0x00  winnt.h


SUBLANG_NORWEGIAN_BOKMAL
SUBLANG_NORWEGIAN_BOKMAL  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_NORWEGIAN_BOKMAL
SUBLANG_NORWEGIAN_BOKMAL  0x01  winnt.h


SUBLANG_NORWEGIAN_NYNORSK
SUBLANG_NORWEGIAN_NYNORSK  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_NORWEGIAN_NYNORSK
SUBLANG_NORWEGIAN_NYNORSK  0x02  winnt.h


SUBLANG_PORTUGUESE
SUBLANG_PORTUGUESE  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_PORTUGUESE
SUBLANG_PORTUGUESE  0x02  winnt.h


SUBLANG_PORTUGUESE_BRAZILIAN
SUBLANG_PORTUGUESE_BRAZILIAN  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_PORTUGUESE_BRAZILIAN
SUBLANG_PORTUGUESE_BRAZILIAN  0x01  winnt.h


SUBLANG_SERBO_CROATIAN_CYRILLIC
SUBLANG_SERBO_CROATIAN_CYRILLIC  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_SERBO_CROATIAN_CYRILLIC
SUBLANG_SERBO_CROATIAN_CYRILLIC  0x02  winnt.h


SUBLANG_SERBO_CROATIAN_LATIN
SUBLANG_SERBO_CROATIAN_LATIN  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_SERBO_CROATIAN_LATIN
SUBLANG_SERBO_CROATIAN_LATIN  0x01  winnt.h


SUBLANG_SPANISH
SUBLANG_SPANISH  0x01  winnt.h

See MAKELANGID.


FN_SUBLANG_SPANISH
SUBLANG_SPANISH  0x01  winnt.h


SUBLANG_SPANISH_MEXICAN
SUBLANG_SPANISH_MEXICAN  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_SPANISH_MEXICAN
SUBLANG_SPANISH_MEXICAN  0x02  winnt.h


SUBLANG_SPANISH_MODERN
SUBLANG_SPANISH_MODERN  0x03  winnt.h

See MAKELANGID.


FN_SUBLANG_SPANISH_MODERN
SUBLANG_SPANISH_MODERN  0x03  winnt.h


SUBLANG_SYS_DEFAULT
SUBLANG_SYS_DEFAULT  0x02  winnt.h

See MAKELANGID.


FN_SUBLANG_SYS_DEFAULT
SUBLANG_SYS_DEFAULT  0x02  winnt.h


SUCCESSFUL_ACCESS_ACE_FLAG
SUCCESSFUL_ACCESS_ACE_FLAG  (0x40)  winnt.h

Used with system-audit and system-alarm ACEs to indicate that a message is generated for successful access attempts. See ACE_HEADER.


FN_SUCCESSFUL_ACCESS_ACE_FLAG
SUCCESSFUL_ACCESS_ACE_FLAG  (0x40)  winnt.h


SW_ERASE
SW_ERASE  0x0004  winuser.h

When specified with SW_INVALIDATE, this flag erases the newly invalidated region by sending a WM_ERASEBKGND message to the window. See ScrollWindowEx.


FN_SW_ERASE
SW_ERASE  0x0004  winuser.h


SW_HIDE
SW_HIDE  0  winuser.h

Hides the window and passes activation to another window. See ShowWindow, HELPWININFO.


FN_SW_HIDE
SW_HIDE  0  winuser.h


SW_INVALIDATE
SW_INVALIDATE  0x0002  winuser.h

Invalidates the region identified by the hrgnUpdate parameter after scrolling. See ScrollWindowEx.


FN_SW_INVALIDATE
SW_INVALIDATE  0x0002  winuser.h


SW_MINIMIZE
SW_MINIMIZE  6  winuser.h

Minimizes the specified window and activates the top-level window in the z-order. See ShowWindow, HELPWININFO.


FN_SW_MINIMIZE
SW_MINIMIZE  6  winuser.h


SW_PARENTCLOSING
SW_PARENTCLOSING  1  winuser.h

The window's owner window is being minimized. See WM_SHOWWINDOW.


FN_SW_PARENTCLOSING
SW_PARENTCLOSING  1  winuser.h


SW_PARENTOPENING
SW_PARENTOPENING  3  winuser.h

The window's owner window is being restored. See WM_SHOWWINDOW.


FN_SW_PARENTOPENING
SW_PARENTOPENING  3  winuser.h


SW_RESTORE
SW_RESTORE  9  winuser.h

Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_SHOWNORMAL). See ShowWindow, HELPWININFO.


FN_SW_RESTORE
SW_RESTORE  9  winuser.h


SW_SCROLLCHILDREN
SW_SCROLLCHILDREN  0x0001  winuser.h

Scrolls all child windows that intersect the rectangle pointed to by the lprcScroll 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 lprcScroll rectangle, even if they do not move. See ScrollWindowEx.


FN_SW_SCROLLCHILDREN
SW_SCROLLCHILDREN  0x0001  winuser.h


SW_SHOW
SW_SHOW  5  winuser.h

Activates the window and displays it in its current size and position. However, if the first call by an application to ShowWindow has nCmdShow set to SW_SHOW, the system uses the startup information mentioned in the description of SW_SHOWDEFAULT. See the Comments section for additional information. See ShowWindow, HELPWININFO.


FN_SW_SHOW
SW_SHOW  5  winuser.h


SW_SHOWDEFAULT
SW_SHOWDEFAULT  10  winuser.h

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. See ShowWindow.


FN_SW_SHOWDEFAULT
SW_SHOWDEFAULT  10  winuser.h


SW_SHOWMAXIMIZED
SW_SHOWMAXIMIZED  3  winuser.h

Activates the window and displays it as a maximized window. See ShowWindow, HELPWININFO.


FN_SW_SHOWMAXIMIZED
SW_SHOWMAXIMIZED  3  winuser.h


SW_SHOWMINIMIZED
SW_SHOWMINIMIZED  2  winuser.h

Activates the window and displays it as a minimized window. See ShowWindow, HELPWININFO.


FN_SW_SHOWMINIMIZED
SW_SHOWMINIMIZED  2  winuser.h


SW_SHOWMINNOACTIVE
SW_SHOWMINNOACTIVE  7  winuser.h

Displays the window as a minimized window. The currently active window remains active. See ShowWindow, HELPWININFO.


FN_SW_SHOWMINNOACTIVE
SW_SHOWMINNOACTIVE  7  winuser.h


SW_SHOWNA
SW_SHOWNA  8  winuser.h

Displays the window in its current state. The window that is currently active remains active. See ShowWindow, HELPWININFO.


FN_SW_SHOWNA
SW_SHOWNA  8  winuser.h


SW_SHOWNOACTIVATE
SW_SHOWNOACTIVATE  4  winuser.h

Displays a window in its most recent size and position. The window that is currently active remains active. See ShowWindow, HELPWININFO.


FN_SW_SHOWNOACTIVATE
SW_SHOWNOACTIVATE  4  winuser.h


SW_SHOWNORMAL
SW_SHOWNORMAL  1  winuser.h

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). See ShowWindow, HELPWININFO.


FN_SW_SHOWNORMAL
SW_SHOWNORMAL  1  winuser.h


SW_SHOWSMOOTH

Specifies that a window is shown by first having it update in a bitmap, and then copying those bits directly to the screen. In many cases this will improve the perceived speed because copying from an off-screen bitmap to the screen is very fast, making the window "snap" onto the screen. See ShowWindow.


SWP_DRAWFRAME
SWP_DRAWFRAME  SWP_FRAMECHANGED  winuser.h

Draws a frame (defined in the window's class description) around the window. The window receives a WM_NCCALCSIZE message. See DeferWindowPos, SetWindowPos, WINDOWPOS.


FN_SWP_DRAWFRAME
SWP_DRAWFRAME  SWP_FRAMECHANGED  winuser.h


SWP_FRAMECHANGED
SWP_FRAMECHANGED  0x0020  winuser.h

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. See SetWindowPos.


FN_SWP_FRAMECHANGED
SWP_FRAMECHANGED  0x0020  winuser.h


SWP_HIDEWINDOW
SWP_HIDEWINDOW  0x0080  winuser.h

Hides the window. See DeferWindowPos, SetWindowPos, WINDOWPOS.


FN_SWP_HIDEWINDOW
SWP_HIDEWINDOW  0x0080  winuser.h


SWP_NOACTIVATE
SWP_NOACTIVATE  0x0010  winuser.h

Does not activate the window. See DeferWindowPos, SetWindowPos, WINDOWPOS.


FN_SWP_NOACTIVATE
SWP_NOACTIVATE  0x0010  winuser.h


SWP_NOCOPYBITS
SWP_NOCOPYBITS  0x0100  winuser.h

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. See SetWindowPos, WINDOWPOS.


FN_SWP_NOCOPYBITS
SWP_NOCOPYBITS  0x0100  winuser.h


SWP_NOMOVE
SWP_NOMOVE  0x0002  winuser.h

Retains current position (ignores the x and y parameters). See DeferWindowPos, SetWindowPos, WINDOWPOS.


FN_SWP_NOMOVE
SWP_NOMOVE  0x0002  winuser.h


SWP_NOOWNERZORDER
SWP_NOOWNERZORDER  0x0200  winuser.h

Does not change owner window's position in the Z order. See WINDOWPOS.


FN_SWP_NOOWNERZORDER
SWP_NOOWNERZORDER  0x0200  winuser.h


SWP_NOREDRAW
SWP_NOREDRAW  0x0008  winuser.h

Does not redraw changes. If this flag is set, no repainting of any kind occurs. This applies to the client area, the non-client area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of the moved window. When this flag is set, the application must explicitly invalidate or redraw any parts of the window and parent window that must be redrawn. See DeferWindowPos, SetWindowPos, WINDOWPOS.


FN_SWP_NOREDRAW
SWP_NOREDRAW  0x0008  winuser.h


SWP_NOREPOSITION
SWP_NOREPOSITION  SWP_NOOWNERZORDER  winuser.h

Same as SWP_NOOWNERZORDER See WINDOWPOS.


FN_SWP_NOREPOSITION
SWP_NOREPOSITION  SWP_NOOWNERZORDER  winuser.h


SWP_NOSIZE
SWP_NOSIZE  0x0001  winuser.h

Retains current size (ignores the cx and cy parameters). See DeferWindowPos, SetWindowPos, WINDOWPOS.


FN_SWP_NOSIZE
SWP_NOSIZE  0x0001  winuser.h


SWP_NOZORDER
SWP_NOZORDER  0x0004  winuser.h

Retains the current Z ordering (ignores the hwndInsertAfter parameter). See DeferWindowPos, SetWindowPos, WINDOWPOS.


FN_SWP_NOZORDER
SWP_NOZORDER  0x0004  winuser.h


SWP_SHOWWINDOW
SWP_SHOWWINDOW  0x0040  winuser.h

Displays the window. See DeferWindowPos, SetWindowPos, WINDOWPOS.


FN_SWP_SHOWWINDOW
SWP_SHOWWINDOW  0x0040  winuser.h


SYNCHRONIZE
SYNCHRONIZE  (0x00100000L)  winnt.h

Enables using the thread handle in any of the wait functions to wait for the thread to terminate. See DuplicateHandle.


FN_SYNCHRONIZE
SYNCHRONIZE  (0x00100000L)  winnt.h


SYSPAL_ERROR
SYSPAL_ERROR  0  wingdi.h

The given device-context is invalid or does not support a color palette. See GetSystemPaletteUse.


FN_SYSPAL_ERROR
SYSPAL_ERROR  0  wingdi.h


SYSPAL_NOSTATIC
SYSPAL_NOSTATIC  2  wingdi.h

System palette contains two static colors (black and white). See GetSystemPaletteUse, SetSystemPaletteUse.


FN_SYSPAL_NOSTATIC
SYSPAL_NOSTATIC  2  wingdi.h


SYSPAL_STATIC
SYSPAL_STATIC  1  wingdi.h

System palette contains static colors that will not change when an application realizes its logical palette. See GetSystemPaletteUse, SetSystemPaletteUse.


FN_SYSPAL_STATIC
SYSPAL_STATIC  1  wingdi.h


SYSTEM_ALARM_ACE_TYPE
SYSTEM_ALARM_ACE_TYPE  (0x3)  winnt.h

System-alarm ACE (defined by the SYSTEM_ALARM_ACE structure). This ACE type is not supported in the current version of Windows NT. See ACE_HEADER.


FN_SYSTEM_ALARM_ACE_TYPE
SYSTEM_ALARM_ACE_TYPE  (0x3)  winnt.h


SYSTEM_AUDIT_ACE_TYPE
SYSTEM_AUDIT_ACE_TYPE  (0x2)  winnt.h

System-audit ACE (defined by the SYSTEM_AUDIT_ACE structure) See ACE_HEADER.


FN_SYSTEM_AUDIT_ACE_TYPE
SYSTEM_AUDIT_ACE_TYPE  (0x2)  winnt.h


SYSTEM_FIXED_FONT
SYSTEM_FIXED_FONT  16  wingdi.h

Fixed-pitch system font used in Windows versions earlier than 3.0. This object is available for compatibility with earlier versions of Windows. See GetStockObject.


FN_SYSTEM_FIXED_FONT
SYSTEM_FIXED_FONT  16  wingdi.h


SYSTEM_FONT
SYSTEM_FONT  13  wingdi.h

System font. By default, Windows uses the system font to draw menus, dialog box controls, and other text. In Windows versions 3.0 and later, the system font is a variable-pitch font width; earlier versions of Windows use a fixed-pitch system font. See GetStockObject.


FN_SYSTEM_FONT
SYSTEM_FONT  13  wingdi.h


TA_BASELINE
TA_BASELINE  24  wingdi.h

The reference point will be on the base line of the text. See GetTextAlign, SetTextAlign.


FN_TA_BASELINE
TA_BASELINE  24  wingdi.h


TA_BOTTOM
TA_BOTTOM  8  wingdi.h

The reference point will be on the bottom edge of the bounding rectangle. See GetTextAlign, SetTextAlign.


FN_TA_BOTTOM
TA_BOTTOM  8  wingdi.h


TA_CENTER
TA_CENTER  6  wingdi.h

The reference point will be aligned horizontally with the center of the bounding rectangle. See GetTextAlign, SetTextAlign.


FN_TA_CENTER
TA_CENTER  6  wingdi.h


TA_LEFT
TA_LEFT  0  wingdi.h

The reference point will be on the left edge of the bounding rectangle. See GetTextAlign, SetTextAlign.


FN_TA_LEFT
TA_LEFT  0  wingdi.h


TA_NOUPDATECP
TA_NOUPDATECP  0  wingdi.h

The current position is not updated after each text output call. The reference point is passed to the text output function. See GetTextAlign, SetTextAlign.


FN_TA_NOUPDATECP
TA_NOUPDATECP  0  wingdi.h


TA_RIGHT
TA_RIGHT  2  wingdi.h

The reference point will be on the right edge of the bounding rectangle. See GetTextAlign, SetTextAlign.


FN_TA_RIGHT
TA_RIGHT  2  wingdi.h


TA_TOP
TA_TOP  0  wingdi.h

The reference point will be on the top edge of the bounding rectangle. See GetTextAlign, SetTextAlign.


FN_TA_TOP
TA_TOP  0  wingdi.h


TA_UPDATECP
TA_UPDATECP  1  wingdi.h

The current position is updated after each text output call. The current position is used as the reference point. See GetTextAlign, SetTextAlign.


FN_TA_UPDATECP
TA_UPDATECP  1  wingdi.h


TAPE_ABSOLUTE_BLOCK
TAPE_ABSOLUTE_BLOCK  1L  winnt.h

Moves the tape to the device-specific block address specified by OffsetLow and OffsetHigh. The Partition parameter is ignored. See SetTapePosition, TAPE_SET_POSITION.


FN_TAPE_ABSOLUTE_BLOCK
TAPE_ABSOLUTE_BLOCK  1L  winnt.h


TAPE_ABSOLUTE_BLOCK_IMMED

Same as TAPE_ABSOLUTE_BLOCK, but returns status as soon as the operation begins. See SetTapePosition, TAPE_SET_POSITION.


TAPE_ABSOLUTE_POSITION
TAPE_ABSOLUTE_POSITION  0L  winnt.h

Indicates that the position specified by OffsetLow and OffsetHigh is an absolute number of blocks from the beginning of the partition specified by Partition. See GetTapePosition, TAPE_GET_POSITION.


FN_TAPE_ABSOLUTE_POSITION
TAPE_ABSOLUTE_POSITION  0L  winnt.h


TAPE_DRIVE_ABS_BLK_IMMED
TAPE_DRIVE_ABS_BLK_IMMED  0x80002000  winnt.h

Device moves the tape to a device-specific block address and returns as soon as the move begins. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_ABS_BLK_IMMED
TAPE_DRIVE_ABS_BLK_IMMED  0x80002000  winnt.h


TAPE_DRIVE_ABSOLUTE_BLK
TAPE_DRIVE_ABSOLUTE_BLK  0x80001000  winnt.h

Device moves the tape to a device specific block address. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_ABSOLUTE_BLK
TAPE_DRIVE_ABSOLUTE_BLK  0x80001000  winnt.h


TAPE_DRIVE_COMPRESSION
TAPE_DRIVE_COMPRESSION  0x00020000  winnt.h

Device supports hardware data compression. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_COMPRESSION
TAPE_DRIVE_COMPRESSION  0x00020000  winnt.h


TAPE_DRIVE_ECC
TAPE_DRIVE_ECC  0x00010000  winnt.h

Device supports hardware error correction. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_ECC
TAPE_DRIVE_ECC  0x00010000  winnt.h


TAPE_DRIVE_END_OF_DATA
TAPE_DRIVE_END_OF_DATA  0x80010000  winnt.h

Device moves the tape to the end-of-data in a partition. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_END_OF_DATA
TAPE_DRIVE_END_OF_DATA  0x80010000  winnt.h


TAPE_DRIVE_ERASE_BOP_ONLY
TAPE_DRIVE_ERASE_BOP_ONLY  0x00000040  winnt.h

Device performs erase operation from the beginning-of-partition only. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_ERASE_BOP_ONLY
TAPE_DRIVE_ERASE_BOP_ONLY  0x00000040  winnt.h


TAPE_DRIVE_ERASE_LONG
TAPE_DRIVE_ERASE_LONG  0x00000020  winnt.h

Device performs long erase operation. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_ERASE_LONG
TAPE_DRIVE_ERASE_LONG  0x00000020  winnt.h


TAPE_DRIVE_ERASE_SHORT
TAPE_DRIVE_ERASE_SHORT  0x00000010  winnt.h

Device performs short erase operation. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_ERASE_SHORT
TAPE_DRIVE_ERASE_SHORT  0x00000010  winnt.h


TAPE_DRIVE_FILEMARKS
TAPE_DRIVE_FILEMARKS  0x80040000  winnt.h

Device moves the tape forward (or backward) a specified number of filemarks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_FILEMARKS
TAPE_DRIVE_FILEMARKS  0x80040000  winnt.h


TAPE_DRIVE_FIXED
TAPE_DRIVE_FIXED  0x00000001  winnt.h

Device creates fixed data partitions. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_FIXED
TAPE_DRIVE_FIXED  0x00000001  winnt.h


TAPE_DRIVE_FIXED_BLOCK
TAPE_DRIVE_FIXED_BLOCK  0x00000400  winnt.h

Device supports fixed-length block mode. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_FIXED_BLOCK
TAPE_DRIVE_FIXED_BLOCK  0x00000400  winnt.h


TAPE_DRIVE_GET_ABSOLUTE_BLK
TAPE_DRIVE_GET_ABSOLUTE_BLK  0x00100000  winnt.h

Device provides the current device-specific block address. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_GET_ABSOLUTE_BLK
TAPE_DRIVE_GET_ABSOLUTE_BLK  0x00100000  winnt.h


TAPE_DRIVE_GET_LOGICAL_BLK
TAPE_DRIVE_GET_LOGICAL_BLK  0x00200000  winnt.h

Device provides the current logical block address (and logical tape partition). See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_GET_LOGICAL_BLK
TAPE_DRIVE_GET_LOGICAL_BLK  0x00200000  winnt.h


TAPE_DRIVE_INITIATOR
TAPE_DRIVE_INITIATOR  0x00000004  winnt.h

Device creates initiator-defined partitions. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_INITIATOR
TAPE_DRIVE_INITIATOR  0x00000004  winnt.h


TAPE_DRIVE_LOAD_UNLOAD
TAPE_DRIVE_LOAD_UNLOAD  0x80000001  winnt.h

Device enables and disables the device for further operations. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_LOAD_UNLOAD
TAPE_DRIVE_LOAD_UNLOAD  0x80000001  winnt.h


TAPE_DRIVE_LOCK_UNLOCK
TAPE_DRIVE_LOCK_UNLOCK  0x80000004  winnt.h

Device enables and disables the tape ejection mechanism. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_LOCK_UNLOCK
TAPE_DRIVE_LOCK_UNLOCK  0x80000004  winnt.h


TAPE_DRIVE_LOG_BLK_IMMED
TAPE_DRIVE_LOG_BLK_IMMED  0x80008000  winnt.h

Device moves the tape to a logical block address in a partition and returns as soon as the move begins. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_LOG_BLK_IMMED
TAPE_DRIVE_LOG_BLK_IMMED  0x80008000  winnt.h


TAPE_DRIVE_LOGICAL_BLK
TAPE_DRIVE_LOGICAL_BLK  0x80004000  winnt.h

Device moves the tape to a logical block address in a partition. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_LOGICAL_BLK
TAPE_DRIVE_LOGICAL_BLK  0x80004000  winnt.h


TAPE_DRIVE_PADDING
TAPE_DRIVE_PADDING  0x00040000  winnt.h

Device supports data padding. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_PADDING
TAPE_DRIVE_PADDING  0x00040000  winnt.h


TAPE_DRIVE_RELATIVE_BLKS
TAPE_DRIVE_RELATIVE_BLKS  0x80020000  winnt.h

Device moves the tape forward (or backward) a specified number of blocks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_RELATIVE_BLKS
TAPE_DRIVE_RELATIVE_BLKS  0x80020000  winnt.h


TAPE_DRIVE_REPORT_SMKS
TAPE_DRIVE_REPORT_SMKS  0x00080000  winnt.h

Device supports reporting setmarks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_REPORT_SMKS
TAPE_DRIVE_REPORT_SMKS  0x00080000  winnt.h


TAPE_DRIVE_REVERSE_POSITION
TAPE_DRIVE_REVERSE_POSITION  0x80400000  winnt.h

Device moves the tape over blocks, filemarks, or setmarks in the reverse direction. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_REVERSE_POSITION
TAPE_DRIVE_REVERSE_POSITION  0x80400000  winnt.h


TAPE_DRIVE_SELECT
TAPE_DRIVE_SELECT  0x00000002  winnt.h

Device creates select data partitions. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_SELECT
TAPE_DRIVE_SELECT  0x00000002  winnt.h


TAPE_DRIVE_SEQUENTIAL_FMKS
TAPE_DRIVE_SEQUENTIAL_FMKS  0x80080000  winnt.h

Device moves the tape forward (or backward) to the first occurrence of a specified number of consecutive filemarks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_SEQUENTIAL_FMKS
TAPE_DRIVE_SEQUENTIAL_FMKS  0x80080000  winnt.h


TAPE_DRIVE_SEQUENTIAL_SMKS
TAPE_DRIVE_SEQUENTIAL_SMKS  0x80200000  winnt.h

Device moves the tape forward (or reverse) to the first occurrence of a specified number of consecutive setmarks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_SEQUENTIAL_SMKS
TAPE_DRIVE_SEQUENTIAL_SMKS  0x80200000  winnt.h


TAPE_DRIVE_SET_BLOCK_SIZE
TAPE_DRIVE_SET_BLOCK_SIZE  0x80000010  winnt.h

Device supports setting the size of a fixed-length logical block or setting the variable-length block mode. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_SET_BLOCK_SIZE
TAPE_DRIVE_SET_BLOCK_SIZE  0x80000010  winnt.h


TAPE_DRIVE_SET_COMPRESSION
TAPE_DRIVE_SET_COMPRESSION  0x80000200  winnt.h

Device enables and disables hardware data compression. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_SET_COMPRESSION
TAPE_DRIVE_SET_COMPRESSION  0x80000200  winnt.h


TAPE_DRIVE_SET_ECC
TAPE_DRIVE_SET_ECC  0x80000100  winnt.h

Device enables and disables hardware error correction. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_SET_ECC
TAPE_DRIVE_SET_ECC  0x80000100  winnt.h


TAPE_DRIVE_SET_PADDING
TAPE_DRIVE_SET_PADDING  0x80000400  winnt.h

Device enables and disables data padding. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_SET_PADDING
TAPE_DRIVE_SET_PADDING  0x80000400  winnt.h


TAPE_DRIVE_SET_REPORT_SMKS
TAPE_DRIVE_SET_REPORT_SMKS  0x80000800  winnt.h

Device enables and disables the reporting of setmarks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_SET_REPORT_SMKS
TAPE_DRIVE_SET_REPORT_SMKS  0x80000800  winnt.h


TAPE_DRIVE_SETMARKS
TAPE_DRIVE_SETMARKS  0x80100000  winnt.h

Device moves the tape forward (or reverse) a specified number of setmarks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_SETMARKS
TAPE_DRIVE_SETMARKS  0x80100000  winnt.h


TAPE_DRIVE_TAPE_CAPACITY
TAPE_DRIVE_TAPE_CAPACITY  0x00000100  winnt.h

Device returns the maximum capacity of the tape. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_TAPE_CAPACITY
TAPE_DRIVE_TAPE_CAPACITY  0x00000100  winnt.h


TAPE_DRIVE_TAPE_REMAINING
TAPE_DRIVE_TAPE_REMAINING  0x00000200  winnt.h

Device returns the remaining capacity of the tape. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_TAPE_REMAINING
TAPE_DRIVE_TAPE_REMAINING  0x00000200  winnt.h


TAPE_DRIVE_TENSION
TAPE_DRIVE_TENSION  0x80000002  winnt.h

Device supports adjusting the tape tension. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_TENSION
TAPE_DRIVE_TENSION  0x80000002  winnt.h


TAPE_DRIVE_VARIABLE_BLOCK
TAPE_DRIVE_VARIABLE_BLOCK  0x00000800  winnt.h

Device supports variable-length block mode. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_VARIABLE_BLOCK
TAPE_DRIVE_VARIABLE_BLOCK  0x00000800  winnt.h


TAPE_DRIVE_WRITE_FILEMARKS
TAPE_DRIVE_WRITE_FILEMARKS  0x82000000  winnt.h

Device writes filemarks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_WRITE_FILEMARKS
TAPE_DRIVE_WRITE_FILEMARKS  0x82000000  winnt.h


TAPE_DRIVE_WRITE_LONG_FMKS
TAPE_DRIVE_WRITE_LONG_FMKS  0x88000000  winnt.h

Device writes long filemarks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_WRITE_LONG_FMKS
TAPE_DRIVE_WRITE_LONG_FMKS  0x88000000  winnt.h


TAPE_DRIVE_WRITE_PROTECT
TAPE_DRIVE_WRITE_PROTECT  0x00001000  winnt.h

Device returns error if the tape is write-enabled or write-protected. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_WRITE_PROTECT
TAPE_DRIVE_WRITE_PROTECT  0x00001000  winnt.h


TAPE_DRIVE_WRITE_SETMARKS
TAPE_DRIVE_WRITE_SETMARKS  0x81000000  winnt.h

Device writes setmarks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_WRITE_SETMARKS
TAPE_DRIVE_WRITE_SETMARKS  0x81000000  winnt.h


TAPE_DRIVE_WRITE_SHORT_FMKS
TAPE_DRIVE_WRITE_SHORT_FMKS  0x84000000  winnt.h

Device writes short filemarks. See TAPE_GET_DRIVE_PARAMETERS.


FN_TAPE_DRIVE_WRITE_SHORT_FMKS
TAPE_DRIVE_WRITE_SHORT_FMKS  0x84000000  winnt.h


TAPE_ERASE_LONG
TAPE_ERASE_LONG  1L  winnt.h

Erases the tape from the current position to the end of the current partition. See EraseTape, TAPE_ERASE.


FN_TAPE_ERASE_LONG
TAPE_ERASE_LONG  1L  winnt.h


TAPE_ERASE_LONG_IMMED

Erases the tape from the current position to the end of the current partition and returns status as soon as the operation begins. See EraseTape, TAPE_ERASE.


TAPE_ERASE_SHORT
TAPE_ERASE_SHORT  0L  winnt.h

Writes an erase gap or end-of-recorded data marker at the current position. See EraseTape, TAPE_ERASE.


FN_TAPE_ERASE_SHORT
TAPE_ERASE_SHORT  0L  winnt.h


TAPE_ERASE_SHORT_IMMED

Writes an erase gap or end-of-recorded data marker at the current position and returns status as soon as the operation begins. See EraseTape, TAPE_ERASE.


TAPE_FILEMARKS
TAPE_FILEMARKS  1L  winnt.h

Writes the number of filemarks specified by dwTapemarkCount. See WriteTapemark.


FN_TAPE_FILEMARKS
TAPE_FILEMARKS  1L  winnt.h


TAPE_FILEMARKS_IMMED

Same as TAPE_FILEMARKS, but returns status as soon as the operation begins. See WriteTapemark.


TAPE_FIXED_PARTITIONS
TAPE_FIXED_PARTITIONS  0L  winnt.h

Partitions the tape based on the device's default definition of partitions. The dwCount and dwSize parameters are ignored. See CreateTapePartition.


FN_TAPE_FIXED_PARTITIONS
TAPE_FIXED_PARTITIONS  0L  winnt.h


TAPE_INITIATOR_PARTITIONS
TAPE_INITIATOR_PARTITIONS  2L  winnt.h

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. See CreateTapePartition.


FN_TAPE_INITIATOR_PARTITIONS
TAPE_INITIATOR_PARTITIONS  2L  winnt.h


TAPE_LOAD
TAPE_LOAD  0L  winnt.h

Loads the tape and moves the tape to the beginning. See PrepareTape.


FN_TAPE_LOAD
TAPE_LOAD  0L  winnt.h


TAPE_LOAD_IMMED

Same as TAPE_LOAD, but returns status as soon as the operation begins. See PrepareTape.


TAPE_LOCK
TAPE_LOCK  3L  winnt.h

Locks the tape ejection mechanism. This prevents the tape from being accidentally ejected. See PrepareTape, TAPE_PREPARE.


FN_TAPE_LOCK
TAPE_LOCK  3L  winnt.h


TAPE_LOGICAL_BLOCK
TAPE_LOGICAL_BLOCK  2L  winnt.h

Moves the tape to the block address specified by OffsetLow and OffsetHigh in the partition specified by Partition. See SetTapePosition, TAPE_SET_POSITION.


FN_TAPE_LOGICAL_BLOCK
TAPE_LOGICAL_BLOCK  2L  winnt.h


TAPE_LOGICAL_BLOCK_IMMED

Same as TAPE_LOGICAL_BLOCK, but returns status as soon as the operation begins. See SetTapePosition, TAPE_SET_POSITION.


TAPE_LOGICAL_POSITION
TAPE_LOGICAL_POSITION  1L  winnt.h

Indicates that the position specified by OffsetLow and OffsetHigh is relative to the current position in the partition specified by Partition. See GetTapePosition, TAPE_GET_POSITION.


FN_TAPE_LOGICAL_POSITION
TAPE_LOGICAL_POSITION  1L  winnt.h


TAPE_LONG_FILEMARKS
TAPE_LONG_FILEMARKS  3L  winnt.h

Write long filemarks. See WriteTapemark, TAPE_WRITE_MARKS.


FN_TAPE_LONG_FILEMARKS
TAPE_LONG_FILEMARKS  3L  winnt.h


TAPE_LONG_FILEMARKS_IMMED

Same as TAPE_LONG_FILEMARKS, but returns status as soon as the operation begins. See WriteTapemark.


TAPE_PARTITION_FIXED

Indicates that the partition parameters are fixed by the device. See TAPE_CREATE_PARTITION.


TAPE_PARTITION_INITIATOR

Indicates that the number of partitions is specified by Count and the partition sizes are specified in the Size array. See TAPE_CREATE_PARTITION.


TAPE_PARTITION_SELECT

Indicates that the number of partitions is specified by Count and the partition sizes are defined by the device. See TAPE_CREATE_PARTITION.


TAPE_REWIND
TAPE_REWIND  0L  winnt.h

Moves the tape to the beginning of the current partition. The Partition, OffsetLow, and OffsetHigh parameters are ignored. See SetTapePosition, TAPE_SET_POSITION.


FN_TAPE_REWIND
TAPE_REWIND  0L  winnt.h


TAPE_REWIND_IMMED

Same as TAPE_REWIND, but returns status as soon as the operation begins. See SetTapePosition, TAPE_SET_POSITION.


TAPE_SELECT_PARTITIONS
TAPE_SELECT_PARTITIONS  1L  winnt.h

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. Refer to your tape device's documentation for more specific information. See CreateTapePartition.


FN_TAPE_SELECT_PARTITIONS
TAPE_SELECT_PARTITIONS  1L  winnt.h


TAPE_SEQUENTIAL_FILEMARKS

Write sequential filemarks. See TAPE_WRITE_MARKS.


TAPE_SETMARKS
TAPE_SETMARKS  0L  winnt.h

Write setmarks. See WriteTapemark, TAPE_WRITE_MARKS.


FN_TAPE_SETMARKS
TAPE_SETMARKS  0L  winnt.h


TAPE_SETMARKS_IMMED

Same as TAPE_SETMARKS, but returns status as soon as the operation begins. See WriteTapemark.


TAPE_SHORT_FILEMARKS
TAPE_SHORT_FILEMARKS  2L  winnt.h

Write short filemarks. See WriteTapemark, TAPE_WRITE_MARKS.


FN_TAPE_SHORT_FILEMARKS
TAPE_SHORT_FILEMARKS  2L  winnt.h


TAPE_SHORT_FILEMARKS_IMMED

Same as TAPE_SHORT_FILEMARKS, but returns status as soon as the operation begins. See WriteTapemark.


TAPE_SPACE_END_OF_DATA
TAPE_SPACE_END_OF_DATA  4L  winnt.h

Moves the tape to the end of the data on the partition specified by Partition. See SetTapePosition, TAPE_SET_POSITION.


FN_TAPE_SPACE_END_OF_DATA
TAPE_SPACE_END_OF_DATA  4L  winnt.h


TAPE_SPACE_FILEMARKS
TAPE_SPACE_FILEMARKS  6L  winnt.h

Moves the tape forward or reverse the number of filemarks specified by OffsetLow and OffsetHigh in the current partition. The Partition parameter is ignored. See SetTapePosition, TAPE_SET_POSITION.


FN_TAPE_SPACE_FILEMARKS
TAPE_SPACE_FILEMARKS  6L  winnt.h


TAPE_SPACE_RELATIVE_BLOCKS
TAPE_SPACE_RELATIVE_BLOCKS  5L  winnt.h

Moves the tape forward or reverse the number of blocks specified by OffsetLow and OffsetHigh in the current partition. The Partition parameter is ignored. See SetTapePosition, TAPE_SET_POSITION.


FN_TAPE_SPACE_RELATIVE_BLOCKS
TAPE_SPACE_RELATIVE_BLOCKS  5L  winnt.h


TAPE_SPACE_SEQUENTIAL_FMKS
TAPE_SPACE_SEQUENTIAL_FMKS  7L  winnt.h

Moves the tape forward or reverse 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. See SetTapePosition, TAPE_SET_POSITION.


FN_TAPE_SPACE_SEQUENTIAL_FMKS
TAPE_SPACE_SEQUENTIAL_FMKS  7L  winnt.h


TAPE_SPACE_SEQUENTIAL_SMKS
TAPE_SPACE_SEQUENTIAL_SMKS  9L  winnt.h

Moves the tape forward or reverse to the first occurrence of 'n' setmarks in the current partition, where 'n' is the number specified by OffsetLow and OffsetHigh. The Partition parameter is ignored. See SetTapePosition, TAPE_SET_POSITION.


FN_TAPE_SPACE_SEQUENTIAL_SMKS
TAPE_SPACE_SEQUENTIAL_SMKS  9L  winnt.h


TAPE_SPACE_SETMARKS
TAPE_SPACE_SETMARKS  8L  winnt.h

Moves the tape forward or reverse the number of setmarks specified by OffsetLow and OffsetHigh in the current partition. The Partition parameter is ignored. See SetTapePosition, TAPE_SET_POSITION.


FN_TAPE_SPACE_SETMARKS
TAPE_SPACE_SETMARKS  8L  winnt.h


TAPE_TENSION
TAPE_TENSION  2L  winnt.h

Move to end of the tape and rewind to the beginning of the tape. This value is ignored if the tape device does not support this action. See PrepareTape, TAPE_PREPARE.


FN_TAPE_TENSION
TAPE_TENSION  2L  winnt.h


TAPE_TENSION_IMMED

Same as TAPE_TENSION_IMMED, but returns status as soon as the operation begins. See PrepareTape.


TAPE_UNLOAD
TAPE_UNLOAD  1L  winnt.h

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. See PrepareTape, TAPE_PREPARE.


FN_TAPE_UNLOAD
TAPE_UNLOAD  1L  winnt.h


TAPE_UNLOAD_IMMED

Rewind and unload the tape, but return as soon as the rewind operation begins. See PrepareTape, TAPE_PREPARE.


TAPE_UNLOCK
TAPE_UNLOCK  4L  winnt.h

Unlocks the tape ejection mechanism. See PrepareTape, TAPE_PREPARE.


FN_TAPE_UNLOCK
TAPE_UNLOCK  4L  winnt.h


TECHNOLOGY
TECHNOLOGY  2  wingdi.h

Device technology. See GetDeviceCaps.


FN_TECHNOLOGY
TECHNOLOGY  2  wingdi.h


TEXTCAPS
TEXTCAPS  34  wingdi.h

A bitmask that indicates the text capabilities of the device. See GetDeviceCaps.


FN_TEXTCAPS
TEXTCAPS  34  wingdi.h


THREAD_ALL_ACCESS
THREAD_ALL_ACCESS  (STANDARD_RIGHTS_REQUIRED | SYNCHRONIZE | 0x3FF)  winnt.h

Specifies all possible access flags for the thread object. See DuplicateHandle.


FN_THREAD_ALL_ACCESS
THREAD_ALL_ACCESS  (STANDARD_RIGHTS_REQUIRED | SYNCHRONIZE | 0x3FF)  winnt.h


THREAD_GET_CONTEXT
THREAD_GET_CONTEXT  (0x0008)  winnt.h

Enables using the thread handle in the GetThreadContext function to read the thread's context. See DuplicateHandle.


FN_THREAD_GET_CONTEXT
THREAD_GET_CONTEXT  (0x0008)  winnt.h


THREAD_QUERY_INFORMATION
THREAD_QUERY_INFORMATION  (0x0040)  winnt.h

Enables using the thread handle in the GetExitCodeThread, GetThreadPriority, and GetThreadSelectorEntry functions to read information from the thread object. See DuplicateHandle.


FN_THREAD_QUERY_INFORMATION
THREAD_QUERY_INFORMATION  (0x0040)  winnt.h


THREAD_SET_CONTEXT
THREAD_SET_CONTEXT  (0x0010)  winnt.h

Enables using the thread handle in the SetThreadContext function to set the thread's context. See DuplicateHandle.


FN_THREAD_SET_CONTEXT
THREAD_SET_CONTEXT  (0x0010)  winnt.h


THREAD_SET_INFORMATION
THREAD_SET_INFORMATION  (0x0020)  winnt.h

Enables using the thread handle in the SetThreadPriority function to set the thread's priority. See DuplicateHandle.


FN_THREAD_SET_INFORMATION
THREAD_SET_INFORMATION  (0x0020)  winnt.h


THREAD_SUSPEND_RESUME
THREAD_SUSPEND_RESUME  (0x0002)  winnt.h

Enables using the thread handle in the SuspendThread or ResumeThread functions to suspend or resume a thread. See DuplicateHandle.


FN_THREAD_SUSPEND_RESUME
THREAD_SUSPEND_RESUME  (0x0002)  winnt.h


THREAD_TERMINATE
THREAD_TERMINATE  (0x0001)  winnt.h

Enables using the thread handle in the TerminateThread function to terminate the thread. See DuplicateHandle.


FN_THREAD_TERMINATE
THREAD_TERMINATE  (0x0001)  winnt.h


TIME_BYTES
TIME_BYTES  0x0004  mmsystem.h

Current byte offset. See MMTIME.


FN_TIME_BYTES
TIME_BYTES  0x0004  mmsystem.h


TIME_MIDI
TIME_MIDI  0x0010  mmsystem.h

MIDI time. See MMTIME.


FN_TIME_MIDI
TIME_MIDI  0x0010  mmsystem.h


TIME_MS
TIME_MS  0x0001  mmsystem.h

Time counted in milliseconds. See MMTIME.


FN_TIME_MS
TIME_MS  0x0001  mmsystem.h


TIME_ONESHOT
TIME_ONESHOT  0  mmsystem.h

Event occurs once, after wPeriod milliseconds. See timeSetEvent.


FN_TIME_ONESHOT
TIME_ONESHOT  0  mmsystem.h


TIME_PERIODIC
TIME_PERIODIC  1  mmsystem.h

Event occurs every wPeriod milliseconds. See timeSetEvent.


FN_TIME_PERIODIC
TIME_PERIODIC  1  mmsystem.h


TIME_SAMPLES
TIME_SAMPLES  0x0002  mmsystem.h

Number of wave samples. See MMTIME.


FN_TIME_SAMPLES
TIME_SAMPLES  0x0002  mmsystem.h


TIME_SMPTE
TIME_SMPTE  0x0008  mmsystem.h

SMPTE time. See MMTIME.


FN_TIME_SMPTE
TIME_SMPTE  0x0008  mmsystem.h


TIME_ZONE_ID_DAYLIGHT
TIME_ZONE_ID_DAYLIGHT  2  winnt.h

The system is operating in the range covered by the DaylightDate member of the structure at lptzi. See GetTimeZoneInformation.


FN_TIME_ZONE_ID_DAYLIGHT
TIME_ZONE_ID_DAYLIGHT  2  winnt.h


TIME_ZONE_ID_STANDARD
TIME_ZONE_ID_STANDARD  1  winnt.h

The system is operating in the range covered by the StandardDate member of the structure at lptzi. See GetTimeZoneInformation.


FN_TIME_ZONE_ID_STANDARD
TIME_ZONE_ID_STANDARD  1  winnt.h


TIME_ZONE_ID_UNKNOWN
TIME_ZONE_ID_UNKNOWN  0  winnt.h

The system cannot determine the current time zone. This is usually because a previous call to SetTimeZoneInformation supplied only the Bias (and no transition dates). See GetTimeZoneInformation.


FN_TIME_ZONE_ID_UNKNOWN
TIME_ZONE_ID_UNKNOWN  0  winnt.h


TOKEN_ADJUST_DEFAULT
TOKEN_ADJUST_DEFAULT  (0x0080)  winnt.h

Changes the default access-control list, primary group, or owner of an access token. See OpenProcessToken.


FN_TOKEN_ADJUST_DEFAULT
TOKEN_ADJUST_DEFAULT  (0x0080)  winnt.h


TOKEN_ADJUST_GROUPS
TOKEN_ADJUST_GROUPS  (0x0040)  winnt.h

Changes the groups specified in an access token. See OpenProcessToken.


FN_TOKEN_ADJUST_GROUPS
TOKEN_ADJUST_GROUPS  (0x0040)  winnt.h


TOKEN_ADJUST_PRIVILEGES
TOKEN_ADJUST_PRIVILEGES  (0x0020)  winnt.h

Changes the privileges specified in an access token. See OpenProcessToken.


FN_TOKEN_ADJUST_PRIVILEGES
TOKEN_ADJUST_PRIVILEGES  (0x0020)  winnt.h


TOKEN_ALL_ACCESS
TOKEN_ALL_ACCESS  (STANDARD_RIGHTS_REQUIRED | TOKEN_ASSIGN_PRIMARY | TOKEN_DUPLICATE | TOKEN_IMPERSONATE | TOKEN_QUERY | TOKEN_QUERY_SOURCE | TOKEN_ADJUST_PRIVILEGES | TOKEN_ADJUST_GROUPS | TOKEN_ADJUST_DEFAULT)  winnt.h

Combines the STANDARD_RIGHTS_REQUIRED standard access rights and all individual access rights for tokens. See OpenProcessToken.


FN_TOKEN_ALL_ACCESS
TOKEN_ALL_ACCESS  (STANDARD_RIGHTS_REQUIRED | TOKEN_ASSIGN_PRIMARY | TOKEN_DUPLICATE | TOKEN_IMPERSONATE | TOKEN_QUERY | TOKEN_QUERY_SOURCE | TOKEN_ADJUST_PRIVILEGES | TOKEN_ADJUST_GROUPS | TOKEN_ADJUST_DEFAULT)  winnt.h


TOKEN_ASSIGN_PRIMARY
TOKEN_ASSIGN_PRIMARY  (0x0001)  winnt.h

Assigns a primary group in an access token. See OpenProcessToken.


FN_TOKEN_ASSIGN_PRIMARY
TOKEN_ASSIGN_PRIMARY  (0x0001)  winnt.h


TOKEN_DUPLICATE
TOKEN_DUPLICATE  (0x0002)  winnt.h

Duplicates an access token. See OpenProcessToken.


FN_TOKEN_DUPLICATE
TOKEN_DUPLICATE  (0x0002)  winnt.h


TOKEN_EXECUTE
TOKEN_EXECUTE  (STANDARD_RIGHTS_EXECUTE)  winnt.h

Combines the STANDARD_RIGHTS_EXECUTE standard access rights and the TOKEN_IMPERSONATE access right. See OpenProcessToken.


FN_TOKEN_EXECUTE
TOKEN_EXECUTE  (STANDARD_RIGHTS_EXECUTE)  winnt.h


TOKEN_IMPERSONATE
TOKEN_IMPERSONATE  (0x0004)  winnt.h

Creates an impersonation access token. See OpenProcessToken.


FN_TOKEN_IMPERSONATE
TOKEN_IMPERSONATE  (0x0004)  winnt.h


TOKEN_QUERY
TOKEN_QUERY  (0x0008)  winnt.h

Queries the contents of an access token. See OpenProcessToken.


FN_TOKEN_QUERY
TOKEN_QUERY  (0x0008)  winnt.h


TOKEN_QUERY_SOURCE
TOKEN_QUERY_SOURCE  (0x0010)  winnt.h

Queries the source of an access token. See OpenProcessToken.


FN_TOKEN_QUERY_SOURCE
TOKEN_QUERY_SOURCE  (0x0010)  winnt.h


TOKEN_READ
TOKEN_READ  (STANDARD_RIGHTS_READ | TOKEN_QUERY)  winnt.h

Combines the STANDARD_RIGHTS_READ standard access rights and the TOKEN_QUERY access right. See OpenProcessToken.


FN_TOKEN_READ
TOKEN_READ  (STANDARD_RIGHTS_READ | TOKEN_QUERY)  winnt.h


TOKEN_WRITE
TOKEN_WRITE  (STANDARD_RIGHTS_WRITE | TOKEN_ADJUST_PRIVILEGES | TOKEN_ADJUST_GROUPS | TOKEN_ADJUST_DEFAULT)  winnt.h

Combines the STANDARD_RIGHTS_WRITE standard access rights and the TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS, and TOKEN_ADJUST_DEFAULT access rights. See OpenProcessToken.


FN_TOKEN_WRITE
TOKEN_WRITE  (STANDARD_RIGHTS_WRITE | TOKEN_ADJUST_PRIVILEGES | TOKEN_ADJUST_GROUPS | TOKEN_ADJUST_DEFAULT)  winnt.h


TPM_CENTERALIGN
TPM_CENTERALIGN  0x0004L  winuser.h

Centers the pop-up menu horizontally relative to the coordinate specified by the x parameter. See TrackPopupMenu.


FN_TPM_CENTERALIGN
TPM_CENTERALIGN  0x0004L  winuser.h


TPM_LEFTALIGN
TPM_LEFTALIGN  0x0000L  winuser.h

Positions the pop-up menu so that its left side is aligned with the coordinate specified by the x parameter. See TrackPopupMenu.


FN_TPM_LEFTALIGN
TPM_LEFTALIGN  0x0000L  winuser.h


TPM_LEFTBUTTON
TPM_LEFTBUTTON  0x0000L  winuser.h

Causes the pop-up menu to track the left mouse button. See TrackPopupMenu.


FN_TPM_LEFTBUTTON
TPM_LEFTBUTTON  0x0000L  winuser.h


TPM_RIGHTALIGN
TPM_RIGHTALIGN  0x0008L  winuser.h

Positions the pop-up menu so that its right side is aligned with the coordinate specified by the x parameter. See TrackPopupMenu.


FN_TPM_RIGHTALIGN
TPM_RIGHTALIGN  0x0008L  winuser.h


TPM_RIGHTBUTTON
TPM_RIGHTBUTTON  0x0002L  winuser.h

Causes the pop-up menu to track the right mouse button. See TrackPopupMenu.


FN_TPM_RIGHTBUTTON
TPM_RIGHTBUTTON  0x0002L  winuser.h


TRANSPARENT
TRANSPARENT  1  wingdi.h

Background remains untouched. See SetBkMode.


FN_TRANSPARENT
TRANSPARENT  1  wingdi.h


TRUNCATE_EXISTING
TRUNCATE_EXISTING  5  winbase.h

Opens the file. Fails if the file does not exist. 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. See CreateFile.


FN_TRUNCATE_EXISTING
TRUNCATE_EXISTING  5  winbase.h


TT_PRIM_LINE
TT_PRIM_LINE  1  wingdi.h

Curve is a polyline. See TTPOLYCURVE.


FN_TT_PRIM_LINE
TT_PRIM_LINE  1  wingdi.h


TT_PRIM_QSPLINE
TT_PRIM_QSPLINE  2  wingdi.h

Curve is a Bézier spline. See TTPOLYCURVE.


FN_TT_PRIM_QSPLINE
TT_PRIM_QSPLINE  2  wingdi.h


TWOSTOPBITS
TWOSTOPBITS  2  winbase.h

2 stop bits See DCB.


FN_TWOSTOPBITS
TWOSTOPBITS  2  winbase.h


UNIQUE_NAME
UNIQUE_NAME  0x00  nb30.h

The name specified by the name member was created with using the NCBADDNAME command. See NAME_BUFFER.


FN_UNIQUE_NAME
UNIQUE_NAME  0x00  nb30.h


UNLOAD_DLL_DEBUG_EVENT
UNLOAD_DLL_DEBUG_EVENT  7  winbase.h

Reports an unload DLL debugging event. The value of u.UnloadDll specifies an UNLOAD_DLL_DEBUG_INFO structure. See DEBUG_EVENT.


FN_UNLOAD_DLL_DEBUG_EVENT
UNLOAD_DLL_DEBUG_EVENT  7  winbase.h


VERTRES
VERTRES  10  wingdi.h

Height of the display, in raster lines. See GetDeviceCaps.


FN_VERTRES
VERTRES  10  wingdi.h


VERTSIZE
VERTSIZE  6  wingdi.h

Height of the physical display, in millimeters. See GetDeviceCaps.


FN_VERTSIZE
VERTSIZE  6  wingdi.h


VFF_BUFFTOOSMALL
VFF_BUFFTOOSMALL  0x0004  winver.h

Indicates at least one of the buffers was too small to contain the corresponding string. An application should check lpszCurDir and lpszDestDir to determine which buffer was too small. See VerFindFile.


FN_VFF_BUFFTOOSMALL
VFF_BUFFTOOSMALL  0x0004  winver.h


VFF_CURNEDEST
VFF_CURNEDEST  0x0001  winver.h

Indicates the currently installed version of the file is not in the recommended destination. See VerFindFile.


FN_VFF_CURNEDEST
VFF_CURNEDEST  0x0001  winver.h


VFF_FILEINUSE
VFF_FILEINUSE  0x0002  winver.h

Indicates Windows is using the currently installed version of the file; therefore, the file cannot be overwritten or deleted. See VerFindFile.


FN_VFF_FILEINUSE
VFF_FILEINUSE  0x0002  winver.h


VFFF_ISSHAREDFILE
VFFF_ISSHAREDFILE  0x0001  winver.h

Indicates the source file may be shared by multiple applications. An application can use this information to determine where the file should be copied. See VerFindFile.


FN_VFFF_ISSHAREDFILE
VFFF_ISSHAREDFILE  0x0001  winver.h


VFT2_DRV_DISPLAY
VFT2_DRV_DISPLAY  0x00000004L  winver.h

Indicates that the file contains a display driver. See VS_FIXEDFILEINFO.


FN_VFT2_DRV_DISPLAY
VFT2_DRV_DISPLAY  0x00000004L  winver.h


VFT2_DRV_INSTALLABLE
VFT2_DRV_INSTALLABLE  0x00000008L  winver.h

Indicates that the file contains an installable driver. See VS_FIXEDFILEINFO.


FN_VFT2_DRV_INSTALLABLE
VFT2_DRV_INSTALLABLE  0x00000008L  winver.h


VFT2_DRV_KEYBOARD
VFT2_DRV_KEYBOARD  0x00000002L  winver.h

Indicates that the file contains a keyboard driver. See VS_FIXEDFILEINFO.


FN_VFT2_DRV_KEYBOARD
VFT2_DRV_KEYBOARD  0x00000002L  winver.h


VFT2_DRV_LANGUAGE
VFT2_DRV_LANGUAGE  0x00000003L  winver.h

Indicates that the file contains a language driver. See VS_FIXEDFILEINFO.


FN_VFT2_DRV_LANGUAGE
VFT2_DRV_LANGUAGE  0x00000003L  winver.h


VFT2_DRV_MOUSE
VFT2_DRV_MOUSE  0x00000005L  winver.h

Indicates that the file contains a mouse driver. See VS_FIXEDFILEINFO.


FN_VFT2_DRV_MOUSE
VFT2_DRV_MOUSE  0x00000005L  winver.h


VFT2_DRV_NETWORK
VFT2_DRV_NETWORK  0x00000006L  winver.h

Indicates that the file contains a network driver. See VS_FIXEDFILEINFO.


FN_VFT2_DRV_NETWORK
VFT2_DRV_NETWORK  0x00000006L  winver.h


VFT2_DRV_PRINTER
VFT2_DRV_PRINTER  0x00000001L  winver.h

Indicates that the file contains a printer driver. See VS_FIXEDFILEINFO.


FN_VFT2_DRV_PRINTER
VFT2_DRV_PRINTER  0x00000001L  winver.h


VFT2_DRV_SOUND
VFT2_DRV_SOUND  0x00000009L  winver.h

Indicates that the file contains a sound driver. See VS_FIXEDFILEINFO.


FN_VFT2_DRV_SOUND
VFT2_DRV_SOUND  0x00000009L  winver.h


VFT2_DRV_SYSTEM
VFT2_DRV_SYSTEM  0x00000007L  winver.h

Indicates that the file contains a system driver. See VS_FIXEDFILEINFO.


FN_VFT2_DRV_SYSTEM
VFT2_DRV_SYSTEM  0x00000007L  winver.h


VFT2_FONT_RASTER
VFT2_FONT_RASTER  0x00000001L  winver.h

Indicates that the file contains a raster font. See VS_FIXEDFILEINFO.


FN_VFT2_FONT_RASTER
VFT2_FONT_RASTER  0x00000001L  winver.h


VFT2_FONT_TRUETYPE
VFT2_FONT_TRUETYPE  0x00000003L  winver.h

Indicates that the file contains a TrueType font. See VS_FIXEDFILEINFO.


FN_VFT2_FONT_TRUETYPE
VFT2_FONT_TRUETYPE  0x00000003L  winver.h


VFT2_FONT_VECTOR
VFT2_FONT_VECTOR  0x00000002L  winver.h

Indicates that the file contains a vector font. See VS_FIXEDFILEINFO.


FN_VFT2_FONT_VECTOR
VFT2_FONT_VECTOR  0x00000002L  winver.h


VFT2_UNKNOWN
VFT2_UNKNOWN  0x00000000L  winver.h

Indicates that the driver or font type is unknown by Windows. See VS_FIXEDFILEINFO.


FN_VFT2_UNKNOWN
VFT2_UNKNOWN  0x00000000L  winver.h


VFT_APP

Indicates that the file contains an application. See VS_FIXEDFILEINFO.


VFT_DLL

Indicates that the file contains a dynamic-link library See VS_FIXEDFILEINFO.


VFT_DRV

Indicates that the file contains a device driver. If dwFileType is VFT_DRV, dwFileSubtype contains a more specific description of the driver. See VS_FIXEDFILEINFO.


VFT_FONT

Indicates that the file contains a font. If dwFileType is VFT_FONT, dwFileSubtype contains a more specific description of the font file. See VS_FIXEDFILEINFO.


VFT_STATIC_LIB

Indicates that the file contains a static-link library. See VS_FIXEDFILEINFO.


VFT_UNKNOWN

Indicates that the file type is unknown to Windows. See VS_FIXEDFILEINFO.


VFT_VXD

Indicates that the file contains a virtual device. See VS_FIXEDFILEINFO.


VIF_ACCESSVIOLATION
VIF_ACCESSVIOLATION  0x00000200L  winver.h

Indicates a read, create, delete or rename operation failed due to an access violation. See VerInstallFile.


FN_VIF_ACCESSVIOLATION
VIF_ACCESSVIOLATION  0x00000200L  winver.h


VIF_BUFFTOOSMALL
VIF_BUFFTOOSMALL  0x00040000L  winver.h

Indicates the szTmpFile buffer was too small to contain the name of the temporary source file. On return, lpdwTmpFileLen contains the size of the buffer required to hold the filename. See VerInstallFile.


FN_VIF_BUFFTOOSMALL
VIF_BUFFTOOSMALL  0x00040000L  winver.h


VIF_CANNOTCREATE
VIF_CANNOTCREATE  0x00000800L  winver.h

Indicates the function cannot create the temporary file. The specific error may be described by another flag. See VerInstallFile.


FN_VIF_CANNOTCREATE
VIF_CANNOTCREATE  0x00000800L  winver.h


VIF_CANNOTDELETE
VIF_CANNOTDELETE  0x00001000L  winver.h

Indicates 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. See VerInstallFile.


FN_VIF_CANNOTDELETE
VIF_CANNOTDELETE  0x00001000L  winver.h


VIF_CANNOTREADDST
VIF_CANNOTREADDST  0x00020000L  winver.h

Indicates the function cannot read the destination (existing) files. This prevents the function from examining the file's attributes. See VerInstallFile.


FN_VIF_CANNOTREADDST
VIF_CANNOTREADDST  0x00020000L  winver.h


VIF_CANNOTREADSRC
VIF_CANNOTREADSRC  0x00010000L  winver.h

Indicates the function cannot read the source file. This could mean that the path was not specified properly. See VerInstallFile.


FN_VIF_CANNOTREADSRC
VIF_CANNOTREADSRC  0x00010000L  winver.h


VIF_CANNOTRENAME
VIF_CANNOTRENAME  0x00002000L  winver.h

Indicates the function cannot rename the temporary file, but already deleted the destination file. See VerInstallFile.


FN_VIF_CANNOTRENAME
VIF_CANNOTRENAME  0x00002000L  winver.h


VIF_DIFFCODEPG
VIF_DIFFCODEPG  0x00000010L  winver.h

Indicates the new file requires a code page that cannot be displayed by the currently running version of Windows. This error can be overridden by calling VerInstallFile with the VIFF_FORCEINSTALL flag. See VerInstallFile.


FN_VIF_DIFFCODEPG
VIF_DIFFCODEPG  0x00000010L  winver.h


VIF_DIFFLANG
VIF_DIFFLANG  0x00000008L  winver.h

Indicates 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. See VerInstallFile.


FN_VIF_DIFFLANG
VIF_DIFFLANG  0x00000008L  winver.h


VIF_DIFFTYPE
VIF_DIFFTYPE  0x00000020L  winver.h

Indicates the new file has different type, subtype, or operating system than the preexisting file. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag. See VerInstallFile.


FN_VIF_DIFFTYPE
VIF_DIFFTYPE  0x00000020L  winver.h


VIF_FILEINUSE
VIF_FILEINUSE  0x00000080L  winver.h

Indicates the preexisting file is in use by Windows and cannot be deleted. See VerInstallFile.


FN_VIF_FILEINUSE
VIF_FILEINUSE  0x00000080L  winver.h


VIF_MISMATCH
VIF_MISMATCH  0x00000002L  winver.h

Indicates 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. See VerInstallFile.


FN_VIF_MISMATCH
VIF_MISMATCH  0x00000002L  winver.h


VIF_OUTOFMEMORY
VIF_OUTOFMEMORY  0x00008000L  winver.h

Indicates 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. See VerInstallFile.


FN_VIF_OUTOFMEMORY
VIF_OUTOFMEMORY  0x00008000L  winver.h


VIF_OUTOFSPACE
VIF_OUTOFSPACE  0x00000100L  winver.h

Indicates the function cannot create the temporary file due to insufficient disk space on the destination drive. See VerInstallFile.


FN_VIF_OUTOFSPACE
VIF_OUTOFSPACE  0x00000100L  winver.h


VIF_SHARINGVIOLATION
VIF_SHARINGVIOLATION  0x00000400L  winver.h

Indicates a read, create, delete or rename operation failed due to a sharing violation. See VerInstallFile.


FN_VIF_SHARINGVIOLATION
VIF_SHARINGVIOLATION  0x00000400L  winver.h


VIF_SRCOLD
VIF_SRCOLD  0x00000004L  winver.h

Indicates the file to install is older than the preexisting file. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag. See VerInstallFile.


FN_VIF_SRCOLD
VIF_SRCOLD  0x00000004L  winver.h


VIF_TEMPFILE
VIF_TEMPFILE  0x00000001L  winver.h

Indicates the temporary copy of the new file is in the destination directory. The cause of failure is reflected in other flags. See VerInstallFile.


FN_VIF_TEMPFILE
VIF_TEMPFILE  0x00000001L  winver.h


VIF_WRITEPROT
VIF_WRITEPROT  0x00000040L  winver.h

Indicates the preexisting file is write-protected. This error can be overridden by calling VerInstallFile again the VIFF_FORCEINSTALL flag. See VerInstallFile.


FN_VIF_WRITEPROT
VIF_WRITEPROT  0x00000040L  winver.h


VIFF_DONTDELETEOLD
VIFF_DONTDELETEOLD  0x0002  winver.h

Installs the file without deleting the previously installed file, if the previously installed file is not in the destination directory. See VerInstallFile.


FN_VIFF_DONTDELETEOLD
VIFF_DONTDELETEOLD  0x0002  winver.h


VIFF_FORCEINSTALL
VIFF_FORCEINSTALL  0x0001  winver.h

Installs the file regardless of mismatched version numbers. The function will only check for physical errors during installation. See VerInstallFile.


FN_VIFF_FORCEINSTALL
VIFF_FORCEINSTALL  0x0001  winver.h


VOS__PM16
VOS__PM16  0x00000002L  winver.h

Indicates that the file was designed for 16-bit Presentation Manager. See VS_FIXEDFILEINFO.


FN_VOS__PM16
VOS__PM16  0x00000002L  winver.h


VOS__PM32
VOS__PM32  0x00000003L  winver.h

Indicates that the file was designed for 32-bit Presentation Manager. See VS_FIXEDFILEINFO.


FN_VOS__PM32
VOS__PM32  0x00000003L  winver.h


VOS__WINDOWS16
VOS__WINDOWS16  0x00000001L  winver.h

Indicates that the file was designed for 16-bit Windows. See VS_FIXEDFILEINFO.


FN_VOS__WINDOWS16
VOS__WINDOWS16  0x00000001L  winver.h


VOS__WINDOWS32
VOS__WINDOWS32  0x00000004L  winver.h

Indicates that the file was designed for 32-bit Windows. See VS_FIXEDFILEINFO.


FN_VOS__WINDOWS32
VOS__WINDOWS32  0x00000004L  winver.h


VOS_DOS
VOS_DOS  0x00010000L  winver.h

Indicates that the file was designed for DOS. See VS_FIXEDFILEINFO.


FN_VOS_DOS
VOS_DOS  0x00010000L  winver.h


VOS_DOS_WINDOWS16
VOS_DOS_WINDOWS16  0x00010001L  winver.h

Indicates that the file was designed for 16-bit Windows running on DOS. See VS_FIXEDFILEINFO.


FN_VOS_DOS_WINDOWS16
VOS_DOS_WINDOWS16  0x00010001L  winver.h


VOS_DOS_WINDOWS32
VOS_DOS_WINDOWS32  0x00010004L  winver.h

Indicates that the file was designed for 32-bit Windows running on DOS. See VS_FIXEDFILEINFO.


FN_VOS_DOS_WINDOWS32
VOS_DOS_WINDOWS32  0x00010004L  winver.h


VOS_NT
VOS_NT  0x00040000L  winver.h

Indicates that the file was designed for NT. See VS_FIXEDFILEINFO.


FN_VOS_NT
VOS_NT  0x00040000L  winver.h


VOS_NT_WINDOWS32
VOS_NT_WINDOWS32  0x00040004L  winver.h

Indicates that the file was designed for 32-bit Windows running on NT. See VS_FIXEDFILEINFO.


FN_VOS_NT_WINDOWS32
VOS_NT_WINDOWS32  0x00040004L  winver.h


VOS_OS216
VOS_OS216  0x00020000L  winver.h

Indicates that the file was designed for 16-bit OS/2. See VS_FIXEDFILEINFO.


FN_VOS_OS216
VOS_OS216  0x00020000L  winver.h


VOS_OS216_PM16
VOS_OS216_PM16  0x00020002L  winver.h

Indicates that the file was designed for 16-bit Presentation Manager running on 16-bit OS/2. See VS_FIXEDFILEINFO.


FN_VOS_OS216_PM16
VOS_OS216_PM16  0x00020002L  winver.h


VOS_OS232
VOS_OS232  0x00030000L  winver.h

Indicates that the file was designed for 32-bit OS/2. See VS_FIXEDFILEINFO.


FN_VOS_OS232
VOS_OS232  0x00030000L  winver.h


VOS_OS232_PM32
VOS_OS232_PM32  0x00030003L  winver.h

Indicates that the file was designed for 32-bit Presentation Manager running on 32-bit OS/2. See VS_FIXEDFILEINFO.


FN_VOS_OS232_PM32
VOS_OS232_PM32  0x00030003L  winver.h


VOS_UNKNOWN
VOS_UNKNOWN  0x00000000L  winver.h

Indicates that the operating system for which the file was designed is unknown to Windows. See VS_FIXEDFILEINFO.


FN_VOS_UNKNOWN
VOS_UNKNOWN  0x00000000L  winver.h


VS_FF_DEBUG
VS_FF_DEBUG  0x00000001L  winver.h

Indicates that the file contains debugging information or is compiled with debugging features enabled. See VS_FIXEDFILEINFO.


FN_VS_FF_DEBUG
VS_FF_DEBUG  0x00000001L  winver.h


VS_FF_INFOINFERRED
VS_FF_INFOINFERRED  0x00000010L  winver.h

Indicates that the file's version data structure was created dynamically; therefore, some of the fields in this data structure may be empty or incorrect. This flag should never be set in a file's VS_VERSION_INFO data. See VS_FIXEDFILEINFO.


FN_VS_FF_INFOINFERRED
VS_FF_INFOINFERRED  0x00000010L  winver.h


VS_FF_PATCHED
VS_FF_PATCHED  0x00000004L  winver.h

Indicates that the file has been modified and is not identical to the original shipping file of the same version number. See VS_FIXEDFILEINFO.


FN_VS_FF_PATCHED
VS_FF_PATCHED  0x00000004L  winver.h


VS_FF_PRERELEASE
VS_FF_PRERELEASE  0x00000002L  winver.h

Indicates that the file is a development version, not a commercially released product. See VS_FIXEDFILEINFO.


FN_VS_FF_PRERELEASE
VS_FF_PRERELEASE  0x00000002L  winver.h


VS_FF_PRIVATEBUILD
VS_FF_PRIVATEBUILD  0x00000008L  winver.h

Indicates that the file was not built using standard release procedures. If this flag is set, the StringFileInfo block should contain a PrivateBuild entry. See VS_FIXEDFILEINFO.


FN_VS_FF_PRIVATEBUILD
VS_FF_PRIVATEBUILD  0x00000008L  winver.h


VS_FF_SPECIALBUILD
VS_FF_SPECIALBUILD  0x00000020L  winver.h

Indicates that 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 block should contain a SpecialBuild entry. See VS_FIXEDFILEINFO.


FN_VS_FF_SPECIALBUILD
VS_FF_SPECIALBUILD  0x00000020L  winver.h


VTA_BASELINE
VTA_BASELINE  TA_BASELINE  wingdi.h

The reference point will be on the baseline of the text. VTA_BASELINE The reference point will be on the baseline of the text. See GetTextAlign, SetTextAlign.


FN_VTA_BASELINE
VTA_BASELINE  TA_BASELINE  wingdi.h


VTA_CENTER
VTA_CENTER  TA_CENTER  wingdi.h

The reference point will be aligned vertically with the center of the bounding rectangle. See GetTextAlign, SetTextAlign.


FN_VTA_CENTER
VTA_CENTER  TA_CENTER  wingdi.h


WA_ACTIVE
WA_ACTIVE  1  winuser.h

The window is being 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). See WM_ACTIVATE.


FN_WA_ACTIVE
WA_ACTIVE  1  winuser.h


WA_CLICKACTIVE
WA_CLICKACTIVE  2  winuser.h

The window is being activated by a mouse click. See WM_ACTIVATE.


FN_WA_CLICKACTIVE
WA_CLICKACTIVE  2  winuser.h


WA_INACTIVE
WA_INACTIVE  0  winuser.h

The window is being deactivated. See WM_ACTIVATE.


FN_WA_INACTIVE
WA_INACTIVE  0  winuser.h


WAVE_ALLOWSYNC
WAVE_ALLOWSYNC  0x00000002  mmsystem.h

If this flag is not specified, then the device will fail to open if it is a synchronous device. See waveInOpen, waveOutOpen.


FN_WAVE_ALLOWSYNC
WAVE_ALLOWSYNC  0x00000002  mmsystem.h


WAVE_FORMAT_1M08
WAVE_FORMAT_1M08  0x00000001  mmsystem.h

11.025 kHz, Mono, 8-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_1M08
WAVE_FORMAT_1M08  0x00000001  mmsystem.h


WAVE_FORMAT_1M16
WAVE_FORMAT_1M16  0x00000004  mmsystem.h

11.025 kHz, Mono, 16-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_1M16
WAVE_FORMAT_1M16  0x00000004  mmsystem.h


WAVE_FORMAT_1S08
WAVE_FORMAT_1S08  0x00000002  mmsystem.h

11.025 kHz, Stereo, 8-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_1S08
WAVE_FORMAT_1S08  0x00000002  mmsystem.h


WAVE_FORMAT_1S16
WAVE_FORMAT_1S16  0x00000008  mmsystem.h

11.025 kHz, Stereo, 16-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_1S16
WAVE_FORMAT_1S16  0x00000008  mmsystem.h


WAVE_FORMAT_2M08
WAVE_FORMAT_2M08  0x00000010  mmsystem.h

22.05 kHz, Mono, 8-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_2M08
WAVE_FORMAT_2M08  0x00000010  mmsystem.h


WAVE_FORMAT_2M16
WAVE_FORMAT_2M16  0x00000040  mmsystem.h

22.05 kHz, Mono, 16-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_2M16
WAVE_FORMAT_2M16  0x00000040  mmsystem.h


WAVE_FORMAT_2S08
WAVE_FORMAT_2S08  0x00000020  mmsystem.h

22.05 kHz, Stereo, 8-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_2S08
WAVE_FORMAT_2S08  0x00000020  mmsystem.h


WAVE_FORMAT_2S16
WAVE_FORMAT_2S16  0x00000080  mmsystem.h

22.05 kHz, Stereo, 16-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_2S16
WAVE_FORMAT_2S16  0x00000080  mmsystem.h


WAVE_FORMAT_4M08
WAVE_FORMAT_4M08  0x00000100  mmsystem.h

44.1 kHz, Mono, 8-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_4M08
WAVE_FORMAT_4M08  0x00000100  mmsystem.h


WAVE_FORMAT_4M16
WAVE_FORMAT_4M16  0x00000400  mmsystem.h

44.1 kHz, Mono, 16-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_4M16
WAVE_FORMAT_4M16  0x00000400  mmsystem.h


WAVE_FORMAT_4S08
WAVE_FORMAT_4S08  0x00000200  mmsystem.h

44.1 kHz, Stereo, 8-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_4S08
WAVE_FORMAT_4S08  0x00000200  mmsystem.h


WAVE_FORMAT_4S16
WAVE_FORMAT_4S16  0x00000800  mmsystem.h

44.1 kHz, Stereo, 16-bit See WAVEINCAPS, WAVEOUTCAPS.


FN_WAVE_FORMAT_4S16
WAVE_FORMAT_4S16  0x00000800  mmsystem.h


WAVE_FORMAT_PCM
WAVE_FORMAT_PCM  1  mmsystem.h

Waveform data is PCM. See WAVEFORMAT.


FN_WAVE_FORMAT_PCM
WAVE_FORMAT_PCM  1  mmsystem.h


WAVE_FORMAT_QUERY
WAVE_FORMAT_QUERY  0x00000001  mmsystem.h

If this flag is specified, the device is queried to determine if it supports the given format but is not actually opened. See waveInOpen, waveOutOpen.


FN_WAVE_FORMAT_QUERY
WAVE_FORMAT_QUERY  0x00000001  mmsystem.h


WAVECAPS_LRVOLUME
WAVECAPS_LRVOLUME  0x00000008  mmsystem.h

Supports separate left and right volume control. See WAVEOUTCAPS.


FN_WAVECAPS_LRVOLUME
WAVECAPS_LRVOLUME  0x00000008  mmsystem.h


WAVECAPS_PITCH
WAVECAPS_PITCH  0x00000001  mmsystem.h

Supports pitch control. See WAVEOUTCAPS.


FN_WAVECAPS_PITCH
WAVECAPS_PITCH  0x00000001  mmsystem.h


WAVECAPS_PLAYBACKRATE
WAVECAPS_PLAYBACKRATE  0x00000002  mmsystem.h

Supports playback rate control. See WAVEOUTCAPS.


FN_WAVECAPS_PLAYBACKRATE
WAVECAPS_PLAYBACKRATE  0x00000002  mmsystem.h


WAVECAPS_VOLUME
WAVECAPS_VOLUME  0x00000004  mmsystem.h

Supports volume control. See WAVEOUTCAPS.


FN_WAVECAPS_VOLUME
WAVECAPS_VOLUME  0x00000004  mmsystem.h


WAVERR_BADFORMAT
WAVERR_BADFORMAT  (WAVERR_BASE + 0)  mmsystem.h

Attempted to open with an unsupported wave format. See waveInOpen, waveOutOpen.


FN_WAVERR_BADFORMAT
WAVERR_BADFORMAT  (WAVERR_BASE + 0)  mmsystem.h


WAVERR_STILLPLAYING
WAVERR_STILLPLAYING  (WAVERR_BASE + 1)  mmsystem.h

There are still buffers in the queue. See waveInClose, waveInUnprepareHeader, waveOutClose, waveOutUnprepareHeader.


FN_WAVERR_STILLPLAYING
WAVERR_STILLPLAYING  (WAVERR_BASE + 1)  mmsystem.h


WAVERR_UNPREPARED
WAVERR_UNPREPARED  (WAVERR_BASE + 2)  mmsystem.h

Buffer hasn't been prepared. See waveInAddBuffer, waveOutWrite.


FN_WAVERR_UNPREPARED
WAVERR_UNPREPARED  (WAVERR_BASE + 2)  mmsystem.h


WB_ISDELIMITER
WB_ISDELIMITER  2  winuser.h

Check whether the character at the current position is a delimiter. See EditWordBreakProc.


FN_WB_ISDELIMITER
WB_ISDELIMITER  2  winuser.h


WB_LEFT
WB_LEFT  0  winuser.h

Look for the beginning of a word to the left of the current position. See EditWordBreakProc.


FN_WB_LEFT
WB_LEFT  0  winuser.h


WB_RIGHT
WB_RIGHT  1  winuser.h

Look for the beginning of a word to the right of the current position. (This is useful in right-aligned edit controls.) See EditWordBreakProc.


FN_WB_RIGHT
WB_RIGHT  1  winuser.h


WC_COMPOSITECHECK
WC_COMPOSITECHECK  0x00000200  winnls.h

Convert composite characters to precomposed characters. See WideCharToMultiByte.


FN_WC_COMPOSITECHECK
WC_COMPOSITECHECK  0x00000200  winnls.h


WC_DEFAULTCHAR
WC_DEFAULTCHAR  0x00000040  winnls.h

Replace exceptions with the default character. See WideCharToMultiByte.


FN_WC_DEFAULTCHAR
WC_DEFAULTCHAR  0x00000040  winnls.h


WC_DEFAULTCHECK
WC_DEFAULTCHECK  0x00000100  winnls.h

Check for the default character and set the lpfUsedDefaultChar flag when necessary. See WideCharToMultiByte.


FN_WC_DEFAULTCHECK
WC_DEFAULTCHECK  0x00000100  winnls.h


WC_DISCARDNS
WC_DISCARDNS  0x00000010  winnls.h

Discard non-spacing characters. See WideCharToMultiByte.


FN_WC_DISCARDNS
WC_DISCARDNS  0x00000010  winnls.h


WC_SEPCHARS
WC_SEPCHARS  0x00000020  winnls.h

Generate separate characters. This is the default behavior. See WideCharToMultiByte.


FN_WC_SEPCHARS
WC_SEPCHARS  0x00000020  winnls.h


WH_CALLWNDPROC
WH_CALLWNDPROC  4  winuser.h

Installs a hook-procedure that monitors messages sent to a window procedure. For more information, see the description of the CallWndProc hook procedure. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_CALLWNDPROC
WH_CALLWNDPROC  4  winuser.h


WH_CBT
WH_CBT  5  winuser.h

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. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_CBT
WH_CBT  5  winuser.h


WH_DEBUG
WH_DEBUG  9  winuser.h

Installs a hook procedure useful for debugging other hook procedures. For more information, see the description of the DebugProc hook procedure. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_DEBUG
WH_DEBUG  9  winuser.h


WH_GETMESSAGE
WH_GETMESSAGE  3  winuser.h

Installs a hook procedure that monitors messages posted to a message queue. For more information, see the description of the GetMsgProc hook procedure. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_GETMESSAGE
WH_GETMESSAGE  3  winuser.h


WH_HARDWARE
WH_HARDWARE  8  winuser.h

Installs a hook procedure that monitors messages that are posted by a nonstandard input device such as a pen. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_HARDWARE
WH_HARDWARE  8  winuser.h


WH_JOURNALPLAYBACK
WH_JOURNALPLAYBACK  1  winuser.h

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. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_JOURNALPLAYBACK
WH_JOURNALPLAYBACK  1  winuser.h


WH_JOURNALRECORD
WH_JOURNALRECORD  0  winuser.h

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. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_JOURNALRECORD
WH_JOURNALRECORD  0  winuser.h


WH_KEYBOARD
WH_KEYBOARD  2  winuser.h

Installs a hook procedure that monitors keystroke messages. For more information, see the description of the KeyboardProc hook procedure. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_KEYBOARD
WH_KEYBOARD  2  winuser.h


WH_MOUSE
WH_MOUSE  7  winuser.h

Installs a hook procedure that monitors mouse messages. For more information, see the description of the MouseProc hook procedure. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_MOUSE
WH_MOUSE  7  winuser.h


WH_MSGFILTER
WH_MSGFILTER  (-1)  winuser.h

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. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_MSGFILTER
WH_MSGFILTER  (-1)  winuser.h


WH_SHELL
WH_SHELL  10  winuser.h

Installs a hook procedure that receives notifications useful to shell applications. For more information, see the description of the ShellProc hook procedure. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_SHELL
WH_SHELL  10  winuser.h


WH_SYSMSGFILTER
WH_SYSMSGFILTER  6  winuser.h

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. See DebugProc, SetWindowsHook, SetWindowsHookEx.


FN_WH_SYSMSGFILTER
WH_SYSMSGFILTER  6  winuser.h


WHDR_BEGINLOOP
WHDR_BEGINLOOP  0x00000004  mmsystem.h

Specifies that this buffer is the first buffer in a loop. This flag is only used with output data buffers. See WAVEHDR.


FN_WHDR_BEGINLOOP
WHDR_BEGINLOOP  0x00000004  mmsystem.h


WHDR_DONE
WHDR_DONE  0x00000001  mmsystem.h

Set by the device driver to indicate that it is finished with the data buffer and is returning it to the application. See WAVEHDR.


FN_WHDR_DONE
WHDR_DONE  0x00000001  mmsystem.h


WHDR_ENDLOOP
WHDR_ENDLOOP  0x00000008  mmsystem.h

Specifies that this buffer is the last buffer in a loop. This flag is only used with output data buffers. See WAVEHDR.


FN_WHDR_ENDLOOP
WHDR_ENDLOOP  0x00000008  mmsystem.h


WHDR_PREPARED
WHDR_PREPARED  0x00000002  mmsystem.h

Set by Windows to indicate that the data buffer has been prepared with waveInPrepareHeader or waveOutPrepareHeader. See WAVEHDR.


FN_WHDR_PREPARED
WHDR_PREPARED  0x00000002  mmsystem.h


WHITE_BRUSH
WHITE_BRUSH  0  wingdi.h

White brush See GetStockObject.


FN_WHITE_BRUSH
WHITE_BRUSH  0  wingdi.h


WHITE_PEN
WHITE_PEN  6  wingdi.h

White pen See GetStockObject.


FN_WHITE_PEN
WHITE_PEN  6  wingdi.h


WHITENESS
WHITENESS  (DWORD)0x00FF0062  wingdi.h

Fills the destination rectangle the color associated with index 1 in the physical palette. (This color is white for the default physical palette.) See BitBlt, PatBlt.


FN_WHITENESS
WHITENESS  (DWORD)0x00FF0062  wingdi.h


WHITEONBLACK
WHITEONBLACK  2  wingdi.h

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. See SetStretchBltMode.


FN_WHITEONBLACK
WHITEONBLACK  2  wingdi.h


WINDING
WINDING  2  wingdi.h

Selects winding number mode (fills any region with a non-zero winding number). See CreatePolygonRgn, CreatePolyPolygonRgn, GetPolyFillMode, SetPolyFillMode.


FN_WINDING
WINDING  2  wingdi.h


WPF_RESTORETOMAXIMIZED
WPF_RESTORETOMAXIMIZED  0x0002  winuser.h

Specifies that the restored window will be maximized, regardless of whether it was maximized before it was minimized. This setting is valid only the next time the window is restored. It does not change the default restoration behavior. This flag is valid only when the SW_SHOWMINIMIZED value is specified for the showCmd member. See WINDOWPLACEMENT.


FN_WPF_RESTORETOMAXIMIZED
WPF_RESTORETOMAXIMIZED  0x0002  winuser.h


WPF_SETMINPOSITION
WPF_SETMINPOSITION  0x0001  winuser.h

Specifies that the x- and y-positions of the minimized window may be specified. This flag must be specified if the coordinates are set in the ptMinPosition member. See WINDOWPLACEMENT.


FN_WPF_SETMINPOSITION
WPF_SETMINPOSITION  0x0001  winuser.h


WS_BORDER
WS_BORDER  0x00800000L  winuser.h

Creates a window that has a thin-line border. See CreateWindow.


FN_WS_BORDER
WS_BORDER  0x00800000L  winuser.h


WS_CAPTION
WS_CAPTION  0x00C00000L  winuser.h

Creates a window that has a title bar (includes the WS_BORDER style). See CreateWindow.


FN_WS_CAPTION
WS_CAPTION  0x00C00000L  winuser.h


WS_CHILD
WS_CHILD  0x40000000L  winuser.h

Creates a child window. This style cannot be used with the WS_POPUP style. See CreateWindow.


FN_WS_CHILD
WS_CHILD  0x40000000L  winuser.h


WS_CHILDWINDOW
WS_CHILDWINDOW  (WS_CHILD)  winuser.h

Same as the WS_CHILD style. See CreateWindow.


FN_WS_CHILDWINDOW
WS_CHILDWINDOW  (WS_CHILD)  winuser.h


WS_CLIPCHILDREN
WS_CLIPCHILDREN  0x02000000L  winuser.h

Excludes the area occupied by child windows when drawing within the parent window. Use this style when creating the parent window. See CreateWindow.


FN_WS_CLIPCHILDREN
WS_CLIPCHILDREN  0x02000000L  winuser.h


WS_CLIPSIBLINGS
WS_CLIPSIBLINGS  0x04000000L  winuser.h

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. For use with the WS_CHILD style only. See CreateWindow.


FN_WS_CLIPSIBLINGS
WS_CLIPSIBLINGS  0x04000000L  winuser.h


WS_DISABLED
WS_DISABLED  0x08000000L  winuser.h

Creates a window that is initially disabled. A disabled window cannot receive input from the user. See CreateWindow.


FN_WS_DISABLED
WS_DISABLED  0x08000000L  winuser.h


WS_DLGFRAME
WS_DLGFRAME  0x00400000L  winuser.h

Creates a window with a border of a style typically used with dialog boxes. A window with this style cannot have a title bar. See CreateWindow.


FN_WS_DLGFRAME
WS_DLGFRAME  0x00400000L  winuser.h


WS_EX_ACCEPTFILES
WS_EX_ACCEPTFILES  0x00000010L  winuser.h

Specifies that a window created with this style accepts drag-drop files. See CreateWindowEx.


FN_WS_EX_ACCEPTFILES
WS_EX_ACCEPTFILES  0x00000010L  winuser.h


WS_EX_DLGMODALFRAME
WS_EX_DLGMODALFRAME  0x00000001L  winuser.h

Creates a window with a double border that can (optionally) be created with a title bar by specifying the WS_CAPTION style in the dwStyle parameter. See CreateWindowEx.


FN_WS_EX_DLGMODALFRAME
WS_EX_DLGMODALFRAME  0x00000001L  winuser.h


WS_EX_NOPARENTNOTIFY
WS_EX_NOPARENTNOTIFY  0x00000004L  winuser.h

Specifies that a child window created by using this style will not send the WM_PARENTNOTIFY message to its parent window when the child window is created or destroyed. See CreateWindowEx.


FN_WS_EX_NOPARENTNOTIFY
WS_EX_NOPARENTNOTIFY  0x00000004L  winuser.h


WS_EX_TOPMOST
WS_EX_TOPMOST  0x00000008L  winuser.h

Specifies that a window created with this style should be placed above all non-topmost windows and stay above them even when the window is deactivated. Use the SetWindowPos function to add or remove this style. See CreateWindowEx.


FN_WS_EX_TOPMOST
WS_EX_TOPMOST  0x00000008L  winuser.h


WS_GROUP
WS_GROUP  0x00020000L  winuser.h

Specifies the first control of a group of controls. The user can change the keyboard focus from one control in the group to the next by using the direction keys. All controls defined with the WS_GROUP style after the first control belong to the same group. The next control with the WS_GROUP style ends the group and starts the next group. See CreateWindow.


FN_WS_GROUP
WS_GROUP  0x00020000L  winuser.h


WS_HSCROLL
WS_HSCROLL  0x00100000L  winuser.h

Creates an MDI child window that has a horizontal scroll bar. WS_HSCROLL Creates a window that has a horizontal scroll bar. WS_HSCROLL Creates an MDI child window that has a horizontal scroll bar. See CreateMDIWindow, CreateWindow, MDICREATESTRUCT.


FN_WS_HSCROLL
WS_HSCROLL  0x00100000L  winuser.h


WS_MAXIMIZE
WS_MAXIMIZE  0x01000000L  winuser.h

Creates a window that is initially maximized. See CreateMDIWindow, CreateWindow, MDICREATESTRUCT.


FN_WS_MAXIMIZE
WS_MAXIMIZE  0x01000000L  winuser.h


WS_MAXIMIZEBOX
WS_MAXIMIZEBOX  0x00010000L  winuser.h

Creates a window that has a maximize box. See CreateWindow.


FN_WS_MAXIMIZEBOX
WS_MAXIMIZEBOX  0x00010000L  winuser.h


WS_MINIMIZE
WS_MINIMIZE  0x20000000L  winuser.h

Creates a window that is initially minimized. See CreateMDIWindow, CreateWindow, MDICREATESTRUCT.


FN_WS_MINIMIZE
WS_MINIMIZE  0x20000000L  winuser.h


WS_MINIMIZEBOX
WS_MINIMIZEBOX  0x00020000L  winuser.h

Creates a window that has a minimize box. See CreateWindow.


FN_WS_MINIMIZEBOX
WS_MINIMIZEBOX  0x00020000L  winuser.h


WS_OVERLAPPED
WS_OVERLAPPED  0x00000000L  winuser.h

Creates an overlapped window. An overlapped window has a title bar and a border. See CreateWindow.


FN_WS_OVERLAPPED
WS_OVERLAPPED  0x00000000L  winuser.h


WS_OVERLAPPEDWINDOW
WS_OVERLAPPEDWINDOW  (WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU | WS_THICKFRAME | WS_MINIMIZEBOX | WS_MAXIMIZEBOX)  winuser.h

Creates an overlapped window having the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. See CreateWindow.


FN_WS_OVERLAPPEDWINDOW
WS_OVERLAPPEDWINDOW  (WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU | WS_THICKFRAME | WS_MINIMIZEBOX | WS_MAXIMIZEBOX)  winuser.h


WS_POPUP
WS_POPUP  0x80000000L  winuser.h

Creates a pop-up window. This style cannot be used with the WS_CHILD style. See CreateWindow.


FN_WS_POPUP
WS_POPUP  0x80000000L  winuser.h


WS_POPUPWINDOW
WS_POPUPWINDOW  (WS_POPUP | WS_BORDER | WS_SYSMENU)  winuser.h

Creates a pop-up window having WS_BORDER, WS_POPUP, and WS_SYSMENU styles. You must combine the WS_CAPTION style with the WS_POPUPWINDOW style to make the System menu visible. See CreateWindow.


FN_WS_POPUPWINDOW
WS_POPUPWINDOW  (WS_POPUP | WS_BORDER | WS_SYSMENU)  winuser.h


WS_SYSMENU
WS_SYSMENU  0x00080000L  winuser.h

Creates a window that has a System-menu box in its title bar. The WS_CAPTION style must also be specified. See CreateWindow.


FN_WS_SYSMENU
WS_SYSMENU  0x00080000L  winuser.h


WS_TABSTOP
WS_TABSTOP  0x00010000L  winuser.h

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. See CreateWindow.


FN_WS_TABSTOP
WS_TABSTOP  0x00010000L  winuser.h


WS_THICKFRAME
WS_THICKFRAME  0x00040000L  winuser.h

Creates a window with a sizing border. See CreateWindow.


FN_WS_THICKFRAME
WS_THICKFRAME  0x00040000L  winuser.h


WS_VISIBLE
WS_VISIBLE  0x10000000L  winuser.h

Creates a window that is initially visible. See CreateWindow.


FN_WS_VISIBLE
WS_VISIBLE  0x10000000L  winuser.h


WS_VSCROLL
WS_VSCROLL  0x00200000L  winuser.h

Creates a window that has a vertical scroll bar. See CreateMDIWindow, CreateWindow, MDICREATESTRUCT.


FN_WS_VSCROLL
WS_VSCROLL  0x00200000L  winuser.h


WVR_REDRAW
WVR_REDRAW  (WVR_HREDRAW | WVR_VREDRAW)  winuser.h

This value causes the entire window to be redrawn. It is a combination of WVR_HREDRAW and WVR_VREDRAW. See WM_NCCALCSIZE.


FN_WVR_REDRAW
WVR_REDRAW  (WVR_HREDRAW | WVR_VREDRAW)  winuser.h


WVR_VALIDRECTS
WVR_VALIDRECTS  0x0400  winuser.h

This value indicates that, upon return from WM_NCCALCSIZE, the rgrc[1] and rgrc[2] rectangles 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. See WM_NCCALCSIZE.


FN_WVR_VALIDRECTS
WVR_VALIDRECTS  0x0400  winuser.h


XCLASS_BOOL
XCLASS_BOOL  0x1000  ddeml.h

A DDE callback function should return TRUE or FALSE when it finishes processing a transaction that belongs to this class. The XCLASS_BOOL transaction types consist of the following: See DdeCallback.


FN_XCLASS_BOOL
XCLASS_BOOL  0x1000  ddeml.h


XCLASS_DATA
XCLASS_DATA  0x2000  ddeml.h

A DDE callback function should return a DDE data handle, CBR_BLOCK, or NULL when it finishes processing a transaction that belongs to this class. The XCLASS_DATA transaction types consist of the following: See DdeCallback.


FN_XCLASS_DATA
XCLASS_DATA  0x2000  ddeml.h


XCLASS_FLAGS
XCLASS_FLAGS  0x4000  ddeml.h

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 types consist of the following: See DdeCallback.


FN_XCLASS_FLAGS
XCLASS_FLAGS  0x4000  ddeml.h


XCLASS_NOTIFICATION
XCLASS_NOTIFICATION  0x8000  ddeml.h

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 types consist of the following: See DdeCallback.


FN_XCLASS_NOTIFICATION
XCLASS_NOTIFICATION  0x8000  ddeml.h


XST_ADVACKRCVD
XST_ADVACKRCVD  13  ddeml.h

The advise transaction was just completed. See CONVINFO.


FN_XST_ADVACKRCVD
XST_ADVACKRCVD  13  ddeml.h


XST_ADVDATAACKRCVD
XST_ADVDATAACKRCVD  16  ddeml.h

The advise data transaction was just completed. See CONVINFO.


FN_XST_ADVDATAACKRCVD
XST_ADVDATAACKRCVD  16  ddeml.h


XST_ADVDATASENT
XST_ADVDATASENT  15  ddeml.h

Advise data has been sent and is awaiting an acknowledgement. See CONVINFO.


FN_XST_ADVDATASENT
XST_ADVDATASENT  15  ddeml.h


XST_ADVSENT
XST_ADVSENT  11  ddeml.h

An advise transaction is awaiting an acknowledgement. See CONVINFO.


FN_XST_ADVSENT
XST_ADVSENT  11  ddeml.h


XST_CONNECTED
XST_CONNECTED  2  ddeml.h

The conversation has no active transactions. See CONVINFO.


FN_XST_CONNECTED
XST_CONNECTED  2  ddeml.h


XST_DATARCVD
XST_DATARCVD  6  ddeml.h

The requested data has just been received. See CONVINFO.


FN_XST_DATARCVD
XST_DATARCVD  6  ddeml.h


XST_EXECACKRCVD
XST_EXECACKRCVD  10  ddeml.h

An execute transaction just completed. See CONVINFO.


FN_XST_EXECACKRCVD
XST_EXECACKRCVD  10  ddeml.h


XST_EXECSENT
XST_EXECSENT  9  ddeml.h

An execute transaction is awaiting an acknowledgement. See CONVINFO.


FN_XST_EXECSENT
XST_EXECSENT  9  ddeml.h


XST_INCOMPLETE
XST_INCOMPLETE  1  ddeml.h

The last transaction failed. See CONVINFO.


FN_XST_INCOMPLETE
XST_INCOMPLETE  1  ddeml.h


XST_INIT1
XST_INIT1  3  ddeml.h

Mid-initiate state 1. See CONVINFO.


FN_XST_INIT1
XST_INIT1  3  ddeml.h


XST_INIT2
XST_INIT2  4  ddeml.h

Mid-initiate state 2. See CONVINFO.


FN_XST_INIT2
XST_INIT2  4  ddeml.h


XST_NULL
XST_NULL  0  ddeml.h

Pre-initiate state. See CONVINFO.


FN_XST_NULL
XST_NULL  0  ddeml.h


XST_POKEACKRCVD
XST_POKEACKRCVD  8  ddeml.h

A poke transaction was just completed. See CONVINFO.


FN_XST_POKEACKRCVD
XST_POKEACKRCVD  8  ddeml.h


XST_POKESENT
XST_POKESENT  7  ddeml.h

A poke transaction is awaiting an acknowledgement. See CONVINFO.


FN_XST_POKESENT
XST_POKESENT  7  ddeml.h


XST_REQSENT
XST_REQSENT  5  ddeml.h

A request transaction is awaiting an acknowledgement. See CONVINFO.


FN_XST_REQSENT
XST_REQSENT  5  ddeml.h


XST_UNADVACKRCVD
XST_UNADVACKRCVD  14  ddeml.h

An unadvise transaction just completed. See CONVINFO.


FN_XST_UNADVACKRCVD
XST_UNADVACKRCVD  14  ddeml.h


XST_UNADVSENT
XST_UNADVSENT  12  ddeml.h

An unadvise transaction is awaiting an acknowledgement. See CONVINFO.


FN_XST_UNADVSENT
XST_UNADVSENT  12  ddeml.h


XTYPF_ACKREQ
XTYPF_ACKREQ  0x0008  ddeml.h

Instructs the server to wait until the client acknowledges 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. See DdeClientTransaction.


FN_XTYPF_ACKREQ
XTYPF_ACKREQ  0x0008  ddeml.h


XTYPF_NODATA
XTYPF_NODATA  0x0004  ddeml.h

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. See DdeClientTransaction.


FN_XTYPF_NODATA
XTYPF_NODATA  0x0004  ddeml.h


_CONTEXT
_CONTEXT _CONTEXT64  winnt.h


_QUAD_FLAGS_OFFSET
_QUAD_FLAGS_OFFSET HighFir  winnt.h


_QUAD_PSR_OFFSET
_QUAD_PSR_OFFSET HighSoftFpcr  winnt.h


_XFORM_
_XFORM_ nothing  wingdi.h


ABORTDOC
ABORTDOC 2  wingdi.h


ABSOLUTE
ABSOLUTE 1  wingdi.h


ACCESS_SYSTEM_SECURITY
ACCESS_SYSTEM_SECURITY (0x01000000L)  winnt.h


ACL_REVISION
ACL_REVISION (2)  winnt.h


ACL_REVISION1
ACL_REVISION1 (1)  winnt.h


ACL_REVISION2
ACL_REVISION2 (2)  winnt.h


AF_APPLETALK
AF_APPLETALK 16  winsock.h


AF_CCITT
AF_CCITT 10  winsock.h


AF_CHAOS
AF_CHAOS 5  winsock.h


AF_DATAKIT
AF_DATAKIT 9  winsock.h


AF_DECnet
AF_DECnet 12  winsock.h


AF_DLI
AF_DLI 13  winsock.h


AF_ECMA
AF_ECMA 8  winsock.h


AF_HYLINK
AF_HYLINK 15  winsock.h


AF_IMPLINK
AF_IMPLINK 3  winsock.h


AF_INET
AF_INET 2  winsock.h


AF_IPX
AF_IPX 6  winsock.h


AF_ISO
AF_ISO 7  winsock.h


AF_LAT
AF_LAT 14  winsock.h


AF_MAX
AF_MAX 18  winsock.h


AF_NETBIOS
AF_NETBIOS 17  winsock.h


AF_NS
AF_NS 6  winsock.h


AF_OSI
AF_OSI AF_ISO  winsock.h


AF_PUP
AF_PUP 4  winsock.h


AF_SNA
AF_SNA 11  winsock.h


AF_UNIX
AF_UNIX 1  winsock.h


AF_UNSPEC
AF_UNSPEC 0  winsock.h


ALL_TRANSPORTS
ALL_TRANSPORTS "M000"  nb30.h


ANSI_CHARSET
ANSI_CHARSET 0  wingdi.h


ANYSIZE_ARRAY
ANYSIZE_ARRAY 1  winnt.h


APIENTRY
APIENTRY WINAPI  windef.h


APIENTRY
APIENTRY WINAPI  windef.h


APIPRIVATE
APIPRIVATE __stdcall  windef.h


APIPRIVATE
APIPRIVATE nothing  windef.h


APPCLASS_MASK
APPCLASS_MASK 0x0000000FL  ddeml.h


APPCMD_MASK
APPCMD_MASK 0x00000FF0L  ddeml.h


APPLICATION_ERROR_MASK
APPLICATION_ERROR_MASK 0x20000000  winnt.h


APPNAMEBUFFERLEN
APPNAMEBUFFERLEN 40  scrnsave.h


ASPECT_FILTERING
ASPECT_FILTERING 0x0001  wingdi.h


ASYNCH
ASYNCH 0x80  nb30.h


BACKGROUND_BLUE
BACKGROUND_BLUE 0x0010  wincon.h


BACKGROUND_GREEN
BACKGROUND_GREEN 0x0020  wincon.h


BACKGROUND_INTENSITY
BACKGROUND_INTENSITY 0x0080  wincon.h


BACKGROUND_RED
BACKGROUND_RED 0x0040  wincon.h


BANDINFO
BANDINFO 24  wingdi.h


BAR_CHAR
BAR_CHAR "|"  nddeapi.h


BAR_WCHAR
BAR_WCHAR L"|"  nddeapi.h


BEGIN_PATH
BEGIN_PATH 4096  wingdi.h


BI_BITFIELDS
BI_BITFIELDS 3L  wingdi.h


BKMODE_LAST
BKMODE_LAST 2  wingdi.h


BOLD_FONTTYPE
BOLD_FONTTYPE 0x0100  commdlg.h


BS_3STATE
BS_3STATE 0x05L  winuser.h


BS_AUTO3STATE
BS_AUTO3STATE 0x06L  winuser.h


BS_AUTOCHECKBOX
BS_AUTOCHECKBOX 0x03L  winuser.h


BS_AUTORADIOBUTTON
BS_AUTORADIOBUTTON 0x09L  winuser.h


BS_CHECKBOX
BS_CHECKBOX 0x02L  winuser.h


BS_DEFPUSHBUTTON
BS_DEFPUSHBUTTON 0x01L  winuser.h


BS_DIBPATTERN8X8
BS_DIBPATTERN8X8 8  wingdi.h


BS_DIBPATTERNPT
BS_DIBPATTERNPT 6  wingdi.h


BS_GROUPBOX
BS_GROUPBOX 0x07L  winuser.h


BS_INDEXED
BS_INDEXED 4  wingdi.h


BS_LEFTTEXT
BS_LEFTTEXT 0x20L  winuser.h


BS_OWNERDRAW
BS_OWNERDRAW 0x0BL  winuser.h


BS_PATTERN8X8
BS_PATTERN8X8 7  wingdi.h


BS_PUSHBUTTON
BS_PUSHBUTTON 0x00L  winuser.h


BS_RADIOBUTTON
BS_RADIOBUTTON 0x04L  winuser.h


BS_USERBUTTON
BS_USERBUTTON 0x08L  winuser.h


BUFFLEN
BUFFLEN 255  scrnsave.h


C1_ALPHA
C1_ALPHA 0x0100  winnls.h


C1_BLANK
C1_BLANK 0x0040  winnls.h


C1_CNTRL
C1_CNTRL 0x0020  winnls.h


C1_DIGIT
C1_DIGIT 0x0004  winnls.h


C1_LOWER
C1_LOWER 0x0002  winnls.h


C1_PUNCT
C1_PUNCT 0x0010  winnls.h


C1_SPACE
C1_SPACE 0x0008  winnls.h


C1_TRANSPARENT
C1_TRANSPARENT 0x0001  mmsystem.h


C1_UPPER
C1_UPPER 0x0001  winnls.h


C1_XDIGIT
C1_XDIGIT 0x0080  winnls.h


C2_ARABICNUMBER
C2_ARABICNUMBER 0x0006  winnls.h


C2_BLOCKSEPARATOR
C2_BLOCKSEPARATOR 0x0008  winnls.h


C2_COMMONSEPARATOR
C2_COMMONSEPARATOR 0x0007  winnls.h


C2_EUROPENUMBER
C2_EUROPENUMBER 0x0003  winnls.h


C2_EUROPESEPARATOR
C2_EUROPESEPARATOR 0x0004  winnls.h


C2_EUROPETERMINATOR
C2_EUROPETERMINATOR 0x0005  winnls.h


C2_LEFTTORIGHT
C2_LEFTTORIGHT 0x0001  winnls.h


C2_NOTAPPLICABLE
C2_NOTAPPLICABLE 0x0000  winnls.h


C2_OTHERNEUTRAL
C2_OTHERNEUTRAL 0x000B  winnls.h


C2_RIGHTTOLEFT
C2_RIGHTTOLEFT 0x0002  winnls.h


C2_SEGMENTSEPARATOR
C2_SEGMENTSEPARATOR 0x0009  winnls.h


C2_WHITESPACE
C2_WHITESPACE 0x000A  winnls.h


C3_DIACRITIC
C3_DIACRITIC 0x0002  winnls.h


C3_NONSPACING
C3_NONSPACING 0x0001  winnls.h


C3_NOTAPPLICABLE
C3_NOTAPPLICABLE 0x0000  winnls.h


C3_SYMBOL
C3_SYMBOL 0x0008  winnls.h


C3_VOWELMARK
C3_VOWELMARK 0x0004  winnls.h


CA_LOG_FILTER
CA_LOG_FILTER 0x0002  wingdi.h


CA_NEGATIVE
CA_NEGATIVE 0x0001  wingdi.h


CADV_LATEACK
CADV_LATEACK 0xFFFF  ddeml.h


CALLBACK_NULL
CALLBACK_NULL 0x00000000l  mmsystem.h


CALLBACK_TASK
CALLBACK_TASK 0x00020000l  mmsystem.h


CALLBACK_TYPEMASK
CALLBACK_TYPEMASK 0x00070000l  mmsystem.h


CAPS1
CAPS1 94  mmsystem.h


CBM_CREATEDIB
CBM_CREATEDIB 0x02L  wingdi.h


CBM_INIT
CBM_INIT 0x04L  wingdi.h


CBR_110
CBR_110 110  winbase.h


CBR_115200
CBR_115200 115200  winbase.h


CBR_1200
CBR_1200 1200  winbase.h


CBR_128000
CBR_128000 128000  winbase.h


CBR_14400
CBR_14400 14400  winbase.h


CBR_19200
CBR_19200 19200  winbase.h


CBR_2400
CBR_2400 2400  winbase.h


CBR_256000
CBR_256000 256000  winbase.h


CBR_300
CBR_300 300  winbase.h


CBR_38400
CBR_38400 38400  winbase.h


CBR_4800
CBR_4800 4800  winbase.h


CBR_56000
CBR_56000 56000  winbase.h


CBR_57600
CBR_57600 57600  winbase.h


CBR_600
CBR_600 600  winbase.h


CBR_9600
CBR_9600 9600  winbase.h


CBR_BLOCK
CBR_BLOCK 0xffffffffL  ddeml.h


CBS_AUTOHSCROLL
CBS_AUTOHSCROLL 0x0040L  winuser.h


CBS_DISABLENOSCROLL
CBS_DISABLENOSCROLL 0x0800L  winuser.h


CBS_DROPDOWN
CBS_DROPDOWN 0x0002L  winuser.h


CBS_DROPDOWNLIST
CBS_DROPDOWNLIST 0x0003L  winuser.h


CBS_HASSTRINGS
CBS_HASSTRINGS 0x0200L  winuser.h


CBS_NOINTEGRALHEIGHT
CBS_NOINTEGRALHEIGHT 0x0400L  winuser.h


CBS_OEMCONVERT
CBS_OEMCONVERT 0x0080L  winuser.h


CBS_OWNERDRAWFIXED
CBS_OWNERDRAWFIXED 0x0010L  winuser.h


CBS_OWNERDRAWVARIABLE
CBS_OWNERDRAWVARIABLE 0x0020L  winuser.h


CBS_SIMPLE
CBS_SIMPLE 0x0001L  winuser.h


CBS_SORT
CBS_SORT 0x0100L  winuser.h


CC_CHORD
CC_CHORD 4  wingdi.h


CC_CIRCLES
CC_CIRCLES 1  wingdi.h


CC_ELLIPSES
CC_ELLIPSES 8  wingdi.h


CC_INTERIORS
CC_INTERIORS 128  wingdi.h


CC_NONE
CC_NONE 0  wingdi.h


CC_PIE
CC_PIE 2  wingdi.h


CC_ROUNDRECT
CC_ROUNDRECT 256  wingdi.h


CC_STYLED
CC_STYLED 32  wingdi.h


CC_WIDE
CC_WIDE 16  wingdi.h


CC_WIDESTYLED
CC_WIDESTYLED 64  wingdi.h


CCERR_CHOOSECOLORCODES
CCERR_CHOOSECOLORCODES 0x5000  cderr.h


CCHDEVICENAME
CCHDEVICENAME 32  wingdi.h


CCHFORMNAME
CCHFORMNAME 32  wingdi.h


CD_LBSELADD
CD_LBSELADD 2  commdlg.h


CD_LBSELCHANGE
CD_LBSELCHANGE 0  commdlg.h


CD_LBSELNOITEMS
CD_LBSELNOITEMS -1  commdlg.h


CD_LBSELSUB
CD_LBSELSUB 1  commdlg.h


CDERR_DIALOGFAILURE
CDERR_DIALOGFAILURE 0xFFFF  cderr.h


CDERR_GENERALCODES
CDERR_GENERALCODES 0x0000  cderr.h


CE_BREAK
CE_BREAK 0x0010  winbase.h


CE_DNS
CE_DNS 0x0800  winbase.h


CE_FRAME
CE_FRAME 0x0008  winbase.h


CE_IOE
CE_IOE 0x0400  winbase.h


CE_MODE
CE_MODE 0x8000  winbase.h


CE_OOP
CE_OOP 0x1000  winbase.h


CE_OVERRUN
CE_OVERRUN 0x0002  winbase.h


CE_PTO
CE_PTO 0x0200  winbase.h


CE_RXOVER
CE_RXOVER 0x0001  winbase.h


CE_RXPARITY
CE_RXPARITY 0x0004  winbase.h


CE_TXFULL
CE_TXFULL 0x0100  winbase.h


CF_RIFF
CF_RIFF 11  winuser.h


CF_WAVE
CF_WAVE 12  winuser.h


CFERR_CHOOSEFONTCODES
CFERR_CHOOSEFONTCODES 0x2000  cderr.h


CFSEPCHAR
CFSEPCHAR '+'  mmsystem.h


CHINESEBIG5_CHARSET
CHINESEBIG5_CHARSET 136  wingdi.h


CLIP_CHARACTER_PRECIS
CLIP_CHARACTER_PRECIS 1  wingdi.h


CLIP_DEFAULT_PRECIS
CLIP_DEFAULT_PRECIS 0  wingdi.h


CLIP_EMBEDDED
CLIP_EMBEDDED (8<<4)  wingdi.h


CLIP_LH_ANGLES
CLIP_LH_ANGLES (1<<4)  wingdi.h


CLIP_MASK
CLIP_MASK 0xf  wingdi.h


CLIP_STROKE_PRECIS
CLIP_STROKE_PRECIS 2  wingdi.h


CLIP_TO_PATH
CLIP_TO_PATH 4097  wingdi.h


CLIP_TT_ALWAYS
CLIP_TT_ALWAYS (2<<4)  wingdi.h


CLOSECHANNEL
CLOSECHANNEL 4112  wingdi.h


CLR_INVALID
CLR_INVALID 0xFFFFFFFF  wingdi.h


CLRBREAK
CLRBREAK 9  winbase.h


CLRDTR
CLRDTR 6  winbase.h


CLRRTS
CLRRTS 4  winbase.h


CNLEN
CNLEN 15  nddeapi.h


COLOR_ADJ_MAX
COLOR_ADJ_MAX (SHORT)100  wingdi.h


COLOR_ADJ_MIN
COLOR_ADJ_MIN (SHORT)-100  wingdi.h


COLOR_BTNHIGHLIGHT
COLOR_BTNHIGHLIGHT 20  winuser.h


COLOROKSTRING
COLOROKSTRING COLOROKSTRINGA  commdlg.h


COLOROKSTRING
COLOROKSTRING COLOROKSTRINGW  commdlg.h


COLOROKSTRINGA
COLOROKSTRINGA "commdlg_ColorOK"  commdlg.h


COLOROKSTRINGW
COLOROKSTRINGW L"commdlg_ColorOK"  commdlg.h


CONSOLE_TEXTMODE_BUFFER
CONSOLE_TEXTMODE_BUFFER 1  wincon.h


CONST
CONST const  windef.h


CONTEXT_CONTROL
CONTEXT_CONTROL (CONTEXT_ALPHA | 0x00000001L)  winnt.h


CONTEXT_CONTROL
CONTEXT_CONTROL (CONTEXT_i386 | 0x00000001L)  winnt.h


CONTEXT_CONTROL
CONTEXT_CONTROL (CONTEXT_R3000 | 0x00000001L)  winnt.h


CONTEXT_DEBUG_REGISTERS
CONTEXT_DEBUG_REGISTERS (CONTEXT_i386 | 0x00000010L)  winnt.h


CONTEXT_FLOATING_POINT
CONTEXT_FLOATING_POINT (CONTEXT_ALPHA | 0x00000002L)  winnt.h


CONTEXT_FLOATING_POINT
CONTEXT_FLOATING_POINT (CONTEXT_i386 | 0x00000008L)  winnt.h


CONTEXT_FLOATING_POINT
CONTEXT_FLOATING_POINT (CONTEXT_R3000 | 0x00000002L)  winnt.h


CONTEXT_FULL
CONTEXT_FULL (CONTEXT_CONTROL | CONTEXT_FLOATING_POINT | CONTEXT_INTEGER)  winnt.h


CONTEXT_FULL
CONTEXT_FULL (CONTEXT_CONTROL | CONTEXT_FLOATING_POINT | CONTEXT_INTEGER)  winnt.h


CONTEXT_FULL
CONTEXT_FULL (CONTEXT_CONTROL | CONTEXT_INTEGER | CONTEXT_SEGMENTS)  winnt.h


CONTEXT_i386
CONTEXT_i386 0x00010000  winnt.h


CONTEXT_i486
CONTEXT_i486 0x00010000  winnt.h


CONTEXT_INTEGER
CONTEXT_INTEGER (CONTEXT_ALPHA | 0x00000004L)  winnt.h


CONTEXT_INTEGER
CONTEXT_INTEGER (CONTEXT_i386 | 0x00000002L)  winnt.h


CONTEXT_INTEGER
CONTEXT_INTEGER (CONTEXT_R3000 | 0x00000004L)  winnt.h


CONTEXT_PORTABLE_32BIT
CONTEXT_PORTABLE_32BIT 0x00100000  winnt.h


CONTEXT_R3000
CONTEXT_R3000 0x00010000  winnt.h


CONTEXT_R4000
CONTEXT_R4000 0x00010000  winnt.h


CONTEXT_SEGMENTS
CONTEXT_SEGMENTS (CONTEXT_i386 | 0x00000004L)  winnt.h


CONTROL_C_EXIT
CONTROL_C_EXIT STATUS_CONTROL_C_EXIT  winbase.h


CP_NONE
CP_NONE 0  wingdi.h


CP_RECTANGLE
CP_RECTANGLE 1  wingdi.h


CP_REGION
CP_REGION 2  wingdi.h


CP_WINANSI
CP_WINANSI 1004  ddeml.h


CP_WINUNICODE
CP_WINUNICODE 1200  ddeml.h


CS_KEYCVTWINDOW
CS_KEYCVTWINDOW 0x0004  winuser.h


CS_NOKEYCVT
CS_NOKEYCVT 0x0100  winuser.h


CT_CTYPE1
CT_CTYPE1 0x00000001  winnls.h


CT_CTYPE2
CT_CTYPE2 0x00000002  winnls.h


CT_CTYPE3
CT_CTYPE3 0x00000004  winnls.h


CTLCOLOR_BTN
CTLCOLOR_BTN 3  winuser.h


CTLCOLOR_DLG
CTLCOLOR_DLG 4  winuser.h


CTLCOLOR_EDIT
CTLCOLOR_EDIT 1  winuser.h


CTLCOLOR_LISTBOX
CTLCOLOR_LISTBOX 2  winuser.h


CTLCOLOR_MAX
CTLCOLOR_MAX 8  winuser.h


CTLCOLOR_MSGBOX
CTLCOLOR_MSGBOX 0  winuser.h


CTLCOLOR_SCROLLBAR
CTLCOLOR_SCROLLBAR 5  winuser.h


CTLCOLOR_STATIC
CTLCOLOR_STATIC 6  winuser.h


CTRL_CLOSE_EVENT
CTRL_CLOSE_EVENT 2  wincon.h


CTRL_LOGOFF_EVENT
CTRL_LOGOFF_EVENT 5  wincon.h


CTRL_SHUTDOWN_EVENT
CTRL_SHUTDOWN_EVENT 6  wincon.h


CTRY_AUSTRALIA
CTRY_AUSTRALIA 61  winnls.h


CTRY_AUSTRIA
CTRY_AUSTRIA 43  winnls.h


CTRY_BELGIUM
CTRY_BELGIUM 32  winnls.h


CTRY_BRAZIL
CTRY_BRAZIL 55  winnls.h


CTRY_CANADA
CTRY_CANADA 2  winnls.h


CTRY_DEFAULT
CTRY_DEFAULT 0  winnls.h


CTRY_DENMARK
CTRY_DENMARK 45  winnls.h


CTRY_FINLAND
CTRY_FINLAND 358  winnls.h


CTRY_FRANCE
CTRY_FRANCE 33  winnls.h


CTRY_GERMANY
CTRY_GERMANY 49  winnls.h


CTRY_ICELAND
CTRY_ICELAND 354  winnls.h


CTRY_IRELAND
CTRY_IRELAND 353  winnls.h


CTRY_ITALY
CTRY_ITALY 39  winnls.h


CTRY_JAPAN
CTRY_JAPAN 81  winnls.h


CTRY_MEXICO
CTRY_MEXICO 52  winnls.h


CTRY_NETHERLANDS
CTRY_NETHERLANDS 31  winnls.h


CTRY_NEW_ZEALAND
CTRY_NEW_ZEALAND 64  winnls.h


CTRY_NORWAY
CTRY_NORWAY 47  winnls.h


CTRY_PORTUGAL
CTRY_PORTUGAL 351  winnls.h


CTRY_PRCHINA
CTRY_PRCHINA 86  winnls.h


CTRY_SOUTH_KOREA
CTRY_SOUTH_KOREA 82  winnls.h


CTRY_SPAIN
CTRY_SPAIN 34  winnls.h


CTRY_SWEDEN
CTRY_SWEDEN 46  winnls.h


CTRY_SWITZERLAND
CTRY_SWITZERLAND 41  winnls.h


CTRY_TAIWAN
CTRY_TAIWAN 886  winnls.h


CTRY_UNITED_KINGDOM
CTRY_UNITED_KINGDOM 44  winnls.h


CTRY_UNITED_STATES
CTRY_UNITED_STATES 1  winnls.h


CW_USEDEFAULT
CW_USEDEFAULT 0x8000000  winuser.h


DATE_LONGDATE
DATE_LONGDATE 0x00000002  winnls.h


DATE_SHORTDATE
DATE_SHORTDATE 0x00000001  winnls.h


DC_COPIES
DC_COPIES 18  wingdi.h


DC_HASDEFID
DC_HASDEFID 0x534B  winuser.h


DC_ORIENTATION
DC_ORIENTATION 17  wingdi.h


DC_PAPERNAMES
DC_PAPERNAMES 16  wingdi.h


DC_TRUETYPE
DC_TRUETYPE 15  wingdi.h


DCB_DIRTY
DCB_DIRTY DCB_ACCUMULATE  wingdi.h


DCX_EXCLUDEUPDATE
DCX_EXCLUDEUPDATE 0x00000100L  winuser.h


DCX_INTERSECTUPDATE
DCX_INTERSECTUPDATE 0x00000200L  winuser.h


DDE_FACK
DDE_FACK 0x8000  ddeml.h


DDE_FACKREQ
DDE_FACKREQ 0x8000  ddeml.h


DDE_FAPPSTATUS
DDE_FAPPSTATUS 0x00ff  ddeml.h


DDE_FBUSY
DDE_FBUSY 0x4000  ddeml.h


DDE_FDEFERUPD
DDE_FDEFERUPD 0x4000  ddeml.h


DDE_FNOTPROCESSED
DDE_FNOTPROCESSED 0x0000  ddeml.h


DDE_FRELEASE
DDE_FRELEASE 0x2000  ddeml.h


DDE_FREQUESTED
DDE_FREQUESTED 0x1000  ddeml.h


DEF_PRIORITY
DEF_PRIORITY 1  winspool.h


DEFAULT_CHARSET
DEFAULT_CHARSET 1  wingdi.h


DEFAULT_IMPERSONATION_LEVEL
DEFAULT_IMPERSONATION_LEVEL SecurityImpersonation  winnt.h


DEFAULT_PITCH
DEFAULT_PITCH 0  wingdi.h


DELETE
DELETE (0x00010000L)  winnt.h


DESKTOP_CREATEMENU
DESKTOP_CREATEMENU 0x0004L  winuser.h


DESKTOP_CREATEWINDOW
DESKTOP_CREATEWINDOW 0x0002L  winuser.h


DESKTOP_ENUMERATE
DESKTOP_ENUMERATE 0x0040L  winuser.h


DESKTOP_HOOKCONTROL
DESKTOP_HOOKCONTROL 0x0008L  winuser.h


DESKTOP_JOURNALPLAYBACK
DESKTOP_JOURNALPLAYBACK 0x0020L  winuser.h


DESKTOP_JOURNALRECORD
DESKTOP_JOURNALRECORD 0x0010L  winuser.h


DESKTOP_READOBJECTS
DESKTOP_READOBJECTS 0x0001L  winuser.h


DESKTOP_WRITEOBJECTS
DESKTOP_WRITEOBJECTS 0x0080L  winuser.h


DEVICE_FONTTYPE
DEVICE_FONTTYPE 0x002  wingdi.h


DEVICE_TYPE
DEVICE_TYPE DWORD  winioctl.h


DEVICEDATA
DEVICEDATA 19  wingdi.h


DIB_PAL_LOGINDICES
DIB_PAL_LOGINDICES 4  wingdi.h


DIB_PAL_PHYSINDICES
DIB_PAL_PHYSINDICES 2  wingdi.h


DIFFERENCE
DIFFERENCE 11  winuser.h


DLG_SCRNSAVECONFIGURE
DLG_SCRNSAVECONFIGURE 2003  scrnsave.h


DLL_PROCESS_ATTACH
DLL_PROCESS_ATTACH 1  winnt.h


DLL_PROCESS_DETACH
DLL_PROCESS_DETACH 0  winnt.h


DLL_THREAD_ATTACH
DLL_THREAD_ATTACH 2  winnt.h


DLL_THREAD_DETACH
DLL_THREAD_DETACH 3  winnt.h


DM_COLLATE
DM_COLLATE 0x0008000L  wingdi.h


DM_COLOR
DM_COLOR 0x0000800L  wingdi.h


DM_COPIES
DM_COPIES 0x0000100L  wingdi.h


DM_COPY
DM_COPY 2  windef.h


DM_COPY
DM_COPY 2  wingdi.h


DM_DEFAULTSOURCE
DM_DEFAULTSOURCE 0x0000200L  wingdi.h


DM_DUPLEX
DM_DUPLEX 0x0001000L  wingdi.h


DM_FORMNAME
DM_FORMNAME 0x0010000L  wingdi.h


DM_GETDEFID
DM_GETDEFID (WM_USER+0)  winuser.h


DM_GRAYSCALE
DM_GRAYSCALE 0x00000001  wingdi.h


DM_IN_BUFFER
DM_IN_BUFFER DM_MODIFY  windef.h


DM_IN_BUFFER
DM_IN_BUFFER DM_MODIFY  wingdi.h


DM_IN_PROMPT
DM_IN_PROMPT DM_PROMPT  windef.h


DM_IN_PROMPT
DM_IN_PROMPT DM_PROMPT  wingdi.h


DM_MODIFY
DM_MODIFY 8  windef.h


DM_MODIFY
DM_MODIFY 8  wingdi.h


DM_ORIENTATION
DM_ORIENTATION 0x0000001L  wingdi.h


DM_OUT_BUFFER
DM_OUT_BUFFER DM_COPY  windef.h


DM_OUT_BUFFER
DM_OUT_BUFFER DM_COPY  wingdi.h


DM_OUT_DEFAULT
DM_OUT_DEFAULT DM_UPDATE  windef.h


DM_OUT_DEFAULT
DM_OUT_DEFAULT DM_UPDATE  wingdi.h


DM_PAPERLENGTH
DM_PAPERLENGTH 0x0000004L  wingdi.h


DM_PAPERSIZE
DM_PAPERSIZE 0x0000002L  wingdi.h


DM_PAPERWIDTH
DM_PAPERWIDTH 0x0000008L  wingdi.h


DM_PRINTQUALITY
DM_PRINTQUALITY 0x0000400L  wingdi.h


DM_PROMPT
DM_PROMPT 4  windef.h


DM_PROMPT
DM_PROMPT 4  wingdi.h


DM_SCALE
DM_SCALE 0x0000010L  wingdi.h


DM_SETDEFID
DM_SETDEFID (WM_USER+1)  winuser.h


DM_SPECVERSION
DM_SPECVERSION 0x320  wingdi.h


DM_TTOPTION
DM_TTOPTION 0x0004000L  wingdi.h


DM_UPDATE
DM_UPDATE 1  windef.h


DM_UPDATE
DM_UPDATE 1  wingdi.h


DM_YRESOLUTION
DM_YRESOLUTION 0x0002000L  wingdi.h


DMBIN_AUTO
DMBIN_AUTO 7  wingdi.h


DMBIN_CASSETTE
DMBIN_CASSETTE 14  wingdi.h


DMBIN_ENVELOPE
DMBIN_ENVELOPE 5  wingdi.h


DMBIN_ENVMANUAL
DMBIN_ENVMANUAL 6  wingdi.h


DMBIN_FIRST
DMBIN_FIRST DMBIN_UPPER  wingdi.h


DMBIN_LARGECAPACITY
DMBIN_LARGECAPACITY 11  wingdi.h


DMBIN_LARGEFMT
DMBIN_LARGEFMT 10  wingdi.h


DMBIN_LAST
DMBIN_LAST DMBIN_CASSETTE  wingdi.h


DMBIN_LOWER
DMBIN_LOWER 2  wingdi.h


DMBIN_MANUAL
DMBIN_MANUAL 4  wingdi.h


DMBIN_MIDDLE
DMBIN_MIDDLE 3  wingdi.h


DMBIN_ONLYONE
DMBIN_ONLYONE 1  wingdi.h


DMBIN_SMALLFMT
DMBIN_SMALLFMT 9  wingdi.h


DMBIN_TRACTOR
DMBIN_TRACTOR 8  wingdi.h


DMBIN_UPPER
DMBIN_UPPER 1  wingdi.h


DMBIN_USER
DMBIN_USER 256  wingdi.h


DMCOLLATE_FALSE
DMCOLLATE_FALSE 0  wingdi.h


DMCOLLATE_TRUE
DMCOLLATE_TRUE 1  wingdi.h


DMCOLOR_COLOR
DMCOLOR_COLOR 2  wingdi.h


DMCOLOR_MONOCHROME
DMCOLOR_MONOCHROME 1  wingdi.h


DMDUP_HORIZONTAL
DMDUP_HORIZONTAL 3  wingdi.h


DMDUP_SIMPLEX
DMDUP_SIMPLEX 1  wingdi.h


DMDUP_VERTICAL
DMDUP_VERTICAL 2  wingdi.h


DMLERR_FIRST
DMLERR_FIRST 0x4000  ddeml.h


DMLERR_LAST
DMLERR_LAST 0x4011  ddeml.h


DMLERR_MEMORY_ERROR
DMLERR_MEMORY_ERROR 0x4008  ddeml.h


DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_CONV_ESTABLISHED 0x400a  ddeml.h


DMLERR_NO_ERROR
DMLERR_NO_ERROR 0  ddeml.h


DMLERR_NOTPROCESSED
DMLERR_NOTPROCESSED 0x4009  ddeml.h


DMLERR_POKEACKTIMEOUT
DMLERR_POKEACKTIMEOUT 0x400b  ddeml.h


DMLERR_POSTMSG_FAILED
DMLERR_POSTMSG_FAILED 0x400c  ddeml.h


DMLERR_REENTRANCY
DMLERR_REENTRANCY 0x400d  ddeml.h


DMLERR_SERVER_DIED
DMLERR_SERVER_DIED 0x400e  ddeml.h


DMLERR_SYS_ERROR
DMLERR_SYS_ERROR 0x400f  ddeml.h


DMLERR_UNADVACKTIMEOUT
DMLERR_UNADVACKTIMEOUT 0x4010  ddeml.h


DMLERR_UNFOUND_QUEUE_ID
DMLERR_UNFOUND_QUEUE_ID 0x4011  ddeml.h


DMORIENT_LANDSCAPE
DMORIENT_LANDSCAPE 2  wingdi.h


DMORIENT_PORTRAIT
DMORIENT_PORTRAIT 1  wingdi.h


DMPAPER_10X14
DMPAPER_10X14 16  wingdi.h


DMPAPER_11X17
DMPAPER_11X17 17  wingdi.h


DMPAPER_A3
DMPAPER_A3 8  wingdi.h


DMPAPER_A4SMALL
DMPAPER_A4SMALL 10  wingdi.h


DMPAPER_A5
DMPAPER_A5 11  wingdi.h


DMPAPER_B4
DMPAPER_B4 12  wingdi.h


DMPAPER_B5
DMPAPER_B5 13  wingdi.h


DMPAPER_ENV_B4
DMPAPER_ENV_B4 33  wingdi.h


DMPAPER_ENV_B5
DMPAPER_ENV_B5 34  wingdi.h


DMPAPER_ENV_B6
DMPAPER_ENV_B6 35  wingdi.h


DMPAPER_ENV_C3
DMPAPER_ENV_C3 29  wingdi.h


DMPAPER_ENV_C4
DMPAPER_ENV_C4 30  wingdi.h


DMPAPER_ENV_C5
DMPAPER_ENV_C5 28  wingdi.h


DMPAPER_ENV_C6
DMPAPER_ENV_C6 31  wingdi.h


DMPAPER_ENV_C65
DMPAPER_ENV_C65 32  wingdi.h


DMPAPER_ENV_DL
DMPAPER_ENV_DL 27  wingdi.h


DMPAPER_ENV_ITALY
DMPAPER_ENV_ITALY 36  wingdi.h


DMPAPER_ENV_MONARCH
DMPAPER_ENV_MONARCH 37  wingdi.h


DMPAPER_ENV_PERSONAL
DMPAPER_ENV_PERSONAL 38  wingdi.h


DMPAPER_EXECUTIVE
DMPAPER_EXECUTIVE 7  wingdi.h


DMPAPER_FANFOLD_LGL_GERMAN
DMPAPER_FANFOLD_LGL_GERMAN 41  wingdi.h


DMPAPER_FANFOLD_STD_GERMAN
DMPAPER_FANFOLD_STD_GERMAN 40  wingdi.h


DMPAPER_FANFOLD_US
DMPAPER_FANFOLD_US 39  wingdi.h


DMPAPER_FIRST
DMPAPER_FIRST DMPAPER_LETTER  wingdi.h


DMPAPER_FOLIO
DMPAPER_FOLIO 14  wingdi.h


DMPAPER_LAST
DMPAPER_LAST DMPAPER_FANFOLD_LGL_GERMAN  wingdi.h


DMPAPER_LEDGER
DMPAPER_LEDGER 4  wingdi.h


DMPAPER_LETTERSMALL
DMPAPER_LETTERSMALL 2  wingdi.h


DMPAPER_NOTE
DMPAPER_NOTE 18  wingdi.h


DMPAPER_QUARTO
DMPAPER_QUARTO 15  wingdi.h


DMPAPER_STATEMENT
DMPAPER_STATEMENT 6  wingdi.h


DMPAPER_TABLOID
DMPAPER_TABLOID 3  wingdi.h


DMPAPER_USER
DMPAPER_USER 256  wingdi.h


DMRES_DRAFT
DMRES_DRAFT (-1)  wingdi.h


DMRES_HIGH
DMRES_HIGH (-4)  wingdi.h


DMRES_LOW
DMRES_LOW (-2)  wingdi.h


DMRES_MEDIUM
DMRES_MEDIUM (-3)  wingdi.h


DN_DEFAULTPRN
DN_DEFAULTPRN 0x0001  commdlg.h


DOMAIN_ALIAS_RID_ACCOUNT_OPS
DOMAIN_ALIAS_RID_ACCOUNT_OPS (0x00000224L)  winnt.h


DOMAIN_ALIAS_RID_ADMINS
DOMAIN_ALIAS_RID_ADMINS (0x00000220L)  winnt.h


DOMAIN_ALIAS_RID_BACKUP_OPS
DOMAIN_ALIAS_RID_BACKUP_OPS (0x00000227L)  winnt.h


DOMAIN_ALIAS_RID_GUESTS
DOMAIN_ALIAS_RID_GUESTS (0x00000222L)  winnt.h


DOMAIN_ALIAS_RID_POWER_USERS
DOMAIN_ALIAS_RID_POWER_USERS (0x00000223L)  winnt.h


DOMAIN_ALIAS_RID_PRINT_OPS
DOMAIN_ALIAS_RID_PRINT_OPS (0x00000226L)  winnt.h


DOMAIN_ALIAS_RID_REPLICATOR
DOMAIN_ALIAS_RID_REPLICATOR (0x00000228L)  winnt.h


DOMAIN_ALIAS_RID_SYSTEM_OPS
DOMAIN_ALIAS_RID_SYSTEM_OPS (0x00000225L)  winnt.h


DOMAIN_ALIAS_RID_USERS
DOMAIN_ALIAS_RID_USERS (0x00000221L)  winnt.h


DOMAIN_GROUP_RID_ADMINS
DOMAIN_GROUP_RID_ADMINS (0x00000200L)  winnt.h


DOMAIN_GROUP_RID_USERS
DOMAIN_GROUP_RID_USERS (0x00000201L)  winnt.h


DOMAIN_USER_RID_ADMIN
DOMAIN_USER_RID_ADMIN (0x000001F4L)  winnt.h


DOMAIN_USER_RID_GUEST
DOMAIN_USER_RID_GUEST (0x000001F5L)  winnt.h


DONT_RESOLVE_DLL_REFERENCES
DONT_RESOLVE_DLL_REFERENCES 0x00000001  winbase.h


DOWNLOADFACE
DOWNLOADFACE 514  wingdi.h


DOWNLOADHEADER
DOWNLOADHEADER 4111  wingdi.h


DRAFTMODE
DRAFTMODE 7  wingdi.h


DRAWPATTERNRECT
DRAWPATTERNRECT 25  wingdi.h


DRIVERVERSION
DRIVERVERSION 0  wingdi.h


DRV_CANCEL
DRV_CANCEL DRVCNF_CANCEL  mmsystem.h


DRV_CLOSE
DRV_CLOSE 0x0004  mmsystem.h


DRV_CONFIGURE
DRV_CONFIGURE 0x0007  mmsystem.h


DRV_DISABLE
DRV_DISABLE 0x0005  mmsystem.h


DRV_ENABLE
DRV_ENABLE 0x0002  mmsystem.h


DRV_EXITSESSION
DRV_EXITSESSION 0x000B  mmsystem.h


DRV_FREE
DRV_FREE 0x0006  mmsystem.h


DRV_INSTALL
DRV_INSTALL 0x0009  mmsystem.h


DRV_LOAD
DRV_LOAD 0x0001  mmsystem.h


DRV_MCI_FIRST
DRV_MCI_FIRST DRV_RESERVED  mmsystem.h


DRV_MCI_LAST
DRV_MCI_LAST (DRV_RESERVED + 0xFFF)  mmsystem.h


DRV_OK
DRV_OK DRVCNF_OK  mmsystem.h


DRV_OPEN
DRV_OPEN 0x0003  mmsystem.h


DRV_POWER
DRV_POWER 0x000F  mmsystem.h


DRV_QUERYCONFIGURE
DRV_QUERYCONFIGURE 0x0008  mmsystem.h


DRV_REMOVE
DRV_REMOVE 0x000A  mmsystem.h


DRV_RESERVED
DRV_RESERVED 0x0800  mmsystem.h


DRV_RESTART
DRV_RESTART DRVCNF_RESTART  mmsystem.h


DRV_USER
DRV_USER 0x4000  mmsystem.h


DRVCNF_CANCEL
DRVCNF_CANCEL 0x0000  mmsystem.h


DRVCNF_OK
DRVCNF_OK 0x0001  mmsystem.h


DRVCNF_RESTART
DRVCNF_RESTART 0x0002  mmsystem.h


DT_INTERNAL
DT_INTERNAL 0x1000  winuser.h


EADDRINUSE
EADDRINUSE WSAEADDRINUSE  winsock.h


EADDRNOTAVAIL
EADDRNOTAVAIL WSAEADDRNOTAVAIL  winsock.h


EAFNOSUPPORT
EAFNOSUPPORT WSAEAFNOSUPPORT  winsock.h


EALREADY
EALREADY WSAEALREADY  winsock.h


ECONNABORTED
ECONNABORTED WSAECONNABORTED  winsock.h


ECONNREFUSED
ECONNREFUSED WSAECONNREFUSED  winsock.h


ECONNRESET
ECONNRESET WSAECONNRESET  winsock.h


EDESTADDRREQ
EDESTADDRREQ WSAEDESTADDRREQ  winsock.h


EDQUOT
EDQUOT WSAEDQUOT  winsock.h


EHOSTDOWN
EHOSTDOWN WSAEHOSTDOWN  winsock.h


EHOSTUNREACH
EHOSTUNREACH WSAEHOSTUNREACH  winsock.h


EINPROGRESS
EINPROGRESS WSAEINPROGRESS  winsock.h


EISCONN
EISCONN WSAEISCONN  winsock.h


ELF_CULTURE_LATIN
ELF_CULTURE_LATIN 0  wingdi.h


ELF_VENDOR_SIZE
ELF_VENDOR_SIZE 4  wingdi.h


ELF_VERSION
ELF_VERSION 0  wingdi.h


ELOOP
ELOOP WSAELOOP  winsock.h


EMR_ANGLEARC
EMR_ANGLEARC 41  wingdi.h


EMR_ARC
EMR_ARC 45  wingdi.h


EMR_ARCTO
EMR_ARCTO 55  wingdi.h


EMR_BEGINPATH
EMR_BEGINPATH 59  wingdi.h


EMR_BITBLT
EMR_BITBLT 76  wingdi.h


EMR_CHORD
EMR_CHORD 46  wingdi.h


EMR_CLOSEFIGURE
EMR_CLOSEFIGURE 61  wingdi.h


EMR_CREATEBRUSHINDIRECT
EMR_CREATEBRUSHINDIRECT 39  wingdi.h


EMR_CREATEDIBPATTERNBRUSHPT
EMR_CREATEDIBPATTERNBRUSHPT 94  wingdi.h


EMR_CREATEMONOBRUSH
EMR_CREATEMONOBRUSH 93  wingdi.h


EMR_CREATEPALETTE
EMR_CREATEPALETTE 49  wingdi.h


EMR_CREATEPEN
EMR_CREATEPEN 38  wingdi.h


EMR_DELETEOBJECT
EMR_DELETEOBJECT 40  wingdi.h


EMR_ELLIPSE
EMR_ELLIPSE 42  wingdi.h


EMR_ENDPATH
EMR_ENDPATH 60  wingdi.h


EMR_EOF
EMR_EOF 14  wingdi.h


EMR_EXCLUDECLIPRECT
EMR_EXCLUDECLIPRECT 29  wingdi.h


EMR_EXTCREATEFONTINDIRECTW
EMR_EXTCREATEFONTINDIRECTW 82  wingdi.h


EMR_EXTCREATEPEN
EMR_EXTCREATEPEN 95  wingdi.h


EMR_EXTFLOODFILL
EMR_EXTFLOODFILL 53  wingdi.h


EMR_EXTSELECTCLIPRGN
EMR_EXTSELECTCLIPRGN 75  wingdi.h


EMR_EXTTEXTOUTA
EMR_EXTTEXTOUTA 83  wingdi.h


EMR_EXTTEXTOUTW
EMR_EXTTEXTOUTW 84  wingdi.h


EMR_FILLPATH
EMR_FILLPATH 62  wingdi.h


EMR_FILLRGN
EMR_FILLRGN 71  wingdi.h


EMR_FLATTENPATH
EMR_FLATTENPATH 65  wingdi.h


EMR_FRAMERGN
EMR_FRAMERGN 72  wingdi.h


EMR_GDICOMMENT
EMR_GDICOMMENT 70  wingdi.h


EMR_HEADER
EMR_HEADER 1  wingdi.h


EMR_INTERSECTCLIPRECT
EMR_INTERSECTCLIPRECT 30  wingdi.h


EMR_INVERTRGN
EMR_INVERTRGN 73  wingdi.h


EMR_LINETO
EMR_LINETO 54  wingdi.h


EMR_MASKBLT
EMR_MASKBLT 78  wingdi.h


EMR_MAX
EMR_MAX 97  wingdi.h


EMR_MIN
EMR_MIN 1  wingdi.h


EMR_MODIFYWORLDTRANSFORM
EMR_MODIFYWORLDTRANSFORM 36  wingdi.h


EMR_MOVETOEX
EMR_MOVETOEX 27  wingdi.h


EMR_OFFSETCLIPRGN
EMR_OFFSETCLIPRGN 26  wingdi.h


EMR_PAINTRGN
EMR_PAINTRGN 74  wingdi.h


EMR_PIE
EMR_PIE 47  wingdi.h


EMR_PLGBLT
EMR_PLGBLT 79  wingdi.h


EMR_POLYBEZIER
EMR_POLYBEZIER 2  wingdi.h


EMR_POLYBEZIER16
EMR_POLYBEZIER16 85  wingdi.h


EMR_POLYBEZIERTO
EMR_POLYBEZIERTO 5  wingdi.h


EMR_POLYBEZIERTO16
EMR_POLYBEZIERTO16 88  wingdi.h


EMR_POLYDRAW
EMR_POLYDRAW 56  wingdi.h


EMR_POLYDRAW16
EMR_POLYDRAW16 92  wingdi.h


EMR_POLYGON
EMR_POLYGON 3  wingdi.h


EMR_POLYGON16
EMR_POLYGON16 86  wingdi.h


EMR_POLYLINE
EMR_POLYLINE 4  wingdi.h


EMR_POLYLINE16
EMR_POLYLINE16 87  wingdi.h


EMR_POLYLINETO
EMR_POLYLINETO 6  wingdi.h


EMR_POLYLINETO16
EMR_POLYLINETO16 89  wingdi.h


EMR_POLYPOLYGON
EMR_POLYPOLYGON 8  wingdi.h


EMR_POLYPOLYGON16
EMR_POLYPOLYGON16 91  wingdi.h


EMR_POLYPOLYLINE
EMR_POLYPOLYLINE 7  wingdi.h


EMR_POLYPOLYLINE16
EMR_POLYPOLYLINE16 90  wingdi.h


EMR_POLYTEXTOUTA
EMR_POLYTEXTOUTA 96  wingdi.h


EMR_POLYTEXTOUTW
EMR_POLYTEXTOUTW 97  wingdi.h


EMR_REALIZEPALETTE
EMR_REALIZEPALETTE 52  wingdi.h


EMR_RECTANGLE
EMR_RECTANGLE 43  wingdi.h


EMR_RESIZEPALETTE
EMR_RESIZEPALETTE 51  wingdi.h


EMR_RESTOREDC
EMR_RESTOREDC 34  wingdi.h


EMR_ROUNDRECT
EMR_ROUNDRECT 44  wingdi.h


EMR_SAVEDC
EMR_SAVEDC 33  wingdi.h


EMR_SCALEVIEWPORTEXTEX
EMR_SCALEVIEWPORTEXTEX 31  wingdi.h


EMR_SCALEWINDOWEXTEX
EMR_SCALEWINDOWEXTEX 32  wingdi.h


EMR_SELECTCLIPPATH
EMR_SELECTCLIPPATH 67  wingdi.h


EMR_SELECTOBJECT
EMR_SELECTOBJECT 37  wingdi.h


EMR_SELECTPALETTE
EMR_SELECTPALETTE 48  wingdi.h


EMR_SETARCDIRECTION
EMR_SETARCDIRECTION 57  wingdi.h


EMR_SETBKCOLOR
EMR_SETBKCOLOR 25  wingdi.h


EMR_SETBKMODE
EMR_SETBKMODE 18  wingdi.h


EMR_SETBRUSHORGEX
EMR_SETBRUSHORGEX 13  wingdi.h


EMR_SETCOLORADJUSTMENT
EMR_SETCOLORADJUSTMENT 23  wingdi.h


EMR_SETDIBITSTODEVICE
EMR_SETDIBITSTODEVICE 80  wingdi.h


EMR_SETMAPMODE
EMR_SETMAPMODE 17  wingdi.h


EMR_SETMAPPERFLAGS
EMR_SETMAPPERFLAGS 16  wingdi.h


EMR_SETMETARGN
EMR_SETMETARGN 28  wingdi.h


EMR_SETMITERLIMIT
EMR_SETMITERLIMIT 58  wingdi.h


EMR_SETPALETTEENTRIES
EMR_SETPALETTEENTRIES 50  wingdi.h


EMR_SETPIXELV
EMR_SETPIXELV 15  wingdi.h


EMR_SETPOLYFILLMODE
EMR_SETPOLYFILLMODE 19  wingdi.h


EMR_SETROP2
EMR_SETROP2 20  wingdi.h


EMR_SETSTRETCHBLTMODE
EMR_SETSTRETCHBLTMODE 21  wingdi.h


EMR_SETTEXTALIGN
EMR_SETTEXTALIGN 22  wingdi.h


EMR_SETTEXTCOLOR
EMR_SETTEXTCOLOR 24  wingdi.h


EMR_SETVIEWPORTEXTEX
EMR_SETVIEWPORTEXTEX 11  wingdi.h


EMR_SETVIEWPORTORGEX
EMR_SETVIEWPORTORGEX 12  wingdi.h


EMR_SETWINDOWEXTEX
EMR_SETWINDOWEXTEX 9  wingdi.h


EMR_SETWINDOWORGEX
EMR_SETWINDOWORGEX 10  wingdi.h


EMR_SETWORLDTRANSFORM
EMR_SETWORLDTRANSFORM 35  wingdi.h


EMR_STRETCHBLT
EMR_STRETCHBLT 77  wingdi.h


EMR_STRETCHDIBITS
EMR_STRETCHDIBITS 81  wingdi.h


EMR_STROKEANDFILLPATH
EMR_STROKEANDFILLPATH 63  wingdi.h


EMR_STROKEPATH
EMR_STROKEPATH 64  wingdi.h


EMR_WIDENPATH
EMR_WIDENPATH 66  wingdi.h


EMSGSIZE
EMSGSIZE WSAEMSGSIZE  winsock.h


ENABLEDUPLEX
ENABLEDUPLEX 28  wingdi.h


ENABLEPAIRKERNING
ENABLEPAIRKERNING 769  wingdi.h


ENABLERELATIVEWIDTHS
ENABLERELATIVEWIDTHS 768  wingdi.h


ENAMETOOLONG
ENAMETOOLONG WSAENAMETOOLONG  winsock.h


ENCAPSULATED_POSTSCRIPT
ENCAPSULATED_POSTSCRIPT 4116  wingdi.h


END_PATH
END_PATH 4098  wingdi.h


ENDDOC
ENDDOC 11  wingdi.h


ENETDOWN
ENETDOWN WSAENETDOWN  winsock.h


ENETRESET
ENETRESET WSAENETRESET  winsock.h


ENETUNREACH
ENETUNREACH WSAENETUNREACH  winsock.h


ENHMETA_SIGNATURE
ENHMETA_SIGNATURE 0x464D4520  wingdi.h


ENHMETA_STOCK_OBJECT
ENHMETA_STOCK_OBJECT 0x80000000  wingdi.h


ENOBUFS
ENOBUFS WSAENOBUFS  winsock.h


ENOPROTOOPT
ENOPROTOOPT WSAENOPROTOOPT  winsock.h


ENOTCONN
ENOTCONN WSAENOTCONN  winsock.h


ENOTEMPTY
ENOTEMPTY WSAENOTEMPTY  winsock.h


ENOTSOCK
ENOTSOCK WSAENOTSOCK  winsock.h


ENUMPAPERBINS
ENUMPAPERBINS 31  wingdi.h


ENUMPAPERMETRICS
ENUMPAPERMETRICS 34  wingdi.h


EOPNOTSUPP
EOPNOTSUPP WSAEOPNOTSUPP  winsock.h


EPFNOSUPPORT
EPFNOSUPPORT WSAEPFNOSUPPORT  winsock.h


EPROCLIM
EPROCLIM WSAEPROCLIM  winsock.h


EPROTONOSUPPORT
EPROTONOSUPPORT WSAEPROTONOSUPPORT  winsock.h


EPROTOTYPE
EPROTOTYPE WSAEPROTOTYPE  winsock.h


EPSPRINTING
EPSPRINTING 33  wingdi.h


EPT_S_CANT_CREATE
EPT_S_CANT_CREATE 1899L  winerror.h


EPT_S_CANT_PERFORM_OP
EPT_S_CANT_PERFORM_OP 1752L  winerror.h


EPT_S_INVALID_ENTRY
EPT_S_INVALID_ENTRY 1751L  winerror.h


EPT_S_NOT_REGISTERED
EPT_S_NOT_REGISTERED 1753L  winerror.h


EREMOTE
EREMOTE WSAEREMOTE  winsock.h


ES_AUTOHSCROLL
ES_AUTOHSCROLL 0x0080L  winuser.h


ES_AUTOVSCROLL
ES_AUTOVSCROLL 0x0040L  winuser.h


ES_CENTER
ES_CENTER 0x0001L  winuser.h


ES_LEFT
ES_LEFT 0x0000L  winuser.h


ES_LOWERCASE
ES_LOWERCASE 0x0010L  winuser.h


ES_MULTILINE
ES_MULTILINE 0x0004L  winuser.h


ES_NOHIDESEL
ES_NOHIDESEL 0x0100L  winuser.h


ES_OEMCONVERT
ES_OEMCONVERT 0x0400L  winuser.h


ES_PASSWORD
ES_PASSWORD 0x0020L  winuser.h


ES_READONLY
ES_READONLY 0x0800L  winuser.h


ES_RIGHT
ES_RIGHT 0x0002L  winuser.h


ES_UPPERCASE
ES_UPPERCASE 0x0008L  winuser.h


ES_WANTRETURN
ES_WANTRETURN 0x1000L  winuser.h


ESB_DISABLE_DOWN
ESB_DISABLE_DOWN 0x0002  winuser.h


ESB_DISABLE_LEFT
ESB_DISABLE_LEFT 0x0001  winuser.h


ESB_DISABLE_RIGHT
ESB_DISABLE_RIGHT 0x0002  winuser.h


ESB_DISABLE_UP
ESB_DISABLE_UP 0x0001  winuser.h


ESHUTDOWN
ESHUTDOWN WSAESHUTDOWN  winsock.h


ESOCKTNOSUPPORT
ESOCKTNOSUPPORT WSAESOCKTNOSUPPORT  winsock.h


ESTALE
ESTALE WSAESTALE  winsock.h


ETIMEDOUT
ETIMEDOUT WSAETIMEDOUT  winsock.h


ETO_GRAYED
ETO_GRAYED 1  wingdi.h


ETOOMANYREFS
ETOOMANYREFS WSAETOOMANYREFS  winsock.h


EUSERS
EUSERS WSAEUSERS  winsock.h


EV_BREAK
EV_BREAK 0x0040  winbase.h


EV_CTS
EV_CTS 0x0008  winbase.h


EV_DSR
EV_DSR 0x0010  winbase.h


EV_ERR
EV_ERR 0x0080  winbase.h


EV_EVENT1
EV_EVENT1 0x0800  winbase.h


EV_EVENT2
EV_EVENT2 0x1000  winbase.h


EV_PERR
EV_PERR 0x0200  winbase.h


EV_RING
EV_RING 0x0100  winbase.h


EV_RLSD
EV_RLSD 0x0020  winbase.h


EV_RX80FULL
EV_RX80FULL 0x0400  winbase.h


EV_RXCHAR
EV_RXCHAR 0x0001  winbase.h


EV_RXFLAG
EV_RXFLAG 0x0002  winbase.h


EV_TXEMPTY
EV_TXEMPTY 0x0004  winbase.h


EVENT_ALL_ACCESS
EVENT_ALL_ACCESS (STANDARD_RIGHTS_REQUIRED|SYNCHRONIZE|0x3)  winnt.h


EVENT_MODIFY_STATE
EVENT_MODIFY_STATE 0x0002  winnt.h


EVENTLOG_END_ALL_PAIRED_EVENTS
EVENTLOG_END_ALL_PAIRED_EVENTS 0x0004  winnt.h


EVENTLOG_END_PAIRED_EVENT
EVENTLOG_END_PAIRED_EVENT 0x0002  winnt.h


EVENTLOG_PAIRED_EVENT_ACTIVE
EVENTLOG_PAIRED_EVENT_ACTIVE 0x0008  winnt.h


EVENTLOG_PAIRED_EVENT_INACTIVE
EVENTLOG_PAIRED_EVENT_INACTIVE 0x0010  winnt.h


EVENTLOG_START_PAIRED_EVENT
EVENTLOG_START_PAIRED_EVENT 0x0001  winnt.h


EVENTLOG_SUCCESS
EVENTLOG_SUCCESS 0X0000  winnt.h


EWOULDBLOCK
EWOULDBLOCK WSAEWOULDBLOCK  winsock.h


EXCEPTION_ACCESS_VIOLATION
EXCEPTION_ACCESS_VIOLATION STATUS_ACCESS_VIOLATION  winbase.h


EXCEPTION_ARRAY_BOUNDS_EXCEEDED
EXCEPTION_ARRAY_BOUNDS_EXCEEDED STATUS_ARRAY_BOUNDS_EXCEEDED  winbase.h


EXCEPTION_BREAKPOINT
EXCEPTION_BREAKPOINT STATUS_BREAKPOINT  winbase.h


EXCEPTION_DATATYPE_MISALIGNMENT
EXCEPTION_DATATYPE_MISALIGNMENT STATUS_DATATYPE_MISALIGNMENT  winbase.h


EXCEPTION_FLT_DENORMAL_OPERAND
EXCEPTION_FLT_DENORMAL_OPERAND STATUS_FLOAT_DENORMAL_OPERAND  winbase.h


EXCEPTION_FLT_DIVIDE_BY_ZERO
EXCEPTION_FLT_DIVIDE_BY_ZERO STATUS_FLOAT_DIVIDE_BY_ZERO  winbase.h


EXCEPTION_FLT_INEXACT_RESULT
EXCEPTION_FLT_INEXACT_RESULT STATUS_FLOAT_INEXACT_RESULT  winbase.h


EXCEPTION_FLT_INVALID_OPERATION
EXCEPTION_FLT_INVALID_OPERATION STATUS_FLOAT_INVALID_OPERATION  winbase.h


EXCEPTION_FLT_OVERFLOW
EXCEPTION_FLT_OVERFLOW STATUS_FLOAT_OVERFLOW  winbase.h


EXCEPTION_FLT_STACK_CHECK
EXCEPTION_FLT_STACK_CHECK STATUS_FLOAT_STACK_CHECK  winbase.h


EXCEPTION_FLT_UNDERFLOW
EXCEPTION_FLT_UNDERFLOW STATUS_FLOAT_UNDERFLOW  winbase.h


EXCEPTION_ILLEGAL_INSTRUCTION
EXCEPTION_ILLEGAL_INSTRUCTION STATUS_ILLEGAL_INSTRUCTION  winbase.h


EXCEPTION_IN_PAGE_ERROR
EXCEPTION_IN_PAGE_ERROR STATUS_IN_PAGE_ERROR  winbase.h


EXCEPTION_INT_DIVIDE_BY_ZERO
EXCEPTION_INT_DIVIDE_BY_ZERO STATUS_INTEGER_DIVIDE_BY_ZERO  winbase.h


EXCEPTION_INT_OVERFLOW
EXCEPTION_INT_OVERFLOW STATUS_INTEGER_OVERFLOW  winbase.h


EXCEPTION_INVALID_DISPOSITION
EXCEPTION_INVALID_DISPOSITION STATUS_INVALID_DISPOSITION  winbase.h


EXCEPTION_MAXIMUM_PARAMETERS
EXCEPTION_MAXIMUM_PARAMETERS 15  winnt.h


EXCEPTION_NONCONTINUABLE
EXCEPTION_NONCONTINUABLE 0x1  winnt.h


EXCEPTION_NONCONTINUABLE_EXCEPTION
EXCEPTION_NONCONTINUABLE_EXCEPTION STATUS_NONCONTINUABLE_EXCEPTION  winbase.h


EXCEPTION_PRIV_INSTRUCTION
EXCEPTION_PRIV_INSTRUCTION STATUS_PRIVILEGED_INSTRUCTION  winbase.h


EXCEPTION_SINGLE_STEP
EXCEPTION_SINGLE_STEP STATUS_SINGLE_STEP  winbase.h


EXCEPTION_STACK_OVERFLOW
EXCEPTION_STACK_OVERFLOW STATUS_STACK_OVERFLOW  winbase.h


EXPAND_LOCAL_DRIVES
EXPAND_LOCAL_DRIVES nothing  winbase.h


EXPENTRY
EXPENTRY CALLBACK  ddeml.h


EXT_DEVICE_CAPS
EXT_DEVICE_CAPS 4099  wingdi.h


EXTTEXTOUT
EXTTEXTOUT 512  wingdi.h


FD_ACCEPT
FD_ACCEPT 0x08  winsock.h


FD_CLOSE
FD_CLOSE 0x20  winsock.h


FD_CONNECT
FD_CONNECT 0x10  winsock.h


FD_OOB
FD_OOB 0x04  winsock.h


FD_READ
FD_READ 0x01  winsock.h


FD_SETSIZE
FD_SETSIZE 64  winsock.h


FD_WRITE
FD_WRITE 0x02  winsock.h


FILE_ADD_FILE
FILE_ADD_FILE ( 0x0002 )  winnt.h


FILE_ADD_SUBDIRECTORY
FILE_ADD_SUBDIRECTORY ( 0x0004 )  winnt.h


FILE_ALL_ACCESS
FILE_ALL_ACCESS (STANDARD_RIGHTS_REQUIRED | SYNCHRONIZE | 0x1FF)  winnt.h


FILE_ANY_ACCESS
FILE_ANY_ACCESS 0  winioctl.h


FILE_APPEND_DATA
FILE_APPEND_DATA ( 0x0004 )  winnt.h


FILE_CASE_PRESERVED_NAMES
FILE_CASE_PRESERVED_NAMES 0x00000002  winnt.h


FILE_CASE_SENSITIVE_SEARCH
FILE_CASE_SENSITIVE_SEARCH 0x00000001  winnt.h


FILE_CREATE_PIPE_INSTANCE
FILE_CREATE_PIPE_INSTANCE ( 0x0004 )  winnt.h


FILE_DELETE_CHILD
FILE_DELETE_CHILD ( 0x0040 )  winnt.h


FILE_DEVICE_8042_PORT
FILE_DEVICE_8042_PORT 0x00000027  winioctl.h


FILE_DEVICE_BEEP
FILE_DEVICE_BEEP 0x00000001  winioctl.h


FILE_DEVICE_CD_ROM
FILE_DEVICE_CD_ROM 0x00000002  winioctl.h


FILE_DEVICE_CD_ROM_FILE_SYSTEM
FILE_DEVICE_CD_ROM_FILE_SYSTEM 0x00000003  winioctl.h


FILE_DEVICE_CONTROLLER
FILE_DEVICE_CONTROLLER 0x00000004  winioctl.h


FILE_DEVICE_DATALINK
FILE_DEVICE_DATALINK 0x00000005  winioctl.h


FILE_DEVICE_DFS
FILE_DEVICE_DFS 0x00000006  winioctl.h


FILE_DEVICE_DISK
FILE_DEVICE_DISK 0x00000007  winioctl.h


FILE_DEVICE_DISK_FILE_SYSTEM
FILE_DEVICE_DISK_FILE_SYSTEM 0x00000008  winioctl.h


FILE_DEVICE_FILE_SYSTEM
FILE_DEVICE_FILE_SYSTEM 0x00000009  winioctl.h


FILE_DEVICE_INPORT_PORT
FILE_DEVICE_INPORT_PORT 0x0000000a  winioctl.h


FILE_DEVICE_KEYBOARD
FILE_DEVICE_KEYBOARD 0x0000000b  winioctl.h


FILE_DEVICE_MAILSLOT
FILE_DEVICE_MAILSLOT 0x0000000c  winioctl.h


FILE_DEVICE_MIDI_IN
FILE_DEVICE_MIDI_IN 0x0000000d  winioctl.h


FILE_DEVICE_MIDI_OUT
FILE_DEVICE_MIDI_OUT 0x0000000e  winioctl.h


FILE_DEVICE_MOUSE
FILE_DEVICE_MOUSE 0x0000000f  winioctl.h


FILE_DEVICE_MULTI_UNC_PROVIDER
FILE_DEVICE_MULTI_UNC_PROVIDER 0x00000010  winioctl.h


FILE_DEVICE_NAMED_PIPE
FILE_DEVICE_NAMED_PIPE 0x00000011  winioctl.h


FILE_DEVICE_NETWORK
FILE_DEVICE_NETWORK 0x00000012  winioctl.h


FILE_DEVICE_NETWORK_BROWSER
FILE_DEVICE_NETWORK_BROWSER 0x00000013  winioctl.h


FILE_DEVICE_NETWORK_FILE_SYSTEM
FILE_DEVICE_NETWORK_FILE_SYSTEM 0x00000014  winioctl.h


FILE_DEVICE_NULL
FILE_DEVICE_NULL 0x00000015  winioctl.h


FILE_DEVICE_PARALLEL_PORT
FILE_DEVICE_PARALLEL_PORT 0x00000016  winioctl.h


FILE_DEVICE_PHYSICAL_NETCARD
FILE_DEVICE_PHYSICAL_NETCARD 0x00000017  winioctl.h


FILE_DEVICE_PRINTER
FILE_DEVICE_PRINTER 0x00000018  winioctl.h


FILE_DEVICE_SCANNER
FILE_DEVICE_SCANNER 0x00000019  winioctl.h


FILE_DEVICE_SCREEN
FILE_DEVICE_SCREEN 0x0000001c  winioctl.h


FILE_DEVICE_SERIAL_MOUSE_PORT
FILE_DEVICE_SERIAL_MOUSE_PORT 0x0000001a  winioctl.h


FILE_DEVICE_SERIAL_PORT
FILE_DEVICE_SERIAL_PORT 0x0000001b  winioctl.h


FILE_DEVICE_SOUND
FILE_DEVICE_SOUND 0x0000001d  winioctl.h


FILE_DEVICE_STREAMS
FILE_DEVICE_STREAMS 0x0000001e  winioctl.h


FILE_DEVICE_TAPE
FILE_DEVICE_TAPE 0x0000001f  winioctl.h


FILE_DEVICE_TAPE_FILE_SYSTEM
FILE_DEVICE_TAPE_FILE_SYSTEM 0x00000020  winioctl.h


FILE_DEVICE_TRANSPORT
FILE_DEVICE_TRANSPORT 0x00000021  winioctl.h


FILE_DEVICE_UNKNOWN
FILE_DEVICE_UNKNOWN 0x00000022  winioctl.h


FILE_DEVICE_VIDEO
FILE_DEVICE_VIDEO 0x00000023  winioctl.h


FILE_DEVICE_VIRTUAL_DISK
FILE_DEVICE_VIRTUAL_DISK 0x00000024  winioctl.h


FILE_DEVICE_WAVE_IN
FILE_DEVICE_WAVE_IN 0x00000025  winioctl.h


FILE_DEVICE_WAVE_OUT
FILE_DEVICE_WAVE_OUT 0x00000026  winioctl.h


FILE_EXECUTE
FILE_EXECUTE ( 0x0020 )  winnt.h


FILE_GENERIC_EXECUTE
FILE_GENERIC_EXECUTE (STANDARD_RIGHTS_EXECUTE | FILE_READ_ATTRIBUTES | FILE_EXECUTE | SYNCHRONIZE)  winnt.h


FILE_GENERIC_READ
FILE_GENERIC_READ (STANDARD_RIGHTS_READ | FILE_READ_DATA | FILE_READ_ATTRIBUTES | FILE_READ_EA | SYNCHRONIZE)  winnt.h


FILE_GENERIC_WRITE
FILE_GENERIC_WRITE (STANDARD_RIGHTS_WRITE | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES | FILE_WRITE_EA | FILE_APPEND_DATA | SYNCHRONIZE) winnt.h


FILE_LIST_DIRECTORY
FILE_LIST_DIRECTORY ( 0x0001 )  winnt.h


FILE_PERSISTENT_ACLS
FILE_PERSISTENT_ACLS 0x00000008  winnt.h


FILE_READ_ACCESS
FILE_READ_ACCESS ( 0x0001 )  winioctl.h


FILE_READ_ATTRIBUTES
FILE_READ_ATTRIBUTES ( 0x0080 )  winnt.h


FILE_READ_DATA
FILE_READ_DATA ( 0x0001 )  winnt.h


FILE_READ_EA
FILE_READ_EA ( 0x0008 )  winnt.h


FILE_TRAVERSE
FILE_TRAVERSE ( 0x0020 )  winnt.h


FILE_TYPE_REMOTE
FILE_TYPE_REMOTE 0x8000  winbase.h


FILE_UNICODE_ON_DISK
FILE_UNICODE_ON_DISK 0x00000004  winnt.h


FILE_WRITE_ACCESS
FILE_WRITE_ACCESS ( 0x0002 )  winioctl.h


FILE_WRITE_ATTRIBUTES
FILE_WRITE_ATTRIBUTES ( 0x0100 )  winnt.h


FILE_WRITE_DATA
FILE_WRITE_DATA ( 0x0002 )  winnt.h


FILE_WRITE_EA
FILE_WRITE_EA ( 0x0010 )  winnt.h


FILEOKSTRING
FILEOKSTRING FILEOKSTRINGA  commdlg.h


FILEOKSTRING
FILEOKSTRING FILEOKSTRINGW  commdlg.h


FILEOKSTRINGA
FILEOKSTRINGA "commdlg_FileNameOK"  commdlg.h


FILEOKSTRINGW
FILEOKSTRINGW L"commdlg_FileNameOK"  commdlg.h


FILEOPENORD
FILEOPENORD 1536  dlgs.h


FINDDLGORD
FINDDLGORD 1540  dlgs.h


FINDMSGSTRING
FINDMSGSTRING FINDMSGSTRINGA  commdlg.h


FINDMSGSTRING
FINDMSGSTRING FINDMSGSTRINGW  commdlg.h


FINDMSGSTRINGA
FINDMSGSTRINGA "commdlg_FindReplace"  commdlg.h


FINDMSGSTRINGW
FINDMSGSTRINGW L"commdlg_FindReplace"  commdlg.h


FIOASYNC
FIOASYNC _IOW('f', 125, u_long)  winsock.h


FIONBIO
FIONBIO _IOW('f', 126, u_long)  winsock.h


FIONREAD
FIONREAD _IOR('f', 127, u_long)  winsock.h


FIXED_PITCH
FIXED_PITCH 1  wingdi.h


FLUSHOUTPUT
FLUSHOUTPUT 6  wingdi.h


FMMENU_FIRST
FMMENU_FIRST 1  wfext.h


FMMENU_LAST
FMMENU_LAST 99  wfext.h


FNERR_FILENAMECODES
FNERR_FILENAMECODES 0x3000  cderr.h


FOCUS_EVENT
FOCUS_EVENT 0x0010  wincon.h


FONTDLGORD
FONTDLGORD 1542  dlgs.h


FONTMAPPER_MAX
FONTMAPPER_MAX 10  wingdi.h


FOREGROUND_BLUE
FOREGROUND_BLUE 0x0001  wincon.h


FOREGROUND_GREEN
FOREGROUND_GREEN 0x0002  wincon.h


FOREGROUND_INTENSITY
FOREGROUND_INTENSITY 0x0008  wincon.h


FOREGROUND_RED
FOREGROUND_RED 0x0004  wincon.h


FORM_BUILTIN
FORM_BUILTIN 0x00000001  winspool.h


FORMAT_MESSAGE_ARGUMENT_ARRAY
FORMAT_MESSAGE_ARGUMENT_ARRAY 0x00002000  winbase.h


FORMAT_MESSAGE_MAX_WIDTH_MASK
FORMAT_MESSAGE_MAX_WIDTH_MASK 0x000000FF  winbase.h


FORMATDLGORD30
FORMATDLGORD30 1544  dlgs.h


FORMATDLGORD31
FORMATDLGORD31 1543  dlgs.h


FOURCC_DOS
FOURCC_DOS mmioFOURCC('D', 'O', 'S', ' ')  mmsystem.h


FOURCC_LIST
FOURCC_LIST mmioFOURCC('L', 'I', 'S', 'T')  mmsystem.h


FOURCC_MEM
FOURCC_MEM mmioFOURCC('M', 'E', 'M', ' ')  mmsystem.h


FOURCC_RIFF
FOURCC_RIFF mmioFOURCC('R', 'I', 'F', 'F')  mmsystem.h


FRAME_FPO
FRAME_FPO 0  winnt.h


FRAME_TRAP
FRAME_TRAP 1  winnt.h


FRAME_TSS
FRAME_TSS 2  winnt.h


FRERR_FINDREPLACECODES
FRERR_FINDREPLACECODES 0x4000  cderr.h


FROM_LEFT_1ST_BUTTON_PRESSED
FROM_LEFT_1ST_BUTTON_PRESSED 0x0001  wincon.h


FROM_LEFT_2ND_BUTTON_PRESSED
FROM_LEFT_2ND_BUTTON_PRESSED 0x0004  wincon.h


FROM_LEFT_3RD_BUTTON_PRESSED
FROM_LEFT_3RD_BUTTON_PRESSED 0x0008  wincon.h


FROM_LEFT_4TH_BUTTON_PRESSED
FROM_LEFT_4TH_BUTTON_PRESSED 0x0010  wincon.h


FS_PERSISTENT_ACLS
FS_PERSISTENT_ACLS FILE_PERSISTENT_ACLS  winbase.h


FSCTL_DISMOUNT_VOLUME
FSCTL_DISMOUNT_VOLUME CTL_CODE(FILE_DEVICE_FILE_SYSTEM, 8, METHOD_BUFFERED, FILE_ANY_ACCESS)  winioctl.h


FSCTL_LOCK_VOLUME
FSCTL_LOCK_VOLUME CTL_CODE(FILE_DEVICE_FILE_SYSTEM, 6, METHOD_BUFFERED, FILE_ANY_ACCESS)  winioctl.h


FSCTL_UNLOCK_VOLUME
FSCTL_UNLOCK_VOLUME CTL_CODE(FILE_DEVICE_FILE_SYSTEM, 7, METHOD_BUFFERED, FILE_ANY_ACCESS)  winioctl.h


FW_BLACK
FW_BLACK FW_HEAVY  wingdi.h


FW_DEMIBOLD
FW_DEMIBOLD FW_SEMIBOLD  wingdi.h


FW_REGULAR
FW_REGULAR FW_NORMAL  wingdi.h


FW_ULTRABOLD
FW_ULTRABOLD FW_EXTRABOLD  wingdi.h


FW_ULTRALIGHT
FW_ULTRALIGHT FW_EXTRALIGHT  wingdi.h


GCW_ATOM
GCW_ATOM (-32)  winuser.h


GDI_ERROR
GDI_ERROR (0xFFFFFFFFL)  wingdi.h


GENERIC_ALL
GENERIC_ALL (0x10000000L)  winnt.h


GETCOLORTABLE
GETCOLORTABLE 5  wingdi.h


GETDEVICEUNITS
GETDEVICEUNITS 42  wingdi.h


GETEXTENDEDTEXTMETRICS
GETEXTENDEDTEXTMETRICS 256  wingdi.h


GETEXTENTTABLE
GETEXTENTTABLE 257  wingdi.h


GETFACENAME
GETFACENAME 513  wingdi.h


GETPAIRKERNTABLE
GETPAIRKERNTABLE 258  wingdi.h


GETPENWIDTH
GETPENWIDTH 16  wingdi.h


GETPHYSPAGESIZE
GETPHYSPAGESIZE 12  wingdi.h


GETPRINTINGOFFSET
GETPRINTINGOFFSET 13  wingdi.h


GETSCALINGFACTOR
GETSCALINGFACTOR 14  wingdi.h


GETSETPAPERBINS
GETSETPAPERBINS 29  wingdi.h


GETSETPAPERMETRICS
GETSETPAPERMETRICS 35  wingdi.h


GETSETPRINTORIENT
GETSETPRINTORIENT 30  wingdi.h


GETSETSCREENPARAMS
GETSETSCREENPARAMS 3072  wingdi.h


GETTECHNOLGY
GETTECHNOLGY 20  wingdi.h


GETTECHNOLOGY
GETTECHNOLOGY 20  wingdi.h


GETTRACKKERNTABLE
GETTRACKKERNTABLE 259  wingdi.h


GETVECTORBRUSHSIZE
GETVECTORBRUSHSIZE 27  wingdi.h


GETVECTORPENSIZE
GETVECTORPENSIZE 26  wingdi.h


GGO_BITMAP
GGO_BITMAP 1  wingdi.h


GGO_METRICS
GGO_METRICS 0  wingdi.h


GGO_NATIVE
GGO_NATIVE 2  wingdi.h


GHND
GHND (GMEM_MOVEABLE | GMEM_ZEROINIT)  winbase.h


GM_ADVANCED
GM_ADVANCED 2  wingdi.h


GM_COMPATIBLE
GM_COMPATIBLE 1  wingdi.h


GM_LAST
GM_LAST 2  wingdi.h


GMEM_DDESHARE
GMEM_DDESHARE 0x2000  winbase.h


GMEM_DISCARDABLE
GMEM_DISCARDABLE 0x0100  winbase.h


GMEM_DISCARDED
GMEM_DISCARDED 0x4000  winbase.h


GMEM_FIXED
GMEM_FIXED 0x0000  winbase.h


GMEM_INVALID_HANDLE
GMEM_INVALID_HANDLE 0x8000  winbase.h


GMEM_LOCKCOUNT
GMEM_LOCKCOUNT 0x00FF  winbase.h


GMEM_LOWER
GMEM_LOWER GMEM_NOT_BANKED  winbase.h


GMEM_MODIFY
GMEM_MODIFY 0x0080  winbase.h


GMEM_MOVEABLE
GMEM_MOVEABLE 0x0002  winbase.h


GMEM_NOCOMPACT
GMEM_NOCOMPACT 0x0010  winbase.h


GMEM_NODISCARD
GMEM_NODISCARD 0x0020  winbase.h


GMEM_NOT_BANKED
GMEM_NOT_BANKED 0x1000  winbase.h


GMEM_NOTIFY
GMEM_NOTIFY 0x4000  winbase.h


GMEM_SHARE
GMEM_SHARE 0x2000  winbase.h


GMEM_VALID_FLAGS
GMEM_VALID_FLAGS 0x7F72  winbase.h


GMEM_ZEROINIT
GMEM_ZEROINIT 0x0040  winbase.h


GPTR
GPTR (GMEM_FIXED | GMEM_ZEROINIT)  winbase.h


GW_MAX
GW_MAX 5  winuser.h


HANGEUL_CHARSET
HANGEUL_CHARSET 129  wingdi.h


HC_NOREM
HC_NOREM HC_NOREMOVE  winuser.h


HDATA_APPOWNED
HDATA_APPOWNED 0x0001  ddeml.h


HEAP_DISABLE_COALESCE_ON_FREE
HEAP_DISABLE_COALESCE_ON_FREE 0x00000080  winnt.h


HEAP_FREE_CHECKING_ENABLED
HEAP_FREE_CHECKING_ENABLED 0x00000040  winnt.h


HEAP_GENERATE_EXCEPTIONS
HEAP_GENERATE_EXCEPTIONS 0x00000004  winnt.h


HEAP_GROWABLE
HEAP_GROWABLE 0x00000002  winnt.h


HEAP_NO_SERIALIZE
HEAP_NO_SERIALIZE 0x00000001  winnt.h


HEAP_REALLOC_IN_PLACE_ONLY
HEAP_REALLOC_IN_PLACE_ONLY 0x00000010  winnt.h


HEAP_TAIL_CHECKING_ENABLED
HEAP_TAIL_CHECKING_ENABLED 0x00000020  winnt.h


HEAP_ZERO_MEMORY
HEAP_ZERO_MEMORY 0x00000008  winnt.h


HELP_COMMAND
HELP_COMMAND 0x0102L  winuser.h


HELP_CONTENTS
HELP_CONTENTS 0x0003L  winuser.h


HELP_CONTEXT
HELP_CONTEXT 0x0001L  winuser.h


HELP_CONTEXTPOPUP
HELP_CONTEXTPOPUP 0x0008L  winuser.h


HELP_FORCEFILE
HELP_FORCEFILE 0x0009L  winuser.h


HELP_HELPONHELP
HELP_HELPONHELP 0x0004L  winuser.h


HELP_INDEX
HELP_INDEX 0x0003L  winuser.h


HELP_KEY
HELP_KEY 0x0101L  winuser.h


HELP_MULTIKEY
HELP_MULTIKEY 0x0201L  winuser.h


HELP_PARTIALKEY
HELP_PARTIALKEY 0x0105L  winuser.h


HELP_QUIT
HELP_QUIT 0x0002L  winuser.h


HELP_SETCONTENTS
HELP_SETCONTENTS 0x0005L  winuser.h


HELP_SETINDEX
HELP_SETINDEX 0x0005L  winuser.h


HELP_SETWINPOS
HELP_SETWINPOS 0x0203L  winuser.h


HELPMSGSTRING
HELPMSGSTRING HELPMSGSTRINGA  commdlg.h


HELPMSGSTRING
HELPMSGSTRING HELPMSGSTRINGW  commdlg.h


HELPMSGSTRINGA
HELPMSGSTRINGA "commdlg_help"  commdlg.h


HELPMSGSTRINGW
HELPMSGSTRINGW L"commdlg_help"  commdlg.h


HIDE_WINDOW
HIDE_WINDOW 0  winuser.h


HIGH_PRIORITY_CLASS
HIGH_PRIORITY_CLASS 0x00000080  winbase.h


HINSTANCE_ERROR
HINSTANCE_ERROR 32  winbase.h


HKL_NEXT
HKL_NEXT 1  winuser.h


HKL_PREV
HKL_PREV 0  winuser.h


HOST_NOT_FOUND
HOST_NOT_FOUND WSAHOST_NOT_FOUND  winsock.h


HS_API_MAX
HS_API_MAX 25  wingdi.h


HS_BDIAGONAL1
HS_BDIAGONAL1 7  wingdi.h


HS_DENSE1
HS_DENSE1 9  wingdi.h


HS_DENSE2
HS_DENSE2 10  wingdi.h


HS_DENSE3
HS_DENSE3 11  wingdi.h


HS_DENSE4
HS_DENSE4 12  wingdi.h


HS_DENSE5
HS_DENSE5 13  wingdi.h


HS_DENSE6
HS_DENSE6 14  wingdi.h


HS_DENSE7
HS_DENSE7 15  wingdi.h


HS_DENSE8
HS_DENSE8 16  wingdi.h


HS_DITHEREDBKCLR
HS_DITHEREDBKCLR 24  wingdi.h


HS_DITHEREDCLR
HS_DITHEREDCLR 20  wingdi.h


HS_DITHEREDTEXTCLR
HS_DITHEREDTEXTCLR 22  wingdi.h


HS_FDIAGONAL1
HS_FDIAGONAL1 6  wingdi.h


HS_HALFTONE
HS_HALFTONE 18  wingdi.h


HS_NOSHADE
HS_NOSHADE 17  wingdi.h


HS_SOLID
HS_SOLID 8  wingdi.h


HS_SOLIDBKCLR
HS_SOLIDBKCLR 23  wingdi.h


HS_SOLIDCLR
HS_SOLIDCLR 19  wingdi.h


HS_SOLIDTEXTCLR
HS_SOLIDTEXTCLR 21  wingdi.h


HSHELL_ACTIVATESHELLWINDOW
HSHELL_ACTIVATESHELLWINDOW 3  winuser.h


HTMAXBUTTON
HTMAXBUTTON 9  winuser.h


HTMINBUTTON
HTMINBUTTON 8  winuser.h


HTSIZEFIRST
HTSIZEFIRST HTLEFT  winuser.h


HTSIZELAST
HTSIZELAST HTBOTTOMRIGHT  winuser.h


ID_APP
ID_APP 100  scrnsave.h


IDLE_PRIORITY_CLASS
IDLE_PRIORITY_CLASS 0x00000040  winbase.h


IDS_DESCRIPTION
IDS_DESCRIPTION 1  scrnsave.h


IE_BADID
IE_BADID (-1)  winbase.h


IE_BAUDRATE
IE_BAUDRATE (-12)  winbase.h


IE_BYTESIZE
IE_BYTESIZE (-11)  winbase.h


IE_DEFAULT
IE_DEFAULT (-5)  winbase.h


IE_HARDWARE
IE_HARDWARE (-10)  winbase.h


IE_MEMORY
IE_MEMORY (-4)  winbase.h


IE_NOPEN
IE_NOPEN (-3)  winbase.h


IE_OPEN
IE_OPEN (-2)  winbase.h


IGNORE
IGNORE 0  winbase.h


ILLUMINANT_A
ILLUMINANT_A 1  wingdi.h


ILLUMINANT_B
ILLUMINANT_B 2  wingdi.h


ILLUMINANT_C
ILLUMINANT_C 3  wingdi.h


ILLUMINANT_D50
ILLUMINANT_D50 4  wingdi.h


ILLUMINANT_D55
ILLUMINANT_D55 5  wingdi.h


ILLUMINANT_D65
ILLUMINANT_D65 6  wingdi.h


ILLUMINANT_D75
ILLUMINANT_D75 7  wingdi.h


ILLUMINANT_DAYLIGHT
ILLUMINANT_DAYLIGHT ILLUMINANT_C  wingdi.h


ILLUMINANT_DEVICE_DEFAULT
ILLUMINANT_DEVICE_DEFAULT 0  wingdi.h


ILLUMINANT_F2
ILLUMINANT_F2 8  wingdi.h


ILLUMINANT_FLUORESCENT
ILLUMINANT_FLUORESCENT ILLUMINANT_F2  wingdi.h


ILLUMINANT_MAX_INDEX
ILLUMINANT_MAX_INDEX ILLUMINANT_F2  wingdi.h


ILLUMINANT_NTSC
ILLUMINANT_NTSC ILLUMINANT_C  wingdi.h


ILLUMINANT_TUNGSTEN
ILLUMINANT_TUNGSTEN ILLUMINANT_A  wingdi.h


IMAGE_ARCHIVE_END
IMAGE_ARCHIVE_END "`n"  winnt.h


IMAGE_ARCHIVE_LINKER_MEMBER
IMAGE_ARCHIVE_LINKER_MEMBER "/ "  winnt.h


IMAGE_ARCHIVE_LONGNAMES_MEMBER
IMAGE_ARCHIVE_LONGNAMES_MEMBER "  winnt.h


IMAGE_ARCHIVE_PAD
IMAGE_ARCHIVE_PAD "n"  winnt.h


IMAGE_ARCHIVE_START
IMAGE_ARCHIVE_START "!archn"  winnt.h


IMAGE_ARCHIVE_START_SIZE
IMAGE_ARCHIVE_START_SIZE 8  winnt.h


IMAGE_COMDAT_SELECT_ANY
IMAGE_COMDAT_SELECT_ANY 2  winnt.h


IMAGE_COMDAT_SELECT_ASSOCIATIVE
IMAGE_COMDAT_SELECT_ASSOCIATIVE 5  winnt.h


IMAGE_COMDAT_SELECT_EXACT_MATCH
IMAGE_COMDAT_SELECT_EXACT_MATCH 4  winnt.h


IMAGE_COMDAT_SELECT_NODUPLICATES
IMAGE_COMDAT_SELECT_NODUPLICATES 1  winnt.h


IMAGE_COMDAT_SELECT_SAME_SIZE
IMAGE_COMDAT_SELECT_SAME_SIZE 3  winnt.h


IMAGE_COMDAT_SELECT_UNKNOWN
IMAGE_COMDAT_SELECT_UNKNOWN 0  winnt.h


IMAGE_DEBUG_MISC_EXENAME
IMAGE_DEBUG_MISC_EXENAME 1  winnt.h


IMAGE_DEBUG_TYPE_CODEVIEW
IMAGE_DEBUG_TYPE_CODEVIEW 2  winnt.h


IMAGE_DEBUG_TYPE_COFF
IMAGE_DEBUG_TYPE_COFF 1  winnt.h


IMAGE_DEBUG_TYPE_EXCEPTION
IMAGE_DEBUG_TYPE_EXCEPTION 5  winnt.h


IMAGE_DEBUG_TYPE_FIXUP
IMAGE_DEBUG_TYPE_FIXUP 6  winnt.h


IMAGE_DEBUG_TYPE_FPO
IMAGE_DEBUG_TYPE_FPO 3  winnt.h


IMAGE_DEBUG_TYPE_MISC
IMAGE_DEBUG_TYPE_MISC 4  winnt.h


IMAGE_DEBUG_TYPE_RESERVED6
IMAGE_DEBUG_TYPE_RESERVED6 7  winnt.h


IMAGE_DEBUG_TYPE_RESERVED7
IMAGE_DEBUG_TYPE_RESERVED7 8  winnt.h


IMAGE_DEBUG_TYPE_UNKNOWN
IMAGE_DEBUG_TYPE_UNKNOWN 0  winnt.h


IMAGE_DIRECTORY_ENTRY_BASERELOC
IMAGE_DIRECTORY_ENTRY_BASERELOC 5  winnt.h


IMAGE_DIRECTORY_ENTRY_COPYRIGHT
IMAGE_DIRECTORY_ENTRY_COPYRIGHT 7  winnt.h


IMAGE_DIRECTORY_ENTRY_DEBUG
IMAGE_DIRECTORY_ENTRY_DEBUG 6  winnt.h


IMAGE_DIRECTORY_ENTRY_EXCEPTION
IMAGE_DIRECTORY_ENTRY_EXCEPTION 3  winnt.h


IMAGE_DIRECTORY_ENTRY_EXPORT
IMAGE_DIRECTORY_ENTRY_EXPORT 0  winnt.h


IMAGE_DIRECTORY_ENTRY_GLOBALPTR
IMAGE_DIRECTORY_ENTRY_GLOBALPTR 8  winnt.h


IMAGE_DIRECTORY_ENTRY_IMPORT
IMAGE_DIRECTORY_ENTRY_IMPORT 1  winnt.h


IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG
IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG 10  winnt.h


IMAGE_DIRECTORY_ENTRY_RESOURCE
IMAGE_DIRECTORY_ENTRY_RESOURCE 2  winnt.h


IMAGE_DIRECTORY_ENTRY_SECURITY
IMAGE_DIRECTORY_ENTRY_SECURITY 4  winnt.h


IMAGE_DIRECTORY_ENTRY_TLS
IMAGE_DIRECTORY_ENTRY_TLS 9  winnt.h


IMAGE_DOS_SIGNATURE
IMAGE_DOS_SIGNATURE 0x5A4D  winnt.h


IMAGE_FILE_16BIT_MACHINE
IMAGE_FILE_16BIT_MACHINE 0x0040  winnt.h


IMAGE_FILE_32BIT_MACHINE
IMAGE_FILE_32BIT_MACHINE 0x0100  winnt.h


IMAGE_FILE_BYTES_REVERSED_HI
IMAGE_FILE_BYTES_REVERSED_HI 0x8000  winnt.h


IMAGE_FILE_BYTES_REVERSED_LO
IMAGE_FILE_BYTES_REVERSED_LO 0x0080  winnt.h


IMAGE_FILE_DEBUG_STRIPPED
IMAGE_FILE_DEBUG_STRIPPED 0x0200  winnt.h


IMAGE_FILE_DLL
IMAGE_FILE_DLL 0x2000  winnt.h


IMAGE_FILE_EXECUTABLE_IMAGE
IMAGE_FILE_EXECUTABLE_IMAGE 0x0002  winnt.h


IMAGE_FILE_LINE_NUMS_STRIPPED
IMAGE_FILE_LINE_NUMS_STRIPPED 0x0004  winnt.h


IMAGE_FILE_LOCAL_SYMS_STRIPPED
IMAGE_FILE_LOCAL_SYMS_STRIPPED 0x0008  winnt.h


IMAGE_FILE_MACHINE_ALPHA
IMAGE_FILE_MACHINE_ALPHA 0x184  winnt.h


IMAGE_FILE_MACHINE_I386
IMAGE_FILE_MACHINE_I386 0x14c  winnt.h


IMAGE_FILE_MACHINE_I860
IMAGE_FILE_MACHINE_I860 0x14d  winnt.h


IMAGE_FILE_MACHINE_R3000
IMAGE_FILE_MACHINE_R3000 0x162  winnt.h


IMAGE_FILE_MACHINE_R4000
IMAGE_FILE_MACHINE_R4000 0x166  winnt.h


IMAGE_FILE_MACHINE_UNKNOWN
IMAGE_FILE_MACHINE_UNKNOWN 0  winnt.h


IMAGE_FILE_MINIMAL_OBJECT
IMAGE_FILE_MINIMAL_OBJECT 0x0010  winnt.h


IMAGE_FILE_PATCH
IMAGE_FILE_PATCH 0x0400  winnt.h


IMAGE_FILE_RELOCS_STRIPPED
IMAGE_FILE_RELOCS_STRIPPED 0x0001  winnt.h


IMAGE_FILE_SYSTEM
IMAGE_FILE_SYSTEM 0x1000  winnt.h


IMAGE_FILE_UPDATE_OBJECT
IMAGE_FILE_UPDATE_OBJECT 0x0020  winnt.h


IMAGE_LIBRARY_PROCESS_INIT
IMAGE_LIBRARY_PROCESS_INIT 1  winnt.h


IMAGE_LIBRARY_PROCESS_TERM
IMAGE_LIBRARY_PROCESS_TERM 2  winnt.h


IMAGE_LIBRARY_THREAD_INIT
IMAGE_LIBRARY_THREAD_INIT 4  winnt.h


IMAGE_LIBRARY_THREAD_TERM
IMAGE_LIBRARY_THREAD_TERM 8  winnt.h


IMAGE_LOADER_FLAGS_BREAK_ON_LOAD
IMAGE_LOADER_FLAGS_BREAK_ON_LOAD 0x00000001  winnt.h


IMAGE_LOADER_FLAGS_DEBUG_ON_LOAD
IMAGE_LOADER_FLAGS_DEBUG_ON_LOAD 0x00000002  winnt.h


IMAGE_NT_SIGNATURE
IMAGE_NT_SIGNATURE 0x00004550  winnt.h


IMAGE_NUMBEROF_DIRECTORY_ENTRIES
IMAGE_NUMBEROF_DIRECTORY_ENTRIES 16  winnt.h


IMAGE_ORDINAL_FLAG
IMAGE_ORDINAL_FLAG 0x80000000  winnt.h


IMAGE_OS2_SIGNATURE
IMAGE_OS2_SIGNATURE 0x454E  winnt.h


IMAGE_OS2_SIGNATURE_LE
IMAGE_OS2_SIGNATURE_LE 0x454C  winnt.h


IMAGE_REL_ALPHA_ABSOLUTE
IMAGE_REL_ALPHA_ABSOLUTE 0x0  winnt.h


IMAGE_REL_ALPHA_BRADDR
IMAGE_REL_ALPHA_BRADDR 0x7  winnt.h


IMAGE_REL_ALPHA_GPDISP
IMAGE_REL_ALPHA_GPDISP 0x6  winnt.h


IMAGE_REL_ALPHA_GPREL32
IMAGE_REL_ALPHA_GPREL32 0x3  winnt.h


IMAGE_REL_ALPHA_HINT
IMAGE_REL_ALPHA_HINT 0x8  winnt.h


IMAGE_REL_ALPHA_INLINE_REFLONG
IMAGE_REL_ALPHA_INLINE_REFLONG 0x9  winnt.h


IMAGE_REL_ALPHA_LITERAL
IMAGE_REL_ALPHA_LITERAL 0x4  winnt.h


IMAGE_REL_ALPHA_LITUSE
IMAGE_REL_ALPHA_LITUSE 0x5  winnt.h


IMAGE_REL_ALPHA_MATCH
IMAGE_REL_ALPHA_MATCH 0xD  winnt.h


IMAGE_REL_ALPHA_PAIR
IMAGE_REL_ALPHA_PAIR 0xC  winnt.h


IMAGE_REL_ALPHA_REFHI
IMAGE_REL_ALPHA_REFHI 0xA  winnt.h


IMAGE_REL_ALPHA_REFLO
IMAGE_REL_ALPHA_REFLO 0xB  winnt.h


IMAGE_REL_ALPHA_REFLONG
IMAGE_REL_ALPHA_REFLONG 0x1  winnt.h


IMAGE_REL_ALPHA_REFLONGNB
IMAGE_REL_ALPHA_REFLONGNB 0x10  winnt.h


IMAGE_REL_ALPHA_REFQUAD
IMAGE_REL_ALPHA_REFQUAD 0x2  winnt.h


IMAGE_REL_ALPHA_SECREL
IMAGE_REL_ALPHA_SECREL 0xF  winnt.h


IMAGE_REL_ALPHA_SECTION
IMAGE_REL_ALPHA_SECTION 0xE  winnt.h


IMAGE_REL_BASED_ABSOLUTE
IMAGE_REL_BASED_ABSOLUTE 0  winnt.h


IMAGE_REL_BASED_HIGH
IMAGE_REL_BASED_HIGH 1  winnt.h


IMAGE_REL_BASED_HIGHADJ
IMAGE_REL_BASED_HIGHADJ 4  winnt.h


IMAGE_REL_BASED_HIGHLOW
IMAGE_REL_BASED_HIGHLOW 3  winnt.h


IMAGE_REL_BASED_I860_BRADDR
IMAGE_REL_BASED_I860_BRADDR 6  winnt.h


IMAGE_REL_BASED_I860_SPLIT
IMAGE_REL_BASED_I860_SPLIT 7  winnt.h


IMAGE_REL_BASED_LOW
IMAGE_REL_BASED_LOW 2  winnt.h


IMAGE_REL_BASED_MIPS_JMPADDR
IMAGE_REL_BASED_MIPS_JMPADDR 5  winnt.h


IMAGE_REL_I386_ABSOLUTE
IMAGE_REL_I386_ABSOLUTE 0  winnt.h


IMAGE_REL_I386_DIR16
IMAGE_REL_I386_DIR16 01  winnt.h


IMAGE_REL_I386_DIR32
IMAGE_REL_I386_DIR32 06  winnt.h


IMAGE_REL_I386_DIR32NB
IMAGE_REL_I386_DIR32NB 07  winnt.h


IMAGE_REL_I386_REL16
IMAGE_REL_I386_REL16 02  winnt.h


IMAGE_REL_I386_REL32
IMAGE_REL_I386_REL32 024  winnt.h


IMAGE_REL_I386_SECREL
IMAGE_REL_I386_SECREL 013  winnt.h


IMAGE_REL_I386_SECTION
IMAGE_REL_I386_SECTION 012  winnt.h


IMAGE_REL_I386_SEG12
IMAGE_REL_I386_SEG12 011  winnt.h


IMAGE_REL_I860_ABSOLUTE
IMAGE_REL_I860_ABSOLUTE 0  winnt.h


IMAGE_REL_I860_BRADDR
IMAGE_REL_I860_BRADDR 050  winnt.h


IMAGE_REL_I860_DIR32
IMAGE_REL_I860_DIR32 06  winnt.h


IMAGE_REL_I860_DIR32NB
IMAGE_REL_I860_DIR32NB 07  winnt.h


IMAGE_REL_I860_HIGH
IMAGE_REL_I860_HIGH 036  winnt.h


IMAGE_REL_I860_HIGHADJ
IMAGE_REL_I860_HIGHADJ 047  winnt.h


IMAGE_REL_I860_LOW0
IMAGE_REL_I860_LOW0 037  winnt.h


IMAGE_REL_I860_LOW1
IMAGE_REL_I860_LOW1 040  winnt.h


IMAGE_REL_I860_LOW2
IMAGE_REL_I860_LOW2 041  winnt.h


IMAGE_REL_I860_LOW3
IMAGE_REL_I860_LOW3 042  winnt.h


IMAGE_REL_I860_LOW4
IMAGE_REL_I860_LOW4 043  winnt.h


IMAGE_REL_I860_PAIR
IMAGE_REL_I860_PAIR 034  winnt.h


IMAGE_REL_I860_SECREL
IMAGE_REL_I860_SECREL 013  winnt.h


IMAGE_REL_I860_SECTION
IMAGE_REL_I860_SECTION 012  winnt.h


IMAGE_REL_I860_SPLIT0
IMAGE_REL_I860_SPLIT0 044  winnt.h


IMAGE_REL_I860_SPLIT1
IMAGE_REL_I860_SPLIT1 045  winnt.h


IMAGE_REL_I860_SPLIT2
IMAGE_REL_I860_SPLIT2 046  winnt.h


IMAGE_REL_MIPS_ABSOLUTE
IMAGE_REL_MIPS_ABSOLUTE 0  winnt.h


IMAGE_REL_MIPS_GPREL
IMAGE_REL_MIPS_GPREL 06  winnt.h


IMAGE_REL_MIPS_JMPADDR
IMAGE_REL_MIPS_JMPADDR 03  winnt.h


IMAGE_REL_MIPS_LITERAL
IMAGE_REL_MIPS_LITERAL 07  winnt.h


IMAGE_REL_MIPS_PAIR
IMAGE_REL_MIPS_PAIR 045  winnt.h


IMAGE_REL_MIPS_REFHALF
IMAGE_REL_MIPS_REFHALF 01  winnt.h


IMAGE_REL_MIPS_REFHI
IMAGE_REL_MIPS_REFHI 04  winnt.h


IMAGE_REL_MIPS_REFLO
IMAGE_REL_MIPS_REFLO 05  winnt.h


IMAGE_REL_MIPS_REFWORD
IMAGE_REL_MIPS_REFWORD 02  winnt.h


IMAGE_REL_MIPS_REFWORDNB
IMAGE_REL_MIPS_REFWORDNB 042  winnt.h


IMAGE_REL_MIPS_SECREL
IMAGE_REL_MIPS_SECREL 013  winnt.h


IMAGE_REL_MIPS_SECTION
IMAGE_REL_MIPS_SECTION 012  winnt.h


IMAGE_RESOURCE_DATA_IS_DIRECTORY
IMAGE_RESOURCE_DATA_IS_DIRECTORY 0x80000000  winnt.h


IMAGE_RESOURCE_NAME_IS_STRING
IMAGE_RESOURCE_NAME_IS_STRING 0x80000000  winnt.h


IMAGE_SCN_ALIGN_16BYTES
IMAGE_SCN_ALIGN_16BYTES 0x00500000  winnt.h


IMAGE_SCN_ALIGN_1BYTES
IMAGE_SCN_ALIGN_1BYTES 0x00100000  winnt.h


IMAGE_SCN_ALIGN_2BYTES
IMAGE_SCN_ALIGN_2BYTES 0x00200000  winnt.h


IMAGE_SCN_ALIGN_32BYTES
IMAGE_SCN_ALIGN_32BYTES 0x00600000  winnt.h


IMAGE_SCN_ALIGN_4BYTES
IMAGE_SCN_ALIGN_4BYTES 0x00300000  winnt.h


IMAGE_SCN_ALIGN_64BYTES
IMAGE_SCN_ALIGN_64BYTES 0x00700000  winnt.h


IMAGE_SCN_ALIGN_8BYTES
IMAGE_SCN_ALIGN_8BYTES 0x00400000  winnt.h


IMAGE_SCN_CNT_CODE
IMAGE_SCN_CNT_CODE 0x00000020  winnt.h


IMAGE_SCN_CNT_INITIALIZED_DATA
IMAGE_SCN_CNT_INITIALIZED_DATA 0x00000040  winnt.h


IMAGE_SCN_CNT_UNINITIALIZED_DATA
IMAGE_SCN_CNT_UNINITIALIZED_DATA 0x00000080  winnt.h


IMAGE_SCN_LNK_COMDAT
IMAGE_SCN_LNK_COMDAT 0x00001000  winnt.h


IMAGE_SCN_LNK_INFO
IMAGE_SCN_LNK_INFO 0x00000200  winnt.h


IMAGE_SCN_LNK_OTHER
IMAGE_SCN_LNK_OTHER 0x00000100  winnt.h


IMAGE_SCN_LNK_OVERLAY
IMAGE_SCN_LNK_OVERLAY 0x00000400  winnt.h


IMAGE_SCN_LNK_REMOVE
IMAGE_SCN_LNK_REMOVE 0x00000800  winnt.h


IMAGE_SCN_MEM_DISCARDABLE
IMAGE_SCN_MEM_DISCARDABLE 0x02000000  winnt.h


IMAGE_SCN_MEM_EXECUTE
IMAGE_SCN_MEM_EXECUTE 0x20000000  winnt.h


IMAGE_SCN_MEM_NOT_CACHED
IMAGE_SCN_MEM_NOT_CACHED 0x04000000  winnt.h


IMAGE_SCN_MEM_NOT_PAGED
IMAGE_SCN_MEM_NOT_PAGED 0x08000000  winnt.h


IMAGE_SCN_MEM_READ
IMAGE_SCN_MEM_READ 0x40000000  winnt.h


IMAGE_SCN_MEM_SHARED
IMAGE_SCN_MEM_SHARED 0x10000000  winnt.h


IMAGE_SCN_MEM_WRITE
IMAGE_SCN_MEM_WRITE 0x80000000  winnt.h


IMAGE_SCN_TYPE_COPY
IMAGE_SCN_TYPE_COPY 0x00000010  winnt.h


IMAGE_SCN_TYPE_DUMMY
IMAGE_SCN_TYPE_DUMMY 0x00000001  winnt.h


IMAGE_SCN_TYPE_GROUPED
IMAGE_SCN_TYPE_GROUPED 0x00000004  winnt.h


IMAGE_SCN_TYPE_NO_LOAD
IMAGE_SCN_TYPE_NO_LOAD 0x00000002  winnt.h


IMAGE_SCN_TYPE_NO_PAD
IMAGE_SCN_TYPE_NO_PAD 0x00000008  winnt.h


IMAGE_SCN_TYPE_REGULAR
IMAGE_SCN_TYPE_REGULAR 0x00000000  winnt.h


IMAGE_SEPARATE_DEBUG_SIGNATURE
IMAGE_SEPARATE_DEBUG_SIGNATURE 0x4944  winnt.h


IMAGE_SIZEOF_ARCHIVE_MEMBER_HDR
IMAGE_SIZEOF_ARCHIVE_MEMBER_HDR 60  winnt.h


IMAGE_SIZEOF_AUX_SYMBOL
IMAGE_SIZEOF_AUX_SYMBOL 18  winnt.h


IMAGE_SIZEOF_BASE_RELOCATION
IMAGE_SIZEOF_BASE_RELOCATION 8  winnt.h


IMAGE_SIZEOF_FILE_HEADER
IMAGE_SIZEOF_FILE_HEADER 20  winnt.h


IMAGE_SIZEOF_LINENUMBER
IMAGE_SIZEOF_LINENUMBER 6  winnt.h


IMAGE_SIZEOF_NT_OPTIONAL_HEADER
IMAGE_SIZEOF_NT_OPTIONAL_HEADER 224  winnt.h


IMAGE_SIZEOF_RELOCATION
IMAGE_SIZEOF_RELOCATION 10  winnt.h


IMAGE_SIZEOF_SECTION_HEADER
IMAGE_SIZEOF_SECTION_HEADER 40  winnt.h


IMAGE_SIZEOF_SHORT_NAME
IMAGE_SIZEOF_SHORT_NAME 8  winnt.h


IMAGE_SIZEOF_STD_OPTIONAL_HEADER
IMAGE_SIZEOF_STD_OPTIONAL_HEADER 28  winnt.h


IMAGE_SIZEOF_SYMBOL
IMAGE_SIZEOF_SYMBOL 18  winnt.h


IMAGE_SUBSYSTEM_NATIVE
IMAGE_SUBSYSTEM_NATIVE 1  winnt.h


IMAGE_SUBSYSTEM_OS2_CUI
IMAGE_SUBSYSTEM_OS2_CUI 5  winnt.h


IMAGE_SUBSYSTEM_POSIX_CUI
IMAGE_SUBSYSTEM_POSIX_CUI 7  winnt.h


IMAGE_SUBSYSTEM_UNKNOWN
IMAGE_SUBSYSTEM_UNKNOWN 0  winnt.h


IMAGE_SUBSYSTEM_WINDOWS_CUI
IMAGE_SUBSYSTEM_WINDOWS_CUI 3  winnt.h


IMAGE_SUBSYSTEM_WINDOWS_GUI
IMAGE_SUBSYSTEM_WINDOWS_GUI 2  winnt.h


IMAGE_SYM_ABSOLUTE
IMAGE_SYM_ABSOLUTE (SHORT)-1  winnt.h


IMAGE_SYM_CLASS_ARGUMENT
IMAGE_SYM_CLASS_ARGUMENT 9  winnt.h


IMAGE_SYM_CLASS_AUTOMATIC
IMAGE_SYM_CLASS_AUTOMATIC 1  winnt.h


IMAGE_SYM_CLASS_BIT_FIELD
IMAGE_SYM_CLASS_BIT_FIELD 18  winnt.h


IMAGE_SYM_CLASS_BLOCK
IMAGE_SYM_CLASS_BLOCK 100  winnt.h


IMAGE_SYM_CLASS_END_OF_FUNCTION
IMAGE_SYM_CLASS_END_OF_FUNCTION (BYTE )-1  winnt.h


IMAGE_SYM_CLASS_END_OF_STRUCT
IMAGE_SYM_CLASS_END_OF_STRUCT 102  winnt.h


IMAGE_SYM_CLASS_ENUM_TAG
IMAGE_SYM_CLASS_ENUM_TAG 15  winnt.h


IMAGE_SYM_CLASS_EXTERNAL
IMAGE_SYM_CLASS_EXTERNAL 2  winnt.h


IMAGE_SYM_CLASS_EXTERNAL_DEF
IMAGE_SYM_CLASS_EXTERNAL_DEF 5  winnt.h


IMAGE_SYM_CLASS_FILE
IMAGE_SYM_CLASS_FILE 103  winnt.h


IMAGE_SYM_CLASS_FUNCTION
IMAGE_SYM_CLASS_FUNCTION 101  winnt.h


IMAGE_SYM_CLASS_LABEL
IMAGE_SYM_CLASS_LABEL 6  winnt.h


IMAGE_SYM_CLASS_MEMBER_OF_ENUM
IMAGE_SYM_CLASS_MEMBER_OF_ENUM 16  winnt.h


IMAGE_SYM_CLASS_MEMBER_OF_STRUCT
IMAGE_SYM_CLASS_MEMBER_OF_STRUCT 8  winnt.h


IMAGE_SYM_CLASS_MEMBER_OF_UNION
IMAGE_SYM_CLASS_MEMBER_OF_UNION 11  winnt.h


IMAGE_SYM_CLASS_NULL
IMAGE_SYM_CLASS_NULL 0  winnt.h


IMAGE_SYM_CLASS_REGISTER
IMAGE_SYM_CLASS_REGISTER 4  winnt.h


IMAGE_SYM_CLASS_REGISTER_PARAM
IMAGE_SYM_CLASS_REGISTER_PARAM 17  winnt.h


IMAGE_SYM_CLASS_SECTION
IMAGE_SYM_CLASS_SECTION 104  winnt.h


IMAGE_SYM_CLASS_STATIC
IMAGE_SYM_CLASS_STATIC 3  winnt.h


IMAGE_SYM_CLASS_STRUCT_TAG
IMAGE_SYM_CLASS_STRUCT_TAG 10  winnt.h


IMAGE_SYM_CLASS_TYPE_DEFINITION
IMAGE_SYM_CLASS_TYPE_DEFINITION 13  winnt.h


IMAGE_SYM_CLASS_UNDEFINED_LABEL
IMAGE_SYM_CLASS_UNDEFINED_LABEL 7  winnt.h


IMAGE_SYM_CLASS_UNDEFINED_STATIC
IMAGE_SYM_CLASS_UNDEFINED_STATIC 14  winnt.h


IMAGE_SYM_CLASS_UNION_TAG
IMAGE_SYM_CLASS_UNION_TAG 12  winnt.h


IMAGE_SYM_CLASS_WEAK_EXTERNAL
IMAGE_SYM_CLASS_WEAK_EXTERNAL 105  winnt.h


IMAGE_SYM_DEBUG
IMAGE_SYM_DEBUG (SHORT)-2  winnt.h


IMAGE_SYM_DTYPE_ARRAY
IMAGE_SYM_DTYPE_ARRAY 3  winnt.h


IMAGE_SYM_DTYPE_FUNCTION
IMAGE_SYM_DTYPE_FUNCTION 2  winnt.h


IMAGE_SYM_DTYPE_NULL
IMAGE_SYM_DTYPE_NULL 0  winnt.h


IMAGE_SYM_DTYPE_POINTER
IMAGE_SYM_DTYPE_POINTER 1  winnt.h


IMAGE_SYM_TYPE_BYTE
IMAGE_SYM_TYPE_BYTE 12  winnt.h


IMAGE_SYM_TYPE_CHAR
IMAGE_SYM_TYPE_CHAR 2  winnt.h


IMAGE_SYM_TYPE_DOUBLE
IMAGE_SYM_TYPE_DOUBLE 7  winnt.h


IMAGE_SYM_TYPE_DWORD
IMAGE_SYM_TYPE_DWORD 15  winnt.h


IMAGE_SYM_TYPE_ENUM
IMAGE_SYM_TYPE_ENUM 10  winnt.h


IMAGE_SYM_TYPE_FLOAT
IMAGE_SYM_TYPE_FLOAT 6  winnt.h


IMAGE_SYM_TYPE_INT
IMAGE_SYM_TYPE_INT 4  winnt.h


IMAGE_SYM_TYPE_LONG
IMAGE_SYM_TYPE_LONG 5  winnt.h


IMAGE_SYM_TYPE_MOE
IMAGE_SYM_TYPE_MOE 11  winnt.h


IMAGE_SYM_TYPE_NULL
IMAGE_SYM_TYPE_NULL 0  winnt.h


IMAGE_SYM_TYPE_SHORT
IMAGE_SYM_TYPE_SHORT 3  winnt.h


IMAGE_SYM_TYPE_STRUCT
IMAGE_SYM_TYPE_STRUCT 8  winnt.h


IMAGE_SYM_TYPE_UINT
IMAGE_SYM_TYPE_UINT 14  winnt.h


IMAGE_SYM_TYPE_UNION
IMAGE_SYM_TYPE_UNION 9  winnt.h


IMAGE_SYM_TYPE_VOID
IMAGE_SYM_TYPE_VOID 1  winnt.h


IMAGE_SYM_TYPE_WORD
IMAGE_SYM_TYPE_WORD 13  winnt.h


IMAGE_SYM_UNDEFINED
IMAGE_SYM_UNDEFINED (SHORT)0  winnt.h


IMAGE_WEAK_EXTERN_SEARCH_LIBRARY
IMAGE_WEAK_EXTERN_SEARCH_LIBRARY 2  winnt.h


IMAGE_WEAK_EXTERN_SEARCH_NOLIBRARY
IMAGE_WEAK_EXTERN_SEARCH_NOLIBRARY 1  winnt.h


IMAGE_WEAK_EXTERN_SEARCH_UNKNOWN
IMAGE_WEAK_EXTERN_SEARCH_UNKNOWN 0  winnt.h


IMPLINK_HIGHEXPER
IMPLINK_HIGHEXPER 158  winsock.h


IMPLINK_IP
IMPLINK_IP 155  winsock.h


IMPLINK_LOWEXPER
IMPLINK_LOWEXPER 156  winsock.h


IN_CLASSA_HOST
IN_CLASSA_HOST 0x00ffffff  winsock.h


IN_CLASSA_MAX
IN_CLASSA_MAX 128  winsock.h


IN_CLASSA_NET
IN_CLASSA_NET 0xff000000  winsock.h


IN_CLASSA_NSHIFT
IN_CLASSA_NSHIFT 24  winsock.h


IN_CLASSB_HOST
IN_CLASSB_HOST 0x0000ffff  winsock.h


IN_CLASSB_MAX
IN_CLASSB_MAX 65536  winsock.h


IN_CLASSB_NET
IN_CLASSB_NET 0xffff0000  winsock.h


IN_CLASSB_NSHIFT
IN_CLASSB_NSHIFT 16  winsock.h


IN_CLASSC_HOST
IN_CLASSC_HOST 0x000000ff  winsock.h


IN_CLASSC_NET
IN_CLASSC_NET 0xffffff00  winsock.h


IN_CLASSC_NSHIFT
IN_CLASSC_NSHIFT 8  winsock.h


INADDR_ANY
INADDR_ANY (u_long)0x00000000  winsock.h


INADDR_BROADCAST
INADDR_BROADCAST (u_long)0xffffffff  winsock.h


INADDR_LOOPBACK
INADDR_LOOPBACK 0x7f000001  winsock.h


INADDR_NONE
INADDR_NONE 0xffffffff  winsock.h


INFINITE
INFINITE 0xFFFFFFFF  winbase.h


INVALID_FILE_SIZE
INVALID_FILE_SIZE (DWORD)0xFFFFFFFF  winbase.h


INVALID_HANDLE_VALUE
INVALID_HANDLE_VALUE (HANDLE)-1  winbase.h


IOC_IN
IOC_IN 0x80000000  winsock.h


IOC_INOUT
IOC_INOUT (IOC_IN|IOC_OUT)  winsock.h


IOC_OUT
IOC_OUT 0x40000000  winsock.h


IOC_VOID
IOC_VOID 0x20000000  winsock.h


IOCPARM_MASK
IOCPARM_MASK 0x7f  winsock.h


IP_OPTIONS
IP_OPTIONS 1  winsock.h


IPPORT_BIFFUDP
IPPORT_BIFFUDP 512  winsock.h


IPPORT_CMDSERVER
IPPORT_CMDSERVER 514  winsock.h


IPPORT_DAYTIME
IPPORT_DAYTIME 13  winsock.h


IPPORT_DISCARD
IPPORT_DISCARD 9  winsock.h


IPPORT_ECHO
IPPORT_ECHO 7  winsock.h


IPPORT_EFSSERVER
IPPORT_EFSSERVER 520  winsock.h


IPPORT_EXECSERVER
IPPORT_EXECSERVER 512  winsock.h


IPPORT_FINGER
IPPORT_FINGER 79  winsock.h


IPPORT_FTP
IPPORT_FTP 21  winsock.h


IPPORT_LOGINSERVER
IPPORT_LOGINSERVER 513  winsock.h


IPPORT_MTP
IPPORT_MTP 57  winsock.h


IPPORT_NAMESERVER
IPPORT_NAMESERVER 42  winsock.h


IPPORT_NETSTAT
IPPORT_NETSTAT 15  winsock.h


IPPORT_RESERVED
IPPORT_RESERVED 1024  winsock.h


IPPORT_RJE
IPPORT_RJE 77  winsock.h


IPPORT_ROUTESERVER
IPPORT_ROUTESERVER 520  winsock.h


IPPORT_SMTP
IPPORT_SMTP 25  winsock.h


IPPORT_SUPDUP
IPPORT_SUPDUP 95  winsock.h


IPPORT_SYSTAT
IPPORT_SYSTAT 11  winsock.h


IPPORT_TELNET
IPPORT_TELNET 23  winsock.h


IPPORT_TFTP
IPPORT_TFTP 69  winsock.h


IPPORT_TIMESERVER
IPPORT_TIMESERVER 37  winsock.h


IPPORT_TTYLINK
IPPORT_TTYLINK 87  winsock.h


IPPORT_WHOIS
IPPORT_WHOIS 43  winsock.h


IPPORT_WHOSERVER
IPPORT_WHOSERVER 513  winsock.h


IPPROTO_GGP
IPPROTO_GGP 2  winsock.h


IPPROTO_ICMP
IPPROTO_ICMP 1  winsock.h


IPPROTO_IDP
IPPROTO_IDP 22  winsock.h


IPPROTO_IP
IPPROTO_IP 0  winsock.h


IPPROTO_MAX
IPPROTO_MAX 256  winsock.h


IPPROTO_ND
IPPROTO_ND 77  winsock.h


IPPROTO_PUP
IPPROTO_PUP 12  winsock.h


IPPROTO_RAW
IPPROTO_RAW 255  winsock.h


IPPROTO_TCP
IPPROTO_TCP 6  winsock.h


IPPROTO_UDP
IPPROTO_UDP 17  winsock.h


ITALIC_FONTTYPE
ITALIC_FONTTYPE 0x0200  commdlg.h


JOB_ACCESS_ADMINISTER
JOB_ACCESS_ADMINISTER 0x00000010  winspool.h


JOB_ALL_ACCESS
JOB_ALL_ACCESS (STANDARD_RIGHTS_REQUIRED | JOB_ACCESS_ADMINISTER)  winspool.h


JOB_EXECUTE
JOB_EXECUTE (STANDARD_RIGHTS_EXECUTE | JOB_ACCESS_ADMINISTER)  winspool.h


JOB_POSITION_UNSPECIFIED
JOB_POSITION_UNSPECIFIED 0  winspool.h


JOB_READ
JOB_READ (STANDARD_RIGHTS_READ | JOB_ACCESS_ADMINISTER)  winspool.h


JOB_STATUS_DELETING
JOB_STATUS_DELETING 0x00000004  winspool.h


JOB_STATUS_ERROR
JOB_STATUS_ERROR 0x00000002  winspool.h


JOB_STATUS_OFFLINE
JOB_STATUS_OFFLINE 0x00000020  winspool.h


JOB_STATUS_PAPEROUT
JOB_STATUS_PAPEROUT 0x00000040  winspool.h


JOB_STATUS_PAUSED
JOB_STATUS_PAUSED 0x00000001  winspool.h


JOB_STATUS_PRINTED
JOB_STATUS_PRINTED 0x00000080  winspool.h


JOB_STATUS_PRINTING
JOB_STATUS_PRINTING 0x00000010  winspool.h


JOB_STATUS_SPOOLING
JOB_STATUS_SPOOLING 0x00000008  winspool.h


JOB_WRITE
JOB_WRITE (STANDARD_RIGHTS_WRITE | JOB_ACCESS_ADMINISTER)  winspool.h


JOYERR_BASE
JOYERR_BASE 160  mmsystem.h


JOYERR_NOERROR
JOYERR_NOERROR (0)  mmsystem.h


JOYSTICKID1
JOYSTICKID1 0  mmsystem.h


JOYSTICKID2
JOYSTICKID2 1  mmsystem.h


KEY_CREATE_LINK
KEY_CREATE_LINK (0x0020)  winnt.h


KEY_EVENT
KEY_EVENT 0x0001  wincon.h


KF_ALTDOWN
KF_ALTDOWN 0x2000  winuser.h


KF_DLGMODE
KF_DLGMODE 0x0800  winuser.h


KF_EXTENDED
KF_EXTENDED 0x0100  winuser.h


KF_MENUMODE
KF_MENUMODE 0x1000  winuser.h


KF_REPEAT
KF_REPEAT 0x4000  winuser.h


KF_UP
KF_UP 0x8000  winuser.h


KL_NAMELENGTH
KL_NAMELENGTH 9  winuser.h


KLF_ACTIVATE
KLF_ACTIVATE 0x00000001  winuser.h


KLF_REORDER
KLF_REORDER 0x00000008  winuser.h


KLF_SUBSTITUTE_OK
KLF_SUBSTITUTE_OK 0x00000002  winuser.h


KLF_UNLOADPREVIOUS
KLF_UNLOADPREVIOUS 0x00000004  winuser.h


LBS_DISABLENOSCROLL
LBS_DISABLENOSCROLL 0x1000L  winuser.h


LBS_EXTENDEDSEL
LBS_EXTENDEDSEL 0x0800L  winuser.h


LBS_HASSTRINGS
LBS_HASSTRINGS 0x0040L  winuser.h


LBS_MULTICOLUMN
LBS_MULTICOLUMN 0x0200L  winuser.h


LBS_MULTIPLESEL
LBS_MULTIPLESEL 0x0008L  winuser.h


LBS_NODATA
LBS_NODATA 0x2000L  winuser.h


LBS_NOINTEGRALHEIGHT
LBS_NOINTEGRALHEIGHT 0x0100L  winuser.h


LBS_NOREDRAW
LBS_NOREDRAW 0x0004L  winuser.h


LBS_NOTIFY
LBS_NOTIFY 0x0001L  winuser.h


LBS_OWNERDRAWFIXED
LBS_OWNERDRAWFIXED 0x0010L  winuser.h


LBS_OWNERDRAWVARIABLE
LBS_OWNERDRAWVARIABLE 0x0020L  winuser.h


LBS_SORT
LBS_SORT 0x0002L  winuser.h


LBS_STANDARD
LBS_STANDARD (LBS_NOTIFY | LBS_SORT | WS_VSCROLL | WS_BORDER)  winuser.h


LBS_USETABSTOPS
LBS_USETABSTOPS 0x0080L  winuser.h


LBS_WANTKEYBOARDINPUT
LBS_WANTKEYBOARDINPUT 0x0400L  winuser.h


LBSELCHSTRING
LBSELCHSTRING LBSELCHSTRINGA  commdlg.h


LBSELCHSTRING
LBSELCHSTRING LBSELCHSTRINGW  commdlg.h


LBSELCHSTRINGA
LBSELCHSTRINGA "commdlg_LBSelChangedNotify"  commdlg.h


LBSELCHSTRINGW
LBSELCHSTRINGW L"commdlg_LBSelChangedNotify"  commdlg.h


LC_INTERIORS
LC_INTERIORS 128  wingdi.h


LC_MARKER
LC_MARKER 4  wingdi.h


LC_NONE
LC_NONE 0  wingdi.h


LC_POLYLINE
LC_POLYLINE 2  wingdi.h


LC_POLYMARKER
LC_POLYMARKER 8  wingdi.h


LC_STYLED
LC_STYLED 32  wingdi.h


LC_WIDE
LC_WIDE 16  wingdi.h


LC_WIDESTYLED
LC_WIDESTYLED 64  wingdi.h


LF_FACESIZE
LF_FACESIZE 32  wingdi.h


LF_FULLFACESIZE
LF_FULLFACESIZE 64  wingdi.h


LHND
LHND (LMEM_MOVEABLE | LMEM_ZEROINIT)  winbase.h


LLC_ADAPTER_ETHERNET
LLC_ADAPTER_ETHERNET 0x0010  dlcapi.h


LLC_ADAPTER_TOKEN_RING
LLC_ADAPTER_TOKEN_RING 0x0040  dlcapi.h


LLC_BUFFER_CREATE
LLC_BUFFER_CREATE 0x30  dlcapi.h


LLC_BUFFER_FREE
LLC_BUFFER_FREE 0x27  dlcapi.h


LLC_BUFFER_GET
LLC_BUFFER_GET 0x26  dlcapi.h


LLC_CHAIN_XMIT_COMMANDS_ON_LINK
LLC_CHAIN_XMIT_COMMANDS_ON_LINK 0  dlcapi.h


LLC_CHAIN_XMIT_COMMANDS_ON_SAP
LLC_CHAIN_XMIT_COMMANDS_ON_SAP 2  dlcapi.h


LLC_COMPLETE_SINGLE_XMIT_FRAME
LLC_COMPLETE_SINGLE_XMIT_FRAME 1  dlcapi.h


LLC_CONTIGUOUS_DATA
LLC_CONTIGUOUS_DATA 0x40  dlcapi.h


LLC_CONTIGUOUS_MAC
LLC_CONTIGUOUS_MAC 0x80  dlcapi.h


LLC_DECREASE_LINK_STATIONS
LLC_DECREASE_LINK_STATIONS 0x80  dlcapi.h


LLC_DIR_CLOSE_ADAPTER
LLC_DIR_CLOSE_ADAPTER 0x04  dlcapi.h


LLC_DIR_CLOSE_DIRECT
LLC_DIR_CLOSE_DIRECT 0x34  dlcapi.h


LLC_DIR_INITIALIZE
LLC_DIR_INITIALIZE 0x20  dlcapi.h


LLC_DIR_INTERRUPT
LLC_DIR_INTERRUPT 0x00  dlcapi.h


LLC_DIR_OPEN_ADAPTER
LLC_DIR_OPEN_ADAPTER 0x03  dlcapi.h


LLC_DIR_OPEN_DIRECT
LLC_DIR_OPEN_DIRECT 0x35  dlcapi.h


LLC_DIR_RCV_ALL_8022_FRAMES
LLC_DIR_RCV_ALL_8022_FRAMES 2  dlcapi.h


LLC_DIR_RCV_ALL_ETHERNET_TYPES
LLC_DIR_RCV_ALL_ETHERNET_TYPES 5  dlcapi.h


LLC_DIR_RCV_ALL_FRAMES
LLC_DIR_RCV_ALL_FRAMES 4  dlcapi.h


LLC_DIR_RCV_ALL_MAC_FRAMES
LLC_DIR_RCV_ALL_MAC_FRAMES 1  dlcapi.h


LLC_DIR_RCV_ALL_TR_FRAMES
LLC_DIR_RCV_ALL_TR_FRAMES 0  dlcapi.h


LLC_DIR_READ_LOG
LLC_DIR_READ_LOG 0x08  dlcapi.h


LLC_DIR_READ_LOG_ADAPTER
LLC_DIR_READ_LOG_ADAPTER 0  dlcapi.h


LLC_DIR_READ_LOG_BOTH
LLC_DIR_READ_LOG_BOTH 2  dlcapi.h


LLC_DIR_READ_LOG_DIRECT
LLC_DIR_READ_LOG_DIRECT 1  dlcapi.h


LLC_DIR_SET_EXCEPTION_FLAGS
LLC_DIR_SET_EXCEPTION_FLAGS 0x2D  dlcapi.h


LLC_DIR_SET_FUNCTIONAL_ADDRESS
LLC_DIR_SET_FUNCTIONAL_ADDRESS 0x07  dlcapi.h


LLC_DIR_SET_GROUP_ADDRESS
LLC_DIR_SET_GROUP_ADDRESS 0x06  dlcapi.h


LLC_DIR_SET_MULTICAST_ADDRESS
LLC_DIR_SET_MULTICAST_ADDRESS 0x05  dlcapi.h


LLC_DIR_STATUS
LLC_DIR_STATUS 0x21  dlcapi.h


LLC_DIR_TIMER_CANCEL
LLC_DIR_TIMER_CANCEL 0x23  dlcapi.h


LLC_DIR_TIMER_CANCEL_GROUP
LLC_DIR_TIMER_CANCEL_GROUP 0x2C  dlcapi.h


LLC_DIR_TIMER_SET
LLC_DIR_TIMER_SET 0x22  dlcapi.h


LLC_DIRECT_OPTIONS_ALL_MACS
LLC_DIRECT_OPTIONS_ALL_MACS 0x1880  dlcapi.h


LLC_DLC_CLOSE_SAP
LLC_DLC_CLOSE_SAP 0x16  dlcapi.h


LLC_DLC_CLOSE_STATION
LLC_DLC_CLOSE_STATION 0x1A  dlcapi.h


LLC_DLC_CONNECT_STATION
LLC_DLC_CONNECT_STATION 0x1B  dlcapi.h


LLC_DLC_FLOW_CONTROL
LLC_DLC_FLOW_CONTROL 0x1D  dlcapi.h


LLC_DLC_MODIFY
LLC_DLC_MODIFY 0x1C  dlcapi.h


LLC_DLC_OPEN_SAP
LLC_DLC_OPEN_SAP 0x15  dlcapi.h


LLC_DLC_OPEN_STATION
LLC_DLC_OPEN_STATION 0x19  dlcapi.h


LLC_DLC_READ_STATISTICS
LLC_DLC_READ_STATISTICS 0  dlcapi.h


LLC_DLC_REALLOCATE_STATIONS
LLC_DLC_REALLOCATE_STATIONS 0x17  dlcapi.h


LLC_DLC_RESET
LLC_DLC_RESET 0x14  dlcapi.h


LLC_DLC_RESET_STATISTICS
LLC_DLC_RESET_STATISTICS 0x80  dlcapi.h


LLC_DLC_SET_THRESHOLD
LLC_DLC_SET_THRESHOLD 0x33  dlcapi.h


LLC_DLC_STATISTICS
LLC_DLC_STATISTICS 0x1E  dlcapi.h


LLC_EVENT_COMMAND_COMPLETION
LLC_EVENT_COMMAND_COMPLETION 0x0001  dlcapi.h


LLC_EVENT_CRITICAL_EXCEPTION
LLC_EVENT_CRITICAL_EXCEPTION 0x0010  dlcapi.h


LLC_EVENT_NETWORK_STATUS
LLC_EVENT_NETWORK_STATUS 0x0020  dlcapi.h


LLC_EVENT_RECEIVE_DATA
LLC_EVENT_RECEIVE_DATA 0x0004  dlcapi.h


LLC_EVENT_STATUS_CHANGE
LLC_EVENT_STATUS_CHANGE 0x0008  dlcapi.h


LLC_EVENT_SYSTEM_ACTION
LLC_EVENT_SYSTEM_ACTION 0x0040  dlcapi.h


LLC_EVENT_TRANSMIT_COMPLETION
LLC_EVENT_TRANSMIT_COMPLETION 0x0002  dlcapi.h


LLC_FIRST_DATA_SEGMENT
LLC_FIRST_DATA_SEGMENT 0x01  dlcapi.h


LLC_GROUP_SAP
LLC_GROUP_SAP 0x02  dlcapi.h


LLC_INCREASE_LINK_STATIONS
LLC_INCREASE_LINK_STATIONS 0  dlcapi.h


LLC_INDICATE_ACCESS_PRTY_LOWERED
LLC_INDICATE_ACCESS_PRTY_LOWERED 0x0020  dlcapi.h


LLC_INDICATE_CONNECT_REQUEST
LLC_INDICATE_CONNECT_REQUEST 0x0400  dlcapi.h


LLC_INDICATE_DLC_COUNTER_OVERFLOW
LLC_INDICATE_DLC_COUNTER_OVERFLOW 0x0040  dlcapi.h


LLC_INDICATE_DM_DISC_RECEIVED
LLC_INDICATE_DM_DISC_RECEIVED 0x4000  dlcapi.h


LLC_INDICATE_FRMR_RECEIVED
LLC_INDICATE_FRMR_RECEIVED 0x2000  dlcapi.h


LLC_INDICATE_FRMR_SENT
LLC_INDICATE_FRMR_SENT 0x1000  dlcapi.h


LLC_INDICATE_LINK_LOST
LLC_INDICATE_LINK_LOST 0x8000  dlcapi.h


LLC_INDICATE_LOCAL_STATION_BUSY
LLC_INDICATE_LOCAL_STATION_BUSY 0x0001  dlcapi.h


LLC_INDICATE_REMOTE_BUSY
LLC_INDICATE_REMOTE_BUSY 0x0200  dlcapi.h


LLC_INDICATE_REMOTE_READY
LLC_INDICATE_REMOTE_READY 0x0100  dlcapi.h


LLC_INDICATE_RESET
LLC_INDICATE_RESET 0x0800  dlcapi.h


LLC_INDICATE_TI_TIMER_EXPIRED
LLC_INDICATE_TI_TIMER_EXPIRED 0x0080  dlcapi.h


LLC_INDIVIDUAL_SAP
LLC_INDIVIDUAL_SAP 0x04  dlcapi.h


LLC_MAX_DLC_COMMAND
LLC_MAX_DLC_COMMAND 0x37  dlcapi.h


LLC_MEMBER_OF_GROUP_SAP
LLC_MEMBER_OF_GROUP_SAP 0x01  dlcapi.h


LLC_NEXT_DATA_SEGMENT
LLC_NEXT_DATA_SEGMENT 0x02  dlcapi.h


LLC_NOT_CONTIGUOUS_DATA
LLC_NOT_CONTIGUOUS_DATA 0x00  dlcapi.h


LLC_OPTION_READ_ALL
LLC_OPTION_READ_ALL 2  dlcapi.h


LLC_OPTION_READ_SAP
LLC_OPTION_READ_SAP 1  dlcapi.h


LLC_OPTION_READ_STATION
LLC_OPTION_READ_STATION 0  dlcapi.h


LLC_RCV_CHAIN_FRAMES_ON_LINK
LLC_RCV_CHAIN_FRAMES_ON_LINK 1  dlcapi.h


LLC_RCV_CHAIN_FRAMES_ON_SAP
LLC_RCV_CHAIN_FRAMES_ON_SAP 2  dlcapi.h


LLC_RCV_READ_INDIVIDUAL_FRAMES
LLC_RCV_READ_INDIVIDUAL_FRAMES 0  dlcapi.h


LLC_READ
LLC_READ 0x31  dlcapi.h


LLC_READ_ALL_EVENTS
LLC_READ_ALL_EVENTS 0x007F  dlcapi.h


LLC_READ_CANCEL
LLC_READ_CANCEL 0x32  dlcapi.h


LLC_RECEIVE
LLC_RECEIVE 0x28  dlcapi.h


LLC_RECEIVE_CANCEL
LLC_RECEIVE_CANCEL 0x29  dlcapi.h


LLC_RECEIVE_MODIFY
LLC_RECEIVE_MODIFY 0x2A  dlcapi.h


LLC_RESET_LOCAL_BUSY_BUFFER
LLC_RESET_LOCAL_BUSY_BUFFER 0xC0  dlcapi.h


LLC_RESET_LOCAL_BUSY_USER
LLC_RESET_LOCAL_BUSY_USER 0x80  dlcapi.h


LLC_SET_LOCAL_BUSY_USER
LLC_SET_LOCAL_BUSY_USER 0  dlcapi.h


LLC_STATUS_MAX_ERROR
LLC_STATUS_MAX_ERROR 0xFF  dlcapi.h


LLC_TRANSMIT_DIR_FRAME
LLC_TRANSMIT_DIR_FRAME 0x0A  dlcapi.h


LLC_TRANSMIT_FRAMES
LLC_TRANSMIT_FRAMES 0x09  dlcapi.h


LLC_TRANSMIT_I_FRAME
LLC_TRANSMIT_I_FRAME 0x0B  dlcapi.h


LLC_TRANSMIT_TEST_CMD
LLC_TRANSMIT_TEST_CMD 0x11  dlcapi.h


LLC_TRANSMIT_UI_FRAME
LLC_TRANSMIT_UI_FRAME 0x0D  dlcapi.h


LLC_TRANSMIT_XID_CMD
LLC_TRANSMIT_XID_CMD 0x0E  dlcapi.h


LLC_TRANSMIT_XID_RESP_FINAL
LLC_TRANSMIT_XID_RESP_FINAL 0x0F  dlcapi.h


LLC_TRANSMIT_XID_RESP_NOT_FINAL
LLC_TRANSMIT_XID_RESP_NOT_FINAL 0x10  dlcapi.h


LLC_XID_HANDLING_IN_APPLICATION
LLC_XID_HANDLING_IN_APPLICATION 0x08  dlcapi.h


LLC_XID_HANDLING_IN_DLC
LLC_XID_HANDLING_IN_DLC 0  dlcapi.h


LLC_XMIT_BUFFER_SIZE
LLC_XMIT_BUFFER_SIZE sizeof(LLC_XMIT_BUFFER)  dlcapi.h


LMEM_DISCARDABLE
LMEM_DISCARDABLE 0x0F00  winbase.h


LMEM_DISCARDED
LMEM_DISCARDED 0x4000  winbase.h


LMEM_FIXED
LMEM_FIXED 0x0000  winbase.h


LMEM_INVALID_HANDLE
LMEM_INVALID_HANDLE 0x8000  winbase.h


LMEM_LOCKCOUNT
LMEM_LOCKCOUNT 0x00FF  winbase.h


LMEM_MODIFY
LMEM_MODIFY 0x0080  winbase.h


LMEM_MOVEABLE
LMEM_MOVEABLE 0x0002  winbase.h


LMEM_NOCOMPACT
LMEM_NOCOMPACT 0x0010  winbase.h


LMEM_NODISCARD
LMEM_NODISCARD 0x0020  winbase.h


LMEM_VALID_FLAGS
LMEM_VALID_FLAGS 0x0F72  winbase.h


LMEM_ZEROINIT
LMEM_ZEROINIT 0x0040  winbase.h


LOCALE_ICENTURY
LOCALE_ICENTURY 0x00000024  winnls.h


LOCALE_ICOUNTRY
LOCALE_ICOUNTRY 0x00000005  winnls.h


LOCALE_ICURRDIGITS
LOCALE_ICURRDIGITS 0x00000019  winnls.h


LOCALE_ICURRENCY
LOCALE_ICURRENCY 0x0000001B  winnls.h


LOCALE_IDATE
LOCALE_IDATE 0x00000021  winnls.h


LOCALE_IDAYLZERO
LOCALE_IDAYLZERO 0x00000026  winnls.h


LOCALE_IDEFAULTCODEPAGE
LOCALE_IDEFAULTCODEPAGE 0x0000000B  winnls.h


LOCALE_IDEFAULTCOUNTRY
LOCALE_IDEFAULTCOUNTRY 0x0000000A  winnls.h


LOCALE_IDEFAULTLANGUAGE
LOCALE_IDEFAULTLANGUAGE 0x00000009  winnls.h


LOCALE_IDIGITS
LOCALE_IDIGITS 0x00000011  winnls.h


LOCALE_IINTLCURRDIGITS
LOCALE_IINTLCURRDIGITS 0x0000001A  winnls.h


LOCALE_ILANGUAGE
LOCALE_ILANGUAGE 0x00000001  winnls.h


LOCALE_ILDATE
LOCALE_ILDATE 0x00000022  winnls.h


LOCALE_ILZERO
LOCALE_ILZERO 0x00000012  winnls.h


LOCALE_IMEASURE
LOCALE_IMEASURE 0x0000000D  winnls.h


LOCALE_IMONLZERO
LOCALE_IMONLZERO 0x00000027  winnls.h


LOCALE_INEGCURR
LOCALE_INEGCURR 0x0000001C  winnls.h


LOCALE_INEGSEPBYSPACE
LOCALE_INEGSEPBYSPACE 0x00000057  winnls.h


LOCALE_INEGSIGNPOSN
LOCALE_INEGSIGNPOSN 0x00000053  winnls.h


LOCALE_INEGSYMPRECEDES
LOCALE_INEGSYMPRECEDES 0x00000056  winnls.h


LOCALE_IPOSSEPBYSPACE
LOCALE_IPOSSEPBYSPACE 0x00000055  winnls.h


LOCALE_IPOSSIGNPOSN
LOCALE_IPOSSIGNPOSN 0x00000052  winnls.h


LOCALE_IPOSSYMPRECEDES
LOCALE_IPOSSYMPRECEDES 0x00000054  winnls.h


LOCALE_ITIME
LOCALE_ITIME 0x00000023  winnls.h


LOCALE_ITLZERO
LOCALE_ITLZERO 0x00000025  winnls.h


LOCALE_NOUSEROVERRIDE
LOCALE_NOUSEROVERRIDE 0x80000000  winnls.h


LOCALE_S1159
LOCALE_S1159 0x00000028  winnls.h


LOCALE_S2359
LOCALE_S2359 0x00000029  winnls.h


LOCALE_SABBREVCTRYNAME
LOCALE_SABBREVCTRYNAME 0x00000007  winnls.h


LOCALE_SABBREVDAYNAME1
LOCALE_SABBREVDAYNAME1 0x00000031  winnls.h


LOCALE_SABBREVDAYNAME2
LOCALE_SABBREVDAYNAME2 0x00000032  winnls.h


LOCALE_SABBREVDAYNAME3
LOCALE_SABBREVDAYNAME3 0x00000033  winnls.h


LOCALE_SABBREVDAYNAME4
LOCALE_SABBREVDAYNAME4 0x00000034  winnls.h


LOCALE_SABBREVDAYNAME5
LOCALE_SABBREVDAYNAME5 0x00000035  winnls.h


LOCALE_SABBREVDAYNAME6
LOCALE_SABBREVDAYNAME6 0x00000036  winnls.h


LOCALE_SABBREVDAYNAME7
LOCALE_SABBREVDAYNAME7 0x00000037  winnls.h


LOCALE_SABBREVLANGNAME
LOCALE_SABBREVLANGNAME 0x00000003  winnls.h


LOCALE_SABBREVMONTHNAME1
LOCALE_SABBREVMONTHNAME1 0x00000044  winnls.h


LOCALE_SABBREVMONTHNAME10
LOCALE_SABBREVMONTHNAME10 0x0000004D  winnls.h


LOCALE_SABBREVMONTHNAME11
LOCALE_SABBREVMONTHNAME11 0x0000004E  winnls.h


LOCALE_SABBREVMONTHNAME12
LOCALE_SABBREVMONTHNAME12 0x0000004F  winnls.h


LOCALE_SABBREVMONTHNAME2
LOCALE_SABBREVMONTHNAME2 0x00000045  winnls.h


LOCALE_SABBREVMONTHNAME3
LOCALE_SABBREVMONTHNAME3 0x00000046  winnls.h


LOCALE_SABBREVMONTHNAME4
LOCALE_SABBREVMONTHNAME4 0x00000047  winnls.h


LOCALE_SABBREVMONTHNAME5
LOCALE_SABBREVMONTHNAME5 0x00000048  winnls.h


LOCALE_SABBREVMONTHNAME6
LOCALE_SABBREVMONTHNAME6 0x00000049  winnls.h


LOCALE_SABBREVMONTHNAME7
LOCALE_SABBREVMONTHNAME7 0x0000004A  winnls.h


LOCALE_SABBREVMONTHNAME8
LOCALE_SABBREVMONTHNAME8 0x0000004B  winnls.h


LOCALE_SABBREVMONTHNAME9
LOCALE_SABBREVMONTHNAME9 0x0000004C  winnls.h


LOCALE_SCOUNTRY
LOCALE_SCOUNTRY 0x00000006  winnls.h


LOCALE_SCURRENCY
LOCALE_SCURRENCY 0x00000014  winnls.h


LOCALE_SDATE
LOCALE_SDATE 0x0000001D  winnls.h


LOCALE_SDAYNAME1
LOCALE_SDAYNAME1 0x0000002A  winnls.h


LOCALE_SDAYNAME2
LOCALE_SDAYNAME2 0x0000002B  winnls.h


LOCALE_SDAYNAME3
LOCALE_SDAYNAME3 0x0000002C  winnls.h


LOCALE_SDAYNAME4
LOCALE_SDAYNAME4 0x0000002D  winnls.h


LOCALE_SDAYNAME5
LOCALE_SDAYNAME5 0x0000002E  winnls.h


LOCALE_SDAYNAME6
LOCALE_SDAYNAME6 0x0000002F  winnls.h


LOCALE_SDAYNAME7
LOCALE_SDAYNAME7 0x00000030  winnls.h


LOCALE_SDECIMAL
LOCALE_SDECIMAL 0x0000000E  winnls.h


LOCALE_SENGCOUNTRY
LOCALE_SENGCOUNTRY 0x00001002  winnls.h


LOCALE_SENGLANGUAGE
LOCALE_SENGLANGUAGE 0x00001001  winnls.h


LOCALE_SGROUPING
LOCALE_SGROUPING 0x00000010  winnls.h


LOCALE_SINTLSYMBOL
LOCALE_SINTLSYMBOL 0x00000015  winnls.h


LOCALE_SLANGUAGE
LOCALE_SLANGUAGE 0x00000002  winnls.h


LOCALE_SLIST
LOCALE_SLIST 0x0000000C  winnls.h


LOCALE_SLONGDATE
LOCALE_SLONGDATE 0x00000020  winnls.h


LOCALE_SMONDECIMALSEP
LOCALE_SMONDECIMALSEP 0x00000016  winnls.h


LOCALE_SMONGROUPING
LOCALE_SMONGROUPING 0x00000018  winnls.h


LOCALE_SMONTHNAME1
LOCALE_SMONTHNAME1 0x00000038  winnls.h


LOCALE_SMONTHNAME10
LOCALE_SMONTHNAME10 0x00000041  winnls.h


LOCALE_SMONTHNAME11
LOCALE_SMONTHNAME11 0x00000042  winnls.h


LOCALE_SMONTHNAME12
LOCALE_SMONTHNAME12 0x00000043  winnls.h


LOCALE_SMONTHNAME2
LOCALE_SMONTHNAME2 0x00000039  winnls.h


LOCALE_SMONTHNAME3
LOCALE_SMONTHNAME3 0x0000003A  winnls.h


LOCALE_SMONTHNAME4
LOCALE_SMONTHNAME4 0x0000003B  winnls.h


LOCALE_SMONTHNAME5
LOCALE_SMONTHNAME5 0x0000003C  winnls.h


LOCALE_SMONTHNAME6
LOCALE_SMONTHNAME6 0x0000003D  winnls.h


LOCALE_SMONTHNAME7
LOCALE_SMONTHNAME7 0x0000003E  winnls.h


LOCALE_SMONTHNAME8
LOCALE_SMONTHNAME8 0x0000003F  winnls.h


LOCALE_SMONTHNAME9
LOCALE_SMONTHNAME9 0x00000040  winnls.h


LOCALE_SMONTHOUSANDSEP
LOCALE_SMONTHOUSANDSEP 0x00000017  winnls.h


LOCALE_SNATIVECTRYNAME
LOCALE_SNATIVECTRYNAME 0x00000008  winnls.h


LOCALE_SNATIVEDIGITS
LOCALE_SNATIVEDIGITS 0x00000013  winnls.h


LOCALE_SNATIVELANGNAME
LOCALE_SNATIVELANGNAME 0x00000004  winnls.h


LOCALE_SNEGATIVESIGN
LOCALE_SNEGATIVESIGN 0x00000051  winnls.h


LOCALE_SPOSITIVESIGN
LOCALE_SPOSITIVESIGN 0x00000050  winnls.h


LOCALE_SSHORTDATE
LOCALE_SSHORTDATE 0x0000001F  winnls.h


LOCALE_STHOUSAND
LOCALE_STHOUSAND 0x0000000F  winnls.h


LOCKFILE_EXCLUSIVE_LOCK
LOCKFILE_EXCLUSIVE_LOCK 0x00000002  winbase.h


LOCKFILE_FAIL_IMMEDIATELY
LOCKFILE_FAIL_IMMEDIATELY 0x00000001  winbase.h


LPTR
LPTR (LMEM_FIXED | LMEM_ZEROINIT)  winbase.h


LPTx
LPTx 0x80  winbase.h


LZERROR_BADOUTHANDLE
LZERROR_BADOUTHANDLE (-2)  lzexpand.h


LZERROR_READ
LZERROR_READ (-3)  lzexpand.h


LZERROR_WRITE
LZERROR_WRITE (-4)  lzexpand.h


LZERROR_GLOBALLOC
LZERROR_GLOBALLOC (-5)  lzexpand.h


LZERROR_GLOBLOCK
LZERROR_GLOBLOCK (-6)  lzexpand.h


LZERROR_BADVALUE
LZERROR_BADVALUE (-7)  lzexpand.h


LZERROR_UNKNOWNALG
LZERROR_UNKNOWNALG (-8)  lzexpand.h


MAX_APPNAME
MAX_APPNAME 255  nddeapi.h


MAX_COMPUTERNAME_LENGTH
MAX_COMPUTERNAME_LENGTH 15  winbase.h


MAX_DEFAULTCHAR
MAX_DEFAULTCHAR 2  winnls.h


MAX_DOMAINNAME
MAX_DOMAINNAME 15  nddeapi.h


MAX_ITEMNAME
MAX_ITEMNAME 255  nddeapi.h


MAX_LANA
MAX_LANA 72  nb30.h


MAX_LEADBYTES
MAX_LEADBYTES 12  winnls.h


MAX_MONITORS
MAX_MONITORS 4  ddeml.h


MAX_NDDESHARENAME
MAX_NDDESHARENAME 256  nddeapi.h


MAX_PATH
MAX_PATH 260  windef.h


MAX_PRIORITY
MAX_PRIORITY 99  winspool.h


MAX_TOPICNAME
MAX_TOPICNAME 255  nddeapi.h


MAX_USERNAME
MAX_USERNAME 15  nddeapi.h


MAXBYTE
MAXBYTE 0xff  winnt.h


MAXCHAR
MAXCHAR 0x7f  winnt.h


MAXDWORD
MAXDWORD 0xffffffff  winnt.h


MAXERRORLENGTH
MAXERRORLENGTH 128  mmsystem.h


MAXFILELEN
MAXFILELEN 13  scrnsave.h


MAXGETHOSTSTRUCT
MAXGETHOSTSTRUCT 1024  winsock.h


MAXIMUM_ALLOWED
MAXIMUM_ALLOWED (0x02000000L)  winnt.h


MAXIMUM_SUSPEND_COUNT
MAXIMUM_SUSPEND_COUNT MAXCHAR  winnt.h


MAXIMUM_WAIT_OBJECTS
MAXIMUM_WAIT_OBJECTS 64  winnt.h


MAXINTATOM
MAXINTATOM 0xC000  winbase.h


MAXLONG
MAXLONG 0x7fffffff  winnt.h


MAXPNAMELEN
MAXPNAMELEN 32  mmsystem.h


MAXSHORT
MAXSHORT 0x7fff  winnt.h


MAXSTRETCHBLTMODE
MAXSTRETCHBLTMODE 4  wingdi.h


MAXWORD
MAXWORD 0xffff  winnt.h


MB_DEFMASK
MB_DEFMASK 0x00000F00L  winuser.h


MB_ICONMASK
MB_ICONMASK 0x000000F0L  winuser.h


MB_MISCMASK
MB_MISCMASK 0x0000C000L  winuser.h


MB_MODEMASK
MB_MODEMASK 0x00003000L  winuser.h


MB_NOFOCUS
MB_NOFOCUS 0x00008000L  winuser.h


MB_TYPEMASK
MB_TYPEMASK 0x0000000FL  winuser.h


MCI_DEVTYPE_ANIMATION
MCI_DEVTYPE_ANIMATION 519  mmsystem.h


MCI_DEVTYPE_CD_AUDIO
MCI_DEVTYPE_CD_AUDIO 516  mmsystem.h


MCI_DEVTYPE_DAT
MCI_DEVTYPE_DAT 517  mmsystem.h


MCI_DEVTYPE_DIGITAL_VIDEO
MCI_DEVTYPE_DIGITAL_VIDEO 520  mmsystem.h


MCI_DEVTYPE_FIRST
MCI_DEVTYPE_FIRST MCI_DEVTYPE_VCR  mmsystem.h


MCI_DEVTYPE_FIRST_USER
MCI_DEVTYPE_FIRST_USER 0x1000  mmsystem.h


MCI_DEVTYPE_LAST
MCI_DEVTYPE_LAST MCI_DEVTYPE_SEQUENCER  mmsystem.h


MCI_DEVTYPE_OTHER
MCI_DEVTYPE_OTHER 521  mmsystem.h


MCI_DEVTYPE_OVERLAY
MCI_DEVTYPE_OVERLAY 515  mmsystem.h


MCI_DEVTYPE_SCANNER
MCI_DEVTYPE_SCANNER 518  mmsystem.h


MCI_DEVTYPE_SEQUENCER
MCI_DEVTYPE_SEQUENCER 523  mmsystem.h


MCI_DEVTYPE_VCR
MCI_DEVTYPE_VCR 513  mmsystem.h


MCI_DEVTYPE_VIDEODISC
MCI_DEVTYPE_VIDEODISC 514  mmsystem.h


MCI_DEVTYPE_WAVEFORM_AUDIO
MCI_DEVTYPE_WAVEFORM_AUDIO 522  mmsystem.h


MCI_ESCAPE
MCI_ESCAPE 0x0805  mmsystem.h


MCI_FIRST
MCI_FIRST 0x0800  mmsystem.h


MCI_FREEZE
MCI_FREEZE 0x0844  mmsystem.h


MCI_LAST
MCI_LAST 0x0FFF  mmsystem.h


MCI_MODE_NOT_READY
MCI_MODE_NOT_READY (MCI_STRING_OFFSET + 12)  mmsystem.h


MCI_MODE_OPEN
MCI_MODE_OPEN (MCI_STRING_OFFSET + 18)  mmsystem.h


MCI_MODE_PAUSE
MCI_MODE_PAUSE (MCI_STRING_OFFSET + 17)  mmsystem.h


MCI_MODE_PLAY
MCI_MODE_PLAY (MCI_STRING_OFFSET + 14)  mmsystem.h


MCI_MODE_RECORD
MCI_MODE_RECORD (MCI_STRING_OFFSET + 15)  mmsystem.h


MCI_MODE_SEEK
MCI_MODE_SEEK (MCI_STRING_OFFSET + 16)  mmsystem.h


MCI_MODE_STOP
MCI_MODE_STOP (MCI_STRING_OFFSET + 13)  mmsystem.h


MCI_OVLY_STATUS_STRETCH
MCI_OVLY_STATUS_STRETCH 0x00004002L  mmsystem.h


MCI_OVLY_WINDOW_DEFAULT
MCI_OVLY_WINDOW_DEFAULT 0x00000000L  mmsystem.h


MCI_OVLY_WINDOW_DISABLE_STRETCH
MCI_OVLY_WINDOW_DISABLE_STRETCH 0x00200000L  mmsystem.h


MCI_OVLY_WINDOW_ENABLE_STRETCH
MCI_OVLY_WINDOW_ENABLE_STRETCH 0x00100000L  mmsystem.h


MCI_REALIZE
MCI_REALIZE 0x0840  mmsystem.h


MCI_SEQ_DIV_PPQN
MCI_SEQ_DIV_PPQN (0 + MCI_SEQ_OFFSET)  mmsystem.h


MCI_SEQ_DIV_SMPTE_24
MCI_SEQ_DIV_SMPTE_24 (1 + MCI_SEQ_OFFSET)  mmsystem.h


MCI_SEQ_DIV_SMPTE_25
MCI_SEQ_DIV_SMPTE_25 (2 + MCI_SEQ_OFFSET)  mmsystem.h


MCI_SEQ_DIV_SMPTE_30
MCI_SEQ_DIV_SMPTE_30 (4 + MCI_SEQ_OFFSET)  mmsystem.h


MCI_SEQ_DIV_SMPTE_30DROP
MCI_SEQ_DIV_SMPTE_30DROP (3 + MCI_SEQ_OFFSET)  mmsystem.h


MCI_SEQ_MAPPER
MCI_SEQ_MAPPER 65535  mmsystem.h


MCI_SEQ_OFFSET
MCI_SEQ_OFFSET 1216  mmsystem.h


MCI_SPIN
MCI_SPIN 0x080C  mmsystem.h


MCI_STRING_OFFSET
MCI_STRING_OFFSET 512  mmsystem.h


MCI_UPDATE
MCI_UPDATE 0x0854  mmsystem.h


MCI_USER_MESSAGES
MCI_USER_MESSAGES (0x400 + MCI_FIRST)  mmsystem.h


MCI_VD_ESCAPE_STRING
MCI_VD_ESCAPE_STRING 0x00000100L  mmsystem.h


MCI_VD_MEDIA_CAV
MCI_VD_MEDIA_CAV (MCI_VD_OFFSET + 3)  mmsystem.h


MCI_VD_MEDIA_CLV
MCI_VD_MEDIA_CLV (MCI_VD_OFFSET + 2)  mmsystem.h


MCI_VD_MEDIA_OTHER
MCI_VD_MEDIA_OTHER (MCI_VD_OFFSET + 4)  mmsystem.h


MCI_VD_MODE_PARK
MCI_VD_MODE_PARK (MCI_VD_OFFSET + 1)  mmsystem.h


MCI_VD_OFFSET
MCI_VD_OFFSET 1024  mmsystem.h


MCI_VD_SPIN_DOWN
MCI_VD_SPIN_DOWN 0x00020000L  mmsystem.h


MCI_VD_SPIN_UP
MCI_VD_SPIN_UP 0x00010000L  mmsystem.h


MCI_WAVE_MAPPER
MCI_WAVE_MAPPER (MCI_WAVE_OFFSET+1)  mmsystem.h


MCI_WAVE_OFFSET
MCI_WAVE_OFFSET 1152  mmsystem.h


MCI_WAVE_PCM
MCI_WAVE_PCM (MCI_WAVE_OFFSET+0)  mmsystem.h


MCIERR_BASE
MCIERR_BASE 256  mmsystem.h


MCIERR_CUSTOM_DRIVER_BASE
MCIERR_CUSTOM_DRIVER_BASE (MCIERR_BASE + 256)  mmsystem.h


MCIERR_DEVICE_LENGTH
MCIERR_DEVICE_LENGTH (MCIERR_BASE + 54)  mmsystem.h


MCIERR_DEVICE_NOT_INSTALLED
MCIERR_DEVICE_NOT_INSTALLED (MCIERR_BASE + 50)  mmsystem.h


MCIERR_DEVICE_ORD_LENGTH
MCIERR_DEVICE_ORD_LENGTH (MCIERR_BASE + 55)  mmsystem.h


MCIERR_EXTRA_CHARACTERS
MCIERR_EXTRA_CHARACTERS (MCIERR_BASE + 49)  mmsystem.h


MCIERR_GET_CD
MCIERR_GET_CD (MCIERR_BASE + 51)  mmsystem.h


MCIERR_ILLEGAL_FOR_AUTO_OPEN
MCIERR_ILLEGAL_FOR_AUTO_OPEN (MCIERR_BASE + 47)  mmsystem.h


MCIERR_NO_INTEGER
MCIERR_NO_INTEGER (MCIERR_BASE + 56)  mmsystem.h


MCIERR_NONAPPLICABLE_FUNCTION
MCIERR_NONAPPLICABLE_FUNCTION (MCIERR_BASE + 46)  mmsystem.h


MCIERR_SET_CD
MCIERR_SET_CD (MCIERR_BASE + 52)  mmsystem.h


MCIERR_SET_DRIVE
MCIERR_SET_DRIVE (MCIERR_BASE + 53)  mmsystem.h


MDIS_ALLCHILDSTYLES
MDIS_ALLCHILDSTYLES 0x0001  winuser.h


MENU_EVENT
MENU_EVENT 0x0008  wincon.h


MENU_TEXT_LEN
MENU_TEXT_LEN 40  wfext.h


META_ANIMATEPALETTE
META_ANIMATEPALETTE 0x0436  wingdi.h


META_ARC
META_ARC 0x0817  wingdi.h


META_BITBLT
META_BITBLT 0x0922  wingdi.h


META_CHORD
META_CHORD 0x0830  wingdi.h


META_CREATEBRUSHINDIRECT
META_CREATEBRUSHINDIRECT 0x02FC  wingdi.h


META_CREATEFONTINDIRECT
META_CREATEFONTINDIRECT 0x02FB  wingdi.h


META_CREATEPALETTE
META_CREATEPALETTE 0x00f7  wingdi.h


META_CREATEPATTERNBRUSH
META_CREATEPATTERNBRUSH 0x01F9  wingdi.h


META_CREATEPENINDIRECT
META_CREATEPENINDIRECT 0x02FA  wingdi.h


META_CREATEREGION
META_CREATEREGION 0x06FF  wingdi.h


META_DELETEOBJECT
META_DELETEOBJECT 0x01f0  wingdi.h


META_DIBBITBLT
META_DIBBITBLT 0x0940  wingdi.h


META_DIBCREATEPATTERNBRUSH
META_DIBCREATEPATTERNBRUSH 0x0142  wingdi.h


META_DIBSTRETCHBLT
META_DIBSTRETCHBLT 0x0b41  wingdi.h


META_ELLIPSE
META_ELLIPSE 0x0418  wingdi.h


META_ESCAPE
META_ESCAPE 0x0626  wingdi.h


META_EXCLUDECLIPRECT
META_EXCLUDECLIPRECT 0x0415  wingdi.h


META_EXTFLOODFILL
META_EXTFLOODFILL 0x0548  wingdi.h


META_EXTTEXTOUT
META_EXTTEXTOUT 0x0a32  wingdi.h


META_FILLREGION
META_FILLREGION 0x0228  wingdi.h


META_FLOODFILL
META_FLOODFILL 0x0419  wingdi.h


META_FRAMEREGION
META_FRAMEREGION 0x0429  wingdi.h


META_INTERSECTCLIPRECT
META_INTERSECTCLIPRECT 0x0416  wingdi.h


META_INVERTREGION
META_INVERTREGION 0x012A  wingdi.h


META_LINETO
META_LINETO 0x0213  wingdi.h


META_MOVETO
META_MOVETO 0x0214  wingdi.h


META_OFFSETCLIPRGN
META_OFFSETCLIPRGN 0x0220  wingdi.h


META_OFFSETVIEWPORTORG
META_OFFSETVIEWPORTORG 0x0211  wingdi.h


META_OFFSETWINDOWORG
META_OFFSETWINDOWORG 0x020F  wingdi.h


META_PAINTREGION
META_PAINTREGION 0x012B  wingdi.h


META_PATBLT
META_PATBLT 0x061D  wingdi.h


META_PIE
META_PIE 0x081A  wingdi.h


META_POLYGON
META_POLYGON 0x0324  wingdi.h


META_POLYLINE
META_POLYLINE 0x0325  wingdi.h


META_POLYPOLYGON
META_POLYPOLYGON 0x0538  wingdi.h


META_REALIZEPALETTE
META_REALIZEPALETTE 0x0035  wingdi.h


META_RECTANGLE
META_RECTANGLE 0x041B  wingdi.h


META_RESIZEPALETTE
META_RESIZEPALETTE 0x0139  wingdi.h


META_RESTOREDC
META_RESTOREDC 0x0127  wingdi.h


META_ROUNDRECT
META_ROUNDRECT 0x061C  wingdi.h


META_SAVEDC
META_SAVEDC 0x001E  wingdi.h


META_SCALEVIEWPORTEXT
META_SCALEVIEWPORTEXT 0x0412  wingdi.h


META_SCALEWINDOWEXT
META_SCALEWINDOWEXT 0x0410  wingdi.h


META_SELECTCLIPREGION
META_SELECTCLIPREGION 0x012C  wingdi.h


META_SELECTOBJECT
META_SELECTOBJECT 0x012D  wingdi.h


META_SELECTPALETTE
META_SELECTPALETTE 0x0234  wingdi.h


META_SETBKCOLOR
META_SETBKCOLOR 0x0201  wingdi.h


META_SETBKMODE
META_SETBKMODE 0x0102  wingdi.h


META_SETDIBTODEV
META_SETDIBTODEV 0x0d33  wingdi.h


META_SETMAPMODE
META_SETMAPMODE 0x0103  wingdi.h


META_SETMAPPERFLAGS
META_SETMAPPERFLAGS 0x0231  wingdi.h


META_SETPALENTRIES
META_SETPALENTRIES 0x0037  wingdi.h


META_SETPIXEL
META_SETPIXEL 0x041F  wingdi.h


META_SETPOLYFILLMODE
META_SETPOLYFILLMODE 0x0106  wingdi.h


META_SETRELABS
META_SETRELABS 0x0105  wingdi.h


META_SETROP2
META_SETROP2 0x0104  wingdi.h


META_SETSTRETCHBLTMODE
META_SETSTRETCHBLTMODE 0x0107  wingdi.h


META_SETTEXTALIGN
META_SETTEXTALIGN 0x012E  wingdi.h


META_SETTEXTCHAREXTRA
META_SETTEXTCHAREXTRA 0x0108  wingdi.h


META_SETTEXTCOLOR
META_SETTEXTCOLOR 0x0209  wingdi.h


META_SETTEXTJUSTIFICATION
META_SETTEXTJUSTIFICATION 0x020A  wingdi.h


META_SETVIEWPORTEXT
META_SETVIEWPORTEXT 0x020E  wingdi.h


META_SETVIEWPORTORG
META_SETVIEWPORTORG 0x020D  wingdi.h


META_SETWINDOWEXT
META_SETWINDOWEXT 0x020C  wingdi.h


META_SETWINDOWORG
META_SETWINDOWORG 0x020B  wingdi.h


META_STRETCHBLT
META_STRETCHBLT 0x0B23  wingdi.h


META_STRETCHDIB
META_STRETCHDIB 0x0f43  wingdi.h


META_TEXTOUT
META_TEXTOUT 0x0521  wingdi.h


METHOD_BUFFERED
METHOD_BUFFERED 0  winioctl.h


METHOD_IN_DIRECT
METHOD_IN_DIRECT 1  winioctl.h


METHOD_NEITHER
METHOD_NEITHER 3  winioctl.h


METHOD_OUT_DIRECT
METHOD_OUT_DIRECT 2  winioctl.h


MF_APPEND
MF_APPEND 0x00000100L  winuser.h


MF_CHANGE
MF_CHANGE 0x00000080L  winuser.h


MF_DELETE
MF_DELETE 0x00000200L  winuser.h


MF_END
MF_END 0x00000080L  winuser.h


MF_INSERT
MF_INSERT 0x00000000L  winuser.h


MF_MASK
MF_MASK 0xFF000000  ddeml.h


MF_REMOVE
MF_REMOVE 0x00001000L  winuser.h


MF_USECHECKBITMAPS
MF_USECHECKBITMAPS 0x00000200L  winuser.h


MFCOMMENT
MFCOMMENT 15  wingdi.h


MHDR_INQUEUE
MHDR_INQUEUE 0x00000004  mmsystem.h


MIDIERR_BASE
MIDIERR_BASE 64  mmsystem.h


MIDIERR_INVALIDSETUP
MIDIERR_INVALIDSETUP (MIDIERR_BASE + 5)  mmsystem.h


MIDIERR_LASTERROR
MIDIERR_LASTERROR (MIDIERR_BASE + 5)  mmsystem.h


MIDIMAPPER
MIDIMAPPER (-1)  mmsystem.h


MIDIPATCHSIZE
MIDIPATCHSIZE 128  mmsystem.h


MINCHAR
MINCHAR 0x80  winnt.h


MINLONG
MINLONG 0x80000000  winnt.h


MINSHORT
MINSHORT 0x8000  winnt.h


MM_ADLIB
MM_ADLIB 9  mmsystem.h


MM_MAX
MM_MAX MM_ANISOTROPIC  wingdi.h


MM_MAX_FIXEDSCALE
MM_MAX_FIXEDSCALE MM_TWIPS  wingdi.h


MM_MCISYSTEM_STRING
MM_MCISYSTEM_STRING 0x3CA  mmsystem.h


MM_MICROSOFT
MM_MICROSOFT 1  mmsystem.h


MM_MIDI_MAPPER
MM_MIDI_MAPPER 1  mmsystem.h


MM_MIN
MM_MIN MM_TEXT  wingdi.h


MM_MPU401_MIDIIN
MM_MPU401_MIDIIN 11  mmsystem.h


MM_MPU401_MIDIOUT
MM_MPU401_MIDIOUT 10  mmsystem.h


MM_PC_JOYSTICK
MM_PC_JOYSTICK 12  mmsystem.h


MM_SNDBLST_MIDIIN
MM_SNDBLST_MIDIIN 4  mmsystem.h


MM_SNDBLST_MIDIOUT
MM_SNDBLST_MIDIOUT 3  mmsystem.h


MM_SNDBLST_SYNTH
MM_SNDBLST_SYNTH 5  mmsystem.h


MM_SNDBLST_WAVEIN
MM_SNDBLST_WAVEIN 7  mmsystem.h


MM_SNDBLST_WAVEOUT
MM_SNDBLST_WAVEOUT 6  mmsystem.h


MM_WAVE_MAPPER
MM_WAVE_MAPPER 2  mmsystem.h


MMIO_DEFAULTBUFFER
MMIO_DEFAULTBUFFER 8192  mmsystem.h


MMIO_DIRTY
MMIO_DIRTY 0x10000000  mmsystem.h


MMIO_EMPTYBUF
MMIO_EMPTYBUF 0x0010  mmsystem.h


MMIO_RWMODE
MMIO_RWMODE 0x00000003  mmsystem.h


MMIO_SHAREMODE
MMIO_SHAREMODE 0x00000070  mmsystem.h


MMIO_UNICODEPROC
MMIO_UNICODEPROC 0x01000000  mmsystem.h


MMIOERR_BASE
MMIOERR_BASE 256  mmsystem.h


MMIOERR_CANNOTOPEN
MMIOERR_CANNOTOPEN (MMIOERR_BASE + 3)  mmsystem.h


MMIOERR_CHUNKNOTFOUND
MMIOERR_CHUNKNOTFOUND (MMIOERR_BASE + 9)  mmsystem.h


MMIOERR_FILENOTFOUND
MMIOERR_FILENOTFOUND (MMIOERR_BASE + 1)  mmsystem.h


MMSYSERR_BASE
MMSYSERR_BASE 0  mmsystem.h


MMSYSERR_ERROR
MMSYSERR_ERROR (MMSYSERR_BASE + 1)  mmsystem.h


MMSYSERR_INVALFLAG
MMSYSERR_INVALFLAG (MMSYSERR_BASE + 10)  mmsystem.h


MMSYSERR_INVALIDALIAS
MMSYSERR_INVALIDALIAS (MMSYSERR_BASE + 13)  mmsystem.h


MMSYSERR_INVALPARAM
MMSYSERR_INVALPARAM (MMSYSERR_BASE + 11)  mmsystem.h


MMSYSERR_LASTERROR
MMSYSERR_LASTERROR (MMSYSERR_BASE + 13)  mmsystem.h


MMSYSERR_NOERROR
MMSYSERR_NOERROR 0  mmsystem.h


MMSYSERR_NOTENABLED
MMSYSERR_NOTENABLED (MMSYSERR_BASE + 3)  mmsystem.h


MOD_SYNTH
MOD_SYNTH 2  mmsystem.h


MOUSE_EVENT
MOUSE_EVENT 0x0002  wincon.h


MOUSETRAILS
MOUSETRAILS 39  wingdi.h


MS_NBF
MS_NBF "MNBF"  nb30.h


MSG_DONTROUTE
MSG_DONTROUTE 0x4  winsock.h


MSG_MAXIOVLEN
MSG_MAXIOVLEN 16  winsock.h


MSG_OOB
MSG_OOB 0x1  winsock.h


MSG_PEEK
MSG_PEEK 0x2  winsock.h


MSGF_MAINLOOP
MSGF_MAINLOOP 8  winuser.h


MSGF_MAX
MSGF_MAX 8  winuser.h


MSGF_MOVE
MSGF_MOVE 3  winuser.h


MSGF_SIZE
MSGF_SIZE 4  winuser.h


MSGF_USER
MSGF_USER 4096  winuser.h


MULTIFILEOPENORD
MULTIFILEOPENORD 1537  dlgs.h


MUTANT_ALL_ACCESS
MUTANT_ALL_ACCESS (STANDARD_RIGHTS_REQUIRED|SYNCHRONIZE|MUTANT_QUERY_STATE)  winnt.h


MUTANT_QUERY_STATE
MUTANT_QUERY_STATE 0x0001  winnt.h


MUTEX_ALL_ACCESS
MUTEX_ALL_ACCESS MUTANT_ALL_ACCESS  winbase.h


MUTEX_MODIFY_STATE
MUTEX_MODIFY_STATE MUTANT_QUERY_STATE  winbase.h


MWT_MAX
MWT_MAX MWT_RIGHTMULTIPLY  wingdi.h


MWT_MIN
MWT_MIN MWT_IDENTITY  wingdi.h


N_BTMASK
N_BTMASK 017  winnt.h


N_BTSHFT
N_BTSHFT 4  winnt.h


N_TMASK
N_TMASK 060  winnt.h


N_TMASK1
N_TMASK1 0300  winnt.h


N_TMASK2
N_TMASK2 0360  winnt.h


N_TSHIFT
N_TSHIFT 2  winnt.h


NAME_FLAGS_MASK
NAME_FLAGS_MASK 0x87  nb30.h


NCB_POST
NCB_POST void CALLBACK  nb30.h


NCBACTION
NCBACTION 0x77  nb30.h


NCBNAMSZ
NCBNAMSZ 16  nb30.h


NDDE_ACCESS_DENIED
NDDE_ACCESS_DENIED 1  nddeapi.h


NDDE_BUF_TOO_SMALL
NDDE_BUF_TOO_SMALL 2  nddeapi.h


NDDE_CANT_ACCESS_SERVER
NDDE_CANT_ACCESS_SERVER 24  nddeapi.h


NDDE_CMD_SHOW_MASK
NDDE_CMD_SHOW_MASK 0x0000FFFFL  nddeapi.h


NDDE_ERROR_MORE_DATA
NDDE_ERROR_MORE_DATA 3  nddeapi.h


NDDE_GUI_CHANGE
NDDE_GUI_CHANGE (NDDE_SHARE_GENERIC_READ | NDDE_SHARE_GENERIC_WRITE | NDDE_SHARE_GENERIC_EXECUTE)  nddesec.h


NDDE_GUI_FULL_CONTROL
NDDE_GUI_FULL_CONTROL (NDDE_SHARE_GENERIC_ALL)  nddesec.h


NDDE_GUI_NONE
NDDE_GUI_NONE (0)  nddesec.h


NDDE_GUI_READ
NDDE_GUI_READ (NDDE_SHARE_GENERIC_READ)  nddesec.h


NDDE_GUI_READ_LINK
NDDE_GUI_READ_LINK (NDDE_SHARE_GENERIC_READ | NDDE_SHARE_INITIATE_LINK)  nddesec.h


NDDE_INTERNAL_ERROR
NDDE_INTERNAL_ERROR 11  nddeapi.h


NDDE_INVALID_APPNAME
NDDE_INVALID_APPNAME 13  nddeapi.h


NDDE_INVALID_FILENAME
NDDE_INVALID_FILENAME 17  nddeapi.h


NDDE_INVALID_ITEM_LIST
NDDE_INVALID_ITEM_LIST 21  nddeapi.h


NDDE_INVALID_ITEMNAME
NDDE_INVALID_ITEMNAME 9  nddeapi.h


NDDE_INVALID_LEVEL
NDDE_INVALID_LEVEL 7  nddeapi.h


NDDE_INVALID_PARAMETER
NDDE_INVALID_PARAMETER 6  nddeapi.h


NDDE_INVALID_PASSWORD
NDDE_INVALID_PASSWORD 8  nddeapi.h


NDDE_INVALID_SECURITY_DESC
NDDE_INVALID_SECURITY_DESC 26  nddeapi.h


NDDE_INVALID_SERVER
NDDE_INVALID_SERVER 4  nddeapi.h


NDDE_INVALID_SESSION
NDDE_INVALID_SESSION 20  nddeapi.h


NDDE_INVALID_SHARE
NDDE_INVALID_SHARE 5  nddeapi.h


NDDE_INVALID_SPECIAL_COMMAND
NDDE_INVALID_SPECIAL_COMMAND 25  nddeapi.h


NDDE_INVALID_TOPIC
NDDE_INVALID_TOPIC 10  nddeapi.h


NDDE_INVALID_WINDOW
NDDE_INVALID_WINDOW 19  nddeapi.h


NDDE_ITEM_ADVISE
NDDE_ITEM_ADVISE (0x00000002)  nddesec.h


NDDE_ITEM_GENERIC_ALL
NDDE_ITEM_GENERIC_ALL (NDDE_ITEM_REQUEST | NDDE_ITEM_ADVISE | NDDE_ITEM_POKE | DELETE | READ_CONTROL | WRITE_DAC | WRITE_OWNER)  nddesec.h


NDDE_ITEM_GENERIC_EXECUTE
NDDE_ITEM_GENERIC_EXECUTE (0)  nddesec.h


NDDE_ITEM_GENERIC_READ
NDDE_ITEM_GENERIC_READ (NDDE_ITEM_REQUEST | NDDE_ITEM_ADVISE)  nddesec.h


NDDE_ITEM_GENERIC_WRITE
NDDE_ITEM_GENERIC_WRITE (NDDE_ITEM_POKE)  nddesec.h


NDDE_ITEM_POKE
NDDE_ITEM_POKE (0x00000004)  nddesec.h


NDDE_ITEM_REQUEST
NDDE_ITEM_REQUEST (0x00000001)  nddesec.h


NDDE_NO_ERROR
NDDE_NO_ERROR 0  nddeapi.h


NDDE_NOT_IMPLEMENTED
NDDE_NOT_IMPLEMENTED 14  nddeapi.h


NDDE_NOT_RUNNING
NDDE_NOT_RUNNING 18  nddeapi.h


NDDE_OUT_OF_MEMORY
NDDE_OUT_OF_MEMORY 12  nddeapi.h


NDDE_REGISTRY_ERROR
NDDE_REGISTRY_ERROR 23  nddeapi.h


NDDE_SHARE_ADD_ITEMS
NDDE_SHARE_ADD_ITEMS (0x00000100)  nddesec.h


NDDE_SHARE_ADVISE
NDDE_SHARE_ADVISE (0x00000020)  nddesec.h


NDDE_SHARE_ALREADY_EXIST
NDDE_SHARE_ALREADY_EXIST 15  nddeapi.h


NDDE_SHARE_DATA_CORRUPTED
NDDE_SHARE_DATA_CORRUPTED 22  nddeapi.h


NDDE_SHARE_EXECUTE
NDDE_SHARE_EXECUTE (0x00000080)  nddesec.h


NDDE_SHARE_GENERIC_EXECUTE
NDDE_SHARE_GENERIC_EXECUTE (NDDE_SHARE_INITIATE_STATIC | NDDE_SHARE_INITIATE_LINK | NDDE_SHARE_EXECUTE)  nddesec.h


NDDE_SHARE_GENERIC_READ
NDDE_SHARE_GENERIC_READ (NDDE_SHARE_READ | NDDE_SHARE_INITIATE_STATIC | NDDE_SHARE_REQUEST | NDDE_SHARE_ADVISE | NDDE_SHARE_LIST_ITEMS) nddesec.h


NDDE_SHARE_GENERIC_WRITE
NDDE_SHARE_GENERIC_WRITE (NDDE_SHARE_INITIATE_STATIC | NDDE_SHARE_INITIATE_LINK | NDDE_SHARE_POKE | DELETE)  nddesec.h


NDDE_SHARE_INITIATE_LINK
NDDE_SHARE_INITIATE_LINK (0x00000008)  nddesec.h


NDDE_SHARE_INITIATE_STATIC
NDDE_SHARE_INITIATE_STATIC (0x00000004)  nddesec.h


NDDE_SHARE_LIST_ITEMS
NDDE_SHARE_LIST_ITEMS (0x00000200)  nddesec.h


NDDE_SHARE_NOT_EXIST
NDDE_SHARE_NOT_EXIST 16  nddeapi.h


NDDE_SHARE_POKE
NDDE_SHARE_POKE (0x00000040)  nddesec.h


NDDE_SHARE_READ
NDDE_SHARE_READ (0x00000001)  nddesec.h


NDDE_SHARE_REQUEST
NDDE_SHARE_REQUEST (0x00000010)  nddesec.h


NDDE_SHARE_WRITE
NDDE_SHARE_WRITE (0x00000002)  nddesec.h


NDDE_SHAREDB_ADD
NDDE_SHAREDB_ADD (0x00000001)  nddesec.h


NDDE_SHAREDB_ADMIN
NDDE_SHAREDB_ADMIN (NDDE_SHAREDB_ADD | NDDE_SHAREDB_DELETE | NDDE_SHAREDB_LIST | READ_CONTROL | WRITE_DAC | WRITE_OWNER)  nddesec.h


NDDE_SHAREDB_DELETE
NDDE_SHAREDB_DELETE (0x00000002)  nddesec.h


NDDE_SHAREDB_EVERYONE
NDDE_SHAREDB_EVERYONE (NDDE_SHAREDB_LIST)  nddesec.h


NDDE_SHAREDB_LIST
NDDE_SHAREDB_LIST (0x00000004)  nddesec.h


NDDE_SHAREDB_OPER
NDDE_SHAREDB_OPER (NDDE_SHAREDB_ADD | NDDE_SHAREDB_DELETE | NDDE_SHAREDB_LIST)  nddesec.h


NDDE_SHAREDB_POWER
NDDE_SHAREDB_POWER (NDDE_SHAREDB_ADD | NDDE_SHAREDB_DELETE | NDDE_SHAREDB_LIST)  nddesec.h


NDDE_SHAREDB_USER
NDDE_SHAREDB_USER (NDDE_SHAREDB_ADD | NDDE_SHAREDB_DELETE | NDDE_SHAREDB_LIST)  nddesec.h


NDDE_TRUST_CMD_SHOW
NDDE_TRUST_CMD_SHOW 0x10000000L   nddeapi.h


NDDE_TRUST_SHARE_DEL
NDDE_TRUST_SHARE_DEL 0x20000000L   nddeapi.h


NDDE_TRUST_SHARE_FAIL
NDDE_TRUST_SHARE_FAIL 27   nddeapi.h


NDDE_TRUST_SHARE_INIT
NDDE_TRUST_SHARE_INIT 0x40000000L   nddeapi.h


NDDE_TRUST_SHARE_START
NDDE_TRUST_SHARE_START 0x80000000L   nddeapi.h


NDDEF_NOCACHELOOKUP
NDDEF_NOCACHELOOKUP 0x0002  nddeapi.h


NDDEF_NOPASSWORDPROMPT
NDDEF_NOPASSWORDPROMPT 0x0001  nddeapi.h


NDDEF_STRIP_NDDE
NDDEF_STRIP_NDDE 0x0004  nddeapi.h


NDR_ASCII_CHAR
NDR_ASCII_CHAR (unsigned long)0X00000000L  rpcndr.h


NDR_BIG_ENDIAN
NDR_BIG_ENDIAN (unsigned long)0X00000000L  rpcndr.h


NDR_CHAR_REP_MASK
NDR_CHAR_REP_MASK (unsigned long)0X0000000FL  rpcndr.h


NDR_EBCDIC_CHAR
NDR_EBCDIC_CHAR (unsigned long)0X00000001L  rpcndr.h


NDR_FLOAT_REP_MASK
NDR_FLOAT_REP_MASK (unsigned long)0X0000FF00L  rpcndr.h


NDR_IEEE_FLOAT
NDR_IEEE_FLOAT (unsigned long)0X00000000L  rpcndr.h


NDR_INT_REP_MASK
NDR_INT_REP_MASK (unsigned long)0X000000F0L  rpcndr.h


NDR_LITTLE_ENDIAN
NDR_LITTLE_ENDIAN (unsigned long)0X00000010L  rpcndr.h


NDR_LOCAL_DATA_REPRESENTATION
NDR_LOCAL_DATA_REPRESENTATION (unsigned long)0X00000010L  rpcndr.h


NDR_VAX_FLOAT
NDR_VAX_FLOAT (unsigned long)0X00000100L  rpcndr.h


NEWFRAME
NEWFRAME 1  wingdi.h


NEWTRANSPARENT
NEWTRANSPARENT 3  mmsystem.h


NEXTBAND
NEXTBAND 3  wingdi.h


NLS_VALID_LOCALE_MASK
NLS_VALID_LOCALE_MASK 0x000fffff  winnt.h


NO_ADDRESS
NO_ADDRESS WSANO_ADDRESS  winsock.h


NO_DATA
NO_DATA WSANO_DATA  winsock.h


NO_ERROR
NO_ERROR 0L  winerror.h


NO_PRIORITY
NO_PRIORITY 0  winspool.h


NO_RECOVERY
NO_RECOVERY WSANO_RECOVERY  winsock.h


NONZEROLHND
NONZEROLHND (LMEM_MOVEABLE)  winbase.h


NONZEROLPTR
NONZEROLPTR (LMEM_FIXED)  winbase.h


NORMAL_PRIORITY_CLASS
NORMAL_PRIORITY_CLASS 0x00000020  winbase.h


NTM_BOLD
NTM_BOLD 0x00000020L  wingdi.h


NTM_ITALIC
NTM_ITALIC 0x00000001L  wingdi.h


NTM_REGULAR
NTM_REGULAR 0x00000040L  wingdi.h


NUMMARKERS
NUMMARKERS 20  wingdi.h


OBM_BTNCORNERS
OBM_BTNCORNERS 32758  winuser.h


OBM_BTSIZE
OBM_BTSIZE 32761  winuser.h


OBM_CHECK
OBM_CHECK 32760  winuser.h


OBM_CHECKBOXES
OBM_CHECKBOXES 32759  winuser.h


OBM_CLOSE
OBM_CLOSE 32754  winuser.h


OBM_COMBO
OBM_COMBO 32738  winuser.h


OBM_DNARROW
OBM_DNARROW 32752  winuser.h


OBM_DNARROWD
OBM_DNARROWD 32742  winuser.h


OBM_DNARROWI
OBM_DNARROWI 32736  winuser.h


OBM_LFARROW
OBM_LFARROW 32750  winuser.h


OBM_LFARROWD
OBM_LFARROWD 32740  winuser.h


OBM_LFARROWI
OBM_LFARROWI 32734  winuser.h


OBM_MNARROW
OBM_MNARROW 32739  winuser.h


OBM_OLD_CLOSE
OBM_OLD_CLOSE 32767  winuser.h


OBM_OLD_DNARROW
OBM_OLD_DNARROW 32764  winuser.h


OBM_OLD_LFARROW
OBM_OLD_LFARROW 32762  winuser.h


OBM_OLD_REDUCE
OBM_OLD_REDUCE 32757  winuser.h


OBM_OLD_RESTORE
OBM_OLD_RESTORE 32755  winuser.h


OBM_OLD_RGARROW
OBM_OLD_RGARROW 32763  winuser.h


OBM_OLD_UPARROW
OBM_OLD_UPARROW 32765  winuser.h


OBM_OLD_ZOOM
OBM_OLD_ZOOM 32756  winuser.h


OBM_REDUCE
OBM_REDUCE 32749  winuser.h


OBM_REDUCED
OBM_REDUCED 32746  winuser.h


OBM_RESTORE
OBM_RESTORE 32747  winuser.h


OBM_RESTORED
OBM_RESTORED 32744  winuser.h


OBM_RGARROW
OBM_RGARROW 32751  winuser.h


OBM_RGARROWD
OBM_RGARROWD 32741  winuser.h


OBM_RGARROWI
OBM_RGARROWI 32735  winuser.h


OBM_SIZE
OBM_SIZE 32766  winuser.h


OBM_UPARROW
OBM_UPARROW 32753  winuser.h


OBM_UPARROWD
OBM_UPARROWD 32743  winuser.h


OBM_UPARROWI
OBM_UPARROWI 32737  winuser.h


OBM_ZOOM
OBM_ZOOM 32748  winuser.h


OBM_ZOOMD
OBM_ZOOMD 32745  winuser.h


OCR_CROSS
OCR_CROSS 32515  winuser.h


OCR_IBEAM
OCR_IBEAM 32513  winuser.h


OCR_ICOCUR
OCR_ICOCUR 32647  winuser.h


OCR_ICON
OCR_ICON 32641  winuser.h


OCR_NO
OCR_NO 32648  winuser.h


OCR_NORMAL
OCR_NORMAL 32512  winuser.h


OCR_SIZE
OCR_SIZE 32640  winuser.h


OCR_SIZEALL
OCR_SIZEALL 32646  winuser.h


OCR_SIZENESW
OCR_SIZENESW 32643  winuser.h


OCR_SIZENS
OCR_SIZENS 32645  winuser.h


OCR_SIZENWSE
OCR_SIZENWSE 32642  winuser.h


OCR_SIZEWE
OCR_SIZEWE 32644  winuser.h


OCR_UP
OCR_UP 32516  winuser.h


OCR_WAIT
OCR_WAIT 32514  winuser.h


OEM_CHARSET
OEM_CHARSET 255  wingdi.h


OF_GET
OF_GET 0x0002  ole.h


OF_HANDLER
OF_HANDLER 0x0004  ole.h


OF_SET
OF_SET 0x0001  ole.h


OFN_NOLONGNAMES
OFN_NOLONGNAMES 0x00040000  commdlg.h


OFS_MAXPATHNAME
OFS_MAXPATHNAME 128  winbase.h


OIC_BANG
OIC_BANG 32515  winuser.h


OIC_HAND
OIC_HAND 32513  winuser.h


OIC_NOTE
OIC_NOTE 32516  winuser.h


OIC_QUES
OIC_QUES 32514  winuser.h


OIC_SAMPLE
OIC_SAMPLE 32512  winuser.h


OLE_CONST
OLE_CONST const  ole.h


OLE_CONST
OLE_CONST nothing  ole.h


OLE_LPCSTR
OLE_LPCSTR LPCSTR  ole.h


OLE_LPCSTR
OLE_LPCSTR LPSTR  ole.h


OLEVERB_PRIMARY
OLEVERB_PRIMARY 0  ole.h


OPENCHANNEL
OPENCHANNEL 4110  wingdi.h


ORD_LANGDRIVER
ORD_LANGDRIVER 1  winuser.h


OT_EMBEDDED
OT_EMBEDDED 2L  ole.h


OT_LINK
OT_LINK 1L  ole.h


OT_STATIC
OT_STATIC 3L  ole.h


OUT_CHARACTER_PRECIS
OUT_CHARACTER_PRECIS 2  wingdi.h


OUT_DEFAULT_PRECIS
OUT_DEFAULT_PRECIS 0  wingdi.h


OUT_DEVICE_PRECIS
OUT_DEVICE_PRECIS 5  wingdi.h


OUT_OUTLINE_PRECIS
OUT_OUTLINE_PRECIS 8  wingdi.h


OUT_RASTER_PRECIS
OUT_RASTER_PRECIS 6  wingdi.h


OUT_STRING_PRECIS
OUT_STRING_PRECIS 1  wingdi.h


OUT_STROKE_PRECIS
OUT_STROKE_PRECIS 3  wingdi.h


OUT_TT_ONLY_PRECIS
OUT_TT_ONLY_PRECIS 7  wingdi.h


OUT_TT_PRECIS
OUT_TT_PRECIS 4  wingdi.h


PAN_ARMSTYLE_INDEX
PAN_ARMSTYLE_INDEX 6  wingdi.h


PAN_CONTRAST_INDEX
PAN_CONTRAST_INDEX 4  wingdi.h


PAN_FAMILYTYPE_INDEX
PAN_FAMILYTYPE_INDEX 0  wingdi.h


PAN_LETTERFORM_INDEX
PAN_LETTERFORM_INDEX 7  wingdi.h


PAN_MIDLINE_INDEX
PAN_MIDLINE_INDEX 8  wingdi.h


PAN_PROPORTION_INDEX
PAN_PROPORTION_INDEX 3  wingdi.h


PAN_SERIFSTYLE_INDEX
PAN_SERIFSTYLE_INDEX 1  wingdi.h


PAN_STROKEVARIATION_INDEX
PAN_STROKEVARIATION_INDEX 5  wingdi.h


PAN_WEIGHT_INDEX
PAN_WEIGHT_INDEX 2  wingdi.h


PAN_XHEIGHT_INDEX
PAN_XHEIGHT_INDEX 9  wingdi.h


PANOSE_COUNT
PANOSE_COUNT 10  wingdi.h


PARTITION_ENTRY_UNUSED
PARTITION_ENTRY_UNUSED 0x00  winioctl.h


PARTITION_EXTENDED
PARTITION_EXTENDED 0x05  winioctl.h


PARTITION_FAT_12
PARTITION_FAT_12 0x01  winioctl.h


PARTITION_FAT_16
PARTITION_FAT_16 0x04  winioctl.h


PARTITION_HUGE
PARTITION_HUGE 0x06  winioctl.h


PARTITION_IFS
PARTITION_IFS 0x07  winioctl.h


PARTITION_NTFT
PARTITION_NTFT 0x80  winioctl.h


PARTITION_UNIX
PARTITION_UNIX 0x63  winioctl.h


PARTITION_XENIX_1
PARTITION_XENIX_1 0x02  winioctl.h


PARTITION_XENIX_2
PARTITION_XENIX_2 0x03  winioctl.h


PASSTHROUGH
PASSTHROUGH 19  wingdi.h


PC_INTERIORS
PC_INTERIORS 128  wingdi.h


PC_NONE
PC_NONE 0  wingdi.h


PC_POLYGON
PC_POLYGON 1  wingdi.h


PC_RECTANGLE
PC_RECTANGLE 2  wingdi.h


PC_SCANLINE
PC_SCANLINE 8  wingdi.h


PC_STYLED
PC_STYLED 32  wingdi.h


PC_TRAPEZOID
PC_TRAPEZOID 4  wingdi.h


PC_WIDE
PC_WIDE 16  wingdi.h


PC_WIDESTYLED
PC_WIDESTYLED 64  wingdi.h


PC_WINDPOLYGON
PC_WINDPOLYGON 4  wingdi.h


PD_NONETWORKBUTTON
PD_NONETWORKBUTTON 0x00200000  commdlg.h


PDERR_PRINTERCODES
PDERR_PRINTERCODES 0x1000  cderr.h


PENDING
PENDING (RASBASE+0)  raserror.h


PERF_COUNTER_BASE
PERF_COUNTER_BASE 0x00030000  winperf.h


PERF_COUNTER_ELAPSED
PERF_COUNTER_ELAPSED 0x00040000  winperf.h


PERF_COUNTER_FRACTION
PERF_COUNTER_FRACTION 0x00020000  winperf.h


PERF_COUNTER_HISTOGRAM_TYPE
PERF_COUNTER_HISTOGRAM_TYPE 0x80000000  winperf.h


PERF_COUNTER_QUEUELEN_TYPE
PERF_COUNTER_QUEUELEN_TYPE (PERF_SIZE_DWORD | PERF_TYPE_COUNTER | PERF_COUNTER_QUEUELEN | PERF_TIMER_TICK | PERF_DELTA_COUNTER | PERF_DISPLAY_NO_SUFFIX)  winperf.h


PERF_COUNTER_RATE
PERF_COUNTER_RATE 0x00010000  winperf.h


PERF_COUNTER_VALUE
PERF_COUNTER_VALUE 0x00000000  winperf.h


PERF_DATA_REVISION
PERF_DATA_REVISION 1  winperf.h


PERF_DATA_VERSION
PERF_DATA_VERSION 1  winperf.h


PERF_DELTA_BASE
PERF_DELTA_BASE 0x00800000  winperf.h


PERF_DELTA_COUNTER
PERF_DELTA_COUNTER 0x00400000  winperf.h


PERF_DISPLAY_NO_SUFFIX
PERF_DISPLAY_NO_SUFFIX 0x00000000  winperf.h


PERF_DISPLAY_NOSHOW
PERF_DISPLAY_NOSHOW 0x40000000  winperf.h


PERF_DISPLAY_PER_SEC
PERF_DISPLAY_PER_SEC 0x10000000  winperf.h


PERF_DISPLAY_PERCENT
PERF_DISPLAY_PERCENT 0x20000000  winperf.h


PERF_DISPLAY_SECONDS
PERF_DISPLAY_SECONDS 0x30000000  winperf.h


PERF_ELAPSED_TIME
PERF_ELAPSED_TIME (PERF_SIZE_LARGE | PERF_TYPE_COUNTER | PERF_COUNTER_ELAPSED | PERF_OBJECT_TIMER | PERF_DISPLAY_SECONDS)  winperf.h


PERF_INVERSE_COUNTER
PERF_INVERSE_COUNTER 0x01000000  winperf.h


PERF_MULTI_COUNTER
PERF_MULTI_COUNTER 0x02000000  winperf.h


PERF_NO_INSTANCES
PERF_NO_INSTANCES -1  winperf.h


PERF_NO_UNIQUE_ID
PERF_NO_UNIQUE_ID -1  winperf.h


PERF_NUMBER_DEC_1000
PERF_NUMBER_DEC_1000 0x00020000  winperf.h


PERF_NUMBER_DECIMAL
PERF_NUMBER_DECIMAL 0x00010000  winperf.h


PERF_NUMBER_HEX
PERF_NUMBER_HEX 0x00000000  winperf.h


PERF_OBJECT_TIMER
PERF_OBJECT_TIMER 0x00200000  winperf.h


PERF_SIZE_DWORD
PERF_SIZE_DWORD 0x00000000  winperf.h


PERF_SIZE_LARGE
PERF_SIZE_LARGE 0x00000100  winperf.h


PERF_SIZE_VARIABLE_LEN
PERF_SIZE_VARIABLE_LEN 0x00000300  winperf.h


PERF_SIZE_ZERO
PERF_SIZE_ZERO 0x00000200  winperf.h


PERF_TEXT_ASCII
PERF_TEXT_ASCII 0x00010000  winperf.h


PERF_TEXT_UNICODE
PERF_TEXT_UNICODE 0x00000000  winperf.h


PERF_TIMER_100NS
PERF_TIMER_100NS 0x00100000  winperf.h


PERF_TIMER_TICK
PERF_TIMER_TICK 0x00000000  winperf.h


PERF_TYPE_COUNTER
PERF_TYPE_COUNTER 0x00000400  winperf.h


PERF_TYPE_NUMBER
PERF_TYPE_NUMBER 0x00000000  winperf.h


PERF_TYPE_TEXT
PERF_TYPE_TEXT 0x00000800  winperf.h


PERF_TYPE_ZERO
PERF_TYPE_ZERO 0x00000C00  winperf.h


PF_APPLETALK
PF_APPLETALK AF_APPLETALK  winsock.h


PF_CCITT
PF_CCITT AF_CCITT  winsock.h


PF_CHAOS
PF_CHAOS AF_CHAOS  winsock.h


PF_DATAKIT
PF_DATAKIT AF_DATAKIT  winsock.h


PF_DECnet
PF_DECnet AF_DECnet  winsock.h


PF_DLI
PF_DLI AF_DLI  winsock.h


PF_ECMA
PF_ECMA AF_ECMA  winsock.h


PF_HYLINK
PF_HYLINK AF_HYLINK  winsock.h


PF_IMPLINK
PF_IMPLINK AF_IMPLINK  winsock.h


PF_INET
PF_INET AF_INET  winsock.h


PF_IPX
PF_IPX AF_IPX  winsock.h


PF_ISO
PF_ISO AF_ISO  winsock.h


PF_LAT
PF_LAT AF_LAT  winsock.h


PF_MAX
PF_MAX AF_MAX  winsock.h


PF_NS
PF_NS AF_NS  winsock.h


PF_OSI
PF_OSI AF_OSI  winsock.h


PF_PUP
PF_PUP AF_PUP  winsock.h


PF_SNA
PF_SNA AF_SNA  winsock.h


PF_UNIX
PF_UNIX AF_UNIX  winsock.h


PF_UNSPEC
PF_UNSPEC AF_UNSPEC  winsock.h


PHYSICALHEIGHT
PHYSICALHEIGHT 111  wingdi.h


PHYSICALOFFSETX
PHYSICALOFFSETX 112  wingdi.h


PHYSICALOFFSETY
PHYSICALOFFSETY 113  wingdi.h


PHYSICALWIDTH
PHYSICALWIDTH 110  wingdi.h


PIPE_ACCESS_DUPLEX
PIPE_ACCESS_DUPLEX 0x00000003  winbase.h


PIPE_ACCESS_INBOUND
PIPE_ACCESS_INBOUND 0x00000001  winbase.h


PIPE_ACCESS_OUTBOUND
PIPE_ACCESS_OUTBOUND 0x00000002  winbase.h


PIPE_CLIENT_END
PIPE_CLIENT_END 0x00000000  winbase.h


PIPE_NOWAIT
PIPE_NOWAIT 0x00000001  winbase.h


PIPE_READMODE_BYTE
PIPE_READMODE_BYTE 0x00000000  winbase.h


PIPE_READMODE_MESSAGE
PIPE_READMODE_MESSAGE 0x00000002  winbase.h


PIPE_SERVER_END
PIPE_SERVER_END 0x00000001  winbase.h


PIPE_TYPE_BYTE
PIPE_TYPE_BYTE 0x00000000  winbase.h


PIPE_TYPE_MESSAGE
PIPE_TYPE_MESSAGE 0x00000004  winbase.h


PIPE_UNLIMITED_INSTANCES
PIPE_UNLIMITED_INSTANCES 255  winbase.h


PIPE_WAIT
PIPE_WAIT 0x00000000  winbase.h


PM_NOYIELD
PM_NOYIELD 0x0002  winuser.h


POLYFILL_LAST
POLYFILL_LAST 2  wingdi.h


POSTSCRIPT_DATA
POSTSCRIPT_DATA 37  wingdi.h


POSTSCRIPT_IGNORE
POSTSCRIPT_IGNORE 38  wingdi.h


POSTSCRIPT_PASSTHROUGH
POSTSCRIPT_PASSTHROUGH 4115  wingdi.h


PR_JOBSTATUS
PR_JOBSTATUS 0x0000  wingdi.h


PRINTDLGORD
PRINTDLGORD 1538  dlgs.h


PRINTER_ACCESS_ADMINISTER
PRINTER_ACCESS_ADMINISTER 0x00000004  winspool.h


PRINTER_ACCESS_USE
PRINTER_ACCESS_USE 0x00000008  winspool.h


PRINTER_ALL_ACCESS
PRINTER_ALL_ACCESS (STANDARD_RIGHTS_REQUIRED | PRINTER_ACCESS_ADMINISTER | PRINTER_ACCESS_USE)  winspool.h


PRINTER_ATTRIBUTE_DEFAULT
PRINTER_ATTRIBUTE_DEFAULT 0x00000004  winspool.h


PRINTER_ATTRIBUTE_DIRECT
PRINTER_ATTRIBUTE_DIRECT 0x00000002  winspool.h


PRINTER_ATTRIBUTE_HIDDEN
PRINTER_ATTRIBUTE_HIDDEN 0x00000020  winspool.h


PRINTER_ATTRIBUTE_LOCAL
PRINTER_ATTRIBUTE_LOCAL 0x00000040  winspool.h


PRINTER_ATTRIBUTE_NETWORK
PRINTER_ATTRIBUTE_NETWORK 0x00000010  winspool.h


PRINTER_ATTRIBUTE_QUEUED
PRINTER_ATTRIBUTE_QUEUED 0x00000001  winspool.h


PRINTER_ATTRIBUTE_SHARED
PRINTER_ATTRIBUTE_SHARED 0x00000008  winspool.h


PRINTER_CHANGE_ADD_FORM
PRINTER_CHANGE_ADD_FORM 0x00010000  winspool.h


PRINTER_CHANGE_ADD_JOB
PRINTER_CHANGE_ADD_JOB 0x00000100  winspool.h


PRINTER_CHANGE_ADD_PORT
PRINTER_CHANGE_ADD_PORT 0x00100000  winspool.h


PRINTER_CHANGE_ADD_PRINT_PROCESSOR
PRINTER_CHANGE_ADD_PRINT_PROCESSOR 0x01000000  winspool.h


PRINTER_CHANGE_ADD_PRINTER
PRINTER_CHANGE_ADD_PRINTER 0x00000001  winspool.h


PRINTER_CHANGE_ADD_PRINTER_DRIVER
PRINTER_CHANGE_ADD_PRINTER_DRIVER 0x10000000  winspool.h


PRINTER_CHANGE_ALL
PRINTER_CHANGE_ALL 0x7777FFFF  winspool.h


PRINTER_CHANGE_CONFIGURE_PORT
PRINTER_CHANGE_CONFIGURE_PORT 0x00200000  winspool.h


PRINTER_CHANGE_DELETE_FORM
PRINTER_CHANGE_DELETE_FORM 0x00040000  winspool.h


PRINTER_CHANGE_DELETE_JOB
PRINTER_CHANGE_DELETE_JOB 0x00000400  winspool.h


PRINTER_CHANGE_DELETE_PORT
PRINTER_CHANGE_DELETE_PORT 0x00400000  winspool.h


PRINTER_CHANGE_DELETE_PRINT_PROCESSOR
PRINTER_CHANGE_DELETE_PRINT_PROCESSOR 0x04000000  winspool.h


PRINTER_CHANGE_DELETE_PRINTER
PRINTER_CHANGE_DELETE_PRINTER 0x00000004  winspool.h


PRINTER_CHANGE_DELETE_PRINTER_DRIVER
PRINTER_CHANGE_DELETE_PRINTER_DRIVER 0x40000000  winspool.h


PRINTER_CHANGE_FORM
PRINTER_CHANGE_FORM 0x00070000  winspool.h


PRINTER_CHANGE_JOB
PRINTER_CHANGE_JOB 0x0000FF00  winspool.h


PRINTER_CHANGE_PORT
PRINTER_CHANGE_PORT 0x00700000  winspool.h


PRINTER_CHANGE_PRINT_PROCESSOR
PRINTER_CHANGE_PRINT_PROCESSOR 0x07000000  winspool.h


PRINTER_CHANGE_PRINTER
PRINTER_CHANGE_PRINTER 0x000000FF  winspool.h


PRINTER_CHANGE_PRINTER_DRIVER
PRINTER_CHANGE_PRINTER_DRIVER 0x70000000  winspool.h


PRINTER_CHANGE_SET_FORM
PRINTER_CHANGE_SET_FORM 0x00020000  winspool.h


PRINTER_CHANGE_SET_JOB
PRINTER_CHANGE_SET_JOB 0x00000200  winspool.h


PRINTER_CHANGE_SET_PRINTER
PRINTER_CHANGE_SET_PRINTER 0x00000002  winspool.h


PRINTER_CHANGE_TIMEOUT
PRINTER_CHANGE_TIMEOUT 0x80000000  winspool.h


PRINTER_CHANGE_WRITE_JOB
PRINTER_CHANGE_WRITE_JOB 0x00000800  winspool.h


PRINTER_ENUM_CONNECTIONS
PRINTER_ENUM_CONNECTIONS 0x00000004  winspool.h


PRINTER_ENUM_CONTAINER
PRINTER_ENUM_CONTAINER 0x00008000  winspool.h


PRINTER_ENUM_EXPAND
PRINTER_ENUM_EXPAND 0x00004000  winspool.h


PRINTER_ENUM_ICON1
PRINTER_ENUM_ICON1 0x00010000  winspool.h


PRINTER_ENUM_ICON2
PRINTER_ENUM_ICON2 0x00020000  winspool.h


PRINTER_ENUM_ICON3
PRINTER_ENUM_ICON3 0x00040000  winspool.h


PRINTER_ENUM_ICON4
PRINTER_ENUM_ICON4 0x00080000  winspool.h


PRINTER_ENUM_ICON5
PRINTER_ENUM_ICON5 0x00100000  winspool.h


PRINTER_ENUM_ICON6
PRINTER_ENUM_ICON6 0x00200000  winspool.h


PRINTER_ENUM_ICON7
PRINTER_ENUM_ICON7 0x00400000  winspool.h


PRINTER_ENUM_ICON8
PRINTER_ENUM_ICON8 0x00800000  winspool.h


PRINTER_ENUM_ICONMASK
PRINTER_ENUM_ICONMASK 0x00ff0000  winspool.h


PRINTER_ENUM_NETWORK
PRINTER_ENUM_NETWORK 0x00000040  winspool.h


PRINTER_ERROR_INFORMATION
PRINTER_ERROR_INFORMATION 0x80000000  winspool.h


PRINTER_ERROR_JAM
PRINTER_ERROR_JAM 0x00000002  winspool.h


PRINTER_ERROR_OUTOFPAPER
PRINTER_ERROR_OUTOFPAPER 0x00000001  winspool.h


PRINTER_ERROR_OUTOFTONER
PRINTER_ERROR_OUTOFTONER 0x00000004  winspool.h


PRINTER_ERROR_SEVERE
PRINTER_ERROR_SEVERE 0x20000000  winspool.h


PRINTER_ERROR_WARNING
PRINTER_ERROR_WARNING 0x40000000  winspool.h


PRINTER_EXECUTE
PRINTER_EXECUTE (STANDARD_RIGHTS_EXECUTE | PRINTER_ACCESS_USE)  winspool.h


PRINTER_READ
PRINTER_READ (STANDARD_RIGHTS_READ | PRINTER_ACCESS_USE)  winspool.h


PRINTER_STATUS_BUSY
PRINTER_STATUS_BUSY 0x00000200  winspool.h


PRINTER_STATUS_DOOR_OPEN
PRINTER_STATUS_DOOR_OPEN 0x00400000  winspool.h


PRINTER_STATUS_ERROR
PRINTER_STATUS_ERROR 0x00000002  winspool.h


PRINTER_STATUS_INITIALIZING
PRINTER_STATUS_INITIALIZING 0x00008000  winspool.h


PRINTER_STATUS_IO_ACTIVE
PRINTER_STATUS_IO_ACTIVE 0x00000100  winspool.h


PRINTER_STATUS_MANUAL_FEED
PRINTER_STATUS_MANUAL_FEED 0x00000020  winspool.h


PRINTER_STATUS_NO_TONER
PRINTER_STATUS_NO_TONER 0x00040000  winspool.h


PRINTER_STATUS_NOT_AVAILABLE
PRINTER_STATUS_NOT_AVAILABLE 0x00001000  winspool.h


PRINTER_STATUS_OFFLINE
PRINTER_STATUS_OFFLINE 0x00000080  winspool.h


PRINTER_STATUS_OUT_OF_MEMORY
PRINTER_STATUS_OUT_OF_MEMORY 0x00200000  winspool.h


PRINTER_STATUS_OUTPUT_BIN_FULL
PRINTER_STATUS_OUTPUT_BIN_FULL 0x00000800  winspool.h


PRINTER_STATUS_PAGE_PUNT
PRINTER_STATUS_PAGE_PUNT 0x00080000  winspool.h


PRINTER_STATUS_PAPER_JAM
PRINTER_STATUS_PAPER_JAM 0x00000008  winspool.h


PRINTER_STATUS_PAPER_OUT
PRINTER_STATUS_PAPER_OUT 0x00000010  winspool.h


PRINTER_STATUS_PAPER_PROBLEM
PRINTER_STATUS_PAPER_PROBLEM 0x00000040  winspool.h


PRINTER_STATUS_PAUSED
PRINTER_STATUS_PAUSED 0x00000001  winspool.h


PRINTER_STATUS_PENDING_DELETION
PRINTER_STATUS_PENDING_DELETION 0x00000004  winspool.h


PRINTER_STATUS_PRINTING
PRINTER_STATUS_PRINTING 0x00000400  winspool.h


PRINTER_STATUS_PROCESSING
PRINTER_STATUS_PROCESSING 0x00004000  winspool.h


PRINTER_STATUS_TONER_LOW
PRINTER_STATUS_TONER_LOW 0x00020000  winspool.h


PRINTER_STATUS_USER_INTERVENTION
PRINTER_STATUS_USER_INTERVENTION 0x00100000  winspool.h


PRINTER_STATUS_WAITING
PRINTER_STATUS_WAITING 0x00002000  winspool.h


PRINTER_STATUS_WARMING_UP
PRINTER_STATUS_WARMING_UP 0x00010000  winspool.h


PRINTER_WRITE
PRINTER_WRITE (STANDARD_RIGHTS_WRITE | PRINTER_ACCESS_USE)  winspool.h


PRNSETUPDLGORD
PRNSETUPDLGORD 1539  dlgs.h


PROCESS_CREATE_PROCESS
PROCESS_CREATE_PROCESS (0x0080)  winnt.h


PROCESSOR_ALPHA_21064
PROCESSOR_ALPHA_21064 21064  winnt.h


PROCESSOR_INTEL_386
PROCESSOR_INTEL_386 386  winnt.h


PROCESSOR_INTEL_486
PROCESSOR_INTEL_486 486  winnt.h


PROCESSOR_INTEL_860
PROCESSOR_INTEL_860 860  winnt.h


PROCESSOR_INTEL_PENTIUM
PROCESSOR_INTEL_PENTIUM 586  winnt.h


PROCESSOR_MIPS_R2000
PROCESSOR_MIPS_R2000 2000  winnt.h


PROCESSOR_MIPS_R3000
PROCESSOR_MIPS_R3000 3000  winnt.h


PROCESSOR_MIPS_R4000
PROCESSOR_MIPS_R4000 4000  winnt.h


PROFILE_KERNEL
PROFILE_KERNEL 0x20000000  winbase.h


PROFILE_SERVER
PROFILE_SERVER 0x40000000  winbase.h


PROFILE_USER
PROFILE_USER 0x10000000  winbase.h


PS_ENDCAP_MASK
PS_ENDCAP_MASK 0x00000F00  wingdi.h


PS_JOIN_MASK
PS_JOIN_MASK 0x0000F000  wingdi.h


PS_STYLE_MASK
PS_STYLE_MASK 0x0000000F  wingdi.h


PS_TYPE_MASK
PS_TYPE_MASK 0x000F0000  wingdi.h


PURGE_RXABORT
PURGE_RXABORT 0x0002  winbase.h


PURGE_RXCLEAR
PURGE_RXCLEAR 0x0008  winbase.h


PURGE_TXABORT
PURGE_TXABORT 0x0001  winbase.h


PURGE_TXCLEAR
PURGE_TXCLEAR 0x0004  winbase.h


PWR_FAIL
PWR_FAIL (-1)  winuser.h


PWR_OK
PWR_OK 1  winuser.h


QID_SYNC
QID_SYNC 0xFFFFFFFF  ddeml.h


QUERYESCSUPPORT
QUERYESCSUPPORT 8  wingdi.h


QUERYROPSUPPORT
QUERYROPSUPPORT 40  mmsystem.h


R2_LAST
R2_LAST 16  wingdi.h


RAS_MaxCallbackNumber
RAS_MaxCallbackNumber 48  ras.h


RAS_MaxDeviceName
RAS_MaxDeviceName 32  ras.h


RAS_MaxDeviceType
RAS_MaxDeviceType 16  ras.h


RAS_MaxEntryName
RAS_MaxEntryName 20  ras.h


RAS_MaxParamKey
RAS_MaxParamKey 32  ras.h


RAS_MaxParamValue
RAS_MaxParamValue 128  ras.h


RAS_MaxPhoneNumber
RAS_MaxPhoneNumber 128  ras.h


RASBASE
RASBASE 600  raserror.h


RASBASEEND
RASBASEEND (RASBASE+111)  raserror.h


RASCS_DONE
RASCS_DONE 0x2000  ras.h


RASCS_PAUSED
RASCS_PAUSED 0x1000  ras.h


RASTER_FONTTYPE
RASTER_FONTTYPE 0x0001  wingdi.h


RC_BIGFONT
RC_BIGFONT 0x0400  wingdi.h


RC_DEVBITS
RC_DEVBITS 0x8000  wingdi.h


RC_GDI20_STATE
RC_GDI20_STATE 0x0020  wingdi.h


RC_NONE
RC_NONE nothing  wingdi.h


RC_OP_DX_OUTPUT
RC_OP_DX_OUTPUT 0x4000  wingdi.h


RC_SAVEBITMAP
RC_SAVEBITMAP 0x0040  wingdi.h


RDH_RECTANGLES
RDH_RECTANGLES 1  wingdi.h


READ_CONTROL
READ_CONTROL (0x00020000L)  winnt.h


REALTIME_PRIORITY_CLASS
REALTIME_PRIORITY_CLASS 0x00000100  winbase.h


REFERENCE_BLACK_MAX
REFERENCE_BLACK_MAX (WORD)4000  wingdi.h


REFERENCE_BLACK_MIN
REFERENCE_BLACK_MIN (WORD)0  wingdi.h


REFERENCE_WHITE_MAX
REFERENCE_WHITE_MAX (WORD)10000  wingdi.h


REFERENCE_WHITE_MIN
REFERENCE_WHITE_MIN (WORD)6000  wingdi.h


REG_FULL_RESOURCE_DESCRIPTOR
REG_FULL_RESOURCE_DESCRIPTOR ( 9 )  winnt.h


REG_LEGAL_CHANGE_FILTER
REG_LEGAL_CHANGE_FILTER (REG_NOTIFY_CHANGE_NAME | REG_NOTIFY_CHANGE_ATTRIBUTES | REG_NOTIFY_CHANGE_LAST_SET | REG_NOTIFY_CHANGE_SECURITY) winnt.h


REG_OPTION_CREATE_LINK
REG_OPTION_CREATE_LINK (0x00000002L)  winnt.h


REG_OPTION_RESERVED
REG_OPTION_RESERVED (0x00000000L)  winnt.h


REG_REFRESH_HIVE
REG_REFRESH_HIVE (0x00000002L)  winnt.h


REGULAR_FONTTYPE
REGULAR_FONTTYPE 0x0400  commdlg.h


RELATIVE
RELATIVE 2  wingdi.h


REPLACEDLGORD
REPLACEDLGORD 1541  dlgs.h


RESETDEV
RESETDEV 7  winbase.h


RESOURCEDISPLAYTYPE_FILE
RESOURCEDISPLAYTYPE_FILE 0x00000004  winnetwk.h


RESOURCEDISPLAYTYPE_GROUP
RESOURCEDISPLAYTYPE_GROUP 0x00000005  winnetwk.h


RESOURCETYPE_DISK
RESOURCETYPE_DISK 0x00000001  winnetwk.h


RESOURCETYPE_PRINT
RESOURCETYPE_PRINT 0x00000002  winnetwk.h


RESOURCETYPE_UNKNOWN
RESOURCETYPE_UNKNOWN 0xFFFFFFFF  winnetwk.h


RESOURCEUSAGE_CONNECTABLE
RESOURCEUSAGE_CONNECTABLE 0x00000001  winnetwk.h


RESOURCEUSAGE_CONTAINER
RESOURCEUSAGE_CONTAINER 0x00000002  winnetwk.h


RESOURCEUSAGE_RESERVED
RESOURCEUSAGE_RESERVED 0x80000000  winnetwk.h


RESTORE_CTM
RESTORE_CTM 4100  wingdi.h


RGB_GAMMA_MAX
RGB_GAMMA_MAX (WORD)65000  wingdi.h


RGB_GAMMA_MIN
RGB_GAMMA_MIN (WORD)02500  wingdi.h


RGN_ERROR
RGN_ERROR ERROR  wingdi.h


RGN_MAX
RGN_MAX RGN_COPY  wingdi.h


RGN_MIN
RGN_MIN RGN_AND  wingdi.h


RIGHTMOST_BUTTON_PRESSED
RIGHTMOST_BUTTON_PRESSED 0x0002  wincon.h


RIP_EVENT
RIP_EVENT 9  winbase.h


RT_DLGINCLUDE
RT_DLGINCLUDE MAKEINTRESOURCE(17)  winuser.h


RTL_CRITSECT_TYPE
RTL_CRITSECT_TYPE 0  winnt.h


RTL_RESOURCE_TYPE
RTL_RESOURCE_TYPE 1  winnt.h


S_ALLTHRESHOLD
S_ALLTHRESHOLD 2  winbase.h


S_LEGATO
S_LEGATO 1  winbase.h


S_NORMAL
S_NORMAL 0  winbase.h


S_PERIOD1024
S_PERIOD1024 1  winbase.h


S_PERIOD2048
S_PERIOD2048 2  winbase.h


S_PERIOD512
S_PERIOD512 0  winbase.h


S_PERIODVOICE
S_PERIODVOICE 3  winbase.h


S_QUEUEEMPTY
S_QUEUEEMPTY 0  winbase.h


S_SERBDNT
S_SERBDNT (-5)  winbase.h


S_SERDCC
S_SERDCC (-7)  winbase.h


S_SERDDR
S_SERDDR (-14)  winbase.h


S_SERDFQ
S_SERDFQ (-13)  winbase.h


S_SERDLN
S_SERDLN (-6)  winbase.h


S_SERDMD
S_SERDMD (-10)  winbase.h


S_SERDPT
S_SERDPT (-12)  winbase.h


S_SERDSH
S_SERDSH (-11)  winbase.h


S_SERDSR
S_SERDSR (-15)  winbase.h


S_SERDST
S_SERDST (-16)  winbase.h


S_SERDTP
S_SERDTP (-8)  winbase.h


S_SERDVL
S_SERDVL (-9)  winbase.h


S_SERDVNA
S_SERDVNA (-1)  winbase.h


S_SERMACT
S_SERMACT (-3)  winbase.h


S_SEROFM
S_SEROFM (-2)  winbase.h


S_SERQFUL
S_SERQFUL (-4)  winbase.h


S_STACCATO
S_STACCATO 2  winbase.h


S_THRESHOLD
S_THRESHOLD 1  winbase.h


S_WHITE1024
S_WHITE1024 5  winbase.h


S_WHITE2048
S_WHITE2048 6  winbase.h


S_WHITE512
S_WHITE512 4  winbase.h


S_WHITEVOICE
S_WHITEVOICE 7  winbase.h


SAVE_CTM
SAVE_CTM 4101  wingdi.h


SB_LEFT
SB_LEFT 6  winuser.h


SB_LINELEFT
SB_LINELEFT 0  winuser.h


SB_LINERIGHT
SB_LINERIGHT 1  winuser.h


SB_PAGELEFT
SB_PAGELEFT 2  winuser.h


SB_PAGERIGHT
SB_PAGERIGHT 3  winuser.h


SB_RIGHT
SB_RIGHT 7  winuser.h


SBS_BOTTOMALIGN
SBS_BOTTOMALIGN 0x0004L  winuser.h


SBS_HORZ
SBS_HORZ 0x0000L  winuser.h


SBS_LEFTALIGN
SBS_LEFTALIGN 0x0002L  winuser.h


SBS_RIGHTALIGN
SBS_RIGHTALIGN 0x0004L  winuser.h


SBS_SIZEBOX
SBS_SIZEBOX 0x0008L  winuser.h


SBS_SIZEBOXBOTTOMRIGHTALIGN
SBS_SIZEBOXBOTTOMRIGHTALIGN 0x0004L  winuser.h


SBS_SIZEBOXTOPLEFTALIGN
SBS_SIZEBOXTOPLEFTALIGN 0x0002L  winuser.h


SBS_TOPALIGN
SBS_TOPALIGN 0x0002L  winuser.h


SBS_VERT
SBS_VERT 0x0001L  winuser.h


SC_ARRANGE
SC_ARRANGE 0xF110  winuser.h


SC_GROUP_IDENTIFIERA
SC_GROUP_IDENTIFIERA '+'  winsvc.h


SC_GROUP_IDENTIFIERW
SC_GROUP_IDENTIFIERW L'+'  winsvc.h


SC_ICON
SC_ICON SC_MINIMIZE  winuser.h


SC_MANAGER_ALL_ACCESS
SC_MANAGER_ALL_ACCESS (STANDARD_RIGHTS_REQUIRED | SC_MANAGER_CONNECT | SC_MANAGER_CREATE_SERVICE | SC_MANAGER_ENUMERATE_SERVICE | SC_MANAGER_LOCK | SC_MANAGER_QUERY_LOCK_STATUS | SC_MANAGER_MODIFY_BOOT_CONFIG)  winsvc.h


SC_MANAGER_CONNECT
SC_MANAGER_CONNECT 0x0001  winsvc.h


SC_MANAGER_CREATE_SERVICE
SC_MANAGER_CREATE_SERVICE 0x0002  winsvc.h


SC_MANAGER_ENUMERATE_SERVICE
SC_MANAGER_ENUMERATE_SERVICE 0x0004  winsvc.h


SC_MANAGER_LOCK
SC_MANAGER_LOCK 0x0008  winsvc.h


SC_MANAGER_MODIFY_BOOT_CONFIG
SC_MANAGER_MODIFY_BOOT_CONFIG 0x0020  winsvc.h


SC_MANAGER_QUERY_LOCK_STATUS
SC_MANAGER_QUERY_LOCK_STATUS 0x0010  winsvc.h


SC_ZOOM
SC_ZOOM SC_MAXIMIZE  winuser.h


SCALINGFACTORX
SCALINGFACTORX 114  wingdi.h


SCALINGFACTORY
SCALINGFACTORY 115  wingdi.h


SE_ASSIGNPRIMARYTOKEN_NAME
SE_ASSIGNPRIMARYTOKEN_NAME TEXT("SeAssignPrimaryTokenPrivilege")  winnt.h


SE_AUDIT_NAME
SE_AUDIT_NAME TEXT("SeAuditPrivilege")  winnt.h


SE_BACKUP_NAME
SE_BACKUP_NAME TEXT("SeBackupPrivilege")  winnt.h


SE_CHANGE_NOTIFY_NAME
SE_CHANGE_NOTIFY_NAME TEXT("SeChangeNotifyPrivilege")  winnt.h


SE_CREATE_PAGEFILE_NAME
SE_CREATE_PAGEFILE_NAME TEXT("SeCreatePagefilePrivilege")  winnt.h


SE_CREATE_PERMANENT_NAME
SE_CREATE_PERMANENT_NAME TEXT("SeCreatePermanentPrivilege")  winnt.h


SE_CREATE_TOKEN_NAME
SE_CREATE_TOKEN_NAME TEXT("SeCreateTokenPrivilege")  winnt.h


SE_DEBUG_NAME
SE_DEBUG_NAME TEXT("SeDebugPrivilege")  winnt.h


SE_INC_BASE_PRIORITY_NAME
SE_INC_BASE_PRIORITY_NAME TEXT("SeIncreaseBasePriorityPrivilege")  winnt.h


SE_INCREASE_QUOTA_NAME
SE_INCREASE_QUOTA_NAME TEXT("SeIncreaseQuotaPrivilege")  winnt.h


SE_LOAD_DRIVER_NAME
SE_LOAD_DRIVER_NAME TEXT("SeLoadDriverPrivilege")  winnt.h


SE_LOCK_MEMORY_NAME
SE_LOCK_MEMORY_NAME TEXT("SeLockMemoryPrivilege")  winnt.h


SE_PROF_SINGLE_PROCESS_NAME
SE_PROF_SINGLE_PROCESS_NAME TEXT("SeProfileSingleProcessPrivilege")  winnt.h


SE_REMOTE_SHUTDOWN_NAME
SE_REMOTE_SHUTDOWN_NAME TEXT("SeRemoteShutdownPrivilege")  winnt.h


SE_RESTORE_NAME
SE_RESTORE_NAME TEXT("SeRestorePrivilege")  winnt.h


SE_SECURITY_NAME
SE_SECURITY_NAME TEXT("SeSecurityPrivilege")  winnt.h


SE_SHUTDOWN_NAME
SE_SHUTDOWN_NAME TEXT("SeShutdownPrivilege")  winnt.h


SE_SYSTEM_ENVIRONMENT_NAME
SE_SYSTEM_ENVIRONMENT_NAME TEXT("SeSystemEnvironmentPrivilege")  winnt.h


SE_SYSTEM_PROFILE_NAME
SE_SYSTEM_PROFILE_NAME TEXT("SeSystemProfilePrivilege")  winnt.h


SE_SYSTEMTIME_NAME
SE_SYSTEMTIME_NAME TEXT("SeSystemtimePrivilege")  winnt.h


SE_TAKE_OWNERSHIP_NAME
SE_TAKE_OWNERSHIP_NAME TEXT("SeTakeOwnershipPrivilege")  winnt.h


SE_TCB_NAME
SE_TCB_NAME TEXT("SeTcbPrivilege")  winnt.h


SE_UNSOLICITED_INPUT_NAME
SE_UNSOLICITED_INPUT_NAME TEXT("SeUnsolicitedInputPrivilege")  winnt.h


SECTION_ALL_ACCESS
SECTION_ALL_ACCESS (STANDARD_RIGHTS_REQUIRED|SECTION_QUERY|SECTION_MAP_WRITE|SECTION_MAP_READ|SECTION_MAP_EXECUTE|SECTION_EXTEND_SIZE) winnt.h


SECTION_EXTEND_SIZE
SECTION_EXTEND_SIZE 0x0010  winnt.h


SECTION_MAP_EXECUTE
SECTION_MAP_EXECUTE 0x0008  winnt.h


SECTION_MAP_READ
SECTION_MAP_READ 0x0004  winnt.h


SECTION_MAP_WRITE
SECTION_MAP_WRITE 0x0002  winnt.h


SECTION_QUERY
SECTION_QUERY 0x0001  winnt.h


SECURITY_ANONYMOUS_LOGON_RID
SECURITY_ANONYMOUS_LOGON_RID (0x00000007L)  winnt.h


SECURITY_BATCH_RID
SECURITY_BATCH_RID (0x00000003L)  winnt.h


SECURITY_BUILTIN_DOMAIN_RID
SECURITY_BUILTIN_DOMAIN_RID (0x00000020L)  winnt.h


SECURITY_CREATOR_GROUP_RID
SECURITY_CREATOR_GROUP_RID (0x00000001L)  winnt.h


SECURITY_CREATOR_OWNER_RID
SECURITY_CREATOR_OWNER_RID (0x00000000L)  winnt.h


SECURITY_CREATOR_SID_AUTHORITY
SECURITY_CREATOR_SID_AUTHORITY {0,0,0,0,0,3}  winnt.h


SECURITY_DESCRIPTOR_MIN_LENGTH
SECURITY_DESCRIPTOR_MIN_LENGTH (20)  winnt.h


SECURITY_DESCRIPTOR_REVISION
SECURITY_DESCRIPTOR_REVISION (1)  winnt.h


SECURITY_DESCRIPTOR_REVISION1
SECURITY_DESCRIPTOR_REVISION1 (1)  winnt.h


SECURITY_DIALUP_RID
SECURITY_DIALUP_RID (0x00000001L)  winnt.h


SECURITY_DYNAMIC_TRACKING
SECURITY_DYNAMIC_TRACKING (TRUE)  winnt.h


SECURITY_INTERACTIVE_RID
SECURITY_INTERACTIVE_RID (0x00000004L)  winnt.h


SECURITY_LOCAL_RID
SECURITY_LOCAL_RID (0X00000000L)  winnt.h


SECURITY_LOCAL_SID_AUTHORITY
SECURITY_LOCAL_SID_AUTHORITY {0,0,0,0,0,2}  winnt.h


SECURITY_LOCAL_SYSTEM_RID
SECURITY_LOCAL_SYSTEM_RID (0x00000012L)  winnt.h


SECURITY_LOGON_IDS_RID
SECURITY_LOGON_IDS_RID (0x00000005L)  winnt.h


SECURITY_LOGON_IDS_RID_COUNT
SECURITY_LOGON_IDS_RID_COUNT (3L)  winnt.h


SECURITY_MAX_IMPERSONATION_LEVEL
SECURITY_MAX_IMPERSONATION_LEVEL SecurityDelegation  winnt.h


SECURITY_NETWORK_RID
SECURITY_NETWORK_RID (0x00000002L)  winnt.h


SECURITY_NON_UNIQUE_AUTHORITY
SECURITY_NON_UNIQUE_AUTHORITY {0,0,0,0,0,4}  winnt.h


SECURITY_NT_AUTHORITY
SECURITY_NT_AUTHORITY {0,0,0,0,0,5}  winnt.h


SECURITY_NT_NON_UNIQUE
SECURITY_NT_NON_UNIQUE (0x00000015L)  winnt.h


SECURITY_NULL_RID
SECURITY_NULL_RID (0x00000000L)  winnt.h


SECURITY_NULL_SID_AUTHORITY
SECURITY_NULL_SID_AUTHORITY {0,0,0,0,0,0}  winnt.h


SECURITY_SERVICE_RID
SECURITY_SERVICE_RID (0x00000006L)  winnt.h


SECURITY_SQOS_PRESENT
SECURITY_SQOS_PRESENT 0x00100000  winbase.h


SECURITY_STATIC_TRACKING
SECURITY_STATIC_TRACKING (FALSE)  winnt.h


SECURITY_VALID_SQOS_FLAGS
SECURITY_VALID_SQOS_FLAGS 0x001F0000  winbase.h


SECURITY_WORLD_RID
SECURITY_WORLD_RID (0x00000000L)  winnt.h


SECURITY_WORLD_SID_AUTHORITY
SECURITY_WORLD_SID_AUTHORITY {0,0,0,0,0,1}  winnt.h


SELECTDIB
SELECTDIB 41  mmsystem.h


SELECTPAPERSOURCE
SELECTPAPERSOURCE 18  wingdi.h


SEMAPHORE_MODIFY_STATE
SEMAPHORE_MODIFY_STATE 0x0002  winnt.h


SEP_CHAR
SEP_CHAR ','  nddeapi.h


SEP_WCHAR
SEP_WCHAR L','  nddeapi.h


SERVER_ACCESS_ADMINISTER
SERVER_ACCESS_ADMINISTER 0x00000001  winspool.h


SERVER_ACCESS_ENUMERATE
SERVER_ACCESS_ENUMERATE 0x00000002  winspool.h


SERVER_ALL_ACCESS
SERVER_ALL_ACCESS (STANDARD_RIGHTS_REQUIRED | SERVER_ACCESS_ADMINISTER | SERVER_ACCESS_ENUMERATE)  winspool.h


SERVER_EXECUTE
SERVER_EXECUTE (STANDARD_RIGHTS_EXECUTE | SERVER_ACCESS_ENUMERATE)  winspool.h


SERVER_READ
SERVER_READ (STANDARD_RIGHTS_READ | SERVER_ACCESS_ENUMERATE)  winspool.h


SERVER_WRITE
SERVER_WRITE (STANDARD_RIGHTS_WRITE | SERVER_ACCESS_ADMINISTER | SERVER_ACCESS_ENUMERATE)  winspool.h


SERVICE_ACCEPT_PAUSE_CONTINUE
SERVICE_ACCEPT_PAUSE_CONTINUE 0x00000002  winsvc.h


SERVICE_ACCEPT_SHUTDOWN
SERVICE_ACCEPT_SHUTDOWN 0x00000004  winsvc.h


SERVICE_ACCEPT_STOP
SERVICE_ACCEPT_STOP 0x00000001  winsvc.h


SERVICE_ACTIVE
SERVICE_ACTIVE 0x00000001  winsvc.h


SERVICE_ADAPTER
SERVICE_ADAPTER 0x00000004  winnt.h


SERVICE_ALL_ACCESS
SERVICE_ALL_ACCESS (STANDARD_RIGHTS_REQUIRED | SERVICE_QUERY_CONFIG | SERVICE_CHANGE_CONFIG | SERVICE_QUERY_STATUS | SERVICE_ENUMERATE_DEPENDENTS | SERVICE_START | SERVICE_STOP | SERVICE_PAUSE_CONTINUE | SERVICE_INTERROGATE | SERVICE_USER_DEFINED_CONTROL)  winsvc.h


SERVICE_AUTO_START
SERVICE_AUTO_START 0x00000002  winnt.h


SERVICE_BOOT_START
SERVICE_BOOT_START 0x00000000  winnt.h


SERVICE_CHANGE_CONFIG
SERVICE_CHANGE_CONFIG 0x0002  winsvc.h


SERVICE_CONTINUE_PENDING
SERVICE_CONTINUE_PENDING 0x00000005  winsvc.h


SERVICE_CONTROL_CONTINUE
SERVICE_CONTROL_CONTINUE 0x00000003  winsvc.h


SERVICE_CONTROL_INTERROGATE
SERVICE_CONTROL_INTERROGATE 0x00000004  winsvc.h


SERVICE_CONTROL_PAUSE
SERVICE_CONTROL_PAUSE 0x00000002  winsvc.h


SERVICE_CONTROL_SHUTDOWN
SERVICE_CONTROL_SHUTDOWN 0x00000005  winsvc.h


SERVICE_CONTROL_STOP
SERVICE_CONTROL_STOP 0x00000001  winsvc.h


SERVICE_DEMAND_START
SERVICE_DEMAND_START 0x00000003  winnt.h


SERVICE_DISABLED
SERVICE_DISABLED 0x00000004  winnt.h


SERVICE_DRIVER
SERVICE_DRIVER (SERVICE_KERNEL_DRIVER | SERVICE_FILE_SYSTEM_DRIVER | SERVICE_RECOGNIZER_DRIVER)  winnt.h


SERVICE_ENUMERATE_DEPENDENTS
SERVICE_ENUMERATE_DEPENDENTS 0x0008  winsvc.h


SERVICE_ERROR_CRITICAL
SERVICE_ERROR_CRITICAL 0x00000003  winnt.h


SERVICE_ERROR_IGNORE
SERVICE_ERROR_IGNORE 0x00000000  winnt.h


SERVICE_ERROR_NORMAL
SERVICE_ERROR_NORMAL 0x00000001  winnt.h


SERVICE_ERROR_SEVERE
SERVICE_ERROR_SEVERE 0x00000002  winnt.h


SERVICE_FILE_SYSTEM_DRIVER
SERVICE_FILE_SYSTEM_DRIVER 0x00000002  winnt.h


SERVICE_INACTIVE
SERVICE_INACTIVE 0x00000002  winsvc.h


SERVICE_INTERROGATE
SERVICE_INTERROGATE 0x0080  winsvc.h


SERVICE_KERNEL_DRIVER
SERVICE_KERNEL_DRIVER 0x00000001  winnt.h


SERVICE_NO_CHANGE
SERVICE_NO_CHANGE 0xffffffff  winsvc.h


SERVICE_PAUSE_CONTINUE
SERVICE_PAUSE_CONTINUE 0x0040  winsvc.h


SERVICE_PAUSE_PENDING
SERVICE_PAUSE_PENDING 0x00000006  winsvc.h


SERVICE_PAUSED
SERVICE_PAUSED 0x00000007  winsvc.h


SERVICE_QUERY_CONFIG
SERVICE_QUERY_CONFIG 0x0001  winsvc.h


SERVICE_QUERY_STATUS
SERVICE_QUERY_STATUS 0x0004  winsvc.h


SERVICE_RECOGNIZER_DRIVER
SERVICE_RECOGNIZER_DRIVER 0x00000008  winnt.h


SERVICE_RUNNING
SERVICE_RUNNING 0x00000004  winsvc.h


SERVICE_START
SERVICE_START 0x0010  winsvc.h


SERVICE_START_PENDING
SERVICE_START_PENDING 0x00000002  winsvc.h


SERVICE_STATE_ALL
SERVICE_STATE_ALL (SERVICE_ACTIVE | SERVICE_INACTIVE)  winsvc.h


SERVICE_STOP
SERVICE_STOP 0x0020  winsvc.h


SERVICE_STOP_PENDING
SERVICE_STOP_PENDING 0x00000003  winsvc.h


SERVICE_STOPPED
SERVICE_STOPPED 0x00000001  winsvc.h


SERVICE_SYSTEM_START
SERVICE_SYSTEM_START 0x00000001  winnt.h


SERVICE_TYPE_ALL
SERVICE_TYPE_ALL (SERVICE_WIN32 | SERVICE_ADAPTER | SERVICE_DRIVER)  winnt.h


SERVICE_USER_DEFINED_CONTROL
SERVICE_USER_DEFINED_CONTROL 0x0100  winsvc.h


SERVICE_WIN32
SERVICE_WIN32 (SERVICE_WIN32_OWN_PROCESS | SERVICE_WIN32_SHARE_PROCESS)  winnt.h


SERVICE_WIN32_OWN_PROCESS
SERVICE_WIN32_OWN_PROCESS 0x00000010  winnt.h


SERVICE_WIN32_SHARE_PROCESS
SERVICE_WIN32_SHARE_PROCESS 0x00000020  winnt.h


SERVICES_ACTIVE_DATABASE
SERVICES_ACTIVE_DATABASE SERVICES_ACTIVE_DATABASEA  winsvc.h


SERVICES_ACTIVE_DATABASE
SERVICES_ACTIVE_DATABASE SERVICES_ACTIVE_DATABASEW  winsvc.h


SERVICES_ACTIVE_DATABASEA
SERVICES_ACTIVE_DATABASEA "ServicesActive"  winsvc.h


SERVICES_ACTIVE_DATABASEW
SERVICES_ACTIVE_DATABASEW L"ServicesActive"  winsvc.h


SERVICES_FAILED_DATABASE
SERVICES_FAILED_DATABASE SERVICES_FAILED_DATABASEA  winsvc.h


SERVICES_FAILED_DATABASE
SERVICES_FAILED_DATABASE SERVICES_FAILED_DATABASEW  winsvc.h


SERVICES_FAILED_DATABASEA
SERVICES_FAILED_DATABASEA "ServicesFailed"  winsvc.h


SERVICES_FAILED_DATABASEW
SERVICES_FAILED_DATABASEW L"ServicesFailed"  winsvc.h


SET_ARC_DIRECTION
SET_ARC_DIRECTION 4102  wingdi.h


SET_BACKGROUND_COLOR
SET_BACKGROUND_COLOR 4103  wingdi.h


SET_BOUNDS
SET_BOUNDS 4109  wingdi.h


SET_CLIP_BOX
SET_CLIP_BOX 4108  wingdi.h


SET_MIRROR_MODE
SET_MIRROR_MODE 4110  wingdi.h


SET_POLY_MODE
SET_POLY_MODE 4104  wingdi.h


SET_SCREEN_ANGLE
SET_SCREEN_ANGLE 4105  wingdi.h


SET_SPREAD
SET_SPREAD 4106  wingdi.h


SET_TAPE_DRIVE_INFORMATION
SET_TAPE_DRIVE_INFORMATION 1  winbase.h


SETABORTPROC
SETABORTPROC 9  wingdi.h


SETALLJUSTVALUES
SETALLJUSTVALUES 771  wingdi.h


SETBREAK
SETBREAK 8  winbase.h


SETCHARSET
SETCHARSET 772  wingdi.h


SETCOLORTABLE
SETCOLORTABLE 4  wingdi.h


SETCOPYCOUNT
SETCOPYCOUNT 17  wingdi.h


SETDIBSCALING
SETDIBSCALING 32  wingdi.h


SETDTR
SETDTR 5  winbase.h


SETKERNTRACK
SETKERNTRACK 770  wingdi.h


SETLINECAP
SETLINECAP 21  wingdi.h


SETLINEJOIN
SETLINEJOIN 22  wingdi.h


SETMITERLIMIT
SETMITERLIMIT 23  wingdi.h


SETRGBSTRING
SETRGBSTRING SETRGBSTRINGA  commdlg.h


SETRGBSTRING
SETRGBSTRING SETRGBSTRINGW  commdlg.h


SETRGBSTRINGA
SETRGBSTRINGA "commdlg_SetRGBColor"  commdlg.h


SETRGBSTRINGW
SETRGBSTRINGW L"commdlg_SetRGBColor"  commdlg.h


SETRTS
SETRTS 3  winbase.h


SETXOFF
SETXOFF 1  winbase.h


SETXON
SETXON 2  winbase.h


SHAREVISTRING
SHAREVISTRING SHAREVISTRINGA  commdlg.h


SHAREVISTRING
SHAREVISTRING SHAREVISTRINGW  commdlg.h


SHAREVISTRINGA
SHAREVISTRINGA "commdlg_ShareViolation"  commdlg.h


SHAREVISTRINGW
SHAREVISTRINGW L"commdlg_ShareViolation"  commdlg.h


SHIFTJIS_CHARSET
SHIFTJIS_CHARSET 128  wingdi.h


SHOW_FULLSCREEN
SHOW_FULLSCREEN 3  winuser.h


SHOW_ICONWINDOW
SHOW_ICONWINDOW 2  winuser.h


SHOW_OPENNOACTIVATE
SHOW_OPENNOACTIVATE 4  winuser.h


SHOW_OPENWINDOW
SHOW_OPENWINDOW 1  winuser.h


SID_MAX_SUB_AUTHORITIES
SID_MAX_SUB_AUTHORITIES (15)  winnt.h


SID_RECOMMENDED_SUB_AUTHORITIES
SID_RECOMMENDED_SUB_AUTHORITIES (1)  winnt.h


SID_REVISION
SID_REVISION (1)  winnt.h


SIOCATMARK
SIOCATMARK _IOR('s', 7, u_long)  winsock.h


SIOCGHIWAT
SIOCGHIWAT _IOR('s', 1, u_long)  winsock.h


SIOCGLOWAT
SIOCGLOWAT _IOR('s', 3, u_long)  winsock.h


SIOCSHIWAT
SIOCSHIWAT _IOW('s', 0, u_long)  winsock.h


SIOCSLOWAT
SIOCSLOWAT _IOW('s', 2, u_long)  winsock.h


SIZE_OF_80387_REGISTERS
SIZE_OF_80387_REGISTERS 80  winnt.h


SIZEFULLSCREEN
SIZEFULLSCREEN SIZE_MAXIMIZED  winuser.h


SIZEICONIC
SIZEICONIC SIZE_MINIMIZED  winuser.h


SIZENORMAL
SIZENORMAL SIZE_RESTORED  winuser.h


SIZEOF_RFPO_DATA
SIZEOF_RFPO_DATA 16  winnt.h


SIZEZOOMHIDE
SIZEZOOMHIDE SIZE_MAXHIDE  winuser.h


SIZEZOOMSHOW
SIZEZOOMSHOW SIZE_MAXSHOW  winuser.h


SM_CMETRICS
SM_CMETRICS 44  winuser.h


SM_RESERVED1
SM_RESERVED1 24  winuser.h


SM_RESERVED2
SM_RESERVED2 25  winuser.h


SM_RESERVED3
SM_RESERVED3 26  winuser.h


SM_RESERVED4
SM_RESERVED4 27  winuser.h


SMTO_NORMAL
SMTO_NORMAL 0x0000  winuser.h


SND_ALIAS_ID
SND_ALIAS_ID 0x00110000  mmsystem.h


SND_ALIAS_ID
SND_ALIAS_ID 0x00110000  mmsystem.h


SND_ALIAS_START
SND_ALIAS_START 0  mmsystem.h


SND_ALIAS_SYSTEMASTERISK
SND_ALIAS_SYSTEMASTERISK sndAlias('S', '*')  mmsystem.h


SND_ALIAS_SYSTEMDEFAULT
SND_ALIAS_SYSTEMDEFAULT sndAlias('S', 'D')  mmsystem.h


SND_ALIAS_SYSTEMEXCLAMATION
SND_ALIAS_SYSTEMEXCLAMATION sndAlias('S', '!')  mmsystem.h


SND_ALIAS_SYSTEMEXIT
SND_ALIAS_SYSTEMEXIT sndAlias('S', 'E')  mmsystem.h


SND_ALIAS_SYSTEMHAND
SND_ALIAS_SYSTEMHAND sndAlias('S', 'H')  mmsystem.h


SND_ALIAS_SYSTEMQUESTION
SND_ALIAS_SYSTEMQUESTION sndAlias('S', '?')  mmsystem.h


SND_ALIAS_SYSTEMSTART
SND_ALIAS_SYSTEMSTART sndAlias('S', 'S')  mmsystem.h


SND_ALIAS_SYSTEMWELCOME
SND_ALIAS_SYSTEMWELCOME sndAlias('S', 'W')  mmsystem.h


SND_RESERVED
SND_RESERVED 0xFF000000  mmsystem.h


SND_TYPE_MASK
SND_TYPE_MASK 0x00170007  mmsystem.h


SND_VALIDFLAGS
SND_VALIDFLAGS 0x0017201F  mmsystem.h


SO_ACCEPTCONN
SO_ACCEPTCONN 0x0002  winsock.h


SO_BROADCAST
SO_BROADCAST 0x0020  winsock.h


SO_CONNDATA
SO_CONNDATA 0x7000  winsock.h


SO_CONNDATALEN
SO_CONNDATALEN 0x7004  winsock.h


SO_CONNOPT
SO_CONNOPT 0x7001  winsock.h


SO_CONNOPTLEN
SO_CONNOPTLEN 0x7005  winsock.h


SO_DEBUG
SO_DEBUG 0x0001  winsock.h


SO_DISCDATA
SO_DISCDATA 0x7002  winsock.h


SO_DISCDATALEN
SO_DISCDATALEN 0x7006  winsock.h


SO_DISCOPT
SO_DISCOPT 0x7003  winsock.h


SO_DISCOPTLEN
SO_DISCOPTLEN 0x7007  winsock.h


SO_DONTROUTE
SO_DONTROUTE 0x0010  winsock.h


SO_ERROR
SO_ERROR 0x1007  winsock.h


SO_KEEPALIVE
SO_KEEPALIVE 0x0008  winsock.h


SO_LINGER
SO_LINGER 0x0080  winsock.h


SO_OOBINLINE
SO_OOBINLINE 0x0100  winsock.h


SO_RCVBUF
SO_RCVBUF 0x1002  winsock.h


SO_RCVLOWAT
SO_RCVLOWAT 0x1004  winsock.h


SO_RCVTIMEO
SO_RCVTIMEO 0x1006  winsock.h


SO_REUSEADDR
SO_REUSEADDR 0x0004  winsock.h


SO_SNDBUF
SO_SNDBUF 0x1001  winsock.h


SO_SNDLOWAT
SO_SNDLOWAT 0x1003  winsock.h


SO_SNDTIMEO
SO_SNDTIMEO 0x1005  winsock.h


SO_TYPE
SO_TYPE 0x1008  winsock.h


SO_USELOOPBACK
SO_USELOOPBACK 0x0040  winsock.h


SOCK_DGRAM
SOCK_DGRAM 2  winsock.h


SOCK_RAW
SOCK_RAW 3  winsock.h


SOCK_RDM
SOCK_RDM 4  winsock.h


SOCK_SEQPACKET
SOCK_SEQPACKET 5  winsock.h


SOCK_STREAM
SOCK_STREAM 1  winsock.h


SOCKET_ERROR
SOCKET_ERROR (-1)  winsock.h


SOL_SOCKET
SOL_SOCKET 0xffff  winsock.h


SOMAXCONN
SOMAXCONN 5  winsock.h


SORT_DEFAULT
SORT_DEFAULT 0x0  winnt.h


SP_NOTREPORTED
SP_NOTREPORTED 0x4000  wingdi.h


SPACEPARITY
SPACEPARITY 4  winbase.h


SPECIFIC_RIGHTS_ALL
SPECIFIC_RIGHTS_ALL (0x0000FFFFL)  winnt.h


SS_BLACKFRAME
SS_BLACKFRAME 0x07L  winuser.h


SS_BLACKRECT
SS_BLACKRECT 0x04L  winuser.h


SS_CENTER
SS_CENTER 0x01L  winuser.h


SS_GRAYFRAME
SS_GRAYFRAME 0x08L  winuser.h


SS_GRAYRECT
SS_GRAYRECT 0x05L  winuser.h


SS_ICON
SS_ICON 0x03L  winuser.h


SS_LEFT
SS_LEFT 0x00L  winuser.h


SS_LEFTNOWORDWRAP
SS_LEFTNOWORDWRAP 0x0CL  winuser.h


SS_NOPREFIX
SS_NOPREFIX 0x80L  winuser.h


SS_RIGHT
SS_RIGHT 0x02L  winuser.h


SS_SIMPLE
SS_SIMPLE 0x0BL  winuser.h


SS_USERITEM
SS_USERITEM 0x0AL  winuser.h


SS_WHITEFRAME
SS_WHITEFRAME 0x09L  winuser.h


SS_WHITERECT
SS_WHITERECT 0x06L  winuser.h


ST_BEGINSWP
ST_BEGINSWP 0  winuser.h


ST_ENDSWP
ST_ENDSWP 1  winuser.h


STANDARD_RIGHTS_ALL
STANDARD_RIGHTS_ALL (0x001F0000L)  winnt.h


STANDARD_RIGHTS_EXECUTE
STANDARD_RIGHTS_EXECUTE (READ_CONTROL)  winnt.h


STANDARD_RIGHTS_READ
STANDARD_RIGHTS_READ (READ_CONTROL)  winnt.h


STANDARD_RIGHTS_REQUIRED
STANDARD_RIGHTS_REQUIRED (0x000F0000L)  winnt.h


STANDARD_RIGHTS_WRITE
STANDARD_RIGHTS_WRITE (READ_CONTROL)  winnt.h


STARTDOC
STARTDOC 10  wingdi.h


STARTF_RUNFULLSCREEN
STARTF_RUNFULLSCREEN 0x00000020  winbase.h


STILL_ACTIVE
STILL_ACTIVE STATUS_PENDING  winbase.h


STM_MSGMAX
STM_MSGMAX 0x172  winuser.h


STOCK_LAST
STOCK_LAST 16  wingdi.h


STRETCHBLT
STRETCHBLT 2048  wingdi.h


SUBLANG_ENGLISH_EIRE
SUBLANG_ENGLISH_EIRE 0x06  winnt.h


SUBLANG_ENGLISH_NZ
SUBLANG_ENGLISH_NZ 0x05  winnt.h


SUBLANG_GERMAN_AUSTRIAN
SUBLANG_GERMAN_AUSTRIAN 0x03  winnt.h


SUCCESS
SUCCESS 0  raserror.h


SW_MAX
SW_MAX 10  winuser.h


SW_MAXIMIZE
SW_MAXIMIZE 3  winuser.h


SW_NORMAL
SW_NORMAL 1  winuser.h


SW_OTHERUNZOOM
SW_OTHERUNZOOM 4  winuser.h


SW_OTHERZOOM
SW_OTHERZOOM 2  winuser.h


SYMBOL_CHARSET
SYMBOL_CHARSET 2  wingdi.h


SYSTEM_LUID
SYSTEM_LUID { 0x3E7, 0x0 }  winnt.h


SZDDE_ITEM_ITEMLIST
SZDDE_ITEM_ITEMLIST "TopicItemList"  ddeml.h


SZDDESYS_ITEM_FORMATS
SZDDESYS_ITEM_FORMATS "Formats"  ddeml.h


SZDDESYS_ITEM_HELP
SZDDESYS_ITEM_HELP "Help"  ddeml.h


SZDDESYS_ITEM_RTNMSG
SZDDESYS_ITEM_RTNMSG "ReturnMessage"  ddeml.h


SZDDESYS_ITEM_STATUS
SZDDESYS_ITEM_STATUS "Status"  ddeml.h


SZDDESYS_ITEM_SYSITEMS
SZDDESYS_ITEM_SYSITEMS "SysItems"  ddeml.h


SZDDESYS_ITEM_TOPICS
SZDDESYS_ITEM_TOPICS "Topics"  ddeml.h


SZDDESYS_TOPIC
SZDDESYS_TOPIC "System"  ddeml.h


TA_MASK
TA_MASK (TA_BASELINE+TA_CENTER+TA_UPDATECP)  wingdi.h


TAPE_DRIVE_EOT_WZ_SIZE
TAPE_DRIVE_EOT_WZ_SIZE 0x00002000  winnt.h


TAPE_DRIVE_ERASE_IMMEDIATE
TAPE_DRIVE_ERASE_IMMEDIATE 0x00000080  winnt.h


TAPE_DRIVE_FORMAT
TAPE_DRIVE_FORMAT 0xA0000000  winnt.h


TAPE_DRIVE_FORMAT_IMMEDIATE
TAPE_DRIVE_FORMAT_IMMEDIATE 0xC0000000  winnt.h


TAPE_DRIVE_HIGH_FEATURES
TAPE_DRIVE_HIGH_FEATURES 0x80000000  winnt.h


TAPE_DRIVE_LOAD_UNLD_IMMED
TAPE_DRIVE_LOAD_UNLD_IMMED 0x80000020  winnt.h


TAPE_DRIVE_LOCK_UNLK_IMMED
TAPE_DRIVE_LOCK_UNLK_IMMED 0x80000080  winnt.h


TAPE_DRIVE_RESERVED_BIT
TAPE_DRIVE_RESERVED_BIT 0x80000000  winnt.h


TAPE_DRIVE_REWIND_IMMEDIATE
TAPE_DRIVE_REWIND_IMMEDIATE 0x80000008  winnt.h


TAPE_DRIVE_SET_EOT_WZ_SIZE
TAPE_DRIVE_SET_EOT_WZ_SIZE 0x00400000  winnt.h


TAPE_DRIVE_SPACE_IMMEDIATE
TAPE_DRIVE_SPACE_IMMEDIATE 0x80800000  winnt.h


TAPE_DRIVE_TENSION_IMMED
TAPE_DRIVE_TENSION_IMMED 0x80000040  winnt.h


TAPE_DRIVE_WRITE_MARK_IMMED
TAPE_DRIVE_WRITE_MARK_IMMED 0x90000000  winnt.h


TAPE_FORMAT
TAPE_FORMAT 5L  winnt.h


TAPE_PSEUDO_LOGICAL_BLOCK
TAPE_PSEUDO_LOGICAL_BLOCK 3L  winnt.h


TAPE_PSEUDO_LOGICAL_POSITION
TAPE_PSEUDO_LOGICAL_POSITION 2L  winnt.h


TC_CP_STROKE
TC_CP_STROKE 0x00000004  wingdi.h


TC_CR_90
TC_CR_90 0x00000008  wingdi.h


TC_CR_ANY
TC_CR_ANY 0x00000010  wingdi.h


TC_EA_DOUBLE
TC_EA_DOUBLE 0x00000200  wingdi.h


TC_GP_TRAP
TC_GP_TRAP 2  winbase.h


TC_HARDERR
TC_HARDERR 1  winbase.h


TC_IA_ABLE
TC_IA_ABLE 0x00000400  wingdi.h


TC_NORMAL
TC_NORMAL 0  winbase.h


TC_OP_CHARACTER
TC_OP_CHARACTER 0x00000001  wingdi.h


TC_OP_STROKE
TC_OP_STROKE 0x00000002  wingdi.h


TC_RA_ABLE
TC_RA_ABLE 0x00002000  wingdi.h


TC_RESERVED
TC_RESERVED 0x00008000  wingdi.h


TC_SA_CONTIN
TC_SA_CONTIN 0x00000100  wingdi.h


TC_SA_DOUBLE
TC_SA_DOUBLE 0x00000040  wingdi.h


TC_SA_INTEGER
TC_SA_INTEGER 0x00000080  wingdi.h


TC_SCROLLBLT
TC_SCROLLBLT 0x00010000  wingdi.h


TC_SF_X_YINDEP
TC_SF_X_YINDEP 0x00000020  wingdi.h


TC_SIGNAL
TC_SIGNAL 3  winbase.h


TC_SO_ABLE
TC_SO_ABLE 0x00001000  wingdi.h


TC_UA_ABLE
TC_UA_ABLE 0x00000800  wingdi.h


TC_VA_ABLE
TC_VA_ABLE 0x00004000  wingdi.h


TCP_NODELAY
TCP_NODELAY 0x0001  winsock.h


THREAD_BASE_PRIORITY_IDLE
THREAD_BASE_PRIORITY_IDLE -15  winnt.h


THREAD_BASE_PRIORITY_LOWRT
THREAD_BASE_PRIORITY_LOWRT 15  winnt.h


THREAD_BASE_PRIORITY_MAX
THREAD_BASE_PRIORITY_MAX 2  winnt.h


THREAD_BASE_PRIORITY_MIN
THREAD_BASE_PRIORITY_MIN -2  winnt.h


THREAD_DIRECT_IMPERSONATION
THREAD_DIRECT_IMPERSONATION (0x0200)  winnt.h


THREAD_IMPERSONATE
THREAD_IMPERSONATE (0x0100)  winnt.h


THREAD_PRIORITY_ABOVE_NORMAL
THREAD_PRIORITY_ABOVE_NORMAL (THREAD_PRIORITY_HIGHEST-1)  winbase.h


THREAD_PRIORITY_BELOW_NORMAL
THREAD_PRIORITY_BELOW_NORMAL (THREAD_PRIORITY_LOWEST+1)  winbase.h


THREAD_PRIORITY_ERROR_RETURN
THREAD_PRIORITY_ERROR_RETURN (MAXLONG)  winbase.h


THREAD_PRIORITY_HIGHEST
THREAD_PRIORITY_HIGHEST THREAD_BASE_PRIORITY_MAX  winbase.h


THREAD_PRIORITY_IDLE
THREAD_PRIORITY_IDLE THREAD_BASE_PRIORITY_IDLE  winbase.h


THREAD_PRIORITY_LOWEST
THREAD_PRIORITY_LOWEST THREAD_BASE_PRIORITY_MIN  winbase.h


THREAD_PRIORITY_NORMAL
THREAD_PRIORITY_NORMAL 0  winbase.h


THREAD_PRIORITY_TIME_CRITICAL
THREAD_PRIORITY_TIME_CRITICAL THREAD_BASE_PRIORITY_LOWRT  winbase.h


THREAD_SET_THREAD_TOKEN
THREAD_SET_THREAD_TOKEN (0x0080)  winnt.h


TIME_FORCE24HOURFORMAT
TIME_FORCE24HOURFORMAT 0x00000008  winnls.h


TIME_NOMINUTESORSECONDS
TIME_NOMINUTESORSECONDS 0x00000001  winnls.h


TIME_NOSECONDS
TIME_NOSECONDS 0x00000002  winnls.h


TIME_NOTIMEMARKER
TIME_NOTIMEMARKER 0x00000004  winnls.h


TIME_ZONE_ID_INVALID
TIME_ZONE_ID_INVALID (DWORD)0xFFFFFFFF  winbase.h


TIMEOUT_ASYNC
TIMEOUT_ASYNC 0xFFFFFFFF  ddeml.h


TIMERR_BASE
TIMERR_BASE 96  mmsystem.h


TIMERR_NOCANDO
TIMERR_NOCANDO (TIMERR_BASE+1)  mmsystem.h


TIMERR_NOERROR
TIMERR_NOERROR (0)  mmsystem.h


TIMERR_STRUCT
TIMERR_STRUCT (TIMERR_BASE+33)  mmsystem.h


TITLEBARNAMELEN
TITLEBARNAMELEN 40  scrnsave.h


TLS_MINIMUM_AVAILABLE
TLS_MINIMUM_AVAILABLE 64  winnt.h


TLS_OUT_OF_INDEXES
TLS_OUT_OF_INDEXES (DWORD)0xFFFFFFFF  winbase.h


TMPF_DEVICE
TMPF_DEVICE 0x08  wingdi.h


TMPF_FIXED_PITCH
TMPF_FIXED_PITCH 0x01  wingdi.h


TMPF_TRUETYPE
TMPF_TRUETYPE 0x04  wingdi.h


TMPF_VECTOR
TMPF_VECTOR 0x02  wingdi.h


TOKEN_SOURCE_LENGTH
TOKEN_SOURCE_LENGTH 8  winnt.h


TRANSFORM_CTM
TRANSFORM_CTM 4107  wingdi.h


TRUETYPE_FONTTYPE
TRUETYPE_FONTTYPE 0x004  wingdi.h


TRY_AGAIN
TRY_AGAIN WSATRY_AGAIN  winsock.h


TT_AVAILABLE
TT_AVAILABLE 0x0001  wingdi.h


TT_ENABLED
TT_ENABLED 0x0002  wingdi.h


TT_POLYGON_TYPE
TT_POLYGON_TYPE 24  wingdi.h


UNCLEN
UNCLEN (CNLEN+2)  nddeapi.h


VALID_INHERIT_FLAGS
VALID_INHERIT_FLAGS (0xF)  winnt.h


VALID_NTFT
VALID_NTFT 0xC0  winioctl.h


VARIABLE_PITCH
VARIABLE_PITCH 2  wingdi.h


VFT2_DRV_COMM
VFT2_DRV_COMM 0x0000000AL  winver.h


VIF_CANNOTDELETECUR
VIF_CANNOTDELETECUR 0x00004000L  winver.h


VK_ADD
VK_ADD 0x6B  winuser.h


VK_ATTN
VK_ATTN 0xF6  winuser.h


VK_BACK
VK_BACK 0x08  winuser.h


VK_CANCEL
VK_CANCEL 0x03  winuser.h


VK_CAPITAL
VK_CAPITAL 0x14  winuser.h


VK_CLEAR
VK_CLEAR 0x0C  winuser.h


VK_CONTROL
VK_CONTROL 0x11  winuser.h


VK_CRSEL
VK_CRSEL 0xF7  winuser.h


VK_DECIMAL
VK_DECIMAL 0x6E  winuser.h


VK_DELETE
VK_DELETE 0x2E  winuser.h


VK_DIVIDE
VK_DIVIDE 0x6F  winuser.h


VK_DOWN
VK_DOWN 0x28  winuser.h


VK_END
VK_END 0x23  winuser.h


VK_EREOF
VK_EREOF 0xF9  winuser.h


VK_ESCAPE
VK_ESCAPE 0x1B  winuser.h


VK_EXECUTE
VK_EXECUTE 0x2B  winuser.h


VK_EXSEL
VK_EXSEL 0xF8  winuser.h


VK_F1
VK_F1 0x70  winuser.h


VK_F10
VK_F10 0x79  winuser.h


VK_F11
VK_F11 0x7A  winuser.h


VK_F12
VK_F12 0x7B  winuser.h


VK_F13
VK_F13 0x7C  winuser.h


VK_F14
VK_F14 0x7D  winuser.h


VK_F15
VK_F15 0x7E  winuser.h


VK_F16
VK_F16 0x7F  winuser.h


VK_F17
VK_F17 0x80  winuser.h


VK_F18
VK_F18 0x81  winuser.h


VK_F19
VK_F19 0x82  winuser.h


VK_F2
VK_F2 0x71  winuser.h


VK_F20
VK_F20 0x83  winuser.h


VK_F21
VK_F21 0x84  winuser.h


VK_F22
VK_F22 0x85  winuser.h


VK_F23
VK_F23 0x86  winuser.h


VK_F24
VK_F24 0x87  winuser.h


VK_F3
VK_F3 0x72  winuser.h


VK_F4
VK_F4 0x73  winuser.h


VK_F5
VK_F5 0x74  winuser.h


VK_F6
VK_F6 0x75  winuser.h


VK_F7
VK_F7 0x76  winuser.h


VK_F8
VK_F8 0x77  winuser.h


VK_F9
VK_F9 0x78  winuser.h


VK_HELP
VK_HELP 0x2F  winuser.h


VK_HOME
VK_HOME 0x24  winuser.h


VK_INSERT
VK_INSERT 0x2D  winuser.h


VK_LBUTTON
VK_LBUTTON 0x01  winuser.h


VK_LCONTROL
VK_LCONTROL 0xA2  winuser.h


VK_LEFT
VK_LEFT 0x25  winuser.h


VK_LMENU
VK_LMENU 0xA4  winuser.h


VK_LSHIFT
VK_LSHIFT 0xA0  winuser.h


VK_MBUTTON
VK_MBUTTON 0x04  winuser.h


VK_MENU
VK_MENU 0x12  winuser.h


VK_MULTIPLY
VK_MULTIPLY 0x6A  winuser.h


VK_NEXT
VK_NEXT 0x22  winuser.h


VK_NONAME
VK_NONAME 0xFC  winuser.h


VK_NUMLOCK
VK_NUMLOCK 0x90  winuser.h


VK_NUMPAD0
VK_NUMPAD0 0x60  winuser.h


VK_NUMPAD1
VK_NUMPAD1 0x61  winuser.h


VK_NUMPAD2
VK_NUMPAD2 0x62  winuser.h


VK_NUMPAD3
VK_NUMPAD3 0x63  winuser.h


VK_NUMPAD4
VK_NUMPAD4 0x64  winuser.h


VK_NUMPAD5
VK_NUMPAD5 0x65  winuser.h


VK_NUMPAD6
VK_NUMPAD6 0x66  winuser.h


VK_NUMPAD7
VK_NUMPAD7 0x67  winuser.h


VK_NUMPAD8
VK_NUMPAD8 0x68  winuser.h


VK_NUMPAD9
VK_NUMPAD9 0x69  winuser.h


VK_OEM_CLEAR
VK_OEM_CLEAR 0xFE  winuser.h


VK_PA1
VK_PA1 0xFD  winuser.h


VK_PAUSE
VK_PAUSE 0x13  winuser.h


VK_PLAY
VK_PLAY 0xFA  winuser.h


VK_PRINT
VK_PRINT 0x2A  winuser.h


VK_PRIOR
VK_PRIOR 0x21  winuser.h


VK_RBUTTON
VK_RBUTTON 0x02  winuser.h


VK_RCONTROL
VK_RCONTROL 0xA3  winuser.h


VK_RETURN
VK_RETURN 0x0D  winuser.h


VK_RIGHT
VK_RIGHT 0x27  winuser.h


VK_RMENU
VK_RMENU 0xA5  winuser.h


VK_RSHIFT
VK_RSHIFT 0xA1  winuser.h


VK_SCROLL
VK_SCROLL 0x91  winuser.h


VK_SELECT
VK_SELECT 0x29  winuser.h


VK_SEPARATOR
VK_SEPARATOR 0x6C  winuser.h


VK_SHIFT
VK_SHIFT 0x10  winuser.h


VK_SNAPSHOT
VK_SNAPSHOT 0x2C  winuser.h


VK_SPACE
VK_SPACE 0x20  winuser.h


VK_SUBTRACT
VK_SUBTRACT 0x6D  winuser.h


VK_TAB
VK_TAB 0x09  winuser.h


VK_UP
VK_UP 0x26  winuser.h


VK_ZOOM
VK_ZOOM 0xFB  winuser.h


VOID
VOID void  winnt.h


VOS__BASE
VOS__BASE 0x00000000L  winver.h


VS_FFI_FILEFLAGSMASK
VS_FFI_FILEFLAGSMASK 0x0000003FL  winver.h


VS_FFI_SIGNATURE
VS_FFI_SIGNATURE 0xFEEF04BDL  winver.h


VS_FFI_STRUCVERSION
VS_FFI_STRUCVERSION 0x00010000L  winver.h


VS_FILE_INFO
VS_FILE_INFO RT_VERSION  winver.h


VS_USER_DEFINED
VS_USER_DEFINED 100  winver.h


VS_VERSION_INFO
VS_VERSION_INFO 1  winver.h


VTA_BOTTOM
VTA_BOTTOM TA_RIGHT  wingdi.h


VTA_LEFT
VTA_LEFT TA_BOTTOM  wingdi.h


VTA_RIGHT
VTA_RIGHT TA_TOP  wingdi.h


VTA_TOP
VTA_TOP TA_LEFT  wingdi.h


WAIT_FAILED
WAIT_FAILED (DWORD)0xFFFFFFFF  winbase.h


WAIT_IO_COMPLETION
WAIT_IO_COMPLETION STATUS_USER_APC  winbase.h


WAIT_TIMEOUT
WAIT_TIMEOUT STATUS_TIMEOUT  winbase.h


WARNING_MSG_ALIAS_NOT_ADDED
WARNING_MSG_ALIAS_NOT_ADDED (RASBASE+44)  raserror.h


WAVE_INVALIDFORMAT
WAVE_INVALIDFORMAT 0x00000000  mmsystem.h


WAVECAPS_SYNC
WAVECAPS_SYNC 0x00000010  mmsystem.h


WAVERR_BASE
WAVERR_BASE 32  mmsystem.h


WAVERR_LASTERROR
WAVERR_LASTERROR (WAVERR_BASE + 3)  mmsystem.h


WAVERR_SYNC
WAVERR_SYNC (WAVERR_BASE + 3)  mmsystem.h


WC_DEFWINDOWPROC
WC_DEFWINDOWPROC 3  winuser.h


WC_DRAWCAPTION
WC_DRAWCAPTION 7  winuser.h


WC_INIT
WC_INIT 1  winuser.h


WC_MINMAX
WC_MINMAX 4  winuser.h


WC_MOVE
WC_MOVE 5  winuser.h


WC_SIZE
WC_SIZE 6  winuser.h


WC_SWP
WC_SWP 2  winuser.h


WH_FOREGROUNDIDLE
WH_FOREGROUNDIDLE 11  winuser.h


WH_MAX
WH_MAX 11  winuser.h


WH_MIN
WH_MIN (-1)  winuser.h


WHDR_INQUEUE
WHDR_INQUEUE 0x00000010  mmsystem.h


WIM_CLOSE
WIM_CLOSE MM_WIM_CLOSE  mmsystem.h


WIM_DATA
WIM_DATA MM_WIM_DATA  mmsystem.h


WIM_OPEN
WIM_OPEN MM_WIM_OPEN  mmsystem.h


WIN31_CLASS
WIN31_CLASS NULL  winreg.h


WINAPI
WINAPI __stdcall  windef.h


WINAPI
WINAPI nothing  windef.h


WINAPIV
WINAPIV __cdecl  windef.h


WINAPIV
WINAPIV nothing  windef.h


WINDOW_BUFFER_SIZE_EVENT
WINDOW_BUFFER_SIZE_EVENT 0x0004  wincon.h


WINSTA_ACCESSCLIPBOARD
WINSTA_ACCESSCLIPBOARD 0x0004L  winuser.h


WINSTA_ACCESSGLOBALATOMS
WINSTA_ACCESSGLOBALATOMS 0x0020L  winuser.h


WINSTA_CREATEDESKTOP
WINSTA_CREATEDESKTOP 0x0008L  winuser.h


WINSTA_ENUMDESKTOPS
WINSTA_ENUMDESKTOPS 0x0001L  winuser.h


WINSTA_ENUMERATE
WINSTA_ENUMERATE 0x0100L  winuser.h


WINSTA_EXITWINDOWS
WINSTA_EXITWINDOWS 0x0040L  winuser.h


WINSTA_READATTRIBUTES
WINSTA_READATTRIBUTES 0x0002L  winuser.h


WINSTA_READSCREEN
WINSTA_READSCREEN 0x0200L  winuser.h


WINSTA_WRITEATTRIBUTES
WINSTA_WRITEATTRIBUTES 0x0010L  winuser.h


WINVER
WINVER 0x030A  winuser.h


WRITE_DAC
WRITE_DAC (0x00040000L)  winnt.h


WRITE_OWNER
WRITE_OWNER (0x00080000L)  winnt.h


WS_EX_TRANSPARENT
WS_EX_TRANSPARENT 0x00000020L  winuser.h


WS_GT
WS_GT (WS_GROUP | WS_TABSTOP)  scrnsave.h


WS_ICONIC
WS_ICONIC WS_MINIMIZE  winuser.h


WS_SIZEBOX
WS_SIZEBOX WS_THICKFRAME  winuser.h


WS_TILED
WS_TILED WS_OVERLAPPED  winuser.h


WS_TILEDWINDOW
WS_TILEDWINDOW WS_OVERLAPPEDWINDOW  winuser.h


WSABASEERR
WSABASEERR 10000  winsock.h


WSADESCRIPTION_LEN
WSADESCRIPTION_LEN 256  winsock.h


WSAEACCES
WSAEACCES (WSABASEERR+13)  winsock.h


WSAEADDRINUSE
WSAEADDRINUSE (WSABASEERR+48)  winsock.h


WSAEADDRNOTAVAIL
WSAEADDRNOTAVAIL (WSABASEERR+49)  winsock.h


WSAEAFNOSUPPORT
WSAEAFNOSUPPORT (WSABASEERR+47)  winsock.h


WSAEALREADY
WSAEALREADY (WSABASEERR+37)  winsock.h


WSAEBADF
WSAEBADF (WSABASEERR+9)  winsock.h


WSAECONNABORTED
WSAECONNABORTED (WSABASEERR+53)  winsock.h


WSAECONNREFUSED
WSAECONNREFUSED (WSABASEERR+61)  winsock.h


WSAECONNRESET
WSAECONNRESET (WSABASEERR+54)  winsock.h


WSAEDESTADDRREQ
WSAEDESTADDRREQ (WSABASEERR+39)  winsock.h


WSAEDQUOT
WSAEDQUOT (WSABASEERR+69)  winsock.h


WSAEFAULT
WSAEFAULT (WSABASEERR+14)  winsock.h


WSAEHOSTDOWN
WSAEHOSTDOWN (WSABASEERR+64)  winsock.h


WSAEHOSTUNREACH
WSAEHOSTUNREACH (WSABASEERR+65)  winsock.h


WSAEINPROGRESS
WSAEINPROGRESS (WSABASEERR+36)  winsock.h


WSAEINTR
WSAEINTR (WSABASEERR+4)  winsock.h


WSAEINVAL
WSAEINVAL (WSABASEERR+22)  winsock.h


WSAEISCONN
WSAEISCONN (WSABASEERR+56)  winsock.h


WSAELOOP
WSAELOOP (WSABASEERR+62)  winsock.h


WSAEMFILE
WSAEMFILE (WSABASEERR+24)  winsock.h


WSAEMSGSIZE
WSAEMSGSIZE (WSABASEERR+40)  winsock.h


WSAENAMETOOLONG
WSAENAMETOOLONG (WSABASEERR+63)  winsock.h


WSAENETDOWN
WSAENETDOWN (WSABASEERR+50)  winsock.h


WSAENETRESET
WSAENETRESET (WSABASEERR+52)  winsock.h


WSAENETUNREACH
WSAENETUNREACH (WSABASEERR+51)  winsock.h


WSAENOBUFS
WSAENOBUFS (WSABASEERR+55)  winsock.h


WSAENOPROTOOPT
WSAENOPROTOOPT (WSABASEERR+42)  winsock.h


WSAENOTCONN
WSAENOTCONN (WSABASEERR+57)  winsock.h


WSAENOTEMPTY
WSAENOTEMPTY (WSABASEERR+66)  winsock.h


WSAENOTSOCK
WSAENOTSOCK (WSABASEERR+38)  winsock.h


WSAEOPNOTSUPP
WSAEOPNOTSUPP (WSABASEERR+45)  winsock.h


WSAEPFNOSUPPORT
WSAEPFNOSUPPORT (WSABASEERR+46)  winsock.h


WSAEPROCLIM
WSAEPROCLIM (WSABASEERR+67)  winsock.h


WSAEPROTONOSUPPORT
WSAEPROTONOSUPPORT (WSABASEERR+43)  winsock.h


WSAEPROTOTYPE
WSAEPROTOTYPE (WSABASEERR+41)  winsock.h


WSAEREMOTE
WSAEREMOTE (WSABASEERR+71)  winsock.h


WSAESHUTDOWN
WSAESHUTDOWN (WSABASEERR+58)  winsock.h


WSAESOCKTNOSUPPORT
WSAESOCKTNOSUPPORT (WSABASEERR+44)  winsock.h


WSAESTALE
WSAESTALE (WSABASEERR+70)  winsock.h


WSAETIMEDOUT
WSAETIMEDOUT (WSABASEERR+60)  winsock.h


WSAETOOMANYREFS
WSAETOOMANYREFS (WSABASEERR+59)  winsock.h


WSAEUSERS
WSAEUSERS (WSABASEERR+68)  winsock.h


WSAEWOULDBLOCK
WSAEWOULDBLOCK (WSABASEERR+35)  winsock.h


WSAHOST_NOT_FOUND
WSAHOST_NOT_FOUND (WSABASEERR+1001)  winsock.h


WSANO_ADDRESS
WSANO_ADDRESS WSANO_DATA  winsock.h


WSANO_DATA
WSANO_DATA (WSABASEERR+1004)  winsock.h


WSANO_RECOVERY
WSANO_RECOVERY (WSABASEERR+1003)  winsock.h


WSANOTINITIALISED
WSANOTINITIALISED (WSABASEERR+93)  winsock.h


WSASYS_STATUS_LEN
WSASYS_STATUS_LEN 128  winsock.h


WSASYSNOTREADY
WSASYSNOTREADY (WSABASEERR+91)  winsock.h


WSATRY_AGAIN
WSATRY_AGAIN (WSABASEERR+1002)  winsock.h


WSAVERNOTSUPPORTED
WSAVERNOTSUPPORTED (WSABASEERR+92)  winsock.h


WVR_ALIGNBOTTOM
WVR_ALIGNBOTTOM 0x0040  winuser.h


WVR_ALIGNLEFT
WVR_ALIGNLEFT 0x0020  winuser.h


WVR_ALIGNRIGHT
WVR_ALIGNRIGHT 0x0080  winuser.h


WVR_ALIGNTOP
WVR_ALIGNTOP 0x0010  winuser.h


WVR_HREDRAW
WVR_HREDRAW 0x0100  winuser.h


WVR_VREDRAW
WVR_VREDRAW 0x0200  winuser.h


XCLASS_MASK
XCLASS_MASK 0xFC00  ddeml.h


AbortProc
AbortProc (Win32)

BOOL CALLBACK AbortProc(hdc, iError)

HDC hdc;	/* handle of device context	*/
int iError;	/* error value	*/

The AbortProc function is an application-defined callback function that is called when a print job is to be canceled during spooling.

Parameter	Description

hdc	Identifies the device context.

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.

Returns

The callback function should return TRUE to continue the print job or FALSE to cancel the print job.

Comments

An application installs this callback function by calling the SetAbortProc function. AbortProc 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


CallWndProc
CallWndProc (Win32)

LRESULT CALLBACK CallWndProc(nCode, wParam, lParam)

int nCode;	/* hook code	*/
WPARAM wParam;	/* current-process flag	*/
LPARAM lParam;	/* address of structure with message data	*/

The CallWndProc hook procedure is an application-defined or library-defined callback function 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.

Parameter	Description

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 CWPSTRUCT structure that contains details about the message.

Returns

The return value should be zero.

Comments

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.

CallWndProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, SendMessage, SetWindowsHookEx, CWPSTRUCT


CBTProc
CBTProc (Win32)

LRESULT CALLBACK CBTProc(nCode, wParam, lParam)

int nCode;	/* hook code	*/
WPARAM wParam;	/* depends on hook code	*/
LPARAM lParam;	/* depends on hook code	*/

The CBTProc hook procedure is an application-defined or library-defined callback function 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.

Parameter	Description

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

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 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 Comments section.

lParam	Depends on the nCode parameter. For details, see the following Comments section.

Returns

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

Comments

The hook procedure should not install a WH_JOURNALPLAYBACK 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 of the window about to be activated.	Specifies a long pointer to a CBTACTIVATESTRUCT structure containing the handle of 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 of the window for which the mouse message is intended. For a list of hit-test codes, see the description of the WM_NCHITTEST message.
HCBT_CREATEWND	Specifies the handle of the new window.	Specifies a long pointer to a CBT_CREATEWND structure containing initialization parameters for the window.
HCBT_DESTROYWND	Specifies the handle of 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. For more information, see the description of the WM_KEYUP or WM_KEYDOWN message.
HCBT_MINMAX	Specifies the handle of 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 description of the ShowWindow function. The high-order word is undefined.
HCBT_MOVESIZE	Specifies the handle of the window to be moved or sized.	Specifies a long pointer to a RECT structure containing the coordinates of the window.
HCBT_QS	Is undefined and must be zero.	Is undefined and must be zero.
HCBT_SETFOCUS	Specifies the handle of the window gaining the keyboard focus.	Specifies the handle of the window losing the keyboard focus.
HCBT_SYSCOMMAND	Specifies a system-command value (SC_) specifying the system command. Formore information about system-command values, see the description of the WM_SYSCOMMAND message.	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, SetWindowsHookEx, CBTACTIVATESTRUCT, CBT_CREATEWND, RECT


CPlApplet
CPlApplet (Win32)

#include <cpl.h>

LONG APIENTRY CPlApplet(hwndCPl, uMsg, lParam1, lParam2)

HWND hwndCPl;	/* handle of Control Panel window	*/
UINT uMsg;	/* message	*/
LONG lParam1;	/* first message parameter	*/
LONG lParam2;	/* second message parameter	*/

The CPlApplet function is a library-defined callback function that serves as the entry point for a Windows Control Panel dynamic-link library (DLL).

Parameter	Description

hwndCPl	Identifies the main Control Panel window.

uMsg	Specifies the message being sent to the DLL.

lParam1	Specifies additional message-dependent information.

lParam2	Specifies additional message-dependent information.

Returns

The return value depends on the message.

Comments

Use the hwndCPl parameter for dialog boxes or other windows that require a handle of a parent window.


DialogProc
DialogProc (Win32)

BOOL CALLBACK DialogProc(hwndDlg, uMsg, wParam, lParam)

HWND hwndDlg;	/* handle of dialog box	*/
UINT uMsg;	/* message	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The DialogProc function is an application-defined callback function that processes messages sent to a modal or modeless dialog box.

Parameter	Description

hwndDlg	Identifies the dialog box.

uMsg	Specifies the message.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

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.

Comments

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


DdeCallback
DdeCallback (Win32)

HDDEDATA CALLBACK DdeCallback(uType, uFmt, hconv, hsz1, hsz2, hdata, dwData1, dwData2)

UINT uType;	/* transaction type	*/
UINT uFmt;	/* clipboard data format	*/
HCONV hconv;	/* handle of the conversation	*/
HSZ hsz1;	/* handle of a string	*/
HSZ hsz2;	/* handle of a string	*/
HDDEDATA hdata;	/* handle of a global memory object	*/
DWORD dwData1;	/* transaction-specific data	*/
DWORD dwData2;	/* transaction-specific data	*/

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.

Parameter	Description

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.

Value	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 types consist of the following:

XTYP_ADVSTART

XTYP_CONNECT

XCLASS_DATA	A DDE callback function should return a DDE handle, CBR_BLOCK, or NULL when it finishes processing a transaction that belongs to this class. The XCLASS_DATA transaction types consist of the following:

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 types consist of the following:

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 types consist of the following:

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. See the description of the transaction type for the meaning of this parameter.

hsz2	Identifies a string. The meaning of this parameter depends on the type of the current transaction. See the description of the transaction type for the meaning of this parameter.

hdata	Identifies DDE data. The meaning of this parameter depends on the type of the current transaction. See the description of the transaction type for the meaning of this parameter.

dwData1	Specifies transaction-specific data. See the description of the transaction type for the meaning of this parameter.

dwData2	Specifies transaction-specific data. See the description of the transaction type for the meaning of this parameter.

Returns

The return value depends on the transaction class. See descriptions of the individual transaction types for the return values.

Comments

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


DebugProc
DebugProc (Win32)

LRESULT CALLBACK DebugProc(nCode, wParam, lParam)

int nCode;	/* hook code	*/
WPARAM wParam;	/* type of hook about to be called	*/
LPARAM lParam;	/* address of structure with debugging information	*/

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.

Parameter	Description

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

For a full description of this structure, see the <Microsoft Win32 Programmer's Reference, Volume 5>.

Returns

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.

Comments

An application installs this hook procedure by specifying the WH_DEBUG hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

CallWndProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, SetWindowsHookEx, DEBUGHOOKINFO


DllEntryPoint
DllEntryPoint (Win32)

BOOL WINAPI DllEntryPoint(hinstDLL, fdwReason, lpvReserved)

HINSTANCE hinstDLL;	/* handle of DLL module	*/
DWORD fdwReason;	/* why function was called	*/
LPVOID lpvReserved;	/* reserved; must be NULL	*/

The DllEntryPoint function is an optional method of entry into a Dynamic-Link Library (DLL) that, if provided, 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 on the linker command line by the hyphen entry switch.

Parameter	Description

hinstDLL	Supplies a handle to the DLL. This handle can be used in subsequent calls to the GetModuleFileName function and other module functions.

fdwReason	Supplies a flag indicating why the DLL entry routine is being called. This value can be one of the following values:

Value	Meaning

DLL_PROCESS_ATTACH

Indicates the DLL is attaching to the address space of the current process as a result of the process starting up or 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 a DLL_PROCESS_ATTACH flag, the system calls the DLL's entrypoint 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 the current process is creating a new thread. When this occurs, the system calls the entrypoint 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. The thread calling the DLL entrypoint with the DLL_PROCESS_ATTACH flag does not call the DLL entrypoint with the DLL_THREAD_ATTACH flag.

Note that a DLL's entrypoint is called with this flag 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 entrypoint of the newly loaded DLL.

DLL_THREAD_DETACH

Indicates 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 entrypoint of all currently loaded DLLs with this flag value. The call is made in the context of the exiting thread. There are cases in which the entrypoint is invoked for a terminating thread even if the DLL never attached to the thread. For example, the entrypoint was never called with the DLL_THREAD_ATTACH flag in the context of the thread. This can occur in two situations:

The thread was the initial thread in the process so the system called the entrypoint with the DLL_PROCESS_ATTACH flag.

The thread was already running when a LoadLibrary call was made, so the system never called the entrypoint function for it.

DLL_PROCESS_DETACH

Indicates the DLL is detaching from the address space of the calling process. This results from either a clean process exit, or from a FreeLibrary call. 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 FreeLibrary, the operating system does not call the DLL's entrypoint with the DLL_THREAD_DETACH flag for the individual threads of the process. The only notification given to the DLL is the 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 via FreeLibrary, and non-NULL if DllEntryPoint has been called during process termination.

Returns

When the system calls the DllEntryPoint function with the DLL_PROCESS_ATTACH flag, the function returns TRUE if it succeeds or FALSE if the initialization fails. If the return value is FALSE when the DllEntryPoint was invoked because the process called the LoadLibrary function, LoadLibrary returns NULL. If the return value is FALSE when the DllEntryPoint is called during process initialization, the process terminates with an error. To get extended error information, use the GetLastError function.

When the system calls the DllEntryPoint function with any flag other than DLL_PROCESS_ATTACH, the return value is ignored.

See Also

FreeLibrary, GetModuleFileName, LoadLibrary, TlsAlloc


EditWordBreakProc
EditWordBreakProc (Win32)

int CALLBACK EditWordBreakProc(lpch, ichCurrent, cch, action)

LPTSTR lpch;	/* address of edit text	*/
int ichCurrent;	/* index of starting point	*/
int cch;	/* length in characters of edit text	*/
int action;	/* action to take	*/

An EditWordBreakProc function is an application-defined callback function that the operating system calls whenever a multiline edit control must break a line of text. A value of type EDITWORDBREAKPROC is a pointer to such a function.

Parameter	Description

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.

action	Specifies the action to be taken by the callback function. This parameter can be one of the following values:

Value	Action

WB_LEFT	Look for the beginning of a word to the left of the current position.

WB_RIGHT	Look for the beginning of a word to the right of the current position. (This is useful in right-aligned edit controls.)

WB_ISDELIMITER	Check whether the character at the current position is a delimiter.

Returns

If the action 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.

Comments

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_SETWORDBREAKPROC


EnhMetaFileProc
EnhMetaFileProc (Win32)

int CALLBACK EnhMetaFileProc(hDC, lpHTable, lpEMFR, nObj, lpData)

HDC hDC;	/* handle of device context	*/
HANDLETABLE FAR *lpHTable;	/* address of metafile handle table	*/
ENHMETARECORD FAR *lpEMFR;	/* address of metafile record	*/
int nObj;	/* count of objects	*/
LPARAM lpData;	/* address of optional data	*/

The EnhMetaFileProc function is an application-defined callback function that processes enhanced-format metafile records. This function is called by the EnumEnhMetaFile function.

Parameter	Description

hDC	Identifies an enhanced-metafile device context (DC).

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.

Returns

This function must return a nonzero value to continue enumeration; to stop enumeration, it must return zero.

Comments

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


EnumChildProc
EnumChildProc (Win32)

BOOL CALLBACK EnumChildProc(hwnd, lParam)

HWND hwnd;	/* handle of child window	*/
LPARAM lParam;	/* application-defined value	*/

The EnumChildProc function is an application-defined callback function that receives child window handles as a result of a call to the EnumChildWindows function.

Parameter	Description

hwnd	Identifies a child window of the parent window specified in the EnumChildWindows function.

lParam	Specifies the application-defined value given in the EnumChildWindows function.

Returns

To continue enumeration, the callback function must return TRUE; to stop enumeration, it must return FALSE.

Comments

The callback function can carry out any desired task.

An application must register this callback function by passing its address to the EnumChildWindows function. EnumChildProc is a placeholder for the application-defined function name.

See Also

EnumChildWindows


EnumFontFamProc
EnumFontFamProc (Win32)

int CALLBACK EnumFontFamProc(lpelf, lpntm, FontType, lParam)

ENUMLOGFONT FAR* lpelf;	/* address of logical-font data	*/
NEWTEXTMETRIC FAR* lpntm;	/* address of physical-font data	*/
int FontType;	/* type of font	*/
LPARAM lParam;	/* address of application-defined data	*/

The EnumFontFamProc function is an application-defined callback function that retrieves data describing available fonts.

Parameter	Description

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.

Returns

The return value must be a nonzero value to continue enumeration; to stop enumeration, it must return zero.

Comments

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, LOGFONT, NEWTEXTMETRIC, TEXTMETRIC


EnumFontsProc
EnumFontsProc (Win32)

int CALLBACK EnumFontsProc(lplf, lptm, dwType, lpData)

lplf lplf;	/* address of logical-font data	*/
lptm lptm;	/* address of physical-font data	*/
DWORD dwType;	/* font type	*/
LPARAM lpData;	/* address of application-supplied data	*/

The EnumFontsProc function is an application-defined callback function that processes font data from the EnumFonts function.

Parameter	Description

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-supplied data passed by EnumFonts.

Returns

The return value must be a nonzero value to continue enumeration; to stop enumeration, it must be zero.

Comments

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-supplied function name.

See Also

EnumFonts, LOGFONT, TEXTMETRIC, LOGFONT, TEXTMETRIC


EnumMetaFileProc
EnumMetaFileProc (Win32)

int CALLBACK EnumMetaFileProc(hDC, lpHTable, lpMFR, nObj, lpClientData)

HDC hDC;	/* handle of device context	*/
HANDLETABLE FAR *lpHTable;	/* address of metafile handle table	*/
METARECORD FAR *lpMFR;	/* address of metafile record	*/
int nObj;	/* count of objects	*/
LPARAM lpClientData;	/* address of optional data	*/

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. For Win32 applications, use the EnhMetaFileProc and EnumEnhMetaFile function.

Parameter	Description

hDC	Identifies a Windows-format metafile device context.

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.

Returns

This function must return a nonzero value to continue enumeration; to stop enumeration, it must return zero.

Comments

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

EnumMetaFile


EnumObjectsProc
EnumObjectsProc (Win32)

VOID CALLBACK EnumObjectsProc(lpLogObject, lpData)

LPVOID lpLogObject;	/* address of graphic-object structure	*/
LPARAM lpData;	/* address of application-defined data	*/

The EnumObjectsProc function is an application-defined callback function that processes object data supplied by the EnumObjects function.

Parameter	Description

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.

Returns

This function does not return a value.

Comments

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, LOGBRUSH, LOGPEN


EnumResLangProc
EnumResLangProc (Win32)

BOOL CALLBACK EnumResLangProc(hModule, lpszType, lpszName, wIDLanguage, lParam)

HANDLE hModule;	/* resource-module handle	*/
LPCTSTR lpszType;	/* address of resource type	*/
LPCTSTR lpszName;	/* address of resource name	*/
WORD wIDLanguage;	/* resource language identifier	*/
LONG lParam;	/* application-defined parameter	*/

The EnumResLangProc function is an application-defined callback function that receives resource languages as a result of a call to the EnumResourceLanguages function.

Parameter	Description

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_BITMAP	Bitmap resource

RT_DIALOG	Dialog box

RT_FONT	Font resource

RT_FONTDIR	Font directory resource

RT_MENU	Menu resource

RT_RCDATA	Application-defined resource (raw data)

RT_STRING	String-table entry

RT_MESSAGETABLE	Message-table entry

RT_CURSOR	Hardware-dependent cursor resource

RT_GROUP_CURSOR	Hardware-independent cursor resource

RT_ICON	Hardware-dependent icon resource

RT_GROUP_ICON	Hardware-independent icon resource

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.

lParam	Specifies the application-defined parameter passed to the EnumResourceLanguages function. This parameter can be used in error checking.

Returns

This callback function should return TRUE to continue enumeration; otherwise, it should return FALSE to stop enumeration.

Comments

The EnumResLangProc function is a placeholder for the application-defined or library-defined function name.

See Also

EnumResourceLanguages


EnumResNameProc
EnumResNameProc (Win32)

BOOL CALLBACK EnumResNameProc(hModule, lpszType, lpszName, lParam)

HANDLE hModule;	/* resource-module handle	*/
LPCTSTR lpszType;	/* address of resource type	*/
LPTSTR lpszName;	/* address of resource name	*/
LONG lParam;	/* application-defined parameter	*/

The EnumResNameProc function is an application-defined callback function that receives resource names as a result of a call to the EnumResourceNames function.

Parameter	Description

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_BITMAP	Bitmap resource

RT_DIALOG	Dialog box

RT_FONT	Font resource

RT_FONTDIR	Font directory resource

RT_MENU	Menu resource

RT_RCDATA	Application-defined resource (raw data)

RT_STRING	String-table entry

RT_MESSAGETABLE	Message-table entry

RT_CURSOR	Hardware-dependent cursor resource

RT_GROUP_CURSOR	Hardware-independent cursor resource

RT_ICON	Hardware-dependent icon resource

RT_GROUP_ICON	Hardware-independent icon resource

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.

Returns

This callback function should return TRUE to continue enumeration; otherwise, it should return FALSE to stop enumeration.

Comments

The EnumResNameProc function is a placeholder for the application-defined or library-defined function name.

See Also

EnumResourceNames


EnumResTypeProc
EnumResTypeProc (Win32)

BOOL CALLBACK EnumResTypeProc(hModule, lpszType, lParam)

HANDLE hModule;	/* resource-module handle	*/
LPTSTR lpszType;	/* address of resource type	*/
LONG lParam;	/* application-defined parameter	*/

The EnumResTypeProc function is an application-defined callback function that receives resource types as a result of a call to the EnumResourceTypes function.

Parameter	Description

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_BITMAP	Bitmap resource

RT_DIALOG	Dialog box

RT_FONT	Font resource

RT_FONTDIR	Font directory resource

RT_MENU	Menu resource

RT_RCDATA	Application-defined resource (raw data)

RT_STRING	String-table entry

RT_MESSAGETABLE	Message-table entry

RT_CURSOR	Hardware-dependent cursor resource

RT_GROUP_CURSOR	Hardware-independent cursor resource

RT_ICON	Hardware-dependent icon resource

RT_GROUP_ICON	Hardware-independent icon resource

RT_VERSION	Version resource

lParam	Specifies the application-defined parameter passed to the EnumResourceTypes function. This parameter can be used in error checking.

Returns

The callback function should return TRUE to continue enumeration; otherwise, it should be FALSE to stop enumeration.

Comments

The EnumResTypeProc function is a placeholder for the application-defined or library-defined function name.

See Also

EnumResourceTypes


EnumThreadWndProc
EnumThreadWndProc (Win32)

BOOL CALLBACK EnumThreadWndProc(hwnd, lParam)

HWND hwnd;	/* handle of window	*/
LPARAM lParam;	/* application-defined value	*/

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.

Parameter	Description

hwnd	Identifies a window associated with the thread specified in the EnumThreadWindows function.

lParam	Specifies the application-defined value given in the EnumThreadWindows function.

Returns

To continue enumeration, the callback function must return TRUE; to stop enumeration, it must return FALSE.

Comments

The callback function can carry out 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


EnumWindowsProc
EnumWindowsProc (Win32)

BOOL CALLBACK EnumWindowsProc(hwnd, lParam)

HWND hwnd;	/* handle of parent window	*/
LPARAM lParam;	/* application-defined value	*/

The EnumWindowsProc function is an application-defined callback function that receives top-level window handles as a result of a call to the EnumWindows function.

Parameter	Description

hwnd	Identifies a top-level window.

lParam	Specifies the application-defined value given in the EnumWindows function.

Returns

To continue enumeration, the callback function must return TRUE; to stop enumeration, it must return FALSE.

Comments

The callback function can carry out any desired task.

An application must register this callback function by passing its address to the EnumWindows function. EnumWindowsProc is a placeholder for the application-defined function name.

See Also

EnumWindows


FileIOCompletionRoutine
FileIOCompletionRoutine (Win32)

VOID WINAPI FileIOCompletionRoutine(fdwError, cbTransferred, lpo)

DWORD fdwError;	/* completion code	*/
DWORD cbTransferred;	/* number of bytes transferred	*/
LPOVERLAPPED lpo;	/* address of structure with I/O information	*/

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

Parameter	Description

fdwError	Specifies the I/O completion status. This 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.

cbTransferred	Specifies the number of bytes transferred. This parameter is zero if an error occurs.

lpo	Points to the OVERLAPPED structure specified by the asynchronous I/O function. The OVERLAPPED structure has the following form:

typedef struct _OVERLAPPED { /* o */

    DWORD  Internal;

    DWORD  InternalHigh;

    DWORD  Offset;

    DWORD  OffsetHigh;

    HANDLE hEvent;

} OVERLAPPED;

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.

Returns

This function does not return a value.

Comments

FileIOCompletionRoutine 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

ReadFileEx, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx


FMExtensionProc
FMExtensionProc (Win32)

LONG WINAPI FMExtensionProc(hwnd, wMsg, lParam)

HWND hwnd;	/* handle of extension window	*/
WORD wMsg;	/* menu-item identifier, or message	*/
LONG lParam;	/* additional message information	*/

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

Parameter	Description

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.

wMsg	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-dependent information.

Returns

The callback function should return the result of the message processing. The actual return value depends on the message processed.

Comments

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.

See Also

FM_REFRESH_WINDOWS, FMS_LOAD


GetMsgProc
GetMsgProc (Win32)

LRESULT CALLBACK GetMsgProc(nCode, wParam, lParam)

int nCode;	/* hook code	*/
WPARAM wParam;	/* removal flag	*/
LPARAM lParam;	/* address of structure with message	*/

The GetMsgProc hook procedure is an application-defined or library-defined callback function 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.

Parameter	Description

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

Returns

The return value should be zero.

Comments

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, SetWindowsHookEx, MSG


JournalPlaybackProc
JournalPlaybackProc (Win32)

LRESULT CALLBACK JournalPlaybackProc(nCode, wParam, lParam)

int nCode;	/* hook code	*/
WPARAM wParam;	/* undefined	*/
LPARAM lParam;	/* address of message being processed	*/

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.

Parameter	Description

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_GETNEXT	The hook procedure must copy the current mouse or keyboard message to the EVENTMSG structure pointed to by the lParam parameter. For a description of the EVENTMSG structure, see the <Microsoft Win32 Programmer's Reference, Volume 5>.

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. For a description of the EVENTMSG structure, see the <Microsoft Win32 Programmer's Reference, Volume 5>.

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 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 EVENTMSG structure that represents a message being processed by the hook procedure. This parameter is valid only when the nCode parameter is HC_GETNEXT.

Returns

To have the system wait before processing the message, the return value must be the amount of time, in clock ticks, 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.

Comments

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 nCode parameter set to HC_GETNEXT without an intervening call with nCode set to HC_SKIP.

If nCode 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 nCode 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 nCode 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+Escape, Alt+Escape, or  Control+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.

JournalPlaybackProc is a placeholder for an application-defined or library-defined function name.

See Also

CallNextHookEx, JournalRecordProc, SetWindowsHookEx, WM_CANCELJOURNAL


JournalRecordProc
JournalRecordProc (Win32)

LRESULT CALLBACK JournalRecordProc(nCode, wParam, lParam)

int nCode;	/* hook code	*/
WPARAM wParam;	/* undefined	*/
LPARAM lParam;	/* address of message being processed	*/

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.

Parameter	Description

nCode	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. For a description of the EVENTMSG structure, see the the the <Microsoft Win32 Programmer's Reference, Volume 5>.

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 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 EVENTMSG structure that contains the message to be recorded.

Returns

The return value is ignored.

Comments

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 three other key combinations that cannot be recorded: Ctrl-Escape, Alt-Escape, and Control-Alt-Del. Those three 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, JournalPlaybackProc, SetWindowsHookEx, WM_CANCELJOURNAL


KeyboardProc
KeyboardProc (Win32)

LRESULT CALLBACK KeyboardProc(nCode, wParam, lParam)

int nCode;	/* hook code	*/
WPARAM wParam;	/* virtual-key code	*/
LPARAM lParam;	/* keystroke-message information	*/

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.

Parameter	Description

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

Returns

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.

Comments

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


LineDDAProc
LineDDAProc (Win32)

VOID CALLBACK LineDDAProc(X, Y, lpData)

int X;	/* x-coordinate of point being evaluated	*/
int Y;	/* y-coordinate of point being evaluated	*/
LPARAM lpData;	/* address of application-defined data	*/

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.

Parameter	Description

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.

Returns

This function must return a nonzero value to continue enumeration; to stop enumeration, it must return zero.

Comments

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


MessageProc
MessageProc (Win32)

LRESULT CALLBACK MessageProc(nCode, wParam, lParam)

int nCode;	/* hook code	*/
WPARAM wParam;	/* undefined	*/
LPARAM lParam;	/* address of structure with message data	*/

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.

Parameter	Description

nCode	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 DDEML

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

Returns

If the hook procedure processes the message, the return value must be a nonzero value. Otherwise, it must be zero.

Comments

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


MouseProc
MouseProc (Win32)

LRESULT CALLBACK MouseProc(nCode, wParam, lParam)

int nCode;	/* hook code	*/
WPARAM wParam;	/* message identifier	*/
LPARAM lParam;	/* mouse coordinates	*/

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.

Parameter	Description

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.

Returns

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.

Comments

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, PeekMessage, SetWindowsHookEx


OutputProc
OutputProc (Win32)

BOOL CALLBACK OutputProc(hdc, lpData, cchData)

HDC hdc;	/* handle of device context	*/
LPARAM lpData;	/* address of string to be drawn	*/
int cchData;	/* length of string to be drawn	*/

The OutputProc function is an application-defined callback function that draws a string as a result of a call to the GrayString function.

Parameter	Description

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.

Returns

If it succeeds, the callback function should return TRUE; otherwise, it should return FALSE.

Comments

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


PropEnumProc
PropEnumProc (Win32)

BOOL CALLBACK PropEnumProc(hwnd, lpszString, hData)

HWND hwnd;	/* handle of window with property	*/
LPCTSTR lpszString;	/* atom or address of string	*/
HANDLE hData;	/* data handle	*/

A PropEnumProc function is an application-defined callback function that receives a window's property data as a result of a call to the EnumProps function. A value of type PROPENUMPROC is a pointer to such a function.

Parameter	Description

hwnd	Identifies the window that contains the property list.

lpszString	Points to the null-terminated string associated with the data identified by the hData parameter. The application specified the string and data handle in a previous call to the SetProp function. If the application passed an atom instead of a string to the SetProp function, the lpszString parameter contains the atom in the low-order word and zero in the high-order word.

hData	Identifies the property data.

Returns

The callback function should return TRUE to continue enumeration or FALSE to stop enumeration.

Comments

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
PropEnumProcEx (Win32)

BOOL CALLBACK PropEnumProcEx(hwnd, lpszString, hData)

HWND hwnd;	/* handle of window with property	*/
LPCTSTR lpszString;	/* atom or address of string	*/
HANDLE hData;	/* data handle	*/
DWORD dwData;	/* application-defined data	*/

A PropEnumProcEx function is an application-defined callback function that receives a window's property data as a result of a call to the EnumPropsEx function. A value of type PROPENUMPROCEX is a pointer to such a function.

Parameter	Description

hwnd	Identifies the window that contains the property list.

lpszString	Points to the null-terminated string associated with the data identified by the hData parameter. The application specified the string and data handle in a previous call to the SetProp function. If the application passed an atom instead of a string to the SetProp function, the lpszString parameter contains the atom in the low-order word and zero in the high-order word.

hData	Identifies the property data.

dwData	Application-defined data.

Returns

The callback function should return TRUE to continue enumeration or FALSE to stop enumeration.

Comments

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


SendAsyncProc
SendAsyncProc (Win32)

VOID CALLBACK SendAsyncProc(hwnd, uMsg, dwData, lResult)

HWND hwnd;	/* handle of destination window	*/
UINT uMsg;	/* message	*/
DWORD dwData;	/* application-defined value	*/
LRESULT lResult;	/* result of message processing	*/

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.

Parameter	Description

hwnd	Identifies the window whose window procedure received the message. If this parameter is HWND_TOPMOST, the message was sent to all top-level windows in the system, including disabled or invisible unowned windows.

uMsg	Specifies the message.

dwData	Specifies an extra value sent from the SendMessageCallback function.

lResult	Specifies the result of the message processing and depends on the message.

Returns

This callback function does not return a value.

Comments

SendAsyncProc is a placeholder for an application-defined function name.

A SendAsyncProc function is installed for calling by passing a SENDASYNCPROC pointer to the SendMessageCallback function.

See Also

SendMessage, SendMessageCallback


ShellProc
ShellProc (Win32)

LRESULT CALLBACK ShellProc(nCode, wParam, lParam)

int nCode;	/* hook code	*/
WPARAM wParam;	/* event-specific information	*/
LPARAM lParam;	/* undefined	*/

The ShellProc hook procedure is an application-defined or library-defined callback function a shell application uses to receive useful notifications from the system.

Parameter	Description

nCode	Specifies the hook code. This parameter can be one of the following values:

Value	Meaning

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	Reserved; not used.

Returns

The return value should be zero.

Comments

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


SysMsgProc
SysMsgProc (Win32)

LRESULT CALLBACK SysMsgProc(nCode, wParam, lParam)

int nCode;	/* message flag	*/
WPARAM wParam;	/* undefined	*/
LPARAM lParam;	/* address of structure with message data	*/

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.

Parameter	Description

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.

Returns

If the hook procedure processes the message, the return value must be a nonzero value. Otherwise, it must be zero.

Comments

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, SetWindowsHookEx


TimerProc
TimerProc (Win32)

VOID CALLBACK TimerProc(hwnd, uMsg, idEvent, dwTime)

HWND hwnd;	/* handle of window for timer messages	*/
UINT uMsg;	/* WM_TIMER message	*/
UINT idEvent;	/* timer identifier	*/
DWORD dwTime;	/* current system time	*/

The TimerProc function is an application-defined callback function that processes WM_TIMER messages.

Parameter	Description

hwnd	Identifies the window associated with the timer.

uMsg	Specifies the WM_TIMER message.

idEvent	Specifies the timer's identifier.

dwTime	Specifies the system time, in Coordinated Universal Time (UTC) format.

Returns

This function does not return a value.

Comments

TimerProc is a placeholder for the application-defined function name.

See Also

KillTimer, SetTimer, WM_TIMER


UndeleteFile
UndeleteFile (Win32)

DWORD APIENTRY UndeleteFile(hwndOwner, lpszDir)

HWND hwndOwner;	/* handle of File Manager window	*/
LPSTR lpszDir;	/* address of name of initial directory	*/

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.

Parameter	Description

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.

Returns

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.


WindowProc
WindowProc (Win32)

LRESULT CALLBACK WindowProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;	/* handle of window	*/
UINT uMsg;	/* message identifier	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The WindowProc function is an application-defined callback function that processes messages sent to a window.

Parameter	Description

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.

Returns

The function should return the result of the message processing. The actual return value depends on the message sent.

Comments

WindowProc is a placeholder for the application-defined function name.

See Also

CallWindowProc,, DefWindowProc, RegisterClass, WNDCLASS


WinMain
WinMain (Win32)

int WinMain(hInstance, hPrevInstance, lpszCmdLine, nCmdShow)

HINSTANCE hInstance;	/* handle of current instance	*/
HINSTANCE hPrevInstance;	/* handle of previous instance	*/
LPSTR lpszCmdLine;	/* address of command line	*/
int nCmdShow;	/* show state of window	*/

The WinMain function is called by the system as the initial entry point for a Windows-based application.

Parameter	Description

hInstance	Identifies the current instance of the application.

hPrevInstance	Identifies the previous instance of the application. For a Windows NT application, this parameter is always NULL.

lpszCmdLine	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).

Returns

If the function succeeds, terminating when it receives a WM_QUIT message, it should return the exit code contained in that message's wParam parameter. If the function terminates before entering the message loop, it should return 0.

Comments

The WinMain function initializes an application, and then performs a message retrieval-and-dispatch loop that is the top-level control structure for the remainder of the application's execution. The 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.

See Also

DispatchMessage, GetMessage, PostQuitMessage, TranslateMessage


Callback Functions (all)

AbortProc	Processes a canceled print job

CallWndProc	Filters messages sent by the SendMessage function

CBTProc	Allows a CBT application to prevent an operation

CPlApplet	Processes messages for a Control Panel DLL

DialogProc	Processes input to a dialog box

DdeCallback	Processes DDEML transactions

DebugProc	Examines data before it is sent to a hook

DllEntryPoint	Called for DLL initialization and cleanup

EditWordBreakProc	Determines line breaks in an edit control

EnhMetaFileProc	Processes enhanced metafile data

EnumChildProc	Processes child window handles during enumeration

EnumFontFamProc	Retrieves fonts in a specified family

EnumFontsProc	Processes font data

EnumMetaFileProc	Processes metafile data

EnumObjectsProc	Processes objects data

EnumResLangProc	List language resources callback

EnumResNameProc	List resource names callback

EnumResTypeProc	List resource types callback

EnumThreadWndProc	Processes thread window handles during enumeration

EnumWindowsProc	Processes parent window handles during enumeration

FileIOCompletionRoutine	Called when asynchronous I/O completes

FMExtensionProc	Processes messages for a File Manager extension

GetMsgProc	Filters messages retrieved by GetMessage

JournalPlaybackProc	Places recorded events into the system queue

JournalRecordProc	Records event messages

KeyboardProc	Filters keystroke messages

LineDDAProc	Processes line data

MessageProc	Filters dialog box, menu, or scroll bar messages

MouseProc	Filters mouse messages

OutputProc	Outputs text for the GrayString function

PropEnumProc	Receives enumerated property for a window

PropEnumProcEx	Receives enumerated property for a window

SendAsyncProc	Receives the result of message processing

ShellProc	Receives notifications from the system

SysMsgProc	Filters dialog, message box, or menu messages

TimerProc	Processes WM_TIMER message

UndeleteFile	Processes the File Manager Undelete command

WindowProc	Processes input to a window

WinMain	Initializes an application and processes message loop


CommDlgExtendedError function
CommDlgExtendedError (Win32)

DWORD CommDlgExtendedError(VOID)

The CommDlgExtendedError function identifies the cause of the most recent error to have occurred during the execution of one of the following common dialog box functions:

ChooseColor

ChooseFont

FindText

GetFileTitle

GetOpenFileName

GetSaveFileName

PrintDlg

ReplaceText

Returns

If the previous call to a common dialog box procedure succeeds, the return value is zero. The return value is CDERR_DIALOGFAILURE if the dialog box could not be created. Otherwise, the return value is a nonzero integer that identifies an error condition.

Comments

Following are the possible CommDlgExtendedError return values and the meaning of each:

Value	Meaning

CDERR_FINDRESFAILURE	The common dialog box procedure failed to find a specified resource.

CDERR_INITIALIZATION	The common dialog box procedure failed during initialization. This error often occurs when insufficient memory is available.

CDERR_LOADRESFAILURE	The common dialog box procedure failed to load a specified resource.

CDERR_LOCKRESFAILURE	The common dialog box procedure failed to lock a specified resource.

CDERR_LOADSTRFAILURE	The common dialog box procedure failed to load a specified string.

CDERR_MEMALLOCFAILURE	The common dialog box procedure was unable to allocate memory for internal structures.

CDERR_MEMLOCKFAILURE	The common dialog box procedure was unable to lock the memory associated with a handle.

CDERR_NOHINSTANCE	The ENABLETEMPLATE flag was set in the Flags member of a structure for the corresponding common dialog box, but the application failed to provide a corresponding instance handle.

CDERR_NOHOOK	The ENABLEHOOK flag was set in the Flags member of a structure for the corresponding common dialog box, but the application failed to provide a pointer to a corresponding hook function.

CDERR_NOTEMPLATE	The ENABLETEMPLATE flag was set in the Flags member of a structure for the corresponding common dialog box, but the application failed to provide a corresponding template.

CDERR_REGISTERMSGFAIL	The RegisterWindowMessage function returned an error value when it was called by the common dialog box procedure.

CDERR_STRUCTSIZE	The lStructSize member of a structure for the corresponding common dialog box is invalid.

CFERR_NOFONTS	No fonts exist.

CFERR_MAXLESSTHANMIN	The size specified in the nSizeMax member of the CHOOSEFONT structure is less than the size specified in the nSizeMin member.

FNERR_BUFFERTOOSMALL	The buffer for a filename is too small. (This buffer is pointed to by the lpstrFile member of the structure for a common dialog box.)

FNERR_INVALIDFILENAME	A filename is invalid.

FNERR_SUBCLASSFAILURE	An attempt to subclass a list box failed because insufficient memory was available.

FRERR_BUFFERLENGTHZERO	A member in a structure for the corresponding common dialog box points to an invalid buffer.

PDERR_CREATEICFAILURE	The PrintDlg function failed when it attempted to create an information context.

PDERR_DEFAULTDIFFERENT	An application called the PrintDlg function with the DN_DEFAULTPRN flag set 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 happens when an application stores the DEVNAMES structure and the user changes the default printer by using Control Panel.)

To use the printer described by the DEVNAMES structure, the application should clear the DN_DEFAULTPRN flag and call the PrintDlg function again. To use the default printer, the application should replace the DEVNAMES structure (and the DEVMODE structure, if one exists) with NULL; this sets the default printer automatically.

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 value applies only to printer drivers written for Windows versions 3.0 and later.)

PDERR_INITFAILURE	Indicates that PrintDlg function failed during initialization, and that there is no more specific extended error code to describe the failure. Think of this as the generic default error code for that 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 set in the Flags member of the PRINTDLG structure, but the hDevMode or hDevNames member was nonzero.

PDERR_SETUPFAILURE	The PrintDlg function failed to load the required resources.

See Also

ChooseColor, ChooseFont, FindText, GetFileTitle, GetOpenFileName, GetSaveFileName, PrintDlg, ReplaceText, CHOOSECOLOR, CHOOSEFONT, FINDREPLACE, OPENFILENAME, PRINTDLG, DEVMODE, DEVNAMES


ChooseColor function
ChooseColor (Win32)

BOOL ChooseColor(lpcc)

LPCHOOSECOLOR lpcc;	/* address of structure with initialization data	*/

The ChooseColor function creates system-defined dialog box from which the user can select a color.

Parameter	Description

lpcc	Points to a CHOOSECOLOR structure that, when the function is called, contains information necessary to initialize the dialog box. When ChooseColor returns, this structure contains information about the user's color selection.

Returns

If the user selects a color, the return value is TRUE; it is FALSE if an error occurs, the user chooses the Cancel button, or the user chooses the Close command on the System menu (often called the Control menu) to close the dialog box.

Use the CommDlgExtendedError function to retrieve extended error information, which may be one of the following values:

CDERR_FINDRESFAILURE

CDERR_INITIALIZATION

CDERR_LOCKRESFAILURE

CDERR_LOADRESFAILURE

CDERR_LOADSTRFAILURE

CDERR_MEMALLOCFAILURE

CDERR_MEMLOCKFAILURE

CDERR_NOHINSTANCE

CDERR_NOHOOK

CDERR_NOTEMPLATE

CDERR_STRUCTSIZE

Comments

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

If the hook function (pointed to by the lpfnHook member of the CHOOSECOLOR structure) processes the WM_CTLCOLORDLG message, this function must return a handle for the brush that should be used to paint the control background.

See Also

CommDlgExtendedError, WM_CTLCOLORDLG, CHOOSECOLOR


ChooseFont function
ChooseFont (Win32)

BOOL ChooseFont(lpcf)

LPCHOOSEFONT lpcf;	/* pointer to structure with initialization data	*/

The ChooseFont function creates a system-defined dialog box from which the user can select a font, a font style (such as bold or italic), a point size, an effect (such as strikeout or underline), and a text color.

Parameter	Description

lpcf	Points to a CHOOSEFONT structure that, when the structure is called, contains information necessary to initialize the dialog box. When ChooseFont returns, this structure contains information about the user's font selection.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Use the CommDlgExtendedError function to retrieve extended error information, which may be one of the following values:

CDERR_FINDRESFAILURE

CDERR_INITIALIZATION

CDERR_LOCKRESFAILURE

CDERR_LOADRESFAILURE

CDERR_LOADSTRFAILURE

CDERR_MEMALLOCFAILURE

CDERR_MEMLOCKFAILURE

CDERR_NOHINSTANCE

CDERR_NOHOOK

CDERR_NOTEMPLATE

CDERR_STRUCTSIZE

CFERR_MAXLESSTHANMIN

CFERR_NOFONTS

Comments

If the hook function (to which the lpfnHook member of the CHOOSEFONT structure points) processes the WM_CTLCOLORDLG message, this function must return a handle for the brush that should be used to paint the control background.

An application can use the WM_CHOOSEFONT_GETLOGFONT message to retrieve a LOGFONT structure for the current logical font while the Font dialog box is open.

See Also

CommDlgExtendedError, WM_CHOOSEFONT_GETLOGFONT, WM_CTLCOLORDLG, CHOOSEFONT


FindText function
FindText (Win32)

HWND FindText(lpfr)

LPFINDREPLACE lpfr;	/* pointer to structure with initialization data	*/

The FindText function creates a system-defined modeless dialog box that enables the user to find text within a document.

Parameter	Description

lpfr	Points to a FINDREPLACE structure that contains information used to initialize the dialog box. When the user makes a selection in the dialog box, the system fills this structure with data that describes the user's selection and then sends a message to the application. This message contains a pointer to the FINDREPLACE structure.

Returns

If the function succeeds, the return value is the window handle of the dialog box; otherwise, it is NULL. Use the CommDlgExtendedError function to retrieve the extended error information, which may be one of the following values:

CDERR_FINDRESFAILURE

CDERR_INITIALIZATION

CDERR_LOCKRESFAILURE

CDERR_LOADRESFAILURE

CDERR_LOADSTRFAILURE

CDERR_MEMALLOCFAILURE

CDERR_MEMLOCKFAILURE

CDERR_NOHINSTANCE

CDERR_NOHOOK

CDERR_NOTEMPLATE

CDERR_STRUCTSIZE

FRERR_BUFFERLENGTHZERO

Comments

FindText does not perform a search operation, it simply returns a string typed by the user (as well as related data such as the direction in which the search should occur). An application must perform the search by using this string.

An application can use the window handle returned by this function to communicate with or to close the dialog box.

The dialog box procedure for the Find dialog box passes user requests to the application by sending special messages. The lParam parameter of each of these messages contains a pointer to a FINDREPLACE structure. The procedure sends the messages to the window identified by the hwndOwner member of the FINDREPLACE structure. An application can register the identifier for these messages by specifying the "commdlg_FindReplace" string in a call to the RegisterWindowMessage function.

For the TAB key to function correctly, any application that calls FindText must also call the IsDialogMessage function in its main message loop. IsDialogMessage returns a value that indicates whether messages are intended for the Find dialog box.

If the hook function (pointed to by the lpfnHook member of the FINDREPLACE structure) processes the WM_CTLCOLORDLG message, this function must return a handle of the brush that should be used to paint the control background.

See Also

IsDialogMessage, RegisterWindowMessage, ReplaceText, WM_CTLCOLORDLG, FINDREPLACE


GetFileTitle function
GetFileTitle (Win32)

short GetFileTitle(lpszFile, lpszTitle, cbBuf)

LPCTSTR lpszFile;	/* address of full path and file name for file	*/
LPTSTR lpszTitle;	/* address of buffer that receives filename	*/
WORD cbBuf;	/* length of buffer	*/

The GetFileTitle function returns the title of the file identified by the lpszFile parameter.

Parameter	Description

lpszFile	Points to the name and location of a file.

lpszTitle	Points 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.

Returns

If the function succeeds, the return value is zero. If the filename is invalid, the return value is a negative number. If the buffer at lpszTitle is too small, the return value is a positive integer that specifies the required buffer size, in characters.

Comments

The function returns an error value if the buffer pointed to by the lpszFile parameter contains any of the following:

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

The required buffer size includes the terminating null character.

Note that sizes are specified and received as character counts, not bytes. That provides UNICODE intelligence; the counts are valid for both the _A and _W versions of this function.

To obtain the buffer size needed for the title of a file, call the GetFileTitle function with lpszTitle set to NULL and cbBuf set to zero. The function will return with the requisite value.

See Also

GetOpenFileName, GetSaveFileName, OPENFILENAME


GetOpenFileName function
GetOpenFileName (Win32)

BOOL GetOpenFileName(lpofn)

LPOPENFILENAME lpofn;	/* address of structure with initialization data	*/

The GetOpenFileName function creates a system-defined dialog box that enables the user to select a file to open.

Parameter	Description

lpofn	Points 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.

Returns

If the user selects a file to open, the return value is TRUE. It is FALSE if an error occurs, the user chooses the Cancel button, the user chooses the Close command on the System menu to close the dialog box, or the buffer identified by the lpstrFile member of the OPENFILENAME structure is too small to contain the string that specifies the selected file.

Use the CommDlgExtendedError function to retrieve extended error information, which may be one of the following values:

CDERR_FINDRESFAILURE

CDERR_INITIALIZATION

CDERR_LOCKRESFAILURE

CDERR_LOADRESFAILURE

CDERR_LOADSTRFAILURE

CDERR_MEMALLOCFAILURE

CDERR_MEMLOCKFAILURE

CDERR_NOHINSTANCE

CDERR_NOHOOK

CDERR_NOTEMPLATE

CDERR_STRUCTSIZE

FNERR_BUFFERTOOSMALL

FNERR_INVALIDFILENAME

FNERR_SUBCLASSFAILURE

Comments

If the hook function (pointed to by the lpfnHook member of the OPENFILENAME structure) processes the WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, or WM_CTLCOLORSTATIC message, this function must return a handle of the brush that should be used to paint the control background.

Ending the dialog from within the hook function by calling the EndDialog function prevents the comdlg32 DLL from properly exiting its worker thread. For applications that dynamically load and/or unload the comdlg32 dll, this may result in an access violation during unload as the worker thread's address space is invalidated.

See Also

CommDlgExtendedError, GetSaveFileName, OPENFILENAME


GetSaveFileName function
GetSaveFileName (Win32)

BOOL GetSaveFileName(lpofn)

LPOPENFILENAME lpofn;	/* address of structure with initialization data	*/

The GetSaveFileName function creates a system-defined dialog box that enables the user to select a file to save.

Parameter	Description

lpofn	Points 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.

Returns

If the user selects a file to save, the return value is TRUE. It is FALSE if an error occurs, the user clicks the Cancel button, the user chooses the Close command on the System menu to close the dialog box, or the buffer identified by the lpstrFile member of the OPENFILENAME structure is too small to contain the string that specifies the selected file.

Use the CommDlgExtendedError function to retrieve extended error information, which may be one of the following values:

CDERR_FINDRESFAILURE

CDERR_INITIALIZATION

CDERR_LOCKRESFAILURE

CDERR_LOADRESFAILURE

CDERR_LOADSTRFAILURE

CDERR_MEMALLOCFAILURE

CDERR_MEMLOCKFAILURE

CDERR_NOHINSTANCE

CDERR_NOHOOK

CDERR_NOTEMPLATE

CDERR_STRUCTSIZE

FNERR_BUFFERTOOSMALL

FNERR_INVALIDFILENAME

FNERR_SUBCLASSFAILURE

Comments

If the hook function (pointed to by the lpfnHook member of the OPENFILENAME structure) processes the WM_CTLCOLORDLG message, this function must return a handle for the brush that should be used to paint the control background.

Ending the dialog from within the hook function by calling the EndDialog function prevents the comdlg32 DLL from properly exiting its worker thread. For applications that dynamically load and/or unload the comdlg32 dll, this may result in an access violation during unload as the worker thread's address space is invalidated.

See Also

CommDlgExtendedError, GetOpenFilename, WM_CTLCOLORDLG, OPENFILENAME


PrintDlg function
PrintDlg (Win32)

BOOL PrintDlg(lppd)

LPPRINTDLG lppd;	/* pointer to structure with initialization data	*/

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 allows the user to select additional job properties and configure the printer.

Parameter	Description

lppd	Points 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.

Returns

If the function succeeds in configuring the printer, the return value is TRUE. The return value is FALSE if an error occurs, the user chooses the Cancel button, or the user chooses the Close command on the System menu to close the dialog box. (The return value is also FALSE if the user chooses the Setup button to display the Print Setup dialog box, chooses the OK button in the Print Setup dialog box, and then chooses the Cancel button in the Print dialog box.)

Use the CommDlgExtendedError function to obtain extended error information, which may be 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

Comments

If the hook function (pointed to by the lpfnPrintHook or lpfnSetupHook member of the PRINTDLG structure) processes the WM_CTLCOLORDLG message, this function must return a handle for the brush that should be used to paint the control background.

See Also

CommDlgExtendedError, WM_CTLCOLORDLG, PRINTDLG


ReplaceText function
ReplaceText (Win32)

HWND ReplaceText(lpfr)

LPFINDREPLACE lpfr;	/* pointer to structure with initialization data	*/

The ReplaceText function creates a system-defined modeless dialog box that enables the user to find and replace text within a document.

Parameter	Description

lpfr	Points to a FINDREPLACE structure that contains information used to initialize the dialog box. When the user makes a selection in the dialog box, the system fills this structure with information about the user's selection and then sends a message to the application. This message contains a pointer to the FINDREPLACE structure.

Returns

If the function succeeds, the return value is the window handle of the dialog box, or it is NULL if an error occurs.

Errors

Use the CommDlgExtendedError function to retrieve extended error information, which may be one of the following values:

CDERR_FINDRESFAILURE

CDERR_INITIALIZATION

CDERR_LOADRESFAILURE

CDERR_LOADSTRFAILURE

CDERR_LOCKRESFAILURE

CDERR_MEMALLOCFAILURE

CDERR_MEMLOCKFAILURE

CDERR_NOHINSTANCE

CDERR_NOHOOK

CDERR_NOTEMPLATE

CDERR_STRUCTSIZE

FRERR_BUFFERLENGTHZERO

Comments

The ReplaceText function does not perform a text replacement operation, it simply returns a string typed by the user (as well as related data). An application must perform the replacement using this string.

An application can use the window handle returned by this function to communicate with or to close the dialog box.

The dialog box procedure for ReplaceText passes user requests to the application by sending special messages. The lParam parameter of each of these messages contains a pointer to a FINDREPLACE structure. The procedure sends the messages to the window identified by the hwndOwner member of the FINDREPLACE structure. An application can register the identifier for these messages by specifying the "commdlg_FindReplace" string in a call to the RegisterWindowMessage function.

For the TAB key to function correctly, any application that calls ReplaceText must also call the IsDialogMessage function in its main message loop. (IsDialogMessage returns a value that indicates whether messages are intended for the Replace dialog box.)

See Also

IsDialogMessage, RegisterWindowMessage, WM_CTLCOLORDLG, FINDREPLACE


Common-Dialog Functions (all)

CommDlgExtendedError	Retrieves Error Data

ChooseColor	Creates a color-selection dialog box

ChooseFont	Creates a font-selection dialog box

FindText	Creates a find-text dialog box

GetFileTitle	Retrieves a filename

GetOpenFileName	Creates an open-filename dialog box

GetSaveFileName	Creates a save-filename dialog box

PrintDlg	Creates a print-text dialog box

ReplaceText	Creates a replace-text dialog box


DdeAbandonTransaction function
DdeAbandonTransaction (Win32)

BOOL DdeAbandonTransaction(idInst, hconv, idTransaction)

DWORD idInst;	/* instance identifier	*/
HCONV hconv;	/* handle of conversation	*/
DWORD idTransaction;	/* transaction identifier	*/

The DdeAbandonTransaction function abandons the specified asynchronous transaction and releases all resources associated with the transaction.

Parameter	Description

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 (the idTransaction parameter is ignored).

idTransaction	Identifies the transaction to abandon. If this parameter is 0L, all active transactions in the specified conversation are abandoned.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALIDPARAMETER

DMLERR_NO_ERROR

DMLERR_UNFOUND_QUEUE_ID

Comments

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, DdeGetLastError, DdeInitialize, DdeQueryConvInfo


DdeAccessData function
DdeAccessData (Win32)

LPBYTE DdeAccessData(hdata, lpcbData)

HDDEDATA hdata;	/* handle of DDE object	*/
LPDWORD lpcbData;	/* pointer to variable that receives data length	*/

The DdeAccessData function provides access to the data in the given dynamic data exchange (DDE) object. An application must call the DdeUnaccessData function when it has finished accessing the data in the object.

Parameter	Description

hdata	Identifies the DDE object to access.

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

Returns

If the function succeeds, the return value is a pointer to the first byte of data in the DDE object; otherwise, the return value is NULL.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALIDPARAMETER

DMLERR_NO_ERROR

Comments

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, DdeGetLastError, DdeUnaccessData


DdeAddData function
DdeAddData (Win32)

HDDEDATA DdeAddData(hdata, lpbSrcBuf, cbAddData, offObj)

HDDEDATA hdata;	/* handle of DDE data object	*/
LPBYTE lpbSrcBuf;	/* address of source buffer	*/
DWORD cbAddData;	/* length of data	*/
DWORD offObj;	/* offset within DDE data object	*/

The DdeAddData function adds data to the given 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.

Parameter	Description

hdata	Identifies the DDE object that receives additional data.

lpbSrcBuf	Points to a buffer containing the data to add to the DDE object.

cbAddData	Specifies the length, in bytes, of the data to be added to the DDE object.

offObj	Specifies an offset, in bytes, from the beginning of the DDE object. The additional data is copied to the object beginning at this offset.

Returns

If the function succeeds, the return value is a new handle of the DDE object. Use the new handle in all references to the object. If an error occurs, the return value is zero.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALIDPARAMETER

DMLERR_MEMORY_ERROR

DMLERR_NO_ERROR

Comments

After a data handle has been used as a parameter in another Dynamic Data Exchange Management Library (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.

If the amount of memory originally allocated is less than is needed to hold the added data, the DdeAddData function reallocates a global memory object of the appropriate size.

See Also

DdeAccessData, DdeCreateDataHandle, DdeGetLastError, DdeUnaccessData


DdeClientTransaction function
DdeClientTransaction (Win32)

HDDEDATA DdeClientTransaction(lpbData, cbData, hconv, hszItem, uFmt, uType, uTimeout, lpdwResult)

LPBYTE lpbData;	/* address of data to pass to server	*/
DWORD cbData;	/* length of data	*/
HCONV hconv;	/* handle of conversation	*/
HSZ hszItem;	/* handle of item-name string	*/
UINT uFmt;	/* clipboard data format	*/
UINT uType;	/* transaction type	*/
DWORD uTimeout;	/* time-out duration	*/
LPDWORD lpdwResult;	/* points to transaction result	*/

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 only after establishing a conversation with the server.

Parameter	Description

lpbData	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, in which case the cbData parameter should be set to 0xFFFFFFFF. This parameter is required only if the uType parameter is XTYP_EXECUTE or XTYP_POKE. Otherwise, this parameter should be NULL.

For this optional usage of the parameter, XTYP_POKE transactions where lpbData is a data handle, the handle must have been created using the DdeCreateDataHandle function, using the same data format specified in the uFmt parameter.

cbData	Specifies the length, in bytes, of the data pointed to by the lpbData parameter. A value of 0xFFFFFFFF indicates that lpbData 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 uType parameter is XTYP_EXECUTE.

uFmt	Specifies the standard clipboard format in which the data item is being submitted or requested.

If the transaction specified by the uType parameter does not pass data or is XTYP_EXECUTE, this parameter should be set to zero.

If the transaction specified by the uType parameter references non-execute DDE data (XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_REQUEST), the uFmt value must be either a valid predefined (CF_) DDE format or a valid registered clipboard format.

uType	Specifies the transaction type. This parameter can be one of the following values:

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

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

uTimeout	Specifies the maximum length of time, in milliseconds, the client will wait for a response from the server application in a synchronous transaction. This parameter should be set to TIMEOUT_ASYNC for asynchronous transactions.

lpdwResult	Points to a variable that receives the result of the transaction. An application that does not check the result can set this value to NULL. 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 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.

Returns

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 non-zero 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

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

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

Comments

When the application has finished using the data handle returned by the DdeClientTransaction function, 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 the client to enter a modal loop while waiting for various asynchronous events. Because of this, the client application can still respond to user input while waiting on a synchronous transaction but 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, DdeCreateStringHandle


DdeCmpStringHandles function
DdeCmpStringHandles (Win32)

int DdeCmpStringHandles(hsz1, hsz2)

HSZ hsz1;	/* handle of first string	*/
HSZ hsz2;	/* handle of second string	*/

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.

Parameter	Description

hsz1	Specifies the first string handle.

hsz2	Specifies the second string handle.

Returns

The return value can be one of the following:

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.

Comments

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 function
DdeConnect (Win32)

HCONV DdeConnect(idInst, hszService, hszTopic, pCC)

DWORD idInst;	/* instance identifier	*/
HSZ hszService;	/* handle of service-name string	*/
HSZ hszTopic;	/* handle of topic-name string	*/
PCONVCONTEXT pCC;	/* address of structure with context data	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the handle of the established conversation; otherwise, it is 0L.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALIDPARAMETER

DMLERR_NO_CONV_ESTABLISHED

DMLERR_NO_ERROR

Comments

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

DdeConnectList, DdeCreateStringHandle, DdeDisconnect, DdeDisconnectList, DdeInitialize, CONVCONTEXT, XTYP_CONNECT, XTYP_REGISTER, XTYP_UNREGISTER


DdeConnectList function
DdeConnectList (Win32)

HCONVLIST DdeConnectList(idInst, hszService, hszTopic, hConvList, pCC)

DWORD idInst;	/* instance identifier	*/
HSZ hszService;	/* handle of service-name string	*/
HSZ hszTopic;	/* handle of topic-name string	*/
HCONVLIST hConvList;	/* handle of conversation list	*/
PCONVCONTEXT pCC;	/* address of structure with context data	*/

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 retrieve a list of conversation handles by passing the function an existing conversation handle. The Dynamic Data Exchange Management Library (DDEML) 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.

Parameter	Description

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 set to 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.

Returns

If the function succeeds, the return value is the handle of a new conversation list; otherwise, it is 0L. The handle of the old conversation list is no longer valid.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALID_PARAMETER

DMLERR_NO_CONV_ESTABLISHED

DMLERR_NO_ERROR

DMLERR_SYS_ERROR

Comments

An application must free the conversation-list handle returned by this function, regardless of whether any conversation handles within the list are active. To free the handle, an application can call the DdeDisconnectList function.

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

DdeConnect, DdeCreateStringHandle, DdeDisconnect, DdeDisconnectList, DdeInitialize, DdeQueryNextServer, CONVCONTEXT, XTYP_CONNECT


DdeCreateDataHandle function
DdeCreateDataHandle (Win32)

HDDEDATA DdeCreateDataHandle(idInst, lpbSrcBuf, cbInitData, offSrcBuf, hszItem, uFmt, afCmd)

DWORD idInst;	/* instance identifier	*/
LPBYTE lpbSrcBuf;	/* address of source buffer	*/
DWORD cbInitData;	/* length of DDE object	*/
DWORD offSrcBuf;	/* offset from beginning of source buffer	*/
HSZ hszItem;	/* handle of item-name string	*/
UINT uFmt;	/* clipboard data format	*/
UINT afCmd;	/* creation flags	*/

The DdeCreateDataHandle function creates a dynamic data exchange (DDE) object and fills the object with the data pointed to by the lpbSrcBuf parameter. A DDE application uses this function during transactions that involve passing data to the partner application.

Parameter	Description

idInst	Specifies the application-instance identifier obtained by a previous call to the DdeInitialize function.

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

cbInitData	Specifies the amount of memory, in bytes, to allocate for the DDE object. If this parameter is zero, the lpbSrcBuf parameter is ignored.

offSrcBuf	Specifies an offset, in bytes, from the beginning of the buffer pointed to by the lpbSrcBuf 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 set to 0L.

uFmt	Specifies the standard clipboard format of the data.

afCmd	Specifies the creation flags. This parameter can be HDATA_APPOWNED, specifying that the server application that calls the DdeCreateDataHandle function owns the data handle this function creates. This 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 set, the application must eventually free the shared memory object associated with this handle by using the DdeFreeDataHandle function. If this flag is not set, after the data handle is returned by the application's DDE callback function or used as a parameter in another DDEML function, the handle becomes invalid in the application that creates the handle.

Returns

If the function succeeds, the return value is a data handle; otherwise, it is 0L.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALIDPARAMETER

DMLERR_MEMORY_ERROR

DMLERR_NO_ERROR

Comments

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, DdeFreeDataHandle, DdeGetData, DdeInitialize, XTYP_EXECUTE


DdeCreateStringHandle function
DdeCreateStringHandle (Win32)

HSZ DdeCreateStringHandle(idInst, lpszString, codepage)

DWORD idInst;	/* instance identifier	*/
LPTSTR lpszString;	/* address of null-terminated string	*/
int codepage;	/* code page identifier	*/

The DdeCreateStringHandle function creates a handle that identifies the string pointed to by the lpszString 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.

Parameter	Description

idInst	Specifies the application-instance identifier obtained by a previous call to the DdeInitialize function.

lpszString	Points to a buffer that contains the null-terminated string for which a handle is to be created. This string may be of any length.

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

Returns

If the function succeeds, the return value is a string handle; otherwise, it is 0L.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_INVALIDPARAMETER

DMLERR_NO_ERROR

DMLERR_SYS_ERROR

Comments

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 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 function
DdeDisconnect (Win32)

BOOL DdeDisconnect(hconv)

HCONV hconv;	/* handle of conversation	*/

The DdeDisconnect function terminates a conversation started by either the DdeConnect or DdeConnectList function and invalidates the given conversation handle.

Parameter	Description

hconv	Identifies the active conversation to be terminated.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_NO_CONV_ESTABLISHED

DMLERR_NO_ERROR

Comments

Any incomplete transactions started before calling DdeDisconnect are immediately abandoned. The XTYP_DISCONNECT transaction type 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 function
DdeDisconnectList (Win32)

BOOL DdeDisconnectList(hConvList)

HCONVLIST hConvList;	/* handle of conversation list	*/

The DdeDisconnectList function destroys the given conversation list and terminates all conversations associated with the list.

Parameter	Description

hConvList	Identifies the conversation list. This handle must have been created by a previous call to the DdeConnectList function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALIDPARAMETER

DMLERR_NO_ERROR

Comments

An application can use the DdeDisconnect function to terminate individual conversations in the list.

See Also

DdeConnect, DdeConnectList, DdeDisconnect, XTYP_DISCONNECT


DdeEnableCallback function
DdeEnableCallback (Win32)

BOOL DdeEnableCallback(idInst, hconv, uCmd)

DWORD idInst;	/* instance identifier	*/
HCONV hconv;	/* handle of conversation	*/
UINT uCmd;	/* the enable/disable function code	*/

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

Parameter	Description

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 0L, the function affects all conversations.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. If the uCmd parameter is EC_QUERYWAITING and the queue contains one or more transactions, the return value is TRUE; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_NO_ERROR

DMLERR_INVALIDPARAMETER

Comments

An application can disable transactions for a specific conversation by returning CBR_BLOCK from its dynamic data exchange (DDE) callback function. When the conversation is reenabled by using the DdeEnableCallback function, the 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.

See Also

DdeConnect, DdeConnectList, DdeDisconnect, DdeInitialize


DdeFreeDataHandle function
DdeFreeDataHandle (Win32)

BOOL DdeFreeDataHandle(hdata)

HDDEDATA hdata;	/* handle of DDE object	*/

The DdeFreeDataHandle function frees a dynamic data exchange (DDE) object and deletes the data handle associated with the object.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_INVALIDPARAMETER

DMLERR_NO_ERROR

Comments

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


DdeFreeStringHandle function
DdeFreeStringHandle (Win32)

BOOL DdeFreeStringHandle(idInst, hsz)

DWORD idInst;	/* instance identifier	*/
HSZ hsz;	/* handle of string	*/

The DdeFreeStringHandle function frees a string handle in the calling application.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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

DdeCmpStringHandles, DdeCreateStringHandle, DdeInitialize, DdeKeepStringHandle, DdeQueryString


DdeGetData function
DdeGetData (Win32)

DWORD DdeGetData(hdata, lpbDest, cbMax, offSrc)

HDDEDATA hdata;	/* handle of DDE object	*/
LPBYTE lpbDest;	/* address of destination buffer	*/
DWORD cbMax;	/* amount of data to copy	*/
DWORD offSrc;	/* offset to beginning of data	*/

The DdeGetData function copies data from the given dynamic data exchange (DDE) object to the specified local buffer.

Parameter	Description

hdata	Identifies the DDE object that contains the data to copy.

lpbDest	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 lpbDest parameter. Typically, this parameter specifies the length of the buffer pointed to by lpbDest.

offSrc	Specifies an offset within the DDE object. Data is copied from the object beginning at this offset.

Returns

If the lpbDest 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 lpbDest parameter is NULL, the return value is the size, in bytes, of the memory object associated with the data handle.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALIDPARAMETER

DMLERR_NO_ERROR

See Also

DdeAccessData, DdeCreateDataHandle, DdeFreeDataHandle


DdeGetLastError function
DdeGetLastError (Win32)

UINT DdeGetLastError(idInst)

DWORD idInst;	/* instance identifier	*/

The DdeGetLastError function returns the most recent error value set by the failure of a Dynamic Data Exchange Management Library (DDEML) function and resets the error value to DMLERR_NO_ERROR.

Parameter	Description

idInst	Specifies the application-instance identifier obtained by a previous call to the DdeInitialize function.

Returns

If the function succeeds, the return value is the last error value. Following are the possible DDEML error values:

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 bit 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 are as follows:

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 is no longer valid.

See Also

DdeInitialize


DdeInitialize function
DdeInitialize (Win32)

UINT DdeInitialize(lpidInst, pfnCallback, afCmd, uRes)

LPDWORD lpidInst;	/* address of instance identifier	*/
PFNCALLBACK pfnCallback;	/* address of callback function	*/
DWORD afCmd;	/* set of command and filter flags	*/
DWORD uRes;	/* reserved	*/

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.

Parameter	Description

lpidInst	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 lpidInst points to a nonzero value, this implies a reinitialization of the DDEML. In this case, lpidInst 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 description of the callback function DdeCallback.

afCmd	Specifies a set of APPCMD_, CBF_, and MF_ flags. The APPCMD_ flags provide special instructions to the DdeInitialize function. The CBF_ flags set 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 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 Comments 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 this flag. On subsequent calls to DdeInitialize, not specifying this flag turns off the application's service-name filters; specifying this flag 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 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.

uRes	Reserved; must be set to 0.

Returns

If the function succeeds, the return value is DMLERR_NO_ERROR.

If the function fails, the return value is one of the following:

DMLERR_DLL_USAGE

DMLERR_INVALIDPARAMETER

DMLERR_SYS_ERROR

Comments

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 this function. 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


DdeKeepStringHandle function
DdeKeepStringHandle (Win32)

BOOL DdeKeepStringHandle(idInst, hsz)

DWORD idInst;	/* instance identifier	*/
HSZ hsz;	/* handle of string	*/

The DdeKeepStringHandle function increments (increases by one) the usage count associated with the given 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.

Parameter	Description

idInst	Specifies the application-instance identifier obtained by a previous call to the DdeInitialize function.

hsz	Identifies the string handle to be saved.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

DdeCreateStringHandle, DdeFreeStringHandle, DdeInitialize, DdeQueryConvInfo, DdeQueryString, CONVINFO


DdeNameService function
DdeNameService (Win32)

HDDEDATA DdeNameService(idInst, hsz1, hszRes, afCmd)

DWORD idInst;	/* instance identifier	*/
HSZ hsz1;	/* handle of service-name string	*/
HSZ hszRes;	/* reserved	*/
UINT afCmd;	/* service-name flags	*/

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.

Parameter	Description

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.

hszRes	Reserved; should be set to 0L.

afCmd	Specifies the service-name flags. This parameter can be one of the following values:

Value	Meaning

DNS_REGISTER	Registers the given service name.

DNS_UNREGISTER	Unregisters the given 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. This 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 set, the server receives an XTYP_CONNECT transaction whenever another DDE application calls the DdeConnect function, regardless of the service name.

Returns

The function returns a non-zero value if it succeeds. 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.

The function returns 0L if it fails.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_DLL_USAGE

DMLERR_INVALIDPARAMETER

DMLERR_NO_ERROR

Comments

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 function
DdePostAdvise (Win32)

BOOL DdePostAdvise(idInst, hszTopic, hszItem)

DWORD idInst;	/* instance identifier	*/
HSZ hszTopic;	/* handle of topic-name string	*/
HSZ hszItem;	/* handle of item-name string	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_DLL_USAGE

DMLERR_NO_ERROR

Comments

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 function
DdeQueryConvInfo (Win32)

UINT DdeQueryConvInfo(hconv, idTransaction, lpConvInfo)

HCONV hconv;	/* handle of conversation	*/
DWORD idTransaction;	/* transaction identifier	*/
PCONVINFO lpConvInfo;	/* address of structure with conversation data	*/

The DdeQueryConvInfo function retrieves information about a dynamic data exchange (DDE) transaction and about the conversation in which the transaction takes place.

Parameter	Description

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.

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

Returns

If the function succeeds, the return value is the number of bytes copied into the CONVINFO structure; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_NO_CONV_ESTABLISHED

DMLERR_NO_ERROR

DMLERR_UNFOUND_QUEUE_ID

Comments

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

DdeConnect, DdeConnectList, DdeKeepStringHandle, DdeQueryNextServer, CONVINFO


DdeQueryNextServer function
DdeQueryNextServer (Win32)

HCONV DdeQueryNextServer(hConvList, hConvPrev)

HCONVLIST hConvList;	/* handle of conversation list	*/
HCONV hConvPrev;	/* previous conversation handle	*/

The DdeQueryNextServer function obtains the next conversation handle in the given conversation list.

Parameter	Description

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.

Returns

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 function
DdeQueryString (Win32)

DWORD DdeQueryString(idInst, hsz, lpsz, cchMax, codepage)

DWORD idInst;	/* instance identifier	*/
HSZ hsz;	/* handle of string	*/
LPTSTR lpsz;	/* address of destination buffer	*/
DWORD cchMax;	/* length of buffer	*/
int codepage;	/* code page identifier	*/

The DdeQueryString function copies text associated with a string handle into a buffer.

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 lpsz parameter is NULL, this function obtains the length, in bytes, of the string associated with the string handle. The length does not include the terminating null character.

Parameter	Description

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.

lpsz	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 lpsz parameter. If the string is longer than (cchMax - 1), it will be truncated. If the lpsz parameter is set to NULL, this parameter is ignored.

codepage	Specifies the code page used to render the string. This value should be either CP_WINANSI or CP_WINUNICODE.

Returns

If the lpsz 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 lpsz 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.

See Also

DdeCmpStringHandles, DdeCreateStringHandle, DdeFreeStringHandle, DdeInitialize


DdeReconnect function
DdeReconnect (Win32)

HCONV DdeReconnect(hconv)

HCONV hconv;	/* handle of conversation to reestablish	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the handle of the reestablished conversation; otherwise, it is 0L.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALIDPARAMETER

DMLERR_NO_CONV_ESTABLISHED

DMLERR_NO_ERROR

See Also

DdeConnect, DdeDisconnect


DdeSetQualityOfService function
DdeSetQualityOfService (Win32) )

BOOL DdeSetQualityOfService(hwndClient, pqosNew, pqosPrev)

HWND hwndClient;	/* 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	*/

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.

Parameter	Description

hwndClient	A window handle that specifies the source of WM_DDE_INITIATE messages that a client will send to start DDE conversations.

pqosNew	Points to a SECURITY_QUALITY_OF_SERVICE structure that contains the desired quality of service (qos) values.

pqosPrev	Points to a SECURITY_QUALITY_OF_SERVICE structure that the function will fill with the previous quality of service (qos) values associated with hwndClient.

This parameter is optional. If an application has no interest in hwndClient's previous qos values, it should set pqosPrev to NULL.

Returns

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. Call GetLastError for extended error information.

Comments

The settings associated with a given hwndClient affect any conversation started subsequent to calling the DdeSetQualityOfService function. The settings remain in force for the duration of any DDE conversation started under them. Once an application starts a DDE conversation using a particular quality of service (qos), it must terminate the conversation and restart the conversation in order to have a different qos take effect. If a qos has not been  specified for a given hwndClient prior to sending a WM_DDE_INITIATE with the wParam set to hwndClient, the system uses its default quality of service values. Those defaults are :

    {

    Length = sizeof(SECURITY_QUALITY_OF_SERVICE);

    ImpersonationLevel = SecurityImpersonation ;

    ContextTrackingMode = SECURITY_STATIC_TRACKING ;

    EffectiveOnly = TRUE ;

    }

See Also

DdeConnect, DdeConnectList, ImpersonateDdeClientWindow, DdeImpersonateClient, CONVCONTEXT, SECURITY_QUALITY_OF_SERVICE, WM_DDE_INITIATE


DdeSetUserHandle function
DdeSetUserHandle (Win32)

BOOL DdeSetUserHandle(hconv,id, hUser)

HCONV hconv;	/* handle of conversation	*/
DWORD id;	/* transaction identifier	*/
DWORD hUser;	/* application-defined value	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALIDPARAMETER

DMLERR_NO_ERROR

DMLERR_UNFOUND_QUEUE_ID

See Also

DdeQueryConvInfo


DdeUnaccessData function
DdeUnaccessData (Win32)

BOOL DdeUnaccessData(hData)

HDDEDATA hData;	/* handle of DDE object	*/

The DdeUnaccessData function unaccesses a dynamic data exchange (DDE) object. An application must call this function after it has finished accessing the object.

Parameter	Description

hData	Identifies the DDE object.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED

DMLERR_INVALIDPARAMETER

DMLERR_NO_ERROR

See Also

DdeAccessData, DdeAddData, DdeCreateDataHandle, DdeFreeDataHandle


DdeUninitialize function
DdeUninitialize (Win32)

BOOL DdeUninitialize(idInst)

DWORD idInst;	/* instance identifier	*/

The DdeUninitialize function frees all Dynamic Data Exchange Management Library (DDEML) resources associated with the calling application.

Parameter	Description

idInst	Specifies the application-instance identifier obtained by a previous call to the DdeInitialize function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

DdeUninitialize terminates any conversations currently open for the application.

See Also

DdeDisconnect, DdeDisconnectList, DdeInitialize


DDEML Functions (all)

DdeAbandonTransaction	Abandons an asynchronous transaction

DdeAccessData	Accesses a DDE data object

DdeAddData	Adds data to a DDE data object

DdeClientTransaction	Begins a DDE data transaction

DdeCmpStringHandles	Compares two DDE string handles

DdeConnect	Establishes a conversation with a server

DdeConnectList	Establishes multiple DDE conversations

DdeCreateDataHandle	Creates a DDE data handle

DdeCreateStringHandle	Creates a DDE string handle

DdeDisconnect	Terminates a DDE conversation

DdeDisconnectList	Destroys a DDE conversation list

DdeEnableCallback	Enables or disables one or more DDE conversations

DdeFreeDataHandle	Frees a DDE data object

DdeFreeStringHandle	Frees a DDE string handle

DdeGetData	Copies data from a DDE data object to a buffer

DdeGetLastError	Returns an error code set by a DDEML function

DdeInitialize	Registers an application with the DDEML

DdeKeepStringHandle	Increments the usage count for a string handle

DdeNameService	Registers or unregisters a service name

DdePostAdvise	Prompts a server to send advise data to a client

DdeQueryConvInfo	Retrieves information about a DDE conversation

DdeQueryNextServer	Obtains the next handle in a conversation list

DdeQueryString	Copies string-handle text to a buffer

DdeReconnect	Reestablishes a DDE conversation

DdeSetQualityOfService	Specify DDE quality of service

DdeSetUserHandle	Associates a user-defined handle with a transaction

DdeUnaccessData	Frees a DDE data object

DdeUninitialize	Frees an application's DDEML resources


DeviceIoControl function
DeviceIoControl (Win32)

BOOL DeviceIoControl(hDevice, dwIoControlCode, lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer, lpcbBytesReturned, lpoOverlapped)

HANDLE hDevice;	/* handle of the device	*/
DWORD dwIoControlCode;	/* control code of operation to perform	*/
LPVOID lpvInBuffer;	/* address of buffer for input data	*/
DWORD cbInBuffer;	/* size of input buffer	*/
LPVOID lpvOutBuffer;	/* address of output buffer	*/
DWORD cbOutBuffer;	/* size of output buffer	*/
LPDWORD lpcbBytesReturned;	/* address of actual bytes of output	*/
LPOVERLAPPED lpoOverlapped;	/* address of overlapped structure	*/

The DeviceIoControl function sends a control code directly to a given device driver, causing the device to perform the specified operation.

Parameter	Description

hDevice	Identifies the device. The CreateFile function returns this 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

IOCTL_DISK_CHECK_VERIFY	Checks for change in removable-media device

IOCTL_DISK_EJECT_MEDIA	Ejects media from a SCSI device

IOCTL_DISK_FORMAT_TRACKS	Formats a contiguous set of disk tracks

IOCTL_DISK_GET_DRIVE_GEOMETRY	Obtain information on the physical disk's geometry

IOCTL_DISK_GET_DRIVE_LAYOUT	Provides info on each partition on a disk

IOCTL_DISK_GET_MEDIA_TYPES	Obtains information about media support

IOCTL_DISK_GET_PARTITION_INFO	Obtain disk partition information

IOCTL_DISK_LOAD_MEDIA	Loads media into a device

IOCTL_DISK_MEDIA_REMOVAL	Enables or disables media eject mechanism

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	Set disk partition type

IOCTL_DISK_VERIFY	Performs logical format of a disk extent

IOCTL_SERIAL_LSRMST_INSERT	Enables or disables placement of line and modem status data into data stream

lpvInBuffer	Points to a buffer containing 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.

cbInBuffer	Specifies the size, in bytes, of the lpvInBuffer buffer.

lpvOutBuffer	Points to a buffer in which the operation's output data is returned. This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not produce output data.

cbOutBuffer	Specifies the size, in bytes, of the lpvOutBuffer buffer.

lpcbBytesReturned	Points to a 32-bit variable that receives the actual size, in bytes, of the data returned in the lpvOutBuffer buffer.

lpoOverlapped	Points to an OVERLAPPED structure. This parameter is ignored if the hDevice handle was opened without specifying the FILE_FLAG_OVERLAPPED flag. This parameter can be NULL if overlapped operation is not desired.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If the lpoOverlapped parameter is NULL or the hDevice handle was opened without specifying the FILE_FLAG_OVERLAPPED flag, the DeviceIoControl function does not return until the operation has been completed, or an error occurs.

If the lpoOverlapped parameter points to an OVERLAPPED structure and the FILE_FLAG_OVERLAPPED flag was specified when hDevice handle was opened, DeviceIoControl 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 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 system sets the event object in the OVERLAPPED structure to the not-signaled state before DeviceIoControl returns, and then it sets it to the signaled state when the operation has been completed. The calling thread can use any of the wait functions to determine the event object's state, then use the GetOverlappedResult function to determine the results of the operation. GetOverlappedResult reports the success or failure of the operation and the number of bytes returned in the lpvOutBuffer buffer.

See Also

CreateEvent, CreateFile, GetOverlappedResult, WaitForMultipleObjects, WaitForSingleObject


IOCTL_DISK_CHECK_VERIFY function
IOCTL_DISK_CHECK_VERIFY (Win32)

dwIoControlCode = IOCTL_DISK_CHECK_VERIFY ;   /* operation code */

lpvInBuffer = NULL;       /* address of input buffer; not used; must be NULL */

cbInBuffer = 0;           /* size of input buffer; not used; must be zero */

lpvOutBuffer = NULL;      /* address of output buffer; not used; must be NULL */

cbOutBuffer = 0;          /* size of output buffer; not used; must be zero */

lpcbBytesReturned;        /* address of actual bytes of output */

The IOCTL_DISK_CHECK_VERIFY operation determines whether a device's media is accessible; for example, whether the media is in the device.

Parameter	Description

lpvInBuffer	Points to an input buffer. Not used with this operation. Set to NULL.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer. Not used with this operation. Set to zero.

lpvOutBuffer	Points to an output buffer. Not used with this operation. Set to NULL.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer. Not used with this operation. Set to zero.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds and the device media is accessible, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE.


IOCTL_DISK_EJECT_MEDIA function
IOCTL_DISK_EJECT_MEDIA (Win32)

dwIoControlCode = IOCTL_DISK_EJECT_MEDIA;   /* operation code */

lpvInBuffer = NULL;       /* address of input buffer; not used; must be NULL */

cbInBuffer = 0;           /* size of input buffer; not used; must be zero */

lpvOutBuffer = NULL;      /* address of output buffer; not used; must be NULL */

cbOutBuffer = 0;          /* size of output buffer; not used; must be zero */

lpcbBytesReturned;        /* address of actual bytes of output */

The IOCTL_DISK_EJECT_MEDIA operation causes media to be ejected from a SCSI device.

Parameter	Description

lpvInBuffer	Points to an input buffer. Not used with this operation. Set to NULL.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer. Not used with this operation. Set to zero.

lpvOutBuffer	Points to an output buffer. Not used with this operation. Set to NULL.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer. Not used with this operation. Set to zero.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

IOCTL_DISK_EJECT_MEDIA  may or may not be supported on SCSI devices that support removable media.

See Also

IOCTL_DISK_MEDIA_REMOVAL, IOCTL_DISK_LOAD_MEDIA


IOCTL_DISK_FORMAT_TRACKS function
IOCTL_DISK_FORMAT_TRACKS (Win32)

dwIoControlCode = IOCTL_DISK_FORMAT_TRACKS;   /* operation code */

lpvInBuffer;              /* address of input buffer */

cbInBuffer;               /* size of input buffer */

lpvOutBuffer = NULL;      /* address of output buffer; not used; must be NULL */

cbOutBuffer = 0;          /* size of output buffer; not used; must be zero */

lpcbBytesReturned;        /* address of actual bytes of output */

The IOCTL_DISK_FORMAT_TRACKS operation formats a specified, contiguous set of tracks on a disk.

Parameter	Description

lpvInBuffer	Points to a buffer that contains a FORMAT_PARAMETERS data structure.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer, which must be large enough to contain a FORMAT_PARAMETERS data structure.

lpvOutBuffer	Points to an output buffer. Not used with this operation. Set to NULL.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer. Not used with this operation. Set to zero.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

This device i/o control operation is for floppy disk devices only.

See Also

FORMAT_PARAMETERS


IOCTL_DISK_GET_DRIVE_GEOMETRY function
IOCTL_DISK_GET_DRIVE_GEOMETRY (Win32)

dwIoControlCode = IOCTL_DISK_GET_DRIVE_GEOMETRY;   /* operation code */

lpvInBuffer = NULL; /* address of input buffer; not used; must be NULL */

cbInBuffer = 0;     /* size of input buffer; not used; must be zero */

lpvOutBuffer ;      /* address of output buffer */

cbOutBuffer ;       /* size of output buffer */

lpcbBytesReturned ; /* address of actual bytes of output */

The IOCTL_DISK_GET_DRIVE_GEOMETRY operation returns information about the physical disk's geometry: type, number of cylinders, tracks per cylinder, sectors per track, and bytes per sector.

Parameter	Description

lpvInBuffer	Points to an input buffer. Not used with this operation. Set to NULL.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer. Not used with this operation. Set to zero.

lpvOutBuffer	Points to a buffer that will receive a DISK_GEOMETRY data structure.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer, which must be greater than or equal to the size of a DISK_GEOMETRY data structure.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

This device i/o control operation is for disk devices.

See Also

IOCTL_DISK_GET_MEDIA_TYPES, DISK_GEOMETRY


IOCTL_DISK_GET_DRIVE_LAYOUT function
IOCTL_DISK_GET_DRIVE_LAYOUT (Win32)

dwIoControlCode = IOCTL_DISK_GET_DRIVE_LAYOUT;   /* operation code */

lpvInBuffer = NULL; /* address of input buffer; not used; must be NULL */

cbInBuffer = 0;     /* size of input buffer; not used; must be zero */

lpvOutBuffer ;      /* address of output buffer */

cbOutBuffer ;       /* size of output buffer */

lpcbBytesReturned ; /* address of actual bytes of output */

The IOCTL_DISK_GET_DRIVE_LAYOUT operation returns information about the number of partitions on a disk and the features of each partition.

Parameter	Description

lpvInBuffer	Points to an input buffer. Not used with this operation. Set to NULL.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer. Not used with this operation. Set to zero.

lpvOutBuffer	Points to a buffer that will receive a DRIVE_LAYOUT_INFORMATION data structure and a series of PARTITION_INFORMATION data structures, one of the latter for each partition on the drive.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer, 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.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

This device i/o control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

See Also

IOCTL_DISK_SET_DRIVE_LAYOUT, DRIVE_LAYOUT_INFORMATION, PARTITION_INFORMATION


IOCTL_DISK_GET_MEDIA_TYPES function
IOCTL_DISK_GET_MEDIA_TYPES (Win32)

dwIoControlCode = IOCTL_DISK_GET_MEDIA_TYPES;   /* operation code */

lpvInBuffer = NULL; /* address of input buffer; not used; must be NULL */

cbInBuffer = 0;     /* size of input buffer; not used; must be zero */

lpvOutBuffer ;      /* address of output buffer */

cbOutBuffer ;       /* size of output buffer */

lpcbBytesReturned;  /* address of actual bytes of output */

The IOCTL_DISK_GET_MEDIA_TYPES returns information about the types of media a device driver supports.

Parameter	Description

lpvInBuffer	Points to an input buffer. Not used with this operation. Set to NULL.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer. Not used with this operation. Set to zero.

lpvOutBuffer	Points to a buffer that will receive an array of DISK_GEOMETRY data structures specifying the media types the device driver supports.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer, which must be large enough to contain as many DISK_GEOMETRY structures as there are media the driver supports.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

This device i/o control operation is for all class drivers, as well as non-SCSI hard drives and floppy disk devices.

See Also

IOCTL_DISK_GET_DRIVE_GEOMETRY, DISK_GEOMETRY


IOCTL_DISK_GET_PARTITION_INFO function
IOCTL_DISK_GET_PARTITION_INFO (Win32)

dwIoControlCode = IOCTL_DISK_GET_PARTITION_INFO ;   /* operation code */

lpvInBuffer = NULL;   /* address of input buffer; not used; must be NULL */

cbInBuffer = 0;       /* size of input buffer; not used; must be zero */

lpvOutBuffer;         /* address of output buffer */

cbOutBuffer;          /* size of output buffer */

lpcbBytesReturned;    /* address of actual bytes of output */

The IOCTL_DISK_GET_PARTITION_INFO operation returns information about the type, size, and nature of a disk partition.

Parameter	Description

lpvInBuffer	Points to an input buffer. Not used with this operation. Set to NULL.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer. Not used with this operation. Set to zero.

lpvOutBuffer	Points to a buffer that will receive a PARTITION_INFORMATION data structure.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer, which must be large enough to contain a PARTITION_INFORMATION data structure.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

This device i/o control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

See Also

IOCTL_DISK_SET_PARTITION_INFO, PARTITION_INFORMATION


IOCTL_DISK_LOAD_MEDIA function
IOCTL_DISK_LOAD_MEDIA (Win32)

dwIoControlCode = IOCTL_DISK_LOAD_MEDIA;   /* operation code */

lpvInBuffer = NULL;       /* address of input buffer; not used; must be NULL */

cbInBuffer = 0;           /* size of input buffer; not used; must be zero */

lpvOutBuffer = NULL;      /* address of output buffer; not used; must be NULL */

cbOutBuffer = 0;          /* size of output buffer; not used; must be zero */

lpcbBytesReturned;        /* address of actual bytes of output */

The IOCTL_DISK_LOAD_MEDIA operation causes media to be loaded into a device.

Parameter	Description

lpvInBuffer	Points to an input buffer. Not used with this operation. Set to NULL.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer. Not used with this operation. Set to zero.

lpvOutBuffer	Points to an output buffer. Not used with this operation. Set to NULL.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer. Not used with this operation. Set to zero.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Comments

The IOCTL_DISK_LOAD_MEDIA is valid only for devices that support loadable media.

See Also

IOCTL_DISK_EJECT_MEDIA, IOCTL_DISK_MEDIA_REMOVAL


IOCTL_DISK_MEDIA_REMOVAL function
IOCTL_DISK_MEDIA_REMOVAL (Win32)

dwIoControlCode = IOCTL_DISK_MEDIA_REMOVAL;   /* operation code */

lpvInBuffer;              /* address of input buffer */

cbInBuffer;               /* size of input buffer */

lpvOutBuffer = NULL;      /* address of output buffer; not used; must be NULL */

cbOutBuffer = 0;          /* size of output buffer; not used; must be zero */

lpcbBytesReturned;        /* address of actual bytes of output */

The IOCTL_DISK_MEDIA_REMOVAL operation enables or disables the mechanism that ejects media, for those devices possessing that locking capability.

Parameter	Description

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

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer, which must be large enough to contain a PREVENT_MEDIA_REMOVAL data structure.

lpvOutBuffer	Points to an output buffer. Not used with this operation. Set to NULL.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer. Not used with this operation. Set to zero.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

The IOCTL_DISK_MEDIA_REMOVAL operation is valid only for devices that support removable media.

See Also

IOCTL_DISK_EJECT_MEDIA, IOCTL_DISK_LOAD_MEDIA, PREVENT_MEDIA_REMOVAL


IOCTL_DISK_PERFORMANCE function
IOCTL_DISK_PERFORMANCE (Win32)

dwIoControlCode = IOCTL_DISK_PERFORMANCE;   /* operation code */

lpvInBuffer = NULL; /* address of input buffer; not used; must be NULL */

cbInBuffer = 0;     /* size of input buffer; not used; must be zero */

lpvOutBuffer;       /* address of output buffer */

cbOutBuffer;        /* size of output buffer */

lpcbBytesReturned;  /* address of actual bytes of output */

The IOCTL_DISK_PERFORMANCE operation provides disk performance information.

Parameter	Description

lpvInBuffer	Points to an input buffer. Not used with this operation. Set to NULL.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer. Not used with this operation. Set to zero.

lpvOutBuffer	Points to a buffer that will receive a DISK_PERFORMANCE data structure.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer, which must be large enough to contain a DISK_PERFORMANCE data structure.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

This device i/o control operation is for disk devices.


IOCTL_DISK_REASSIGN_BLOCKS function
IOCTL_DISK_REASSIGN_BLOCKS (Win32)

dwIoControlCode = IOCTL_DISK_REASSIGN_BLOCKS;   /* operation code */

lpvInBuffer;              /* address of input buffer */

cbInBuffer;               /* size of input buffer */

lpvOutBuffer = NULL;      /* address of output buffer; not used; must be NULL */

cbOutBuffer = 0;          /* size of output buffer; not used; must be zero */

lpcbBytesReturned;        /* address of actual bytes of output */

The IOCTL_DISK_REASSIGN_BLOCKS operation directs the disk device to map one or more blocks to its spare-block pool.

Parameter	Description

lpvInBuffer	Points to a buffer that contains a REASSIGN_BLOCKS data structure specifying the blocks to reassign to its spare block pool.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer, 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.

lpvOutBuffer	Points to an output buffer. Not used with this operation. Set to NULL.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer. Not used with this operation. Set to zero.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

This device i/o control operation is for disk devices.

See Also

REASSIGN_BLOCKS


IOCTL_DISK_SET_DRIVE_LAYOUT function
IOCTL_DISK_SET_DRIVE_LAYOUT (Win32)

dwIoControlCode = IOCTL_DISK_SET_DRIVE_LAYOUT;   /* operation code */

lpvInBuffer;              /* address of input buffer */

cbInBuffer;               /* size of input buffer */

lpvOutBuffer = NULL;      /* address of output buffer; not used; must be NULL */

cbOutBuffer = 0;          /* size of output buffer; not used; must be zero */

lpcbBytesReturned;        /* address of actual bytes of output */

The IOCTL_DISK_SET_DRIVE_LAYOUT operation partitions a disk as specified by drive layout and partition information data.

Parameter	Description

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

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer, 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.

lpvOutBuffer	Points to an output buffer. Not used with this operation. Set to NULL.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer. Not used with this operation. Set to zero.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

This device i/o control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

See Also

IOCTL_DISK_GET_DRIVE_LAYOUT, DRIVE_LAYOUT_INFORMATION, PARTITION_INFORMATION


IOCTL_DISK_SET_PARTITION_INFO function
IOCTL_DISK_SET_PARTITION_INFO (Win32)

dwIoControlCode = IOCTL_DISK_SET_PARTITION_INFO;   /* operation code */

lpvInBuffer;              /* address of input buffer */

cbInBuffer;               /* size of input buffer */

lpvOutBuffer = NULL;      /* address of output buffer; not used; must be NULL */

cbOutBuffer = 0;          /* size of output buffer; not used; must be zero */

lpcbBytesReturned;        /* address of actual bytes of output */

The IOCTL_DISK_SET_PARTITION_INFO operation sets the partition type of the specified disk partition.

Parameter	Description

lpvInBuffer	Points to a buffer that contains the partition data to be set. The data exists as a SET_PARTITION_INFORMATION data structure.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer, which must be large enough to contain a SET_PARTITION_INFORMATION data structure.

lpvOutBuffer	Points to an output buffer. Not used with this operation. Set to NULL.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer. Not used with this operation. Set to zero.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer. Not used with this operation. Set to NULL.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

This device i/o control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

See Also

IOCTL_DISK_GET_PARTITION_INFORMATION, SET_PARTITION_INFORMATION


IOCTL_DISK_VERIFY function
IOCTL_DISK_VERIFY (Win32)

dwIoControlCode = IOCTL_DISK_VERIFY;   /* operation code */

lpvInBuffer;              /* address of input buffer */

cbInBuffer;               /* size of input buffer */

lpvOutBuffer = NULL;      /* address of output buffer; not used; must be NULL */

cbOutBuffer = 0;          /* size of output buffer; not used; must be zero */

lpcbBytesReturned;        /* address of actual bytes of output */

The IOCTL_DISK_VERIFY operation performs a logical format of a specified extent on a disk.

Parameter	Description

lpvInBuffer	Points to a buffer that contains a VERIFY_INFORMATION data structure.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer, which must be large enough to contain a VERIFY_INFORMATION data structure.

lpvOutBuffer	Points to an output buffer. Not used with this operation. Set to NULL.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer. Not used with this operation. Set to zero.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

This device i/o control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

See Also

IOCTL_DISK_CHECK_VERIFY, VERIFY_INFORMATION


IOCTL_SERIAL_LSRMST_INSERT function
IOCTL_SERIAL_LSRMST_INSERT (Win32)

dwIoControlCode = IOCTL_SERIAL_LSRMST_INSERT;   /* operation code */

lpvInBuffer;              /* address of input buffer */

cbInBuffer;               /* size of input buffer */

lpvOutBuffer = NULL;      /* address of output buffer; not used; must be NULL */

cbOutBuffer = 0;          /* size of output buffer; not used; must be zero */

lpcbBytesReturned;        /* address of actual bytes of output */

The IOCTL_SERIAL_LSRMST_INSERT operation enables or disables the placement of line status and modem status values into the regular data stream that an application acquires via the ReadFile function.

When this line/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 Comments section below for status value details.

Parameter	Description

lpvInBuffer	Points to a buffer that contains a single BYTE.

If the BYTE is a non-zero value, it is the desired line/modem status value escape character. The operation will turn the LSRMST_INSERT line/modem status data placement mode on.

If the BYTE is zero, the operation will turn the LSRMST_INSERT line/modem status data placement mode off.

The escape character can not be the xon or xoff character.

cbInBuffer	Specifies the size in bytes of the buffer pointed to by lpvInBuffer. For this operation, this value should be 1.

lpvOutBuffer	Points to an output buffer. Not used with this operation. Set to NULL.

cbOutBuffer	Specifies the size in bytes of the buffer pointed to by lpvOutBuffer. Not used with this operation. Set to zero.

lpcbBytesReturned	Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Returns

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. Use GetLastError to obtain extended error information.

Comments

Note that an application that uses this scheme must examine each character in the data stream to determine the presence of modem/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.


Device I/O

DeviceIoControl	Calls a device driver directly

IOCTL_DISK_CHECK_VERIFY	Checks for change in removable-media device

IOCTL_DISK_EJECT_MEDIA	Ejects media from a SCSI device

IOCTL_DISK_FORMAT_TRACKS	Formats a contiguous set of disk tracks

IOCTL_DISK_GET_DRIVE_GEOMETRY	Obtain information on the physical disk's geometry

IOCTL_DISK_GET_DRIVE_LAYOUT	Provides info on each partition on a disk

IOCTL_DISK_GET_MEDIA_TYPES	Obtains information about media support

IOCTL_DISK_GET_PARTITION_INFO	Obtain disk partition information

IOCTL_DISK_LOAD_MEDIA	Loads media into a device

IOCTL_DISK_MEDIA_REMOVAL	Enables or disables media eject mechanism

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	Set disk partition type

IOCTL_DISK_VERIFY	Performs logical format of a disk extent

IOCTL_SERIAL_LSRMST_INSERT	Places modem and line status values into data stream


AbortDoc function
AbortDoc (Win32)

int AbortDoc(hdc)

HDC hdc;	/* handle of device context	*/

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.

Parameter	Description

hdc	Identifies the device context for the print job.

Returns

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, use the GetLastError function.

Comments

Applications should call the AbortDoc function to stop a print job in case an error occurred, 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 the AbortDoc function 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 function
AbortPath (Win32)

BOOL AbortPath(hdc)

HDC hdc;	/* handle of device context	*/

The AbortPath function closes and discards any paths in the given device context (DC).

Parameter	Description

hdc	Identifies the DC from which a path will be discarded.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


AddFontResource function
AddFontResource (Win32)

int AddFontResource(lpszFilename)

LPCTSTR lpszFilename;	/* address of font-resource filename	*/

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.

Parameter	Description

lpszFilename	Points 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.

Returns

If the function succeeds, the return value specifies the number of fonts added.

If the function fails, the return value is zero. Call GetLastError for extended error information.

Comments

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


AngleArc function
AngleArc (Win32)

BOOL AngleArc(hdc, X, Y, dwRadius, eStartAngle, eSweepAngle)

HDC hdc;	/* handle of 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	*/

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.

Parameter	Description

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 in logical units. 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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, this function 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, POINT


AnimatePalette function
AnimatePalette (Win32)

BOOL AnimatePalette(hpal, iStartIndex, cEntries, ppe)

HPALETTE hpal;	/* handle of logical color palette	*/
UINT iStartIndex;	/* first entry in logical palette	*/
UINT cEntries;	/* count of entries in logical palette	*/
CONST PALETTEENTRY *ppe;	/* address of first replacement	*/

The AnimatePalette function replaces entries in the given logical palette.

Parameter	Description

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	Points to the first member of an array of PALETTEENTRY structures used to replace the current entries.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, PALETTEENTRY, LOGPALETTE


Arc function
Arc (Win32)

BOOL Arc(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect, nXStartArc, nYStartArc, nXEndArc, nYEndArc)

HDC hdc;	/* handle of device context	*/
int nLeftRect;	/* x-coord. of upper-left corner of bounding rectangle	*/
int nTopRect;	/* y-coord. of upper-left corner of bounding rectangle	*/
int nRightRect;	/* x-coord. of lower-right corner of bounding rectangle	*/
int nBottomRect;	/* y-coord. of lower-right corner of bounding rectangle	*/
int nXStartArc;	/* first radial ending point	*/
int nYStartArc;	/* first radial ending point	*/
int nXEndArc;	/* second radial ending point	*/
int nYEndArc;	/* second radial ending point	*/

The Arc function draws an elliptical arc.

Parameter	Description

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.

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.

Returns

If the arc is drawn, the return value is TRUE; otherwise, it is FALSE.

Comments

The points (nLeftRect, nTopRect) and (nRightRect, nBottomRect) specify the bounding rectangle. An ellipse formed by the given bounding rectangle defines the curve of the arc. The arc extends counterclockwise from the point where it intersects the radial from the center of the bounding rectangle to (nXStartArc, nYStartArc). The arc ends where it intersects the radial from the center of the bounding rectangle to (nXEndArc, nYEndArc). 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 this function.

See Also

AngleArc, ArcTo, Chord, Ellipse, Pie, SetArcDirection


ArcTo function
ArcTo (Win32)

BOOL ArcTo(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect, nXRadial1, nYRadial1, nXRadial2, nYRadial2)

HDC hdc;	/* handle of device context	*/
int nLeftRect;	/* x-coordinate of upper-left corner of bounding rectangle	*/
int nTopRect;	/* y-coordinate of upper-left corner of bounding rectangle	*/
int nRightRect;	/* x-coordinate of lower-right corner of bounding rectangle	*/
int nBottomRect;	/* y-coordinate of lower-right corner of bounding rectangle	*/
int nXRadial1;	/* first radial ending point	*/
int nYRadial1;	/* first radial ending point	*/
int nXRadial2;	/* second radial ending point	*/
int nYRadial2;	/* second radial ending point	*/

The ArcTo function draws an elliptical arc.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

This function is similar to Arc, except that the current position is updated.

The points (nLeftRect, nTopRect) and (nRightRect, nBottomRect) specify the bounding rectangle. An ellipse formed by the given bounding rectangle defines the curve of the arc. The arc extends counterclockwise, default arc direction, from the point where it intersects the radial line from the center of the bounding rectangle to (nXRadial1, nYRadial1). The arc ends where it intersects the radial line from the center of the bounding rectangle to (nXRadial2, nYRadial2). 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


BeginPath function
BeginPath (Win32)

BOOL BeginPath(hdc)

HDC hdc;	/* handle of device context	*/

The BeginPath function opens a path bracket in the given device context (DC).

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value is TRUE; otherwise it is FALSE. To obtain extended error information, use the GetLastError function.

Comments

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 the BeginPath function for a DC, any previous paths are discarded from that DC.

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

See Also

EndPath, FillPath, PathToRegion, SelectClipPath, StrokeAndFillPath, StrokePath, WidenPath


BitBlt function
BitBlt (Win32)

BOOL BitBlt(hdcDest, nXDest, nYDest, nWidth, nHeight, hdcSrc, nXSrc, nYSrc, dwRop)

HDC hdcDest;	/* handle of destination device context	*/
int nXDest;	/* x-coordinate of destination rect. upper left corner	*/
int nYDest;	/* y-coordinate of destination rect. upper left corner	*/
int nWidth;	/* width of destination rect.	*/
int nHeight;	/* height of destination rect.	*/
HDC hdcSrc;	/* handle of source device context	*/
int nXSrc;	/* x-coordinate of source rect. upper left corner	*/
int nYSrc;	/* y-coordinate of source rect. upper left corner	*/
DWORD dwRop;	/* raster operation code	*/

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 the given destination device context.

Parameter	Description

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

For further information on raster operations, and complete lists of all the raster operation codes, see RasterOperationCodes.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

BitBlt returns an error if the source and destination device contexts represent different devices.

See Also

GetDeviceCaps, MaskBlt, PlgBlt, StretchBlt


CancelDC function
CancelDC (Win32)

BOOL CancelDC(hdc)

HDC hdc;	/* handle of device context	*/

The CancelDC function cancels any pending operation on the given device context.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value is TRUE. Otherwise, it is FALSE.

Comments

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


Chord function
Chord (Win32)

BOOL Chord(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect, nXRadial1, nYRadial1, nXRadial2, nYRadial2)

HDC hdc;	/* handle of device context	*/
int nLeftRect;	/* x-coord. of bounding rect. upper-left corner	*/
int nTopRect;	/* y-coord. of bounding rect. upper-left corner	*/
int nRightRect;	/* x-coord. of bounding rect. lower-right corner	*/
int nBottomRect;	/* y-coord. of bounding rect. 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	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 the 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 this function.

See Also

AngleArc, Arc, ArcTo, Pie


CloseEnhMetaFile function
CloseEnhMetaFile (Win32)

HENHMETAFILE CloseEnhMetaFile(hdc)

HDC hdc;	/* handle of an enhanced-metafile device context	*/

The CloseEnhMetaFile function closes an enhanced-metafile device context (DC) and returns a handle that identifies an enhanced-format metafile.

Parameter	Description

hdc	Identifies an enhanced-metafile device context.

Returns

If the function succeeds, the return value is a handle of an enhanced metafile; otherwise, it is NULL.

Comments

An application can use the enhanced-metafile handle returned by this 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


CloseFigure function
CloseFigure (Win32)

BOOL CloseFigure(hdc)

HDC hdc;	/* handle of device context	*/

The CloseFigure function closes an open figure in a path.

Parameter	Description

hdc	Identifies the device context in which the figure will be closed.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To obtain extended error information, use the GetLastError function.

Comments

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 MoveTo function), and 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.)

Any line or curve added to the path after CloseFigure starts a new figure.

See Also

BeginPath, EndPath, ExtCreatePen


CloseMetaFile function
CloseMetaFile (Win32)

HMETAFILE CloseMetaFile(hdc)

HDC hdc;	/* handle of metafile device context	*/

The CloseMetaFile function closes a metafile device context (DC) and returns a handle that identifies a Windows-format metafile.

This function is provided for compatibility with earlier versions of Microsoft Windows. For Win32 applications, use the CloseEnhMetaFile function.

Parameter	Description

hdc	Identifies a metafile device context used to create a Windows-format metafile.

Returns

If the function succeeds, the return value is a handle of a Windows-format metafile; otherwise, it is NULL.

Comments

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, CopyMetaFile, CreateMetaFile, DeleteMetaFile, EnumMetaFile, GetMetaFileBitsEx, PlayMetaFile, PolyBezier, SetWinMetaFileBits, SetWorldTransform


CombineRgn function
CombineRgn (Win32)

int CombineRgn(hrgnDest, hrgnSrc1, hrgnSrc2, fnCombineMode)

HRGN hrgnDest;	/* handle of destination region	*/
HRGN hrgnSrc1;	/* handle of source region	*/
HRGN hrgnSrc2;	/* handle of source region	*/
int fnCombineMode;	/* region combining mode	*/

The CombineRgn function combines two regions and stores the result in a third region. The two regions are combined according to the specified mode.

Parameter	Description

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

Returns

The return value specifies the type of the resulting region. 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.

ERROR	No region created.

Comments

The three regions need not be distinct. For example, hrgnSrc1 can equal hrgnDest.

See Also

CreateEllipticRgn, CreateEllipticRgnIndirect, CreatePolygonRgn, CreatePolyPolygonRgn, CreateRectRgn, CreateRectRgnIndirect, CreateRoundRectRgn


CombineTransform function
CombineTransform (Win32)

BOOL CombineTransform(lpxformResult, lpxform1, lpxform2)

LPXFORM lpxformResult;	/* address of combined transformation	*/
CONST XFORM * lpxform1;	/* address of first transformation	*/
CONST XFORM * lpxform2;	/* address of second transformation	*/

The CombineTransform function concatenates two world-space to page-space transformations.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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


CopyEnhMetaFile function
CopyEnhMetaFile (Win32)

HENHMETAFILE CopyEnhMetaFile(hemfSrc, lpszFile)

HENHMETAFILE hemfSrc;	/* handle of an enhanced metafile	*/
LPCTSTR lpszFile;	/* address of a filename string	*/

The CopyEnhMetaFile function copies the contents of an enhanced-format metafile to the given file.

Parameter	Description

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.

Returns

If the function succeeds, the return value is a handle of the copy of the enhanced metafile; otherwise, it is NULL. To obtain extended error information, use the GetLastError function.

Comments

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.

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


CopyMetaFile function
CopyMetaFile (Win32)

HMETAFILE CopyMetaFile(hmfSrc, lpszFile)

HMETAFILE hmfSrc;	/* handle of a Windows format metafile	*/
LPCTSTR lpszFile;	/* address of a filename string	*/

The CopyMetaFile function copies the content of a Windows-format metafile to the given file.

This function is provided for compatibility with earlier versions of Microsoft Windows. For Win32 applications, use the CopyEnhMetaFile function.

Parameter	Description

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.

Returns

If the function succeeds, the return value is a handle of the copy of the Windows-format metafile; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

This function supports only applications designed for Microsoft Windows version 3.x. It does not record or play back the new graphics device interface (GDI) 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, GetLastError


CreateBitmap function
CreateBitmap (Win32)

HBITMAP CreateBitmap(nWidth, nHeight, cPlanes, cBitsPerPel, lpvBits)

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;	/* address of array containing color data	*/

The CreateBitmap function creates a bitmap with the given width, height, and color format (color planes and bits per pixel).

Parameter	Description

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.

Returns

If the function succeeds, the return value is a handle of a bitmap; otherwise, it is NULL.

Comments

The CreateBitmap function should be used only to create monochrome bitmaps. The CreateDIBitmap function should be used to create color bitmaps. If the bitmap is monochrome, zeros represent the foreground color and ones represent the background color for the destination device context.

After a bitmap is created, it can be selected into a device context by calling the SelectObject function.

See Also

CreateDIBitmap, DeleteObject, GetBitmapBits, SelectObject, SetBitmapBits


CreateBitmapIndirect function
CreateBitmapIndirect (Win32)

HBITMAP CreateBitmapIndirect(lpbm)

CONST BITMAP * lpbm;	/* address of the bitmap data	*/

The CreateBitmapIndirect function creates a bitmap with the given width, height, and color format (color planes and bits per pixel).

Parameter	Description

lpbm	Points to a BITMAP structure that contains information about the bitmap.

Returns

If the function succeeds, the return value is a handle of the bitmap; otherwise, it is NULL.

Comments

The CreateBitmapIndirect function should be used only to create monochrome bitmaps. The CreateDIBitmap function should be used to create color bitmaps. If the bitmap is monochrome, zeros represent the foreground color and ones represent the background color for the destination device context.

After a bitmap is created, it can be selected into a device context by calling the SelectObject function.

See Also

BitBlt, CreateBitmap, CreateDIBitmap, SelectObject


CreateBrushIndirect function
CreateBrushIndirect (Win32)

HBRUSH CreateBrushIndirect(lplb)

CONST LOGBRUSH * lplb;	/* address of structure describing brush	*/

The CreateBrushIndirect function creates a logical brush that has the specified style, color, and pattern.

Parameter	Description

lplb	Points to a LOGBRUSH structure that contains information about the brush.

Returns

If the function succeeds, the return value identifies a logical brush; otherwise, it is NULL.

Comments

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.

See Also

DeleteObject, GetBrushOrgEx, SelectObject, SetBrushOrgEx, LOGBRUSH


CreateCompatibleBitmap function
CreateCompatibleBitmap (Win32)

HBITMAP CreateCompatibleBitmap(hdc, nWidth, nHeight)

HDC hdc;	/* handle of device context	*/
int nWidth;	/* width of bitmap, in pixels	*/
int nHeight;	/* height of bitmap, in pixels	*/

The CreateCompatibleBitmap function creates a bitmap compatible with the device that is associated with the given device context (DC).

Parameter	Description

hdc	Identifies a device context.

nWidth	Specifies the bitmap width, in pixels.

nHeight	Specifies the bitmap height, in pixels.

Returns

If the function succeeds, the return value is a handle of the bitmap; otherwise, it is NULL.

Comments

The color format of the bitmap created by this function matches the color format of the device identified by the hdc parameter. This bitmap can be selected into any memory DC that is compatible with the original device.

Because memory DCs allow both color and monochrome bitmaps, the format of the bitmap returned by the CreateCompatibleBitmap function differs when the specified DC is a memory DC. However, a compatible bitmap that was created for a nonmemory DC always possesses the same color format and uses the same color palette as the specified DC.

See Also

DeleteObject, SelectObject


CreateCompatibleDC function
CreateCompatibleDC (Win32)

HDC CreateCompatibleDC(hdc)

HDC hdc;	/* handle of memory device context	*/

The CreateCompatibleDC function creates a memory device context (DC) compatible with the given device.

Parameter	Description

hdc	Identifies the device context. If this handle is NULL, the function creates a memory device context compatible with the application's current screen.

Returns

If the function succeeds, the return value is the handle of a memory device context; otherwise, it is NULL.

Comments

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 DC. Once a bitmap has been selected, the DC can be used to prepare images that will be copied to the screen or printed.

This 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 a memory DC is no longer needed, an application must delete it by calling the DeleteDC function.

See Also

CreateCompatibleBitmap, DeleteDC, GetDeviceCaps


CreateDC function
CreateDC (Win32)

HDC CreateDC(lpszDriver, lpszDevice, lpszOutput, lpInitData)

LPCTSTR lpszDriver;	/* address of string specifying driver name	*/
LPCTSTR lpszDevice;	/* address of string specifying device name	*/
LPCTSTR lpszOutput;	/* address of string specifying port or file	*/
CONST DEVMODE *lpInitData;	/* address of optional printer data	*/

The CreateDC function creates a device context (DC) for the specified device by using the given name.

Parameter	Description

lpszDriver	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". This parameter is ignored; it is present only to keep the function prototype identical with Windows 3.1.

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. This parameter is ignored; it is present only to keep the function prototype identical with Windows 3.1.

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 given device. The lpInitData parameter must be NULL if the device driver is to use the default initialization (if any) specified by the user through Windows Print Manager.

Returns

If the function succeeds, the return value is the handle of a device context for the specified device; otherwise, it is NULL.

See Also

DocumentProperties, DEVMODE


CreateDIBitmap function
CreateDIBitmap (Win32)

HBITMAP CreateDIBitmap(hdc, lpbmih, fdwInit, lpbInit, lpbmi, fuUsage)

HDC hdc;	/* handle of device context	*/
CONST BITMAPINFOHEADER * lpbmih;	/* address of bitmap size and format data	*/
DWORD fdwInit;	/* initialization flag	*/
CONST VOID *lpbInit;	/* address of initialization data	*/
CONST BITMAPINFO * lpbmi;	/* address of bitmap color-format data	*/
UINT fuUsage;	/* color-data usage	*/

The CreateDIBitmap function creates a device-dependent bitmap (DDB) from a device-independent bitmap (DIB) and, optionally, sets the bitmap bits.

Parameter	Description

hdc	Identifies a device context.

lpbmih	Points to a BITMAPINFOHEADER structure.

If fdwInit has the value CBM_INIT, the function uses the BITMAPINFOHEADER structure to obtain, among other information, the desired width and height of the bitmap. This scenario is compatible with the Windows 3.1 CreateDIBitmap function.

If fdwInit has the value CBM_CREATEDIB, the function ignores the lpbmih parameter. The parameter may be NULL. This scenario is new for the Win32 API set.

fdwInit	Specifies how the bitmap is to be created. This parameter must be one of the following values:

Value	Meaning

CBM_CREATEDIB	The color format of the bitmap being created matches the color format specified in the structure pointed to by the lpbmi parameter. If this flag is not specified, the bitmap is assumed to be compatible with the device associated with the device context identified by the hdc parameter.

CBM_INIT	The data pointed to by the lpbInit and lpbmi parameters is to be used to initialize the bitmap. If this flag is not specified, the data is not used.

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 data 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	The color table consists of an array of 16-bit indices into the logical palette of the DC into which the bitmap is to be selected.

DIB_PAL_INDICES	There is no color table for the bitmap. The bitmap bits are indices into the device's physical palette, not the currently selected logical palette.

DIB_RGB_COLORS	The color table contains literal RGB values.

Returns

If the function succeeds, the return value is a handle of the bitmap; otherwise, it is NULL.

Comments

In order for a device to reach optimal bitmap drawing speed, the bitmap bits must be indices into the device's physical palette (and DIB_PAL_INDICES must be specified as the usage argument). Applications that create bitmaps in this format must use the colors from the device's physical palette. These colors are obtained by calling the GetSystemPaletteEntries function and are valid only when the application window is the active window. For more information about color and palettes, see Colors and Color Palettes.

See Also

DeleteObject, GetDeviceCaps, GetSystemPaletteEntries, SelectObject, BITMAPINFO, BITMAPINFOHEADER


CreateDIBPatternBrush function
CreateDIBPatternBrush (Win32)

HBRUSH CreateDIBPatternBrush(hglbDIBPacked, fuColorSpec)

HGLOBAL hglbDIBPacked;	/* handle of device-independent bitmap	*/
UINT fuColorSpec;	/* color table data	*/

The CreateDIBPatternBrush function creates a logical brush that has the pattern specified by the given device-independent bitmap (DIB). The brush can subsequently be selected into any device context (DC) 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 applications written with the Win32 API, use the CreateDIBPatternBrushPt.

Parameter	Description

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.

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 DC that the brush is to be selected into.

DIB_RGB_COLORS	A color table is provided and contains literal RGB values.

DIB_PAL_INDICES	No color table is provided. The bitmap itself contains indices into the logical palette of the DC that the brush is to be selected into.

Returns

If the function succeeds, the return value identifies a logical brush; otherwise, it is NULL.

Comments

When an application selects a two-color DIB pattern brush into a monochrome DC, 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 DC. 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.

See Also

CreateDIBPatternBrushPt, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, SetBkColor, SetTextColor, BITMAPINFO


CreateDIBPatternBrushPt function
CreateDIBPatternBrushPt (Win32)

HBRUSH CreateDIBPatternBrushPt(lpPackedDIB, iUsage)

CONST VOID * lpPackedDIB;	/* address of structure and bitmap bits	*/
UINT iUsage;	/* usage flags	*/

The CreateDIBPatternBrushPt function creates a logical brush that has the pattern specified by the device-independent bitmap (DIB).

Parameter	Description

lpPackedDIB	Points to a packed DIB consisting of a BITMAPINFO structure immediately followed by an array of bytes defining the pixels of the bitmap.

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 DC into which the brush is to be selected.

DIB_RGB_COLORS	A color table is provided and contains literal RGB values.

DIB_PAL_INDICES	No color table is provided. The bitmap itself contains indices into the logical palette of the DC into which the brush is to be selected.

Returns

If the function succeeds, the return value identifies a logical brush; otherwise, it is NULL.

Comments

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 DC by calling the SelectObject function.

See Also

CreateDIBPatternBrush, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, DeleteObject, GetBrushOrgEx, SelectObject, SetBrushOrgEx, BITMAPINFO


CreateDIBSection function
CreateDIBSection (Win32)

The CreateDIBSection function is not implemented for the first release of Windows NT.


CreateDiscardableBitmap function
CreateDiscardableBitmap (Win32)

HBITMAP CreateDiscardableBitmap(hDC, nWidth, nHeight)

HDC hDC;	/* handle of device context	*/
int nWidth;	/* bitmap width	*/
int nHeight;	/* bitmap height	*/

The CreateDiscardableBitmap function creates a discardable bitmap that is compatible with the given 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 given device.

The CreateDiscardableBitmap function is included only for compatibility with earlier versions of Windows. For Win32 applications, use the CreateCompatibleBitmap function.

Parameter	Description

hDC	Identifies a device context.

nWidth	Specifies the width, in bits, of the bitmap.

nHeight	Specifies the height, in bits, of the bitmap.

Returns

If the function succeeds, the return value is a handle of the bitmap; otherwise, it is NULL.

See Also

CreateCompatibleBitmap


CreateEllipticRgn function
CreateEllipticRgn (Win32)

HRGN CreateEllipticRgn(nLeftRect, nTopRect, nRightRect, nBottomRect)

int nLeftRect;	/* x-coordinate upper left corner bounding rectangle	*/
int nTopRect;	/* y-coordinate upper left corner bounding rectangle	*/
int nRightRect;	/* x-coordinate lower right corner bounding rectangle	*/
int nBottomRect;	/* y-coordinate lower right corner bounding rectangle	*/

The CreateEllipticRgn function creates an elliptical region.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the handle of the region; otherwise, it is NULL.

Comments

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 function
CreateEllipticRgnIndirect (Win32)

HRGN CreateEllipticRgnIndirect(lprc)

CONST RECT *lprc;	/* address of structure defining bounding rectangle	*/

The CreateEllipticRgnIndirect function creates an elliptical region.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the handle of the region; otherwise, it is NULL.

Comments

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, SelectObject


CreateEnhMetaFile function
CreateEnhMetaFile (Win32)

HDC CreateEnhMetaFile(hdcRef, lpFilename, lpRect, lpDescription)

HDC hdcRef;	/* handle of a reference device context	*/
LPCTSTR lpFilename;	/* address of a filename string	*/
CONST RECT * lpRect;	/* address of a bounding rectangle	*/
LPCTSTR lpDescription;	/* address of an optional description string	*/

The CreateEnhMetaFile function creates a device context (DC) for an enhanced-format metafile. This DC can be used to store a device-independent picture.

Parameter	Description

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.

Returns

If the function succeeds, the return value is a handle of the device context for the enhanced metafile; otherwise, it is NULL.

Comments

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 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 DC created by this function to store a graphics picture in an enhanced metafile. The handle identifying this DC 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 DC.

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


CreateFont function
CreateFont (Win32)

HFONT CreateFont(nHeight, nWidth, nEscapement, nOrientation, fnWeight, fdwItalic, fdwUnderline, fdwStrikeOut, fdwCharSet, fdwOutputPrecision, fdwClipPrecision, fdwQuality, fdwPitchAndFamily, lpszFace)

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;	/* address of typeface name string	*/

The CreateFont function creates a logical font that has specific characteristics. The logical font can subsequently be selected as the font for any device.

Parameter	Description

nHeight	Specifies the desired height, in logical units, of the requested font's character cell or character. (The character height value is the character cell height value minus the the internal-leading value.) If this value is greater than zero, the font mapper matches it against available character cell height values; if this value is zero, the font mapper uses a default height value when it searches for a match; if this value is less than zero, the font mapper matches it against available character height values.

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.

nOrientation	Specifies the angle, in tenths of degrees, between each character's base line and the x-axis of the device.

fnWeight	Specifies the desired weight of the font. (If this value is zero, a default weight is used.) This parameter can be one of the following values:

Value	Weight

FW_DONTCARE	0

FW_THIN	100

FW_EXTRALIGHT	200

FW_LIGHT	300

FW_NORMAL	400

FW_MEDIUM	500

FW_SEMIBOLD	600

FW_BOLD	700

FW_EXTRABOLD	800

FW_HEAVY	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 desired character set. The following values are predefined:

ANSI_CHARSET

UNICODE_CHARSET

SYMBOL_CHARSET

SHIFTJIS_CHARSET

HANGEUL_CHARSET

CHINESEBIG5_CHARSET

OEM_CHARSET

The OEM character set is operating-system dependent.

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.

fdwOutputPrecision	Specifies the desired output precision. The output precision defines how closely the output must match the requested font's height, width, character orientation, escapement, and pitch. It can be one of the following values:

OUT_DEFAULT_PRECIS

OUT_STRING_PRECIS

OUT_CHARACTER_PRECIS

OUT_STROKE_PRECIS

OUT_TT_PRECIS

OUT_DEVICE_PRECIS

OUT_RASTER_PRECIS

OUT_TT_ONLY_PRECIS

OUT_OUTLINE_PRECIS

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 a 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_PRECIS forces the font mapper to choose a TrueType font for a specified a device or raster font, even if there is no TrueType font of the same name.)

fdwClipPrecision	Specifies the desired 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:

CLIP_DEFAULT_PRECIS

CLIP_CHARACTER_PRECIS

CLIP_STROKE_PRECIS

CLIP_MASK

CLIP_LH_ANGLES

CLIP_TT_ALWAYS

CLIP_EMBEDDED

To use an embedded read-only font, applications must specify CLIP_ENCAPSULATE.

To achieve consistent rotation of device, TrueType, and vector fonts, an application can use the OR operator to combine the CLIP_LH_ANGLES value with any of the other fdwClipPrecision values. If the CLIP_LH_ANGLES bit is set, the rotation for all fonts depends on whether the orientation of the coordinate system is left-handed or right-handed. If CLIP_LH_ANGLES is not set, 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.)

fdwQuality	Specifies the desired 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. 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. 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

Applications can set bit 2 (0x04) of the fdwPitchAndFamily parameter to choose a TrueType font.

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. The EnumFonts function can be used to enumerate the typeface names of all currently available fonts.

Returns

If the function succeeds, the return value is a handle of a logical font; otherwise, it is NULL. To get extended error information, use the GetLastError function.

See Also

DeleteObject, SelectObject


CreateFontIndirect function
CreateFontIndirect (Win32)

HFONT CreateFontIndirect(lplf)

CONST LOGFONT *lplf;	/* address of logical font structure	*/

The CreateFontIndirect function creates a logical font that has the characteristics specified in the given structure. The font can subsequently be selected as the current font for any device context.

Parameter	Description

lplf	Points to a LOGFONT structure that defines the characteristics of the logical font.

Returns

If the function succeeds, the return value is a handle of a logical font; otherwise, it is NULL.

Comments

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.

See Also

DeleteObject, SelectObject


CreateHalftonePalette function
CreateHalftonePalette (Win32)

HPALETTE CreateHalftonePalette(hdc)

HDC hdc;	/* handle of device context	*/

The CreateHalftonePalette function creates a halftone palette for the specified device context.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value identifies a logical halftone palette; otherwise, it is 0. To get extended error information, use the GetLastError function.

Comments

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.

See Also

RealizePalette, SelectPalette, SetStretchBltMode


CreateHatchBrush function
CreateHatchBrush (Win32)

HBRUSH CreateHatchBrush(fnStyle, clrref)

int fnStyle;	/* hatch style	*/
COLORREF clrref;	/* color value	*/

The CreateHatchBrush function creates a logical brush that has the specified hatch pattern and color.

Parameter	Description

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.

Returns

If the function succeeds, the return value identifies a logical brush; otherwise, it is NULL.

Comments

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 (DC) 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.

See Also

CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreatePatternBrush, CreateSolidBrush, DeleteObject, GetBrushOrgEx, SelectObject, SetBrushOrgEx, RGB


CreateIC function
CreateIC (Win32)

HDC CreateIC(lpszDriver, lpszDevice, lpszOutput, lpdvmInit)

LPCTSTR lpszDriver;	/* address of string specifying driver name	*/
LPCTSTR lpszDevice;	/* address of string specifying device name	*/
LPCTSTR lpszOutput;	/* address of string specifying port or file name	*/
CONST DEVMODE * lpdvmInit;	/* address of optional initialization data	*/

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.

Parameter	Description

lpszDriver	Points to a null-terminated character string that specifies the name of the device driver (for example, "Epson"). This parameter is ignored; it is present only to keep the function prototype identical with Windows 3.1.

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 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 given device. The lpdvmInit parameter must be NULL if the device driver is to use the default initialization (if any) specified by the user through Windows Print Manager.

Returns

If the function succeeds, the return value is the handle of an information context; otherwise, it is NULL.

Comments

An error occurs if an application calls a GDI drawing function and supplies a handle identifying an information context.

See Also

DocumentProperties, GetDeviceCaps, DEVMODE


CreateMetaFile function
CreateMetaFile (Win32)

HDC CreateMetaFile(lpszFile)

LPCTSTR lpszFile;	/* address of filename string	*/

The CreateMetaFile function creates a device context (DC) for a Windows-format metafile.

This function is provided for compatibility with earlier versions of Microsoft Windows. For Win32 applications, use the CreateEnhMetaFile function.

Parameter	Description

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.

Returns

If the function succeeds, the return value is a handle of the device context for the Windows-format metafile; otherwise, it is NULL.

Comments

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.

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 DC 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, DeleteMetaFile, GetTextColor, PolyBezier, SelectClipRgn


CreatePalette function
CreatePalette (Win32)

HPALETTE CreatePalette(lplgpl)

CONST LOGPALETTE *lplgpl;	/* address of logical color palette	*/

The CreatePalette function creates a logical color palette.

Parameter	Description

lplgpl	Points to a LOGPALETTE structure that contains information about the colors in the logical palette.

Returns

If the function succeeds, the return value is a handle that identifies a logical palette; otherwise it is NULL. To get extended error information, use the GetLastError function.

Comments

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.

See Also

GetDeviceCaps, RealizePalette, SelectPalette, LOGPALETTE


CreatePatternBrush function
CreatePatternBrush (Win32)

HBRUSH CreatePatternBrush(hbmp)

HBITMAP hbmp;	/* handle of bitmap	*/

The CreatePatternBrush function creates a logical brush with the specified bitmap pattern.

Parameter	Description

hbmp	Identifies the bitmap to be used to create the logical brush.

Returns

If the function succeeds, the return value identifies a logical brush; otherwise, it is NULL.

Comments

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 (DC) 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 DC 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.

See Also

CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateHatchBrush, DeleteObject, GetBrushOrgEx, LoadBitmap, SelectObject, SetBrushOrgEx


CreatePen function
CreatePen (Win32)

HPEN CreatePen(fnPenStyle, nWidth, crColor)

int fnPenStyle;	/* pen style	*/
int nWidth;	/* pen width	*/
COLORREF crColor;	/* pen color	*/

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.

Parameter	Description

fnPenStyle	Specifies the pen style. It can be any one of the following values:

Value	Meaning

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

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.

Returns

If the function succeeds, the return value is a handle that identifies a logical pen; otherwise, it is NULL.

Comments

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 an application no longer requires a given pen, it should call the DeleteObject function to delete the pen from the device context.

See Also

CreatePenIndirect, DeleteObject, ExtCreatePen, GetObject, RGB, SelectObject


CreatePenIndirect function
CreatePenIndirect (Win32)

HPEN CreatePenIndirect(lplgpn)

CONST LOGPEN * lplgpn;	/* address of LOGPEN structure	*/

The CreatePenIndirect function creates a logical cosmetic pen that has the style, width, and color specified in the given structure.

Parameter	Description

lplgpn	Points to the LOGPEN structure that specifies the pen's style, width, and color.

Returns

If the function succeeds, the return value is a handle that identifies a logical cosmetic pen; otherwise, it is NULL.

Comments

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 an application no longer requires a given pen, it should call the DeleteObject function to delete the pen from the device context.

See Also

CreatePen, DeleteObject, ExtCreatePen, GetObject, RGB, SelectObject, LOGPEN


CreatePolygonRgn function
CreatePolygonRgn (Win32)

HRGN CreatePolygonRgn(lppt, cPoints, fnPolyFillMode)

CONST POINT *lppt;	/* address of array of points	*/
int cPoints;	/* number of points in array	*/
int fnPolyFillMode;	/* polygon-filling mode	*/

The CreatePolygonRgn function creates a polygonal region.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the handle of the region; otherwise, it is NULL.

See Also

CreatePolyPolygonRgn, DeleteObject, SelectObject, SetPolyFillMode


CreatePolyPolygonRgn function
CreatePolyPolygonRgn (Win32)

HRGN CreatePolyPolygonRgn(lppt, lpPolyCounts, nCount, fnPolyFillMode)

CONST POINT *lppt;	/* address of array of points	*/
CONST INT *lpPolyCounts;	/* address of array that contains vertex counts	*/
int nCount;	/* number of integers in array of vertex counts	*/
int fnPolyFillMode;	/* polygon fill mode	*/

The CreatePolyPolygonRgn function creates a region consisting of a series of polygons. The polygons can overlap.

Parameter	Description

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 lppt array.

nCount	Specifies the total number of integers in the lpPolyCounts 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.

Returns

If the function succeeds, the return value is the handle of the region; otherwise, it is 0.

See Also

CreatePolygonRgn, DeleteObject, SelectObject, SetPolyFillMode


CreateRectRgn function
CreateRectRgn (Win32)

HRGN CreateRectRgn(nLeftRect, nTopRect, nRightRect, nBottomRect)

int nLeftRect;	/* x-coordinate of upper left corner	*/
int nTopRect;	/* y-coordinate of upper left corner	*/
int nRightRect;	/* x-coordinate of lower right corner	*/
int nBottomRect;	/* y-coordinate of lower right corner	*/

The CreateRectRgn function creates a rectangular region.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the handle of the region; otherwise, it is NULL.

Comments

The region will be exclusive of the bottom and right edges.

See Also

CreateRectRgnIndirect, CreateRoundRectRgn, DeleteObject, SelectObject


CreateRectRgnIndirect function
CreateRectRgnIndirect (Win32)

HRGN CreateRectRgnIndirect(lprc)

CONST RECT *lprc;	/* address of the rectangle	*/

The CreateRectRgnIndirect function creates a rectangular region.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the handle of the region; otherwise, it is NULL.

Comments

The region will be exclusive of the bottom and right edges.

See Also

CreateRectRgn, CreateRoundRectRgn, DeleteObject, SelectObject


CreateRoundRectRgn function
CreateRoundRectRgn (Win32)

HRGN CreateRoundRectRgn(nLeftRect, nTopRect, nRightRect, nBottomRect, nWidthEllipse, nHeightEllipse)

int nLeftRect;	/* x-coordinate upper left corner of region	*/
int nTopRect;	/* y-coordinate upper left corner of region	*/
int nRightRect;	/* x-coordinate lower right corner of region	*/
int nBottomRect;	/* y-coordinate lower right corner of region	*/
int nWidthEllipse;	/* height of ellipse for rounded corners	*/
int nHeightEllipse;	/* width of ellipse for rounded corners	*/

The CreateRoundRectRgn function creates a rectangular region with rounded corners.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the handle of the region; otherwise, it is NULL.

See Also

CreateRectRgn, CreateRectRgnIndirect, DeleteObject, SelectObject


CreateScalableFontResource function
CreateScalableFontResource (Win32)

BOOL CreateScalableFontResource(fdwHidden, lpszFontRes, lpszFontFile, lpszCurrentPath)

DWORD fdwHidden;	/* flag for read-only embedded font	*/
LPCTSTR lpszFontRes;	/* address of filename for font resource	*/
LPCTSTR lpszFontFile;	/* address of filename for scalable font	*/
LPCTSTR lpszCurrentPath;	/* address of path to font file	*/

The CreateScalableFontResource function creates a font resource file for a scalable font.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


CreateSolidBrush function
CreateSolidBrush (Win32)

HBRUSH CreateSolidBrush(crColor)

COLORREF crColor;	/* brush color value	*/

The CreateSolidBrush function creates a logical brush that has the specified solid color.

Parameter	Description

crColor	Specifies the color of the brush.

Returns

If the function succeeds, the return value identifies a logical brush; otherwise the return value is NULL.

Comments

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 (DC) by calling the SelectObject function.

See Also

CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateHatchBrush, CreatePatternBrush, DeleteObject, SelectObject, RGB


DeleteDC function
DeleteDC (Win32)

BOOL DeleteDC(hdc)

HDC hdc;	/* handle of device context	*/

The DeleteDC function deletes the given device context.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 function
DeleteEnhMetaFile (Win32)

BOOL DeleteEnhMetaFile(hemf)

HENHMETAFILE hemf;	/* handle of an enhanced metafile	*/

The DeleteEnhMetaFile function deletes an enhanced-format metafile or an enhanced-format metafile handle.

Parameter	Description

hemf	Identifies an enhanced metafile.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

If the hemf parameter identifies an enhanced metafile stored in memory, this 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


DeleteMetaFile function
DeleteMetaFile (Win32)

BOOL DeleteMetaFile(hmf)

HMETAFILE hmf;	/* handle of Windows-format metafile	*/

The DeleteMetaFile function deletes a Windows-format metafile or Windows-format metafile handle.

This function is provided for compatibility with earlier versions of Microsoft Windows. For Win32 applications, use the DeleteEnhMetaFile function.

Parameter	Description

hmf	Identifies a Windows-format metafile.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 contents are lost when it is deleted by using the DeleteMetaFile function.

See Also

BeginPath, CopyMetaFile, CreateMetaFile, GetMetaFile, PolyBezier, SetWorldTransform


DeleteObject function
DeleteObject (Win32)

BOOL DeleteObject(hObject)

HGDIOBJ hObject;	/* handle of graphic object	*/

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 given handle is no longer valid.

Parameter	Description

hObject	Identifies a logical pen, brush, font, bitmap, region, or palette.

Returns

If the function succeeds, the return value is TRUE. If the given handle is not valid or is currently selected into a device context, the return value is FALSE.

Comments

The object to be deleted must not be currently 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


DeviceCapabilities function
DeviceCapabilities (Win32)

DWORD DeviceCapabilities(pDevice, pPort, fwCapability, pOutput, pDevMode)

LPCTSTR pDevice;	/* address of device-name string	*/
LPCTSTR pPort;	/* address of port-name string	*/
WORD fwCapability;	/* device capability to query	*/
LPTSTR pOutput;	/* address of the output	*/
CONST DEVMODE * pDevMode;	/* address of structure with device data	*/

The DeviceCapabilities function retrieves the capabilities of a printer device driver.

Parameter	Description

pDevice	Points to a null-terminated string that contains the name of a printer device, such as PCL/HP LaserJet.

pPort	Points 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_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_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_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 fields 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 POINT structure containing the maximum paper size that the dmPaperLength and dmPaperWidth members of the printer driver's DEVMODE structure can specify.

DC_MINEXTENT	Returns a POINT structure containing the minimum paper size that the dmPaperLength and dmPaperWidth members of the printer driver's DEVMODE structure can specify.

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 lpszOutput 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. The return value can be one or more of the following:

Value	Meaning

DCTT_BITMAP	Device is capable of printing TrueType fonts as graphics. (For example, dot-matrix and PCL printers.)

DCTT_DOWNLOAD	Device is capable of downloading TrueType fonts. (For example, PCL and PostScript printers.)

DCTT_SUBDEV	Device is capable of substituting device fonts for TrueType fonts. (For example, PostScript printers.)

For DC_TRUETYPE, the lpszOutput parameter should be NULL.

DC_VERSION	Returns the specification version to which the printer driver conforms.

pOutput	Points 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	Points 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.

Returns

If the function succeeds, the return value depends on the setting of the fwCapability parameter. The return value is -1 if the function fails.

See Also

GetDeviceCaps, GetProcAddress, LoadLibrary


DC_BINNAMES
DC_BINNAMES  12  wingdi.h

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.


FN_DC_BINNAMES
DC_BINNAMES  12  wingdi.h


DC_BINS
DC_BINS  6  wingdi.h

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.


FN_DC_BINS
DC_BINS  6  wingdi.h


DC_COPIES

Returns the number of copies the device can print.


DC_DRIVER
DC_DRIVER  11  wingdi.h

Returns the version number of the printer driver.


FN_DC_DRIVER
DC_DRIVER  11  wingdi.h


DC_DUPLEX
DC_DUPLEX  7  wingdi.h

Returns the level of duplex support. The function returns 1 if the printer is capable of duplex printing. Otherwise, the return value is zero.


FN_DC_DUPLEX
DC_DUPLEX  7  wingdi.h


DC_ENUMRESOLUTIONS
DC_ENUMRESOLUTIONS  13  wingdi.h

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


FN_DC_ENUMRESOLUTIONS
DC_ENUMRESOLUTIONS  13  wingdi.h


DC_EXTRA
DC_EXTRA  9  wingdi.h

Returns the number of bytes required for the device-specific portion of the DEVMODE structure for the printer driver.


FN_DC_EXTRA
DC_EXTRA  9  wingdi.h


DC_FIELDS
DC_FIELDS  1  wingdi.h

Returns the dmFields member of the printer driver's DEVMODE structure. The dmFields member indicates which fields in the device-independent portion of the structure are supported by the printer driver.


FN_DC_FIELDS
DC_FIELDS  1  wingdi.h


DC_FILEDEPENDENCIES
DC_FILEDEPENDENCIES  14  wingdi.h

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.


FN_DC_FILEDEPENDENCIES
DC_FILEDEPENDENCIES  14  wingdi.h


DC_MAXEXTENT
DC_MAXEXTENT  5  wingdi.h

Returns a POINT structure containing the maximum paper size that the dmPaperLength and dmPaperWidth members of the printer driver's DEVMODE structure can specify.


FN_DC_MAXEXTENT
DC_MAXEXTENT  5  wingdi.h


DC_MINEXTENT
DC_MINEXTENT  4  wingdi.h

Returns a POINT structure containing the minimum paper size that the dmPaperLength and dmPaperWidth members of the printer driver's DEVMODE structure can specify.


FN_DC_MINEXTENT
DC_MINEXTENT  4  wingdi.h


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:


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
DC_PAPERS  2  wingdi.h

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.


FN_DC_PAPERS
DC_PAPERS  2  wingdi.h


DC_PAPERSIZE
DC_PAPERSIZE  3  wingdi.h

Copies the dimensions of all supported paper sizes, in tenths of a millimeter, to an array of POINT structures pointed to by the lpszOutput 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.


FN_DC_PAPERSIZE
DC_PAPERSIZE  3  wingdi.h


DC_SIZE
DC_SIZE  8  wingdi.h

Returns the dmSize member of the printer driver's DEVMODE structure.


FN_DC_SIZE
DC_SIZE  8  wingdi.h


DC_TRUETYPE

Retrieves the abilities of the driver to use TrueType fonts. The return value can be one or more of the following:


DC_VERSION
DC_VERSION  10  wingdi.h

Returns the specification version to which the printer driver conforms.


FN_DC_VERSION
DC_VERSION  10  wingdi.h


DeviceCapabilitiesEx function
DeviceCapabilitiesEx (Win32)

The DeviceCapabilitiesEx function is not implemented for the first release of Windows NT. It is exported, so that applications based on pre-release versions of Windows NT will load, but nothing happens when it is called. Applications should use the DeviceCapabilities function.

See Also

DeviceCapabilities, GetDeviceCaps


DPtoLP function
DPtoLP (Win32)

BOOL DPtoLP(hdc, lpPoints, nCount)

HDC hdc;	/* handle of device context	*/
LPPOINT lpPoints;	/* address of array of points	*/
int nCount;	/* count of points	*/

The DPtoLP function converts device coordinates into logical coordinates. The conversion depends on the mapping mode of the device context (DC), the settings of the origins and extents for the window and viewport, and the world transformation.

Parameter	Description

hdc	Identifies the DC.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

This 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


DrawEscape function
DrawEscape (Win32)

int DrawEscape(hdc, nEscape, cbInput, lpszInData)

HDC hdc;	/* handle of device context	*/
int nEscape;	/* specifies escape function	*/
int cbInput;	/* size of structure for input	*/
LPCSTR lpszInData;	/* address of structure for input	*/

The DrawEscape function accesses drawing capabilities of a video display that are not directly available through the graphics device interface (GDI).

Parameter	Description

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.

Returns

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. Use the GetLastError function to obtain extended error information.

Comments

When an application calls the DrawEscape function, the data identified by cbInput and lpszInData is passed directly to the specified display driver.


Ellipse function
Ellipse (Win32)

BOOL Ellipse(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect)

HDC hdc;	/* handle of device context	*/
int nLeftRect;	/* x-coord. of bounding rect. upper-left corner	*/
int nTopRect;	/* y-coord. of bounding rect. upper-left corner	*/
int nRightRect;	/* x-coord. of bounding rect. lower-right corner	*/
int nBottomRect;	/* y-coord. of bounding rect. lower-right corner	*/

The Ellipse function draws an ellipse. The center of the ellipse is the center of the given bounding rectangle. The ellipse is outlined by using the current pen and is filled by using the current brush.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The current position is neither used nor updated by this function.

See Also

Arc, ArcTo


EndDoc function
EndDoc (Win32)

int EndDoc(hdc)

HDC hdc;	/* handle of device context	*/

The EndDoc function ends a print job. This function replaces the ENDDOC printer escape.

Parameter	Description

hdc	Identifies the device context for the print job.

Returns

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, use the GetLastError function.

Comments

Applications should call the EndDoc function immediately after finishing a print job.

See Also

StartDoc


EndPage function
EndPage (Win32)

int EndPage(hdc)

HDC hdc;	/* handle of device context	*/

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.

Parameter	Description

hdc	Identifies the device context for the print job.

Returns

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is SP_ERROR. Use GetLastError to obtain extended error information.

Comments

Use the ResetDC function to change the device mode, if necessary, after calling the EndPage function.

See Also

ResetDC, StartPage


EndPath function
EndPath (Win32)

BOOL EndPath(hdc)

HDC hdc;	/* handle of device context	*/

The EndPath function closes a path bracket and selects the path defined by the bracket into the given device context (DC).

Parameter	Description

hdc	Identifies the DC into which the new path is selected.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. Use the GetLastError function to get the error value, which can be one of the following:

ERROR_CAN_NOT_COMPLETE

ERROR_INVALID_PARAMETER

See Also

BeginPath


EnumEnhMetaFile function
EnumEnhMetaFile (Win32)

BOOL EnumEnhMetaFile(hdc, hemf, lpEnhMetaFunc, lpData, lpRect)

HDC hdc;	/* handle of device context	*/
HENHMETAFILE hemf;	/* handle of enhanced metafile	*/
ENHMFENUMPROC lpEnhMetaFunc;	/* address of callback function	*/
LPVOID lpData;	/* address of callback-function data	*/
CONST RECT * lpRect;	/* address of bounding rectangle	*/

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.

Parameter	Description

hdc	Identifies a device context (DC). 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 description of 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.

Returns

If the callback function successfully enumerates all the records in the enhanced metafile, the return value is TRUE; otherwise, it is FALSE.

Comments

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 DC's transformation and mapping mode to transform the picture displayed by the PlayEnhMetaFileRecord function. If hdc is NULL, the picture is not transformed and will appear distorted.

You can use the EnumEnhMetaFile function to embed one enhanced-metafile within another.

See Also

EnhMetaFileProc, PlayEnhMetaFile, PlayEnhMetaFileRecord


EnumFontFamilies function
EnumFontFamilies (Win32)

int EnumFontFamilies(hdc, lpszFamily, lpEnumFontFamProc, lParam)

HDC hdc;	/* handle of device control	*/
LPCTSTR lpszFamily;	/* address of family-name string	*/
FONTENUMPROC lpEnumFontFamProc;	/* address of callback function	*/
LPARAM lParam;	/* address of application-supplied data	*/

The EnumFontFamilies function enumerates the fonts in a specified font family that are available on a given device.

Parameter	Description

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 description of the EnumFontFamProc function.

lParam	Points to application-supplied data. The data is passed to the callback function along with the font information.

Returns

If the function succeeds, the return value is the last value returned by the callback function. Its meaning is implementation specific.

Comments

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


EnumFonts function
EnumFonts (Win32)

int EnumFonts(hdc, lpFaceName, lpFontFunc, lParam)

HDC hdc;	/* handle of device context	*/
LPCTSTR lpFaceName;	/* address of font typeface name string	*/
FONTENUMPROC lpFontFunc;	/* address of callback function	*/
LPARAM lParam;	/* address of application-supplied data	*/

The EnumFonts function enumerates the fonts available on a given device. For each font with the specified typeface name, the EnumFonts function retrieves information about that font and passes it to the application-supplied 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.

Parameter	Description

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-supplied callback function. For more information about the callback function, see the description of the EnumFontsProc function.

lParam	Points to any application-supplied data. The data is passed to the callback function along with the font information.

Returns

If the function succeeds, the return value is the last value returned by the callback function. Its meaning is defined by the application.

See Also

EnumFontFamilies, EnumFontsProc, GetDeviceCaps


EnumMetaFile function
EnumMetaFile (Win32)

BOOL EnumMetaFile(hdc, hmf, lpMetaFunc, lParam)

HDC hdc;	/* handle of device context	*/
HMETAFILE hmf;	/* handle of Windows-format metafile	*/
MFENUMPROC lpMetaFunc;	/* address of callback function	*/
LPARAM lParam;	/* address of callback function data	*/

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. For Win32 applications, use EnumEnhMetaFile function.

Parameter	Description

hdc	Identifies a device context (DC). 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 description of the EnumMetaFileProc callback function.

lParam	Points to optional callback-function data.

Returns

If the callback function successfully enumerates all the records in the Windows-format metafile, the return value is TRUE; otherwise, it is FALSE.

Comments

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, EnumMetaFileProc, PlayMetaFile, PlayMetaFileRecord, PolyBezier, SetWinMetaFileBits, SetWorldTransform


EnumObjects function
EnumObjects (Win32)

int EnumObjects(hdc, nObjectType, lpObjectFunc, lParam)

HDC hdc;	/* handle of device context	*/
int nObjectType;	/* object-type identifier	*/
GOBJENUMPROC lpObjectFunc;	/* address of callback function	*/
LPARAM lParam;	/* address of application-supplied data	*/

The EnumObjects function enumerates the pens or brushes available for the given 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.

Parameter	Description

hdc	Identifies the device context.

nObjectType	Specifies the object type. This parameter can be OBJ_BRUSH or OBJ_PEN.

lpObjectFunc	The address of the application-defined callback function. For more information about the callback function, see the description of the EnumObjectsProc function.

lParam	Points to the application-defined data. The data is passed to the callback function along with the object information.

Returns

The return value specifies the last value returned by the callback function. Its meaning is user-defined.

See Also

GetObject, LOGPEN, LOGBRUSH


EqualRgn function
EqualRgn (Win32)

BOOL EqualRgn(hSrcRgn1, hSrcRgn2)

HRGN hSrcRgn1;	/* handle of first region	*/
HRGN hSrcRgn2;	/* handle of second region	*/

The EqualRgn function checks the two given regions to determine whether they are identical. The function considers two regions identical if they are equal in size and shape.

Parameter	Description

hSrcRgn1	Identifies a region.

hSrcRgn2	Identifies a region.

Returns

If the two regions are equal, the return value is TRUE; otherwise, it is FALSE. A return value of ERROR means at least one of the region handles is invalid.

See Also

CreateRectRgn, CreateRectRgnIndirect


Escape function
Escape (Win32)

int Escape(hdc, nEscape, cbInput, lpvInData, lpvOutData)

HDC hdc;	/* handle of device context	*/
int nEscape;	/* escape function	*/
int cbInput;	/* size of structure for input	*/
LPCSTR lpvInData;	/* address of input structure	*/
LPVOID lpvOutData;	/* address of output structure	*/

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.

Parameter	Description

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.

Returns

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. Otherwise, the return value is an error. To get extended error information, use the GetLastError function.

Errors

If the function fails, the return value is one of the following:

Value	Meaning

SP_ERROR	General error.

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	User terminated the job through Windows Print Manager.

Comments

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 ResetDC function was new for Windows version 3.1. ResetDC updates a device context, allowing such new functionality as changing the paper orientation or paper bin within a single print job. This ability was not supported by an escape in previous versions of Windows.

Following is a list of the obsolete printer escapes that are supported only for compatibility with earlier 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.


ExcludeClipRect function
ExcludeClipRect (Win32)

int ExcludeClipRect(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect)

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

The ExcludeClipRect function creates a new clipping region that consists of the existing clipping region minus the specified rectangle.

Parameter	Description

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.

Returns

If the function succeeds, the return value specifies the new clipping region's complexity. It 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.

Comments

The lower and right edges of the given rectangle are not excluded from the clipping region.

See Also

IntersectClipRect


ExtCreatePen function
ExtCreatePen (Win32)

HPEN ExtCreatePen(dwPenStyle, dwWidth, lplb, dwStyleCount, lpStyle)

DWORD dwPenStyle;	/* pen style	*/
DWORD dwWidth;	/* pen width	*/
CONST LOGBRUSH * lplb;	/* address of struc. for brush attributes	*/
DWORD dwStyleCount;	/* length of array containing custom style bits	*/
CONST DWORD * lpStyle;	/* optional array of custom style bits	*/

The ExtCreatePen function creates a logical cosmetic or geometric pen that has the specified style, width, and brush attributes.

Parameter	Description

dwPenStyle	Specifies a combination of type, style, end cap, and join attributes. The values from each category should be 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	Pen sets every other pixel. (This style is applicable only for cosmetic pens.)

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 alternating dashes and double dots.

PS_NULL	Pen is invisible.

PS_USERSTYLE	Pen uses a styling array supplied by the user.

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.

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.

Returns

If the function succeeds, the return value is a handle that identifies a logical pen; otherwise, it is zero.

Comments

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

When an application no longer requires a given pen, it should call the DeleteObject function to delete the pen from the device context.

See Also

CreatePen, CreatePenIndirect, DeleteObject, GetObject, SelectObject


ExtCreateRegion function
ExtCreateRegion (Win32)

HRGN ExtCreateRegion(lpXform, nCount, lpRgnData)

CONST XFORM * lpXform;	/* address of transformation data	*/
DWORD nCount;	/* size of structure containing region data	*/
CONST RGNDATA * lpRgnData;	/* address of region data	*/

The ExtCreateRegion function creates a region from the given region and transformation data.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the value of the region; otherwise, it is NULL.

Comments

An application can retrieve data for a region by calling the GetRegionData function.

See Also

GetRegionData


ExtEscape function
ExtEscape (Win32)

int ExtEscape(hdc, nEscape, cbInput, lpszInData, cbOutput, lpszOutData)

HDC hdc;	/* handle of device context	*/
int nEscape;	/* escape function	*/
int cbInput;	/* size of structure for input	*/
LPCSTR lpszInData;	/* address of input structure	*/
int cbOutput;	/* size, in bytes, of output data	*/
LPSTR lpszOutData;	/* address of output structure	*/

The ExtEscape function allows applications to access capabilities of a particular device that are not available through GDI.

Parameter	Description

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.

Returns

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, use the GetLastError function.

Comments

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.

See Also

Escape, GetDeviceCaps


ExtFloodFill function
ExtFloodFill (Win32)

BOOL ExtFloodFill(hdc, nXStart, nYStart, crColor, fuFillType)

HDC hdc;	/* handle of device context	*/
int nXStart;	/* x-coordinate where filling begins	*/
int nYStart;	/* y-coordinate where filling begins	*/
COLORREF crColor;	/* fill color	*/
UINT fuFillType;	/* fill type	*/

The ExtFloodFill function fills an area of the display surface with the current brush.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Following are some of the reasons this function might fail:

The filling could not be completed.

The given point has the boundary color specified by the crColor parameter (if FLOODFILLBORDER was requested).

The given 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, an application can call the GetDeviceCaps function.

See Also

GetDeviceCaps


ExtSelectClipRgn function
ExtSelectClipRgn (Win32)

int ExtSelectClipRgn(hdc, hrgn, fnMode)

HDC hdc;	/* handle of device context	*/
HRGN hrgn;	/* handle of region	*/
int fnMode;	/* region-selection mode	*/

The ExtSelectClipRgn function combines the given region with the current clipping region by using the specified mode.

Parameter	Description

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.

Returns

If the function succeeds, the return value specifies the new clipping region's complexity. It 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.

Comments

If an error occurs when this function is called, the previous clipping region for the given device context is not affected.

The ExtSelectClipRgn function assumes that the coordinates for the given region are specified in device units.

Only a copy of the given 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 function
ExtTextOut (Win32)

BOOL ExtTextOut(hdc, X, Y, fuOptions, lprc, lpszString, cbCount, lpDx)

HDC hdc;	/* handle of 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 lpszString;	/* address of string	*/
UINT cbCount;	/* number of characters in string	*/
CONST INT * lpDx;	/* address of array of inter-character spacing values	*/

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.

Parameter	Description

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_OPAQUE	The current background color should be used to fill the rectangle.

lprc	Points to an optional RECT structure that specifies the dimensions of a rectangle that is used to clip the string of text and/or to fill the text background by using the current background color.

lpszString	Points to the character string to be drawn.

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.

Returns

If the string is drawn, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 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 given device context. When this flag is set, Windows ignores the X and Y parameters on subsequent ExtTextOut calls.

See Also

GetTextAlign, SetTextAlign, RECT


FillPath function
FillPath (Win32)

BOOL FillPath(hdc)

HDC hdc;	/* handle of device context	*/

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.

Parameter	Description

hdc	Identifies a device context that contains a valid path.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. Use the GetLastError function to get the error value, which can be one of the following:

ERROR_CAN_NOT_COMPLETE

ERROR_INVALID_PARAMETER

ERROR_NOT_ENOUGH_MEMORY

Comments

After its interior is filled, the path is discarded from the device context identified by the hdc parameter.

See Also

BeginPath, SetPolyFillMode, StrokeAndFillPath, StrokePath,


FillRgn function
FillRgn (Win32)

BOOL FillRgn(hdc, hrgn, hbr)

HDC hdc;	/* handle of device context	*/
HRGN hrgn;	/* handle of region to be filled	*/
HBRUSH hbr;	/* handle of brush used to fill the region	*/

The FillRgn function fills the given region by using the given brush.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

CreateBrushIndirect, CreateDIBPatternBrush, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, PaintRgn


FixBrushOrgEx function
FixBrushOrgEx (Win32)

BOOL FixBrushOrgEx(hdc, nXOrg, nYOrg, lppt)

HDC hdc;	/* handle of device context	*/
int nXOrg;	/* an origin x-coordinate	*/
int nYOrg;	/* an origin y-coordinate	*/
LPPOINT lppt;	/* pointer to brush origin	*/

The FixBrushOrgEx function is not implemented for Win32. It is provided for compatibility with Win32s. If called, the function does nothing, and returns FALSE.

See Also

GetBrushOrgEx, SetBrushOrgEx


FlattenPath function
FlattenPath (Win32)

BOOL FlattenPath(hdc)

HDC hdc;	/* handle of device context	*/

The FlattenPath function transforms any curves in the path that is selected into the current device context, turning each curve into a sequence of lines.

Parameter	Description

hdc	Identifies a device context that contains a valid path.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. Use the GetLastError function to get the error value, which can be one of the following:

ERROR_CAN_NOT_COMPLETE

ERROR_INVALID_PARAMETER

ERROR_NOT_ENOUGH_MEMORY

See Also

WidenPath


FloodFill function
FloodFill (Win32)

BOOL FloodFill(hdc, nXStart, nYStart, crFill)

HDC hdc;	/* handle of device context	*/
int nXStart;	/* x-coord., where fill begins	*/
int nYStart;	/* y-coord., where fill begins	*/
COLORREF crFill;	/* fill color	*/

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 applications, use the ExtFloodFill function with FLOODFILLBORDER specified.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Following are reasons this function might fail:

The fill should 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


FrameRgn function
FrameRgn (Win32)

BOOL FrameRgn(hdc, hrgn, hbr, nWidth, nHeight)

HDC hdc;	/* handle of device context	*/
HRGN hrgn;	/* handle of region to be framed	*/
HBRUSH hbr;	/* handle of brush used to draw border	*/
int nWidth;	/* width of region frame	*/
int nHeight;	/* height of region frame	*/

The FrameRgn function draws a border around the given region by using the given brush.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

FillRgn, PaintRgn


GdiComment function
GdiComment (Win32)

BOOL GdiComment(hdc, cbSize, lpData)

HDC hdc;	/* handle of a device context	*/
UINT cbSize;	/* size of text buffer	*/
CONST BYTE * lpData;	/* address of text buffer	*/

The GdiComment function copies a comment from a buffer into a specified enhanced-format metafile.

Parameter	Description

hdc	Identifies a device context.

cbSize	Specifies the length of the comment buffer, in bytes.

lpData	Points to the buffer that contains the comment.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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

See Also

CreateEnhMetaFile, EMRFORMAT


GdiFlush function
GdiFlush (Win32)

BOOL GdiFlush(VOID)

The GdiFlush function flushes the calling thread's current batch.

Returns

If all functions in the current batch succeed, the return value is TRUE; otherwise, it is FALSE, indicating that at least one function returned an error.

Comments

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.

A multi-threaded application that serializes access to GDI objects with a mutex must be sure to flush the GDI batch queue by calling GdiFlush as each thread releases ownership of the GDI object. This prevents collisions on the GDI objects (device contexts, metafiles, etc.).

See Also

GdiGetBatchLimit, GdiSetBatchLimit


GdiGetBatchLimit function
GdiGetBatchLimit (Win32)

DWORD GdiGetBatchLimit(VOID)

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.

Returns

If the function succeeds, the return value is the batch limit; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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 function
GdiSetBatchLimit (Win32)

DWORD GdiSetBatchLimit(dwLimit)

DWORD dwLimit;	/* batch limit	*/

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.

Parameter	Description

dwLimit	Specifies the batch limit to be set. A value of 0 sets the default limit. A value of 1 disables batching.

Returns

If the function succeeds, the return value is the previous batch limit; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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


GetArcDirection function
GetArcDirection (Win32)

int GetArcDirection(hdc)

HDC hdc;	/* handle of device context	*/

The GetArcDirection function returns the current arc direction for the given device context. Arc and rectangle functions use the arc direction.

Parameter	Description

hdc	Identifies the device context.

Returns

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 drawn counterclockwise.

AD_CLOCKWISE	Arcs and rectangles drawn clockwise.

If an error occurs, the return value is zero.

See Also

SetArcDirection


GetAspectRatioFilterEx function
GetAspectRatioFilterEx (Win32)

BOOL GetAspectRatioFilterEx(hdc, lpAspectRatio)

HDC hdc;	/* handle of device context	*/
LPSIZE lpAspectRatio;	/* address of aspect-ratio filter	*/

The GetAspectRatioFilterEx function retrieves the setting for the current aspect-ratio filter.

Parameter	Description

hdc	Identifies a device context.

lpAspectRatio	Points to a SIZE structure that receives the current aspect-ratio filter.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


GetBitmapBits function
GetBitmapBits (Win32)

LONG GetBitmapBits(hbmp, cbBuffer, lpvBits)

HBITMAP hbmp;	/* handle of bitmap	*/
LONG cbBuffer;	/* number of bytes to copy to buffer	*/
LPVOID lpvBits;	/* address of buffer for bitmap bits	*/

The GetBitmapBits function copies the bits of the specified bitmap into a buffer.

The GetBitmapBits function is included only for compatibility with earlier versions of Windows. For Win32 applications, use the GetDIBits function.

Parameter	Description

hbmp	Identifies the bitmap.

cbBuffer	Specifies the number of bytes to be copied.

lpvBits	Points to the buffer to receive the bitmap. (The bitmap is an array of bytes.)

Returns

If the function succeeds, the return value is the actual number of bytes in the bitmap; otherwise, it is zero.

Comments

The bits in the destination buffer must be WORD aligned.

See Also

GetDIBits


GetBitmapDimensionEx function
GetBitmapDimensionEx (Win32)

BOOL GetBitmapDimensionEx(hBitmap, lpDimension)

HBITMAP hBitmap;	/* handle of bitmap	*/
LPSIZE lpDimension;	/* address of structure receiving dimensions	*/

The GetBitmapDimensionEx function retrieves the dimensions of a bitmap. The retrieved dimensions must have been set previously by the SetBitmapDimensionEx function.

Parameter	Description

hBitmap	Identifies the bitmap.

lpDimension	Points to a SIZE structure to receive the bitmap dimensions. The SIZE structure has the following form:

typedef struct tagSIZE { /* siz */

    LONG cx;

    LONG cy;

} SIZE;

For a full description of this structure, see the <Microsoft Win32 Programmer's Reference, Volume 5>.

Returns

If the function was successful, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If no dimensions have been set, a default width and height of zero are returned.

See Also

SetBitmapDimensionEx


GetBkColor function
GetBkColor (Win32)

COLORREF GetBkColor(hdc)

HDC hdc;	/* handle of device context	*/

The GetBkColor function returns the current background color of the given device.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value is a COLORREF value for the current background color; otherwise, it is CLR_INVALID.

See Also

SetBkColor


GetBkMode function
GetBkMode (Win32)

int GetBkMode(hdc)

HDC hdc;	/* handle of device context	*/

The GetBkMode function returns the background mix mode of the given device context (DC). The background mix mode is used with text, hatched brushes, and pen styles that are not solid lines.

Parameter	Description

hdc	Identifies the DC.

Returns

If the function succeeds, the return value specifies the current background mix mode; otherwise, it is zero.

See Also

SetBkMode


GetBoundsRect function
GetBoundsRect (Win32)

UINT GetBoundsRect(hdc, lprcBounds, flags)

HDC hdc;	/* handle of device context	*/
LPRECT lprcBounds;	/* address of structure for bounding rectangle	*/
UINT flags;	/* information to return	*/

The GetBoundsRect function returns the current accumulated bounding rectangle for a given device context (DC).

Windows maintains an accumulated bounding rectangle for each application. An application can retrieve and set this rectangle.

Parameter	Description

hdc	Identifies the device context (DC) 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. The following value has meaning:

Value	Meaning

DCB_RESET	Clears the bounding rectangle after returning it. If this flag is not set, the bounding rectangle will not be cleared.

Returns

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 (DC) handle is invalid.

DCB_RESET	The bounding rectangle is empty.

DCB_SET	The bounding rectangle is not empty.

DCB_ENABLE	Boundary accumulation is on.

DCB_DISABLE	Boundary accumulation is off.

Comments

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 function
GetBrushOrgEx (Win32)

BOOL GetBrushOrgEx(hdc, lppt)

HDC hdc;	/* handle of device context	*/
LPPOINT lppt;	/* address of structure of coordinates	*/

The GetBrushOrgEx function retrieves the current brush origin for the given device context (DC).

Parameter	Description

hdc	Identifies the DC.

lppt	Points to a POINT structure that receives the brush origin, in device coordinates.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 pixel at the brush's origin to the upper-left corner of the 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.

See Also

SetBrushOrgEx, POINT


GetCharABCWidths function
GetCharABCWidths (Win32)

BOOL GetCharABCWidths(hdc, uFirstChar, uLastChar, lpabc)

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

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 account 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, OUTLINETEXTMETRIC


GetCharABCWidthsFloat function
GetCharABCWidthsFloat (Win32)

BOOL GetCharABCWidthsFloat(hdc, iFirstChar, iLastChar, lpABCF)

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

The GetCharABCWidthsFloat function retrieves the widths, in logical units, of consecutive characters in a given range from the current font.

Parameter	Description

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-supplied buffer with an array of ABCFLOAT structures to receive the character widths when the function returns.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

"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 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

GetCharABCWidths, GetCharWidth, GetCharWidthFloat, ABCFLOAT


GetCharWidth function
GetCharWidth (Win32)

BOOL GetCharWidth(hdc, iFirstChar, iLastChar, lpBuffer)

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

The GetCharWidth function retrieves the widths, in logical coordinates, of consecutive characters in a given range from the current font.

The GetCharWidth function is exactly the same as the GetCharWidth32 function, with one difference: GetCharWidth has a subtle off-by-one bug that shows up in certain obscure situations, and GetCharWidth32 does not. The GetCharWidth behavior was maintained for backwards compatibility reasons; several Win 3.x applications are aware of, and rely upon, the subtle bug. New applications should call GetCharWidth32.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
GetCharWidth32 (Win32)

BOOL GetCharWidth32(hdc, iFirstChar, iLastChar, lpBuffer)

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

The GetCharWidth32 function retrieves the widths, in logical coordinates, of consecutive characters in a given range from the current font.

The GetCharWidth32 function is exactly the same as the GetCharWidth function, with one difference: GetCharWidth has a subtle off-by-one bug that shows up in certain obscure situations, and GetCharWidth32 does not. The GetCharWidth behavior was maintained for backwards compatibility reasons; several Win 3.x applications are aware of, and rely upon, the subtle bug. New applications should call GetCharWidth32.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
GetCharWidthFloat (Win32)

BOOL GetCharWidthFloat(hdc, iFirstChar, iLastChar, pxBuffer)

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

The GetCharWidthFloat function retrieves the fractional widths of consecutive characters in a given range from the current font.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, GetCharWidth


GetClipBox function
GetClipBox (Win32)

int GetClipBox(hdc, lprc)

HDC hdc;	/* handle of the device context	*/
LPRECT lprc;	/* address of structure with rectangle	*/

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.

Parameter	Description

hdc	Identifies the device context.

lprc	Points to a RECT structure that is to receive the rectangle dimensions.

Returns

If the function succeeds, the return value specifies the clipping box's complexity. It 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.

See Also

RECT


GetClipRgn function
GetClipRgn (Win32)

int GetClipRgn(hdc, hrgn)

HDC hdc;	/* handle of device context	*/
HRGN hrgn;	/* handle of region	*/

The GetClipRgn function retrieves a handle identifying the current application-defined clipping region for the given device context.

Parameter	Description

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.

Returns

If the function succeeds and there is no clipping region for the given device context, the return value is 0; 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.

Comments

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

SelectClipRgn


GetColorAdjustment function
GetColorAdjustment (Win32)

BOOL GetColorAdjustment(hdc, lpca)

HDC hdc;	/* handle of device context	*/
LPCOLORADJUSTMENT lpca;	/* address of coloradjustment structure	*/

The GetColorAdjustment function retrieves the color adjustment values for the specified device context.

Parameter	Description

hdc	Identifies the device context.

lpca	Points to a COLORADJUSTMENT structure to receive the color adjustment values. The COLORADJUSTMENT structure has the following form:

The COLORADJUSTMENT structure has the following format:

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;

For a full description of this structure, see the <Microsoft Win32 Programmer's Reference, Volume 5>.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

SetColorAdjustment, COLORADJUSTMENT


GetCurrentObject function
GetCurrentObject (Win32)

HGDIOBJ GetCurrentObject(hdc, uObjectType)

HDC hdc;	/* handle of device context	*/
UINT uObjectType;	/* object-type identifier	*/

The GetCurrentObject function returns the currently selected object of the specified type.

Parameter	Description

hdc	Identifies the device context (DC).

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

Returns

If the function succeeds, the return value is the handle of the specified object. Otherwise, it is NULL.

Comments

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 function
GetCurrentPositionEx (Win32)

BOOL GetCurrentPositionEx(hdc, lpPoint)

HDC hdc;	/* handle of device context	*/
LPPOINT lpPoint;	/* address of structure receiving current position	*/

The GetCurrentPositionEx function retrieves the current position in logical coordinates.

Parameter	Description

hdc	Identifies the device context.

lpPoint	Points to a POINT structure that receives the coordinates of the current position.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

MoveToEx, POINT


GetDCOrg function
GetDCOrg (Win32)

The GetDCOrg function is obsolete. Win32 applications should use the GetDCOrgEx function.

See Also

GetDCOrgEx


GetDCOrgEx function
GetDCOrgEx (Win32)

BOOL GetDCOrgEx(hdc, lpPoint)

HDC hdc;	/* device context handle	*/
LPPOINT lpPoint;	/* address of structure that receives translation origin	*/

The GetDCOrgEx function obtains the final translation origin for a given device context. The final translation origin specifies an offset that Windows uses to translate device coordinates into client coordinates (for coordinates in an application's window).

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The final translation origin is relative to the physical origin of the screen.

See Also

CreateIC


GetDeviceCaps function
GetDeviceCaps (Win32)

int GetDeviceCaps(hdc, nIndex)

HDC hdc;	/* device context handle	*/
int nIndex;	/* index of capability to query	*/

The GetDeviceCaps function retrieves device-specific information about a given device.

Parameter	Description

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.

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.

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 polygon 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 can scroll text using a bit-block transfer.

Returns

The return value specifies the value of the desired item.

See Also

CreateEnhMetaFile, CreateIC, DeviceCapabilities, GetObjectType, LOGFONT


GetDIBits function
GetDIBits (Win32)

int GetDIBits(hdc, hbmp, uStartScan, cScanLines, lpvBits, lpbi, uUsage)

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

The GetDIBits function retrieves the bits of the specified bitmap and copies them into the given buffer using the specified format.

Parameter	Description

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.

DIB_PAL_INDICES	There is no color table for the bitmap. Only the BITMAPINFOHEADER portion of the BITMAPINFO structure is filled in.

Returns

If the function succeeds, the return value is the number of scan lines copied from the bitmap; otherwise, it is zero.

Comments

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 graphics device interface (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 must be initialized to specify the size and format of the DIB. The bitmap's color table will be appended to the BITMAPINFO structure.

If lpvBits is NULL, GetDIBits fills in the BITMAPINFO structure, but does not retrieve the bits from the bitmap.

If lpvBits is NULL and the bit count member of the BITMAPINFO structure is initialized to zero, GetDIBits fills in the BITMAPINFOHEADER structure without the color table. This technique can be used to query the attributes of a bitmap.

The bitmap identified by the hbmp parameter must not be selected into a device context when the application calls this function.

The origin for the DIB is the bottom left corner of the bitmap, not the top left corner.

See Also

SetDIBits, BITMAPINFO, BITMAPINFOHEADER


GetEnhMetaFile function
GetEnhMetaFile (Win32)

HENHMETAFILE GetEnhMetaFile(lpszMetaFile)

LPCTSTR lpszMetaFile;	/* address of metafile name	*/

The GetEnhMetaFile function creates a handle that identifies the enhanced-format metafile stored in the given file.

Parameter	Description

lpszMetaFile	Points to the null-terminated string that specifies the name of an enhanced metafile.

Returns

If the function succeeds, the return value is a handle of the enhanced metafile; otherwise, it is NULL.

Comments

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.

See Also

DeleteEnhMetaFile, SetWinMetaFileBits


GetEnhMetaFileBits function
GetEnhMetaFileBits (Win32)

UINT GetEnhMetaFileBits(hemf, cbBuffer, lpbBuffer)

HENHMETAFILE hemf;	/* handle of metafile	*/
UINT cbBuffer;	/* size of data buffer, in bytes	*/
LPBYTE lpbBuffer;	/* address of data buffer	*/

The GetEnhMetaFileBits function retrieves the contents of the given enhanced-format metafile and copies them into a buffer.

Parameter	Description

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.

Returns

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. Otherwise, the return value is zero.

Comments

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 function
GetEnhMetaFileDescription (Win32)

UINT GetEnhMetaFileDescription(hemf, cchBuffer, lpszDescription)

HENHMETAFILE hemf;	/* handle of enhanced metafile	*/
UINT cchBuffer;	/* size of text buffer, in characters	*/
LPTSTR lpszDescription;	/* address of text buffer	*/

The GetEnhMetaFileDescription function retrieves an optional text description from an enhanced-format metafile and copies the string to the given buffer.

Parameter	Description

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.

Returns

If the text description exists but the buffer pointer is NULL, the return value is the length of the text string, in characters; if the text description exists and the buffer pointer is a valid pointer, the return value is the number of characters copied into the buffer; otherwise, it is GDI_ERROR. If the optional text description does not exist, the return value is zero.

Comments

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.

See Also

CreateEnhMetaFile


GetEnhMetaFileHeader function
GetEnhMetaFileHeader (Win32)

UINT GetEnhMetaFileHeader(hemf, cbBuffer, lpemh)

HENHMETAFILE hemf;	/* handle of enhanced metafile	*/
UINT cbBuffer;	/* size of buffer, in bytes	*/
LPENHMETAHEADER lpemh;	/* address of buffer to receive data	*/

The GetEnhMetaFileHeader function retrieves the record containing the header for the given enhanced-format metafile.

Parameter	Description

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.

Returns

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.

Comments

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.

See Also

PlayEnhMetaFile


GetEnhMetaFilePaletteEntries function
GetEnhMetaFilePaletteEntries (Win32)

UINT GetEnhMetaFilePaletteEntries(hemf, cEntries, lppe)

HENHMETAFILE hemf;	/* handle of enhanced metafile	*/
UINT cEntries;	/* count of palette entries	*/
LPPALETTEENTRY lppe;	/* address of palette-entry array	*/

The GetEnhMetaFilePaletteEntries function retrieves optional palette entries from the given enhanced-metafile.

Parameter	Description

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.

Returns

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.

Comments

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, PlayEnhMetaFile, RealizePalette, SelectPalette, PALETTEENTRY


GetFontData function
GetFontData (Win32)

DWORD GetFontData(hdc, dwTable, dwOffset, lpvBuffer, cbData)

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

The GetFontData function retrieves font metric data for a TrueType® font.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the number of bytes returned; otherwise, it is GDI_ERROR.

Comments

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, OUTLINETEXTMETRIC


GetGlyphOutline function
GetGlyphOutline (Win32)

DWORD GetGlyphOutline(hdc, uChar, uFormat, lpgm, cbBuffer, lpvBuffer, lpmat2)

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

The GetGlyphOutline function retrieves the outline or bitmap for a character in the TrueType® font that is selected into the given device context.

Parameter	Description

hdc	Identifies the device context.

uChar	Specifies the character for which data is to be returned.

uFormat	Specifies the format in which the function returns the data. It can be one of the following values:

Value	Meaning

GGO_BITMAP	Returns the glyph bitmap. For information about memory allocation, see the following "Comments" section.

GGO_NATIVE	Returns 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	Returns only 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 Returns section below.

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.

Returns

If the function succeeds, and GGO_BITMAP or GGO_NATIVE is specified, the return value is greater than zero.

If the function succeeds, and GGO_METRICS is specified, the return value is zero.

If GGO_BITMAP or GGO_NATIVE is specified, and the buffer size or address is zero, the return value specifies the required buffer size. If GGO_BITMAP or GGO_NATIVE is specified, and the function fails for other reasons, the return value is GDI_ERROR.

If GGO_METRICS is specified, and the function fails, the return value is GDI_ERROR.

Comments

The glyph outline returned by the GetGlyphOutline function is for a grid-fitted glyph. (A grid-fitted glyph 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 should 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.

An application can rotate characters retrieved in bitmap format by specifying a 2-by-2 transformation matrix in the lpMatrix parameter.

See Also

GetOutlineTextMetrics, GLYPHMETRICS, MAT2, OUTLINETEXTMETRIC


GetGraphicsMode function
GetGraphicsMode (Win32)

int GetGraphicsMode(hdc)

HDC hdc;	/* handle of device context	*/

The GetGraphicsMode function retrieves the current graphics mode for the specified device context.

Parameter	Description

hdc	Identifies the device context.

Returns

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

Otherwise, the return value is zero.

Comments

An application can set the graphics mode for a device context by calling the SetGraphicsMode function.

See Also

SetGraphicsMode


GetKerningPairs function
GetKerningPairs (Win32)

DWORD GetKerningPairs(hdc, nNumPairs, lpkrnpair)

HDC hdc;	/* handle of device context	*/
DWORD nNumPairs;	/* number of kerning-pairs to be retrieved	*/
LPKERNINGPAIR lpkrnpair;	/* address of kerning-pair array	*/

The GetKerningPairs function retrieves the character-kerning pairs for the currently selected font for the given device context (DC).

Parameter	Description

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.

Returns

If the function succeeds, the return value is the number of kerning-pairs returned; otherwise, it is zero.

See Also

KERNINGPAIR


GetMapMode function
GetMapMode (Win32)

int GetMapMode(hdc)

HDC hdc;	/* handle of device context	*/

The GetMapMode function retrieves the current mapping mode.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value specifies the mapping mode; otherwise, it is zero.

Comments

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


GetMetaFile function
GetMetaFile (Win32)

HMETAFILE GetMetaFile(lpszFile)

LPCTSTR lpszFile;	/* address of metafile name	*/

The GetMetaFile function creates a handle that identifies the given Windows-format metafile.

This function is provided for compatibility with earlier versions of Microsoft Windows. For Win32 applications, use the GetEnhMetaFile function.

Parameter	Description

lpszFile	Points to the null-terminated string that specifies the name of a Windows-format metafile. (The metafile must already exist.)

Returns

If the function succeeds, the return value is a handle of the Windows-format metafile; otherwise, it is NULL.

Comments

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.

An application can call to convert a Windows-format metafile into an enhanced-format metafile, by calling the SetWinMetaFileBits function.

When the application no longer needs the handle returned by GetMetaFile, it should delete the handle by using the DeleteMetaFile function.

Where text arguments must use Unicode™ characters, use the 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.

See Also

DeleteMetaFile, SetWinMetaFileBits


GetMetaFileBitsEx function
GetMetaFileBitsEx (Win32)

UINT GetMetaFileBitsEx(hmf, nSize, lpvData)

HMETAFILE hmf;	/* handle of metafile	*/
UINT nSize;	/* size of metafile, in bytes	*/
LPVOID lpvData;	/* address of metafile data	*/

The GetMetaFileBitsEx function retrieves the contents of a Windows-format metafile and copies them into the given buffer.

This function is provided for compatibility with earlier versions of Microsoft Windows. For Win32 applications, use the GetEnhMetaFileBits function.

Parameter	Description

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.

Returns

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. Otherwise, it is zero.

Comments

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, PolyBezier, SetMetaFileBitsEx, SetWinMetaFileBits, SetWorldTransform


GetMetaRgn function
GetMetaRgn (Win32)

int GetMetaRgn(hdc, hrgn)

HDC hdc;	/* handle of device context	*/
HRGN hrgn;	/* handle of region	*/

The GetMetaRgn function retrieves the current metaregion for the given device context.

Parameter	Description

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.

Returns

If the function succeeds, the return value is 1; otherwise, it is 0.

Comments

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 function
GetMiterLimit (Win32)

BOOL GetMiterLimit(hdc, peLimit)

HDC hdc;	/* handle of device context	*/
PFLOAT peLimit;	/* address of variable receiving miter limit	*/

The GetMiterLimit function returns the miter limit for the given device context.

Parameter	Description

hdc	Identifies the device context.

peLimit	Points to a floating-point value where the current miter limit will be returned.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The miter limit is used when drawing geometric lines that have miter joins.

See Also

ExtCreatePen, SetMiterLimit


GetNearestColor function
GetNearestColor (Win32)

COLORREF GetNearestColor(hdc, crColor)

HDC hdc;	/* handle of device context	*/
COLORREF crColor;	/* color to be matched	*/

The GetNearestColor function returns a color value identifying a color from the system palette that will be displayed when the given color value is used.

Parameter	Description

hdc	Identifies the device context.

crColor	Specifies a color value that identifies a requested color.

Returns

If the function succeeds, the return value identifies a color from the system palette that corresponds to the given color value; otherwise, it is CLR_INVALID. To get extended error information, use the GetLastError function.

See Also

GetDeviceCaps, GetNearestPaletteIndex, COLORREF


GetNearestPaletteIndex function
GetNearestPaletteIndex (Win32)

UINT GetNearestPaletteIndex(hpal, crColor)

HPALETTE hpal;	/* handle of logical color palette	*/
COLORREF crColor;	/* color to be matched	*/

The GetNearestPaletteIndex function retrieves the index for the entry in the given logical palette most closely matching a given color value.

Parameter	Description

hpal	Identifies a logical color palette.

crColor	Specifies a color to be matched.

Returns

If the function succeeds, the return value is the index of an entry in a logical palette; otherwise, it is CLR_INVALID. To get extended error information, use the GetLastError function.

Comments

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


GetObject function
GetObject (Win32)

int GetObject(hgdiobj, cbBuffer, lpvObject)

HGDIOBJ hgdiobj;	/* handle of object	*/
int cbBuffer;	/* size of buffer for object information	*/
LPVOID lpvObject;	/* address of buffer for object information	*/

The GetObject function fills a buffer with information defining a given object. The function retrieves a BITMAP, EXTLOGPEN, LOGPEN, LOGBRUSH, or LOGFONT structure, or an integer, depending on the given object.

Parameter	Description

hgdiobj	Identifies a logical bitmap, brush, font, palette, or pen .

cbBuffer	Specifies the number of bytes to be copied to the buffer.

lpvObject	Points to the buffer that is to receive the information. If the parameter is NULL, the return value contains the number of bytes needed for the logical object.

Returns

If lpvObject is a valid pointer and the function succeeds, the return value is the number of bytes returned; if lpvObject is NULL and the function succeeds, the return value is the number of bytes required to hold the object. Otherwise, the return value is zero.

Comments

The buffer pointed to by the lpvObject parameter must be sufficiently large to receive the information.

If the hgdiobj parameter identifies a bitmap, the GetObject function returns only the width, height, and color format information of the bitmap. The bits can be retrieved by using the GetBitmapBits function.

If hgdiobj identifies a logical palette, GetObject retrieves a 2-byte integer specifying 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

GetDIBits, GetPaletteEntries, BITMAP, LOGBRUSH, LOGFONT, LOGPALETTE, LOGPEN


GetObjectType function
GetObjectType (Win32)

DWORD GetObjectType(hgdiobj)

HGDIOBJ hgdiobj;	/* handle of graphic object	*/

The GetObjectType identifies the type of the given object.

Parameter	Description

hgdiobj	Identifies the object.

Returns

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


GetOutlineTextMetrics function
GetOutlineTextMetrics (Win32)

UINT GetOutlineTextMetrics(hdc, cbData, lpOTM)

HDC hdc;	/* handle of device context	*/
UINT cbData;	/* size of metric data array	*/
LPOUTLINETEXTMETRIC lpOTM;	/* address of metric data array	*/

The GetOutlineTextMetrics function retrieves text metrics for TrueType® fonts.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE or the size of the required buffer; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, OUTLINETEXTMETRIC, TEXTMETRIC


GetPaletteEntries function
GetPaletteEntries (Win32)

UINT GetPaletteEntries(hpal, iStartIndex, nEntries, lppe)

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

The GetPaletteEntries function retrieves a specified range of palette entries from the given logical palette.

Parameter	Description

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.

Returns

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. Otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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, PALETTEENTRY, PALETTEENTRY


GetPath function
GetPath (Win32)

int GetPath(hdc, lpPoints, lpTypes, nSize)

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

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.

Parameter	Description

hdc	Identifies a device context that contains a closed path.

lpPoints	Points to an array of POINT structures where the line endpoints and curve control points are placed.

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 lpPoints 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 types 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 type may be combined with the following flag (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 lpPoints array. This value must be the same as the number of bytes that may be placed in the lpTypes array.

Returns

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. Use the GetLastError function to get the error value, which can be one of the following:

ERROR_CAN_NOT_COMPLETE

ERROR_INVALID_PARAMETER

ERROR_BUFFER_OVERFLOW

Comments

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, PolyDraw, WidenPath, POINT


GetPixel function
GetPixel (Win32)

COLORREF GetPixel(hdc, nXPos, nYPos)

HDC hdc;	/* handle of device context	*/
int nXPos;	/* x-coordinate of pixel	*/
int nYPos;	/* y-coordinate of pixel	*/

The GetPixel function retrieves the red, green, blue (RGB) color value of the pixel at the specified coordinates.

Parameter	Description

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.

Returns

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.

Comments

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 given device supports this function.

See Also

GetDeviceCaps


GetPolyFillMode function
GetPolyFillMode (Win32)

int GetPolyFillMode(hdc)

HDC hdc;	/* handle of device context	*/

The GetPolyFillMode function retrieves the current polygon fill mode.

Parameter	Description

hdc	Identifies the device context.

Returns

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.

For more information about these modes, see the SetPolyFillMode function.

See Also

SetPolyFillMode


GetRasterizerCaps function
GetRasterizerCaps (Win32)

BOOL GetRasterizerCaps(lprs, cb)

LPRASTERIZER_STATUS lprs;	/* address of rasterizer information structure	*/
UINT cb;	/* number of bytes in structure	*/

The GetRasterizerCaps function returns flags indicating whether TrueType® fonts are installed in the system.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The GetRasterizerCaps function enables applications and printer drivers to determine whether TrueType is 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, RASTERIZER_STATUS


GetRegionData function
GetRegionData (Win32)

DWORD GetRegionData(hRgn, dwCount, lpRgnData)

HRGN hRgn;	/* handle of region	*/
DWORD dwCount;	/* size of buffer containing region data	*/
LPRGNDATA lpRgnData;	/* address of buffer containing region data	*/

The GetRegionData function fills the specified buffer with data describing the given region. This data includes the dimensions of the rectangles that make up the region.

Parameter	Description

hRgn	Identifies the region.

dwCount	Specifics 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.

Returns

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. Otherwise, the return value is zero.

Comments

This function is used in conjunction with the ExtCreateRegion function.

See Also

ExtCreateRegion, RGNDATA


GetRgnBox function
GetRgnBox (Win32)

int GetRgnBox(hrgn, lprc)

HRGN hrgn;	/* handle of a region	*/
LPRECT lprc;	/* address of structure that receives bounding rect.	*/

The GetRgnBox function retrieves the bounding rectangle of the given region.

Parameter	Description

hrgn	Identifies the region.

lprc	Points to a RECT structure that receives the bounding rectangle.

Returns

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 function
GetROP2 (Win32)

int GetROP2(hdc)

HDC hdc;	/* handle of device context	*/

The GetROP2 function retrieves the foreground mix mode. The mix mode specifies how the pen or interior color and the color already on the screen are combined to yield a new color.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value specifies the foreground mix mode; otherwise, it is zero.

Comments

Following are the foreground mix modes:

Mix mode	Description

R2_BLACK	Pixel is always 0.

R2_WHITE	Pixel is always 1.

R2_NOP	Pixel remains unchanged.

R2_NOT	Pixel is the inverse of the screen color.

R2_COPYPEN	Pixel is the pen color.

R2_NOTCOPYPEN	Pixel is the inverse of the pen color.

R2_MERGEPENNOT	Pixel is a combination of the pen color and the inverse of the screen color.

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_MASKNOTPEN	Pixel is a combination of the colors common to both the screen and the inverse of the pen.

R2_MERGEPEN	Pixel is a combination of the pen color and the screen color.

R2_NOTMERGEPEN	Pixel is the inverse of the R2_MERGEPEN color.

R2_MASKPEN	Pixel is a combination of the colors common to both the pen and the screen.

R2_NOTMASKPEN	Pixel is the inverse of the R2_MASKPEN color.

R2_XORPEN	Pixel is a combination of the colors in the pen and in the screen, but not in both.

R2_NOTXORPEN	Pixel is the inverse of the R2_XORPEN color.

See Also

SetROP2


GetStockObject function
GetStockObject (Win32)

HGDIOBJ GetStockObject(fnObject)

int fnObject;	/* type of stock object	*/

The GetStockObject function retrieves a handle to one of the predefined stock pens, brushes, fonts, or palettes.

Parameter	Description

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 system font.

ANSI_VAR_FONT	Windows variable-pitch system font.

DEVICE_DEFAULT_FONT	Device-dependent font.

OEM_FIXED_FONT	Original equipment manufacturer (OEM) dependent fixed 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 variable-pitch font; earlier versions of Windows use a fixed-pitch system font.

SYSTEM_FIXED_FONT	Fixed-pitch system font used in Windows versions earlier than 3.0. This stock object is available for compatibility with earlier versions of Windows.

DEFAULT_PALETTE	Default palette. This palette consists of the static colors in the system palette.

Returns

If the function succeeds, the return value identifies the logical object requested; otherwise, it is NULL.

Comments

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.

See Also

DeleteObject, SelectObject


GetStretchBltMode function
GetStretchBltMode (Win32)

int GetStretchBltMode(hdc)

HDC hdc;	/* handle of device context	*/

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.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value is the current stretching mode; otherwise, it is zero.

See Also

SetStretchBltMode, StretchBlt


GetSystemPaletteEntries function
GetSystemPaletteEntries (Win32)

UINT GetSystemPaletteEntries(hdc, iStartIndex, nEntries, lppe)

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

The GetSystemPaletteEntries function retrieves a range of palette entries from the system palette that is associated with the given device context.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the number of entries retrieved from the palette; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

An application can determine whether or not a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

See Also

GetDeviceCaps, GetPaletteEntries, PALETTEENTRY


GetSystemPaletteUse function
GetSystemPaletteUse (Win32)

UINT GetSystemPaletteUse(hdc)

HDC hdc;	/* handle of device context	*/

The GetSystemPaletteUse function retrieves the current state of the system (physical) palette for the given device context.

Parameter	Description

hdc	Identifies the device context.

Returns

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, use the GetLastError function.

Comments

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


GetTextAlign function
GetTextAlign (Win32)

UINT GetTextAlign(hdc)

HDC hdc;	/* handle of device context	*/

The GetTextAlign function retrieves the text-alignment setting for the given device context.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value is the status of the text-alignment flags. Otherwise, it is GDI_ERROR.

To get extended error information, use the GetLastError function.

For a list of status return values, see the Comments section of this entry. 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_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.

Comments

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 GetTextExtent 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, SetTextAlign, TextOut


GetTextCharacterExtra function
GetTextCharacterExtra (Win32)

int GetTextCharacterExtra(hdc)

HDC hdc;	/* handle of device context	*/

The GetTextCharacterExtra function retrieves the current intercharacter spacing for the given device context.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value is the current intercharacter spacing. Otherwise, it is INVALID_WIDTH.

Comments

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, TextOut


GetTextColor function
GetTextColor (Win32)

COLORREF GetTextColor(hdc)

HDC hdc;	/* handle of device context	*/

The GetTextColor function retrieves the current text color for the given device context.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value is the current text color as a COLORREF value; otherwise, it is CLR_INVALID.

Comments

The text color defines the foreground color of characters drawn by using the TextOut or ExtTextOut function.

See Also

ExtTextOut, TextOut


GetTextExtentExPoint function
GetTextExtentExPoint (Win32)

BOOL GetTextExtentExPoint(hdc, lpszStr, cchString, nMaxExtent, lpnFit, alpDx, lpSize)

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

The GetTextExtentExPoint function retrieves the number of characters in a specified string that will fit within a given 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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If both the lpnFit and alpDx parameters are NULL, calling the GetTextExtentExPoint function is equivalent to calling the GetTextExtentPoint function.

See Also

GetTextExtentPoint


GetTextExtentPoint function
GetTextExtentPoint (Win32)

BOOL GetTextExtentPoint(hdc, lpsz, cbString, lpSize)

HDC hdc;	/* handle of device context	*/
LPCTSTR lpsz;	/* address of text string	*/
int cbString;	/* number of characters in string	*/
LPSIZE lpSize;	/* address of structure for string size	*/

The GetTextExtentPoint function computes the width and height of the given string of text.

The GetTextExtentPoint function is exactly the same as the GetTextExtentPoint32 function, with one difference: GetTextExtentPoint has a subtle off-by-one bug that shows up in certain obscure situations, and GetTextExtentPoint32 does not. The GetTextExtentPoint behavior was maintained for backwards compatibility reasons; several Win 3.x applications are aware of, and rely upon, the subtle bug. New applications should call GetTextExtentPoint32.

Parameter	Description

hdc	Identifies the device context.

lpsz	Points to the string of text.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
GetTextExtentPoint32 (Win32)

BOOL GetTextExtentPoint32(hdc, lpsz, cbString, lpSize)

HDC hdc;	/* handle of device context	*/
LPCTSTR lpsz;	/* address of text string	*/
int cbString;	/* number of characters in string	*/
LPSIZE lpSize;	/* address of structure for string size	*/

The GetTextExtentPoint32 function computes the width and height of the given string of text.

The GetTextExtentPoint32 function is exactly the same as the GetTextExtentPoint function, with one difference: GetTextExtentPoint has a subtle off-by-one bug that shows up in certain obscure situations, and GetTextExtentPoint32 does not. The GetTextExtentPoint behavior was maintained for backwards compatibility reasons; several Win 3.x applications are aware of, and rely upon, the subtle bug. New applications should call GetTextExtentPoint32.

Parameter	Description

hdc	Identifies the device context.

lpsz	Points to the string of text.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
GetTextFace (Win32)

int GetTextFace(hdc, nCount, lpFaceName)

HDC hdc;	/* handle of device context	*/
int nCount;	/* length of buffer receiving typeface name	*/
LPTSTR lpFaceName;	/* address of buffer receiving typeface name	*/

The GetTextFace function retrieves the typeface name of the font that is selected into the given device context.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the number of characters copied to the buffer; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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, GetTextExtentPoint, GetTextMetrics


GetTextMetrics function
GetTextMetrics (Win32)

BOOL GetTextMetrics(hdc, lptm)

HDC hdc;	/* handle of device context	*/
LPTEXTMETRIC lptm;	/* address of text metrics structure	*/

The GetTextMetrics function fills the given buffer with the metrics for the currently selected font.

Parameter	Description

hdc	Identifies the device context.

lptm	Points to the TEXTMETRIC structure that is to receive the metrics.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetTextAlign, GetTextExtent, GetTextFace, SetTextJustification, TEXTMETRIC


GetViewportExtEx function
GetViewportExtEx (Win32)

BOOL GetViewportExtEx(hdc, lpSize)

HDC hdc;	/* handle of device context	*/
LPSIZE lpSize;	/* address of structure receiving viewport dimensions	*/

The GetViewportExtEx function retrieves the x-extents and y-extents of the current viewport for the given device context (DC).

Parameter	Description

hdc	Identifies the DC.

lpSize	Points to a SIZE structure. The x- and y-extents, in device units, are placed in this structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

GetWindowExtEx, SetViewportExtEx, SetWindowExtEx


GetViewportOrgEx function
GetViewportOrgEx (Win32)

BOOL GetViewportOrgEx(hdc, lpPoint)

HDC hdc;	/* handle of device context	*/
LPPOINT lpPoint;	/* address of structure receiving the viewport origin	*/

The GetViewportOrgEx function retrieves the x-coordinates and y-coordinates of the viewport origin for the given device context (DC).

Parameter	Description

hdc	Identifies the DC.

lpPoint	Points to a POINT structure that receives the origin coordinates.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

GetWindowOrgEx, SetViewportOrgEx, SetWindowOrgEx


GetWindowExtEx function
GetWindowExtEx (Win32)

BOOL GetWindowExtEx(hdc, lpSize)

HDC hdc;	/* handle of device context	*/
LPSIZE lpSize;	/* address of structure receiving window extents	*/

This function retrieves the x-extents and y-extents of the window for the given device context (DC).

Parameter	Description

hdc	Identifies the DC.

lpSize	Points to a SIZE structure. The x- and y-extents in page-space units are placed in this structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

GetViewportExtEx, SetViewportExtEx, SetWindowExtEx, SIZE


GetWindowOrgEx function
GetWindowOrgEx (Win32)

BOOL GetWindowOrgEx(hdc, lpPoint)

HDC hdc;	/* handle of device context	*/
LPPOINT lpPoint;	/* address of structure receiving the window origin	*/

The GetWindowOrgEx function retrieves the x-coordinates and y-coordinates of the window origin for the given device context (DC).

Parameter	Description

hdc	Identifies the device context.

lpPoint	Points to a POINT structure that receives the coordinates, in page units, of the window origin.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

GetViewportOrgEx, SetViewportOrgEx, SetWindowOrgEx


GetWinMetaFileBits function
GetWinMetaFileBits (Win32)

UINT GetWinMetaFileBits(hemf, cbBuffer, lpbBuffer, fnMapMode, hdcRef)

HENHMETAFILE hemf;	/* handle of the enhanced metafile	*/
UINT cbBuffer;	/* buffer size	*/
LPBYTE lpbBuffer;	/* pointer to buffer	*/
INT fnMapMode;	/* mapping mode	*/
HDC hdcRef;	/* handle of reference device context	*/

The GetWinMetaFileBits function converts the enhanced-format records from a metafile into Windows-format records and stores the converted records in the specified buffer.

Parameter	Description

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.

Returns

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; otherwise, it is zero.

Comments

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 SetViewportOrg and SetViewportExt functions. However, GetWinMetaFileBits does create Windows-format records for the SetWindowExt 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


GetWorldTransform function
GetWorldTransform (Win32)

BOOL GetWorldTransform(hdc, lpXform)

HDC hdc;	/* handle of device context	*/
LPXFORM lpXform;	/* address of structure receiving transformation	*/

The GetWorldTransform function retrieves the current world-space to page-space transformation.

Parameter	Description

hdc	Identifies the device context.

lpXform	Points to an XFORM structure that receives the current world-space to page-space transformation.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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, XFORM


IntersectClipRect function
IntersectClipRect (Win32)

int IntersectClipRect(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect)

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

The IntersectClipRect function creates a new clipping region from the intersection of the current clipping region and the specified rectangle.

Parameter	Description

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.

Returns

If the function succeeds, the return value specifies the new clipping region's type. It 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.)

Comments

The lower and rightmost edges of the given rectangle are excluded from the clipping region.

See Also

ExcludeClipRect


InvertRgn function
InvertRgn (Win32)

BOOL InvertRgn(hdc, hrgn)

HDC hdc;	/* handle of device context	*/
HRGN hrgn;	/* handle of region to be inverted	*/

The InvertRgn function inverts the colors in the given region.

Parameter	Description

hdc	Identifies the device context.

hrgn	Identifies the region for which colors are inverted. The region's coordinates are presumed to be logical coordinates.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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


LineDDA function
LineDDA (Win32)

BOOL LineDDA(nXStart, nYStart, nXEnd, nYEnd, lpLineFunc, lpData)

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

The LineDDA function determines which pixels should be highlighted for a line defined by the given starting and ending points.

Parameter	Description

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 description of the LineDDAProc callback function.

lpData	Points to the application-defined data.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

This 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


LineTo function
LineTo (Win32)

BOOL LineTo(hdc, nXEnd, nYEnd)

HDC hdc;	/* device context handle	*/
int nXEnd;	/* x-coordinate of line's ending point	*/
int nYEnd;	/* y-coordinate of line's ending point	*/

The LineTo function draws a line from the current position up to, but not including, the specified point.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 the function succeeds, the current position is set to the specified ending point.

See Also

MoveToEx, Polyline, PolylineTo


LPtoDP function
LPtoDP (Win32)

BOOL LPtoDP(hdc, lpPoints, nCount)

HDC hdc;	/* handle of device context	*/
LPPOINT lpPoints;	/* array of points	*/
int nCount;	/* count of points	*/

The LPtoDP function converts logical coordinates into device coordinates. The conversion depends on the mapping mode of the device context (DC), the settings of the origins and extents for the window and viewport, and the world transformation.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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


MaskBlt function
MaskBlt (Win32)

BOOL MaskBlt(hdcDest, nXDest, nYDest, nWidth, nHeight, hdcSrc, nXSrc, nYSrc, hbmMask, xMask, yMask, dwRop)

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

The MaskBlt function combines the color data for the source and destination bitmaps using the given mask and raster operation.

Parameter	Description

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 byte of the high word of this value; the foreground raster operation code is stored in the low byte of the high word of this value; the low word of this value is ignored, and should be zero. The macro MAKEROP4 creates such combinations of foreground and background raster operation codes.

See the Comments section below for a discussion of foreground and background in the context of this function.

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

For further information on raster operations, and complete lists of all the raster operation codes, see RasterOperationCodes.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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-blitting task by adjusting the pixel offsets and rectangle sizes sent to MaskBlt.

See Also

BitBlt, GetDeviceCaps, PlgBlt, StretchBlt


ModifyWorldTransform function
ModifyWorldTransform (Win32)

BOOL ModifyWorldTransform(hdc, lpXform, iMode)

HDC hdc;	/* handle of device context	*/
CONST XFORM * lpXform;	/* address of transformation data	*/
DWORD iMode;	/* modification mode	*/

The ModifyWorldTransform function changes the world transformation for the given device context (DC) using the specified mode.

Parameter	Description

hdc	Specifies the DC.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The ModifyWorldTransform function will fail unless graphics mode for the given device context (DC) has been set to GM_ADVANCED by previosly calling the SetGraphicsMode function. Likewise, it will not be possible to reset the graphics mode for the DC 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


MoveToEx function
MoveToEx (Win32)

BOOL MoveToEx(hdc, X, Y, lpPoint)

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

The MoveToEx function updates the current position to the specified point and optionally returns the previous position.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The MoveToEx function affects all drawing functions.

See Also

AngleArc, LineTo, PolyBezierTo, PolylineTo, POINT


OffsetClipRgn function
OffsetClipRgn (Win32)

int OffsetClipRgn(hdc, nXOffset, nYOffset)

HDC hdc;	/* handle of device context	*/
int nXOffset;	/* offset along x-axis	*/
int nYOffset;	/* offset along y-axis	*/

The OffsetClipRgn function moves the clipping region of the given device context by the specified offsets.

Parameter	Description

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.

Returns

If the function succeeds, the return value specifies the new region's complexity. It 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 not affected.)

See Also

SelectClipRgn


OffsetRgn function
OffsetRgn (Win32)

int OffsetRgn(hrgn, nXOffset, nYOffset)

HRGN hrgn;	/* handle of region	*/
int nXOffset;	/* offset along x-axis	*/
int nYOffset;	/* offset along y-axis	*/

The OffsetRgn function moves a region by the specified offsets.

Parameter	Description

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.

Returns

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 function
OffsetViewportOrgEx (Win32)

BOOL OffsetViewportOrgEx(hdc, nXOffset, nYOffset, lpPoint)

HDC hdc;	/* handle of device context	*/
int nXOffset;	/* horizontal offset	*/
int nYOffset;	/* vertical offset	*/
LPPOINT lpPoint;	/* address of structure receiving original origin	*/

The OffsetViewportOrgEx function modifies the viewport origin for the given device context (DC) using the specified horizontal and vertical offsets.

Parameter	Description

hdc	Identifies the DC.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The new origin is the sum of the current origin and the horizontal and vertical offsets.

See Also

GetViewportOrgEx, OffsetWindowOrgEx, SetViewportOrgEx, POINT


OffsetWindowOrgEx function
OffsetWindowOrgEx (Win32)

BOOL OffsetWindowOrgEx(hdc, nXOffset, nYOffset, lpPoint)

HDC hdc;	/* handle of device context	*/
int nXOffset;	/* horizontal offset	*/
int nYOffset;	/* vertical offset	*/
LPPOINT lpPoint;	/* address of structure receiving the original origin	*/

The OffsetViewportOrgEx function modifies the window origin for the given device context (DC) using the specified horizontal and vertical offsets.

Parameter	Description

hdc	Identifies the DC.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

GetViewportOrgEx, OffsetViewportOrgEx

See Also

POINT


PaintRgn function
PaintRgn (Win32)

BOOL PaintRgn(hdc, hrgn)

HDC hdc;	/* handle of device context	*/
HRGN hrgn;	/* handle of region to be painted	*/

The PaintRgn function paints the given region by using the brush currently selected into the device context.

Parameter	Description

hdc	Identifies the device context.

hrgn	Identifies the region to be filled. The region's coordinates are presumed to be logical coordinates.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

FillRgn


PatBlt function
PatBlt (Win32)

BOOL PatBlt(hdc, nXLeft, nYLeft, nWidth, nHeight, dwRop)

HDC hdc;	/* handle of 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	*/

The PatBlt function paints the given rectangle using the brush that is currently selected into the given device context. The brush color and the surface color(s) are combined by using the given raster operation.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

See Also

GetDeviceCaps


PathToRegion function
PathToRegion (Win32)

HRGN PathToRegion(hdc)

HDC hdc;	/* handle of device context	*/

The PathToRegion function creates a region from the path that is selected into the given device context.

Parameter	Description

hdc	Identifies a device context that contains a closed path.

Returns

If the function succeeds, the return value identifies a valid region; otherwise, it is zero. Use the GetLastError function to get the error value, which can be one of the following:

ERROR_CAN_NOT_COMPLETE

ERROR_INVALID_PARAMETER

ERROR_NOT_ENOUGH_MEMORY

Comments

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 given device context.

See Also

BeginPath, EndPath, SetPolyFillMode,


Pie function
Pie (Win32)

BOOL Pie(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect, nXRadial1, nYRadial1, nXRadial2, nYRadial2)

HDC hdc;
int nLeftRect;	/* x-coord. of bounding rect. upper-left corner	*/
int nTopRect;	/* y-coord. of bounding rect. upper-left corner	*/
int nRightRect;	/* x-coord. of bounding rect. lower-right corner	*/
int nBottomRect;	/* y-coord. of bounding rect. 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	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 this function.

See Also

AngleArc, Arc, ArcTo, Chord


PlayEnhMetaFile function
PlayEnhMetaFile (Win32)

BOOL PlayEnhMetaFile(hdc, hemf, lpRect)

HDC hdc;	/* handle of a device context	*/
HENHMETAFILE hemf;	/* handle of an enhanced metafile	*/
CONST RECT * lpRect;	/* address of bounding rectangle	*/

The PlayEnhMetaFile function displays the picture stored in the given enhanced-format metafile.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

See Also

CancelDC, GetEnhMetaFileHeader, GetEnhMetaFilePaletteEntries, SetWorldTransform


PlayEnhMetaFileRecord function
PlayEnhMetaFileRecord (Win32)

BOOL PlayEnhMetaFileRecord(hdc, lpHandletable, lpEnhMetaRecord, nHandles)

HDC hdc;	/* handle of device context	*/
LPHANDLETABLE lpHandletable;	/* address of metafile handle table	*/
CONST ENHMETARECORD * lpEnhMetaRecord;	/* address of metafile record	*/
UINT nHandles;	/* count of handles	*/

The PlayEnhMetaFileRecord function plays an enhanced-metafile record by executing the graphics device interface (GDI) functions identified by the record.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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.

See Also

EnumEnhMetaFile, PlayEnhMetaFile


PlayMetaFile function
PlayMetaFile (Win32)

BOOL PlayMetaFile(hdc, hmf)

HDC hdc;	/* handle of the device context	*/
HMETAFILE hmf;	/* handle of the metafile	*/

The PlayMetaFile function displays the picture stored in the given Windows-format metafile on the specified device.

This function is provided for compatibility with earlier versions of Microsoft Windows. For Win32 applications, use the PlayEnhMetaFile function.

Parameter	Description

hdc	Identifies a device context.

hmf	Identifies a Windows-format metafile.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 function
PlayMetaFileRecord (Win32)

BOOL PlayMetaFileRecord(hdc, lpHandletable, lpMetaRecord, nHandles)

HDC hdc;	/* handle of device context	*/
LPHANDLETABLE lpHandletable;	/* address of metafile handle table	*/
LPMETARECORD lpMetaRecord;	/* address of metafile record	*/
UINT nHandles;	/* count of handles	*/

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 earlier versions of Microsoft Windows. For Win32 applications, use the PlayEnhMetaFileRecord function.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 function
PlgBlt (Win32)

BOOL PlgBlt(hdcDest, lpPoint, hdcSrc, nXSrc, nYSrc, nWidth, nHeight, hbmMask, xMask, yMask)

HDC hdcDest;	/* handle of destination device context	*/
LPPOINT lpPoint;	/* vertices of destination parallelogram	*/
HDC hdcSrc;	/* handle of 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 of bitmask	*/
int xMask;	/* x-coord. of upper left corner of bitmask rect.	*/
int yMask;	/* y-coord. of upper left corner of bitmask rect.	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

If the source and destination device contexts represent incompatible devices, PlgBlt returns an error.

See Also

BitBlt, GetDeviceCaps, MaskBlt, SetStretchBltMode, StretchBlt


PolyBezier function
PolyBezier (Win32)

BOOL PolyBezier(hdc, lppt, cPoints)

HDC hdc;	/* handle of device context	*/
CONST POINT * lppt;	/* address of endpoints and control points	*/
DWORD cPoints;	/* count of endpoints and control points	*/

The PolyBezier function draws one or more Bézier splines.

Parameter	Description

hdc	Identifies a device context.

lppt	Points to an array of POINT structures that contain the endpoints and control points of the spline(s).

cPoints	Specifies the number of points in the lppt array. This value must be one more than three times the number of splines to be drawn, because each Bézier spline requires two control points and an endpoint, and the initial spline requires an additional starting point.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

This function draws cubic Bézier splines by using the endpoints and control points specified by the lppt parameter. The first spline is drawn from the first point to the fourth point by using the second and third points as control points. Each subsequent spline in the sequence needs exactly three more points: the ending point of the previous spline 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, PolyBezierTo, POINT


PolyBezierTo function
PolyBezierTo (Win32)

BOOL PolyBezierTo(hdc, lppt, cCount)

HDC hdc;	/* handle of device context	*/
CONST POINT * lppt;	/* address of endpoints and control points	*/
DWORD cCount;	/* count of endpoints and control points	*/

The PolyBezierTo function draws one or more Bézier splines.

Parameter	Description

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 splines to be drawn, because each Bézier spline requires two control points and an ending point.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

This function draws cubic Bézier splines by using the control points specified by the lppt parameter. The first spline is drawn from the current position to the third point by using the first two points as control points. For each subsequent spline, the function needs exactly three more points, and uses the ending point of the previous spline as the starting point for the next.

PolyBezierTo moves the current position to the ending point of the last Bézier spline. The figure is not filled.

This function draws lines by using the current pen.

See Also

MoveToEx, PolyBezier, POINT


PolyDraw function
PolyDraw (Win32)

BOOL PolyDraw(hdc, lppt, lpbTypes, cCount)

HDC hdc;	/* handle of a device context	*/
CONST POINT * lppt;	/* address of array of points	*/
CONST BYTE * lpbTypes;	/* address of line and curve identifiers	*/
int cCount;	/* count of points	*/

The PolyDraw function draws a set of line segments and Bézier splines.

Parameter	Description

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

lpbTypes	Points to an array that specifies how each point in the lppt array is used. Values 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 spline.

PT_BEZIERTO types always occur in sets of three. The current position defines the starting point for the Bézier spline. 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 constant by using the bitwise operator OR to indicate that the corresponding point is the last point in a figure and the figure is closed:

Type	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 MoveTo point.

This flag is combined with the PT_LINETO type for a line, or with the PT_BEZIERTO type of the ending point for a Bézier spline, 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

This function can be used in place of consecutive calls to MoveTo, LineTo, and PolyBezierTo functions to draw disjoint figures. The lines and splines 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 lpbTypes indicate whether each point is part of a MoveTo, a LineTo, or part of a BezierTo operation. It is also possible to close figures.

This function updates the current position.

See Also

BeginPath, BezierTo, EndPath, LineTo, MoveTo, PolyBezierTo, PolyLine


PolyTextOut function
PolyTextOut (Win32)

BOOL PolyTextOut(hdc, pptxt, cStrings)

HDC hdc;	/* handle of device context	*/
CONST POLYTEXT * pptxt;	/* address of array of structures that identify strings	*/
int cStrings;	/* number of structures in array	*/

The PolyTextOut function draws several strings using the font and text colors currently selected in the specified device context.

Parameter	Description

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.

Returns

If the function is successful, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SetTextAlign, POLYTEXT


Polygon function
Polygon (Win32)

BOOL Polygon(hdc, lpPoints, nCount)

HDC hdc;	/* handle of device context	*/
CONST POINT *lpPoints;	/* address of polygon's vertices	*/
int nCount;	/* count of polygon's vertices	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 this function.

See Also

GetPolyFillMode, Polyline, PolylineTo, PolyPolygon, SetPolyFillMode, POINT


Polyline function
Polyline (Win32)

BOOL Polyline(hdc, lppt, cPoints)

HDC hdc;	/* handle of device context	*/
CONST POINT *lppt;	/* address of array containing endpoints	*/
int cPoints;	/* number of points in the array	*/

The Polyline function draws a series of line segments by connecting the points in the given array.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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, PolylineTo, PolyPolyline, POINT


PolylineTo function
PolylineTo (Win32)

BOOL PolylineTo(hdc, lppt, cCount)

HDC hdc;	/* handle of device context	*/
CONST POINT * lppt;	/* address of array of points	*/
DWORD cCount;	/* number of points in array	*/

The PolylineTo function draws one or more straight lines.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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, Polyline, POINT


PolyPolygon function
PolyPolygon (Win32)

BOOL PolyPolygon(hdc, lpPoints, lpPolyCounts, nCount)

HDC hdc;	/* handle of device context	*/
CONST POINT *lpPoints;	/* address of vertices for all polygons	*/
LPINT lpPolyCounts;	/* count of vertices for each polygon	*/
int nCount;	/* count of polygons	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The current position is neither used nor updated by this function.

See Also

GetPolyFillMode, Polygon, Polyline, PolylineTo, SetPolyFillMode


PolyPolyline function
PolyPolyline (Win32)

BOOL PolyPolyline(hdc, lppt, lpdwPolyPoints, cCount)

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

The PolyPolyline function draws multiple series of connected line segments.

Parameter	Description

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 polygon. Each entry must be greater than or equal to two.

cCount	Specifies the total number of counts in the lpdwPolyPoints array.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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

Polyline, PolylineTo, POINT


PtInRegion function
PtInRegion (Win32)

BOOL PtInRegion(hrgn, X, Y)

HRGN hrgn;	/* handle of region	*/
int X;	/* x-coordinate of point	*/
int Y;	/* y-coordinate of point	*/

The PtInRegion function determines whether the specified point is inside the given region.

Parameter	Description

hrgn	Identifies the region to be examined.

X	Specifies the x-coordinate of the point.

Y	Specifies the y-coordinate of the point.

Returns

If the specified point is in the region, the return value is TRUE; otherwise, it is FALSE.

See Also

RectInRegion


PtVisible function
PtVisible (Win32)

BOOL PtVisible(hdc, X, Y)

HDC hdc;	/* handle of device context	*/
int X;	/* x-coordinate of point	*/
int Y;	/* y-coordinate of point	*/

The PtVisible function indicates whether the specified point is within the clipping region of the given device context.

Parameter	Description

hdc	Identifies the device context.

X	Specifies the logical x-coordinate of the point.

Y	Specifies the logical y-coordinate of the point.

Returns

If the specified point is within the clipping region of the device context, the return value is TRUE; otherwise, it is FALSE.

See Also

RectVisible


RealizePalette function
RealizePalette (Win32)

UINT RealizePalette(hdc)

HDC hdc;	/* handle of device context	*/

The RealizePalette function maps palette entries from the current logical palette to the system palette.

Parameter	Description

hdc	Identifies the device context (DC) into which a logical palette has been selected.

Returns

If the function succeeds, the return value is the number of entries in the logical palette mapped to the system palette; otherwise, it is GDI_ERROR. To get extended error information, use the GetLastError function.

Comments

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 given 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

GetDeviceCaps, CreatePalette, SelectPalette


Rectangle function
Rectangle (Win32)

BOOL Rectangle(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect)

HDC hdc;	/* handle of device context	*/
int nLeftRect;	/* x-coord. of bounding rect. upper-left corner	*/
int nTopRect;	/* y-coord. of bounding rect. upper-left corner	*/
int nRightRect;	/* x-coord. of bounding rect. lower-right corner	*/
int nBottomRect;	/* y-coord. of bounding rect. lower-right corner	*/

The Rectangle function draws a rectangle. The rectangle is outlined by using the current pen and filled by using the current brush.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The current position is neither used nor updated by this function.

See Also

RoundRect


RectInRegion function
RectInRegion (Win32)

BOOL RectInRegion(hrgn, lprc)

HRGN hrgn;	/* handle of region	*/
CONST RECT *lprc;	/* address of structure with rectangle	*/

The RectInRegion function determines whether any part of the specified rectangle is within the boundaries of the given region.

Parameter	Description

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.

Returns

If any part of the specified rectangle lies within the boundaries of the region, the return value is TRUE; otherwise, the return value is FALSE.

See Also

PtInRegion, RECT


RectVisible function
RectVisible (Win32)

BOOL RectVisible(hdc, lprc)

HDC hdc;	/* handle of the device context	*/
CONST RECT *lprc;	/* address of rectangle structure	*/

The RectVisible function determines whether any part of the specified rectangle lies within the clipping region of the given device context.

Parameter	Description

hdc	Identifies the device context.

lprc	Points to a RECT structure that contains the logical coordinates of the specified rectangle.

Returns

If some portion of the specified rectangle lies within the clipping region, the return value is TRUE; otherwise, it is FALSE.

See Also

CreateRectRgn, PtVisible, SelectClipRgn, RECT


RemoveFontResource function
RemoveFontResource (Win32)

BOOL RemoveFontResource(lpFileName)

LPCTSTR lpFileName;	/* address of font-resource filename	*/

The RemoveFontResource function removes the fonts in the specified file from the Windows font table.

Parameter	Description

lpFileName	Points to a null-terminated string that names a font resource file.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 is sent 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


ResetDC function
ResetDC (Win32)

HDC ResetDC(hdc, lpInitData)

HDC hdc;	/* handle of device context	*/
CONST DEVMODE * lpInitData;	/* address of structure with DC information	*/

The ResetDC function updates the given printer or plotter device context (DC), based on the information in the specified structure.

Parameter	Description

hdc	Identifies the device context to update.

lpInitData	Points to a DEVMODE structure containing information about the new device context.

Returns

If the function succeeds, the return value is the handle of the original device context. Otherwise, it is NULL.

Comments

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. For more information about device context types, see Device Contexts.

See Also

DeviceCapabilities, Escape, DEVMODE


ResizePalette function
ResizePalette (Win32)

BOOL ResizePalette(hpal, nEntries)

HPALETTE hpal;
UINT nEntries;

The ResizePalette function increases or decreases the size of the given logical palette based on the specified value.

Parameter	Description

hpal	Identifies the palette to be changed.

nEntries	Specifies the number of entries in the palette after it has been resized.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, PALETTEENTRY


RestoreDC function
RestoreDC (Win32)

BOOL RestoreDC(hdc, nSavedDC)

HDC hdc;	/* handle of device context	*/
int nSavedDC;	/* specifies state to be restored	*/

The RestoreDC function restores the given device context (DC) to the specified state. The DC is restored by popping state information off a stack created by earlier calls to the SaveDC function.

Parameter	Description

hdc	Identifies the DC.

nSavedDC	Specifies the instance of the DC to be restored. If this parameter is positive, nSavedDC represents a specific instance of the DC to be restored. If this parameter is negative, nSavedDC represents an instance relative to the current DC. For example, -1 restores the most recently saved state.

Returns

If the function succeeds, the return value is TRUE. Otherwise, it is FALSE.

Comments

The stack can contain the state information for several instances of the DC. 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


RoundRect function
RoundRect (Win32)

BOOL RoundRect(hdc, nLeftRect, nTopRect, nRightRect, nBottomRect, nWidth, nHeight)

HDC hdc;	/* handle of device context	*/
int nLeftRect;	/* x-coord. of bounding rect. upper-left corner	*/
int nTopRect;	/* y-coord. of bounding rect. upper-left corner	*/
int nRightRect;	/* x-coord. of bounding rect. lower-right corner	*/
int nBottomRect;	/* y-coord. of bounding rect. lower-right corner	*/
int nWidth;	/* width of ellipse used to draw rounded corners	*/
int nHeight;	/* height of ellipse used to draw rounded corners	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The current position is neither used nor updated by this function.

See Also

Rectangle


SaveDC function
SaveDC (Win32)

int SaveDC(hdc)

HDC hdc;	/* handle of device context	*/

The SaveDC function saves the current state of the given 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.

Parameter	Description

hdc	Identifies the device context to be saved.

Returns

If the function succeeds, the return value identifies the saved device context. Otherwise, it is zero.

Comments

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 function
ScaleViewportExtEx (Win32)

BOOL ScaleViewportExtEx(hdc, Xnum, Xdenom, Ynum, Ydenom, lpSize)

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

The ScaleViewportExtEx function modifies the viewport for the given device context (DC) by using the ratios formed by the given multiplicands and divisors.

Parameter	Description

hdc	Identifies the DC.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The viewport extents are modified as follows:

    xNewVE = (xOldVE * Xnum) / Xdenom

    yNewVE = (yOldVE * Ynum) / Ydenom

See Also

GetViewportExtEx, SIZE


ScaleWindowExtEx function
ScaleWindowExtEx (Win32)

BOOL ScaleWindowExtEx(hdc, Xnum, Xdenom, Ynum, Ydenom, lpSize)

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

The ScaleWindowExtEx function modifies the window for the given device context (DC) using the ratios formed by the given multiplicands and divisors.

Parameter	Description

hdc	Identifies the DC.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The window extents are modified as follows:

    xNewWE = (xOldWE * Xnum) / Xdenom

    yNewWE = (yOldWE * Ynum) / Ydenom

See Also

GetWindowExtEx, SIZE


SelectClipPath function
SelectClipPath (Win32)

BOOL SelectClipPath(hdc, iMode)

HDC hdc;	/* handle of device context	*/
int iMode;	/* clipping mode	*/

The SelectClipPath function selects the current path as a clipping region for the given device context, combining the new region with any existing clipping region by using the specified mode.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. Use the GetLastError function to get the error value, which can be one of the following:

ERROR_CAN_NOT_COMPLETE

ERROR_INVALID_PARAMETER

ERROR_NOT_ENOUGH_MEMORY

Comments

The device context identified by the hdc parameter must contain a closed path.

See Also

BeginPath, EndPath


SelectClipRgn function
SelectClipRgn (Win32)

int SelectClipRgn(hdc, hrgn)

HDC hdc;	/* handle of device context	*/
HRGN hrgn;	/* handle of region to be selected	*/

The SelectClipRgn function selects the given region as the current clipping region for the given device context.

Parameter	Description

hdc	Identifies the device context.

hrgn	Identifies the region to be selected.

Returns

If the function succeeds, the return value specifies the region's complexity. It 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 not affected.)

Comments

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 the given region are specified in device units.

To remove a device-context's clipping region, specify a NULL region handle.

See Also

ExtSelectClipRgn


SelectObject function
SelectObject (Win32)

HGDIOBJ SelectObject(hdc, hgdiobj)

HDC hdc;	/* handle of DC	*/
HGDIOBJ hgdiobj;	/* handle of object	*/

The SelectObject function selects an object into the given device context (DC). The new object replaces the previous object of the same type.

Parameter	Description

hdc	Identifies the DC.

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

(Bitmaps can be selected for memory DCs only, and for only one DC at a time.)

Brush	CreateBrushIndirect, CreateDIBPatternBrush, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush

Font	CreateFont, CreateFontIndirect

Pen	CreatePen, CreatePenIndirect

Region	CombineRgn, CreateEllipticRgn, CreateEllipticRgnIndirect, CreatePolygonRgn, CreateRectRgn, CreateRectRgnIndirect

Returns

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.

Comments

This function returns the previously selected object of the given 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 DC at a time.

See Also

SelectClipRgn, SelectPalette


SelectPalette function
SelectPalette (Win32)

HPALETTE SelectPalette(hdc, hpal, bForceBackground)

HDC hdc;	/* handle of device context	*/
HPALETTE hpal;	/* handle of logical color-palette	*/
BOOL bForceBackground;	/* foreground/background mode	*/

The SelectPalette function selects the given logical palette into the given device context.

Parameter	Description

hdc	Identifies the device context (DC).

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 parameter 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 DC, this parameter is ignored.)

Returns

If the function succeeds, the return value identifies the device context's previous logical palette; otherwise, it is null. To get extended error information, use the GetLastError function.

Comments

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


SetAbortProc function
SetAbortProc (Win32)

int SetAbortProc(hdc, lpAbortProc)

HDC hdc;	/* handle of device context	*/
ABORTPROC lpAbortProc;	/* address of abort function	*/

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.

Parameter	Description

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 description of the AbortProc callback function.

Returns

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, use the GetLastError function.

See Also

AbortDoc, AbortProc


SetArcDirection function
SetArcDirection (Win32)

int SetArcDirection(hdc, ArcDirection)

HDC hdc;	/* identifies the device context	*/
int ArcDirection;	/* specifies the new arc direction	*/

The SetArcDirection sets the drawing direction to be used for arc and rectangle functions.

Parameter	Description

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.

Returns

If the function succeeds, the return value specifies the old arc direction; otherwise, it is zero.

Comments

The default direction is counterclockwise.

The SetArcDirection function specifies the direction in which the following functions draw:

Arc	ArcTo

Chord	Ellipse

Pie	Rectangle

RoundRect

See Also

Arc, ArcTo, Chord, Ellipse, Pie, Rectangle, RoundRect


SetBitmapBits function
SetBitmapBits (Win32)

LONG SetBitmapBits(hbmp, cBytes, lpBits)

HBITMAP hbmp;	/* handle of bitmap	*/
DWORD cBytes;	/* number of bytes in bitmap array	*/
CONST VOID *lpBits;	/* address of array with bitmap bits	*/

The SetBitmapBits function sets the bits of color data for the given bitmap to the specified values.

The SetBitmapBits function is included only for compatibility with earlier versions of Windows. For Win32 applications, use the SetDIBits function.

Parameter	Description

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 given bitmap.

Returns

If the function succeeds, the return value is the number of bytes used in setting the bitmap bits; otherwise, it is zero.

Comments

The array identified by lpBits must be WORD aligned.

See Also

GetBitmapBits, SetDIBits


SetBitmapDimensionEx function
SetBitmapDimensionEx (Win32)

BOOL SetBitmapDimensionEx(hBitmap, nWidth, nHeight, lpSize)

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

The SetBitmapDimensionEx function assigns preferred dimensions to a bitmap. These dimensions can be used by applications; however, they are not used by Windows.

Parameter	Description

hBitmap	Identifies the 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

An application can retrieve the dimensions assigned to a bitmap with the SetBitmapDimensionEx function by calling the GetBitmapDimensionEx function.

See Also

GetBitmapDimensionEx


SetBkColor function
SetBkColor (Win32)

COLORREF SetBkColor(hdc, crColor)

HDC hdc;	/* handle of device context	*/
COLORREF crColor;	/* background color value	*/

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.

Parameter	Description

hdc	Identifies the device context.

crColor	Specifies the new background color.

Returns

If the function succeeds, the return value specifies the previous background color as a COLORREF value. Otherwise, the return value is CLR_INVALID.

Comments

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, GetBkMode, SetBkMode


SetBkMode function
SetBkMode (Win32)

int SetBkMode(hdc, iBkMode)

HDC hdc;	/* handle of device context	*/
int iBkMode;	/* flag specifying background mode	*/

The SetBkMode function sets the background mix mode of the given device context (DC). The background mix mode is used with text, hatched brushes, and pen styles that are not solid lines.

Parameter	Description

hdc	Identifies the DC.

iBkMode	Specifies the background mode. This parameter can be either of the following modes:

Value	Description

OPAQUE	Background is filled with the current background color before the text, hatched brush, or pen is drawn.

TRANSPARENT	Background remains untouched.

Returns

If the function succeeds, the return value specifies the previous background mode; otherwise, it is zero.

Comments

This function affects the line styles for lines drawn using a pen created by the CreatePen function. This function does not affect lines drawn using a pen created by the ExtCreatePen function.

See Also

CreatePen, ExtCreatePen, GetBkMode


SetBoundsRect function
SetBoundsRect (Win32)

UINT SetBoundsRect(hdc, lprcBounds, flags)

HDC hdc;	/* handle of device context	*/
CONST RECT *lprcBounds;	/* address of structure for rectangle	*/
UINT flags;	/* controls rectangle combination	*/

The SetBoundsRect function controls the accumulation of bounding rectangle information for the given device context (DC). 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.

Parameter	Description

hdc	Identifies the DC 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.

Returns

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.

Comments

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


SetBrushOrgEx function
SetBrushOrgEx (Win32)

BOOL SetBrushOrgEx(hdc, nXOrg, nYOrg, lppt)

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

The SetBrushOrgEx function sets the brush origin that GDI assigns to the next brush an application selects into the specified device context (DC).

Parameter	Description

hdc	Identifies the DC.

nXOrg	Specifies the x-coordinate, in device units, of the new brush origin. This value must be in the range 0 through 7.

nYOrg	Specifies the y-coordinate, in device units, of the new brush origin. This value must be in the range 0 through 7.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, value 0 corresponds to the leftmost column of pixels; value 7 corresponds to the rightmost column. For vertical coordinates, 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 pixel at the brush's origin to the upper-left corner of the application window's client area.

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

See Also

GetBrushOrgEx, SetStretchBltMode


SetColorAdjustment function
SetColorAdjustment (new for 32-bit)

BOOL SetColorAdjustment(hdc, lpca)

HDC hdc;	/* handle of device context	*/
CONST COLORADJUSTMENT * lpca;	/* address of coloradjustment structure	*/

The SetColorAdjustment function sets the color adjustment values for the given device context using the specified values.

Parameter	Description

hdc	Identifies the device context.

lpca	Points to a COLORADJUSTMENT structure containing the color adjustment values.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

SetStretchBltMode, StretchBlt, StretchDIBits, COLORADJUSTMENT


SetDIBits function
SetDIBits (Win32)

int SetDIBits(hdc, hbmp, uStartScan, cScanLines, lpvBits, lpbmi, fuColorUse)

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

The SetDIBits function sets the pixels in the given bitmap using the color data found in the given device-independent bitmap (DIB).

Parameter	Description

hdc	Identifies a device context.

hbmp	Identifies the bitmap that is to be altered using the color data from the given 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.

DIB_PAL_INDICES	There is no color table for the bitmap. The array contains indices into the the system palette.

Returns

If the function succeeds, the return value is the number of scan lines copied; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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, Colors and Color Palettes.

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 device-independent bitmaps is the bottom left corner of the bitmap.

See Also

GetSystemPaletteEntries, BITMAPINFO


SetDIBitsToDevice function
SetDIBitsToDevice (Win32)

int SetDIBitsToDevice(hdc, XDest, YDest, dwWidth, dwHeight, XSrc, YSrc, uStartScan, cScanLines, lpvBits, lpbmi, fuColorUse)

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

The SetDIBitsToDevice function sets the pixels in the given rectangle on the device that is associated with the destination device context using color data from a device-independent bitmap (DIB).

Parameter	Description

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 data structure that contains information about the DIB.

fuColorUse	Specifies whether the bmiColors member of the BITMAPINFO data 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_PAL_INDICES	There is no color table for the bitmap. The array contains indices into the system palette. No color translation occurs.

DIB_RGB_COLORS	The color table contains literal RGB values.

Returns

If the function succeeds, the return value is the number of scan lines set; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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, Colors and Color Palettes.

The origin of a device-independent bitmap is the bottom left corner of the bitmap, not the top 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.

See Also

SetDIBits, StretchDIBits, BITMAPCOREINFO, BITMAPINFO, BITMAPCOREINFO, BITMAPINFO


SetEnhMetaFileBits function
SetEnhMetaFileBits (Win32)

HENHMETAFILE SetEnhMetaFileBits(cbBuffer, lpData)

UINT cbBuffer;	/* buffer size	*/
CONST BYTE * lpData;	/* buffer that contains enhanced metafile data	*/

The SetEnhMetaFileBits function creates a memory-based enhanced-format metafile from the supplied data.

Parameter	Description

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

Returns

If the function succeeds, the return value is a handle of a memory-based enhanced metafile; otherwise, it is NULL.

Comments

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


SetGraphicsMode function
SetGraphicsMode (Win32)

int SetGraphicsMode(hdc, iMode)

HDC hdc;	/* handle of the device context	*/
int iMode;	/* graphics mode	*/

The SetGraphicsMode function sets the graphics mode for the specified device context.

Parameter	Description

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 3.1. This is a 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 SetViewportExtent and SetWindowExtent.

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

Returns

If the function succeeds, the return value is the old graphics mode; otherwise, it is zero.

Comments

There are three areas in which graphics output differs according to the graphics mode:

1) Text Output: In the GM_COMPATIBLE mode, True Type (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 True Type 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 True type (or vector font) text is scaled appropriately. The only way to write non-horizontal text in the GM_COMPATIBLE mode is to specify non-zero escapement and orientation for the logical font selected in this DC.

In the GM_ADVANCED mode, True Type (or vector font) text output fully conforms to the world-to-device transform in the DC. The raster fonts only have very limited transformation capabilities (stretching by some integer factors); 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 counter-clockwise 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, SetArcDirection


SetMapMode function
SetMapMode (Win32)

int SetMapMode(hdc, fnMapMode)

HDC hdc;	/* handle of device context	*/
int fnMapMode;	/* new mapping mode	*/

The SetMapMode function sets the mapping mode of the given device context (DC)). 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.

Parameter	Description

hdc	Identifies the DC.

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

Returns

If the function succeeds, the return value identifies the previous mapping mode; otherwise, it is zero.

Comments

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 function
SetMapperFlags (Win32)

DWORD SetMapperFlags(hdc, dwFlag)

HDC hdc;	/* handle of device context	*/
DWORD dwFlag;	/* font-mapper flag	*/

The SetMapperFlags function alters the algorithm the font mapper uses when it maps logical fonts to physical fonts.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the previous value of the font-mapper flag; otherwise, it is GDI_ERROR. To get extended error information, use the GetLastError function.

Comments

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


SetMetaFileBitsEx function
SetMetaFileBitsEx (Win32)

HMETAFILE SetMetaFileBitsEx(nSize, lpData)

UINT nSize;	/* size of Windows-format metafile	*/
CONST BYTE * lpData;	/* address of buffer containing metafile data	*/

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. For Win32 applications, use the SetEnhMetaFileBits function.

Parameter	Description

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

Returns

If the function succeeds, the return value is a handle of a memory-based Windows-format metafile; otherwise, it is NULL.

Comments

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

DeleteMetaFile, GetMetaFileBitsEx, SetWinMetaFileBits


SetMetaRgn function
SetMetaRgn (Win32)

int SetMetaRgn(hdc)

HDC hdc;	/* handle of device context	*/

The SetMetaRgn function intersects the current clipping region for the given device context with the current metaregion and saves the combined region as the new metaregion for the given device context. The clipping region is reset to a null region.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value specifies the new clipping region's complexity. It 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.)

Comments

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


SetMiterLimit function
SetMiterLimit (Win32)

BOOL SetMiterLimit(hdc, eNewLimit, peOldLimit)

HDC hdc;	/* handle of device context	*/
FLOAT eNewLimit;	/* new miter limit	*/
PFLOAT peOldLimit;	/* previous miter limit	*/

The SetMiterLimit function sets the limit for the length of miter joins for the given device context.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


SetPaletteEntries function
SetPaletteEntries (Win32)

UINT SetPaletteEntries(hpal, iStart, cEntries, lppe)

HPALETTE hpal;	/* handle of palette	*/
UINT iStart;	/* index of first entry to set	*/
UINT cEntries;	/* number of entries to set	*/
CONST PALETTEENTRY *lppe;	/* address of array of structures	*/

The SetPaletteEntries function sets RGB (red, green, blue) color values and flags in a range of entries in a logical palette.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the number of entries that were set in the logical palette; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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, RealizePalette, PALETTEENTRY


SetPixel function
SetPixel (Win32)

COLORREF SetPixel(hdc, X, Y, crColor)

HDC hdc;	/* handle of device context	*/
int X;	/* x-coordinate of pixel	*/
int Y;	/* y-coordinate of pixel	*/
COLORREF crColor;	/* pixel color	*/

The SetPixel function sets the pixel at the specified coordinates to the specified color.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the original color of the pixel. If the specified coordinates correspond to a pixel outside the current clipping region, the return value is GDI_ERROR. If the function fails for any other reason, the return value is COLOR_INVALID. To get extended error information, use the GetLastError function.

Comments

The pixel at the specified coordinates must be within the boundaries of the current clipping region.

Not all devices support the SetPixel function. For more information, see the description of the GetDeviceCaps function.

See Also

GetDeviceCaps, SetPixelV


SetPixelV function
SetPixelV (Win32)

BOOL SetPixelV(hdc, X, Y, crColor)

HDC hdc;	/* handle of device context	*/
int X;	/* x-coordinate of pixel	*/
int Y;	/* y-coordinate of pixel	*/
COLORREF crColor;	/* new pixel color	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Not all devices support the SetPixelV function. For more information, see 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 function
SetPolyFillMode (Win32)

int SetPolyFillMode(hdc, iPolyFillMode)

HDC hdc;	/* handle of device context	*/
int iPolyFillMode;	/* polygon fill mode	*/

The SetPolyFillMode function sets the polygon fill mode for functions that fill polygons.

Parameter	Description

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

Returns

The return value specifies the previous filling mode. If an error occurs, the return value is zero.

Comments

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


SetRectRgn function
SetRectRgn (Win32)

BOOL SetRectRgn(hrgn, nLeftRect, nTopRect, nRightRect, nBottomRect)

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

The SetRectRgn function changes the given region into a rectangular region with the specified coordinates.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The region does not include the lower and right boundaries of the rectangle.

See Also

CreateRectRgn


SetROP2 function
SetROP2 (Win32)

int SetROP2(hdc, fnDrawMode)

HDC hdc;	/* handle of device context	*/
int fnDrawMode;	/* drawing mode	*/

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.

Parameter	Description

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_WHITE	Pixel is always 1.

R2_NOP	Pixel remains unchanged.

R2_NOT	Pixel is the inverse of the screen color.

R2_COPYPEN	Pixel is the pen color.

R2_NOTCOPYPEN	Pixel is the inverse of the pen color.

R2_MERGEPENNOT	Pixel is a combination of the pen color and the inverse of the screen color.

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_MASKNOTPEN	Pixel is a combination of the colors common to both the screen and the inverse of the pen.

R2_MERGEPEN	Pixel is a combination of the pen color and the screen color.

R2_NOTMERGEPEN	Pixel is the inverse of the R2_MERGEPEN color.

R2_MASKPEN	Pixel is a combination of the colors common to both the pen and the screen.

R2_NOTMASKPEN	Pixel is the inverse of the R2_MASKPEN color.

R2_XORPEN	Pixel is a combination of the colors in the pen and in the screen, but not in both.

R2_NOTXORPEN	Pixel is the inverse of the R2_XORPEN color.

Returns

If the function succeeds, the return value specifies the previous mix mode; otherwise, it is zero.

Comments

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


SetStretchBltMode function
SetStretchBltMode (Win32)

int SetStretchBltMode(hdc, iStretchMode)

HDC hdc;	/* handle of device context	*/
int iStretchMode;	/* bitmap stretching mode	*/

The SetStretchBltMode function sets the bitmap stretching mode in the given device context.

Parameter	Description

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.

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.

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 SetBrushOrgEx to set the brush origin. If it fails to do so, brush misalignment occurs.

Returns

If the function succeeds, the return value is the previous stretching-mode; otherwise, it is zero.

Comments

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 and WHITEONBLACK modes are typically used to preserve foreground pixels in monochrome bitmaps. The COLORONCOLOR 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.

See Also

SetBrushOrgEx, StretchBlt


SetSystemPaletteUse function
SetSystemPaletteUse (Win32)

UINT SetSystemPaletteUse(hdc, uUsage)

HDC hdc;	/* handle of device context	*/
UINT uUsage;	/* palette-usage flag	*/

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

Parameter	Description

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. It can be either of these 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.

Returns

If the function succeeds, the return value is the previous usage of the system palette (it can be either SYSPAL_NOSTATIC or SYSPAL_STATIC); otherwise, it is SYSPAL_ERROR. To get extended error information, use the GetLastError function.

Comments

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 SYSPAL_NOSTATIC is set, the application must call GetSysColor 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 given 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 follow these 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


SetTextAlign function
SetTextAlign (Win32)

UINT SetTextAlign(hdc, fMode)

HDC hdc;	/* handle of device context	*/
UINT fMode;	/* text-alignment flag	*/

The SetTextAlign function sets the text-alignment flags for the given device context.

Parameter	Description

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

Returns

If the function succeeds, the return value is the previous text-alignment setting; otherwise, it is GDI_ERROR. To get extended error information, use the GetLastError function.

Comments

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, TextOut


SetTextCharacterExtra function
SetTextCharacterExtra (Win32)

int SetTextCharacterExtra(hdc, nCharExtra)

HDC hdc;	/* handle of device context	*/
int nCharExtra;	/* extra-space value	*/

The SetTextCharacterExtra function sets the intercharacter spacing. Intercharacter spacing is added to each character, including break characters, when Windows writes a line of text.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the previous intercharacter spacing.

See Also

DrawText, TextOut


SetTextColor function
SetTextColor (Win32)

COLORREF SetTextColor(hdc, crColor)

HDC hdc;	/* handle of device context	*/
COLORREF crColor;	/* text color	*/

The SetTextColor function sets the text color for the given device context to the specified color.

Parameter	Description

hdc	Identifies the device context.

crColor	Specifies the color of the text.

Returns

If the function succeeds, the return value is a color reference for the previous text color; otherwise, it is CLR_INVALID. To get extended error information, use the GetLastError function.

Comments

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, RGB, SetBkColor, StretchBlt, TextOut, RGB


SetTextJustification function
SetTextJustification (Win32)

BOOL SetTextJustification(hdc, nBreakExtra, nBreakCount)

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

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 GetTextExtentPoint function is always used with the SetTextJustification function. The GetTextExtentPoint 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, GetTextExtentPoint, GetTextMetrics, TextOut


SetViewportExtEx function
SetViewportExtEx (Win32)

BOOL SetViewportExtEx(hdc, nXExtent, nYExtent, lpSize)

HDC hdc;	/* handle of device context	*/
int nXExtent;	/* new horizontal viewport extent	*/
int nYExtent;	/* new vertical viewport extent	*/
LPSIZE lpSize;	/* original viewport extent	*/

The SetViewportExtEx function sets the horizontal and vertical extents of the viewport for the given device context by using the specified values.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 function
SetViewportOrgEx (Win32)

BOOL SetViewportOrgEx(hdc, X, Y, lpPoint)

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

The SetViewportOrgEx function sets the viewport origin of the given device context (DC) by using the specified coordinates.

Parameter	Description

hdc	Identifies the DC.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

GetViewportOrgEx, SetWindowOrgEx, POINT


SetWindowExtEx function
SetWindowExtEx (Win32)

BOOL SetWindowExtEx(hdc, nXExtent, nYExtent, lpSize)

HDC hdc;	/* handle of device context	*/
int nXExtent;	/* new horizontal window extent	*/
int nYExtent;	/* new vertical window extent	*/
LPSIZE lpSize;	/* original window extent	*/

The SetWindowExtEx function sets the horizontal and vertical extents of the window for the given device context (DC) by using the specified values.

Parameter	Description

hdc	Identifies the DC.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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


SetWindowOrgEx function
SetWindowOrgEx (Win32)

BOOL SetWindowOrgEx(hdc, X, Y, lpPoint)

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

The SetWindowOrgEx function sets the window origin of the given device context (DC) by using the specified coordinates.

Parameter	Description

hdc	Identifies the DC.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

GetViewportOrgEx, GetWindowOrgEx, SetViewportOrgEx


SetWinMetaFileBits function
SetWinMetaFileBits (Win32)

HENHMETAFILE SetWinMetaFileBits(cbBuffer, lpbBuffer, hdcRef, lpmfp)

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

The SetWinMetaFileBits function converts a metafile from the older Windows format to the new enhanced format and stores the new metafile in memory.

Parameter	Description

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.

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.

Returns

If the function succeeds, the return value is a handle of a memory-based enhanced metafile; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

Windows uses the reference device'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 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, PlayEnhMetaFile, METAFILEPICT


SetWorldTransform function
SetWorldTransform (Win32)

BOOL SetWorldTransform(hdc, lpXform)

HDC hdc;	/* handle of device context	*/
CONST XFORM * lpXform;	/* address of transformation data	*/

The SetWorldTransform function sets a two-dimensional linear transformation between world space and page space for the given device context (DC). This transformation can be used to scale, rotate, shear, or translate graphics output.

Parameter	Description

hdc	Identifies the device context (DC).

lpXform	Points to an XFORM structure that contains the transformation data.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 graphics mode for the given device context (DC) has been set to GM_ADVANCED by previosly calling the SetGraphicsMode function. Likewise, it will not be possible to reset the graphics mode for the DC to the default GM_COMPATIBLE mode, unless the world transform has first been reset to the dafault identity transform by calling SetWorldTransform or ModifyWorldTransform.

See Also

GetWorldTransform, ModifyWorldTransform, SetGraphicsMode, SetMapMode, SetViewportExtEx, SetViewportOrgEx, SetWindowExtEx, SetWindowOrgEx, XFORM


StartDoc function
StartDoc (Win32)

int StartDoc(hdc, lpdi)

HDC hdc;	/* handle of device context	*/
CONST DOCINFO * lpdi;	/* address of structure with file names	*/

The StartDoc function starts a print job. This function replaces the STARTDOC printer escape.

Parameter	Description

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.

Returns

If the function succeeds, the return value is greater than zero. This value is the job identifier for the document.

If the function fails, the return value is SP_ERROR. To get extended error information, use the GetLastError function.

Comments

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

EndDoc, GetJob, SetJob, DOCINFO


StartPage function
StartPage (Win32)

int StartPage(hDC)

HDC hDC;	/* handle of device context	*/

The StartPage function prepares the printer driver to accept data.

Parameter	Description

hDC	Identifies the device context for the print job.

Returns

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, use the GetLastError function.

Comments

The system disables the ResetDC function between calls to the StartPage and EndPage functions. This means that an application cannot change the device mode except at page boundaries.

See Also

EndPage,, ResetDC


StretchBlt function
StretchBlt (Win32)

BOOL StretchBlt(hdcDest, nXOriginDest, nYOriginDest, nWidthDest, nHeightDest, hdcSrc, nXOriginSrc, nYOriginSrc, nWidthSrc, nHeightSrc, dwRop)

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

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.

Parameter	Description

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.

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

For further information on raster operations, and complete lists of all the raster operation codes, see RasterOperationCodes.

Returns

If the function was successful, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 description of the GetDeviceCaps function.

See Also

BitBlt, GetDeviceCaps, MaskBlt, PlgBlt, SetStretchBltMode


StretchDIBits function
StretchDIBits (Win32)

int StretchDIBits(hdc, XDest, YDest, nDestWidth, nDestHeight, XSrc, YSrc, nSrcWidth, nSrcHeight, lpBits, lpBitsInfo, iUsage, dwRop)

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

The StretchDIBits function copies the color data for a rectangle of pixels in a device-independent bitmap (DIB) to the given 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.

Parameter	Description

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.

DIB_PAL_INDICES	There is no color table for the bitmap. The DIB itself contains indices into the system palette. No color translation occurs.

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.

Returns

If the function succeeds, the return value is the number of scan lines copied; otherwise, it is GDI_ERROR. To get extended error information, use the GetLastError function.

Comments

The origin of a DIB is the lower-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, BITMAPCOREINFO


StrokeAndFillPath function
StrokeAndFillPath (Win32)

BOOL StrokeAndFillPath(hdc)

HDC hdc;	/* handle of device context	*/

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.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. Use the GetLastError function to get the error value, which may be one of the following:

ERROR_CAN_NOT_COMPLETE

ERROR_INVALID_PARAMETER

ERROR_NOT_ENOUGH_MEMORY

Comments

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 function
StrokePath (Win32)

BOOL StrokePath(hdc)

HDC hdc;	/* handle of device context	*/

The StrokePath function renders the specified path by using the current pen.

Parameter	Description

hdc	Identifies a device context that contains a closed path.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. Use the GetLastError function to get the error value, which may be one of the following:

ERROR_CAN_NOT_COMPLETE

ERROR_INVALID_PARAMETER

ERROR_NOT_ENOUGH_MEMORY

Comments

The device context identified by the hdc parameter must contain a closed path.

See Also

BeginPath, EndPath, ExtCreatePen,


TextOut function
TextOut (Win32)

BOOL TextOut(hdc, nXStart, nYStart, lpszString, cbString)

HDC hdc;	/* handle of device context	*/
int nXStart;	/* x-coordinate of starting position	*/
int nYStart;	/* y-coordinate of starting position	*/
LPCTSTR lpszString;	/* address of string	*/
int cbString;	/* number of characters in string	*/

The TextOut function writes a character string at the specified location, using the currently selected font.

Parameter	Description

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.

lpszString	Points to the string to be drawn.

cbString	Specifies the number of characters in the string.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 given 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. Thus, the region generated by this path is the area enclosed by the character box and the outline of the TrueType text. That is, the region generated is the character box minus the text, rather than the text itself. This is not intuitive. However, 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. Here is some sample code that shows the non-intuitive situation and the commented-out fix to that situation :

// 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 on out into the world

TextOut(hdc, r.left, r.top, "Windows NT Rules Well & Wisely", 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));

// okay, fill the region with grayness

FillRect(hdc, &r, GetStockObject(GRAY_BRUSH));

See Also

GetTextAlign, SetTextAlign, TabbedTextOut


UpdateColors function
UpdateColors (Win32)

BOOL UpdateColors(hdc)

HDC hdc;	/* handle of device context	*/

The UpdateColors function updates the client area of the given device context by remapping the current colors in the client area to the currently realized logical palette.

Parameter	Description

hdc	Identifies the device context.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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_SYSPALETTECHANGE message is received.

See Also

GetDeviceCaps, RealizePalette


WidenPath function
WidenPath (Win32)

BOOL WidenPath(hdc)

HDC hdc;	/* handle of device context	*/

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.

Parameter	Description

hdc	Identifies a device context that contains a closed path.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. Use the GetLastError function to get extended error information, which can be one of the following:

ERROR_CAN_NOT_COMPLETE

ERROR_INVALID_PARAMETER

ERROR_NOT_ENOUGH_MEMORY

Comments

This 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, EndPath, SetMiterLimit


GetAspectRatioFilter function
GetAspectRatioFilter (Win32)

The GetAspectRatioFilter function has been deleted. For Win32 applications, use the GetAspectRatioFilterEx function.

See Also

GetAspectRatioFilterEx


GetBitmapDimension function
GetBitmapDimension (Win32)

The GetBitmapDimension function has been deleted. For Win32 applications, use the GetBitmapDimensionEx function.

See Also

GetBitmapDimensionEx


GetBrushOrg function
GetBrushOrg (Win32)

The GetBrushOrg function has been deleted. For Win32 applications, use the GetBrushOrgEx function.

See Also

GetBrushOrgEx


GetCurrentPosition function
GetCurrentPosition (Win32)

The GetCurrentPosition function has been deleted. Win32 should use the GetCurrentPositionEx function.

See Also

GetCurrentPositionEx


GetMetaFileBits function
GetMetaFileBits (Win32)

The GetMetaFileBits function has been deleted. For Win32 applications, use the GetMetaFileBitsEx function.

See Also

GetMetaFileBitsEx


GetTextExtent function
GetTextExtent (Win32)

The GetTextExtent function has been deleted. For Win32 applications, use the GetTextExtentPoint function.

See Also

GetTextExtentPoint


GetViewportExt function
GetViewportExt (Win32)

The GetViewportExt function has been deleted. Win32 applications should use the GetViewportExtEx function.

See Also

GetViewportExtEx


GetViewportOrg function
GetViewportOrg (Win32)

The GetViewportOrg function has been deleted. Win32 applications should use the GetViewportOrgEx function.

See Also

GetViewportOrgEx


GetWindowExt function
GetWindowExt (Win32)

The GetWindowExt function has been deleted. Win32 applications should use the GetWindowExtEx function.

See Also

GetWindowExtEx


GetWindowOrg function
GetWindowOrg (Win32)

The GetWindowOrg function has been deleted. Win32 applications should use the GetWindowOrgEx function.

See Also

GetWindowOrgEx


MoveTo function
MoveTo (Win32)

The MoveTo function has been deleted. Win32 applications should use the MoveToEx function.

See Also

MoveToEx


OffsetViewportOrg function
OffsetViewportOrg (Win32)

The OffsetViewportOrg function has been deleted. Win32 applications should use the OffsetViewportOrgEx function.

See Also

OffsetViewportOrgEx


OffsetWindowOrg function
OffsetWindowOrg (Win32)

The OffsetWindowOrg function has been deleted. Win32 applications should use the OffsetWindowOrgEx function.

See Also

OffsetWindowOrgEx


ScaleViewportExt function
ScaleViewportExt (Win32)

The ScaleViewportExt function has been deleted. Win32 applications should use the ScaleViewportExtEx function.

See Also

ScaleViewportExtEx


ScaleWindowExt function
ScaleWindowExt (Win32)

The ScaleWindowExt function has been deleted. Win32 applications should use the ScaleWindowExtEx function.

See Also

ScaleWindowExtEx


SetBitmapDimension function
SetBitmapDimension (Win32)

The SetBitmapDimension function has been deleted. For Win32 applications, use the SetBitmapDimensionEx function.

See Also

SetBitmapDimensionEx


SetBrushOrg function
SetBrushOrg (Win32)

The SetBrushOrg function is obsolete. For Win32 applications, use the SetBrushOrgEx function.


SetMetaFileBits function
SetMetaFileBits (Win32)

The SetMetaFileBits function has been deleted. For Win32 applications, use the SetMetaFileBitsEx function.

See Also

SetMetaFileBitsEx


SetViewportExt function
SetViewportExt (Win32)

The SetViewportExt function has been deleted. Win32 applications should use the SetViewportExtEx function.

See Also

SetViewportExtEx


SetViewportOrg function
SetViewportOrg (Win32)

The SetViewportOrg function has been deleted. Win32 applications should use the SetViewportOrgEx function.

See Also

SetViewportOrgEx


SetWindowExt function
SetWindowExt (Win32)

The SetWindowExt function has been deleted. Win32 applications should use the SetWindowExtEx function.

See Also

SetWindowExtEx


SetWindowOrg function
SetWindowOrg (Win32)

The SetWindowOrg function has been deleted. Win32 applications should use the SetWindowOrgEx function.

See Also

SetWindowOrgEx


UnrealizeObject function
UnrealizeObject (Win32)

BOOL UnrealizeObject(HGDIOBJ)

HGDIOBJ hgdiobj;	/* logical palette handle	*/

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.

In Win16, UnrealizeObject could also be used to reset the origin of a brush. It does not have that behavior in Win32. If hgdiobj is a brush, the Win32 version of UnrealizeObject does nothing, and the function returns TRUE. Win32 applications should use SetBrushOrgEx to set the origin of a brush.

Parameter	Description

hgdiobj	Identifies the object to be reset. For the Win32 version of this function, hgdiobj should be a handle to a logical palette; if it is a handle to a brush, the function does nothing.

Returns

If the function succeeds, the return value is TRUE; otherwise it is FALSE. Call GetLastError for further error information.

If hgdiobj is a brush handle, the function does nothing, and returns TRUE.

Comments

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

RealizePalette, SetBrushOrgEx


GDI Functions (all)

AbortDoc	Terminates a print job

AbortPath	Aborts and discards any paths in a DC

AddFontResource	Adds a font to the font table

AngleArc	Draws an arc with specified angle

AnimatePalette	Replaces entries in a logical palette

Arc	Draws an arc

ArcTo	Draws an elliptical arc

BeginPath	Starts a path bracket

BitBlt	Copies a bitmap between device contexts

CancelDC	Cancels any pending operation on specified DC

Chord	Draws a chord

CloseEnhMetaFile	Closes an enhanced metafile DC

CloseFigure	Closes a figure in a path

CloseMetaFile	Closes a Windows metafile DC

CombineRgn	Creates a region by combining two regions

CombineTransform	Combines two transforms

CopyEnhMetaFile	Copies an enhanced metafile

CopyMetaFile	Copies a Windows metafile

CreateBitmap	Creates device-dependent memory bitmap

CreateBitmapIndirect	Creates bitmap using BITMAP structure

CreateBrushIndirect	Creates a brush with specified attributes

CreateCompatibleBitmap	Creates bitmap compatible with DC

CreateCompatibleDC	Creates a DC compatible with specified DC

CreateDC	Creates a device context

CreateDIBitmap	Creates bitmap handle from DIB spec

CreateDIBPatternBrush	Creates a pattern brush from a DIB

CreateDIBPatternBrushPt	Creates logical brush from bitmap

CreateDIBSection	Creates a bitmap from a DIB

CreateDiscardableBitmap	Creates discardable bitmap

CreateEllipticRgn	Creates an elliptical region

CreateEllipticRgnIndirect	Creates an elliptical region

CreateEnhMetaFile	Creates an enhanced metafile DC

CreateFont	Creates a logical font

CreateFontIndirect	Creates a font using LOGFONT structure

CreateHalftonePalette	Create halftone palette for a device context

CreateHatchBrush	Creates a hatched brush

CreateIC	Creates an information context

CreateMetaFile	Creates a Windows metafile DC

CreatePalette	Creates a logical color palette

CreatePatternBrush	Creates a pattern brush from a bitmap

CreatePen	Creates a logical pen

CreatePenIndirect	Creates a pen using a LOGPEN structure

CreatePolygonRgn	Creates a polygonal region

CreatePolyPolygonRgn	Creates a region consisting of polygons

CreateRectRgn	Creates a rectangular region

CreateRectRgnIndirect	Creates a region using a RECT structure

CreateRoundRectRgn	Creates rectangular region with round corners

CreateScalableFontResource	Creates resource file with font info

CreateSolidBrush	Creates a solid brush with a specified color

DeleteDC	Deletes a device context

DeleteEnhMetaFile	Invalidates enhanced metafile handle

DeleteMetaFile	Invalidates Windows metafile handle

DeleteObject	Deletes an object from memory

DeviceCapabilities	Obtains device-driver capabilities

DeviceCapabilitiesEx	Not implemented; use Device Capabilities

DPtoLP	Converts device coordinates to logical

DrawEscape	Allows direct access to device

Ellipse	Draws an ellipse

EndDoc	Ends a print job

EndPage	Ends a page

EndPath	Ends a path bracket

EnumEnhMetaFile	Returns GDI calls within an enhanced metafile

EnumFontFamilies	Retrieves fonts in a specified family

EnumFonts	Enumerates fonts on specified device

EnumMetaFile	Returns GDI calls within a Windows metafile

EnumObjects	Enumerates pens and brushes in a device context

EqualRgn	Compares two regions for equality

Escape	Allows access to device

ExcludeClipRect	Changes clipping region, excluding rectangle

ExtCreatePen	Creates a logical pen

ExtCreateRegion	Creates a region from region data

ExtEscape	Allows access to private device

ExtFloodFill	Fills area with current brush

ExtSelectClipRgn	Selects a region as a clip region

ExtTextOut	Writes a character string in rectangular region

FillPath	Fills the current path

FillRgn	Fills a region with a brush

FixBrushOrgEx	Not implemented for Win32

FlattenPath	Transforms curves to lines

FloodFill	Fills area with current brush

FrameRgn	Draws a border around a region

GdiComment	Adds a comment to an enhanced metafile

GdiFlush	Flushes the calling thread's current GDI batch

GdiGetBatchLimit	Returns number of buffered GDI functions

GdiSetBatchLimit	Sets number of buffered GDI functions

GetArcDirection	Returns arc and rectangle drawing direction

GetAspectRatioFilterEx	Retrieves current aspect-ratio filter

GetBitmapBits	Copies bitmap bits to a buffer

GetBitmapDimensionEx	Retrieves width and height of bitmap

GetBkColor	Retrieves the current background color

GetBkMode	Retrieves the background mode

GetBoundsRect	Returns current accumulated bounding rectangle

GetBrushOrgEx	Retrieves the origin of the current brush

GetCharABCWidths	Retrieves widths of consecutive characters

GetCharABCWidthsFloat	Retrieves widths of consecutive characters

GetCharWidth	Retrieves character widths

GetCharWidth32	Retrieves character widths

GetCharWidthFloat	Returns fractional character widths

GetClipBox	Retrieves rectangle for clipping region

GetClipRgn	Returns current clipping region

GetColorAdjustment	Get color adjustment for a device context

GetCurrentObject	Returns the currently selected object

GetCurrentPositionEx	Retrieves position in logical units

GetDCOrg	Obsolete; use GetDCOrgEx instead

GetDCOrgEx	Retrieves translation origin for device context

GetDeviceCaps	Retrieves device capabilities

GetDIBits	Copies DIB bits into a buffer

GetEnhMetaFile	Creates an enhanced metafile

GetEnhMetaFileBits	Copies enhanced metafile bits to a buffer

GetEnhMetaFileDescription	Returns creator and title for enhanced metafile

GetEnhMetaFileHeader	Returns enhanced metafile header

GetEnhMetaFilePaletteEntries	Returns enhanced metafile palette entries

GetFontData	Retrieves font metric data

GetGlyphOutline	Retrieves data for individual outline character

GetGraphicsMode	Retrieves the graphics mode for the specified DC

GetKerningPairs	Returns current font kerning pairs

GetMapMode	Retrieves mapping mode

GetMetaFile	Creates a Windows metafile

GetMetaFileBitsEx	Copies Windows metafile bits to a buffer

GetMetaRgn	Returns current meta region

GetMiterLimit	Returns current miter-join length

GetNearestColor	Retrieves closest available color

GetNearestPaletteIndex	Retrieves nearest match for a color

GetObject	Retrieves information about an object

GetObjectType	Returns object type

GetOutlineTextMetrics	Retrieves metrics for TrueType fonts

GetPaletteEntries	Retrieves range of palette entries

GetPath	Returns all lines and curves in path

GetPixel	Retrieves RGB color of specified pixel

GetPolyFillMode	Retrieves the current polygon-filling mode

GetRasterizerCaps	Retrieves status of TrueType on system

GetRegionData	Retrieves region data

GetRgnBox	Retrieves bounding rectangle for region

GetROP2	Retrieves the current drawing mode

GetStockObject	Retrieves handle of a stock pen, brush, or font

GetStretchBltMode	Retrieves the current bitmap-stretching mode

GetSystemPaletteEntries	Retrieves entries from system palette

GetSystemPaletteUse	Determines use of entire system palette

GetTextAlign	Retrieves text-alignment flags

GetTextCharacterExtra	Retrieves intercharacter spacing

GetTextColor	Retrieves current text color

GetTextExtentExPoint	Retrieves an array of sub-string lengths

GetTextExtentPoint	Retrieves dimensions of string

GetTextExtentPoint32	Retrieves dimensions of string

GetTextFace	Retrieves typeface name of the current font

GetTextMetrics	Retrieves the metrics for the current font

GetViewportExtEx	Retrieves viewport extent

GetViewportOrgEx	Retrieves viewport origin

GetWindowExtEx	Retrieves window extents

GetWindowOrgEx	Retrieves window origin

GetWinMetaFileBits	Retrieves metafile contents in Windows format

GetWorldTransform	Returns current world transform

IntersectClipRect	Creates clipping region from intersection

InvertRgn	Inverts the colors in a region

LineDDA	Computes successive points in a line

LineTo	Draws a line from the current position

LPtoDP	Converts logical points to device points

MaskBlt	Transfers a bitmap through a mask

ModifyWorldTransform	Changes the current world transform

MoveToEx	Moves the current position

OffsetClipRgn	Moves a clipping region

OffsetRgn	Moves a region by a specified offset

OffsetViewportOrgEx	Moves viewport origin

OffsetWindowOrgEx	Moves window origin

PaintRgn	Fills region with brush in device context

PatBlt	Creates a bitmap pattern

PathToRegion	Creates a region from a path

Pie	Draws a pie-shaped wedge

PlayEnhMetaFile	Plays an enhanced metafile to a DC

PlayEnhMetaFileRecord	Plays an enhanced metafile record

PlayMetaFile	Plays a Windows metafile to a DC

PlayMetaFileRecord	Plays a Windows metafile record

PlgBlt	Transfers a block of pixels

PolyBezier	Draws Bezier splines

PolyBezierTo	Draws Bezier splines

PolyDraw	Draws a set of lines and Bezier splines

PolyTextOut	Draws several strings

Polygon	Draws a polygon

Polyline	Draws line segments to connect specified points

PolylineTo	Draws one or more straight lines

PolyPolygon	Draws a series of polygons

PolyPolyline	Draws connected line segments

PtInRegion	Queries whether a point is in a region

PtVisible	Queries whether point is within clipping region

RealizePalette	Maps entries from logical to system palette

Rectangle	Draws a rectangle

RectInRegion	Queries whether rectangle overlaps region

RectVisible	Queries whether rectangle is in clip region

RemoveFontResource	Removes font resource

ResetDC	Updates a device context

ResizePalette	Changes the size of a logical palette

RestoreDC	Restores device context

RoundRect	Draws a rectangle with rounded corners

SaveDC	Saves current state of device context

ScaleViewportExtEx	Scales viewport extents

ScaleWindowExtEx	Scales window extents

SelectClipPath	Selects current path as clip region

SelectClipRgn	Selects clipping region for device context

SelectObject	Selects object into a device context

SelectPalette	Selects a palette into a device context

SetAbortProc	Sets the abort function for a print job

SetArcDirection	Sets arc and rectangle drawing direction

SetBitmapBits	Sets bitmap bits from array of bytes

SetBitmapDimensionEx	Sets width and height of bitmap

SetBkColor	Sets the current background color

SetBkMode	Sets the background mode

SetBoundsRect	Controls bounding-rectangle accumulation

SetBrushOrgEx	Sets the origin of the current brush

SetColorAdjustment	Set color adjustment for a device context

SetDIBits	Sets the bits of a bitmap

SetDIBitsToDevice	Sets DIB bits to device

SetEnhMetaFileBits	Creates a memory-based enhanced metafile from data

SetGraphicsMode	Sets the graphics mode for the specified DC

SetMapMode	Sets mapping mode

SetMapperFlags	Sets font-mapper flag

SetMetaFileBitsEx	Creates a memory-based Windows metafile from data

SetMetaRgn	Selects the clip region as a meta region

SetMiterLimit	Sets miter-join length

SetPaletteEntries	Sets colors and flags for a color palette

SetPixel	Sets pixel to specified color

SetPixelV	Sets pixel to specified color

SetPolyFillMode	Sets the polygon-filling mode

SetRectRgn	Changes a region into specified rectangle

SetROP2	Sets the current drawing mode

SetStretchBltMode	Sets the bitmap-stretching mode

SetSystemPaletteUse	Use of system palette static colors

SetTextAlign	Sets text-alignment flags

SetTextCharacterExtra	Sets intercharacter spacing

SetTextColor	Sets the foreground color of text

SetTextJustification	Sets justification for text output

SetViewportExtEx	Sets viewport extents

SetViewportOrgEx	Sets viewport origin

SetWindowExtEx	Sets window extents

SetWindowOrgEx	Sets the window origin

SetWinMetaFileBits	Creates enhanced metafile from Windows metafile data

SetWorldTransform	Sets the current world transform

StartDoc	Starts a print job

StartPage	Prepares printer driver to receive data

StretchBlt	Copies a bitmap, transforming if required

StretchDIBits	Moves DIB from source to destination rectangle

StrokeAndFillPath	Closes, strokes and fills a path

StrokePath	Renders a path with the current pen

TextOut	Writes a character string at specified location

UpdateColors	Updates colors in client area

WidenPath	Sets the current path to pen width

GetAspectRatioFilter	Obsolete

GetBitmapDimension	Obsolete

GetBrushOrg	Obsolete

GetCurrentPosition	Obsolete

GetMetaFileBits	Obsolete

GetTextExtent	Obsolete

GetViewportExt	Obsolete

GetViewportOrg	Obsolete

GetWindowExt	Obsolete

GetWindowOrg	Obsolete

MoveTo	Obsolete

OffsetViewportOrg	Obsolete

OffsetWindowOrg	Obsolete

ScaleViewportExt	Obsolete

ScaleWindowExt	Obsolete

SetBitmapDimension	Obsolete

SetBrushOrg	Obsolete

SetMetaFileBits	Obsolete

SetViewportExt	Obsolete

SetViewportOrg	Obsolete

SetWindowExt	Obsolete

SetWindowOrg	Obsolete

UnrealizeObject	Resets a logical palette


AbnormalTermination function
AbnormalTermination (Win32)

BOOL AbnormalTermination(VOID)

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.

Returns

If the try block of the try-finally statement terminated abnormally, the return value is TRUE; otherwise, it is FALSE.

Comments

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.


AbortSystemShutdown function
AbortSystemShutdown (Win32)

BOOL AbortSystemShutdown(lpszMachineName)

LPTSTR lpszMachineName;	/* addr. of name of computer to stop shutting down	*/

The AbortSystemShutdown function stops a system shutdown started by using the InitiateSystemShutdown function.

Parameter	Description

lpszMachineName	Points to the null-terminated string that specifies the network name of the computer where the shutdown is to be stopped. If lpszMachineName is NULL or points to an empty string, the function stops the shutdown on the local computer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 this function are typically due to an invalid computer name, an inaccessible computer, or insufficient privilege.

See Also

InitiateSystemShutdown


AddAtom function
AddAtom (Win32)

ATOM AddAtom(lpszName)

LPCTSTR lpszName;	/* address of string to add	*/

The AddAtom function adds a character string to the local atom table and returns a unique value (an atom) identifying the string.

Parameter	Description

lpszName	Points to the null-terminated string to be added. Strings differing only in case are considered identical. The case of the first string added is preserved and returned by the GetAtomName function.

Returns

If the function succeeds, the return value is the newly created atom; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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 lpszName 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 lpszName is in the range 0x0001 through 0xBFFF, the return value is the low-order word of lpszName.

See Also

DeleteAtom, FindAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName, MAKEINTATOM


AcsLan function
AcsLan (Win32)

ACSLAN_STATUS AcsLan(pCcb, ppBadCcb)

PLLC_CCB pCcb;	/* CCB control block	*/
PLLC_CCB * ppBadCcb ;	/* pointer for invalid CCB control blocks	*/

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 the AcsLan function can complete synchronously or asynchronously. The DLC driver, not the caller, determines how a command completes. This is unlike Netbios, for example, in which commands complete synchronously or asynchronously as requested by the caller.

There are some differences between NT DLC and the CCB2 interface documented in the IBM LAN Technical Reference. The most notable is that the buffer pool must be specified on an open adapter instance basis, and not per-SAP. 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.

Parameter	Description

pCcb	Points to an LLC_CCB structure describing the function being performed. Please refer to the IBM LAN Technical Reference for details of this structure.

ppBadCcb	Points to a pointer to an LLC_CCB structure. This parameter is used when a chain of CCBs is submitted. If not NULL on input, this pointer will contain a pointer to the first invalid CCB discovered in the chain.

Returns

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 other timing considerations. This return code does not mean that the command completed successfully. The caller must check the uchDlcStatus field in the CCB to determine whether the request succeeded or failed.

ACSLAN_STATUS_INVALID_CCB_POINTER

A pointer in the CCB structure or the parameter table is invalid.

ACSLAN_STATUS_CCB_IN_ERROR

A problem was detected with the CCB. The caller should check the values in the CCB and resubmit it.

ACSLAN_STATUS_CHAINED_CCB_IN_ERROR

A problem was detected with a CCB in a chain of CCBs.

ACSLAN_STATUS_SYSTEM_ERROR

This code is not used.

ACSLAN_STATUS_SYSTEM_STATUS

This code is not used.

ACSLAN_STATUS_INVALID_COMMAND

The command in the uchDlcCommand field of the CCB is unrecognized.

See Also

Netbios


AllocConsole function
AllocConsole (Win32)

BOOL AllocConsole(VOID)

The AllocConsole function allocates a new console for the calling process.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

A process can only be associated with one console, so AllocConsole 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 specified).

See Also

CreateProcess, FreeConsole, GetStdHandle


BackupEventLog function
BackupEventLog (Win32)

BOOL BackupEventLog(hEventLog, lpszBackupFileName)

HANDLE hEventLog;	/* handle to event log	*/
LPCTSTR lpszBackupFileName;	/* name of backup file	*/

The BackupEventLog function saves the given event log to a backup file. The function does not clear the event log.

Parameter	Description

hEventLog	Identifies the open event log. This handle is returned by the OpenEventLog or OpenBackupEventLog function.

lpszBackupFileName	Points 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


BackupRead function
BackupRead (Win32)

BOOL BackupRead(hFileHandle, lpBuffer, dwNumberOfBytesToRead, lpdwNumberOfBytesRead, bAbort, bProcessSecurity, lpContext)

HANDLE hFileHandle;	/* handle of open file	*/
LPBYTE lpBuffer;	/* address of buffer to read to	*/
DWORD dwNumberOfBytesToRead;	/* number of bytes to read	*/
LPDWORD lpdwNumberOfBytesRead;	/* address of no. of bytes read	*/
BOOL bAbort;	/* termination type	*/
BOOL bProcessSecurity;	/* process security flag	*/
LPVOID *lpContext;	/* internal context information	*/

The BackupRead function reads into a buffer the data associated with a file.

Parameter	Description

hFileHandle	Identifies the file or directory being backed up. This handle is created by using the CreateFile function.

lpBuffer	Points to the buffer where the data stream is to be placed.

dwNumberOfBytesToRead	Specifies the length of the buffer. The buffer size must be greater than the size of a WIN32_STREAM_ID structure.

lpdwNumberOfBytesRead	Points to a doubleword that, when the function returns, contains the number of bytes read. If this parameter is zero and the return value is TRUE, 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 were deallocated.

bProcessSecurity	Indicates whether the access-control list (ACL) data for the opened object will be backed up. If this value is TRUE, the ACL data will be backed up.

lpContext	Points to an internal structure used only by this function. Storage for this structure is allocated by BackupRead. This parameter must point to a NULL value before the first call to the file or directory to be read. When the function returns, this parameter contains reserved information. This parameter must not be changed between calls to BackupRead. To deallocate the storage for this information, your application should call BackupRead with the bAbort parameter set to TRUE before exiting.

Returns

If the transfer of data to the buffer succeeds, the return value is TRUE; otherwise it is FALSE, indicating that an I/O error occurred. To get extended error information, use the GetLastError function.

Comments

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, to enable 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


BackupSeek function
BackupSeek (Win32)

BOOL BackupSeek(hFile, dwLowBytesToSeek, dwHighBytesToSeek, lpdwLowByteSeeked, lpdwHighByteSeeked, lpContext)

HANDLE hFile;	/* handle of open file	*/
DWORD dwLowBytesToSeek;	/* low-order 32 bits of number of bytes	*/
DWORD dwHighBytesToSeek;	/* high-order 32 bits of number of bytes	*/
LPDWORD lpdwLowBytesSeeked;	/* address of no. of bytes func. seeks	*/
LPDWORD lpdwHighBytesSeeked;	/* address of no. of bytes func. seeks	*/
LPVOID * lpContext;	/* internal context information	*/

The BackupSeek function seeks forward in a data stream initially accessed with the BackupRead or BackupWrite function.

Parameter	Description

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.

lpdwLowBytesSeeked	Points to a doubleword that, when the function returns, contains the low-order 32 bits of the number of bytes the function actually seeks.

lpdwHighBytesSeeked	Points to a doubleword that, when the function returns, contains the high-order 32 bits of the number of bytes the function actually seeks.

lpContext	Address of a pointer to an internal data structure used by the function. This must be the same data structure that was initialized by the BackupRead function. An application must not touch the contents of this structure.

Returns

If the function could seek the requested amount, the function returns TRUE. Otherwise, it is FALSE.

Comments

Applications use this 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 lpdwLowBytesSeeked and lpdwHighBytesSeeked 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


BackupWrite function
BackupWrite (Win32)

BOOL BackupWrite(hFileHandle, lpBuffer, dwNumberOfBytesToWrite, lpdwNumberOfBytesWritten, bAbort, bProcessSecurity, lpContext)

HANDLE hFileHandle;	/* handle of open file	*/
LPBYTE lpBuffer;	/* address of buffer to write	*/
DWORD dwNumberOfBytesToWrite;	/* number of bytes to write	*/
LPDWORD lpdwNumberOfBytesWritten;	/* address of no. of bytes written	*/
BOOL bAbort;	/* termination type	*/
BOOL bProcessSecurity;	/* process security	*/
LPVOID *lpContext;	/* internal context information	*/

The BackupWrite function transfers data from a buffer to the specified file or directory. The data must be divided into substreams separated by WIN32_STREAM_ID structures.

Parameter	Description

hFileHandle	Identifies the handle of the file or directory being restored. This handle is created by using the CreateFile function.

lpBuffer	Points to the buffer that contains the data stream.

dwNumberOfBytesToWrite	Specifies the length of the buffer. The buffer size must be greater than the size of a WIN32_STREAM_ID structure.

lpNumberOfBytesWritten	Points to a doubleword that, when the function returns, contains the number of bytes written.

bAbort	Indicates whether BackupWrite terminated abnormally. If this value is TRUE, the operation terminated abnormally and all buffers were deallocated.

bProcessSecurity	Indicates whether the access-control list (ACL) data for the opened object will be restored. If this value is TRUE, the ACL data will be restored.

lpContext	Points to an internal data structure used only by this function. Storage for this structure is allocated by the BackupRead function. This parameter must point to a NULL value before the first call to the file or directory to be written. When the function returns, this parameter contains reserved information. This parameter must not be changed between calls to BackupWrite. To deallocate the storage for this information, your application should call BackupWrite with the bAbort parameter set to TRUE before exiting.

Returns

If the function succeeds, the return value is TRUE; otherwise it is FALSE, indicating that an I/O error occurred. To get extended error information, use the GetLastError function.

Comments

The BACKUP_LINK stream type enables you to restore files with hard links. The data returned by BackupRead is to be used only as input to BackupWrite.

See Also

BackupRead, BackupSeek


Beep function
Beep (Win32)

BOOL Beep(dwFreq, dwDuration)

DWORD dwFreq;	/* sound frequency, in hertz	*/
DWORD dwDuration;	/* sound duration, in milliseconds	*/

The Beep function generates simple tones on the speaker.

Parameter	Description

dwFreq	Specifies the frequency, in hertz, of the sound. This parameter must be in the range 37 through 32,767 (0x25 through 0x7FFF).

dwDuration	Specifies the duration, in milliseconds, of the sound.

One value has a special meaning: If dwDuration is -1, the function operates asynchronously, and produces sound until the function is called again.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The Beep function is synchronous in all but one case; the function does not generally return control to its caller until the sound finishes. The exception to this occurs when dwDuration has the value -1. In that case, the Beep function is asynchronous, returning control immediately to its caller while the sound continues playing. The sound continues until the next call to Beep.


BeginUpdateResource function
BeginUpdateResource (Win32)

HANDLE BeginUpdateResource(lpszExeFile, bDeleteExistingResources)

LPCTSTR lpszExeFile;	/* addr. of file in which to update resources	*/
BOOL bDeleteExistingResources;	/* deletion option	*/

The BeginUpdateResource function returns a handle that can be used by the UpdateResource function to add, delete, or replace resources in an executable file.

Parameter	Description

lpszExeFile	Points 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 lpszExeFile does not specify a full path, Windows searches for the file in the current directory.

bDeleteExistingResources	Specifies whether to delete the lpszExeFile 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.

Returns

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, use the GetLastError function.

See Also

EndUpdateResource, UpdateResource


BuildCommDCB function
BuildCommDCB (Win32)

BOOL BuildCommDCB(lpszDef, lpdcb)

LPCTSTR lpszDef;	/* address of device-control string	*/
LPDCB lpdcb;	/* address of device-control block	*/

The BuildCommDCB function fills a specified DCB structure with the values in a specified string.

Parameter	Description

lpszDef	Points to a null-terminated string that specifies device-control information. The string must have the same form as the Windows NT MODE command-line arguments. For example, the following line 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, except that it must specify a valid device, as follows:

COM1: baud=1200 parity=N data=8 stop=1

lpdcb	Points to the DCB structure to be filled in.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The BuildCommDCB function adjusts only those members of the DCB structure specifically affected by the lpszDef 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 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 DCB structure. To apply these settings to a serial port, use the SetCommState function.

See Also

SetCommState, DCB


BuildCommDCBAndTimeouts function
BuildCommDCBAndTimeouts (Win32)

BOOL BuildCommDCBAndTimeouts(lpDef, lpDCB, lpCommTimeouts)

LPCTSTR lpDef;	/* address of a device control string	*/
LPDCB lpDCB;	/* address of a device control block	*/
LPCOMMTIMEOUTS lpCommTimeouts;	/* address of a comm timeout structure	*/

The BuildCommDCBAndTimeouts function translates a device definition string into appropriate device-control block codes, then places these codes into a device control block. The function can also set up timeout values, including the possibility of no timeouts, for a device; the function's behavior in this regard varies based upon the contents of the device definition string.

Parameter	Description

lpDef	Points to a null terminated character string that specifies device control information for the device. The function takes this string, parses it, then sets appropriate values in the DCB data structure pointed to by lpDCB.

lpDCB	Points to a DCB data structure that the function fills with information it gleans from the device control information string pointed to by lpDef. This DCB structure defines the control settings for a communications device.

lpCommTimeouts	Points to a COMMTIMEOUTS structure that the function can use to set device timeout values.

The BuildCommDcbAndTimeouts function modifies its timeout setting behavior based on the presence, setting, 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 timeout values for the device based on the timeout structure pointed to by lpCommTimeouts.

If that string contains the substring "TO=OFF", the function sets up the device with no timeouts.

If that string contains neither of the aforementioned "TO=xxx" substrings, the function ignores the timeout structure pointed to by lpCommTimeouts. The timeout structure will not be accessed in any way.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetCommTimeouts, SetCommTimeouts, BuildCommDCB, COMMTIMEOUTS, DCB


CallNamedPipe function
CallNamedPipe (Win32)

BOOL CallNamedPipe(lpszPipeName, lpvWriteBuf, cbWriteBuf, lpvReadBuf, cbReadBuf, lpcbRead, dwTimeout)

LPCTSTR lpszPipeName;	/* address of pipe name	*/
LPVOID lpvWriteBuf;	/* address of write buffer	*/
DWORD cbWriteBuf;	/* size in bytes of write buffer	*/
LPVOID lpvReadBuf;	/* address of read buffer	*/
DWORD cbReadBuf;	/* size in bytes of read buffer	*/
LPDWORD lpcbRead;	/* number of bytes read	*/
DWORD dwTimeout;	/* time-out time in milliseconds	*/

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.

Parameter	Description

lpszPipeName	Points to a null-terminated string specifying the pipe name.

lpvWriteBuf	Points to the buffer containing the data written to the pipe.

cbWriteBuf	Specifies the size, in bytes, of the write buffer.

lpvReadBuf	Points to the buffer that receives the data read from the pipe.

cbReadBuf	Specifies the size, in bytes, of the read buffer.

lpcbRead	Points to a 32-bit variable that receives the number of bytes read from the pipe.

dwTimeout	Specifies the number of milliseconds to wait for the named pipe to be available. In addition to numeric values, the following special values are available:

Value	Meaning

NMPWAIT_NOWAIT	Do not wait for the named pipe. If the named pipe is not available, the function returns an error.

NMPWAIT_WAIT_FOREVER	Wait indefinitely.

NMPWAIT_USE_DEFAULT_WAIT	Use default timeout specified in call to CreateNamedPipe.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Calling the CallNamedPipe function is equivalent to calling CreateFile (or WaitNamedPipe, if CreateFile cannot open the pipe immediately), TransactNamedPipe, and CloseHandle. 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 cbReadBuf, CallNamedPipe returns FALSE, and the GetLastError function 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


ClearCommBreak function
ClearCommBreak (Win32)

BOOL ClearCommBreak(hCommDev)

HANDLE hCommDev;	/* handle of the communications device	*/

The ClearCommBreak function restores character transmission for a given communications device and places the transmission line in a nonbreak state.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

A communications device is placed in a break state by the SetCommBreak or EscapeCommFunction function. This suspends character transmission until the break state is cleared by calling ClearCommBreak.

See Also

ClearCommError, EscapeCommFunction, SetCommBreak


ClearCommError function
ClearCommError (Win32)

BOOL ClearCommError(hCommDev, lpdwErrors, lpcst)

HANDLE hCommDev;	/* handle of the communications device	*/
LPDWORD lpdwErrors;	/* address of variable to receive error codes	*/
LPCOMSTAT lpcst;	/* address of buffer for communication status	*/

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.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

lpdwErrors	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 values is specified:

Value	Meaning

CE_BREAK	The hardware detected a break condition.

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 hCommDev parameter is invalid. If this bit set, this is the only valid error.

CE_OOP	The parallel device signaled that it is out of paper.

CE_OVERRUN	A character-buffer overrun has occurred. The next character is lost.

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 was received.

CE_RXPARITY	The hardware detected a parity error.

CE_TXFULL	The application tried to transmit a character, but the output buffer was full.

CE_DNS	The parallel device is not selected.

CE_PTO	A timeout occurred on a parallel device.

lpcst	Points to a COMSTAT structure in which the device's status information is returned. If lpcst is NULL, no status information is returned.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 are accepted until the application has acknowledged the communications error by calling the ClearCommError function.

The ClearCommError function fills the status buffer pointed to by the lpcst parameter with the current status of the communications device specified by thehCommDev parameter.

See Also

ClearCommBreak, DCB


ClearEventLog function
ClearEventLog (Win32)

BOOL ClearEventLog(hEventLog, lpszBackupFile)

HANDLE hEventLog;	/* handle to event log	*/
LPCTSTR lpszBackupFile;	/* name of backup file	*/

The ClearEventLog function clears the given event log, and optionally saves the current copy of the logfile to a backup file.

Parameter	Description

hEventLog	Identifies the event log to be cleared. This handle is returned by the OpenEventLog function.

lpszBackupFile	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 lpszBackupFile is NULL, the current event logfile is not backed up.

Returns

If the function succeeds, the return value is TRUE. The given event log has been backed up (if lpszBackupFile is not NULL) and then cleared. Otherwise, the return value is FALSE. To get extended error information, use the GetLastError function.

Comments

This 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).

ClearEventLog 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 lpszBackupFile, ClearEventLog fails.

See Also

OpenEventLog


CloseEventLog function
CloseEventLog (Win32)

BOOL CloseEventLog(hEventLog)

HANDLE hEventLog;	/* handle to event log	*/

The CloseEventLog function closes the given event log.

Parameter	Description

hEventLog	Identifies the event log to be closed. This handle is returned by the OpenEventLog function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

OpenEventLog


CloseHandle function
CloseHandle (Win32)

BOOL CloseHandle(hObject)

HANDLE hObject;	/* handle of object to close	*/

The CloseHandle function closes an open object handle.

Parameter	Description

hObject	Identifies an open object handle.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The CloseHandle function closes handles to the following objects:

Console input or output

Event file

File mapping

Mutex

Named pipe

Process

Semaphore

Thread

CloseHandle invalidates the specified object handle, decrements the object's handle count, and performs object retention checks. Once the last handle of 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 CreateFile.

See Also

CreateFile, DeleteFile


CompareFileTime function
CompareFileTime (Win32)

LONG CompareFileTime(lpft1, lpft2)

CONST FILETIME * lpft1;	/* address of first file time	*/
CONST FILETIME * lpft2;	/* address of second file time	*/

The CompareFileTime function compares two 64-bit file times.

Parameter	Description

lpft1	Points to a FILETIME structure that specifies the first 64-bit file time.

lpft2	Points to a FILETIME structure that specifies the second 64-bit file time.

Returns

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


ConnectNamedPipe function
ConnectNamedPipe (Win32)

BOOL ConnectNamedPipe(hNamedPipe, lpo)

HANDLE hNamedPipe;	/* handle of named pipe to connect	*/
LPOVERLAPPED lpo;	/* address of overlapped structure	*/

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 CreateFile or CallNamedPipe.

Parameter	Description

hNamedPipe	Identifies the server end of a named pipe instance. This handle is returned by the CreateNamedPipe function.

lpo	Points to an OVERLAPPED structure. This parameter can be NULL if overlapped operation is not desired. For a description of how the wait mode and the overlapped mode of the hNamedPipe handle affect the behavior of this function, see the Comments section.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

A named pipe server process can use the ConnectNamedPipe function with a newly created pipe instance. It can also be used with an instance that was previously connected to another client process, in which 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 in the SetNamedPipeHandleState function. The function is executed as an overlapped operation if FILE_FLAG_OVERLAPPED was specified when the pipe handle was created, and if the lpOverlapped parameter is not NULL. Otherwise, the function is executed synchronously. If an overlapped operation is used, 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 lpo is NULL, the operation executes synchronously. The function does not return until a client is connected or an error occurs. The function returns TRUE if a client connected after the function was called. If a client connected before the function was 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 which case, there is a good connection between client and server, even though the function returned FALSE.

If lpo is not NULL, the operation executes asynchronously. The function returns immediately with a return value of FALSE. If a client process connected before the function was 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 not-signaled 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--WaitForSingleObject, WaitForMultipleObjects, WaitForSingleObjectEx, WaitForMultipleObjectsEx, 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, ConnectNamedPipe on a nonblocking mode pipe handle returns FALSE. In these cases, 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® Windows NT(TM) Advanced Server version 2.0, and should not be used to achieve asynchronous I/O with named pipes.

See Also

CreateFile, CallNamedPipe, CreateEvent, CreateNamedPipe, DisconnectNamedPipe, GetOverlappedResult, SetNamedPipeHandleState, SleepEx, WaitForSingleObject, WaitForSingleObjectEx, WaitForMultipleObjects, WaitForMultipleObjectsEx


ContinueDebugEvent function
ContinueDebugEvent (Win32)

BOOL ContinueDebugEvent(idProcess, idThread, fdwContinueStatus)

DWORD idProcess;	/* process to continue	*/
DWORD idThread;	/* thread to continue	*/
DWORD fdwContinueStatus;	/* continuation status	*/

The ContinueDebugEvent function enables a debugger to continue a thread that previously reported a debugging event.

Parameter	Description

idProcess	Identifies the process to continue.

idThread	Identifies the thread to continue. The combination of process identifier and thread identifier must identify a thread that has previously reported a debugging event.

fdwContinueStatus	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 idThread 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 idThread 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 invoked; otherwise, the process is terminated. For any other debugging event, this flag simply continues the thread.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Only the thread that created idProcess with the CreateProcess function can call ContinueDebugEvent.

After this function succeeds, the specified thread continues. Depending on the debugging event previously reported by the thread, certain side effects 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


CopyFile function
CopyFile (Win32)

BOOL CopyFile(lpszExistingFile, lpszNewFile, fFailIfExists)

LPCTSTR lpszExistingFile;	/* address of name of an existing file	*/
LPCTSTR lpszNewFile;	/* address of filename to copy to	*/
BOOL fFailIfExists;	/* flag for operation if file exists	*/

The CopyFile function copies an existing file to a new file.

Parameter	Description

lpszExistingFile	Points to a null-terminated string that specifies the name of an existing file.

lpszNewFile	Points to a null-terminated string that specifies the name of the new file.

fFailIfExists	Specifies how this operation is to proceed if a file of the same name as that specified by lpszNewFile 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Security attributes for the existing file are not copied to the new file.

FILE_ATTRIBUTE_* file attributes for the existing file are copied to the new file. For example, if an existing file has the FILE_ATTRIBUTE_READONLY file attribute set, a copy created via a call to CopyFile will also have the FILE_ATTRIBUTE_READONLY file attribute set. See CreateFile for further information on FILE_ATTRIBUTE_* file attributes

See Also

CreateFile, MoveFile


CopyMemory function
CopyMemory (Win32)

VOID CopyMemory (Destination, Source, Length)

PVOID Destination;	/* address of copy destination	*/
CONST VOID * Source;	/* address of block to copy	*/
DWORD Length;	/* size in bytes of block to copy	*/

The CopyMemory function copies a block of memory from one location to another.

Parameter	Description

Destination	Points to the starting address of the destination of the copy.

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.

Returns

This function has no return value.

Comments

If the source and destination blocks overlap, the results are undefined. For overlapped blocks, use the MoveMemory function.

See Also

FillMemory, MoveMemory, ZeroMemory


CreateConsoleScreenBuffer function
CreateConsoleScreenBuffer (Win32)

HANDLE CreateConsoleScreenBuffer(fdwAccess, fdwShareMode, lpsa, fdwType, pvReserved)

DWORD fdwAccess;	/* access flag	*/
DWORD fdwShareMode;	/* buffer share mode	*/
LPSECURITY_ATTRIBUTES lpsa;	/* address of security attributes	*/
DWORD fdwType;	/* type of buffer to create	*/
PVOID pvReserved;	/* reserved	*/

The CreateConsoleScreenBuffer function creates a console screen buffer and returns a handle of it.

Parameter	Description

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

fdwShareMode	Specifies how this console screen buffer can be shared. This parameter can be zero, indicating that the buffer cannot be shared, or 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.

lpsa	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the console screen buffer.

fdwType	Specifies the type of console screen buffer to create. The only currently supported screen buffer type is CONSOLE_TEXTMODE_BUFFER.

pvReserved	Reserved for possible future use; should be NULL.

Returns

If the function succeeds, the return value is a handle of the new console screen buffer; otherwise, it is INVALID_HANDLE_VALUE. To get extended error information, use the GetLastError function.

Comments

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

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 fdwAccess 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

GetConsoleScreenBufferInfo, SetConsoleActiveScreenBuffer, SetConsoleScreenBufferSize


CreateDirectory function
CreateDirectory (Win32)

BOOL CreateDirectory(lpszPath, lpsa)

LPCTSTR lpszPath;	/* address of path of directory to create	*/
LPSECURITY_ATTRIBUTES lpsa;	/* address of security descriptor	*/

The CreateDirectory function creates a new directory.

Parameter	Description

lpszPath	Points to a null-terminated string that specifies the path of the directory to be created.

lpsa	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the directory. The file system must support this parameter for it to have an effect.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CreateDirectoryEx, RemoveDirectory


CreateDirectoryEx function
CreateDirectoryEx (Win32)

BOOL CreateDirectoryEx(lpTemplateDirectory, lpNewDirectory, lpSecurityAttributes)

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

The CreateDirectoryEx function creates a new directory with a specified pathname 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.

Parameter	Description

lpTemplateDirectory	Points to a null-terminated string that specifies the pathname of the directory to be used as a template when creating the new directory.

lpPathName	Points to a null-terminated string that specifies the pathname of the directory to be created.

lpSecurityAttributes	Points to a SECURITY_ATTRIBUTES structure that supplies a security descriptor for the new directory. This parameter is optional. The target file system must support security on files and directories for this parameter to have an effect.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The CreateDirectoryEx function allows the creation of directories that inherit stream information from other directories. This is useful, for example, when dealing with Macintosh directories, which have as an attribute a resource stream that is needed to properly identify directory contents.

See Also

CreateDirectory, RemoveDirectory


CreateEvent function
CreateEvent (Win32)

HANDLE CreateEvent(lpsa, fManualReset, fInitialState, lpszEventName)

LPSECURITY_ATTRIBUTES lpsa;	/* address of security attributes	*/
BOOL fManualReset;	/* flag for manual-reset event	*/
BOOL fInitialState;	/* flag for initial state	*/
LPCTSTR lpszEventName;	/* address of event-object name	*/

The CreateEvent function creates a named or unnamed event object.

Parameter	Description

lpsa	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the event object.

If lpsa is NULL, the event object is created with a default security descriptor and the resulting handle is not inheritable.

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

fInitialState	Specifies the initial state of the event object. If TRUE, the initial state is signaled; otherwise, it is nonsignaled.

lpszEventName	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 lpszEventName matches the name of an existing named event object, this function requests EVENT_ALL_ACCESS access to the existing object. In this case, the fManualReset and fInitialState parameters are ignored because they have already been set by the creating process. If the lpsa parameter is not NULL, it determines whether the handle can be inherited, but its security-descriptor member is ignored.

If lpszEventName is NULL, the event object is created without a name.

If lpszEventName 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.

Returns

If the function succeeds, the return value is a handle of 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, use the GetLastError function.

Comments

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 of an event object.

Any thread of the calling process can specify the event-object handle in a call to one of the wait functions (MsgWaitForMultipleObjects, WaitForSingleObject, WaitForMultipleObjects, WaitForSingleObjectEx, or WaitForMultipleObjectsEx). 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 fInitialState 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 of an event object if the lpsa 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, OpenEvent, ResetEvent, SetEvent, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


CreateFile function
CreateFile (Win32)

HANDLE CreateFile(lpszName, fdwAccess, fdwShareMode, lpsa, fdwCreate, fdwAttrsAndFlags, hTemplateFile)

LPCTSTR lpszName;	/* address of name of the file	*/
DWORD fdwAccess;	/* access (read-write) mode	*/
DWORD fdwShareMode;	/* share mode	*/
LPSECURITY_ATTRIBUTES lpsa;	/* address of security descriptor	*/
DWORD fdwCreate;	/* how to create	*/
DWORD fdwAttrsAndFlags;	/* file attributes	*/
HANDLE hTemplateFile;	/* handle of file with attrs. to copy	*/

The CreateFile function creates, opens, or truncates a file, pipe, communications resource, disk device, or console. It returns a handle that can be used to access the object.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the file, pipe, communications resource, disk device, or console to create, open, or truncate.

fdwAccess	Specifies the type of access to the file. An application can obtain read access, write access, both read and write access, or device query access. Use the following flag constants to build a value for this parameter; note that both GENERIC_READ and GENERIC_WRITE must be set to obtain both read and write access:

Value	Meaning

0	Allows an application to query device attributes without actually accessing the device.

GENERIC_READ	Specifies read access to the file. Data can be read from the file and the file pointer can be moved.

GENERIC_WRITE	Specifies write access to the file. Data can be written to the file and the file pointer can be moved.

fdwShareMode	Specifies how this file can be shared. This parameter must be some combination of the following values:

Value	Meaning

0	Prevents the file from being shared.

FILE_SHARE_READ	Other open operations can be performed on the file for read access. Specify this flag if the CreateFile function is opening the client end of a mailslot.

FILE_SHARE_WRITE	Other open operations can be performed on the file for write access.

lpsa	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the file. The file system must support this parameter for it to have an effect.

fdwCreate	Specifies the action to take when the file exists or does not exist. For more information about this parameter, see Comments. This parameter must be one of the following values:

Value	Meaning

CREATE_NEW	Creates a new file. Fails if the specified file already exists.

CREATE_ALWAYS	Creates a new file. Overwrites the file if it exists.

OPEN_EXISTING	Opens the file. Fails if the file does not exist.

Please see the Comments section below for a discussion of why you should use the OPEN_EXISTING flag if you are using the CreateFile function on a device, including the console.

OPEN_ALWAYS	Opens the file, if it exists. If the file does not exist, the function creates the file as if fdwCreate 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. Fails if the file does not exist.

fdwAttrsAndFlags	Specifies the file attributes and flags for the file. Any combination of the following flags and attributes is acceptable, except that all other file attributes override FILE_ATTRIBUTE_NORMAL.

Attribute	Meaning

FILE_ATTRIBUTE_ARCHIVE

The file is an archive file. Applications use this flag to mark files for backup or removal.

FILE_ATTRIBUTE_NORMAL

The file has no other attributes set. This attribute is valid only if used alone.

FILE_ATTRIBUTE_HIDDEN

The file is hidden. It is not to be included in an ordinary directory listing.

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.

FILE_ATTRIBUTE_ATOMIC_WRITE

Reserved for future use. Do not specify.

FILE_ATTRIBUTE_XACTION_WRITE

Reserved for future use. Do not specify.

Flag	Meaning

FILE_FLAG_WRITE_THROUGH

Instructs the operating system to write through any intermediate cache and go directly to the file. The operating system can still cache writes, but cannot lazily flush the writes.

FILE_FLAG_OVERLAPPED

Instructs the operating system to initialize the file 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 FILE_FLAG_OVERLAPPED is specified, 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 OVERLAPPED structure argument 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, for example).

FILE_FLAG_NO_BUFFERING

Indicates that the file is to be opened with no intermediate buffering or caching done by the system. Reads and writes to the file must be done on sector boundaries. Buffer addresses for reads and writes must be aligned on disk sector boundaries in memory. An application can determine sector size with the GetDiskFreeSpace function.

FILE_FLAG_RANDOM_ACCESS

Indicates that the file is accessed randomly. Windows uses this flag to optimize file caching.

FILE_FLAG_SEQUENTIAL_SCAN

Indicates that the file is to be accessed sequentially from beginning to end. Windows uses this flag 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 potentially large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occassionally skip over small ranges of bytes.

FILE_FLAG_DELETE_ON_CLOSE

Indicates that the operating system is to delete the file immediately after all its handles have been closed.

FILE_FLAG_BACKUP_SEMANTICS

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.

FILE_FLAG_POSIX_SEMANTICS

Indicates to access the file 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 3.x, or Windows NT.

If the CreateFile function opens the client side of a named pipe, the fdwAttrsAndFlags parameter can also contain Security Quality of Service information. When the calling application specifies the SECURITY_SQOS_PRESENT flag, the fdwAttrsAndFlags 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.

Value	Meaning

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 this flag is not specified, all aspects of the client's security context are available.

This flag allows the client to limit the groups and privileges a server can use while impersonating the client.

For more information about security, see Security.

hTemplateFile	Specifies a handle with GENERIC_READ access to a template file. The template file supplies extended attributes for the file being created.

Returns

If the function succeeds, the return value is an open handle of the specified file. If the specified file exists before the function call, and fdwCreate 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 0.

If the function fails, the return value is INVALID_HANDLE_VALUE. Call GetLastError for extended error information.

Comments

When creating a new file, the CreateFile function performs the following actions:

Combines the file attributes and flags specified by fdwAttrsAndFlags with FILE_ATTRIBUTE_ARCHIVE.

Sets the file length to zero.

If the hTemplateFile parameter is specified, CreateFile copies the extended attributes supplied by the template file to the new file.

When opening an existing file, CreateFile performs the following actions:

Combines the file flags specified by fdwAttrsAndFlags with existing file attributes. CreateFile ignores the file attributes specified by fdwAttrsAndFlags.

Sets the file length according to the value of fdwCreate.

Ignores the hTemplateFile parameter.

If the lpsa parameter isn't NULL, CreateFile ignores the lpSecurityDescriptor member of the SECURITY_ATTRIBUTES structure. The other structure members are valid. The bInheritHandle member is the only way to indicate whether the file handle can be inherited.

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 CreateNamedPipe dwOpenMode parameter.

For more information about pipes, see Pipes.

If CreateFile opens the client end of a mailslot, the function always returns a valid handle, even if the mailslot does not exist. In other words, there is no relationship between opening the client end and opening the server end of the mailslot.

For more information about mailslots, see Mailslots.

CreateFile can create a handle to a communications resource, such as the serial port COM1. For communications resources, the fdwShareMode parameter must be 0 (exclusive access), the fdwCreate 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 input and output (I/O).

For more information about communications, see Communications.

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

Parameter	Value

lpszName	Use the values CONIN$ to specify console input, CONOUT$ to specify console output.

CONIN$ gets a handle of the console's input buffer, even if the SetStdHandle function redirected the standard input handle. Use the GetStdHandle function to get the standard input handle.

CONOUT$ gets a handle of the active screen buffer, even if SetStdHandle redirected the standard output handle. Use GetStdHandle to get the standard output handle.

fdwAccess	"GENERIC_READ | GENERIC_WRITE" is preferred, but either one can limit access.

fdwShareMode	If the calling process inherited the console, or a child process should be able to access the console, this parameter must be "FILE_SHARE_READ | FILE_SHARE_WRITE".

lpsa	If the calling process wants the console to be inherited, the bInheritHandle member of the SECURITY_ATTRIBUTES structure must be TRUE.

fdwCreate	The user should specify OPEN_EXISTING when using CreateFile to open the console.

fdwAttrsAndFlags	Ignored.

hTemplateFile	Ignored.

A call to CreateFile with lpszName set to "CON" and fwdAccess set to GENERIC_READ opens a console for input. A call to CreateFile with lpszName set to "CON" and fwdAccess set to GENERIC_WRITE opens a console for output. A call to CreateFile with lpszName set to "CON" and fwdAccess set to GENERIC_READ | GENERIC_WRITE will cause CreateFile to fail, returning an ERROR_PATH_NOT_FOUND error.

The CreateFile function may be used to open a disk drive or a partition on a disk drive. The function returns a handle to the disk device; that handle may 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 lpszName string should be of the form \\.\PhysicalDriveN to open the Nth hard disk. Hard disk numbers start at 0. For example:

String	Meaning

\\.\PHYSICALDRIVE2	Obtains a handle to the user's computer's third physical drive

The lpszName 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 the user's computer's A: drive.

\\.\C:	Obtains a handle to the user's computer's C: drive.

The  fdwCreate parameter must have the value OPEN_EXISTING.

When opening a floppy disk or a partition on a hard disk, the fdwShareMode flag must at least specify FILE_SHARE_WRITE.

Use the CloseHandle function to close a handle returned by CreateFile.

As noted above, specifying 0 for fdwAccess allows an application to query device attributes without actually accessing the device. This 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.

See Also

AllocConsole, CloseHandle, ConnectNamedPipe, CreateNamedPipe, GetDiskFreeSpace, GetOverlappedResult, GetStdHandle, OpenFile, SetStdHandle


CreateFileMapping function
CreateFileMapping (Win32)

HANDLE CreateFileMapping(hFile, lpsa, fdwProtect, dwMaximumSizeHigh, dwMaximumSizeLow, lpszMapName)

HANDLE hFile;	/* handle of file to map	*/
LPSECURITY_ATTRIBUTES lpsa;	/* optional security attributes	*/
DWORD fdwProtect;	/* protection for mapping object	*/
DWORD dwMaximumSizeHigh;	/* high-order 32 bits of object size	*/
DWORD dwMaximumSizeLow;	/* low-order 32 bits of object size	*/
LPCTSTR lpszMapName;	/* name of file-mapping object	*/

The CreateFileMapping function creates a named or unnamed file-mapping object for the specified file.

Parameter	Description

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

lpsa	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the mapping object.

If lpsa is NULL, the file-mapping object is created with a default security descriptor and the resulting handle is not inherited.

fdwProtect	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-and-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 binary-ORing the following SEC_* values with the preceding PAGE_* values:

Value	Description

SEC_COMMIT	All pages of a section are to be set to the commit state.

SEC_IMAGE	The file specified for a section's file mapping is an executable image file.

SEC_NOCACHE	All pages of a section are to be set as non-cacheable.

SEC_RESERVE	All pages of a section are to be set to the reserved state.

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 the dwMaximumSizeLow and dwMaximumSizeHigh parameters are zero, the maximum size of the file-mapping object is equal to the current size of the file identified by hFile.

lpszMapName	Points to a null-terminated string specifying the name of the mapping object. The name can contain any character except the backslash path-separator character (\).

If lpszMapName matches the name of an existing named mapping object, this function requests access to the mapping object with the protection specified by the fdwProtect parameter.

If lpszMapName is NULL, the mapping object is created without a name.

Returns

If the function succeeds, the return value is a handle of 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, use the GetLastError function.

Comments

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 the DuplicateHandle function reference page. For information on opening a file-mapping object by name, see the OpenFileMapping function reference page.

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 machines both map a file as writable, and both change the same page, each machine 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.

In order to fully close a file mapping object, an application must first unmap all mapped views of the file mapping object by calling UnmapViewOfFile, and then close the file mapping object handle by calling CloseHandle. 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

DuplicateHandle, MapViewOfFile, MapViewOfFileEx, OpenFileMapping


CreateMailslot function
CreateMailslot (Win32)

HANDLE CreateMailslot(lpszName, cbMaxMsg, dwReadTimeout, lpsa)

LPCTSTR lpszName;	/* address of string for mailslot name	*/
DWORD cbMaxMsg;	/* maximum message size	*/
DWORD dwReadTimeout;	/* milliseconds before read time-out	*/
LPSECURITY_ATTRIBUTES lpsa;	/* address of security structure	*/

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.

Parameter	Description

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

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

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

lpsa	Points to a SECURITY_ATTRIBUTES structure specifying the security attributes for the mailslot.

If lpsa is NULL, the mailslot is created with a default security descriptor, and the resulting handle is not inherited.

Returns

For a full description of this structure, see <Microsoft Win32 Programmer's Reference, Volume 5>.

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, use the GetLastError function.

Comments

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.

Microsoft® Windows NT™ Advanced Server uses 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 given name in the specified domain.

\\*\mailslot\name	Retrieves a client handle to all mailslots with the given 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. When an application attempts to write more than 400 bytes, the WriteFile function fails and the GetLastError functions 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, SetMailslotInfo, SECURITY_ATTRIBUTES


CreateMutex function
CreateMutex (Win32)

HANDLE CreateMutex(lpsa, fInitialOwner, lpszMutexName)

LPSECURITY_ATTRIBUTES lpsa;	/* address of security attributes	*/
BOOL fInitialOwner;	/* flag for initial ownership	*/
LPCTSTR lpszMutexName;	/* address of mutex-object name	*/

The CreateMutex function creates a named or unnamed mutex object.

Parameter	Description

lpsa	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the mutex object.

If lpsa is NULL, the mutex object is created with a default security descriptor and the resulting handle is not inheritable.

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

lpszMutexName	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 lpszMutexName matches the name of an existing named mutex object, this function requests MUTEX_ALL_ACCESS access to the existing object. In this case, the fInitialOwner parameter is ignored because it has already been set by the creating process. If the lpsa parameter is not NULL, it determines whether the handle can be inherited, but its security-descriptor member is ignored.

If lpszMutexName is NULL, the mutex object is created without a name.

If lpszMutexName 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.

Returns

If the function succeeds, the return value is a handle of 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, use the GetLastError function.

Comments

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 of a mutex object.

Any thread of the calling process can specify the mutex-object handle in a call to one of the wait functions (MsgWaitForMultipleObjects, WaitForSingleObject, WaitForMultipleObjects, WaitForSingleObjectEx, or WaitForMultipleObjectsEx). 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 fInitialOwner 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 of 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 fInitialOwner 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 of a mutex object if the lpsa 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, MsgWaitForMultipleObjects, OpenMutex, ReleaseMutex, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


CreateNamedPipe function
CreateNamedPipe (Win32)

HANDLE CreateNamedPipe(lpName, dwOpenMode, dwPipeMode, nMaxInstances, nOutBufferSize, nInBufferSize, nDefaultTimeOut, lpSecurityAttributes)

LPCTSTR lpName;	/* address of pipe name	*/
DWORD dwOpenMode;	/* pipe open mode	*/
DWORD dwPipeMode;	/* pipe-specific modes	*/
DWORD nMaxInstances;	/* maximum number of instances	*/
DWORD nOutBufferSize;	/* out buffer size in bytes	*/
DWORD nInBufferSize;	/* in buffer size in bytes	*/
DWORD nDefaultTimeOut;	/* time-out time in milliseconds	*/
LPSECURITY_ATTRIBUTES lpSecurityAttributes;	/* security attributes	*/

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.

Parameter	Description

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.

The dwOpenMode parameter must specify one of the following pipe access mode flags. The same one must be specified for each instance of the pipe:

Value	Meaning

PIPE_ACCESS_DUPLEX

The pipe is bidirectional; both server and client processes can read from and write to the pipe. This 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 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 gives the server the equivalent of GENERIC_WRITE access to the pipe. The client must specify GENERIC_READ access when connecting to the pipe.

The dwOpenMode parameter can also include either or both of the following flags, to enable write-through mode or overlapped mode. These flags can be different for different instances of the same pipe.

Value	Meaning

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 enabled, the functions that write 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 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 enabled, the functions that perform read, write, and connect operations that may take a significant time to be completed can return immediately. This 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 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, the functions that perform 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.

The dwOpenMode parameter can include any combination of the following security access mode flags. These flags can be different for different instances of the same pipe. They can be specified without concern for what other dwOpenMode flags have been specified.

Value	Meaning

WRITE_DAC

The caller will have write access to the named pipe's discretionary 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 mode, and wait mode of the pipe handle.

One of the following type flags can be specified. The same one must be specified for each instance of the pipe. If you specify zero, the parameter defaults to byte-type mode.

Value	Meaning

PIPE_TYPE_BYTE

Data is written to the pipe as a stream of bytes. This flag cannot be used with the PIPE_READMODE_MESSAGE flag.

PIPE_TYPE_MESSAGE

Data is written to the pipe as a stream of messages. This flag 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.

Value	Meaning

PIPE_READMODE_BYTE

Data is read from the pipe as a stream of bytes. This flag 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 flag 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.

Value	Meaning

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. This 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. See the Comments section below for a discussion on sizing named pipe buffers.

nInBufferSize	Specifies the number of bytes to reserve for the input buffer. See the Comments section below for a discussion on sizing named pipe buffers.

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	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the pipe. Since named pipes are implemented as a file system, and that file system supports the lpSecurityAttributes parameter, lpSecurityAttributes will always have an effect when specified.

If lpSecurityAttributes is NULL, the pipe is created with a default security descriptor, and the resulting handle is not inherited.

Note that access to some security attributes can be granted by setting particular flags in the     dwOpenMode parameter.

Returns

If the function succeeds, the return value is a handle to the server end of a named pipe instance . Otherwise, it is INVALID_HANDLE_VALUE. To get extended error information, use the GetLastError function. The return value is ERROR_INVALID_PARAMETER if nMaxInstances is greater than PIPE_UNLIMITED_INSTANCES.

Comments

To create an instance of a named pipe by using the CreateNamedPipe function the user must have FILE_CREATE_PIPE_INSTANCE access to the named pipe object. If a new named pipe is being created, then 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- or message-type), pipe access (duplex, inbound, or outbound), instance count, and time-out value. If different values are used, this function fails and the GetLastError function 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, ReadFile, ReadFileEx, TransactNamedPipe, WaitNamedPipe, WriteFile, WriteFileEx


CreatePipe function
CreatePipe (Win32)

BOOL CreatePipe(phRead, phWrite, lpsa, cbPipe)

PHANDLE phRead;	/* address of variable for read handle	*/
PHANDLE phWrite;	/* address of variable for write handle	*/
LPSECURITY_ATTRIBUTES lpsa;	/* address of security attributes	*/
DWORD cbPipe;	/* number of bytes reserved for pipe	*/

The CreatePipe function creates an anonymous pipe and returns handles to the read and write ends of the pipe.

Parameter	Description

phRead	Points to the variable that receives the read handle for the pipe.

phWrite	Points to the variable that receives the write handle for the pipe.

lpsa	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the pipe. The file system must support this parameter for it to have an effect.

If lpsa is NULL, the pipe is created with a default security descriptor, and the resulting handle is not inherited. For a full description of this structure, see <Microsoft Win32 Programmer's Reference, Volume 5>.

cbPipe	Specifies the buffer size for the pipe. This is only a suggestion; the system uses this value to calculate an appropriate buffering mechanism. If this parameter is zero, the system uses the default buffer size.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The CreatePipe function 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 ReadFile and WriteFile.

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, WriteFile


CreateProcess function
CreateProcess (Win32)

BOOL CreateProcess(lpszImageName, lpszCommandLine, lpsaProcess, lpsaThread, fInheritHandles, fdwCreate, lpvEnvironment, lpszCurDir, lpsiStartInfo, lppiProcInfo)

LPCTSTR lpszImageName;	/* address of module name	*/
LPCTSTR lpszCommandLine;	/* address of command line	*/
LPSECURITY_ATTRIBUTES lpsaProcess;	/* address of process security attrs	*/
LPSECURITY_ATTRIBUTES lpsaThread;	/* address of thread security attrs	*/
BOOL fInheritHandles;	/* new process inherits handles?	*/
DWORD fdwCreate;	/* creation flags	*/
LPVOID lpvEnvironment;	/* address of new environment block	*/
LPCTSTR lpszCurDir;	/* address of current directory name	*/
LPSTARTUPINFO lpsiStartInfo;	/* address of STARTUPINFO	*/
LPPROCESS_INFORMATION lppiProcInfo;	/* address of PROCESS_INFORMATION	*/

The CreateProcess function creates a new process and its primary thread. The new process executes the specified executable file.

Parameter	Description

lpszImageName	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 lpszCommandLine string. The specified module can be a Win32 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.

lpszCommandLine	Points to a null-terminated string specifying the command line for the application to be executed. If this parameter is NULL, the lpszImageName string is used as the command line. If both lpszImageName and lpszCommandLine are non-NULL, lpszImageName specifies the module to execute and lpszCommandLine 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 lpszImageName 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 "." 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 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.

If the process to be created is a DOS or Windows application, lpszCommandLine should be a full command line in which the first element is the application name. Since this also works well for Win32 applications, it is the most robust way to set lpszCommandLine.

lpsaProcess	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the created process.

If lpsaProcess is NULL, the process is created with a default security descriptor, and the resulting handle is not inherited.

lpsaThread	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the primary thread of the new process. If lpsaThread is NULL, the process is created with a default security descriptor, and the resulting handle is not inherited.

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

fdwCreate	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

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.

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.

DEBUG_ONLY_THIS_PROCESS

If set, the calling process is treated as a debugger, and the new process is a process being debugged. If the new process creates additional processes, the system does not notify the debugger of any debug events that occur in the additional processes.

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.

DETACHED_PROCESS

For console processes, the new process does not have access to the console of the parent process. The new process can call AllocConsole if it later wants to create a new console. This flag cannot be used with the CREATE_NEW_CONSOLE flag.

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 group ID of the new process group is the same as the process ID, which is returned in the lppiProcInfo structure. Process groups are used by the GenerateConsoleCtrlEvent function to enable sending a CTRL+C or CTRL+BREAK signal to a group of console processes.

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

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.

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.

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.

lpvEnvironment	Points to an environment block for the new process. If this parameter is NULL, the new process uses the environment of the calling process. The environment block consists of a null-terminated block of null-terminated strings (that is, two null bytes at the end of the block). 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 system's drives' current directory information is not automatically propagated to the new process. See the Comments section below for a discussion of this situation and how to handle it.

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

lpsiStartInfo	Points to a STARTUPINFO structure that specifies how the main window for the new process should appear.

lppiProcInfo	Points to a PROCESS_INFORMATION structure that receives identification information about the new process.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 the CreateProcess function.

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

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 be able to use the handle to gain access to the thread.

The process is assigned a 32-bit process identifier. The ID 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 ID 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 lpszImageName or lpszCommandLine strings, it doesn't matter whether the application name includes the filename extension, with one exception: a DOS or Windows application whose filename extension is .COM must include that.

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 command, because this function notifies all 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 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:

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

2	Only one thread in a process can be in a DLL initialization or detach routine at a time.

3	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 above in the description of lpvEnvironment, such current directory information for a system's drives does not automatically propagate to a new process when  the CreateProcess function's lpvEnvironment 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 (since Windows NT uses a sorted environment), and then put  them into  the environment block specified by lpvEnvironment. Typically they will go at the front  of the environment block, due to the aforementioned Windows NT environment block sorting.

One way to obtain a drive X:'s current directory variable 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 a new process' X: drive.

The handle returned by the CreateProcess function has PROCESS_ALL_ACCESS access to the process object.

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, GetCommandLine, GetEnvironmentStrings, GetExitCodeProcess, GetStartupInfo, GetSystemDirectory, GetWindowsDirectory, OpenProcess, ResumeThread, TerminateProcess


CreateRemoteThread function
CreateRemoteThread (Win32)

HANDLE CreateRemoteThread(hProcess, lpsa, cbStack, lpStartAddr, lpvThreadParm, fdwCreate, lpIDThread)

HANDLE hProcess;	/* handle to process to create thread in	*/
LPSECURITY_ATTRIBUTES lpsa;	/* address of thread security attrs	*/
DWORD cbStack;	/* initial thread stack size	*/
LPTHREAD_START_ROUTINE lpStartAddr;	/* address of thread function	*/
LPVOID lpvThreadParm;	/* address of argument for new thread	*/
DWORD fdwCreate;	/* creation flags	*/
LPDWORD lpIDThread;	/* address of returned thread identifier	*/

The CreateRemoteThread function creates a thread that runs in the address space of the another process.

Parameter	Description

hProcess	Identifies the process in which the thread is to be created. The handle must have PROCESS_CREATE_THREAD access.

lpsa	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the thread.

If lpsa is NULL, the thread is created with a default security descriptor, and the resulting handle is not inherited.

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

lpStartAddr	Points to the starting address of the new thread. The address is logically a procedure that never returns and that accepts as an argument a single 32-bit pointer argument.

lpvThreadParm	Points to a single 32-bit value passed to the thread.

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

lpIDThread	Points to a 32-bit variable that receives the thread identifier.

Returns

If the function succeeds, the return value is a handle to the new thread; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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 lpStartAddr parameter. If this function returns, the results are unspecified.

The CreateRemoteThread function may succeed even if lpStartAddr 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 bad 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 bad or missing 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.

ExitProcess, ExitThread, CreateThread, CreateRemoteThread, 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:

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

2	Only one thread in a process can be in a DLL initialization or detach routine at a time.

3	The ExitProcess function does not return until no threads are in their DLL initialization or detach routines.

See Also

CloseHandle, CreateProcess, CreateThread, ExitProcess, ExitThread, ResumeThread


CreateSemaphore function
CreateSemaphore (Win32)

HANDLE CreateSemaphore(lpsa, cSemInitial, cSemMax, lpszSemName)

LPSECURITY_ATTRIBUTES lpsa;	/* address of security attributes	*/
LONG cSemInitial;	/* initial count	*/
LONG cSemMax;	/* maximum count	*/
LPCTSTR lpszSemName;	/* address of semaphore-object name	*/

The CreateSemaphore function creates a named or unnamed semaphore object.

Parameter	Description

lpsa	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the semaphore object.

If lpsa is NULL, the semaphore object is created with a default security descriptor and the resulting handle is not inheritable.

cSemInitial	Specifies an initial count for the semaphore object. This value must be greater than or equal to zero and less than or equal to cSemMax. 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.

cSemMax	Specifies the maximum count for the semaphore object. This value must be greater than zero.

lpszSemName	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 lpszSemName matches the name of an existing named semaphore object, this function requests SEMAPHORE_ALL_ACCESS access to the existing object. In this case, the cSemInitial and cSemMax parameters are ignored because they have already been set by the creating process. If the lpsa parameter is not NULL, it determines whether the handle can be inherited, but its security-descriptor member is ignored.

If lpszSemName is NULL, the semaphore object is created without a name.

If lpszSemName 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.

Returns

If the function succeeds, the return value is a handle of 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, use the GetLastError function.

Comments

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 of a semaphore object.

Any thread of the calling process can specify the semaphore-object handle in a call to one of the wait functions (MsgWaitForMultipleObjects, WaitForSingleObject, WaitForMultipleObjects, WaitForSingleObjectEx, or WaitForMultipleObjectsEx). 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 cSemInitial 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 cSemMax 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 of a semaphore object if the lpsa 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, OpenSemaphore, ReleaseSemaphore, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


CreateTapePartition function
CreateTapePartition (Win32)

DWORD CreateTapePartition(hDevice, dwPartitionMethod, dwCount, dwSize)

HANDLE hDevice;	/* handle of open device	*/
DWORD dwPartitionMethod;	/* type of new partition	*/
DWORD dwCount;	/* number of new partitions to create	*/
DWORD dwSize;	/* size of new partition, in megabytes	*/

The CreateTapePartition function reformats a tape.

Parameter	Description

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. Refer to the hardware documentation to determine what type of partitions your device supports. 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. Refer to your tape device's documentation for more specific information.

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.

Returns

If the function succeeds, the return value is NO_ERROR; otherwise, it 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.

Comments

Creating partitions reformats the tape. All previous information recorded on the tape is destroyed.


CreateThread function
CreateThread (Win32)

HANDLE CreateThread(lpsa, cbStack, lpStartAddr, lpvThreadParm, fdwCreate, lpIDThread)

LPSECURITY_ATTRIBUTES lpsa;	/* address of thread security attrs	*/
DWORD cbStack;	/* initial thread stack size	*/
LPTHREAD_START_ROUTINE lpStartAddr;	/* address of thread function	*/
LPVOID lpvThreadParm;	/* argument for new thread	*/
DWORD fdwCreate;	/* creation flags	*/
LPDWORD lpIDThread;	/* address of returned thread ID	*/

The CreateThread function creates a thread to execute within the address space of the calling process.

Parameter	Description

lpsa	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the thread.

If lpsa is NULL, the thread is created with a default security descriptor, and the resulting handle is not inherited.

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

lpStartAddr	Points to the application-supplied function to be executed by the thread and represents the starting address of the thread. The function accepts a single 32-bit argument and returns a 32-bit exit code.

lpvThreadParm	Specifies a single 32-bit parameter value passed to the thread.

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

lpIDThread	Points to a 32-bit variable that receives the thread identifier.

Returns

If the function succeeds, the return value is a handle to the new thread. Otherwise, the return value is NULL. Use the GetLastError function to obtain extended error information.

Comments

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 lpStartAddr 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 lpStartAddr 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 bad 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 bad or missing 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.

ExitProcess, ExitThread, CreateThread, CreateRemoteThread, 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:

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

2	Only one thread in a process can be in a DLL initialization or detach routine at a time.

3	The ExitProcess function does not return until no threads are in their DLL initialization or detach routines.

See Also

CloseHandle, CreateProcess, CreateRemoteThread, ExitProcess, ExitThread, ResumeThread


DefineDosDevice function
DefineDosDevice (Win32)

BOOL DefineDosDevice(dwFlags, lpDeviceName, lpTargetPath)

DWORD dwFlags;	/* flags specifying aspects of device definition	*/
LPCTSTR lpDeviceName;	/* pointer to DOS device name string	*/
LPCTSTR lpTargetPath;	/* pointer to DOS or Windows NT path string	*/

The DefineDosDevice function lets an application define, redefine, or delete DOS device names.

DOS device names are stored as symbolic links in the Windows NT object name space. The code that converts a DOS path into a corresponding Windows NT path uses these symbolic links to map DOS devices and drive letters. The DefineDosDevice function provides a mechanism whereby a Win32 application can modify the symbolic links used to implement the DOS device namespace.

Parameter	Description

dwFlags	Specifies several controllable aspects of the DefineDosDevice function. You can use one or more of the following values to set flags:

Value	Meaning

DDD_RAW_TARGET_PATH	If specified, the function does not convert the lpTargetPath string from a DOS path to a Windows NT path, but takes it as is.

DDD_REMOVE_DEFINITION	If specified, the function removes the specified definition for the specified device. To determine which definition to remove, this 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, then 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,then the device name will be removed.

If this flag is NOT set, then the string pointed to by the lpTargetPath parameter will become the new mapping for this device.

DDD_EXACT_MATCH_ON_REMOVE	If set, along with DDD_REMOVE_DEFINITION, then this function will use an exact match to determine which mapping to remove. Use this flag to insure that you don't delete something that you did not define.

lpDeviceName	Pointer to a 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	Pointer to a path string that will implement this device. Points to a DOS path string unless the DDD_RAW_TARGET_PATH flag is specified, in which case this parameter points to a Windows NT path string.

Returns

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. Use the GetLastError function to obtain extended error information.

Comments

As stated above, in this function's introductory summary, the DefineDosDevice function provides a means whereby a Win32 application can create and modify the symbolic links used to implement the DOS device namespace. To query the current mapping for a particular DOS device name, or to obtain a list of all DOS devices known to the system, use the QueryDosDevice function.

DOS Device names are global. Once defined, a DOS device name remains visible to all processes until either it is explicity 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


DebugActiveProcess function
DebugActiveProcess (Win32)

BOOL DebugActiveProcess(idProcess)

DWORD idProcess;	/* process to be debugged	*/

The DebugActiveProcess function allows a debugger to attach to an active process and then debug it.

Parameter	Description

idProcess	Identifies the process to be debugged. The debugger gets debugging access to the process as if it had created the process with the DEBUG_ONLY_THIS_PROCESS flag set.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 MS-DOS, this is always true if the process identifier is valid. In the Win32 API for Windows NT, this function 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, this 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 idProcess 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, WaitForDebugEvent


DebugBreak function
DebugBreak (Win32)

VOID DebugBreak(VOID)

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 invoked. In most cases, this causes the calling process to terminate because of an unhandled breakpoint exception.

Returns

This function does not return a value.

See Also

DebugActiveProcess


DeleteAtom function
DeleteAtom (Win32)

ATOM DeleteAtom(atm)

ATOM atm;	/* atom to delete	*/

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.

Parameter	Description

atm	Identifies the atom and character string to be deleted.

Returns

If the function succeeds, the return value is zero; otherwise, it is the value of the atm parameter. To get extended error information, use the GetLastError function.

Comments

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

DeleteAtom 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


DeleteCriticalSection function
DeleteCriticalSection (Win32)

VOID DeleteCriticalSection(lpcsCriticalSection)

LPCRITICAL_SECTION lpcsCriticalSection;	/* address of critical section object	*/

The DeleteCriticalSection function releases all resources used by an unowned critical section object.

Parameter	Description

lpcsCriticalSection	Points to the critical section object.

Returns

This function does not return a value.

Comments

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 or LeaveCriticalSection function.

See Also

EnterCriticalSection, InitializeCriticalSection, LeaveCriticalSection


DeleteFile function
DeleteFile (Win32)

BOOL DeleteFile(lpszFileName)

LPCTSTR lpszFileName;	/* address of the name of the file to delete	*/

The DeleteFile function deletes an existing file.

Parameter	Description

lpszFileName	Points to a null-terminated string that specifies the file to be deleted.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If an application attempts to delete an open file or a file that does not exist, the DeleteFile function fails. Use the CloseHandle function to close an open file.

See Also

CloseHandle, CreateFile


DeregisterEventSource function
DeregisterEventSource (Win32)

BOOL DeregisterEventSource(hEventLog)

HANDLE hEventLog;	/* handle to event log	*/

The DeregisterEventSource function closes a handle returned by the RegisterEventSource function.

Parameter	Description

hEventLog	Identifies the event log whose handle was returned by RegisterEventSource.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

RegisterEventSource


DisconnectNamedPipe function
DisconnectNamedPipe (Win32)

BOOL DisconnectNamedPipe(hNamedPipe)

HANDLE hNamedPipe;	/* handle of named pipe	*/

The DisconnectNamedPipe function disconnects the server end of a named pipe instance from a client process.

Parameter	Description

hNamedPipe	Identifies an instance of a named pipe. This handle must be created by the CreateNamedPipe function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 the DisconnectNamedPipe function 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 calling the ConnectNamedPipe function.

See Also

CloseHandle, ConnectNamedPipe, CreateNamedPipe, FlushFileBuffers


DosDateTimeToFileTime function
DosDateTimeToFileTime (Win32)

BOOL DosDateTimeToFileTime(wDOSDate, wDOSTime, lpft)

WORD wDOSDate;	/* 16-bit MS-DOS date	*/
WORD wDOSTime;	/* 16-bit MS-DOS time	*/
LPFILETIME lpft;	/* address of buffer for 64-bit file time	*/

The DosDateTimeToFileTime function converts MS-DOS date and time values to a 64-bit file time.

Parameter	Description

wDOSDate	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, etc.)

9-15	Year offset from 1980 (add 1980 to get actual year)

wDOSTime	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)

lpft	Points to a FILETIME structure to receive the converted 64-bit file time.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

FileTimeToDosDateTime, FileTimeToSystemTime, SystemTimeToFileTime


DuplicateHandle function
DuplicateHandle (Win32)

BOOL DuplicateHandle(hSourceProcess, hSource, hTargetProcess, lphTarget, fdwAccess, fInherit, fdwOptions)

HANDLE hSourceProcess;	/* handle of process to duplicate from	*/
HANDLE hSource;	/* handle to duplicate	*/
HANDLE hTargetProcess;	/* handle of process to duplicate to	*/
LPHANDLE lphTarget;	/* address of duplicate handle	*/
DWORD fdwAccess;	/* access for duplicate handle	*/
BOOL fInherit;	/* handle inherited by child process?	*/
DWORD fdwOptions;	/* optional actions	*/

The DuplicateHandle function duplicates an object handle.

Parameter	Description

hSourceProcess	Identifies the process containing the handle to duplicate. The handle must have PROCESS_DUP_HANDLE access.

hSource	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, refer to the Comments section.

hTargetProcess	Identifies the process that is to receive the duplicated handle. The handle must have PROCESS_DUP_HANDLE access.

lphTarget	Points to a variable receiving the value of the duplicate handle. This handle value is valid in the context of the target process.

This parameter can be NULL. A NULL value is useful when the function's effects are desired, but the caller has no interest in a duplicate handle.

fdwAccess	Specifies the access requested for the new handle. This parameter is ignored if the fdwOptions 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 Comments section. Note that the new handle can have more access than the original handle.

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

fdwOptions	Specifies optional actions. This parameter can be zero, or any combination of the following flags:

Value	Meaning

DUPLICATE_CLOSE_SOURCE	Close the source handle. This occurs regardless of any error status returned.

DUPLICATE_SAME_ACCESS	Ignore the fdwAccess parameter. The duplicate handle has the same access as the source handle.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The DuplicateHandle function 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, shared memory) to communicate the process ID to the duplicating process. This ID 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 (for example, named pipe, shared memory) 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 or OpenProcess function.

Semaphore

The handle is returned by the CreateSemaphore or OpenSemaphore function.

Thread

The handle is returned by the CreateProcess, CreateThread or CreateRemoteThread function.

In addition to STANDARD_RIGHTS_REQUIRED, the following access flags can be specified in the fdwAccess parameter for the different object types. Note that the new handle can have more access than the original handle.

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

FILE_MAP_READ

Enables mapping the object into memory that permits read access.

FILE_MAP_ALL_ACCESS

Specifies all possible access flags for the file mapping object.

Any combination of the following access flags is valid for mutex objects:

Access	Description

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

MUTEX_ALL_ACCESS	Specifies all possible access flags for the mutex object.

Any combination of the following access flags is valid for semaphore objects:

Access	Description

SEMAPHORE_MODIFY_STATE	Enables use of the semaphore handle in the ReleaseSemaphore function to modify the semaphore's count.

SYNCHRONIZE	Enables use of the semaphore handle in any of the wait functions to wait for the semaphore's state to be signaled.

SEMAPHORE_ALL_ACCESS	Specifies all possible access flags for the semaphore object.

Any combination of the following access flags is valid for event objects:

Access	Description

EVENT_MODIFY_STATE	Enables use of the event handle in the SetEvent and ResetEvent functions to modify the event's state.

SYNCHRONIZE	Enables use of the event handle in any of the wait functions to wait for the event's state to be signaled.

EVENT_ALL_ACCESS	Specifies all possible access flags for the event object.

Any combination of the following access flags is valid for process objects:

Access	Description

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	Enables using the process handle in any of the wait functions to wait for the process to terminate.

PROCESS_ALL_ACCESS	Specifies all possible access flags for the process object.

Any combination of the following access flags is valid for thread objects:

Access	Description

SYNCHRONIZE

Enables using the thread handle in any of the wait functions to wait for the thread to terminate.

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.

THREAD_ALL_ACCESS

Specifies all possible access flags for the thread object.

See Also

CloseHandle


EndUpdateResource function
EndUpdateResource (Win32)

BOOL EndUpdateResource(hUpdateFile, fDiscard)

HANDLE hUpdateFile;	/* update-file handle	*/
BOOL fDiscard;	/* write flag	*/

The EndUpdateResource function ends a resource update in an executable file.

Parameter	Description

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

Returns

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 TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

BeginUpdateResource, UpdateResource


EnterCriticalSection function
EnterCriticalSection (Win32)

VOID EnterCriticalSection(lpcsCriticalSection)

LPCRITICAL_SECTION lpcsCriticalSection;	/* address of critical section object	*/

The EnterCriticalSection function waits for ownership of the specified critical section object. The function returns when the calling thread is granted ownership.

Parameter	Description

lpcsCriticalSection	Points to the critical section object.

Returns

This function does not return a value.

Comments

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 EnterCriticalSection to request ownership of the critical section before executing any section of code that accesses the protected resource. If another thread currently owns the critical section object, EnterCriticalSection blocks the execution of the calling thread indefinitely until the other thread releases its ownership. If the critical section object is currently unowned, the system grants ownership to the requesting thread so it can access the resource. 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.

Once a thread has ownership of a critical section, it can make additional calls to EnterCriticalSection without blocking its execution. This prevents a thread from deadlocking itself while waiting for a critical section that it already owns. To release its ownership, the thread must call LeaveCriticalSection once for each time that it entered the critical section.

For similar synchronization between the threads of different processes, use a mutex object.

See Also

CreateMutex, DeleteCriticalSection, InitializeCriticalSection, LeaveCriticalSection


EnumResourceLanguages function
EnumResourceLanguages (Win32)

BOOL EnumResourceLanguages(hModule, lpszType, lpszName, lpEnumFunc, lParam)

HINSTANCE hModule;	/* resource-module handle	*/
LPCTSTR lpszType;	/* address of resource type	*/
LPCTSTR lpszName;	/* address of resource name	*/
ENUMRESLANGPROC lpEnumFunc;	/* address of callback function	*/
LONG lParam;	/* application-defined parameter	*/

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.

Parameter	Description

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.

lpszType	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_BITMAP	Bitmap resource

RT_DIALOG	Dialog box

RT_FONT	Font resource

RT_FONTDIR	Font directory resource

RT_MENU	Menu resource

RT_RCDATA	Application-defined resource (raw data)

RT_STRING	String-table entry

RT_MESSAGETABLE	Message-table entry

RT_CURSOR	Hardware-dependent cursor resource

RT_GROUP_CURSOR	Hardware-independent cursor resource

RT_ICON	Hardware-dependent icon resource

RT_GROUP_ICON	Hardware-independent icon resource

RT_VERSION	Version resource

lpszName	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 description of the EnumResLangProc function.

lParam	Specifies an application-defined value passed to the callback function. This parameter may be used in error checking.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
EnumResourceNames (Win32)

BOOL EnumResourceNames(hModule, lpszType, lpEnumFunc, lParam)

HINSTANCE hModule;	/* resource-module handling	*/
LPCTSTR lpszType;	/* address of resource type	*/
ENUMRESNAMEPROC lpEnumFunc;	/* address of callback function	*/
LONG lParam;	/* application-defined parameter	*/

The EnumResourceNames function searches a module for each resource of the specified type passes the name of each resource it locates to an application-defined callback function.

Parameter	Description

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_BITMAP	Bitmap resource

RT_DIALOG	Dialog box

RT_FONT	Font resource

RT_FONTDIR	Font directory resource

RT_MENU	Menu resource

RT_RCDATA	Application-defined resource (raw data)

RT_STRING	String-table entry

RT_MESSAGETABLE	Message-table entry

RT_CURSOR	Hardware-dependent cursor resource

RT_GROUP_CURSOR	Hardware-independent cursor resource

RT_ICON	Hardware-dependent icon resource

RT_GROUP_ICON	Hardware-independent icon resource

RT_VERSION	Version resource

lpEnumFunc	Points to the callback function to be called for each enumerated resource name. For more information, see the description of the EnumResNameProc function.

lParam	Specifies an application-defined value passed to the callback function. This parameter can be used in error checking.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
EnumResourceTypes (Win32)

BOOL EnumResourceTypes(hModule, lpEnumFunc, lParam)

HINSTANCE hModule;	/* resource-module handle	*/
ENUMRESTYPEPROC lpEnumFunc;	/* address of callback function	*/
LONG lParam;	/* application-defined parameter	*/

The EnumResourceTypes function searches a module for resources and passes each resource type it finds to an application-defined callback function.

Parameter	Description

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 description of the EnumResTypeProc function.

lParam	Specifies an application-defined value passed to the callback function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


EraseTape function
EraseTape (Win32)

DWORD EraseTape(hDevice, fdwEraseType, bImmediate)

HANDLE hDevice;	/* handle of open device	*/
DWORD fdwEraseType;	/* type of erasure to perform	*/
BOOL bImmediate;	/* return after erase operation begins	*/

The EraseTape function erases all or part of a tape.

Parameter	Description

hDevice	Identifies the device where the tape is to be erased. This handle is created by using the CreateFile function.

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

Returns

If the function succeeds, the return value is NO_ERROR; otherwise, it 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.

Comments

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.


EscapeCommFunction function
EscapeCommFunction (Win32)

BOOL EscapeCommFunction(hCommDev, fdwFunc)

HANDLE hCommDev;	/* handle of the communications device	*/
DWORD fdwFunc;	/* extended function to perform	*/

The EscapeCommFunction function directs a given communications device to perform an extended function.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

fdwFunc	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 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 non-break state. The CLRBREAK extended function is identical to the ClearCommBreak function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

ClearCommBreak, SetCommBreak


ExitProcess function
ExitProcess (Win32)

VOID ExitProcess(uExitCode)

UINT uExitCode;	/* exit code for all threads	*/

The ExitProcess function ends a process and all its threads.

Parameter	Description

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 code. Use the GetExitCodeThread function to retrieve a thread's exit code.

Returns

This function does not return a value.

Comments

The ExitProcess function is the preferred method of ending a process. This function provides a clean process shutdown. This includes calling the entrypoint function of all attached DLLs with a code 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 code, 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 code 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.

ExitProcess, ExitThread, CreateThread, CreateRemoteThread, 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:

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

2	Only one thread in a process can be in a DLL initialization or detach routine at a time.

3	The ExitProcess function 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 function
ExitThread (Win32)

VOID ExitThread(dwExitCode)

DWORD dwExitCode;	/* exit code for this thread	*/

The ExitThread function ends a thread.

Parameter	Description

dwExitCode	Specifies the exit code for the calling thread. Use the GetExitCodeThread function to retrieve a thread's exit code.

Returns

This function does not return a value.

Comments

The ExitThread function 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 entrypoint function of all attached DLLs is invoked with a code 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.

ExitProcess, ExitThread, CreateThread, CreateRemoteThread, 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:

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

2	Only one thread in a process can be in a DLL initialization or detach routine at a time.

3	The ExitProcess function does not return until no threads are in their DLL initialization or detach routines.

See Also

CreateProcess, CreateRemoteThread, CreateThread, ExitProcess, GetExitCodeThread, TerminateThread


ExpandEnvironmentStrings function
ExpandEnvironmentStrings (Win32)

DWORD ExpandEnvironmentStrings(lpszSrc, lpszDest, cchDest)

LPCTSTR lpszSrc;	/* address of string with environment variables	*/
LPTSTR lpszDest;	/* address of string with expanded env. variables	*/
DWORD cchDest;	/* maximum chars. in expanded string	*/

The ExpandEnvironmentStrings function expands environment-variable strings and replaces them with their defined values.

Parameter	Description

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

lpszDest	Points to a buffer to receive a copy of the source buffer, after all environment-variable name substitutions have been performed.

cchDest	Specifies the maximum number of characters that can be stored in the buffer pointed to by the lpszDest parameter, including the terminating null character.

Returns

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, use the GetLastError function.


FatalAppExit function
FatalAppExit (Win32)

VOID FatalAppExit(uAction, lpszMessageText)

UINT uAction;	/* reserved	*/
LPCTSTR lpszMessageText;	/* address of string to display in message box	*/

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.

Parameter	Description

uAction	Reserved; must be zero.

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

Returns

This function does not return a value.

Comments

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 function
FatalExit (Win32)

VOID FatalExit(nExitCode)

int nExitCode;	/* error code	*/

The FatalExit function transfers execution control to the debugger. The behavior of the debugger thereafter is specific to the type of debugger used.

Parameter	Description

nExitCode	Specifies the error code associated with this exit.

Returns

This function does not return a value.

Comments

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


FileTimeToDosDateTime function
FileTimeToDosDateTime (Win32)

BOOL FileTimeToDosDateTime(lpft, lpwDOSDate, lpwDOSTime)

CONST FILETIME * lpft;	/* address of 64-bit file time	*/
LPWORD lpwDOSDate;	/* address of variable for MS-DOS date	*/
LPWORD lpwDOSTime;	/* address of variable for MS-DOS time	*/

The FileTimeToDosDateTime function converts a 64-bit file time to MS-DOS date and time values.

Parameter	Description

lpft	Points to a FILETIME structure containing the 64-bit file time to convert to MS-DOS date and time format.

lpwDOSDate	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)

lpwDOSTime	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)

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
FileTimeToLocalFileTime (Win32)

BOOL FileTimeToLocalFileTime(LPFILETIME lpft, LPFILETIME lpftLocal)

CONST FILETIME * lpft;	/* address of UTC file time to convert	*/
LPFILETIME lpftLocal;	/* address of converted file time	*/

The FileTimeToLocalFileTime function converts a file time based on the Coordinated Universal Time (UTC) to a local file time.

Parameter	Description

lpft	Points to a FILETIME structure containing the UTC-based file time to be converted into a local file time.

lpftLocal	Points to a FILETIME structure to receive the converted local file time. This parameter cannot be the same as the lpft parameter.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

LocalFileTimeToFileTime


FileTimeToSystemTime function
FileTimeToSystemTime (Win32)

BOOL FileTimeToSystemTime(lpft, lpst)

CONST FILETIME * lpft;	/* address of file time to convert	*/
LPSYSTEMTIME lpst;	/* address of converted system time	*/

The FileTimeToSystemTime function converts a 64-bit file time to system time format.

Parameter	Description

lpft	Points to a FILETIME structure containing the file time to convert to system date and time format.

lpst	Points to a SYSTEMTIME structure to receive the converted file time.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

DosDateTimeToFileTime, FileTimeToDosDateTime, SystemTimeToFileTime


FillConsoleOutputAttribute function
FillConsoleOutputAttribute (Win32)

BOOL FillConsoleOutputAttribute(hConsole, wAttribute, cCharCells, coordAttr, lpcWritten)

HANDLE hConsole;	/* handle of screen buffer	*/
WORD wAttribute;	/* color attribute to write	*/
DWORD cCharCells;	/* number of character cells to write to	*/
COORD coordAttr;	/* x- and y-coordinates of first cell	*/
LPDWORD lpcWritten;	/* address of number of cells written to	*/

The FillConsoleOutputAttribute function sets the text and background color attributes for a specified number of character cells, beginning at the given coordinates in a screen buffer.

Parameter	Description

hConsole	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

cCharCells	Specifies the number of character cells to be set to the specified color attributes.

coordAttr	Specifies a COORD structure containing the screen buffer coordinates of the first cell whose attributes are to be set.

lpcWritten	Points to the variable that receives the number of character cells whose attributes were actually set.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

FillConsoleOutputCharacter, SetConsoleTextAttribute, WriteConsoleOutputAttribute


FillConsoleOutputCharacter function
FillConsoleOutputCharacter (Win32)

BOOL FillConsoleOutputCharacter(hConsole, chFillChar, cCharCells, coordChar, lpcWritten)

HANDLE hConsole;	/* handle of screen buffer	*/
TCHAR chFillChar;	/* character to write	*/
DWORD cCharCells;	/* number of character cells to write to	*/
COORD coordChar;	/* x- and y-coordinates of first cell	*/
LPDWORD lpcWritten;	/* address of number of cells written to	*/

The FillConsoleOutputCharacter function writes a character to the screen buffer a specified number of times, beginning at the given coordinates.

Parameter	Description

hConsole	Identifies a screen buffer. The handle must have GENERIC_WRITE access.

chFillChar	Specifies the character to write to the screen buffer.

cCharCells	Specifies the number of character cells to write the character to.

coordChar	Specifies a COORD structure containing the screen buffer coordinates of the first cell to write the character to.

lpcWritten	Points to the variable that receives the number of characters actually written to the screen buffer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

See Also

FillConsoleOutputAttribute, WriteConsoleOutputCharacter


FillMemory function
FillMemory (Win32)

VOID FillMemory (Destination, Length, Fill)

PVOID Destination;	/* address of block to fill	*/
DWORD Length;	/* size in bytes of block to fill	*/
BYTE Fill;	/* the byte value with which to fill	*/

The FillMemory function fills a block of memory with a specified value.

Parameter	Description

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.

Returns

This function has no return value.

See Also

CopyMemory, MoveMemory, ZeroMemory


FindAtom function
FindAtom (Win32)

ATOM FindAtom(lpszString)

LPCTSTR lpszString;	/* address of string to find	*/

The FindAtom function searches the local atom table for the specified character string and retrieves the atom associated with that string.

Parameter	Description

lpszString	Points to the null-terminated character string to search for.

Returns

If the function succeeds, the return value is the atom associated with the given string. Otherwise, the return value is zero. To get extended error information, use the GetLastError function.

Comments

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 function
FindClose (Win32)

BOOL FindClose(hFindFile)

HANDLE hFindFile;	/* file search handle	*/

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.

Parameter	Description

hFindFile	Identifies the search handle. This handle must have been previously opened by the FindFirstFile function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
FindCloseChangeNotification (Win32)

BOOL FindCloseChangeNotification(hChange)

HANDLE hChange;	/* handle of change notification to close	*/

The FindCloseChangeNotification function stops notification handle change monitoring.

Parameter	Description

hChange	Identifies a change notification handle created by the FindFirstChangeNotification function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

After the FindCloseChangeNotification function is called, the handle specified by the hChange parameter cannot be used in subsequent calls to either the FindNextChangeNotification or FindCloseChangeNotification function.

See Also

FindFirstChangeNotification, FindNextChangeNotification, WaitForMultipleObjects, WaitForSingleObject


FindFirstChangeNotification function
FindFirstChangeNotification (Win32)

HANDLE FindFirstChangeNotification(lpszPath, fWatchSubTree, fdwFilter)

LPCTSTR lpszPath;	/* address of the name of the directory to watch	*/
BOOL fWatchSubTree;	/* flag for monitoring directory or directory tree	*/
DWORD fdwFilter;	/* filter conditions to watch for	*/

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.

Parameter	Description

lpszPath	Points to a null-terminated string that specifies the path of the directory to watch.

fWatchSubTree	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 FALSE, it monitors only the specified directory.

fdwFilter	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 satisfies a change notification wait. This includes renames, creations, and deletes.

FILE_NOTIFY_CHANGE_DIR_NAME

Any directory-name change in the watched directory or subtree satisfies a change notification wait. This includes directory creations and deletions.

FILE_NOTIFY_CHANGE_ATTRIBUTES

Any attribute change in the watched directory or subtree satisfies a change notification wait.

FILE_NOTIFY_CHANGE_SIZE

Any file-size change in the watched directory or subtree satisfies a change notification wait. 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, this 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 satisfies a change notification wait. 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, this occurs only when the cache is sufficiently flushed.

FILE_NOTIFY_CHANGE_SECURITY

Any security-descriptor change in the watched directory or subtree satisfies a change notification wait.

Returns

If the function succeeds, the return value is a handle of a find change notification object; otherwise, it is INVALID_HANDLE_VALUE. To get extended error information, use the GetLastError function.

Comments

The WaitForSingleObject and WaitForMultipleObjects functions 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, close it by using the FindCloseChangeNotification function.

See Also

FindCloseChangeNotification, FindNextChangeNotification, WaitForMultipleObjects, WaitForSingleObject


FindFirstFile function
FindFirstFile (Win32)

HANDLE FindFirstFile(lpszSearchFile, lpffd)

LPCTSTR lpszSearchFile;	/* address of name of the file to search for	*/
LPWIN32_FIND_DATA lpffd;	/* address of returned information	*/

The FindFirstFile function searches a directory for a file whose name matches the specified filename. FindFirstFile examines subdirectory names as well as filenames.

Parameter	Description

lpszSearchFile	Points to a null-terminated string that specifies a valid directory or path and filename, which can contain wildcard characters (* and ?).

lpffd	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 functions to refer to the file or subdirectory.

Returns

If the function succeeds, the return value is a search handle used in a subsequent call to FindNextFile or FindClose; otherwise, it is INVALID_HANDLE_VALUE. To get extended error information, use the GetLastError function.

Comments

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


FindNextChangeNotification function
FindNextChangeNotification (Win32)

BOOL FindNextChangeNotification(hChange)

HANDLE hChange;	/* handle of change notification to signal	*/

The FindNextChangeNotification function requests that the operating system signal a change notification handle the next time it detects an appropriate change.

Parameter	Description

hChange	Specifies a change notification handle created by the FindFirstChangeNotification function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

After the FindNextChangeNotification function returns successfully, the application can wait for notification that a change has occurred by using the WaitForSingleObject or WaitForMultipleObjects function.

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.

Do not use FindNextChangeNotification more than once on the same handle without using either WaitForSingleObject or WaitForMultipleObjects. An application may miss a change notification if it uses FindNextChangeNotification when there is a change request outstanding.

When hChange is no longer needed, close it by using the FindCloseChangeNotification function.

See Also

FindCloseChangeNotification, FindFirstChangeNotification, WaitForMultipleObjects, WaitForSingleObject


FindNextFile function
FindNextFile (Win32)

BOOL FindNextFile(hFindFile, lpffd)

HANDLE hFindFile;	/* handle of search returned by FindFirstFile	*/
LPWIN32_FIND_DATA lpffd;	/* address of structure for data on found file	*/

The FindNextFile function continues a file search from a previous call to the FindFirstFile function.

Parameter	Description

hFindFile	Specifies a search handle returned by a previous call to the FindFirstFile function.

lpffd	Points to the WIN32_FIND_DATA structure to receive 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function. If no matching files can be found, the GetLastError function returns ERROR_NO_MORE_FILES.

Comments

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


FindResource function
FindResource (Win32)

HRSRC FindResource(hModule, lpszName, lpszType)

HINSTANCE hModule;	/* resource-module handle	*/
LPCTSTR lpszName;	/* address of resource name	*/
LPCTSTR lpszType;	/* address of resource type	*/

The FindResource function determines the location of a resource with the given type and name in the given module.

Parameter	Description

hModule	Identifies the module whose executable file contains the resource.

lpszName	Specifies the name of the resource. For more details, see the Comments section.

lpszType	Specifies the resource type. For more details, see the Comments section. For standard resource types, this parameter can be one of the following values:

Value	Meaning

RT_ACCELERATOR	Accelerator table

RT_BITMAP	Bitmap resource

RT_DIALOG	Dialog box

RT_FONT	Font resource

RT_FONTDIR	Font directory resource

RT_MENU	Menu resource

RT_RCDATA	Application-defined resource (raw data)

RT_STRING	String-table entry

RT_MESSAGETABLE	Message-table entry

RT_CURSOR	Hardware-dependent cursor resource

RT_GROUP_CURSOR	Hardware-independent cursor resource

RT_ICON	Hardware-dependent icon resource

RT_GROUP_ICON	Hardware-independent icon resource

RT_VERSION	Version resource

Returns

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, use the GetLastError function.

Comments

If the high-order word of the lpszName or lpszType 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 function
FindResourceEx (Win32)

HRSRC FindResourceEx(hModule, lpszType, lpszName, wLanguage)

HINSTANCE hModule;	/* resource-module handle	*/
LPCTSTR lpszType;	/* address of resource type	*/
LPCTSTR lpszName;	/* address of resource name	*/
WORD wLanguage;	/* resource language	*/

The FindResourceEx function determines the location of the resource with the specified type, name, and language in the given module.

Parameter	Description

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.

lpszType	Points to a null-terminated string specifying the type name of the resource. For standard resource types, this parameter can be one of the following values:

Value	Meaning

RT_ACCELERATOR	Accelerator table

RT_BITMAP	Bitmap resource

RT_DIALOG	Dialog box

RT_FONT	Font resource

RT_FONTDIR	Font directory resource

RT_MENU	Menu resource

RT_RCDATA	Application-defined resource (raw data)

RT_STRING	String-table entry

RT_MESSAGETABLE	Message-table entry

RT_CURSOR	Hardware-dependent cursor resource

RT_GROUP_CURSOR	Hardware-independent cursor resource

RT_ICON	Hardware-dependent icon resource

RT_GROUP_ICON	Hardware-independent icon resource

RT_VERSION	Version resource

lpszName	Points to a null-terminated string specifying the name of the resource.

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 in the <Microsoft Win32 Programmer's Reference, Volume 5>.

Returns

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, use the GetLastError function.

Comments

If the high-word of the lpszType or lpszName 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, LoadResource, MAKELANGID


FlushConsoleInputBuffer function
FlushConsoleInputBuffer (Win32)

BOOL FlushConsoleInputBuffer(hConsoleInput)

HANDLE hConsoleInput;	/* handle of console input buffer	*/

The FlushConsoleInputBuffer function flushes the console input buffer. All input records currently in the input buffer are discarded.

Parameter	Description

hConsoleInput	Identifies the console input buffer. The handle must have GENERIC_WRITE access.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetNumberOfConsoleInputEvents, PeekConsoleInput, ReadConsoleInput, WriteConsoleInput


FlushFileBuffers function
FlushFileBuffers (Win32)

BOOL FlushFileBuffers(hFile)

HANDLE hFile;	/* handle of file to which the function writes data	*/

The FlushFileBuffers function clears the buffers for the specified file and causes all buffered data to be written to the file.

Parameter	Description

hFile	Specifies an open file handle. The file handle must have been created with GENERIC_WRITE access to the file.

If hFile specifies a communications device, this function flushes only the transmit buffer.

If hFile specifies the server end of a named pipe, this function does not return until the client has read all buffered data from the pipe.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The WriteFile and WriteFileEx functions typically write data to an internal buffer written to disk on a regular basis. The FlushFileBuffers function writes all of the buffered information for the specified file to disk.

See Also

WriteFile, WriteFileEx


FlushInstructionCache function
FlushInstructionCache (Win32)

BOOL FlushInstructionCache(hProcess, lpvBase, cbFlush)

HANDLE hProcess;	/* process with cache to flush	*/
LPCVOID lpvBase;	/* address of region to flush	*/
DWORD cbFlush;	/* length of region to flush	*/

The FlushInstructionCache function flushes the instruction cache for the specified process.

Parameter	Description

hProcess	Identifies the process that has an instruction cache to flush.

lpvBase	Points to the base of the region to be flushed. This parameter can be NULL.

cbFlush	Specifies the length of the region to be flushed if the lpvBase parameter is not NULL.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.


FlushViewOfFile function
FlushViewOfFile (Win32)

BOOL FlushViewOfFile(lpvBase, cbFlush)

LPCVOID lpvBase;	/* start address of byte range to flush	*/
DWORD cbFlush;	/* number of bytes in range	*/

The FlushViewOfFile function writes to the disk a byte range within a mapped view of a file.

Parameter	Description

lpvBase	Specifies the base address of the byte range to be flushed to the disk representation of the mapped file.

cbFlush	Specifies the number of bytes to flush.

If cbFlush is zero, the file is flushed from the base address to the end of the mapping.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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. This happens automatically whenever a view is unmapped, either explicitly, by using the UnmapViewOfFile function, or as a result of process termination.

See Also

MapViewOfFile, UnmapViewOfFile


FormatMessage function
FormatMessage (Win32)

DWORD FormatMessage(dwFlags, lpSource, dwMessageId, dwLanguageId, lpBuffer, nSize, Arguments)

DWORD dwFlags;	/* source and processing options	*/
LPCVOID lpSource;	/* address of message source	*/
DWORD dwMessageId;	/* requested message identifier	*/
DWORD dwLanguageId;	/* language identifier for requested message	*/
LPTSTR lpBuffer;	/* address of message buffer	*/
DWORD nSize;	/* maximum size of message buffer	*/
va_list * Arguments;	/* address of array of message inserts	*/

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 ID and a language ID. The function copies the formatted message text to an output buffer, processing any embedded insert sequences if requested.

Parameter	Description

dwFlags	Specifies various function options. The high order bits are a set of flags that specify aspects of the formatting process and how to interpret the lpSource parameter. If one of those flags, the FORMAT_MESSAGE_MAX_WIDTH_MASK, is set, then the low order 8 bits specify the maximum width, in characters, of a formatted line. The following constants may be used to set 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 characters 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.

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' application image file will be searched.

FORMAT_MESSAGE_FROM_SYSTEM

Specifies that the function should search the system message-table resource(s) for the requested message if it is not found in lpSource, or if lpSource is not examined, which occurs when neither of the preceding two flags is specified.

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.

FORMAT_MESSAGE_MAX_WIDTH_MASK

Specifies that the low order 8 bits of dwFlags contain data that determines the maximum width, in characters, of each line formatted into the output buffer.

A zero value in the low order 8 bits of dwFlags means that there are no width restrictions, and only the line breaks in the message definition will go into the output buffer.

A non-zero value in the low order 8 bits of dwFlags means that line breaks in the message definition text are ignored; instead, that non-zero value determines the maximum output line width, with the proviso that strings delimited by white space are never split across a line break. Hard coded line breaks in the message definition text, identified by the %n escape sequence, are always output to the output buffer.

A value of FORMAT_MESSAGE_MAX_WIDTH_MASK in the low order 8 bits of dwFlags means that line breaks in the message definition text are ignored, hard coded line breaks are kept, and no new line breaks are generated.

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.

lpBuffer	Points to a buffer for the formatted (and null-terminated) message. If dwFlags includes FORMAT_MESSAGE_ALLOCATE_BUFFER, the function allocates a buffer via LocalAlloc,  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 characters that can be stored in the output buffer. If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is set, this parameter specifies the minimum number of 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.

Returns

If the function succeeds, the return value is the number of characters stored in the output buffer, excluding the terminating null character; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

An application can use the FORMAT_MESSAGE_MAX_WIDTH_MASK constant to mask the low 8 bits of dwFlags to retrieve the maximum line length.

Each insert must have a corresponding element in the array pointed to by the Arguments parameter.

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


FreeConsole function
FreeConsole (Win32)

BOOL FreeConsole(VOID)

The FreeConsole function detaches the calling process from its console.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If other processes share the console, the console is not destroyed, but the calling process cannot reference 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


FreeLibrary function
FreeLibrary (Win32)

BOOL FreeLibrary(hLibModule)

HINSTANCE hLibModule;	/* handle of loaded library module	*/

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.

Parameter	Description

hLibModule	Identifies the loaded library module. The LoadLibrary or GetModuleHandle function returns this handle.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Each process maintains a reference count for each loaded library module. This reference count is incremented each time LoadLibrary is called, and decremented each time FreeLibrary is called. A DLL library module loaded at process initialization due to load-time dynamic linking has a reference count of one. This count incremented if the same module is loaded by a call to LoadLibrary.

Before unmapping a DLL 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 flag. This gives the DLL an opportunity to clean up resources allocated on behalf of the current process. After the entrypoint 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

LoadLibrary


FreeResource function
FreeResource (Win32)

The FreeResource function is obsolete. It is not necessary for Win32 applications to free resources loaded by using the LoadResource function.

See Also

LoadResource, LockResource


GenerateConsoleCtrlEvent function
GenerateConsoleCtrlEvent (Win32)

BOOL GenerateConsoleCtrlEvent(fdwEvent, IDProcessGroup)

DWORD fdwEvent;	/* signal to generate	*/
DWORD IDProcessGroup;	/* process group to get signal	*/

The GenerateConsoleCtrlEvent function sends a specified signal to a console process group that shares the console associated with the calling process.

Parameter	Description

fdwEvent	Specifies the type of signal to generate. One of the following values is specified:

Value	Meaning

CTRL_C_EVENT	Generates CTRL+C signal.

CTRL_BREAK_EVENT	Generates CTRL+BREAK signal.

IDProcessGroup	Identifies 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 the new process group. The process group includes all processes that are descendants of this 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SetConsoleCtrlHandler


GetAtomName function
GetAtomName (Win32)

UINT GetAtomName(atm, lpszBuffer, cchBuffer)

ATOM atm;	/* atom identifying character string	*/
LPTSTR lpszBuffer;	/* address of buffer for atom string	*/
int cchBuffer;	/* size of buffer	*/

The GetAtomName function retrieves a copy of the character string associated with the specified local atom.

Parameter	Description

atm	Specifies the local atom that identifies the character string to be retrieved.

lpszBuffer	Points to the buffer for the character string.

cchBuffer	Specifies the size, in characters, of the buffer.

Returns

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. Otherwise, the return value is zero. To get extended error information, use the GetLastError function.

Comments

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


GetCommandLine function
GetCommandLine (Win32)

LPTSTR GetCommandLine(VOID)

The GetCommandLine function returns the command line for the current process.

Returns

The return value is the address of the command line for the current process.

Comments

Non-UNICODE console processes written in c can use the argc/argv mechanism 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 LPSTRs for parameters, not LPTSTRs.

See Also

CreateProcess, WinMain


GetCommMask function
GetCommMask (Win32)

BOOL GetCommMask(hCommDev, lpfdwEvtMask)

HANDLE hCommDev;	/* handle of the communications device	*/
LPDWORD lpfdwEvtMask;	/* address of variable to get the event mask	*/

The GetCommMask function retrieves the value of the event mask for a given communications device.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

lpfdwEvtMask	Points to the 32-bit variable to be filled in 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_RING	A ring indicator was detected.

EV_RLSD	The RLSD (receive-line-signal-detect) signal changed state.

EV_RXCHAR	Any 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The GetCommMask function sets the bits of 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 to wait for one of the events to occur. To modify the event mask of a communications resource, use the SetCommMask function.

See Also

SetCommMask


GetCommModemStatus function
GetCommModemStatus (Win32)

BOOL GetCommModemStatus(hCommDev, lpfdwModemStats)

HANDLE hCommDev;	/* handle of the communications device	*/
LPDWORD lpfdwModemStats;	/* address of control-register values	*/

The GetCommModemStatus function retrieves modem control-register values.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

lpfdwModemStats	Points to a 32-bit variable whose bits are set to indicate the current state of the modem control-register values. This parameter can be a combination of the following flags:

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

WaitCommEvent


GetCommProperties function
GetCommProperties (Win32)

BOOL GetCommProperties(hCommDev, lpcmmp)

HANDLE hCommDev;	/* handle of the communications device	*/
LPCOMMPROP lpcmmp;	/* address of communications properties structure	*/

The GetCommProperties function fills a buffer with information about the communications properties for a given communications device.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

lpcmmp	Points to a COMMPROP structure in which the communications properties information is returned. The structure can be used in subsequent calls to the SetCommState, SetCommTimeouts, or SetupComm functions to configure the communications device.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The GetCommProperties function returns information from a device driver about the configuration settings that are supported by the driver.

See Also

SetCommState, SetCommTimeouts, SetupComm, COMMPROP


GetCommState function
GetCommState (Win32)

BOOL GetCommState(hCommDev, lpdcb)

HANDLE hCommDev;	/* handle of the communications device	*/
LPDCB lpdcb;	/* address of device-control block structure	*/

The GetCommState function fills in a device-control block (a DCB structure) with the current control settings for a given communications device.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

lpdcb	Points to the DCB structure in which the control settings information is returned.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

SetCommState, DCB


GetCommTimeouts function
GetCommTimeouts (Win32)

BOOL GetCommTimeouts(hCommDev, lpct)

HANDLE hCommDev;	/* handle of the communications device	*/
LPCOMMTIMEOUTS lpct;	/* address of comm timeouts structure	*/

The GetCommTimeouts function retrieves the timeout parameters for all read and write operations on a given communications device.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

lpct	Points to a COMMTIMEOUTS structure in which the timeout information is returned.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

For more information about timeout values for communications devices, see the SetCommTimeouts function.

See Also

SetCommTimeouts


GetComputerName function
GetComputerName (Win32)

BOOL GetComputerName(lpszName, lpcchBuffer)

LPTSTR lpszName;	/* address of name buffer	*/
LPDWORD lpcchBuffer;	/* address of size of name buffer	*/

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.

Parameter	Description

lpszName	Points to a buffer to receive the null-terminated character string containing the computer name.

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

Returns

If the function succeeds, the return value is TRUE and the variable at lpcchBuffer contains the number of characters copied to the destination buffer, not including the terminating null character. If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

See Also

SetComputerName


GetConsoleCP function
GetConsoleCP (Win32)

UINT GetConsoleCP(VOID)

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.

Returns

The return value is a code that identifies the code page.

Comments

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 function
GetConsoleCursorInfo (Win32)

BOOL GetConsoleCursorInfo(hConsoleOutput, pcci)

HANDLE hConsoleOutput;	/* handle of console screen buffer	*/
PCONSOLE_CURSOR_INFO pcci;	/* address of cursor information	*/

The GetConsoleCursorInfo function retrieves the size and visibility of the cursor for the specified console screen buffer.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer. The handle must have GENERIC_READ access.

pcci	Points to a CONSOLE_CURSOR_INFO structure in which information about the console's cursor is returned.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

SetConsoleCursorInfo


GetConsoleMode function
GetConsoleMode (Win32)

BOOL GetConsoleMode(hConsole, lpfdwMode)

HANDLE hConsole;	/* handle of console input or screen buffer	*/
LPDWORD lpfdwMode;	/* current mode flags	*/

The GetConsoleMode function reports the current input mode of a console's input buffer or the current output mode of a console screen buffer.

Parameter	Description

hConsole	Identifies a console input buffer or a screen buffer. The handle must have GENERIC_READ access.

lpfdwMode	Points to a 32-bit variable whose bits are set to indicate the current mode of the specified buffer.

If the hConsole 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 the ENABLE_MOUSE_INPUT mode is enabled.

If the hConsole 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 line when it reaches the end of the current row. This causes the lines displayed in the console window to scroll up automatically when the cursor advances beyond the last line in the window. It also causes the contents of the screen buffer to scroll up (discarding the top line of the screen buffer) when the cursor advances beyond the last line in the screen buffer. If this mode is disabled, the last character in the row is overwritten.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, use the SetConsoleMode function.

See Also

ReadConsole, ReadConsoleInput, ReadFile, SetConsoleMode, WriteConsole, WriteFile


GetConsoleOutputCP function
GetConsoleOutputCP (Win32)

UINT GetConsoleOutputCP(VOID)

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.

Returns

The return value is a code that identifies the code page.

Comments

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 function
GetConsoleScreenBufferInfo (Win32)

BOOL GetConsoleScreenBufferInfo(hConsoleOutput, pcsbi)

HANDLE hConsoleOutput;	/* handle of console screen buffer	*/
PCONSOLE_SCREEN_BUFFER_INFO pcsbi;	/* address of screen info. buffer	*/

The GetConsoleScreenBufferInfo function retrieves information about the specified console screen buffer.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer. The handle must have GENERIC_READ access.

pcsbi	Points to a CONSOLE_SCREEN_BUFFER_INFO structure in which the screen buffer information is returned.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

GetLargestConsoleWindowSize, SetConsoleCursorPosition, SetConsoleScreenBufferSize, SetConsoleWindowInfo


GetConsoleTitle function
GetConsoleTitle (Win32)

DWORD GetConsoleTitle(lpszTitle, cchTitle)

LPTSTR lpszTitle;	/* address of buffer for title	*/
DWORD cchTitle;	/* size of the buffer	*/

The GetConsoleTitle function retrieves the title bar string for the current console window.

Parameter	Description

lpszTitle	Points to a buffer that receives a null-terminated string containing the string that appears in the title bar of the console window.

cchTitle	Specifies the size, in characters, of the buffer pointed to by the lpszTitle parameter.

Returns

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

To set the title bar string for a console window, use the SetConsoleTitle function.

See Also

SetConsoleTitle


GetCurrentDirectory function
GetCurrentDirectory (Win32)

DWORD GetCurrentDirectory(cchCurDir, lpszCurDir)

DWORD cchCurDir;	/* size, in characters, of directory buffer	*/
LPTSTR lpszCurDir;	/* address of buffer for current directory	*/

The GetCurrentDirectory function retrieves the current directory for the current process.

Parameter	Description

cchCurDir	Specifies the length, in characters, of the buffer for the current directory string. The buffer length must include room for a terminating null character.

lpszCurDir	Points to the buffer for the current directory string. This null-terminated string specifies the absolute path to the current directory.

Returns

If the function succeeds, the return value specifies the number of characters written to the buffer, not including the terminating null character; otherwise, it is zero. To get extended error information, use the GetLastError function.

If the lpszCurDir buffer is not large enough, the return value specifies the required size of the buffer, not including the number of bytes necessary for a terminating null character.

See Also

CreateDirectory, GetSystemDirectory, GetWindowsDirectory, RemoveDirectory, SetCurrentDirectory


GetCurrentProcess function
GetCurrentProcess (Win32)

HANDLE GetCurrentProcess(VOID)

The GetCurrentProcess function returns a pseudohandle for the current process.

Returns

The return value is a pseudohandle to the current process.

Comments

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.

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 function
GetCurrentProcessId (Win32)

DWORD GetCurrentProcessId(VOID)

The GetCurrentProcessId function returns the process identifier of the calling process.

Returns

The return value is the process identifier of the calling process.

Comments

Until the process terminates, the process identifier uniquely identifies the process throughout the system.

See Also

GetCurrentProcess, OpenProcess


GetCurrentThread function
GetCurrentThread (Win32)

HANDLE GetCurrentThread(VOID)

The GetCurrentThread function returns a pseudohandle for the current thread.

Returns

The return value is a pseudohandle for the current thread.

Comments

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 function
GetCurrentThreadId (Win32)

DWORD GetCurrentThreadId(VOID)

The GetCurrentThreadId function returns the thread identifier of the calling thread.

Returns

The return value is the thread identifier of the calling thread.

Comments

Until the thread terminates, the thread identifier uniquely identifies the thread throughout the system

See Also

GetCurrentThread


GetDiskFreeSpace function
GetDiskFreeSpace (Win32)

BOOL GetDiskFreeSpace(lpszRootPathName, lpSectorsPerCluster, lpBytesPerSector, lpFreeClusters, lpClusters)

LPCTSTR lpszRootPathName;	/* address of root path name	*/
LPDWORD lpSectorsPerCluster;	/* address of sectors per cluster	*/
LPDWORD lpBytesPerSector;	/* address of bytes per sector	*/
LPDWORD lpFreeClusters;	/* address of number of free clusters	*/
LPDWORD lpClusters;	/* address of total number of clusters	*/

The GetDiskFreeSpace function retrieves information about the specified disk, including the amount of free space on the disk.

Parameter	Description

lpszRootPathName	Points to a null-terminated string that specifies the root directory of the disk to return information about. If lpszRootPathName 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.

lpFreeClusters	Points to a variable for the total number of free clusters on the disk.

lpClusters	Points to a variable for the total number of clusters on the disk.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetDriveType


GetDriveType function
GetDriveType (Win32)

UINT GetDriveType(lpszRootPathName)

LPCTSTR lpszRootPathName;	/* address of root path name	*/

The GetDriveType function determines whether a disk drive is removable, fixed, CD-ROM, RAM disk, or a network drive.

Parameter	Description

lpszRootPathName	Points to a null-terminated string that specifies the root directory of the disk to return information about. If lpszRootPathName is NULL, the function uses the root of the current directory.

Returns

The return value specifies the type of drive. It can be one of the following values:

Value	Meaning

0	Drive type cannot be determined.

1	Root directory does not exist.

DRIVE_REMOVABLE	Disk can be removed from the drive.

DRIVE_FIXED	Disk cannot be removed from the drive.

DRIVE_REMOTE	Drive is a remote (network) drive.

DRIVE_CDROM	Drive is a CD-ROM drive.

DRIVE_RAMDISK	Drive is a RAM disk.

See Also

GetDiskFreeSpace


GetEnvironmentStrings function
GetEnvironmentStrings (Win32)

LPVOID GetEnvironmentStrings(VOID)

The GetEnvironmentStrings function returns the address of the environment block for the current process.

Returns

The return value is the address of the environment block for the current process.

Comments

Do not use the return value of the GetEnvironmentStrings function to get or set environment variables. Instead, use the GetEnvironmentVariable and SetEnvironmentVariable functions to access the environment variables within this block.

A process can use the return value to specify the environment address used by the CreateProcess function.

See Also

CreateProcess, GetEnvironmentVariable, SetEnvironmentVariable


GetEnvironmentVariable function
GetEnvironmentVariable (Win32)

DWORD GetEnvironmentVariable(lpszName, lpszValue, cchValue)

LPCTSTR lpszName;	/* address of environment variable name	*/
LPTSTR lpszValue;	/* address of buffer for variable value	*/
DWORD cchValue;	/* size of buffer in characters	*/

The GetEnvironmentVariable function retrieves the value of the specified variable from the environment block of the calling process.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the environment variable.

lpszValue	Points to a buffer to receive the value of the specified environment variable.

cchValue	Specifies the size in characters of the lpszValue buffer.

Returns

If the function succeeds, the return value is the number of characters stored in lpszValue, not including the terminating null character. The return value is zero if the environment variable name was not found in the environment block for the current process. If the lpszValue buffer is not large enough, the return value is the size, in characters, of the buffer required to hold the value string including the terminating null character.

See Also

GetEnvironmentStrings, SetEnvironmentVariable


GetExceptionCode function
GetExceptionCode (Win32)

DWORD GetExceptionCode(VOID)

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.

Returns

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 tried 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 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_SINGLE_STEP

A trace trap or other single-instruction mechanism signaled that one instruction has been executed.

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_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_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_PRIV_INSTRUCTION

The thread tried to execute an instruction whose operation is not allowed in the current machine mode.

STATUS_NONCONTINUABLE_EXCEPTION

The thread tried to continue execution after a noncontinuable exception occurred.

Comments

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 function
GetExceptionInformation (Win32)

LPEXCEPTION_POINTERS GetExceptionInformation(VOID)

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.

Returns

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.

Comments

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

GetExceptionCode


GetExitCodeProcess function
GetExitCodeProcess (Win32)

BOOL GetExitCodeProcess(hProcess, lpdwExitCode)

HANDLE hProcess;	/* handle to the process	*/
LPDWORD lpdwExitCode;	/* address to receive termination status	*/

The GetExitCodeProcess function retrieves the termination status of the specified process.

Parameter	Description

hProcess	Identifies the process. The handle must have PROCESS_QUERY_INFORMATION access.

lpdwExitCode	Points to a 32-bit variable to receive the process termination status.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 code specified in the ExitProcess or TerminateProcess function.

The return value from the process's main or WinMain function.

The exception code for an unhandled exception that caused the process to terminate.

See Also

ExitProcess, ExitThread, TerminateProcess


GetExitCodeThread function
GetExitCodeThread (Win32)

BOOL GetExitCodeThread(hThread, lpdwExitCode)

HANDLE hThread;	/* handle to the thread	*/
LPDWORD lpdwExitCode;	/* address to receive termination status	*/

The GetExitCodeThread function retrieves the termination status of the specified thread.

Parameter	Description

hThread	Identifies the thread. The handle must have THREAD_QUERY_INFORMATION access.

lpdwExitCode	Points to a 32-bit variable to receive the thread termination status.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 code specified in the ExitThread or TerminateThread function.

The return value from the thread function.

The exit code of the thread's process.

See Also

GetExitCodeProcess, ExitThread, TerminateThread


GetFileAttributes function
GetFileAttributes (Win32)

DWORD GetFileAttributes(lpszFileName)

LPCTSTR lpszFileName;	/* address of the name of the file	*/

The GetFileAttributes function returns attributes for the specified file.

Parameter	Description

lpszFileName	Points to a null-terminated string that specifies the name of the file.

Returns

If the function succeeds, the return value contains the attributes of the specified file; otherwise, it is 0xFFFFFFFF. To get extended error information, use the GetLastError function.

The attributes can be one or more of the following values:

Value	Meaning

FILE_ATTRIBUTE_ARCHIVE

The file is an archive file. Applications use this flag to mark files for backup or removal.

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 attribute is valid only if used alone.

FILE_ATTRIBUTE_READONLY

The file is a read-only file. 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 a temporary file. Applications can 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.

FILE_ATTRIBUTE_ATOMIC_WRITE

Reserved for future use. Do not specify.

FILE_ATTRIBUTE_XACTION_WRITE

Reserved for future use. Do not specify.

See Also

FindFirstFile, FindNextFile, SetFileAttributes


GetFileInformationByHandle function
GetFileInformationByHandle (Win32)

BOOL GetFileInformationByHandle(hFile, lpFileInformation)

HANDLE hFile;	/* handle of file	*/
LPBY_HANDLE_FILE_INFORMATION lpFileInformation;	/* address of structure	*/

The GetFileInformationByHandle function retrieves information about the specified file.

Parameter	Description

hFile	Identifies the file to return information about.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

BY_HANDLE_FILE_INFORMATION


GetFileSize function
GetFileSize (Win32)

DWORD GetFileSize(hFile, lpdwFileSizeHigh)

HANDLE hFile;	/* handle of file to get size of	*/
LPDWORD lpdwFileSizeHigh;	/* address of high-order word for file size	*/

The GetFileSize function retrieves the size, in bytes, of the specified file.

Parameter	Description

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.

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

Returns

If the function succeeds, the return value is the low-order doubleword of the file size, and, if lpdwFileSizeHigh is non-NULL, the function puts the high-order doubleword of the file size into the LONG pointed to by that parameter.

If the function fails, and lpdwFileSizeHigh is NULL, the return value is 0xFFFFFFFF. Call GetLastError for extended error information.

If the function fails, and lpdwFileSizeHigh is non-NULL, the return value is 0xFFFFFFFF and GetLastError will return a value other than NO_ERROR.

Comments

Using the GetFileSize function with a handle of a nonseeking device such as a pipe or a communications device has no meaning. Use the GetFileType function to determine the file type for hFile.

Note that, if the return value is 0xFFFFFFFF and lpdwFileSizeHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed. Here is some sample code that illustrates the point:

//

// Case One: calling the function with

//           lpdwFileSizeHigh == 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

//           lpdwFileSizeHigh != 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

GetFileType


GetFileTime function
GetFileTime (Win32)

BOOL GetFileTime(hFile, lpftCreation, lpftLastAccess, lpftLastWrite)

HANDLE hFile;	/* identifies the file	*/
LPFILETIME lpftCreation;	/* address of creation time	*/
LPFILETIME lpftLastAccess;	/* address of last access time	*/
LPFILETIME lpftLastWrite;	/* address of last write time	*/

The GetFileTime function retrieves the date and time that a file was created, last accessed, and last modified.

Parameter	Description

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.

lpftCreation	Points to a FILETIME structure to receive the date and time the file was created. The file allocation table (FAT) file system does not record this time. This parameter can be NULL if the application does not require this information.

lpftLastAccess	Points to a FILETIME structure to receive the date and time the file was last accessed. The FAT file system does not record this time. 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.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The FAT file system does not record the creation or last access times, but both the high-performance file system (HPFS) and the New Technology file system (NTFS) do.

See Also

GetFileSize, GetFileType, SetFileTime


GetFileType function
GetFileType (Win32)

DWORD GetFileType(hFile)

HANDLE hFile;	/* file handle	*/

The GetFileType function returns the type of the specified file.

Parameter	Description

hFile	Identifies an open file handle.

Returns

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


GetFullPathName function
GetFullPathName (Win32)

DWORD GetFullPathName(lpszFile, cchPath, lpszPath, ppszFilePart)

LPCTSTR lpszFile;	/* address of name of file to find path for	*/
DWORD cchPath;	/* size, in characters, of path buffer	*/
LPTSTR lpszPath;	/* address of path buffer	*/
LPTSTR *ppszFilePart;	/* address of filename in path	*/

The GetFullPathName function retrieves the full path and filename of a specified file.

Parameter	Description

lpszFile	Points to a null-terminated string that specifies a valid filename.

cchPath	Specifies the size, in characters, of the buffer for the drive and path.

lpszPath	Points to a buffer that contains the null-terminated name of the drive and path.

ppszFilePart	Points to a variable that receives the address (in lpszPath) of the final component in the path.

Returns

If the GetFullPathName function succeeds, the return value is the length, in characters, of the string copied to lpszPath, not including the terminating null character.

If the lpszPath 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. Use the GetLastError function to get extended error information.

Comments

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

GetTempPath, SearchPath


GetLargestConsoleWindowSize function
GetLargestConsoleWindowSize (Win32)

COORD GetLargestConsoleWindowSize(hConsoleOutput)

HANDLE hConsoleOutput;	/* handle of console screen buffer	*/

The GetLargestConsoleWindowSize function returns the size of the largest possible console window, based on the current font and the size of the display.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer.

Returns

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, use the GetLastError function.

Comments

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

GetConsoleScreenBufferInfo, SetConsoleWindowInfo


GetLastError function
GetLastError (Win32)

DWORD GetLastError(VOID)

The GetLastError function returns the last-error code.

Returns

The return value is the most recent last-error code code set by the SetLastError function. (Most of the functions in the Win32 API call SetLastError when they fail.)

Comments

An application should call this function immediately after a function call fails (typically indicated by returning FALSE, NULL, 0xFFFFFFFF, or -1) to determine the cause of the failure.

Win32 API functions that return indications of failure call SetLastError when they fail. With one exception, they do NOT call SetLastError when they succeed. So, if three Win32 API function calls are made, and the first one fails and the second two succeed, the error code stored by the first one is still available after the second two succeed. The exception to this no-write-on-success rule is the TlsGetValue function, which needs to clear the last error code when it succeeds to allow checking the error-free retrieval of NULL values.

The last-error code value is maintained on a per-thread basis, so multiple threads do not overwrite each other's last-error code value.

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 an application and to ensure that your error code does not conflict with any system-defined error codes.

See Also

SetLastError, SetLastErrorEx


GetLocalTime function
GetLocalTime (Win32)

VOID GetLocalTime(lpst)

LPSYSTEMTIME lpst;	/* address of system time structure	*/

The GetLocalTime function retrieves the current local date and time.

Parameter	Description

lpst	Points to a SYSTEMTIME structure to receive the current local date and time.

Returns

This function does not return a value.

See Also

GetSystemTime, SetLocalTime


GetLogicalDrives function
GetLogicalDrives (Win32)

DWORD GetLogicalDrives(void)

The GetLogicalDrives function returns a bitmask representing the currently available disk drives.

Returns

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 function
GetLogicalDriveStrings (Win32)

DWORD GetLogicalDriveStrings(cchBuffer, lpszBuffer)

DWORD cchBuffer;	/* size of the buffer	*/
LPTSTR lpszBuffer;	/* address of the buffer for drive strings	*/

The GetLogicalDriveStrings function fills a buffer with strings that specify valid drives in the system.

Parameter	Description

cchBuffer	Specifies the maximum size, in characters, of the buffer pointed to by lpszBuffer. This size does not include the terminating null character.

lpszBuffer	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 null terminator.

        c:\<null>d:\<null><null>

Returns

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

Comments

Each string in the buffer may be used wherever a root directory is required, such as with the GetDriveType and GetDiskFreeSpace functions.

See Also

GetLogicalDrives


GetMailslotInfo function
GetMailslotInfo (Win32)

BOOL GetMailslotInfo(hMailslot, lpcbMaxMsg, lpcbNextMsg, lpcMsg, lpdwReadTimeout)

HANDLE hMailslot;	/* mailslot handle	*/
LPDWORD lpcbMaxMsg;	/* address of maximum message size	*/
LPDWORD lpcbNextMsg;	/* address of size of next message	*/
LPDWORD lpcMsg;	/* address of number of messages	*/
LPDWORD lpdwReadTimeout;	/* address of read time-out	*/

The GetMailslotInfo function retrieves information about the given mailslot.

Parameter	Description

hMailslot	Identifies a mailslot. The CreateMailslot function must create this handle.

lpcbMaxMsg	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. An application can set this parameter to NULL.

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

An application can set this parameter to NULL.

lpcMsg	Points to a buffer specifying the total number of messages waiting to be read, when the function returns. An application can set this parameter to NULL.

lpdwReadTimeout	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. An application can set this parameter to NULL.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CreateMailslot, SetMailslotInfo


GetModuleFileName function
GetModuleFileName (Win32)

DWORD GetModuleFileName(hinstModule, lpszPath, cchPath)

HMODULE hinstModule;	/* handle of module to find filename for	*/
LPTSTR lpszPath;	/* address of buffer for module path	*/
DWORD cchPath;	/* size of buffer in characters	*/

The GetModuleFileName function retrieves the full path and filename for the executable file containing the given module.

Parameter	Description

hinstModule	Identifies the module whose executable filename is being requested. If the parameter is NULL, GetModuleFileName returns the path for the file used to create the calling process.

lpszPath	Points to a buffer that is filled in with the path and filename of the given module.

cchPath	Specifies the length, in characters, of the lpszPath buffer. If the length of the path and filename exceeds this limit, the string is truncated.

Returns

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer; otherwise, it is zero. To get extended error information, use the GetLastError function.

See Also

GetModuleHandle, LoadLibrary


GetModuleHandle function
GetModuleHandle (Win32)

HMODULE GetModuleHandle(lpszModule)

LPCTSTR lpszModule;	/* address of module name to return handle for	*/

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.

Parameter	Description

lpszModule	Points to a null-terminated string that names a Win32 module (.DLL or .EXE). If the file extension is omitted, the default library file extension .DLL is appended. The filename string can include a trailing point character (.) to indicate that the module name has no extension. The string need not specify a path. The name is compared (case independently) to the names of modules currently mapped into the calling process.

If this parameter is NULL, GetModuleHandle returns a handle of the file used to create the calling process.

Returns

If the function succeeds, the return value is a handle to the specified module; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The returned handle is not global, inheritable, or duplicatable, and cannot be used by another process.

The handles returned by GetModuleHandle and LoadLibrary can be used in the same functions, such as GetProcAddress, FreeLibrary, or LoadResource. The difference between the two functions is that LoadLibrary maps the module into the address space of the calling process, if necessary. If it is already mapped, LoadLibrary increments the module's reference count. GetModuleHandle 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. It 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, another thread in the same process could free the module and another module could be loaded and given the same module handle, causing the one returned by GetModuleHandle to refer to a module other than the one intended.

See Also

FreeLibrary, GetModuleFileName, GetProcAddress, LoadLibrary, LoadResource


GetNamedPipeHandleState function
GetNamedPipeHandleState (Win32)

BOOL GetNamedPipeHandleState(hNamedPipe, lpdwState, lpdwCurInstances, lpcbMaxCollect, lpdwCollectTimeout, lpszUser, cchMaxUser)

HANDLE hNamedPipe;	/* handle of named pipe	*/
LPDWORD lpdwState;	/* address of flags indicating pipe state	*/
LPDWORD lpdwCurInstances;	/* address of number of current pipe instances	*/
LPDWORD lpcbMaxCollect;	/* address of max bytes before remote transmission	*/
LPDWORD lpdwCollectTimeout;	/* address of max time before remote transmission	*/
LPTSTR lpszUser;	/* address of user name of client process	*/
DWORD cchMaxUser;	/* size in characters of user name buffer	*/

The GetNamedPipeHandleState function retrieves information about the given named pipe. The information returned can vary during the lifetime of an instance of a named pipe.

Parameter	Description

hNamedPipe	Identifies the named pipe about which you want information. The handle must have GENERIC_READ access to the named pipe.

lpdwState	Points to a 32-bit variable that receives flags indicating the current state of the handle. Set the parameter to NULL if the information is not needed. Either or both of the following flags can be set:

Value	Meaning

PIPE_NOWAIT	The pipe handle is in nonblocking mode. If this flag is not set, the pipe handle is in blocking mode.

PIPE_READMODE_MESSAGE	The pipe handle is in message-read mode. If this flag is not set, the pipe handle is in byte-read mode.

lpdwCurInstances	Points to a 32-bit variable that will receive the number of current pipe instances. Set this parameter to NULL if the information is not required.

lpcbMaxCollect	Points to a 32-bit variable that will receive 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. Set this parameter to NULL if the information is not required.

lpdwCollectTimeout	Points to a 32-bit variable that will receive 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. Set this parameter to NULL if the information is not required.

lpszUser	Points to a buffer that will receive the null-terminated string containing the username string of the client application. This parameter must be NULL if the specified pipe handle is to the client end of a named pipe. Set this parameter to NULL if the information is not required.

cchMaxUser	Specifies the size, in characters, of the lpszUser buffer. This parameter is ignored if lpszUser is NULL.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
GetNamedPipeInfo (Win32)

BOOL GetNamedPipeInfo(hNamedPipe, lpdwType, lpcbOutBuf, lpcbInBuf, lpcMaxInstances)

HANDLE hNamedPipe;	/* handle of named pipe	*/
LPDWORD lpdwType;	/* address of flags indicating type of pipe	*/
LPDWORD lpcbOutBuf;	/* address of size in bytes of pipe's output buffer	*/
LPDWORD lpcbInBuf;	/* address of size in bytes of pipe's input buffer	*/
LPDWORD lpcMaxInstances;	/* address of max number of pipe instances	*/

The GetNamedPipeInfo function retrieves information about the given named pipe.

Parameter	Description

hNamedPipe	Identifies the named pipe instance. The handle must have GENERIC_READ access to the named pipe.

lpdwType	Points to a 32-bit variable that will receive flags indicating the type of the named pipe and whether the handle is to the server or client end of the pipe. Set this parameter to NULL if this information is not required. Either or both of the following flags can be set:

Value	Meaning

PIPE_SERVER_END

The handle refers to the server end of a named pipe instance. If this flag is not set, the handle refers to the client end of a named pipe instance.

PIPE_TYPE_MESSAGE

The named pipe is a message-type pipe. If this flag is not set, the pipe is a byte-type pipe.

lpcbOutBuf	Points to a 32-bit variable that will receive the size, in bytes, of the buffer for outgoing data. If the buffer size is zero, the buffer is allocated as needed. Set this parameter to NULL if this information is not required.

lpcbInBuf	Points to a 32-bit variable that will receive the size, in bytes, of the buffer for incoming data. If the buffer size is zero, the buffer is allocated as needed. Set this parameter to NULL if this information is not required.

lpcMaxInstances	Points to a 32-bit variable that will receive 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. Set this parameter to NULL if this information is not required.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CreateNamedPipe, GetNamedPipeHandleState


GetNumberOfConsoleInputEvents function
GetNumberOfConsoleInputEvents (Win32)

BOOL GetNumberOfConsoleInputEvents(hConsoleInput, lpcNumberOfEvents)

HANDLE hConsoleInput;	/* handle of console input buffer	*/
LPDWORD lpcNumberOfEvents;	/* address for number of events	*/

The GetNumberOfConsoleInputEvents function retrieves the number of unread input records in the console's input buffer.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 (that is, the WaitForSingleObject or WaitForMultipleObjects function) 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, WaitForMultipleObjects, WaitForSingleObject


GetNumberOfConsoleMouseButtons function
GetNumberOfConsoleMouseButtons (Win32)

BOOL GetNumberOfConsoleMouseButtons(lpcMouseButtons)

LPDWORD lpcMouseButtons;	/* number of buttons	*/

The GetNumberOfConsoleMouseButtons function retrieves the number of buttons on the mouse used by the current console.

Parameter	Description

lpcMouseButtons	Points to a 32-bit variable that receives the number of mouse buttons.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
GetNumberOfEventLogRecords (Win32)

BOOL GetNumberOfEventLogRecords(hEventLog, pcRecords)

HANDLE hEventLog;	/* handle to event log	*/
PDWORD pcRecords;	/* buffer for number of records	*/

The GetNumberOfEventLogRecords function retrieves the number of records in the given event log.

Parameter	Description

hEventLog	Identifies the open event log. This handle is returned by the OpenEventLog or OpenBackupEventLog function.

pcRecords	Points to a variable that receives the number of records in the given event log.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetOldestEventLogRecord


GetOldestEventLogRecord function
GetOldestEventLogRecord (Win32)

BOOL GetOldestEventLogRecord(hEventLog, pdwOldestRecord)

HANDLE hEventLog;	/* handle to event log	*/
PDWORD pdwOldestRecord;	/* buffer for number of oldest record	*/

The GetOldestEventLogRecord function retrieves the absolute record number of the oldest record in the given event log.

Parameter	Description

hEventLog	Identifies the open event log. This handle is returned by the OpenEventLog or OpenBackupEventLog function.

pdwOldestRecord	Points to the variable that receives the absolute record number of the oldest record in the given event log.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetNumberOfEventLogRecords


GetOverlappedResult function
GetOverlappedResult (Win32)

BOOL GetOverlappedResult(hFile, lpoOverlapped, lpcbTransfer, fWait)

HANDLE hFile;	/* handle of file, pipe, or comm. device	*/
LPOVERLAPPED lpoOverlapped;	/* address of overlapped structure	*/
LPDWORD lpcbTransfer;	/* address of actual bytes count	*/
BOOL fWait;	/* wait flag	*/

The GetOverlappedResult function returns the results of an overlapped operation on the specified file, named pipe, or communications device.

Parameter	Description

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.

lpoOverlapped	Points to an OVERLAPPED structure that was specified when the overlapped operation was started.

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 input and output (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 fWait 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 fWait parameter set to TRUE causes the function to be blocked indefinitely.

See Also

ConnectNamedPipe, CreateEvent, DeviceIoControl, GetLastError, ReadFile, TransactNamedPipe, WaitCommEvent, WriteFile


GetPriorityClass function
GetPriorityClass (Win32)

DWORD GetPriorityClass(hProcess)

HANDLE hProcess;	/* handle to the process	*/

The GetPriorityClass function returns the priority class for the given process. This value together with the priority value of each thread of the process determines each thread's base priority level.

Parameter	Description

hProcess	Identifies the process. The handle must have PROCESS_QUERY_INFORMATION access.

Returns

If the function succeeds, the return value is the priority class of the specified process; otherwise, it is zero. To get extended error information, use the GetLastError function.

The process's priority class is one of the following values:

Priority	Meaning

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.

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.

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.

Comments

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

SetPriorityClass, GetThreadPriority, SetThreadPriority


GetPrivateProfileInt function
GetPrivateProfileInt (Win32)

UINT GetPrivateProfileInt(lpszSection, lpszKey, dwDefault, lpszFile)

LPCTSTR lpszSection;	/* address of section name	*/
LPCTSTR lpszKey;	/* address of key name	*/
INT dwDefault;	/* return value if key name is not found	*/
LPCTSTR lpszFile;	/* address of initialization filename	*/

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. New applications should store initialization information in the registry.

Parameter	Description

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

dwDefault	Specifies the default value to return if the key name cannot be found in the initialization file.

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

Returns

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.

Comments

The function searches the file for a key that matches the name specified by the lpszKey parameter under the section name specified by the lpszSection 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 lpszSection and lpszKey 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.

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.

See Also

GetProfileInt, WritePrivateProfileString


GetPrivateProfileSection function
GetPrivateProfileSection (Win32)

DWORD GetPrivateProfileSection(lpszSection, lpszReturnBuffer, cchBuffer, lpszFile)

LPCTSTR lpszSection;	/* address of section name	*/
LPTSTR lpszReturnBuffer;	/* address of return buffer	*/
DWORD cchBuffer;	/* size of return buffer	*/
LPCTSTR lpszFile;	/* address of initialization filename	*/

The GetPrivateProfileSection function retrieves all of the keys and values for the specified section from the given initialization file. This function is provided for compatibility with 16-bit applications written for Windows. New applications should store initialization information in the registry.

Parameter	Description

lpszSection	Points to a null-terminated string containing the section name in the initialization file.

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

cchBuffer	Specifies the size, in characters, of the buffer pointed to by the lpszReturnBuffer parameter.

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

Returns

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 cchBuffer minus two.

Comments

The data in the buffer pointed to by the lpszReturnBuffer 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 lpszSection 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 lpszReturnBuffer parameter.

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.

See Also

GetProfileSection, WritePrivateProfileSection,


GetPrivateProfileString function
GetPrivateProfileString (Win32)

DWORD GetPrivateProfileString(lpszSection, lpszKey, lpszDefault, lpszReturnBuffer, cchReturnBuffer, lpszFile)

LPCTSTR lpszSection;	/* address of section name	*/
LPCTSTR lpszKey;	/* address of key name	*/
LPCTSTR lpszDefault;	/* address of default string	*/
LPTSTR lpszReturnBuffer;	/* address of destination buffer	*/
DWORD cchReturnBuffer;	/* size of destination buffer	*/
LPCTSTR lpszFile;	/* address of initialization filename	*/

The GetPrivateProfileString function retrieves a string from the specified section in the given initialization file. This function is provided for compatibility with 16-bit Windows-based applications. New applications should store initialization information in the registry.

Parameter	Description

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

lpszKey	Points 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 lpszSection parameter are copied to the buffer specified by the lpszReturnBuffer parameter.

lpszDefault	Points to a null-terminated string that specifies the default value for the given key if the key cannot be found in the initialization file. This parameter cannot be NULL.

lpszReturnBuffer	Points to the buffer that receives the retrieved string.

cchReturnBuffer	Specifies the size, in characters, of the buffer pointed to by the lpszReturnBuffer parameter.

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

Returns

If the function succeeds, the return value is the number of characters copied to the buffer, not including the terminating null character.

If neither lpszSection nor lpszKey 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 cchReturnBuffer minus one.

If either lpszSection or lpszKey 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 cchReturnBuffer minus two.

Comments

The GetPrivateProfileString function searches the specified initialization file for a key that matches the name specified by the lpszKey parameter under the section heading specified by the lpszSection 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 lpszDefault parameter. A section in the initialization file must have the following form:

[section]

key=string

      .

      .

      .

If lpszSection is NULL, GetPrivateProfileString copies all section names in the specified file to the supplied buffer. If lpszKey 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 lpszKey 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.

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.

See Also

GetProfileString, WritePrivateProfileString


GetProcAddress function
GetProcAddress (Win32)

FARPROC GetProcAddress(hModule, lpszProc)

HMODULE hModule;	/* handle to DLL module	*/
LPCSTR lpszProc;	/* name of function	*/

The GetProcAddress function returns the address of the specified exported dynamic-link library (DLL) function.

Parameter	Description

hModule	Identifies the DLL module that contains the function. The LoadLibrary or GetModuleHandle function return this handle.

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

Returns

If the function succeeds, the return value is the address of the function's entrypoint; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

Use the GetProcAddress function to retrieve addresses of exported functions in DLLs.

The spelling and case of the function name pointed to by lpszProc must be identical to that in the EXPORTS statement of the source DLL's module-definition file.

The lpszProc 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 module-definition file. The function then uses the ordinal as an index to read the function's address from a function table. If the module-definition 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, specify the function by name rather than by ordinal value.

See Also

LoadLibrary, FreeLibrary, GetModuleHandle


GetProcessHeap function
GetProcessHeap (Win32)

HANDLE GetProcessHeap (VOID)

The GetProcessHeap function obtains a handle to the calling process' heap. This handle can then be used in calls to the HeapAlloc, HeapReAlloc, HeapFree, and HeapSize functions.

Returns

If the function succeeds, the return value is a handle to the calling process' heap.

If the function fails, the return value is NULL.

Comments

The GetProcessHeap function allows Win32 programs to allocate memory from the process heap without having to first create a heap with the HeapCreate function. Here is an example of such a call:

        HeapAlloc( GetProcessHeap(), 0, dwBytes );

Note that the handle obtained by calling this function should not be used in calls to the HeapDestroy function.

Also, 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

HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, HeapSize


GetProcessShutdownParameters function
GetProcessShutdownParameters (Win32)

BOOL GetProcessShutdownParameters(lpdwLevel, lpdwFlags)

LPDWORD lpdwLevel;
LPDWORD lpdwFlags;

The GetProcessShutdownParameters function retrieves shutdown parameters for the currently calling process. For the parameter descriptions, see the SetProcessShutdownParmeters function.

Parameter	Description

lpdwLevel	Points to a variable that receives the shutdown level. Higher levels shutdown first. System level shutdown orders are reserved for system components. Higher numbers shutdown 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. The flags can be added together:

Value	Meaning

SHUTDOWN_NORETRY	If this process takes longer than the specified timeout to shutdown, do not put up a retry dialog for the user. Instead, just cause the process to directly exit.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

SetProcessShutdownParameters


GetProcessTimes function
GetProcessTimes (Win32)

BOOL GetProcessTimes(hProcess, lpCreationTime, lpExitTime, lpKernelTime, lpUserTime)

HANDLE hProcess;	/* specifies the process of interest	*/
LPFILETIME lpCreationTime;	/* when the process was born	*/
LPFILETIME lpExitTime;	/* when the process died	*/
LPFILETIME lpKernelTime;	/* time the process has spent in kernel-mode	*/
LPFILETIME lpUserTime;	/* time the process has spent in user-mode	*/

The GetProcessTimes function obtains timing information about a specified process.

Parameter	Description

hProcess	An open handle that specifies the process whose timing information is sought. This handle must be created with PROCESS_QUERY_INFORMATION access.

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 contents of this structure are 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 process' threads 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 process' threads has executed in user-mode is determined, and then all of those times are summed together to obtain this value.

Returns

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. Call GetLastError for extended error information.

Comments

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. Windows NT provides several functions that an application can use to convert such values to more generally useful forms; see Time , and the functions noted in the See Also section below.

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

FileTimeToDosDateTime, FileTimeToSystemTime, FileTimeToLocalFileTime, FILETIME


GetProfileInt function
GetProfileInt (Win32)

UINT GetProfileInt(lpszSection, lpszKey, dwDefault)

LPCTSTR lpszSection;	/* address of section name	*/
LPCTSTR lpszKey;	/* address of key name	*/
INT dwDefault;	/* default value if key name is not found	*/

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. New applications should store initialization information in the registry.

Parameter	Description

lpszSection	Points to a null-terminated string that specifies the section containing the key name.

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

dwDefault	Specifies the default value to return if the key name cannot be found in the initialization file..

Returns

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.

Comments

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.

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.

See Also

GetPrivateProfileInt, WriteProfileString


GetProfileSection function
GetProfileSection (Win32)

DWORD GetProfileSection(lpszSection, lpszReturnBuffer, cchBuffer)

LPCTSTR lpszSection;	/* address of section name	*/
LPTSTR lpszReturnBuffer;	/* address of return buffer	*/
DWORD cchBuffer;	/* size of return buffer	*/

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. New applications should store initialization information in the registry.

Parameter	Description

lpszSection	Points to a null-terminated string containing the section name in the WIN.INI file.

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

cchBuffer	Specifies the size, in characters, of the buffer pointed to by the lpszReturnBuffer parameter.

Returns

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 cchBuffer minus two.

Comments

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.

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.

See Also

GetPrivateProfileSection, WriteProfileSection


GetProfileString function
GetProfileString (Win32)

DWORD GetProfileString(lpszSection, lpszKey, lpszDefault, lpszReturnBuffer, cchReturnBuffer)

LPCTSTR lpszSection;	/* address of section name	*/
LPCTSTR lpszKey;	/* address of key name	*/
LPCTSTR lpszDefault;	/* address of default string	*/
LPTSTR lpszReturnBuffer;	/* address of destination buffer	*/
DWORD cchReturnBuffer;	/* size of destination buffer	*/

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. New applications should store initialization information in the registry.

Parameter	Description

lpszSection	Points 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.

lpszKey	Points 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.

lpszDefault	Points to the default value for the given key if the key cannot be found in the initialization file. This parameter cannot be NULL.

lpszReturnBuffer	Points to a buffer that receives the character string.

cchReturnBuffer	Specifies the size, in characters, of the buffer pointed to by the lpszReturnBuffer parameter.

Returns

If the function succeeds, the return value is the number of characters copied to the buffer, not including the null-terminating character.

If neither lpszSection nor lpszKey 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 cchReturnBuffer minus one.

If either lpszSection or lpszKey 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 cchReturnBuffer minus two.

Comments

If the string associated with the lpszKey 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 lpszDefault parameter must point to a valid string, even if the string is empty (that is, even if its first character is a null character).

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.

See Also

GetPrivateProfileString, WriteProfileString


GetStartupInfo function
GetStartupInfo (Win32)

VOID GetStartupInfo(lpsi)

LPSTARTUPINFO lpsi;	/* address of STARTUPINFO structure	*/

The GetStartupInfo function retrieves the contents of the STARTUPINFO structure that was specified when the calling process was created.

Parameter	Description

lpsi	Points to a STARTUPINFO structure that is filled in by the function.

Returns

This function does not return a value.

Comments

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 function
GetStdHandle (Win32)

HANDLE GetStdHandle(fdwDevice)

DWORD fdwDevice;	/* input, output, or error device	*/

The GetStdHandle function returns a handle for the standard input, standard output, or standard error device.

Parameter	Description

fdwDevice	Specifies the device to return the handle for. 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

Returns

If the function succeeds, the return value is a handle of the specified device; otherwise, it is the INVALID_HANDLE_VALUE flag. To get extended error information, use the GetLastError function.

Comments

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 or WriteFile function, or any of the console functions that access the console input buffer or a screen buffer (for example, the ReadConsoleInput, WriteConsole, or GetConsoleScreenBufferInfo function).

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 have been redirected by a call to SetStdHandle, in which case GetStdHandle returns the redirected handle. If the standard handles have been redirected, you can specify "CONIN$" in a call to the CreateFile function to get a handle of a console's input buffer. Similarly, you can specify "CONOUT$" to get a handle of a console's active screen buffer.

See Also

SetStdHandle


GetSystemDirectory function
GetSystemDirectory (Win32)

UINT GetSystemDirectory(lpszSysPath, cchSysPath)

LPTSTR lpszSysPath;	/* address of buffer for system directory	*/
UINT cchSysPath;	/* size of directory buffer	*/

The GetSystemDirectory function retrieves the path of the Windows system directory. The system directory contains such files as Windows libraries, drivers, and font files.

Parameter	Description

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

cchSysPath	Specifies the maximum size of the buffer, in characters. This value should be set to at least MAX_PATH.

Returns

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, use the GetLastError function.

Comments

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 function
GetSystemInfo (Win32)

VOID GetSystemInfo(lpSystemInfo)

LPSYSTEM_INFO lpSystemInfo;	/* address of system info. structure	*/

The GetSystemInfo function returns information about the current system.

Parameter	Description

lpSystemInfo	Points to a SYSTEM_INFO structure to be filled in by this function.

Returns

This function does not return a value.


GetSystemTime function
GetSystemTime (Win32)

VOID GetSystemTime(lpst)

LPSYSTEMTIME lpst;	/* address of system time structure	*/

The GetSystemTime function retrieves the current system date and time. The system time is expressed in the Universal Time Convention (UTC).

Parameter	Description

lpst	Points to a SYSTEMTIME structure to receive the current system date and time.

Returns

This function does not return a value.

See Also

GetLocalTime, SetSystemTime


GetTapeParameters function
GetTapeParameters (Win32)

DWORD GetTapeParameters(hDevice, dwOperation, lpdwSize, lpTapeInformation)

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

The GetTapeParameters function retrieves information that describes the tape or the tape drive.

Parameter	Description

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

Returns

If the function succeeds, the return value is NO_ERROR. Otherwise, it can be 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.

Comments

The block size range values (maximum and minimum) returned by the GetTapeParameters function called with dwOperation set to GET_TAPE_DRIVE_INFORMATION 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 a GetTapeParameters GET_TAPE_DRIVE_INFORMATION call.

See Also

SetTapeParameters


GetTapePosition function
GetTapePosition (Win32)

DWORD GetTapePosition(hDevice, dwPositionType, lpdwPartition, lpdwOffsetLow, lpdwOffsetHigh)

HANDLE hDevice;	/* handle of open device	*/
DWORD dwPositionType;	/* type of address to obtain	*/
LPDWORD lpdwPartition;	/* current tape partition	*/
LPDWORD lpdwOffsetLow;	/* low-order 32 bits of tape position	*/
LPDWORD lpdwOffsetHigh;	/* high-order 32 bits of tape position	*/

The GetTapePosition function retrieves the current address of the tape, in logical or absolute blocks.

Parameter	Description

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 32-bits are not required.

Returns

If the function succeeds, the return value is NO_ERROR; otherwise, it 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.

Comments

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

GetTapeParameters, SetTapePosition


GetTapeStatus function
GetTapeStatus (Win32)

DWORD GetTapeStatus(hDevice)

HANDLE hDevice;	/* handle of open device	*/

The GetTapeStatus function indicates whether the tape device is ready to process tape commands.

Parameter	Description

hDevice	Identifies the device for which to get the device status. This handle is created by using the CreateFile function.

Returns

If the tape device is ready to accept appropriate tape-access commands without returning errors, the return value is NO_ERROR; otherwise, it 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.


GetTempFileName function
GetTempFileName (Win32)

UINT GetTempFileName(lpszPath, lpszPrefix, uUnique, lpszTempFile)

LPCTSTR lpszPath;	/* address of name of dir. where temp. file is created	*/
LPCTSTR lpszPrefix;	/* address of prefix of temp. filename	*/
UINT uUnique;	/* number used to create temp. filename	*/
LPTSTR lpszTempFile;	/* address buffer that will receive temp. filename	*/

The GetTempFileName function creates a temporary filename of the following form:

path\preuuuu.tmp

The following table describes the filename syntax:

Component	Meaning

path	The path specified by the lpszPath parameter

pre	The first three letters of the lpszPrefix string

uuuu	The hexadecimal value of uUnique

Parameter	Description

lpszPath	Points to a null-terminated string that specifies the path where the function creates the temporary 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.

lpszPrefix	Points to a null-terminated string that will be used as the temporary filename prefix. This string must consist of characters in the ANSI character set.

uUnique	Specifies an unsigned integer used in creating the temporary filename. If this parameter is nonzero, it is appended to the temporary filename. If this parameter is zero, Windows uses the current system time to create a number to append to the filename.

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

Returns

The return value specifies a unique numeric value used in the temporary filename. If the uUnique parameter is nonzero, the return value specifies this same number.

If the function fails, the return value is zero. To get extended error information, use the GetLastError function.

Comments

When Windows shuts down, temporary files whose name has 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 the 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. This 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 function
GetTempPath (Win32)

DWORD GetTempPath(cchBuffer, lpszTempPath)

DWORD cchBuffer;	/* size, in characters, of the buffer	*/
LPTSTR lpszTempPath;	/* address of buffer for temp. path name	*/

The GetTempPath function retrieves the path of the directory designated for temporary files.

Parameter	Description

cchBuffer	Specifies the size, in characters, of the string buffer identified by lpszTempPath.

lpszTempPath	Points to a string buffer that receives the null-terminated temporary file path.

Returns

If the function succeeds, the return value is the length, in characters, of the string copied to lpszTempPath, not including the terminating null character. If the return value is greater than cchBuffer, 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, use the GetLastError function.

See Also

GetTempFileName


GetThreadContext function
GetThreadContext (Win32)

BOOL GetThreadContext(hThread, lpContext)

HANDLE hThread;	/* handle of thread with context	*/
LPCONTEXT lpContext;	/* address of context structure	*/

The GetThreadContext function retrieves the context of the specified thread.

Parameter	Description

hThread	Identifies an open handle of a thread whose context is to be retrieved. The handle must have THREAD_GET_CONTEXT access to the thread.

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 machine specific. Two versions of the CONTEXT structure currently exist, one version for x86 processors and another for MIPS™ processors.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

GetThreadContext 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 identified by the hThread handle is typically being debugged, but the function can also operate when it is not being debugged.

See Also

SetThreadContext


GetThreadPriority function
GetThreadPriority (Win32)

int GetThreadPriority(hThread)

HANDLE hThread;	/* handle to thread	*/

The GetThreadPriority function returns the priority value for the given thread. This value together with the priority class of the thread's process determines the thread's base priority level.

Parameter	Description

hThread	Identifies the thread. The handle must have THREAD_QUERY_INFORMATION access.

Returns

If the function succeeds, the return value is the thread's priority level; otherwise, it is THREAD_PRIORITY_ERROR_RETURN. To get extended error information, use the GetLastError function.

The thread's priority level is one of the following values:

Priority	Meaning

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.

Comments

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 reference page for the SetPriorityClass function.

See Also

SetThreadPriority, GetPriorityClass, SetPriorityClass


GetThreadSelectorEntry function
GetThreadSelectorEntry (Win32)

BOOL GetThreadSelectorEntry(hThread, dwSelector, lpSelectorEntry)

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

The GetThreadSelectorEntry function retrieves a descriptor table entry for the specified selector and thread.

Parameter	Description

hThread	Identifies a handle of the thread containing the specified selector. The handle must have THREAD_QUERY_INFORMATION access.

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.

Returns

If the function succeeds, the return value is TRUE. 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 FALSE. To get extended error information, use the GetLastError function.

Comments

This function 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.


GetThreadTimes function
GetThreadTimes (Win32)

BOOL GetThreadTimes(hThread, lpCreationTime, lpExitTime, lpKernelTime, lpUserTime)

HANDLE hThread;	/* specifies the thread of interest	*/
LPFILETIME lpCreationTime;	/* when the thread was born	*/
LPFILETIME lpExitTime;	/* when the thread died	*/
LPFILETIME lpKernelTime;	/* time the thread has spent in kernel-mode	*/
LPFILETIME lpUserTime;	/* time the thread has spent in user-mode	*/

The GetThreadTimes function obtains timing information about a specified thread.

Parameter	Description

hThread	An open handle that specifies the thread whose timing information is sought. This handle must be created with THREAD_QUERY_INFORMATION access.

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 contents of this structure are 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.

Returns

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. Call GetLastError for extended error information.

Comments

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. Windows NT provides several functions that an application can use to convert such values to more generally useful forms; see Time , and the functions noted in the See Also section below.

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

FileTimeToDosDateTime, FileTimeToSystemTime, FileTimeToLocalFileTime, FILETIME


GetTimeZoneInformation function
GetTimeZoneInformation (Win32)

DWORD GetTimeZoneInformation(lptzi)

LPTIME_ZONE_INFORMATION lptzi;	/* address of time-zone settings	*/

The GetTimeZoneInformation function retrieves the current time-zone parameters. These parameters control the translations between Universal Time Convention (UTC) time and local time.

Parameter	Description

lptzi	Points to a TIME_ZONE_INFORMATION structure to receive the current time-zone parameters.

Returns

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 lptzi 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 lptzi parameter.

Otherwise, it is 0xFFFFFFFF. Use the GetLastError function to get extended error information.

Comments

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


GetUserName function
GetUserName (Win32)

BOOL GetUserName(lpBuffer, lpcchBuffer)

LPTSTR lpBuffer;	/* address of name buffer	*/
LPDWORD lpcchBuffer;	/* address of size of name buffer	*/

The GetUserName function retrieves the user name of the current thread. This is the name of the user currently logged onto the system.

Parameter	Description

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.

lpcchBuffer	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 lpcchBuffer points to.

Returns

If the function succeeds, the return value is TRUE, and the variable pointed to by lpcchBuffer 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 FALSE. Use the GetLastError function to obtain extended error information.

Comments

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


GetVersion function
GetVersion (Win32)

DWORD GetVersion(VOID)

The GetVersion function returns the current version number of Windows and information about the operating system platform.

Returns

If the function succeeds, the return value is the major and minor version numbers of Windows and a code specifying the operating system platform. The low word contains the version number of Windows. The high byte specifies the minor version (revision) number, in hexadecimal notation. The low byte specifies the major version number, in hexadecimal notation.

The high word contains the information about the operating system platform. The high bit specifies the platform, as follows:

Value	Platform

0	Windows NT

1	Win32s™ on Windows 3.1

The remaining bits in the high word are reserved for Microsoft internal use.

Comments

This function does not return the current version number of MS-DOS®.


GetVolumeInformation function
GetVolumeInformation (Win32)

BOOL GetVolumeInformation(lpRootPathName, lpVolumeNameBuffer, nVolumeNameSize, lpVolumeSerialNumber, lpMaximumComponentLength, lpFileSystemFlags, lpFileSystemNameBuffer, nFileSystemNameSize)

LPCTSTR lpRootPathName;	/* address of root dir. 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 max. length of filename	*/
LPDWORD lpFileSystemFlags;	/* address of file system flags	*/
LPTSTR lpFileSystemNameBuffer;	/* address of name of file system	*/
DWORD nFileSystemNameSize;	/* length of lpFileSystemNameBuffer	*/

The GetVolumeInformation function returns information about the file system whose root directory is specified.

Parameter	Description

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.

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.

On systems that use the high-performance (HPFS) and New Technology (NTFS) file systems, this function may indicate that individual filename components can be up to 255 characters. However, you cannot create a filename of this length because the CreateFile function has a limit of 255 characters for the combined path and filename.

lpFileSystemFlags	Points to a doubleword that receives flags associated with the specified file system. This parameter can be any combination of the following flags:

Value	Meaning

FS_CASE_IS_PRESERVED

The case of filenames is preserved when the name is placed on disk.

FS_CASE_SENSITIVE

The file system supports case-sensitive filename lookup.

FS_UNICODE_STORED_ON_DISK

The file system supports Unicode in filenames as they appear on disk.

lpFileSystemNameBuffer	Points to a buffer that receives the name of the file system (such as FAT, HPFS, 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.

Returns

If all the requested information is retrieved, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

SetVolumeLabel


GetWindowsDirectory function
GetWindowsDirectory (Win32)

UINT GetWindowsDirectory(lpszWinPath, cchWinPath)

LPTSTR lpszWinPath;	/* address of buffer for Windows directory	*/
UINT cchWinPath;	/* size of directory buffer	*/

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.

Parameter	Description

lpszWinPath	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:\.

cchWinPath	Specifies the maximum size, in characters, of the buffer specified by the lpszWinPath parameter. This value should be set to at least MAX_PATH to allow sufficient room in the buffer for the path.

Returns

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, use the GetLastError function.

Comments

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 %HOMEPATH% directory. The %HOMEPATH% directory will be different for each user if so specified by an administrator via the User Manager adminstrative tool. %HOMEPATH% is an environment variable. The %HOMEPATH% is always set either to the user's home directory, which is guaranteed to be private for each user, or to a default directory (for example, c:\users\default) where the user will have all access.

See Also

GetCurrentDirectory, GetSystemDirectory


GlobalAddAtom function
GlobalAddAtom (Win32)

ATOM GlobalAddAtom(lpszName)

LPCTSTR lpszName;	/* address of string to add	*/

The GlobalAddAtom function adds a character string to the global atom table and returns a unique value (an atom) identifying the string.

Parameter	Description

lpszName	Points to the null-terminated string to be added. 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.

Returns

If the function succeeds, the return value is the newly created atom; otherwise, the return value is zero. To get extended error information, use the GetLastError function.

Comments

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 description of 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 lpszName 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 lpszName is in the range 0x0001 through 0xBFFF, the return value is the low-order word of lpszName.

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 function
GlobalAlloc (Win32)

HGLOBAL GlobalAlloc(fuFlags, cbBytes)

UINT fuFlags;	/* object allocation attributes	*/
DWORD cbBytes;	/* number of bytes to allocate	*/

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.

Parameter	Description

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

Value	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 versions 3.x, this memory is not shared globally. However, this flag is available for compatibility purposes. It may be used by some implementations to enhance the performance of DDE operations and it should, therefore, be set 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 implementations may ignore this flag.

GMEM_LOWER

Ignored. This flag is provided only for compatibility with Windows versions 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 versions 3.x.

GMEM_NOTIFY

Ignored. This flag is provided only for compatibility with Windows versions 3.x.

GMEM_SHARE

Same as the GMEM_DDESHARE flag.

GMEM_ZEROINIT

Initializes memory contents to zero.

cbBytes	Specifies the number of bytes to allocate. If cbBytes is zero and the fuFlags parameter specifies the GMEM_MOVEABLE flag, this function returns a handle to a memory object that is marked as discarded.

Returns

If the function succeeds, the return value is the handle of the newly allocated memory object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

If the heap does not contain sufficient free space to satisfy the request, this function 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 a 16-byte boundary.

GlobalAlloc and LocalAlloc 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


GlobalDeleteAtom function
GlobalDeleteAtom (Win32)

ATOM GlobalDeleteAtom(atm)

ATOM atm;	/* atom to delete	*/

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.

Parameter	Description

atm	Identifies the atom and character string to be deleted.

Returns

If the function succeeds, the return value is zero; otherwise, it is the value of the atm parameter. To get extended error information, use the GetLastError function.

Comments

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 function
GlobalDiscard (Win32)

HGLOBAL GlobalDiscard(hglbMem)

HGLOBAL hglbMem;	/* handle of global memory object	*/

The GlobalDiscard function discards the specified global memory block. The lock count of the memory object must be zero.

Parameter	Description

hglbMem	Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Returns

If the function succeeds, the return value is the handle of the memory object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The GlobalDiscard function discards only global objects that the calling process allocated with the GMEM_DISCARDABLE flag set. 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

GlobalReAlloc


GlobalFindAtom function
GlobalFindAtom (Win32)

ATOM GlobalFindAtom(lpszString)

LPCTSTR lpszString;	/* address of string to find	*/

The GlobalFindAtom function searches the global atom table for the specified character string and retrieves the global atom associated with that string.

Parameter	Description

lpszString	Points to the null-terminated character string to search for.

Returns

If the function succeeds, the return value is the global atom associated with the given string. Otherwise, the return value is zero. To get extended error information, use the GetLastError function.

Comments

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


GlobalFlags function
GlobalFlags (Win32)

UINT GlobalFlags(hglbMem)

HGLOBAL hglbMem;	/* handle of global memory object	*/

The GlobalFlags function returns information about the specified global memory object.

Parameter	Description

hglbMem	Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Returns

If the function succeeds, the return value is a 32-bit value specifying the allocation flags and the lock count for the memory object; otherwise, it is the GMEM_INVALID_HANDLE flag, indicating that the global handle is not valid. To get extended error information, use the GetLastError function.

Comments

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:

Value	Meaning

GMEM_DDESHARE	Memory was allocated for use by the dynamic data exchange (DDE) functions. Unlike Windows versions 3.x, this memory is not shared globally. However, this flag is available for compatibility purposes and may be used by some implementations to enhance the performance of DDE operations. Only processes that use DDE or the clipboard for interprocess communication 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 function
GlobalFree (Win32)

HGLOBAL GlobalFree(hglbMem)

HGLOBAL hglbMem;	/* handle of global memory object	*/

The GlobalFree function frees the specified global memory object and invalidates its handle.

Parameter	Description

hglbMem	Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Returns

If the function succeeds, the return value is NULL; otherwise, it is equal to the handle of the global memory object. To get extended error information, use the GetLastError function.

Comments

If the memory object is locked (that is, if it has a lock count that is greater than zero), the GlobalFree function fails. The GlobalLock function locks a global memory object and increments the lock count. The GlobalUnlock function unlocks it and decrements the lock count. To get the lock count of a global memory object, use the GlobalFlags function.

If the process tries to examine or modify the memory after it has been freed, heap corruption or an access violation exception (EXCEPTION_ACCESS_VIOLATION) may occur.

If the hgblMem parameter is NULL, GlobalFree fails and the system generates an access violation exception.

See Also

GlobalAlloc, GlobalFlags, GlobalLock, GlobalReAlloc, GlobalUnlock


GlobalGetAtomName function
GlobalGetAtomName (Win32)

UINT GlobalGetAtomName(atm, lpszBuffer, cchBuffer)

ATOM atm;	/* atom identifier	*/
LPTSTR lpszBuffer;	/* address of buffer for atom string	*/
int cchBuffer;	/* size of buffer	*/

The GlobalGetAtomName function retrieves a copy of the character string associated with the specified global atom.

Parameter	Description

atm	Identifies the global atom associated with the character string to be retrieved.

lpszBuffer	Points to the buffer for the character string.

cchBuffer	Specifies the size, in characters, of the buffer.

Returns

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. Otherwise, the return value is zero. To get extended error information, use the GetLastError function.

Comments

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 function
GlobalHandle (Win32)

HGLOBAL GlobalHandle(lpvMem)

LPCVOID lpvMem;	/* address of global memory block	*/

The GlobalHandle function retrieves the handle associated with the specified pointer to a global memory block.

Parameter	Description

lpvMem	Points to the first byte of the global memory block. This pointer is returned by the GlobalLock function.

Returns

If the function succeeds, the return value is the handle of the specified global memory object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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 function
GlobalLock (Win32)

LPVOID GlobalLock(hglbMem)

HGLOBAL hglbMem;	/* handle of global memory object	*/

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.

Parameter	Description

hglbMem	Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Returns

If the function succeeds, the return value is a pointer to the first byte of the memory block; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, GlobalLock increments this 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

GlobalFlags, GlobalReAlloc, GlobalUnlock


GlobalMemoryStatus function
GlobalMemoryStatus (Win32)

VOID GlobalMemoryStatus(lpmstMemStat)

LPMEMORYSTATUS lpmstMemStat;	/* address of memory status structure	*/

The GlobalMemoryStatus function retrieves information about current available memory. The function returns information about both physical and virtual memory.

Parameter	Description

lpmstMemStat	Points to a MEMORYSTATUS structure in which the information about current memory availability is returned. Before calling this function, the calling process should set the dwLength member of this structure.

Returns

This function does not return a value.

Comments

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.


GlobalReAlloc function
GlobalReAlloc (Win32)

HGLOBAL GlobalReAlloc(hglbMem, cbBytes, fuFlags)

HGLOBAL hglbMem;	/* handle of global memory object	*/
DWORD cbBytes;	/* new size of block	*/
UINT fuFlags;	/* how to reallocate object	*/

The GlobalReAlloc function changes the size or attributes of a specified global memory object. The size can increase or decrease.

Parameter	Description

hglbMem	Identifies the global memory object to be reallocated. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

cbBytes	Specifies the new size, in bytes, of the memory block. If cbBytes is zero and the fuFlags parameter specifies the GMEM_MOVEABLE flag, this function returns the handle of a memory object that is marked as discarded. If the fuFlags parameter specifies the GMEM_MODIFY flag, this parameter is ignored.

fuFlags	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 cbBytes 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

This flag allocates discardable memory. This flag is used only 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

This flag changes a fixed memory object to a movable memory object, if the GMEM_MODIFY flag is also specified.

If fuFlags does not specify GMEM_MODIFY, the parameter can be any combination of the following flags:

Flag	Meaning

GMEM_MOVEABLE

If cbBytes is zero, this flag 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 cbBytes is nonzero, this flag enables the system to move the reallocated block to a new location. This does not change 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 hglbMem parameter. If the object is movable, the block can be moved without invalidating the handle. This can occur 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

This flag prevents memory from being compacted or discarded to satisfy the allocation request.

GMEM_ZEROINIT

This flag causes the additional memory contents to be initialized to zero, if the memory object is growing in size.

Returns

If the function succeeds, the return value is the handle of the reallocated memory object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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.

See Also

GlobalAlloc, GlobalFree, GlobalLock


GlobalSize function
GlobalSize (Win32)

DWORD GlobalSize(hglbMem)

HGLOBAL hglbMem;	/* handle of global memory object	*/

The GlobalSize function retrieves the current size, in bytes, of the specified global memory object.

Parameter	Description

hglbMem	Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Returns

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, use the GetLastError function.

Comments

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 GlobalFlags function before calling GlobalSize.

See Also

GlobalAlloc, GlobalFlags, GlobalReAlloc


GlobalUnlock function
GlobalUnlock (Win32)

BOOL GlobalUnlock(hglbMem)

HGLOBAL hglbMem;	/* handle of global memory object	*/

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.

Parameter	Description

hglbMem	Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Returns

If the object's lock count was decremented to zero, the return value is FALSE; otherwise, it is TRUE. To get extended error information, use the GetLastError function.

Comments

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, the GlobalLock function increments this 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.

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

GlobalFlags, GlobalLock


HandlerRoutine function
HandlerRoutine (Win32)

BOOL HandlerRoutine(dwCtrlType)

DWORD dwCtrlType;	/*	*/

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.

Parameter	Description

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 selecting "Close" from the console window's system menu, or by selecting "End Task" from the Program Manager's Task List dialog box).

CTRL_LOGOFF_EVENT

A signal that the system sends to all console processes when a user is logging off. This 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.

Returns

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

Comments

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 invoked 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 popup dialog that asks the user whether to terminate the process. The system also displays the dialog if the process does not respond within a timeout 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 from being displayed. In this case, the system just terminates the process when a HandlerRoutine returns TRUE or when the timeout period elapses.

See Also

GenerateConsoleCtrlEvent, GetProcessShutdownParameters, SetConsoleCtrlHandler, SetProcessShutdownParameters


HeapAlloc function
HeapAlloc (Win32)

LPVOID HeapAlloc(hHeap, dwFlags, dwBytes)

HANDLE hHeap;	/* handle of the private heap block	*/
DWORD dwFlags;	/* heap allocation control flags	*/
DWORD dwBytes;	/* number of bytes to allocate	*/

The HeapAlloc function allocates a block of memory from a heap. The allocated memory is not movable.

Parameter	Description

hHeap	Specifies the heap within which the memory shall be allocated. This is a handle returned by the HeapCreate or the 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 the HeapCreate function. You can use one or more of the following values:

Value	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 while this function is accessing the heap. For more information about HEAP_NO_SERIALIZE, see the Comments for the HeapCreate function.

HEAP_ZERO_MEMORY	Specifies that the allocated memory will be initialized to zero.

dwBytes	Specifies the number of bytes to be allocated.

Returns

If the function succeeds, the return value is a pointer to the allocated memory block.

If the function fails, and HEAP_GENERATE_EXCEPTIONS has NOT been set, the return value is NULL.

If the function fails, and HEAP_GENERATE_EXCEPTIONS has been set, the following exception values can be generated :

Value	Meaning

STATUS_NO_MEMORY	The allocation attempt failed for lack of available memory.

STATUS_ACCESS_VIOLATION	The allocation attempt failed because of heap corruption or improper function parameters.

Comments

If the HeapAlloc 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 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

HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, HeapSize


HeapCreate function
HeapCreate (Win32)

HANDLE HeapCreate(flOptions, dwInitialSize, dwMaximumSize)

DWORD flOptions;	/* heap allocation flag	*/
DWORD dwInitialSize;	/* initial heap size	*/
DWORD dwMaximumSize;	/* maximum heap size	*/

The HeapCreate function creates a heap object that is private to the calling process. This reserves a contiguous block of the process's virtual address space and allocates physical storage for a specified initial portion of this block.

Parameter	Description

flOptions	Specifies optional attributes for the new heap. These flags will affect subsequent access to the new heap via calls to the HeapAlloc, HeapFree, HeapReAlloc, and HeapSize functions. You can specify one or more of the following values:

Value	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. Serializing 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	Specifies the maximum size, in bytes, of the heap. This value determines the size of the block in the process's virtual address space that is reserved. The value is rounded up to the next page boundary. If allocation requests made by the HeapAlloc function exceed the initial amount of physical storage specified by the dwInitialSize parameter, additional pages of physical storage are allocated for the heap, up to this maximum limit. If this parameter is zero, the size of the heap is limited by available memory.

Returns

If the function succeeds, the return value is a handle of the newly created heap; otherwise, it is NULL.

Comments

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 the HeapAlloc function 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 invoked 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 from a heap with a maximum size of 64K, the request may fail because of the system overhead.

If the HEAP_NO_SERIALIZE flag is not specified, the simple default, the heap will serialize access within the calling process. This 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 this mutual exclusion on the heap. Lacking 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. Thus, the HEAP_NO_SERIALIZE flag can 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

HeapAlloc, HeapDestroy, HeapFree, HeapReAlloc, HeapSize, GetProcessHeap


HeapDestroy function
HeapDestroy (Win32)

BOOL HeapDestroy(hHeap)

HANDLE hHeap;	/* handle of heap	*/

The HeapDestroy function destroys the specified heap object.

Parameter	Description

hHeap	Specifies the heap to be destroyed. This should be a heap handle returned by the HeapCreate function. Do not use a heap handle returned by the GetProcessHeap function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The HeapDestroy function decommits and releases all the pages of a private heap object, and invalidates the handle of the heap.

Processes can call HeapDestroy without first calling the HeapFree function to free memory allocated from the heap.

See Also

HeapAlloc, HeapCreate, HeapFree, HeapReAlloc, HeapSize, GetProcessHeap


HeapFree function
HeapFree (Win32)

BOOL HeapFree(hHeap, dwFlags, lpMem)

HANDLE hHeap;	/* handle of the heap	*/
DWORD dwFlags;	/* heap freedom flags	*/
LPVOID lpMem;	/* address of the memory to free	*/

The HeapFree function frees a memory block allocated from a heap by the HeapAlloc or HeapReAlloc function.

Parameter	Description

hHeap	Specifies the heap whose block the function frees. This is a handle returned by the HeapCreate or the 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 when the heap was created with the HeapCreate function:

Value	Meaning

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 Comments for the HeapCreate function.

lpMem	Points to the memory block to free. This is a pointer returned by the HeapAlloc function or the HeapReAlloc function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

HeapAlloc, HeapCreate, HeapDestroy, HeapReAlloc, HeapSize, GetProcessHeap


HeapReAlloc function
HeapReAlloc (Win32)

LPVOID HeapReAlloc(hHeap, dwFlags, lpMem, dwBytes)

HANDLE hHeap;	/* handle of a heap block	*/
DWORD dwFlags;	/* flags specifying aspects of reallocation	*/
LPVOID lpMem;	/* address of the memory to reallocate	*/
DWORD dwBytes;	/* number of bytes to reallocate	*/

The HeapReAlloc function re-allocates a block of memory from a heap. The allocated memory is not movable.

Parameter	Description

hHeap	Specifies the heap within which the memory shall be re-allocated. This is a handle returned by the HeapCreate or the GetProcessHeap function.

dwFlags	Specifies several controllable aspects of heap re-allocation. Specifying any of these flags will override the corresponding flag specified when the heap was created with the HeapCreate function. You can use one or more of the following values:

Value	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 while this function is accessing the heap. For more information about HEAP_NO_SERIALIZE, see the Comments for the HeapCreate function.

HEAP_REALLOC_IN_PLACE_ONLY	Specifies that there can be no movement when re-allocating a memory block to a larger size. If this flag is not specified, and the re-allocation request is for a larger size, the HeapReAlloc 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 re-allocation 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 will re-allocate. This pointer is returned by a prior call to the HeapAlloc function or the HeapReAlloc function.

dwBytes	Specifies the new size of the memory block in bytes. A memory block's size may be increased or decreased with this function.

Returns

If the function succeeds, the return value is a pointer to the re-allocated memory block.

If the function fails, and HEAP_GENERATE_EXCEPTIONS has NOT been set, the return value is NULL.

If the function fails, and HEAP_GENERATE_EXCEPTIONS has been set, the following exception values can be generated :

Value	Meaning

STATUS_NO_MEMORY	The re-allocation attempt failed for lack of available memory.

STATUS_ACCESS_VIOLATION	The re-allocation attempt failed because of heap corruption or improper function parameters.

Comments

If the HeapReAlloc 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 size of the re-allocated block, use the HeapSize function.

To free a block of memory allocated by HeapReAlloc, use the HeapFree function.

See Also

HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapSize, GetProcessHeap


HeapSize function
HeapSize (Win32)

DWORD HeapSize(hHeap, dwFlags, lpMem)

HANDLE hHeap;	/* handle of the heap	*/
DWORD dwFlags ;	/* heap size control flags	*/
LPCVOID lpMem;	/* address of memory to return size for	*/

The HeapSize function returns the size, in bytes, of a memory block allocated from a heap by the HeapAlloc or HeapReAlloc function.

Parameter	Description

hHeap	Specifies the heap within which the memory block whose size is desired resides. This is a handle returned by the HeapCreate function or the GetProcessHeap function.

dwFlags	Specifies several controllable aspects of accessing 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 when the heap was created with the HeapCreate function:

Value	Meaning

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 Comments for the HeapCreate function.

lpMem	Points to the memory block whose size the function will obtain. This is a pointer returned by the HeapAlloc function or the HeapReAlloc function.

Returns

If the function succeeds, the return value is the size, in bytes, of the allocated memory block; otherwise, it is zero.

See Also

HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, GetProcessHeap


_hread function
_hread (Win32)

long _hread(hFile, lpBuffer, lBytes)

HFILE hFile;	/* handle of file	*/
LPVOID lpBuffer;	/* address of buffer for read data	*/
long lBytes;	/* length, in bytes, of data buffer	*/

The _hread function reads data from the specified file. This function is provided for compatibility with earlier versions of Windows. For applications written with the Win32 API, use the ReadFile function.

Parameter	Description

hFile	Identifies the specified file.

lpBuffer	Points to a buffer that contains the data read from the file.

lBytes	Specifies the number of bytes to read from the file.

Returns

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 the file (EOF) before reading the specified number of bytes. If the function fails, the return value is HFILE_ERROR. To get extended error information, use the GetLastError function.

See Also

_hwrite, ReadFile


_hwrite function
_hwrite (Win32)

long _hwrite(hFile, lpBuffer, lBytes)

HFILE hFile;	/* handle of file	*/
LPCSTR lpBuffer;	/* address of buffer for data to be written	*/
long lBytes;	/* number of bytes to write	*/

The _hwrite function writes data to the specified file. This function is provided for compatibility with earlier versions of Windows. For applications written with the Win32 API, use the WriteFile function.

Parameter	Description

hFile	Identifies the specified file.

lpBuffer	Points to a buffer that contains the data to write to the file.

lBytes	Specifies the number of bytes to write to the file.

Returns

If the function succeeds, the return value indicates the number of bytes actually written to the file. Otherwise, it is HFILE_ERROR. To get extended error information, use the GetLastError function.

See Also

_hread, WriteFile


InitAtomTable function
InitAtomTable (Win32)

BOOL InitAtomTable(cTableEntries)

DWORD cTableEntries;	/* size of atom table	*/

The InitAtomTable function initializes the local atom table and sets it to the specified size.

Parameter	Description

cTableEntries	Specifies the size, in table entries, of the atom table. This value should be a prime number.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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


InitializeCriticalSection function
InitializeCriticalSection (Win32)

VOID InitializeCriticalSection(lpcsCriticalSection)

LPCRITICAL_SECTION lpcsCriticalSection;	/* address of critical section object	*/

The InitializeCriticalSection function initializes a critical section object.

Parameter	Description

lpcsCriticalSection	Points to the critical section object.

Returns

This function does not return a value.

Comments

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 and LeaveCriticalSection functions 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 to manage critical section objects.

See Also

CreateMutex, DeleteCriticalSection, EnterCriticalSection, LeaveCriticalSection


InitiateSystemShutdown function
InitiateSystemShutdown (Win32)

BOOL InitiateSystemShutdown(lpszMachineName, lpszMessage, dwTimeout, fForceAppsClosed, fReboot)

LPTSTR lpszMachineName;	/* addr. of name of computer to shut down	*/
LPTSTR lpszMessage;	/* addr. of msg. to display in dialog box	*/
DWORD dwTimeout;	/* time to display dialog box	*/
BOOL fForceAppsClosed;	/* force apps. with unsaved changes flag	*/
BOOL fReboot;	/* reboot flag	*/

The InitiateSystemShutdown function initiates a shutdown and optional restart of the specified computer.

Parameter	Description

lpszMachineName	Points to the null-terminated string that specifies the network name of the computer to shut down. If lpszMachineName is NULL or points to an empty string, the function shuts down the local computer.

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

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 invalid or inaccessible computer name or insufficient privilege.

See Also

AbortSystemShutdown


InterlockedDecrement function
InterlockedDecrement (Win32)

LONG InterlockedDecrement(lplVal)

LPLONG lplVal;	/* address of the variable to decrement	*/

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 InterlockedDecrement or InterlockedIncrement function to access the same variable simultaneously.

Parameter	Description

lplVal	Points to the 32-bit variable to decrement.

Returns

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.

Comments

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 variable pointed to by the lplVal parameter must be aligned on a 32-bit boundary; otherwise, this function will fail on multiprocessor x86 systems.

See Also

InterlockedExchange, InterlockedIncrement


InterlockedExchange function
InterlockedExchange (Win32)

LONG InterlockedExchange(Target, Value)

LPLONG Target;	/* address of 32-bit value to exchange	*/
LONG Value;	/* new value for %LONG% pointed to by <Target>	*/

The InterlockedExchange function atomically exchanges a pair of 32-bit values.

Parameter	Description

Target	Address of LONG to exchange. The function sets this LONG to Value, and returns its prior value.

Value	Specifies a new value for the LONG pointed to by Target.

Returns

The function returns the prior value of the LONG pointed to by Target.

Comments

InterlockedExchange, InterlockedDecrement, 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

InterlockedDecrement, InterlockedIncrement


InterlockedIncrement function
InterlockedIncrement (Win32)

LONG InterlockedIncrement(lplVal)

LPLONG lplVal;	/* address of the variable to increment	*/

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 InterlockedDecrement or InterlockedIncrement function to access the same variable simultaneously.

Parameter	Description

lplVal	Points to the 32-bit variable to increment.

Returns

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.

Comments

InterlockedDecrement, InterlockedIncrement, and InterlockedExchange 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 lplVal parameter must be aligned on a 32-bit boundary; otherwise, this function will fail on multiprocessor x86 systems.

See Also

InterlockedDecrement, InterlockedExchange


IsBadCodePtr function
IsBadCodePtr (Win32)

BOOL IsBadCodePtr(lpfnProc)

FARPROC lpfnProc;	/* address of function	*/

The IsBadCodePtr function determines whether the calling process has read access to the memory at the specified address.

Parameter	Description

lpfnProc	Points to an address in memory.

Returns

If the calling process has read access to the specified memory, the return value is FALSE; otherwise, it is TRUE. To get extended error information, use the GetLastError function.

Comments

The IsBadCodePtr function 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. This 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 function
IsBadHugeReadPtr (Win32)

BOOL IsBadHugeReadPtr(lpvPtr, cbBytes)

CONST VOID *lpvPtr;	/* address of memory block	*/
UINT cbBytes;	/* number of bytes to test	*/

The IsBadHugeReadPtr function verifies that the calling process has read access to the specified range of memory.

Parameter	Description

lpvPtr	Points to the first byte of the memory block.

cbBytes	Specifies the size, in bytes, of the memory block. If this parameter is zero, the return value is FALSE.

Returns

If the calling process has read access to all bytes in the specified memory range, the return value is FALSE; otherwise, it is TRUE. To get extended error information, use the GetLastError function.

Comments

If the calling process has read access to some, but not all, of the bytes in the specified memory range, TRUE is returned.

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. This enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

This function 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

IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadReadPtr, IsBadStringPtr, IsBadWritePtr


IsBadHugeWritePtr function
IsBadHugeWritePtr (Win32)

BOOL IsBadHugeWritePtr(lpvPtr, cbBytes)

LPVOID lpvPtr;	/* address of memory block	*/
UINT cbBytes;	/* number of bytes to test	*/

The IsBadHugeWritePtr function verifies that the calling process has write access to the specified range of memory.

Parameter	Description

lpvPtr	Points to the first byte of the memory block.

cbBytes	Specifies the size, in bytes, of the memory block. If this parameter is zero, the return value is FALSE.

Returns

If the calling process has write access to all bytes in the specified memory range, the return value is FALSE; otherwise, it is TRUE. To get extended error information, use the GetLastError function.

Comments

If the calling process has write access to some, but not all, of the bytes in the specified memory range, TRUE is returned .

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. This enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

This function 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, IsBadHugeWritePtr, IsBadReadPtr, IsBadStringPtr, IsBadWritePtr


IsBadReadPtr function
IsBadReadPtr (Win32)

BOOL IsBadReadPtr(lpvPtr, cbBytes)

CONST VOID *lpvPtr;	/* address of memory block	*/
UINT cbBytes;	/* number of bytes to test	*/

The IsBadReadPtr function verifies that the calling process has read access to the specified range of memory.

Parameter	Description

lpvPtr	Points to the first byte of the memory block.

cbBytes	Specifies the size, in bytes, of the memory block. If this parameter is zero, the return value is FALSE.

Returns

If the calling process has read access to all bytes in the specified memory range, the return value is FALSE; otherwise, it is TRUE. To get extended error information, use the GetLastError function.

Comments

If the calling process has read access to some, but not all, of the bytes in the specified memory range, TRUE is returned.

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


IsBadStringPtr function
IsBadStringPtr (Win32)

BOOL IsBadStringPtr(lpszStr, cchMax)

LPCTSTR lpszStr;	/* address of string	*/
UINT cchMax;	/* maximum size of string	*/

The IsBadStringPtr function verifies that the calling process has read access to a range of memory pointed to by a string pointer.

Parameter	Description

lpszStr	Points to a null-terminated string, either Unicode or ASCII.

cchMax	Specifies the maximum size, in characters, of the string. This 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 cchMax, whichever is smaller. If this parameter is zero, the return value is FALSE.

Returns

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 cchMax, the return value is FALSE; otherwise, it is TRUE. To get extended error information, use the GetLastError function.

Comments

If the calling process has read access to some, but not all, of the bytes in the specified memory range, TRUE is returned.

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. This 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 function
IsBadWritePtr (Win32)

BOOL IsBadWritePtr(lpvPtr, cbBytes)

LPVOID lpvPtr;	/* address of memory block	*/
UINT cbBytes;	/* number of bytes to test	*/

The IsBadWritePtr function verifies that the calling process has write access to the specified range of memory.

Parameter	Description

lpvPtr	Points to the first byte of the memory block.

cbBytes	Specifies the size, in bytes, of the memory block. If this parameter is zero, the return value is FALSE.

Returns

If the calling process has write access to all bytes in the specified memory range, the return value is FALSE; otherwise, it is TRUE. To get extended error information, use the GetLastError function.

Comments

If the calling process has write access to some, but not all, of the bytes in the specified memory range, TRUE is returned.

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


LeaveCriticalSection function
LeaveCriticalSection (Win32)

VOID LeaveCriticalSection(lpcsCriticalSection)

LPCRITICAL_SECTION lpcsCriticalSection;	/* address of critical section object	*/

The LeaveCriticalSection function releases ownership of the specified critical section object.

Parameter	Description

lpcsCriticalSection	Points to the critical section object.

Returns

This function does not return a value.

Comments

A thread uses the EnterCriticalSection function to acquire ownership of a critical section object. Once a thread owns a critical section, it can make additional calls to EnterCriticalSection without blocking its execution. This prevents a thread from deadlocking itself while waiting for a critical section that it already owns. 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.

The threads of a single process can use a critical section object to provide mutually exclusive access to a shared resource. For similar synchronization between the threads of different processes, use a mutex object.

See Also

CreateMutex, DeleteCriticalSection, EnterCriticalSection, InitializeCriticalSection


LoadLibrary function
LoadLibrary (Win32)

HINSTANCE LoadLibrary(lpszLibFile)

LPCTSTR lpszLibFile;	/* address of file name of executable module	*/

The LoadLibrary function maps the specified executable module into the address space of the calling process.

Parameter	Description

lpszLibFile	Points to a null-terminated string that names the Win32 module (.DLL or .EXE). 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 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 file extension is omitted, the default library file 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	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.

The first directory searched is the one directory containing the image file used to create the calling process (see the CreateProcess function). This allows private dynamic-link library 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. This includes libraries 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.

Returns

If the function succeeds, the return value is a handle to the module; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

LoadLibrary can be used to map a dynamic-link library (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, in that a LoadLibrary call by one process does not produce a handle 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 flag. If the DLL's entrypoint function does not return TRUE, LoadLibrary fails and returns NULL.

See Also

DllEntryPoint, FreeLibrary, FindResource, GetProcAddress, GetSystemDirectory, GetWindowsDirectory, LoadResource


LoadLibraryEx function
LoadLibraryEx (Win32)

HINSTANCE LoadLibraryEx(lpszLibFile, hFile, dwFlags)

LPCTSTR lpszLibFile;	/* address of library-file name	*/
HANDLE hFile;	/* reserved; must be NULL	*/
DWORD dwFlags;	/* entrypoint execute flag	*/

The LoadLibraryEx function maps the specified executable module into the address space of the calling process.

Parameter	Description

lpszLibFile	Points to a null-terminated string that names the Win32 module (.DLL or .EXE). 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 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 file 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 in which the executable module for the calling process is located.

2	The current directory.

3	The Windows system directory. The GetSystemDirectory function retrieves the path of this directory.

4	The Windows directory. The GetSystemDirectory function retrieves the path of this directory.

5	The directories listed in the PATH environment variable.

hFile	Reserved; must be NULL.

dwFlags	If lpszLibFile is a dynamic-link library (DLL), specifies whether to call the DllEntryPoint function. If this parameter is zero, LoadLibraryEx is identical to the LoadLibrary function. If the DONT_RESOLVE_DLL_REFERENCES flag is specified, the DllEntryPoint function is not used for process and thread initialization and termination.

Returns

If the function succeeds, the return value is a handle to the mapped library module; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The LoadLibraryEx function is identical to the LoadLibrary function except that it enables the option of mapping a DLL module without calling the DLL's DllEntryPoint function.

The calling process can use the returned handle to identify the module in the GetProcAddress, FindResource, and LoadResource functions.

See Also

FreeLibrary, GetProcAddress, LoadLibrary


LoadModule function
LoadModule (Win32)

DWORD LoadModule(lpszModule, lpvParamBlock)

LPCSTR lpszModule;	/* address of filename to load	*/
LPVOID lpvParamBlock;	/* address of parameter block for new module	*/

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 Window. For Win32 applications, use the CreateProcess function.

Parameter	Description

lpszModule	Points to a null-terminated string that contains the filename of the application to run. If the lpszModule string 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	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.

lpvParamBlock	Points to a 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 parameter to CreateProcess. 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 string if it is not used.

Returns

If the function succeeds, the return value is greater than 31; otherwise, it is an error code, which may be one of the following:

Value	Meaning

0	The 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).

Comments

Win32 applications should use the CreateProcess function. In the Win32 API, the implementation of the LoadModule function calls the CreateProcess function. The following section describes how each parameter for the CreateProcess function is formed:

CreateProcess parameter	Value

lpszImageName	LoadModule lpszModule parameter

lpszCommandLine	LoadModule lpvParamBlock->lpCmdLine

lpsaProcess	NULL

lpsaThread	NULL

fInheritHandles	FALSE

fdwCreate	0

lpvEnvironment	LoadModule lpvParamBlock->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 lpvParamBlock->lpCmdShow parameter.

lppiProcInfo.hProcess	The handle is immediately closed.

lppiProcInfo.hThread	The handle is immediately closed.

See Also

CreateProcess, GetSystemDirectory, GetWindowsDirectory, ShowWindow, WinExec


LoadResource function
LoadResource (Win32)

HGLOBAL LoadResource(hModule, hResInfo)

HINSTANCE hModule;	/* resource-module handle	*/
HRSRC hResInfo;	/* resource handle	*/

The LoadResource function loads the specified resource into global memory.

Parameter	Description

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.

Returns

If the function succeeds, the return value is a handle to the global memory block containing the data associated with the resource. Otherwise, it is NULL. To get extended error information, us the GetLastError function.

Comments

It is not necessary to free a resource loaded by using the LoadResource function.

See Also

FindResource, LoadLibrary, LoadModule, LockResource


LocalAlloc function
LocalAlloc (Win32)

HLOCAL LocalAlloc(fuFlags, cbBytes)

UINT fuFlags;	/* allocation attributes	*/
UINT cbBytes;	/* number of bytes to allocate	*/

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.

Parameter	Description

fuFlags	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 implementations 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.

cbBytes	Specifies the number of bytes to allocate. If cbBytes is zero and the fuFlags parameter specifies the LMEM_MOVEABLE flag, this function returns a handle to a memory object that is marked as discarded.

Returns

If the function succeeds, the return value is the handle of the newly allocated memory object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

If the heap does not contain sufficient free space to satisfy the request, this function returns NULL.

GlobalAlloc and LocalAlloc 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


LocalDiscard function
LocalDiscard (Win32)

HLOCAL LocalDiscard(hlocMem)

HLOCAL hlocMem;	/* handle of local memory object	*/

The LocalDiscard function discards the specified local memory object. The lock count of the memory object must be zero.

Parameter	Description

hlocMem	Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Returns

If the function succeeds, the return value is the handle of the local memory object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The LocalDiscard function discards only local objects allocated by a process with the LMEM_DISCARDABLE flag set. 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

LocalReAlloc


LocalFileTimeToFileTime function
LocalFileTimeToFileTime (Win32)

BOOL LocalFileTimeToFileTime(lpftLocal, lpft)

CONST FILETIME * lpftLocal;	/* address of local file time to convert	*/
LPFILETIME lpft;	/* address of converted file time	*/

The LocalFileTimeToFileTime function converts a local file time to a file time based on the Universal Time Convention (UTC).

Parameter	Description

lpftLocal	Points to a FILETIME structure that specifies the local file time to be converted into a UTC-based file time.

lpft	Points to a FILETIME structure to receive the converted UTC-based file time. This parameter cannot be the same as the lpftLocal parameter.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

FileTimeToLocalFileTime


LocalFlags function
LocalFlags (Win32)

UINT LocalFlags(hlocMem)

HLOCAL hlocMem;	/* handle of local memory object	*/

The LocalFlags function returns information about the specified local memory object.

Parameter	Description

hlocMem	Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Returns

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; otherwise, it is the LMEM_INVALID_HANDLE flag, indicating that the local handle is not valid. To get extended error information, use the GetLastError function.

Comments

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 set 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 function
LocalFree (Win32)

HLOCAL LocalFree(hlocMem)

HLOCAL hlocMem;	/* handle of local memory object	*/

The LocalFree function frees the specified local memory object and invalidates its handle.

Parameter	Description

hlocMem	Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Returns

If the function succeeds, the return value is NULL; otherwise, it is equal to the handle of the local memory object. To get extended error information, use the GetLastError function.

Comments

The LocalFree function fails if the memory object is locked, indicating a lock count greater than zero. The LocalLock function locks a local memory object and increments the lock count. The LocalUnlock function unlocks it and decrements the lock count. To get the lock count of a local memory object, use the LocalFlags function.

If the process tries to examine or modify the memory after it has been freed, heap corruption or an access violation exception (EXCEPTION_ACCESS_VIOLATION) may occur.

If the hlocMem parameter is NULL, LocalFree fails and the system generates an access violation exception.

See Also

LocalAlloc, LocalFlags, LocalLock, LocalReAlloc, LocalUnlock


LocalHandle function
LocalHandle (Win32)

HLOCAL LocalHandle(lpvMem)

LPCVOID lpvMem;	/* address of local memory object	*/

The LocalHandle function retrieves the handle associated with the specified pointer to a local memory object.

Parameter	Description

lpvMem	Points to the first byte of the local memory object. This pointer is returned by the LocalLock function.

Returns

If the function succeeds, the return value is the handle of the specified local memory object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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 function
LocalLock (Win32)

LPVOID LocalLock(hlocMem)

HLOCAL hlocMem;	/* handle of local memory object	*/

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.

Parameter	Description

hlocMem	Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Returns

If the function succeeds, the return value is a pointer to the first byte of the memory block; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, LocalLock increments this 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

LocalFlags, LocalReAlloc, LocalUnlock


LocalReAlloc function
LocalReAlloc (Win32)

HLOCAL LocalReAlloc(hlocMem, cbBytes, fuFlags)

HLOCAL hlocMem;	/* handle of local memory object	*/
UINT cbBytes;	/* new size of block	*/
UINT fuFlags;	/* how to reallocate object	*/

The LocalReAlloc function changes the size or the attributes of a specified local memory object. The size can increase or decrease.

Parameter	Description

hlocMem	Identifies the local memory object to be reallocated. This handle is returned by either the LocalAlloc or LocalReAlloc function.

cbBytes	Specifies the new size, in bytes, of the memory block. If cbBytes is zero and the fuFlags parameter specifies the LMEM_MOVEABLE flag, this function returns a handle to a memory object that is marked as discarded. This parameter is ignored if fuFlags specifies the LMEM_MODIFY flag.

fuFlags	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 cbBytes 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

This flag allocates discardable memory. This flag is used only 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

This flag changes a fixed memory object to a movable memory object, if the LMEM_MODIFY flag is also specified.

If fuFlags does not specify LMEM_MODIFY, the parameter can be a combination of any of the following flags:

Flag	Meaning

LMEM_MOVEABLE

If cbBytes 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 cbBytes is nonzero, this flag enables the system to move the reallocated block to a new location. This does not change 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 hlocMem parameter. If the object is movable, the block can be moved without invalidating the handle. This can occur 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

This flag prevents memory from being compacted or discarded to satisfy the allocation request.

LMEM_ZEROINIT

This flag causes the additional memory contents to be initialized to zero, if the memory object is growing in size.

Returns

If the function succeeds, the return value is the handle of the reallocated memory object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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


LocalSize function
LocalSize (Win32)

UINT LocalSize(hlocMem)

HLOCAL hlocMem;	/* handle of local memory object	*/

The LocalSize function returns the current size, in bytes, of the specified local memory object.

Parameter	Description

hlocMem	Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Returns

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, use the GetLastError function.

Comments

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, LocalReAlloc


LocalUnlock function
LocalUnlock (Win32)

BOOL LocalUnlock(hlocMem)

HLOCAL hlocMem;	/* handle of local memory object	*/

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.

Parameter	Description

hlocMem	Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Returns

If the object's lock count is decremented to zero, the return value is FALSE; otherwise, it is TRUE. To get extended error information, use the GetLastError function.

Comments

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, the LocalLock function increments this 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.

Memory objects allocated with the LMEM_FIXED flag always have a lock count of zero. If the specified memory block is fixed memory, this function returns nonzero.

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

LocalFlags, LocalLock


LockFile function
LockFile (Win32)

BOOL LockFile(hFile, dwFileOffsetLow, dwFileOffsetHigh, cbLockLow, cbLockHigh)

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 cbLockLow;	/* low-order word of length to lock	*/
DWORD cbLockHigh;	/* high-order word of length to lock	*/

The LockFile function locks a region in an open file. Locking a region prevents other processes from accessing the region.

Parameter	Description

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.

cbLockLow	Specifies the low-order word of the length of the byte range to be locked.

cbLockHigh	Specifies the high-order word of the length of the byte range to be locked.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
LockFileEx (Win32)

BOOL LockFileEx(hFile, dwFlags, dwReserved, nNumberOfBytesToLockLow, nNumberOfBytesToLockHigh, lpOverlapped)

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;	/* pointer to struct with lock region start offset	*/

The LockFileEx function locks a byte range within an open file for shared or exclusive access.

Parameter	Description

hFile	Supplies 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	Supplies flag bits that modify the behavior of this function. You may set one or more of the following flags:

Value	Meaning

LOCKFILE_FAIL_IMMEDIATELY	If set, the function returns immediately if it is unable to acquire the requested lock. Otherwise it waits.

LOCKFILE_EXCLUSIVE_LOCK	If set, the function requests an exclusive lock. Otherwise it requests a shared lock.

dwReserved	Reserved parameter that must be set to zero.

nNumberOfBytesToLockLow	Supplies the low order 32-bits of the length of the byte range to lock.

nNumberOfBytesToLockHigh	Supplies the high order 32-bits of the length of the byte range to lock.

lpOverlapped	Required pointer to an OVERLAPPED data structure that the function uses with the locking request. This structure contains the file offset of the beginning of the lock range.

Returns

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE/NULL. Use the GetLastError function to obtain extended error information.

Comments

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 other processes write access to the specified region of the file, but allows other processes to read the locked region.

If requesting an exclusive lock for a file that is already locked shared or exclusively by other threads, then 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, UnlockFile, UnlockFileEx


LockResource function
LockResource (Win32)

LPVOID LockResource(hglb)

HGLOBAL hglb;	/* handle to resource to lock	*/

The LockResource function locks the specified resource in memory.

Parameter	Description

hglb	Identifies the resource to be locked. The LoadResource function returns this handle.

Returns

If the loaded resource is locked, the return value is a pointer to the first byte of the resource; otherwise, it is NULL.

Comments

It is not necessary for Win32 applications to unlock resources locked by using 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


lstrcat function
lstrcat (Win32)

LPTSTR lstrcat(lpszString1, lpszString2)

LPTSTR lpszString1;	/* address of buffer for concatenated strings	*/
LPCTSTR lpszString2;	/* address of string to add to string1	*/

The lstrcat function appends one string to another.

Parameter	Description

lpszString1	Points to a byte array containing a null-terminated string. The byte array must be large enough to contain both strings.

lpszString2	Points to the null-terminated string to be appended to the string specified in the lpszString1 parameter.

Returns

If the function succeeds, the return value is a pointer to the byte array. To get extended error information, use the GetLastError function.

See Also

lstrcmp, lstrcmpi, lstrcpy, lstrlen


lstrcmp function
lstrcmp (Win32)

int lstrcmp(lpszString1, lpszString2)

LPCTSTR lpszString1;	/* address of first string	*/
LPCTSTR lpszString2;	/* address of second string	*/

The lstrcmp function compares two character strings. The comparison is case sensitive.

Parameter	Description

lpszString1	Points to the first null-terminated string to be compared.

lpszString2	Points to the second null-terminated string to be compared.

Returns

If the function succeeds and the string pointed to by lpszString1 is less than the string pointed to by lpszString2, the return value is negative; if the string pointed to by lpszString1 is greater than the string pointed to by lpszString2, it is positive. If the strings are equal, the return value is zero.

Comments

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.

See Also

lstrcat, lstrcmpi, lstrcpy, lstrlen


lstrcmpi function
lstrcmpi (Win32)

int lstrcmpi(lpszString1, lpszString2)

LPCTSTR lpszString1;	/* address of first string	*/
LPCTSTR lpszString2;	/* address of second string	*/

The lstrcmpi function compares two character strings. The comparison is not case sensitive.

Parameter	Description

lpszString1	Points to the first null-terminated string to be compared.

lpszString2	Points to the second null-terminated string to be compared.

Returns

If the function succeeds and the string pointed to by lpszString1 is less than the string pointed to by lpszString2, the return value is negative; if the string pointed to by lpszString1 is greater than the string pointed to by lpszString2, it is positive. If the strings are equal, the return value is zero.

Comments

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

With a double-byte character set (DBCS) version of Windows, this function can compare two DBCS strings.

See Also

lstrcat, lstrcmp, lstrcpy, lstrlen


lstrcpy function
lstrcpy (Win32)

LPTSTR lstrcpy(lpszString1, lpszString2)

LPTSTR lpszString1;	/* address of buffer	*/
LPCTSTR lpszString2;	/* address of string to copy	*/

The lstrcpy function copies a string to a buffer.

Parameter	Description

lpszString1	Points to a buffer to receive the contents of the string pointed to by the lpszString2 parameter. The buffer must be large enough to contain the string, including the terminating null character.

lpszString2	Points to the null-terminated string to be copied.

Returns

If the function succeeds, the return value is a pointer to the buffer; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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


lstrlen function
lstrlen (Win32)

int lstrlen(lpszString)

LPCTSTR lpszString;	/* address of string to count	*/

The lstrlen function returns the length, in characters, of the specified string (not including the terminating null character).

Parameter	Description

lpszString	Points to a null-terminated string.

Returns

If the function succeeds, the return value specifies the length, in characters, of the string.

See Also

lstrcat, lstrcmp, lstrcmpi, lstrcpy


_lclose function
_lclose (Win32)

HFILE _lclose(hFile)

HFILE hFile;	/* handle of file to close	*/

The _lclose function closes the specified file so it is no longer available for reading or writing. This function is provided for compatibility with earlier versions of Windows. For applications written with the Win32 API, use the CloseHandle function.

Parameter	Description

hFile	Identifies the file to be closed. This handle is returned by the function that created or last opened the file.

Returns

If the function succeeds, the return value is zero; otherwise, it is HFILE_ERROR. To get extended error information, use the GetLastError function.

See Also

CreateFile, _lopen


_lcreat function
_lcreat (Win32)

HFILE _lcreat(lpszFileName, fnAttribute)

LPCSTR lpszFileName;	/* address of the name of the file to open	*/
int fnAttribute;	/* file attribute	*/

The _lcreat function creates or opens a specified file. This function is provided for compatibility with earlier versions of Windows. For applications written with the Win32 API, use the CreateFile function.

Parameter	Description

lpszFileName	Points to a null-terminated string that names the file to be opened. The string must consist of characters from the Windows ANSI character set.

fnAttribute	Specifies the file attributes. The 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.

Returns

If the function succeeds, the return value is a file handle; otherwise, it is HFILE_ERROR. To get extended error information, use the GetLastError function.

Comments

If the file does not exist, _lcreat creates a new file and opens it for writing. If the file does exist, _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.

Use the _lcreat function carefully. It can open any file, even one already opened by another function.

See Also

CreateFile, _lopen


_llseek function
_llseek (Win32)

LONG _llseek(hFile, lOffset, nOrigin)

HFILE hFile;	/* handle of file	*/
LONG lOffset;	/* number of bytes to move	*/
int nOrigin;	/* position to move from	*/

The _llseek function repositions the file pointer in a previously opened file. This function is provided for compatibility with earlier versions of Windows. For applications written with the Win32 API, use the SetFilePointer function.

Parameter	Description

hFile	Identifies the file.

lOffset	Specifies the number of bytes the file pointer is to be moved.

nOrigin	Specifies the starting position and direction of the file pointer. The 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 its current position.

2	Moves the file pointer lOffset bytes from the end of the file.

Returns

If the function succeeds, the return value specifies the new offset of the pointer, in bytes, from the beginning of the file. Otherwise, the return value is HFILE_ERROR. To get extended error information, use the GetLastError function.

Comments

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 function
_lopen (Win32)

HFILE _lopen(lpszFileName, fnOpenMode)

LPCSTR lpszFileName;	/* address of name of file to open	*/
int fnOpenMode;	/* file access mode	*/

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 earlier versions of Windows. For applications written with the Win32 API, use the CreateFile function.

Parameter	Description

lpszFileName	Points to a null-terminated string that names the file to open. The string must consist of characters from the Windows ANSI character set.

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

Value	Meaning

OF_READ	Opens the file for reading from only.

OF_READWRITE	Opens the file for reading from and writing to.

OF_WRITE	Opens the file for writing to only.

The share mode can be one of the following:

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.

Returns

If the function succeeds, the return value is a file handle; otherwise, it is HFILE_ERROR. To get extended error information, use the GetLastError function.

See Also

CreateFile


_lread function
_lread (Win32)

UINT _lread(hFile, lpBuffer, cbRead)

HFILE hFile;	/* handle of file	*/
LPVOID lpBuffer;	/* address of buffer for read data	*/
UINT cbRead;	/* length, in bytes, of data buffer	*/

The _lread function reads data from the specified file. This function is provided for compatibility with earlier versions of Windows. For applications written with the Win32 API, use the ReadFile function.

Parameter	Description

hFile	Identifies the specified file.

lpBuffer	Points to a buffer that contains the data read from the file.

cbRead	Specifies the number of bytes to read from the file.

Returns

The return value indicates the number of bytes actually read from the file. If the number of bytes read is less than cbRead, the function has reached the end of the file (EOF) before reading the specified number of bytes. If the function fails, the return value is HFILE_ERROR. To get extended error information, use the GetLastError function.

See Also

_lwrite, ReadFile


_lwrite function
_lwrite (Win32)

UINT _lwrite(hFile, lpBuffer, cbWrite)

HFILE hFile;	/* handle of file	*/
LPCSTR lpBuffer;	/* address of buffer for data to be written	*/
UINT cbWrite;	/* number of bytes to write	*/

The _lwrite function writes data to the specified file. This function is provided for compatibility with earlier versions of Windows. For applications written with the Win32 API, use the WriteFile function.

Parameter	Description

hFile	Identifies the specified file.

lpBuffer	Points to a buffer that contains the data to write to the file.

cbWrite	Specifies the number of bytes to write to the file.

Returns

If the function succeeds, the return value indicates the number of bytes actually written to the file. Otherwise, it is HFILE_ERROR. To get extended error information, use the GetLastError function.

See Also

_lread, WriteFile


MapViewOfFile function
MapViewOfFile (Win32)

LPVOID MapViewOfFile(hMapObject, fdwAccess, dwOffsetHigh, dwOffsetLow, cbMap)

HANDLE hMapObject;	/* file-mapping object to map into address space	*/
DWORD fdwAccess;	/* access mode	*/
DWORD dwOffsetHigh;	/* high-order 32 bits of file offset	*/
DWORD dwOffsetLow;	/* low-order 32 bits of file offset	*/
DWORD cbMap;	/* number of bytes to map	*/

The MapViewOfFile function maps a view of a file into the address space of the calling process.

Parameter	Description

hMapObject	Identifies an open handle of a file-mapping object. The CreateFileMapping and OpenFileMapping functions return this handle.

fdwAccess	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-and-write access. The hMapObject parameter must have been created with PAGE_READWRITE protection. A read-and-write view of the file is mapped.

FILE_MAP_READ	Read-only access. The hMapObject parameter 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 hMapObject parameter must have been created with PAGE_WRITECOPY protection. A copy on write view of the file is mapped.

dwOffsetHigh	Specifies the high-order 32 bits of the file offset where mapping is to begin.

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

cbMap	Specifies the number of bytes of the file to map. If cbMap is zero, the entire file is mapped.

Returns

If the function succeeds, the return value is the starting address of the mapped view; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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 given 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, MapViewOfFileEx, OpenFileMapping, UnmapViewOfFile, SYSTEM_INFO


MapViewOfFileEx function
MapViewOfFileEx (Win32)

LPVOID MapViewOfFileEx(hMapObject, fdwAccess, dwOffsetHigh, dwOffsetLow, cbMap, lpvBase)

HANDLE hMapObject;	/* file-mapping object to map into address space	*/
DWORD fdwAccess;	/* access mode	*/
DWORD dwOffsetHigh;	/* high-order 32 bits of file offset	*/
DWORD dwOffsetLow;	/* low-order 32 bits of file offset	*/
DWORD cbMap;	/* number of bytes to map	*/
LPVOID lpvBase;	/* suggested starting address for mapped view	*/

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 only in Windows NT.

Parameter	Description

hMapObject	Identifies an open handle to a file-mapping object. The CreateFileMapping and OpenFileMapping functions return this handle.

fdwAccess	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 hMapObject parameter must have been created with PAGE_READWRITE protection. A read-and-write view of the file is mapped.

FILE_MAP_READ	Read-only access. The hMapObject parameter 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 hMapObject parameter must have been created with PAGE_WRITECOPY protection. A copy on write view of the file is mapped.

dwOffsetHigh	Specifies the high-order 32 bits of the file offset where mapping is to begin.

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

cbMap	Specifies the number of bytes of the file to map. If cbMap is zero, the entire file is mapped.

lpvBase	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 lpvBase is NULL, the operating system chooses the mapping address. In this case, this function is equivalent to the MapViewOfFile function.

Returns

If the function succeeds, the return value is the starting address of the mapped view; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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.

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 given 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, UnmapViewOfFile, SYSTEM_INFO


MoveFile function
MoveFile (Win32)

BOOL MoveFile(lpszExisting, lpszNew)

LPCTSTR lpszExisting;	/* address of name of the existing file	*/
LPCTSTR lpszNew;	/* address of new name for the file	*/

The MoveFile function renames an existing file or a directory (including all its children).

Parameter	Description

lpszExisting	Points to a null-terminated string that names an existing file or directory.

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

Returns

If the function succeeds, the return value is TRUE; otherwise it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 with this is that the MoveFile function will fail on directory moves when the destination is on a different volume.

See Also

CopyFile, MoveFileEx


MoveFileEx function
MoveFileEx (Win32)

BOOL MoveFileEx(lpszExisting, lpszNew, fdwFlags)

LPCTSTR lpszExisting;	/* address of name of the existing file	*/
LPCTSTR lpszNew;	/* address of new name for the file	*/
DWORD fdwFlags;	/* flag to determine how to move file	*/

The MoveFileEx function renames an existing file.

Parameter	Description

lpszExisting	Points to a null-terminated string that names an existing file.

lpszNew	Points to a null-terminated string that specifies the new name of a file. The new file can be on a different file system or drive. If this parameter is NULL, the file specified by lpszExisting is deleted.

fdwFlags	Specifies how to move the file. This parameter must be one of the following values:

Value	Meaning

MOVEFILE_REPLACE_EXISTING

If a file of the name specified by lpszNew already exists, the function replaces its contents with those specified by lpszExisting.

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.

MOVEFILE_DELAY_UNTIL_REBOOT

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. Therefore, this parameter enables the function to delete paging files from previous startups.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Please note that an application cannot specify both MOVEFILE_DELAY_UNTIL_REBOOT and MOVEFILE_COPY_ALLOWED for fdwFlags. Calls that do so will fail.

See Also

CopyFile, DeleteFile, MoveFile


MoveMemory function
MoveMemory (Win32)

VOID MoveMemory (Destination, Source, Length)

PVOID Destination;	/* address of move destination	*/
CONST VOID * Source;	/* address of block to move	*/
DWORD Length;	/* size in bytes of block to move	*/

The MoveMemory function moves a block of memory from one location to another.

Parameter	Description

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.

Returns

This function has no return value.

Comments

The source and destination blocks may overlap.

See Also

CopyMemory, FillMemory, ZeroMemory


MulDiv function
MulDiv (Win32)

int MulDiv(nMultiplicand, nMultiplier, nDivisor)

int nMultiplicand;	/* 32-bit signed multiplicand	*/
int nMultiplier;	/* 32-bit signed multiplier	*/
int nDivisor;	/* 32-bit signed divisor	*/

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.

Parameter	Description

nMultiplicand	Specifies the multiplicand.

nMultiplier	Specifies the multiplier.

nDivisor	Specifies the number by which the result of the multiplication (nMultiplicand * nMultiplier) is to be divided.

Returns

If the function succeeds, the return value is the result of the multiplication and division. If either an overflow occurred or nDivisor was 0, the return value is -1.

See Also

CreateLogFont


Netbios function
Netbios (Win32)

UCHAR Netbios(pncb)

PNCB pncb;	/* address of the network-control block	*/

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

Parameter	Description

pncb	Points to an NCB structure describing the network-control block to process.

Returns

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

There are two return value possibilites for accepted asynchronous requests. If the asynchronous command has already completed when the Netbios call returns to its caller, the return value is the completion code of the NCB, just as if it were a synchronous NCB. If the asynchronous command is still pending when the Netbios call returns to its caller, the return value is 0.

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

Comments

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.

The Netbios function 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 ncb_post 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 (ncb_event). The event is set to the non-signalled state by the system when an asynchronous NetBIOS command is accepted, and is set to the signalled 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

NCB


OpenBackupEventLog function
OpenBackupEventLog (Win32)

HANDLE OpenBackupEventLog(lpszUNCServerName, lpszFileName)

LPCTSTR lpszUNCServerName;	/* backup file server name	*/
LPCTSTR lpszFileName;	/* backup filename	*/

The OpenBackupEventLog function opens a handle of a backup event log. This handle can be used with the BackupEventLog function.

Parameter	Description

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

lpszFileName	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, lpszUNCServerName must be NULL).

Returns

If the function succeeds, the return value is a handle of the backup event log; otherwise, the return value is NULL.

Comments

If the backup filename specifies a remote server, lpszUNCServerName must be NULL. You cannot use this function to open a file on a remote server.

See Also

BackupEventLog


OpenEvent function
OpenEvent (Win32)

HANDLE OpenEvent(fdwAccess, fInherit, lpszEventName)

DWORD fdwAccess;	/* access flag	*/
BOOL fInherit;	/* inherit flag	*/
LPCTSTR lpszEventName;	/* address of event-object name	*/

The OpenEvent function returns a handle of an existing named event object.

Parameter	Description

fdwAccess	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_MODIFY_STATE	Enables use of the event handle in the SetEvent and ResetEvent functions to modify the event's state.

SYNCHRONIZE	Enables use of the event handle in any of the wait functions to wait for the event's state to be signaled.

EVENT_ALL_ACCESS	Specifies all possible access flags for the event object.

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

lpszEventName	Points to a null-terminated string that names the event to be opened. Name comparisons are case sensitive.

Returns

If the function succeeds, the return value is a handle of the event object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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 fdwAccess 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, DuplicateHandle, MsgWaitForMultipleObjects, PulseEvent, ResetEvent, SetEvent, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


OpenEventLog function
OpenEventLog (Win32)

HANDLE OpenEventLog(lpszUNCServerName, lpszSourceName)

LPCTSTR lpszUNCServerName;	/* address of server name	*/
LPCTSTR lpszSourceName;	/* address of source name	*/

The OpenEventLog function opens a handle of an event log.

Parameter	Description

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

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

Returns

If the function succeeds, the return value is the handle of an event log; otherwise, the return value is NULL. To get extended error information, use the GetLastError function.

See Also

ClearEventLog, CloseEventLog, GetNumberOfEventLogRecords, GetOldestEventLogRecord, ReadEventLog, ReportEvent


OpenFile function
OpenFile (Win32)

HFILE OpenFile(lpszFile, lpOpenBuff, fuMode)

LPCSTR lpszFile;	/* address of filename	*/
LPOFSTRUCT lpOpenBuff;	/* address of buffer for file information	*/
UINT fuMode;	/* action and attributes	*/

The OpenFile function creates, opens, reopens, or deletes a file.

This function is provided for compatibility with earlier versions of Windows. In particular, the OpenFile function cannot open a named pipe. For Win32 applications, use the CreateFile function.

Parameter	Description

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

lpOpenBuff	Points to the OFSTRUCT structure to receive 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.

fuMode	Specifies the action to take. These styles can be combined by using the bitwise OR operator:

Value	Meaning

OF_CANCEL	Ignored. In the Win32 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 file 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 application programming interface (API), opens the file with compatibility mode, allowing any process on a given computer to open the file any number of times. Other efforts to open with any other sharing mode fail. For NTFS-based file systems, this flag is mapped to OF_SHARE_DENY_NONE.

OF_SHARE_DENY_NONE	Opens the file without denying read or write access to other processes. If the file has been opened in compatibility mode by any other process, the function fails.

OF_SHARE_DENY_READ	Opens the file and denies read access to other processes. If the file has been opened in compatibility mode or for read access by any other process, the function fails.

OF_SHARE_DENY_WRITE	Opens the file and denies write access to other processes. If the file has been opened in compatibility mode or for write access by any other process, the function fails.

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.

Returns

If the function succeeds, the return value specifies a file handle; otherwise, it is HFILE_ERROR. To get extended error information, use the GetLastError function.

Comments

If the lpszFile 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	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.

The lpszFile parameter cannot contain wildcard characters.

To close the file after use, call the _lclose function.

See Also

CreateFile, GetSystemDirectory, GetWindowsDirectory, _lclose, OFSTRUCT


OpenFileMapping function
OpenFileMapping (Win32)

HANDLE OpenFileMapping(dwDesiredAccess, bInheritHandle, lpName)

DWORD dwDesiredAccess;	/* access mode	*/
BOOL bInheritHandle;	/* inherit flag	*/
LPCTSTR lpName;	/* address of name of file-mapping object	*/

The OpenFileMapping function opens a named file-mapping object.

Parameter	Description

dwDesiredAccess	Specifies the access to the file-mapping object. For Windows NT, this access is checked against any security descriptor on the target file-mapping object. This parameter can be one of the following values:

Value	Meaning

FILE_MAP_WRITE	Read-and-write access. The target file-mapping object must have been created with PAGE_READWRITE protection. A read-and-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.

Returns

If the function succeeds, the return value is an open handle to the specified file-mapping object. Otherwise, the return value is NULL. To get extended error information, use the GetLastError function.

Comments

The handle that OpenFileMapping returns can be used with any function that requires a handle to a file-mapping object.


OpenMutex function
OpenMutex (Win32)

HANDLE OpenMutex(fdwAccess, fInherit, lpszMutexName)

DWORD fdwAccess;	/* access flag	*/
BOOL fInherit;	/* inherit flag	*/
LPCTSTR lpszMutexName;	/* address of mutex-object name	*/

The OpenMutex function returns a handle of an existing named mutex object.

Parameter	Description

fdwAccess	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

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

MUTEX_ALL_ACCESS	Specifies all possible access flags for the mutex object.

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

lpszMutexName	Points to a null-terminated string that names the mutex to be opened. Name comparisons are case sensitive.

Returns

If the function succeeds, the return value is a handle of the mutex object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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, subject to the limitations of the access specified in the fdwAccess 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, DuplicateHandle, MsgWaitForMultipleObjects, ReleaseMutex, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


OpenProcess function
OpenProcess (Win32)

HANDLE OpenProcess(fdwAccess, fInherit, IDProcess)

DWORD fdwAccess;	/* access flag	*/
BOOL fInherit;	/* can child process inherit?	*/
DWORD IDProcess;	/* process identifier	*/

The OpenProcess function returns a handle of an existing process object.

Parameter	Description

fdwAccess	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_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	Enables using the process handle in any of the wait functions to wait for the process to terminate.

PROCESS_ALL_ACCESS	Specifies all possible access flags for the process object.

fInherit	Specifies whether the returned handle can be inherited by a new process created by the current process. If TRUE, the handle is inheritable.

IDProcess	Specifies the process identifier of the process to open.

Returns

If the function succeeds, the return value is an open handle of the specified process; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The handle returned by the OpenProcess function can be used in any function that requires a handle to a process, provided the appropriate access rights were requested.

See Also

CreateProcess, GetCurrentProcess, GetCurrentProcessId


OpenSemaphore function
OpenSemaphore (Win32)

HANDLE OpenSemaphore(fdwAccess, fInherit, lpszSemName)

DWORD fdwAccess;	/* access flag	*/
BOOL fInherit;	/* inherit flag	*/
LPCTSTR lpszSemName;	/* address of semaphore-object name	*/

The OpenSemaphore function returns a handle of an existing named semaphore object.

Parameter	Description

fdwAccess	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_MODIFY_STATE	Enables use of the semaphore handle in the ReleaseSemaphore function to modify the semaphore's count.

SYNCHRONIZE	Enables use of the semaphore handle in any of the wait functions to wait for the semaphore's state to be signaled.

SEMAPHORE_ALL_ACCESS	Specifies all possible access flags for the semaphore object.

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

lpszSemName	Points to a null-terminated string that names the semaphore to be opened. Name comparisons are case sensitive.

Returns

If the function succeeds, the return value is a handle of the semaphore object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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, subject to the limitations of the access specified in the fdwAccess 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, MsgWaitForMultipleObjects, ReleaseSemaphore, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


OutputDebugString function
OutputDebugString (Win32)

VOID OutputDebugString(lpszOutputString)

LPCTSTR lpszOutputString;	/* address of string to be displayed	*/

The OutputDebugString function sends a string to the debugger for the current application.

Parameter	Description

lpszOutputString	Points to the null-terminated string to be displayed.

Returns

This function does not return a value.

Comments

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, this function does nothing.


PeekConsoleInput function
PeekConsoleInput (Win32)

BOOL PeekConsoleInput(hConsoleInput, pirBuffer, cInRecords, lpcRead)

HANDLE hConsoleInput;	/* handle of a console input buffer	*/
PINPUT_RECORD pirBuffer;	/* address of the buffer for peek data	*/
DWORD cInRecords;	/* number of records to read	*/
LPDWORD lpcRead;	/* address of number of records read	*/

The PeekConsoleInput function reads data from the specified console input buffer without removing it from the buffer.

Parameter	Description

hConsoleInput	Identifies the input buffer. The handle must have GENERIC_READ access.

pirBuffer	Points to an INPUT_RECORD buffer to receive the input buffer data.

cInRecords	Specifies the size, in records, of the buffer pointed to by the pirBuffer parameter.

lpcRead	Points to a 32-bit variable to receive the number of input records read.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

See Also

ReadConsoleInput, WriteConsoleInput


PeekNamedPipe function
PeekNamedPipe (Win32)

BOOL PeekNamedPipe(hPipe, lpvBuffer, cbBuffer, lpcbRead, lpcbAvail, lpcbMessage)

HANDLE hPipe;	/* handle of pipe to copy from	*/
LPVOID lpvBuffer;	/* address of data buffer	*/
DWORD cbBuffer;	/* size in bytes of data buffer	*/
LPDWORD lpcbRead;	/* address of number of bytes read	*/
LPDWORD lpcbAvail;	/* address of total number of bytes available	*/
LPDWORD lpcbMessage;	/* address of unread bytes in this message	*/

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.

Parameter	Description

hPipe	Identifies the pipe. This can be a handle to a named pipe instance, as returned by CreateNamedPipe or CreateFile, or it can be a handle to the read end of an anonymous pipe, as returned by CreatePipe. The handle must have GENERIC_READ access to the pipe.

lpvBuffer	Points to a buffer to receive data read from the pipe. Set this parameter to NULL if no data is to be read.

cbBuffer	Specifies the size, in bytes, of the buffer at lpvBuffer. This parameter is ignored if lpvBuffer is NULL.

lpcbRead	Points to a 32-bit variable that will receive the number of bytes read from the pipe. Set this parameter to NULL if no data is to be read.

lpcbAvail	Points to a 32-bit variable that will receive the total number of bytes available to be read from the pipe. Set this parameter to NULL if this information is not required.

lpcbMessage	Points to a 32-bit variable that will receive the number of bytes remaining in this message. This will be zero for byte-type named pipes or for anonymous pipes. Set this parameter to NULL if this information is not required.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The PeekNamedPipe function 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 cbBuffer. For a named pipe handle in message-read mode, the function reads the next message in the pipe. If the message is larger than cbBuffer, the function returns TRUE after reading the specified number of bytes. In this situation, lpcbMessage will receive the number of bytes remaining in the message.

See Also

CreateFile, CreateNamedPipe, CreatePipe, ReadFile, WriteFile


PlaySound function
PlaySound (Win32)

BOOL PlaySound(lpszName, hModule, fdwSound)

LPCTSTR lpszName;	/* sound string	*/
HANDLE hModule;	/* sound resource	*/
DWORD fdwSound;	/* sound type	*/

The PlaySound function plays a waveform sound.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the resource, file, or registry entry for the sound to be played.

hModule	Identifies the module from which the resource is to be loaded if the lpszName parameter specifies the name of a resource.

fdwSound	Specifies the nature of the lpszName parameter and how the sound should be played. This parameter can be a combination of the following values (except as noted):

fdwSound	Meaning

SND_ALIAS	The lpszName parameter specifies an entry in the [sounds] section of the registry, of the form: alias=path. Do not use with either SND_FILENAME or SND_RESOURCE.

SND_ASYNC	The sound should be played asynchronously. The call to PlaySound returns as soon as the sound is started. Do not use with SND_SYNC.

SND_FILENAME	The lpszName parameter specifies the name of a wave file. Do not use with either SND_ALIAS or SND_RESOURCE.

SND_NODEFAULT	The default system sound should not be played if the alias supplied by the lpszName parameter cannot be found. Can be used with SND_ALIAS.

SND_NOWAIT	The call to PlaySound is to fail if no suitable wave device is available to play the sound.

SND_RESOURCE	The lpszName parameter specifies the name of a resource. Do not use with either SND_ALIAS or SND_FILENAME.

SND_SYNC	The sound should be played synchronously. The call to PlaySound does not return until the sound has finished playing. Do not use with SND_ASYNC.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

When playing a sound specified by an alias name from the registry, the default action is to search for the given name and, if it is not found, to search for the SystemDefault entry and play that sound. If the application does not want the default sound to be played, it can set the SND_NODEFAULT flag.

The function can play wave resources from a module, from wave files named explicitly, or from wave files specified by entries in the [sounds] section of the registry.

If the SND_ASYNC flag is set, a return value of TRUE indicates only that the thread has started that will attempt to play the sound. There is no indication that the sound will actually be played.

The PlaySound function provides a simple mechanism to play wave files and wave files built into an application as resources of type WAVE.

See Also

sndPlaySound


PrepareTape function
PrepareTape (Win32)

DWORD PrepareTape(hDevice, dwOperation, bImmediate)

HANDLE hDevice;	/* handle of open device	*/
DWORD dwOperation;	/* preparation method	*/
BOOL bImmediate;	/* return after operation begins	*/

The PrepareTape function prepares the tape to be accessed or removed.

Parameter	Description

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_LOAD	Loads the tape and moves the tape to the beginning.

TAPE_LOCK	Locks the tape ejection mechanism. This prevents the tape from being 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 flag 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 prepartion begins. If this parameter is TRUE, the function returns immediately; if FALSE, the function does not return until the operation has been completed.

Returns

If the function succeeds, the return value is NO_ERROR; otherwise, it 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.

Comments

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.


PulseEvent function
PulseEvent (Win32)

BOOL PulseEvent(hEvent)

HANDLE hEvent;	/* handle of event object	*/

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.

Parameter	Description

hEvent	Identifies the event object. The CreateEvent or OpenEvent function returns this handle, which must have EVENT_MODIFY_STATE access.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 (WaitForMultipleObjects, WaitForMultipleObjectsEx, and MsgWaitForMultipleObjects) 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, MsgWaitForMultipleObjects, OpenEvent, ResetEvent, SetEvent, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


PurgeComm function
PurgeComm (Win32)

BOOL PurgeComm(hCommDev, fdwAction)

HANDLE hCommDev;	/* handle of the communications resource	*/
DWORD fdwAction;	/* action to perform	*/

The PurgeComm function can discard all characters from the output or input buffer of a given communications resource. It can also terminate pending read or write operations on the resource.

Parameter	Description

hCommDev	Identifies the communications resource. The CreateFile function returns this handle.

fdwAction	Specifies the action to take. This parameter can be a combination of the following values:

Value	Meaning

PURGE_TXABORT	Terminate all outstanding write operations are terminated and return immediately, even if the write operations have not been completed.

PURGE_RXABORT	Terminate all outstanding read operations are terminated and return 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).

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 timeouts, and it will not return until all pending write operations have been transmitted.

See Also

CreateFile


QueryDosDevice function
QueryDosDevice (Win32)

DWORD QueryDosDevice(lpDeviceName, lpTargetPath, ucchMax)

LPCTSTR lpDeviceName;	/* pointer to DOS device name string	*/
LPTSTR lpTargetPath;	/* pointer to buffer for storing query results	*/
DWORD ucchMax;	/* maximum storage capacity of that buffer	*/

The QueryDosDevice function lets an application obtain information about DOS device names. The function can obtain the current mapping for a particular DOS device name. The function can also obtain a list of all existing DOS device names.

DOS device names are stored as symbolic links in the Windows NT object name space. The code that converts a DOS path into a corresponding Windows NT path uses these symbolic links to map DOS devices and drive letters. The QueryDosDevice function provides a mechanism whereby a Win32 application can query the names of the symbolic links used to implement the DOS device namespace as well as the value of each specific symbolic link.

Parameter	Description

lpDeviceName	Pointer to a 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 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 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 DOS device names. Each null-terminated string stored into the buffer is the name of an existing DOS device.

ucchMax	Specifies the maximum number of characters that can be stored into the buffer pointed to by lpTargetPath.

Returns

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. Use the GetLastError function to obtain extended error information.

Comments

The DefineDosDevice function provides a means whereby a Win32 application can create and modify the symbolic links used to implement the DOS device namespace.

DOS Device names are global. Once defined, a DOS device name remains visible to all processes until either it is explicity removed or the system reboots.

See Also

DefineDosDevice


QueryPerformanceCounter function
QueryPerformanceCounter (Win32)

BOOL QueryPerformanceCounter(lpliPerformanceCount)

LARGE_INTEGER *lpliPerformanceCount;	/* address of current counter value	*/

The QueryPerformanceCounter function retrieves the current value of the high-resolution performance counter, if one exists.

Parameter	Description

lpliPerformanceCount	Points to a variable that the function sets to the current performance-counter value (in counts). If the installed hardware does not support a high-resolution performance counter, lpliPerformanceCount is set to zero.

Returns

If the installed hardware supports a high-resolution performance counter, the return value is FALSE; otherwise, it is TRUE. To get extended error information, use the GetLastError function.

See Also

QueryPerformanceFrequency


QueryPerformanceFrequency function
QueryPerformanceFrequency (Win32)

BOOL QueryPerformanceFrequency(lpliPerformanceFreq)

LARGE_INTEGER *lpliPerformanceFreq;	/* address of current frequency	*/

The QueryPerformanceFrequency function retrieves the frequency of the high-resolution performance counter, if one exists.

Parameter	Description

lpliPerformanceFreq	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, lpliPerformanceFreq is set to zero.

Returns

If the installed hardware supports a high-resolution performance counter, the return value is FALSE; otherwise, it is TRUE. To get extended error information, use the GetLastError function.

See Also

QueryPerformanceCounter


RaiseException function
RaiseException (Win32)

VOID RaiseException(dwExceptionCode, dwExceptionFlags, cArguments, lpArguments)

DWORD dwExceptionCode;	/* exception code	*/
DWORD dwExceptionFlags;	/* continuable exception flag	*/
DWORD cArguments;	/* number of arguments in array	*/
CONST DWORD * lpArguments;	/* address of array of arguments	*/

The RaiseException function raises an exception in the calling thread.

Parameter	Description

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 0xffffffff, Windows NT pops up 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 STATUS_NONCONTINUABLE_EXCEPTION exception.

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

Returns

This function does not return a value.

Comments

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, cArguments, 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

GetExceptionCode, GetExceptionInformation


ReadConsole function
ReadConsole (Win32)

BOOL ReadConsole(hConsoleInput, lpvBuffer, cchToRead, lpcchRead, lpvReserved)

HANDLE hConsoleInput;	/* handle of a console input buffer	*/
LPVOID lpvBuffer;	/* address of buffer to receive data	*/
DWORD cchToRead;	/* number of characters to read	*/
LPDWORD lpcchRead;	/* address of number of characters read	*/
LPVOID lpvReserved;	/* reserved	*/

The ReadConsole function reads character input from the console input buffer and removes it from the buffer.

Parameter	Description

hConsoleInput	Identifies the console input buffer. The handle must have GENERIC_READ access.

lpvBuffer	Points to a buffer that receives the data read from the console input buffer.

cchToRead	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 lpvBuffer parameter should be at least cchToRead * sizeof(TCHAR).

lpcchRead	Points to a 32-bit variable that receives the number of characters actually read.

lpvReserved	Reserved; must be NULL.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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. However, ReadConsole can only be used with a console input buffer handle; ReadFile can also be used with other handles (such as files or pipes). This means that 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 query 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. Such events can only be read by using the ReadConsoleInput function.

See Also

GetConsoleMode, ReadConsoleInput, ReadFile, SetConsoleMode, WriteConsole


ReadConsoleInput function
ReadConsoleInput (Win32)

BOOL ReadConsoleInput(hConsoleInput, pirBuffer, cInRecords, lpcRead)

HANDLE hConsoleInput;	/* handle of a console input buffer	*/
PINPUT_RECORD pirBuffer;	/* address of the buffer for read data	*/
DWORD cInRecords;	/* number of records to read	*/
LPDWORD lpcRead;	/* address of number of records read	*/

The ReadConsoleInput function reads data from a console input buffer and removes it from the buffer.

Parameter	Description

hConsoleInput	Identifies the input buffer. The handle must have GENERIC_READ access.

pirBuffer	Points to an INPUT_RECORD buffer that receives the input buffer data.

cInRecords	Specifies the size, in input records, of the buffer pointed to by the pirBuffer parameter.

lpcRead	Points to a 32-bit variable that receives the number of input records read.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If the number of records requested in the cInRecords 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 (that is, the WaitForSingleObject or WaitForMultipleObjects function) 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.

See Also

FlushConsoleInputBuffer, GetNumberOfConsoleInputEvents, PeekConsoleInput, ReadConsole, ReadFile, WriteConsoleInput


ReadConsoleOutput function
ReadConsoleOutput (Win32)

BOOL ReadConsoleOutput(hConsoleOutput, pchiDestBuffer, coordDestBufferSize, coordDestBufferCoord, psrctSourceRect)

HANDLE hConsoleOutput;	/* handle of a console screen buffer	*/
PCHAR_INFO pchiDestBuffer;	/* address of buffer that receives data	*/
COORD coordDestBufferSize;	/* column-row size of destination buffer	*/
COORD coordDestBufferCoord;	/* upper left cell to write to	*/
PSMALL_RECT psrctSourceRect;	/* address of rectangle to read from	*/

The ReadConsoleOutput function reads character and color attribute data from a specified rectangular block of character cells in a console screen buffer, and the function writes the data to a rectangular block at a given location in the destination buffer.

Parameter	Description

hConsoleOutput	Identifies the screen buffer. The handle must have GENERIC_READ access.

pchiDestBuffer	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 coordDestBufferSize parameter.

coordDestBufferSize	Specifies the size, in character cells, of the pchiDestBuffer parameter. The X member of the COORD structure is the number of columns; the Y member is the number of rows.

coordDestBufferCoord	Specifies the coordinates of the upper left cell in the pchiDestBuffer parameter to receive the data read from the screen buffer. The X member of the COORD structure is the column, and the Y member is the row.

psrctSourceRect	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 to read. On output, the structure members specify the actual rectangle that was copied from.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 psrctSourceRect parameter specifies the size and location of the block to read from the screen buffer. A destination rectangle of the same size is located with its upper left cell at the coordinates of the coordDestBufferCoord parameter in the pchiDestBuffer array. Data read from the cells in the screen buffer source rectangle is copied to the corresponding cells in the destination buffer. Where the corresponding cell is outside the boundaries of the destination buffer rectangle (whose dimensions are specified by the coordSrcBufferSize 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 there is no screen buffer data available to be read.

Before ReadConsoleOutput returns, it sets the members of the structure pointed to by the psrctSourceRect parameter to the actual screen buffer rectangle whose cells were copied into the destination buffer. This reflects the cells in the source rectangle for which there existed a corresponding cell in the destination buffer, and it clips the dimensions of the source rectangle to the boundaries of the screen buffer.

If the rectangle specified by psrctSourceRect 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 psrctSourceRect 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.

See Also

ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, WriteConsoleOutput


ReadConsoleOutputAttribute function
ReadConsoleOutputAttribute (Win32)

BOOL ReadConsoleOutputAttribute(hConsoleOutput, lpwAttribute, cReadCells, coordReadCoord, lpcNumberRead)

HANDLE hConsoleOutput;	/* handle of a console screen buffer	*/
LPWORD lpwAttribute;	/* address of buffer to receive attributes	*/
DWORD cReadCells;	/* number of character cells to read from	*/
COORD coordReadCoord;	/* coordinates of first cell to read from	*/
LPDWORD lpcNumberRead;	/* address of number of cells read from	*/

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.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer. The handle must have GENERIC_READ access.

lpwAttribute	Points to a buffer that receives the attributes read from the screen buffer.

cReadCells	Specifies the number of screen buffer character cells from which to read. The size of the buffer pointed to by the lpwAttribute parameter should be cReadCells * sizeof(WORD).

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

lpcNumberRead	Points to a 32-bit variable that receives the number of attributes actually read.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If the number of attributes to 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 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

ReadConsoleOutput, ReadConsoleOutputCharacter, WriteConsoleOutput, WriteConsoleOutputAttribute, WriteConsoleOutputCharacter


ReadConsoleOutputCharacter function
ReadConsoleOutputCharacter (Win32)

BOOL ReadConsoleOutputCharacter(hConsoleOutput, lpReadBuffer, cchRead, coordReadCoord, lpcNumberRead)

HANDLE hConsoleOutput;	/* handle of a console screen buffer	*/
LPTSTR lpReadBuffer;	/* address of buffer to receive characters	*/
DWORD cchRead;	/* number of character cells to read from	*/
COORD coordReadCoord;	/* coordinates of first cell to read from	*/
LPDWORD lpcNumberRead;	/* address of number of cells read from	*/

The ReadConsoleOutputCharacter function copies a specified number of characters from consecutive cells of a console screen buffer, beginning at a given location.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer. The handle must have GENERIC_READ access.

lpReadBuffer	Points to a buffer that receives the characters read from the screen buffer.

cchRead	Specifies the number of screen buffer character cells from which to read. The size of the buffer pointed to by the lpReadBuffer parameter should be cchRead * sizeof(TCHAR).

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

lpcNumberRead	Points to a 32-bit variable that receives the number of characters actually read.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If the number of characters to 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 read from extends beyond the end of the screen buffer, characters up to the end of the screen buffer are read.

See Also

ReadConsoleOutput, ReadConsoleOutputAttribute, WriteConsoleOutput, WriteConsoleOutputAttribute, WriteConsoleOutputCharacter


ReadEventLog function
ReadEventLog (Win32)

BOOL ReadEventLog(hEventLog, fdwRead, dwRecordNumber, lpvBuffer, cbBuffer, pcbRead, pcbNeeded)

HANDLE hEventLog;	/* handle of event log	*/
DWORD fdwRead;	/* specifies how to read log	*/
DWORD dwRecordNumber;	/* number of first record	*/
LPVOID lpvBuffer;	/* address of buffer for read data	*/
DWORD cbBuffer;	/* number of bytes to read	*/
DWORD *pcbRead;	/* number of bytes read	*/
DWORD *pcbRequired;	/* number of bytes required for next record	*/

The ReadEventLog function reads a whole number of entries from the given event log. The function can be used to read log entries in forward or reverse chronological order.

Parameter	Description

hEventLog	Identifies the event log to read. This handle is returned by the OpenEventLog function.

fdwRead	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 dwRecordNumber parameter. If this flag is used, fdwRead 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.

dwRecordNumber	Specifies the log-entry record number at which the read operation should start. This parameter is ignored unless the fdwRead parameter includes the EVENTLOG_SEEK_READ flag.

lpvBuffer	Points to a buffer for the data read from the event log. This parameter cannot be NULL, even if the cbBuffer parameter is zero.

The buffer will be filled with an EVENTLOGRECORD structure.

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

pcbRead	Points to a variable that receives the number of bytes read by the function.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, OpenEventLog, ReportEvent, EVENTLOGRECORD


ReadFile function
ReadFile (Win32)

BOOL ReadFile(hFile, lpBuffer, nNumberOfBytesToRead, lpNumberOfBytesRead, lpOverlapped)

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

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.

Parameter	Description

hFile	Identifies the file to be read. The file handle must have been created with GENERIC_READ access to the file.

lpBuffer	Points to the buffer that receives the data read from the file.

nNumberOfBytesToRead	Specifies the number of bytes to read from the file.

lpNumberOfBytesRead	Points to the number of bytes read by this call. 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.

lpOverlapped	Points to an OVERLAPPED structure. This structure is required if hFile was created with FILE_FLAG_OVERLAPPED.

This parameter must not be NULL if hFile was created with FILE_FLAG_OVERLAPPED. It must point to a valid OVERLAPPED structure. If hFile was created with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function fails in unpredictable ways.

If hFile was not created 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 was created 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. The calling process can 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 is not created 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

If the return value is TRUE 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.

Comments

If part of the file is locked by another process and the read overlaps the locked portion, this function fails.

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 ReadFile or PeekNamedPipe function call.

When reading from a communications device, ReadFile normally waits until the requested number of bytes has been received. The SetCommTimeouts function can be used to force ReadFile to return with fewer bytes.

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 with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

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

CreateFile, GetOverlappedResult, PeekNamedPipe, ReadFileEx, SetCommTimeouts, WriteFile


ReadFileEx function
ReadFileEx (Win32)

BOOL ReadFileEx(hFile, lpBuffer, nNumberOfBytesToRead, lpOverlapped, lpcr)

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 lpcr;	/* address of completion routine	*/

The ReadFileEx function reads data from a file and reports its completion status asynchronously. This function is an extension to the ReadFile function that enables an application to continue with other processing.

Parameter	Description

hFile	Identifies the file to read. The file handle must have been created with the FILE_FLAG_OVERLAPPED flag and must have GENERIC_READ access to the file.

lpBuffer	Points to the buffer that receives the data read from the file.

nNumberOfBytesToRead	Specifies the number of bytes to read from the file.

lpOverlapped	Points to an OVERLAPPED structure that must be valid for the duration of the read operation. If the calling application can return while the read operation is still pending, do not use a local variable.

lpcr	Points to the completion routine called when the read operation has been completed. For more information about the completion routine, see the description of the FileIOCompletionRoutine function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

If the read operation has not finished, the function returns TRUE. If the calling thread is in an alertable wait (using the SleepEx, WaitForMultipleObjectsEx or WaitForSingleObjectEx function) when the read operation finishes, the completion routine is called and the wait has been completed with a return value of WAIT_IO_COMPLETION.

If the calling thread is not in an alertable wait when the read operation has been completed, the operating system queues the completion routine call until the thread enters an alertable wait.

If ReadFileEx attempts to read past the end of the file, the function returns FALSE and GetLastError returns ERROR_HANDLE_EOF.

Comments

If part of the file is locked by another process and the read overlaps the locked portion, this function fails.

If ReadFileEx attempts to read from a mailslot whose buffer is too small, the function returns FALSE and GetLastError returns ERROR_INSUFFICIENT_BUFFER.

The ReadFileEx function may fail with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

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

CreateFile, ReadFile, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx


ReadProcessMemory function
ReadProcessMemory (Win32)

BOOL ReadProcessMemory(hProcess, lpBaseAddress, lpBuffer, cbRead, lpNumberOfBytesRead)

HANDLE hProcess;	/* handle of the proc whose memory is read	*/
LPCVOID lpBaseAddress;	/* address to start reading	*/
LPVOID lpBuffer;	/* address of buffer to place read data	*/
DWORD cbRead;	/* number of bytes to read	*/
LPDWORD lpNumberOfBytesRead;	/* actual number of bytes read	*/

The ReadProcessMemory function reads memory in a specified process. The entire area to be read must be accessible, or the operation fails.

Parameter	Description

hProcess	Specifies an open handle of a process whose memory is read. The handle must have been created with PROCESS_VM_READ access to the process.

lpBaseAddress	Specifies 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	Specifies the address of a buffer that receives the contents from the address space of the specified process.

cbRead	Specifies the requested number of bytes to read from the specified process.

lpNumberOfBytesRead	Specifies the actual number of bytes transferred into the specified buffer. If lpNumberOfBytesRead is NULL, the parameter is ignored.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function. The function will fail if the requested read operation crosses into an area of the process that is inaccessible.

Comments

This function 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 ReadProcessMemory. 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 above.

See Also

WriteProcessMemory


RegisterEventSource function
RegisterEventSource (Win32)

HANDLE RegisterEventSource(lpszUNCServer, lpszSource)

LPCTSTR lpszUNCServer;	/* server name for source	*/
LPCTSTR lpszSource;	/* source name for registered handle	*/

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.

Parameter	Description

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

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

Returns

If the function succeeds, the return value is a handle that can be used with the ReportEvent function; otherwise, the return value is NULL.

See Also

DeregisterEventSource, ReportEvent


RegCloseKey function
RegCloseKey (Win32)

LONG RegCloseKey(hkey)

HKEY hkey;	/* handle of key to close	*/

The RegCloseKey function releases the handle of the given key.

Parameter	Description

hkey	Identifies the open key to close.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

The handle for a given 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 function
RegConnectRegistry (Win32)

LONG RegConnectRegistry(lpszComputerName, hkey, phkResult)

LPTSTR lpszComputerName;	/* address of name of remote computer	*/
HKEY hkey;	/* predefined registry handle	*/
PHKEY phkResult;	/* address of buffer for remote registry handle	*/

The RegConnectRegistry function establishes a connection to a predefined registry handle on another computer.

Parameter	Description

lpszComputerName	Points to a null-terminated string containing the name of the remote computer. The string has the following form:

\\computername

If lpszComputerName 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.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

When a handle returned by RegConnectRegistry is no longer needed it should be closed by calling RegCloseKey.


RegCreateKey function
RegCreateKey (Win32)

LONG RegCreateKey(hkey, lpszSubKey, phkResult)

HKEY hkey;	/* handle of an open key	*/
LPCTSTR lpszSubKey;	/* address of name of subkey to open	*/
PHKEY phkResult;	/* address of buffer for opened handle	*/

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. New applications should use the RegCreateKeyEx function.

Parameter	Description

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.

lpszSubKey	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, lpszSubKey may be NULL. In that case, the handle returned via 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.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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 lpszSubKey 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).

See Also

RegCloseKey, RegCreateKeyEx, RegDeleteKey, RegOpenKey, RegOpenKeyEx, RegSetValue


RegCreateKeyEx function
RegCreateKeyEx (Win32)

LONG RegCreateKeyEx(hkey, lpszSubKey, dwReserved, lpszClass, fdwOptions, samDesired, lpSecurityAttributes, phkResult, lpdwDisposition)

HKEY hkey;	/* handle of an open key	*/
LPCTSTR lpszSubKey;	/* address of subkey name	*/
DWORD dwReserved;	/* reserved	*/
LPTSTR lpszClass;	/* address of class string	*/
DWORD fdwOptions;	/* 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 dispostion value buffer	*/

The RegCreateKeyEx function creates the specified key. If the key already exists in the registry, the function opens it.

Parameter	Description

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.

lpszSubKey	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. This parameter cannot be NULL.

dwReserved	Reserved; must be zero.

lpszClass	Points to a null-terminated string that specifies the class (object type) of this key. This parameter is ignored if the key already exists.

fdwOptions	Specifies special options for the key. Currently, this parameter can be one of the following values:

Value	Meaning

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

REG_OPTION_NON_VOLATILE	This key is not volatile; the information is stored in a file and is preserved when the system is restarted. The RegSaveKey function saves non-volatile keys.

By default, keys are not volatile. This option is ignored if the key already exists.

The RegSaveKey function only saves non-volatile keys. It does not save volatile keys.

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	Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the new key.

If this parameter is NULL, the key receives a default security descriptor. If the operating system does not support security, this parameter 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.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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_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

RegCreateKey, RegDeleteKey, RegOpenKey, RegOpenKeyEx, RegSaveKey


RegDeleteKey function
RegDeleteKey (Win32)

LONG RegDeleteKey(hkey, lpszSubKey)

HKEY hkey;	/* handle of open key	*/
LPCTSTR lpszSubKey;	/* address of name of subkey to delete	*/

The RegDeleteKey function deletes the specified key. This function cannot delete a key that has subkeys.

Parameter	Description

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 lpszSubKey parameter must be a subkey of the key identified by hkey.

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

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

If the function succeeds, RegDeleteKey removes the specified key from the registration database. The entire key, including all of its values, is removed.

To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

See Also

RegCloseKey, RegCreateKeyEx, RegOpenKeyEx


RegDeleteValue function
RegDeleteValue (Win32)

LONG RegDeleteValue(hkey, lpszValue)

HKEY hkey;	/* handle of key	*/
LPTSTR lpszValue;	/* address of value name	*/

The RegDeleteValue function removes a named value from the given registry key.

Parameter	Description

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

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

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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 function
RegEnumKey (Win32)

LONG RegEnumKey(hkey, iSubKey, lpszName, cchName)

HKEY hkey;	/* handle of key to query	*/
DWORD iSubKey;	/* index of subkey to query	*/
LPTSTR lpszName;	/* address of buffer for subkey name	*/
DWORD cchName;	/* size of subkey buffer	*/

The RegEnumKey function enumerates subkeys of the given 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. New applications should use the RegEnumKeyEx function.

Parameter	Description

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.

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

lpszName	Points to a buffer that receives the name of the subkey, including the termination null character. This function copies only the name of the subkey, not the full key hierarchy, to the buffer.

cchName	Specifies the size, in characters, of the buffer pointed to by the lpszName 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 plus one MAX_PATH characters.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

To enumerate subkeys, an application should initially call the RegEnumKey function with the iSubKey parameter set to zero. The application should then increment the iSubKey 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 iSubKey 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 function
RegEnumKeyEx (Win32)

LONG RegEnumKeyEx(hkey, iSubkey, lpszName, lpcchName, lpdwReserved, lpszClass, lpcchClass, lpftLastWrite)

HKEY hkey;	/* handle of key to enumerate	*/
DWORD iSubkey;	/* index of subkey to enumerate	*/
LPTSTR lpszName;	/* address of buffer for subkey name	*/
LPDWORD lpcchName;	/* address for size of subkey buffer	*/
LPDWORD lpdwReserved;	/* reserved	*/
LPTSTR lpszClass;	/* address of buffer for class string	*/
LPDWORD lpcchClass;	/* address for size of class buffer	*/
PFILETIME lpftLastWrite;	/* address for time key last written to	*/

The RegEnumKeyEx function enumerates subkeys of the given 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.

Parameter	Description

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.

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

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

lpcchName	Points to a variable that specifies the size, in characters, of the buffer specified by the lpszName parameter. This size should include the terminating null character. When the function returns, the variable pointed to by lpcchName contains the number of characters stored in the buffer. The count returned does not include the terminating null character.

lpdwReserved	Reserved; must be NULL.

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

lpcchClass	Points to a variable that specifies the size, in characters, of the buffer specified by the lpszClass parameter. The size should include the terminating null character. When the function returns, lpcchClass contains the number of characters stored in the buffer. The count returned does not include the terminating null charater. This parameter can be NULL only if lpszClass is NULL.

lpftLastWrite	Points to a variable that receives the time the enumerated subkey was last written to.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

To enumerate subkeys, an application should initially call the RegEnumKeyEx function with the iSubKey parameter set to zero. The application should then increment the iSubKey parameter and call RegEnumKeyEx until there are no more subkeys (until the function returns ERROR_NO_MORE_ITEMS).

The application can also set iSubKey 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

RegDeleteKey, RegEnumKey


RegEnumValue function
RegEnumValue (Win32)

LONG RegEnumValue(hkey, iValue, lpszValue, lpcchValue, lpdwReserved, lpdwType, lpbData, lpcbData)

HKEY hkey;	/* handle of key to query	*/
DWORD iValue;	/* index of value to query	*/
LPTSTR lpszValue;	/* address of buffer for value string	*/
LPDWORD lpcchValue;	/* address for size of value buffer	*/
LPDWORD lpdwReserved;	/* reserved	*/
LPDWORD lpdwType;	/* address of buffer for type code	*/
LPBYTE lpbData;	/* address of buffer for value data	*/
LPDWORD lpcbData;	/* address for size of data buffer	*/

The RegEnumValue function enumerates the values for the given open registry key. The function copies one indexed value name and data block for the key each time it is called.

Parameter	Description

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.

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

lpszValue	Points to a buffer that receives the name of the value, including the terminating null character.

lpcchValue	Points to a variable that specifies the size, in characters, of the buffer pointed to the lpszValue parameter. This size should include the terminating null character. When the function returns, the variable pointed to by lpcchValue contains the number of characters stored in the buffer. The count returned does not include the terminating null character.

lpdwReserved	Reserved; must be NULL.

lpdwType	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 word. This is the most common format for computers running Windows NT.

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

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 lpdwType parameter can be NULL if the type code is not required.

lpbData	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 lpbData 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 lpbData is NULL.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

To enumerate values, an application should initially call the RegEnumValue function with the iValue parameter set to zero. The application should then increment iValue and call the RegEnumValue function until there are no more values (until the function returns ERROR_NO_MORE_ITEMS).

The application can also set iValue 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 ReqQueryInfoKey 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 function
RegFlushKey (Win32)

LONG RegFlushKey(hkey)

HKEY hkey;	/* handle of key to write	*/

The RegFlushKey function writes all the attributes of the given open key into the registry.

Parameter	Description

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

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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 110% certainty that registry changes are on disk. If you don't know whether a RegFlushKey call is required, it probably isn't.

See Also

RegCloseKey, RegDeleteKey


RegGetKeySecurity function
RegGetKeySecurity (Win32)

LONG RegGetKeySecurity(hkey, SecInf, pSecDesc, lpcbSecDesc)

HKEY hkey;	/* open handle of key to set	*/
SECURITY_INFORMATION SecInf;	/* descriptor contents	*/
PSECURITY_DESCRIPTOR pSecDesc;	/* address of descriptor for key	*/
LPDWORD lpcbSecDesc;	/* address of size of buffer and descriptor	*/

The RegGetKeySecurity function retrieves a copy of the security descriptor protecting the given open registry key.

Parameter	Description

hkey	Identifies an open key for which to retrieve the security descriptor.

SecInf	Specifies a SECURITY_INFORMATION structure that indicates the requested security information.

pSecDesc	Points to a buffer that receives a copy of the requested security descriptor.

lpcbSecDesc	Points to a variable that specifies the size, in bytes, of the buffer pointed to by the pSecDesc parameter. When the function returns, the variable contains the number of bytes written to the buffer.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

If the buffer specified by the pSecDesc parameter is too small, the function returns ERROR_INSUFFICIENT_BUFFER and the lpcbSecDesc parameter contains the number of bytes required for the requested security descriptor.

To read the security descriptor for the given 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).

See Also

RegDeleteKey, RegOpenKeyEx, RegSetKeySecurity


RegLoadKey function
RegLoadKey (Win32)

LONG RegLoadKey(hkey, lpszSubKey, lpszFile)

HKEY hkey;	/* handle of open key	*/
LPCTSTR lpszSubKey;	/* address of name of subkey	*/
LPCTSTR lpszFile;	/* address of filename for registry information	*/

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.

Parameter	Description

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.

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

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

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

A call to RegLoadKey fails if the calling process does not have the SE_RESTORE_PRIVILEGE privilege.

If hkey is a handle returned by RegConnectRegistry, then the path specified in lpszFile is relative to the remote computer.

See Also

RegDeleteKey, RegReplaceKey, RegRestoreKey, RegSaveKey, RegUnloadKey


RegNotifyChangeKeyValue function
RegNotifyChangeKeyValue (Win32)

LONG RegNotifyChangeKeyValue(hkey, fWatchSubTree, fdwNotifyFilter, hEvent, fAsync)

HKEY hkey;	/* handle of key to watch	*/
BOOL fWatchSubTree;	/* flag for subkey notification	*/
DWORD fdwNotifyFilter;	/* changes to be reported	*/
HANDLE hEvent;	/* handle of signaled event	*/
BOOL fAsync;	/* flag for asynchronous reporting	*/

The RegNotifyChangeKeyValue function indicates when a registry key or any of its subkeys has changed.

Parameter	Description

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

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

fdwNotifyFilter	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

Changes to key names that occur in the specified key or in the specified key and its subkeys cause a change notification. This includes key creations and deletions.

REG_NOTIFY_CHANGE_ATTRIBUTES

Attribute changes that occur in a key or in a key and its subkeys cause a change notification.

REG_NOTIFY_CHANGE_LAST_SET

Changes to the last write time that occur in a key or in a key and its subkeys cause a change notification.

REG_NOTIFY_CHANGE_SECURITY

Security-descriptor changes that occur in a key or in a key and its subkeys cause a change notification.

hEvent	Identifies an event. If the fAsync parameter is TRUE, the function returns immediately and changes are reported by signaling this event. If fAsync is FALSE, hEvent is ignored.

fAsync	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 given 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 fAsync parameter cannot be TRUE.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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 function
RegOpenKey (Win32)

LONG RegOpenKey(hkey, lpszSubKey, phkResult)

HKEY hkey;	/* handle of open key	*/
LPCTSTR lpszSubKey;	/* address of name of subkey to open	*/
PHKEY phkResult;	/* address of handle of open key	*/

The RegOpenKey function opens the specified key. This function is provided for compatibility with Windows version 3.1. New applications should use the RegOpenKeyEx function.

Parameter	Description

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.

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

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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

RegCreateKey, RegCreateKeyEx, RegDeleteKey, RegOpenKeyEx


RegOpenKeyEx function
RegOpenKeyEx (Win32)

LONG RegOpenKeyEx(hkey, lpszSubKey, dwReserved, samDesired, phkResult)

HKEY hkey;	/* handle of open key	*/
LPCTSTR lpszSubKey;	/* address of name of subkey to open	*/
DWORD dwReserved;	/* reserved	*/
REGSAM samDesired;	/* security access mask	*/
PHKEY phkResult;	/* address of handle of open key	*/

The RegOpenKeyEx function opens the specified key.

Parameter	Description

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

lpszSubKey	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 perviously opened.

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

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

Unlike the RegCreateKeyEx function, the RegOpenKeyEx function does not create the specified key if the key does not exist in the registry.

See Also

RegCreateKeyEx, RegDeleteKey, RegOpenKey


RegQueryInfoKey function
RegQueryInfoKey (Win32)

LONG RegQueryInfoKey (hkey, lpszClass, lpcchClass, lpdwReserved, lpcSubKeys, lpcchMaxSubkey, lpcchMaxClass, lpcValues, lpcchMaxValueName, lpcbMaxValueData, lpcbSecurityDescriptor, lpftLastWriteTime)

HKEY hkey;	/* handle of key to query	*/
LPTSTR lpszClass;	/* address of buffer for class string	*/
LPDWORD lpcchClass;	/* address of size of class string buffer	*/
LPDWORD lpdwReserved;	/* reserved	*/
LPDWORD lpcSubKeys;	/* address of buffer for number of subkeys	*/
LPDWORD lpcchMaxSubkey;	/* address of buffer for longest subkey name length	*/
LPDWORD lpcchMaxClass;	/* address of buffer for longest class string length	*/
LPDWORD lpcValues;	/* address of buffer for number of value entries	*/
LPDWORD lpcchMaxValueName;	/* address of buffer for longest value name length	*/
LPDWORD lpcbMaxValueData;	/* 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	*/

The RegQueryInfoKey function retrieves information about a specified registry key.

Parameter	Description

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

lpszClass	Points to a buffer that receives the key's class name.

lpcchClass	Points to a variable that specifies the size, in characters, of the buffer pointed to by the lpszClass 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.

lpdwReserved	Reserved; must be NULL.

lpcSubKeys	Points to a variable that receives the number of subkeys contained by the specified key.

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

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

lpcValues	Points to a variable that receives the number of values associated with the key.

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

lpcbMaxValueData	Points to a variable that receives the length, in bytes, of the longest data component among the key's values.

lpcbSecurityDescriptor	Points to a variable that receives the length, in bytes, of the key's security descriptor.

lpftLastWriteTime	Points to a variable that receives a FILETIME structure, indicating the last time the key or any of its value entries was modified.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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

RegDeleteKey, RegEnumKey, RegEnumKeyEx, RegEnumValue, RegQueryValue, RegQueryValueEx


RegQueryValue function
RegQueryValue (Win32)

LONG RegQueryValue(hkey, lpszSubKey, lpszValue, pcbValue)

HKEY hkey;	/* handle of key to query	*/
LPCTSTR lpszSubKey;	/* address of name of subkey to query	*/
LPTSTR lpszValue;	/* address of buffer for returned string	*/
PLONG pcbValue;	/* address of buffer for size of returned string	*/

The RegQueryValue function retrieves the value associated with the unnamed value for a specified key in the registry. Values in the Windows NT 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. New applications should use the RegQueryValueEx function.

Parameter	Description

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

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

lpszValue	Points to a buffer that receives the value associated with the lpszSubKey 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 lpszValue is NULL, and pcbValue is not NULL, the function places the size in bytes of the data referenced by the value key, including the NULL terminator, into the variable pointed to by pcbValue. This lets an application determine how to best pre-allocate a buffer for the value key's data.

pcbValue	Points to a variable specifying the size, in bytes, of the buffer pointed to by the lpszValue parameter. When the function returns, this variable contains the size of the data copied to lpszValue, including the terminating NULL character.

If the buffer specified by lpszValue 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 pcbValue.

If lpszValue is NULL, the function returns ERROR_SUCCESS, and stores the size of the string, in bytes, into the variable pointed to by pcbValue. 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 pcbValue always incudes the size of the terminating NULL character in the string.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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 lpszValue parameter.

See Also

RegEnumKey, RegEnumKeyEx, RegEnumValue, RegQueryInfoKey, RegQueryValueEx, RegSetValue, RegSetValueEx


RegQueryValueEx function
RegQueryValueEx (Win32)

LONG RegQueryValueEx(hkey, lpszValueName, lpdwReserved, lpdwType, lpbData, lpcbData)

HKEY hkey;	/* handle of key to query	*/
LPTSTR lpszValueName;	/* address of name of value to query	*/
LPDWORD lpdwReserved;	/* reserved	*/
LPDWORD lpdwType;	/* address of buffer for value type	*/
LPBYTE lpbData;	/* address of data buffer	*/
LPDWORD lpcbData;	/* address of data buffer size	*/

The RegQueryValueEx function retrieves the type and data for a specified value name associated with an open registry key.

Parameter	Description

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

lpszValueName	Points to a null-terminated string containing the name of the value to be queried.

lpdwReserved	Reserved; must be NULL.

lpdwType	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 word. This is the most common format for computers running Windows NT.

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

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 lpdwType parameter can be NULL if the type is not required.

lpbData	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 lpbData parameter. When the function returns, this variable contains the size of the data copied to lpbData.

If the buffer specified by lpbData 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 lpbData is NULL, and lpcbData is non-NULL, the function returns ERROR_SUCCESS, and stores the size of the data, in bytes, into 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 may be NULL only if lpbData is NULL.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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

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, RegEnumKey, RegEnumKeyEx, RegEnumValue, RegQueryInfoKey, RegQueryValue


RegReplaceKey function
RegReplaceKey (Win32)

LONG RegReplaceKey(hkey, lpszSubKey, lpszNewFile, lpszBackupFile)

HKEY hkey;	/* handle of open key	*/
LPCTSTR lpszSubKey;	/* address of name of subkey	*/
LPCTSTR lpszNewFile;	/* address of filename for file with new data	*/
LPCTSTR lpszBackupFile;	/* address of filename for backup file	*/

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.

Parameter	Description

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

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

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

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

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

The file specified by the lpszNewFile parameter remains open until the system is restarted.

A process must have the SE_RESTORE_NAME privilege to call this function. For more information about privileges, see Security.

If hkey is a handle  returned by RegConnectRegistry, then the paths specified in lpszNewFile and lpszBackupFile are relative to the remote computer.

See Also

RegDeleteKey, RegLoadKey, RegRestoreKey


RegRestoreKey function
RegRestoreKey (Win32)

LONG RegRestoreKey(hkey, lpszFile, fdw)

HKEY hkey;	/* handle of key where restore begins	*/
LPCTSTR lpszFile;	/* address of filename containing saved tree	*/
DWORD fdw;	/* optional flags	*/

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.

Parameter	Description

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 lpszFile parameter.

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

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

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

If the calling process does not have the SE_RESTORE_NAME privilege or if any subkeys of the hkey parameter are open, ReqRestoreKey fails. For more information about privileges, see Security.

This function replaces the keys and values below the given 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 lpszFile 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 lpszFile 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 lpszFile is relative to the remote computer.

See Also

RegDeleteKey, RegLoadKey, RegReplaceKey, RegSaveKey


RegSaveKey function
RegSaveKey (Win32)

LONG RegSaveKey(hkey, lpszFile, lpsa)

HKEY hkey;	/* handle of key where save begins	*/
LPCTSTR lpszFile;	/* address of filename to save to	*/
LPSECURITY_ATTRIBUTES lpsa;	/* address of security structure	*/

The RegSaveKey function saves the given key and all of its subkeys and values to a new file.

Parameter	Description

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

lpszFile	Points to a null-terminated string containing the name of the file in which the given 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.

lpsa	Points to a SECURITY_ATTRIBUTES structure for the new file. If this parameter is NULL, the file receives a default security descriptor.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

If hkey represents a key on a remote computer, the path described by lpszFile is relative to the remote computer.

The caller of this function must posses the SeBackupPrivilege security privilege.

The RegSaveKey function only saves non-volatile keys. It does not save volatile keys. A key is made volatile or non-volatile at its creation; see RegCreateKeyEx.

See Also

RegCreateKeyEx, RegDeleteKey, RegLoadKey, RegReplaceKey, RegRestoreKey


RegSetKeySecurity function
RegSetKeySecurity (Win32)

LONG RegSetKeySecurity(hkey, si, psd)

HKEY hkey;	/* open handle of key to set	*/
SECURITY_INFORMATION si;	/* descriptor contents	*/
PSECURITY_DESCRIPTOR psd;	/* address of descriptor to for key	*/

The RegSetKeySecurity function sets the security of an open registry key.

Parameter	Description

hkey	Identifies an open key for which the security descriptor is set.

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

psd	Points to a SECURITY_DESCRIPTOR structure that specifies the security attributes to set for the specified key.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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.

For more information about privileges, see Security.

See Also

RegDeleteKey, RegGetKeySecurity


RegSetValue function
RegSetValue (Win32)

LONG RegSetValue(hkey, lpszSubKey, fdwType, lpszData, cbData)

HKEY hkey;	/* handle of key to set value for	*/
LPCTSTR lpszSubKey;	/* address of subkey name	*/
DWORD fdwType;	/* type of value	*/
LPCTSTR lpszData;	/* address of value data	*/
DWORD cbData;	/* size of value data	*/

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. New applications should use the RegSetValueEx function, which allows an application to set any number of named values of any data type.

Parameter	Description

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

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

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

lpszData	Points to a null-terminated string containing the value to set for the given key.

cbData	Specifies the length, in characters, of the string pointed to by the lpszData parameter, not including the terminating null character.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

If the key specified by the lpszSubKey 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 configuration registry. This will help the registry perform efficiently.

The key identified by hkey 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 lpszData parameter must be an ANSI character string. The string is converted to Unicode before it is stored in the registry.

See Also

RegFlushKey, RegQueryValue, RegQueryValueEx, RegSetValueEx


RegSetValueEx function
RegSetValueEx (Win32)

LONG RegSetValueEx(hkey, lpszValueName, dwReserved, fdwType, lpbData, cbData)

HKEY hkey;	/* handle of key to set value for	*/
LPCTSTR lpszValueName;	/* address of value to set	*/
DWORD dwReserved;	/* reserved	*/
DWORD fdwType;	/* flag for value type	*/
CONST BYTE * lpbData;	/* address of value data	*/
DWORD cbData;	/* size of value data	*/

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 given key.

Parameter	Description

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

lpszValueName	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 fdwType parameter is the REG_SZ type, this function sets the same value the RegSetValue function would set.

dwReserved	Reserved; must be zero.

fdwType	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 word. This is the most common format for computers running Windows NT.

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

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.

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

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise, it is an error value.

Comments

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 fdwType 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 lpbData parameter must be an ANSI character string. The string is converted to Unicode before it is stored in the registry.

See Also

RegFlushKey, RegQueryValue, RegQueryValueEx, RegSetValue


RegUnLoadKey function
RegUnLoadKey (Win32)

LONG RegUnLoadKey(hkey, lpszSubKey)

HKEY hkey;	/* handle of open key	*/
LPCTSTR lpszSubKey;	/* address of name of subkey to unload	*/

The RegUnLoadKey function unloads the specified key and subkeys from the registry.

Parameter	Description

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

lpszSubKey	Points to a null-terminated string containing the name of the subkey to be unloaded. The key referred to by the lpszSubKey parameter must have been created by using the RegLoadKey function.

Returns

If the function succeeds, the return value is ERROR_SUCCESS. Otherwise, it is an error code.

Comments

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

The calling process must have the SE_RESTORE_NAME privilege. For more information about privileges, see Security.

See Also

RegDeleteKey, RegLoadKey, RegRestoreKey


ReleaseMutex function
ReleaseMutex (Win32)

BOOL ReleaseMutex(hMutex)

HANDLE hMutex;	/* handle of mutex object	*/

The ReleaseMutex function releases ownership of the specified mutex object.

Parameter	Description

hMutex	Identifies the mutex object. The CreateMutex or OpenMutex function returns this handle.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


ReleaseSemaphore function
ReleaseSemaphore (Win32)

BOOL ReleaseSemaphore(hSemaphore, cReleaseCount, lplPreviousCount)

HANDLE hSemaphore;	/* handle of the semaphore object	*/
LONG cReleaseCount;	/* amount to add to current count	*/
LPLONG lplPreviousCount;	/* address of previous count	*/

The ReleaseSemaphore function increases the count of the specified semaphore object by a specified amount.

Parameter	Description

hSemaphore	Identifies the semaphore object. The CreateSemaphore or OpenSemaphore function returns this handle, which must have SEMAPHORE_MODIFY_STATE access.

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, MsgWaitForMultipleObjects, OpenSemaphore, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


RemoveDirectory function
RemoveDirectory (Win32)

BOOL RemoveDirectory(lpszDir)

LPCTSTR lpszDir;	/* address of directory to remove	*/

The RemoveDirectory function deletes an existing empty directory.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CreateDirectory


ReportEvent function
ReportEvent (Win32)

BOOL ReportEvent(hEventSource, fwEventType, fwCategory, IDEvent, pUserSid, cStrings, cbData, plpszStrings, lpvData)

HANDLE hEventSource;	/* handle returned by RegisterEventSource	*/
WORD fwEventType;	/* event type to log	*/
WORD fwCategory;	/* event category	*/
DWORD IDEvent;	/* event identifier	*/
PSID pUserSid;	/* user security identifier (optional)	*/
WORD cStrings;	/* number of strings to merge with message	*/
DWORD cbData;	/* size of raw (binary) data (in bytes)	*/
LPCTSTR *plpszStrings;	/* array of strings to merge with message	*/
LPVOID lpvData;	/* address of binary data	*/

The ReportEvent function writes an entry at the end of the given event log.

Parameter	Description

hEventSource	Identifies the event log. This handle is returned by the RegisterEventSource function.

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

fwCategory	Specifies the event category. This is source-specific information; the category can have any value.

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

pUserSid	Points to the current user's security identifier. This parameter can be NULL if the security identifier is not required.

cStrings	Specifies the number of strings in the array pointed to by the plpszStrings parameter. A value of zero indicates that no strings are present.

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

plpszStrings	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 cStrings is zero.

lpvData	Points to the buffer containing the binary data. This parameter must be a valid pointer (or NULL), even if the cbData parameter is zero.

Returns

If the function succeeds, the return value is TRUE, indicating that the entry was written to the log. If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

Comments

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 hEventSource 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


ResetEvent function
ResetEvent (Win32)

BOOL ResetEvent(hEvent)

HANDLE hEvent;	/* handle of event object	*/

The ResetEvent function sets the state of the specified event object to nonsignaled.

Parameter	Description

hEvent	Identifies the event object. The CreateEvent or OpenEvent function returns this handle, which must have EVENT_MODIFY_STATE access.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


ResumeThread function
ResumeThread (Win32)

DWORD ResumeThread(hThread)

HANDLE hThread;	/* identifies thread to restart	*/

The ResumeThread function decrements a thread's suspend count. When the suspend count is decremented to zero, the execution of the thread is resumed.

Parameter	Description

hThread	Specifies a handle for the thread to be restarted. The handle must have THREAD_SUSPEND_RESUME access to the thread.

Returns

If the function succeeds, the return value is the thread's previous suspend count. Otherwise, the return value is 0xFFFFFFFF. To get extended error information, use the GetLastError function.

Comments

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 resultant 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. The ResumeThread function must be called the return value minus one times before the thread will start running.

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 if they are suspended.

See Also

SuspendThread


ScrollConsoleScreenBuffer function
ScrollConsoleScreenBuffer (Win32)

BOOL ScrollConsoleScreenBuffer(hConsoleOutput, psrctSourceRect, psrctClipRect, coordDestOrigin, pchiFill)

HANDLE hConsoleOutput;	/* handle of a console screen buffer	*/
PSMALL_RECT psrctSourceRect;	/* address of screen buffer rect. to move	*/
PSMALL_RECT psrctClipRect;	/* address of affected screen buffer rect.	*/
COORD coordDestOrigin;	/* new location of screen buffer rect.	*/
PCHAR_INFO pchiFill;	/* address of fill character and color	*/

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.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer. The handle must have GENERIC_WRITE access.

psrctSourceRect	Points to a SMALL_RECT structure whose members specify the upper left and lower right coordinates of the screen buffer rectangle to be moved.

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

coordDestOrigin	Specifies the upper left corner of the new location of the psrctSourceRect contents.

pchiFill	Points to a CHAR_INFO structure that specifies the character and color attributes to be used in filling the cells within the intersection of psrctSourceRect and psrctClipRect that were left empty as a result of the move.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

ScrollConsoleScreenBuffer copies the contents of a rectangular region of a screen buffer, the psrctSourceRect parameter, to another area of the screen buffer. The target rectangle has the same dimensions as psrctSourceRect with its upper left corner at the coordinates specified by the coordDestOrigin parameter. Those parts of psrctSourceRect, that do not overlap with the target rectangle are filled in with the character and color attributes specified by the pchiFill parameter.

The clipping rectangle applies to changes made in both the psrctSourceRect and the target rectangle. For example, if the clipping rectangle does not include a region that would have been filled by the contents of pchiFill, 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 psrctSourceRect is the region contained by (0,0) and (19,19) and coordDestOrigin 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). The changes to the screen buffer are also clipped according to psrctClipRect, 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.

See Also

SetConsoleWindowInfo


SearchPath function
SearchPath (Win32)

DWORD SearchPath(lpszPath, lpszFile, lpszExtension, cchReturnBuffer, lpszReturnBuffer, plpszFilePart)

LPCTSTR lpszPath;	/* address of the search path	*/
LPCTSTR lpszFile;	/* address of the filename	*/
LPCTSTR lpszExtension;	/* address of the extension	*/
DWORD cchReturnBuffer;	/* size, in characters, of the buffer	*/
LPTSTR lpszReturnBuffer;	/* address of buffer for found filename	*/
LPTSTR *plpszFilePart;	/* address of pointer to file part	*/

The SearchPath function searches for the specified file.

Parameter	Description

lpszPath	Points to a null-terminated string that specifies the path to be searched for the file. If lpszPath is NULL, the 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	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.

lpszFile	Points to a null-terminated string that specifies the name of the file to search for.

lpszExtension	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 extension must be a period (.). The extension is added only if the specified filename does not end with an extension.

If a file extension is not required or if the filename contains an extension, this parameter can be NULL.

cchReturnBuffer	Specifies the length, in characters, of the buffer that receives the valid path and filename.

lpszReturnBuffer	Points to the buffer for the valid path and filename of the file found.

plpszFilePart	Specifies the address (within lpszReturnBuffer) of the last component of the valid path and filename. This is the address of the character immediately following the final backslash (\) in the path; it points to the filename.

Returns

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 return value is greater than cchReturnBuffer, 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, use the GetLastError function.

See Also

FindFirstFile, FindNextFile


SetCommBreak function
SetCommBreak (Win32)

BOOL SetCommBreak(hCommDev)

HANDLE hCommDev;	/* handle of the communications device	*/

The SetCommBreak function suspends character transmission for a given communications device and places the transmission line in a break state until the ClearCommBreak function is called.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The SetCommBreak function does not flush data that has not been transmitted.

See Also

ClearCommBreak


SetCommMask function
SetCommMask (Win32)

BOOL SetCommMask(hCommDev, fdwEvtMask)

HANDLE hCommDev;	/* handle of the communications device	*/
DWORD fdwEvtMask;	/* mask that identifies enabled events	*/

The SetCommMask function specifies a set of events to be monitored for a given communications device.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

fdwEvtMask	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	Any 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The SetCommMask function specifies the set of events that can be monitored for a particular communications resource. To wait for one of the events to occur, a handle to the communications resource can be specified in a call to the WaitCommEvent function. To get the current event mask of a communications resource, use the GetCommMask function.

If SetCommMask is called for a communications resource while a wait is pending for that resource, WaitCommEvent returns an error.

See Also

GetCommMask, WaitCommEvent


SetCommState function
SetCommState (Win32)

BOOL SetCommState(hCommDev, lpdcb)

HANDLE hCommDev;	/* handle of the communications device	*/
LPDCB lpdcb;	/* address of device control block structure	*/

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.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The SetCommState function uses a DCB structure to specify the desired configuration. The GetCommState function returns the current configuration.

If you are interested in setting 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, GetCommState, DCB


SetCommTimeouts function
SetCommTimeouts (Win32)

BOOL SetCommTimeouts(hCommDev, lpctmo)

HANDLE hCommDev;	/* handle of the communications device	*/
LPCOMMTIMEOUTS lpctmo;	/* address of comm timeout structure	*/

The SetCommTimeouts function sets the timeout parameters for all read and write operations on a given communications device.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

lpctmo	Points to a COMMTIMEOUTS structure that contains the new timeout values.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetCommTimeouts, ReadFile, ReadFileEx, WriteFile, WriteFileEx, COMMTIMEOUTS


SetComputerName function
SetComputerName (Win32)

BOOL SetComputerName(lpszName)

LPCTSTR lpszName;	/* address of new computer name	*/

The SetComputerName function sets the computer name to be used the next time the system is restarted.

Parameter	Description

lpszName	Points to a null-terminated character string that specifies the new computer name. The name must not be longer than MAX_COMPUTERNAME_LENGTH characters.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Applications using this function must have administrator rights.

See Also

GetComputerName


SetConsoleActiveScreenBuffer function
SetConsoleActiveScreenBuffer (Win32)

BOOL SetConsoleActiveScreenBuffer(hConsoleOutput)

HANDLE hConsoleOutput;	/* handle of console screen buffer	*/

The SetConsoleActiveScreenBuffer function sets the specified screen buffer to be the currently displayed console screen buffer.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
SetConsoleCP (Win32)

BOOL SetConsoleCP(IDCodePage)

UINT IDCodePage;	/* code page to set	*/

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.

Parameter	Description

IDCodePage	Identifies the code page to set. The identifiers of the code pages available on the local computer are stored in the registry under the key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 query a console's output code page, use the SetConsoleOutputCP and GetConsoleOutputCP functions.

See Also

GetConsoleCP, GetConsoleOutputCP, SetConsoleOutputCP


SetConsoleCtrlHandler function
SetConsoleCtrlHandler (Win32)

BOOL SetConsoleCtrlHandler(pHandlerRoutine, fAdd)

PHANDLER_ROUTINE pHandlerRoutine;	/* address of handler function	*/
BOOL fAdd;	/* handler to add or remove	*/

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.

Parameter	Description

pHandlerRoutine	Points to the application-defined HandlerRoutine to add or remove. This parameter can be NULL.

fAdd	Specifies whether to add or remove the function pointed to by the pHandlerRoutine parameter from the handler list. If this parameter is TRUE, the handler is added; if it is FALSE, the handler is removed.

If the pHandlerRoutine 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 normally treated as signals (SIGINT and SIGBREAK). When a console window with the keyboard focus receives a CTRL+C or CTRL+BREAK, the signal is normally passed to all processes sharing that console.

CTRL+BREAK is always treated as a signal, but the normal 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, the CTRL_C is passed to the console process and treated as a signal, as discussed above.

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 APIs, or any C run-time functions that call console APIs, may not work reliably during processing of any of the above three signals. 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

GenerateConsoleCtrlEvent, GetConsoleMode, SetConsoleMode


SetConsoleCursorInfo function
SetConsoleCursorInfo (Win32)

BOOL SetConsoleCursorInfo(hConsoleOutput, pcci)

HANDLE hConsoleOutput;	/* handle of console screen buffer	*/
PCONSOLE_CURSOR_INFO pcci;	/* address of cursor information	*/

The SetConsoleCursorInfo function sets the size and visibility of the cursor for the specified console screen buffer.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer. The handle must have GENERIC_WRITE access.

pcci	Points to a CONSOLE_CURSOR_INFO structure containing the new specifications for the screen buffer's cursor.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

GetConsoleCursorInfo, SetConsoleCursorPosition


SetConsoleCursorPosition function
SetConsoleCursorPosition (Win32)

BOOL SetConsoleCursorPosition(hConsoleOutput, coordCursor)

HANDLE hConsoleOutput;	/* handle of console screen buffer	*/
COORD coordCursor;	/* new cursor position coordinates	*/

The SetConsoleCursorPosition function sets the cursor position in the specified console screen buffer.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer. The handle must have GENERIC_WRITE access.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SetConsoleCursorInfo


SetConsoleMode function
SetConsoleMode (Win32)

BOOL SetConsoleMode(hConsole, fdwMode)

HANDLE hConsole;	/* handle of console input or screen buffer	*/
DWORD fdwMode;	/* input or output mode to set	*/

The SetConsoleMode function sets the input mode of a console's input buffer or the output mode of a console screen buffer.

Parameter	Description

hConsole	Identifies a console input buffer or a screen buffer. The handle must have GENERIC_WRITE access.

fdwMode	Specifies the input or output mode to set. If the hConsole 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 the ENABLE_MOUSE_INPUT mode is enabled.

If the hConsole 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 line when it reaches the end of the current row. This causes the lines displayed in the console window to scroll up automatically when the cursor advances beyond the last line in the window. It also causes the contents of the screen buffer to scroll up (discarding the top line of the screen buffer) when the cursor advances beyond the last line in the screen buffer. If this mode is disabled, the last character in the row is overwritten.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 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, ReadConsole, ReadConsoleInput, ReadFile, WriteConsole, WriteFile


SetConsoleOutputCP function
SetConsoleOutputCP (Win32)

BOOL SetConsoleOutputCP(IDCodePage)

UINT IDCodePage;	/* code page to set	*/

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.

Parameter	Description

IDCodePage	Identifies the code page to set. The identifiers of the code pages available on the local computer are stored in the registry under the key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 query a console's input code page, use the SetConsoleCP and GetConsoleCP functions.

See Also

GetConsoleCP, GetConsoleOutputCP, SetConsoleCP


SetConsoleScreenBufferSize function
SetConsoleScreenBufferSize (Win32)

BOOL SetConsoleScreenBufferSize(hConsoleOutput, coordSize)

HANDLE hConsoleOutput;	/* handle of console screen buffer	*/
COORD coordSize;	/* new size in character rows and cols.	*/

The SetConsoleScreenBufferSize function changes the size of the specified console screen buffer.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer. The handle must have GENERIC_WRITE access.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetConsoleScreenBufferInfo, SetConsoleWindowInfo


SetConsoleTextAttribute function
SetConsoleTextAttribute (Win32)

BOOL SetConsoleTextAttribute(hConsoleOutput, wAttr)

HANDLE hConsoleOutput;	/* handle of console screen buffer	*/
WORD wAttr;	/* text and background colors	*/

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.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer. The handle must have GENERIC_READ access.

wAttr	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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

To determine the current color attributes of a screen buffer, call the GetConsoleScreenBufferInfo function.

See Also

GetConsoleScreenBufferInfo, ReadConsole, ReadFile, WriteConsole, WriteFile


SetConsoleTitle function
SetConsoleTitle (Win32)

BOOL SetConsoleTitle(lpszTitle)

LPTSTR lpszTitle;	/* address of new title	*/

The SetConsoleTitle function sets the title bar string for the current console window.

Parameter	Description

lpszTitle	Points to a null-terminated string that contains the string to appear in the title bar of the console window.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetConsoleTitle


SetConsoleWindowInfo function
SetConsoleWindowInfo (Win32)

BOOL SetConsoleWindowInfo(hConsoleOutput, fAbsolute, psrctWindowRect)

HANDLE hConsoleOutput;	/* handle of console screen buffer	*/
BOOL fAbsolute;	/* coordinate type flag	*/
PSMALL_RECT psrctWindowRect;	/* address of new window rectangle	*/

The SetConsoleWindowInfo function sets the current size and position of a console screen buffer's window.

Parameter	Description

hConsoleOutput	Identifies a console screen buffer. The handle must have GENERIC_WRITE access.

fAbsolute	Specifies how the coordinates in the structure pointed to by the psrctWindowRect parameter are used. If fAbsolute 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.

psrctWindowRect	Points to a SMALL_RECT structure that contains values that determine the new upper left and lower right corners of the window.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 psrctWindowRect rectangle (or the calculated top and left coordinates, if fAbsolute 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 and 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, ScrollConsoleScreenBuffer


SetCurrentDirectory function
SetCurrentDirectory (Win32)

BOOL SetCurrentDirectory(lpszCurDir)

LPCTSTR lpszCurDir;	/* address of name of new current directory	*/

The SetCurrentDirectory function changes the current directory for the current process.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


SetDebugErrorLevel function
SetDebugErrorLevel (Win32)

VOID SetDebugErrorLevel(dwLevel)

DWORD dwLevel;	/* debugging error level	*/

The SetDebugErrorLevel function sets the minimum error level at which Windows will generate debugging events and pass them to a debugger.

Parameter	Description

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	The kernel does not report errors. This 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.

Returns

This function does not return a value.

Comments

The debugger calls this function to specify the types of errors that it wants to 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.


SetEndOfFile function
SetEndOfFile (Win32)

BOOL SetEndOfFile(hFile)

HANDLE hFile;	/* handle of file whose EOF is to be set	*/

The SetEndOfFile function moves the end-of-file position for the specified file to the current position of the file pointer.

Parameter	Description

hFile	Identifies the file to have its end-of-file position moved. The file handle must have been created with GENERIC_WRITE access to the file.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

This function can be used to truncate or extend a file. If the file is extended, the contents of the file between the old end-of-file position and the new position are not defined.

See Also

CreateFile


SetEnvironmentVariable function
SetEnvironmentVariable (Win32)

BOOL SetEnvironmentVariable(lpszName, lpszValue)

LPCTSTR lpszName;	/* address of environment variable name	*/
LPCTSTR lpszValue;	/* address of new value for variable	*/

The SetEnvironmentVariable function sets the value of an environment variable for the current process.

Parameter	Description

lpszName	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 lpszValue is not NULL.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetEnvironmentVariable


SetErrorMode function
SetErrorMode (Win32)

UINT SetErrorMode(fuErrorMode)

UINT fuErrorMode;	/* error mode	*/

The SetErrorMode function controls whether Windows handles serious errors or allows the calling application to handle them.

Parameter	Description

fuErrorMode	Specifies the error mode. The flag can be a combination of the following values:

Value	Action

SEM_FAILCRITICALERRORS	Windows does not display the critical-error-handler message box and returns the error to the calling application.

SEM_NOGPFAULTERRORBOX	Windows does not display the general-protection-fault message box. This flag should be set only by debugging applications that handle general protection (GP) faults themselves.

SEM_NOOPENFILEERRORBOX	Windows does not display a message box when it fails to find a file.

Returns

The return value is the previous state of the error-mode flag.


SetEvent function
SetEvent (Win32)

BOOL SetEvent(hEvent)

HANDLE hEvent;	/* handle of event object	*/

The SetEvent function sets the state of the specified event object to signaled.

Parameter	Description

hEvent	Identifies the event object. The CreateEvent or OpenEvent function returns this handle, which must have EVENT_MODIFY_STATE access.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, 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, MsgWaitForMultipleObjects, OpenEvent, PulseEvent, ResetEvent, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


SetFileApisToOEM function
SetFileApisToOEM (Win32)

VOID SetFileApisToOEM(VOID)

The SetFileApisToOEM function sets a group of Win32 APIs to produce OEM character set strings. This is useful for 8-bit console input and output.

Comments

The 8-bit console APIs use the OEM codepage. All other APIs use the ANSI codepage by default. This means that strings returned by the console APIs may not be processed correctly by the other APIs and vice versa. For example, if FindFirstFileA returns a string that contains certain extended ANSI characters, WriteConsoleA will not display the string properly.

The best long-term solution for a console application is to use Unicode. Short of that solution, a console application should use the SetFileApisToOEM function. That function changes the relevant Win32 file functions so that they produce OEM character set strings rather than ANSI character set strings.

When dealing with command lines, a console application should obtain the command line in Unicode form and convert it to OEM form using the relevant character-to-OEM functions. Also, note that argv uses the ANSI character set.

Here is a list of Win32 file functions that are involved in this situation:

_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


SetFileAttributes function
SetFileAttributes (Win32)

BOOL SetFileAttributes(lpFileName, dwFileAttributes)

LPCTSTR lpFileName;	/* address of filename	*/
DWORD dwFileAttributes;	/* address of attributes to set	*/

The SetFileAttributes function sets a file's attributes.

Parameter	Description

lpFileName	Points to a string that specifies the name of the file whose attributes are to be set.

dwFileAttributes	Specifies the file attributes to set for the file. This parameter can be a combination of the following flags. However, all other flags override the FILE_ATTRIBUTE_NORMAL flag.

Attribute	Meaning

FILE_ATTRIBUTE_ARCHIVE

The file is an archive file. Applications use this flag to mark files for backup or removal.

FILE_ATTRIBUTE_NORMAL

The file has no other attributes set. This attribute is valid only if used alone.

FILE_ATTRIBUTE_HIDDEN

The file is hidden. It is not to be included in an ordinary directory listing.

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.

FILE_ATTRIBUTE_ATOMIC_WRITE

Reserved for future use. Do not specify.

FILE_ATTRIBUTE_XACTION_WRITE

Reserved for future use. Do not specify.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetFileAttributes


SetFilePointer function
SetFilePointer (Win32)

DWORD SetFilePointer(hFile, lDistanceToMove, lpDistanceToMoveHigh, dwMoveMethod)

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

The SetFilePointer function moves the file pointer of an open file.

Parameter	Description

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, this function 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.

Returns

If the function succeeds, the return value is the low-order doubleword of the new file pointer, and, if lpDistanceToMoveHigh is non-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. Call GetLastError for extended error information.

If the function fails, and lpDistanceToMoveHigh is non-NULL, the return value is 0xFFFFFFFF and GetLastError will return a value other than NO_ERROR.

Comments

Using this function with a handle to a nonseeking device, such as a pipe or a communications device, has no meaning. Use the GetFileType function to determine the file type for hFile.

A multithreaded application should be careful when setting the file pointer. 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.

Note that, if the return value is 0xFFFFFFFF and lpDistanceToMoveHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed. Here is some sample code that illustrates the 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

ReadFile, ReadFileEx, WriteFile, WriteFileEx


SetFileTime function
SetFileTime (Win32)

BOOL SetFileTime(hFile, lpftCreation, lpftLastAccess, lpftLastWrite)

HANDLE hFile;	/* identifies the file	*/
CONST FILETIME * lpftCreation;	/* time the file was created	*/
CONST FILETIME * lpftLastAccess;	/* time the file was last accessed	*/
CONST FILETIME * lpftLastWrite;	/* time the file was last written	*/

The SetFileTime function sets the date and time that a file was created, last accessed, or last modified.

Parameter	Description

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.

lpftCreation	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. The file allocation table (FAT) file system does not support this time value, so this parameter may be ignored. Both the high-performance file system (HPFS) and the New Technology file system (NTFS) support the creation time value.

lpftLastAccess	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. The FAT file system does not support this time value, so this parameter may be ignored. Both HPFS and NTFS support the access time value.

lpftLastWrite	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. All file systems support this time value.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetFileSize, GetFileTime, GetFileType


SetHandleCount function
SetHandleCount (Win32)

UINT SetHandleCount(cHandles)

UINT cHandles;	/* number of file handles needed	*/

The SetHandleCount function changes the number of file handles available to a process.

The SetHandleCount function is not necessary under the Windows NT implementation of Win32, and in fact has no effect when called under Windows NT.

The SetHandleCount function may be necessary under other implementations of Win32, such as Win32s, in order to increase the default number of available file handles. Under Win32s, this default is 20.

Parameter	Description

cHandles	Specifies the number of file handles needed by the application. The maximum value is implementation-dependent. Under Win32s, the maximum value is 255.

Returns

Under Windows NT, this function has no effect, and the return value is simply the value of the cHandles parameter.

Under other implementations of Win32, such as 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 cHandles parameter.

Comments

Under Windows NT, the maximum number of files that an application can open is determined by the amount of available non-paged memory pool. That is because each open file handle consumes part of that resource.


SetLastError function
SetLastError (Win32)

VOID SetLastError(fdwError)

DWORD fdwError;	/* per-thread error code	*/

The SetLastError function sets the last-error code for the calling thread.

Parameter	Description

fdwError	Specifies the last-error code for this thread.

Comments

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

Win32 API functions that return indications of failure call SetLastError when they fail. With one exception, they do NOT call SetLastError when they succeed. So, if three Win32 API function calls are made, and the first one fails and the second two succeed, the error code stored by the first one is still available after the second two succeed. The exception to this no-write-on-success rule is the TlsGetValue function, which needs to clear the last error code when it succeeds to allow checking the error-free retrieval of NULL values.

Applications can retrieve the value saved by this function by using the GetLastError function. The use of GetLastError is optional; an application need call it only if it is interested in knowing the specific reason for a function failure.

The last-error code value is kept in thread local storage so that multiple threads do not overwrite each other's values.

See Also

GetLastError, SetLastErrorEx, TlsGetValue


SetLastErrorEx function
SetLastErrorEx (Win32)

VOID SetLastErrorEx(fdwError, fdwType)

DWORD fdwError;	/* per-thread error code	*/
DWORD fdwType;	/* error type	*/

The SetLastErrorEx function sets the last-error code and type for the calling thread.

Parameter	Description

fdwError	Specifies the last-error code for this thread.

fdwType	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 value is set without reporting anything to the debugger. This is equivalent to using the SetLastError function.

Comments

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

The Win32 API functions that return indications of failure call the SetLastError function when they fail. If three Win32 API function calls are made and the first one fails and the second two succeed, the error code stored by the first one is still available after the second two succeed.

Applications can retrieve the value saved by this function by using the GetLastError function.

The last-error code value is kept in thread local storage so that multiple threads do not overwrite each other's values.

See Also

GetLastError, SetLastError


SetLocalTime function
SetLocalTime (Win32)

BOOL SetLocalTime(lpst)

CONST SYSTEMTIME * lpst;	/* address of local time to set	*/

The SetLocalTime function sets the current local time and date.

Parameter	Description

lpst	Points to a SYSTEMTIME structure that contains the current local date and time.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The application must have system-time privilege (the SE_SYSTEMTIME_NAME privilege) for this function to succeed. 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 Security.

See Also

AdjustTokenPrivileges, GetLocalTime, GetSystemTime, SYSTEMTIME


SetMailslotInfo function
SetMailslotInfo (Win32)

BOOL SetMailslotInfo(hMailslot, dwReadTimeout)

HANDLE hMailslot;	/* mailslot handle	*/
DWORD dwReadTimeout;	/* read time-out	*/

The SetMailslotInfo function sets the time-out value used by the given mailslot for a read operation.

Parameter	Description

hMailslot	Identifies a mailslot. The CreateMailslot function must create this handle.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


SetNamedPipeHandleState function
SetNamedPipeHandleState (Win32)

BOOL SetNamedPipeHandleState(hNamedPipe, lpdwMode, lpcbMaxCollect, lpdwCollectDataTimeout)

HANDLE hNamedPipe;	/* handle of named pipe	*/
LPDWORD lpdwMode;	/* address of new pipe mode	*/
LPDWORD lpcbMaxCollect;	/* address of max bytes before remote transmission	*/
LPDWORD lpdwCollectDataTimeout;	/* address of max time before remote transmission	*/

The SetNamedPipeHandleState function sets the read mode and the blocking mode of the given named pipe. If the specified handle is to the client end of a named pipe, and the named pipe server process is on a remote computer, the function can also be used to control local buffering.

Parameter	Description

hNamedPipe	Identifies the named pipe instance. This 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.

lpdwMode	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. Set this parameter to NULL if the mode is not being set. Use one of the following read modes:

Value	Meaning

PIPE_READMODE_BYTE

Data is read from the pipe as a stream of bytes. This 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.

Use one of the following wait modes:

Value	Meaning

PIPE_WAIT

Blocking mode is enabled. This 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, the operations are not finished until there is data to read, all data is written, or a client is connected. This 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.

lpcbMaxCollect	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 given 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 specified the FILE_FLAG_WRITE_THROUGH flag in the CreateFile function when the handle was created. Set this parameter to NULL if the collection count is not being set.

lpdwCollectDataTimeout	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. Set this parameter to NULL if the collection count is not being set.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

ConnectNamedPipe, CreateFile, CreateNamedPipe, GetNamedPipeHandleState, ReadFile, WriteFile


SetPriorityClass function
SetPriorityClass (Win32)

BOOL SetPriorityClass(hProcess, fdwPriority)

HANDLE hProcess;	/* handle to the process	*/
DWORD fdwPriority;	/* priority class value	*/

The SetPriorityClass function sets the priority class for the given process. This value together with the priority value of each thread of the process determines each thread's base priority level.

Parameter	Description

hProcess	Identifies the process. The handle must have PROCESS_SET_INFORMATION access.

fdwPriority	Specifies the priority class for the process. Specify one of the following values:

Priority	Meaning

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.

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.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 will scheduling of threads at a lower level take place.

The base priority level of a thread is in the range 1 through 31. Following are the normal base priority levels for each priority class:

Class	Normal base priority

IDLE_PRIORITY_CLASS	4

NORMAL_PRIORITY_CLASS	9 if the window of the process is in the foreground; and 7 if the window is in the background

HIGH_PRIORITY_CLASS	13

REALTIME_PRIORITY_CLASS	24

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

The initial priority class of a process can be specified in the CreateProcess function. If not 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.

Be very careful when manipulating priorities--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.

The following table shows the base priority levels for each combination of priority class and thread priority value. Note that for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, and HIGH_PRIORITY_CLASS, this base level can receive dynamic boosts.

Base	Priority class/Thread priority

31	Real-time class, THREAD_PRIORITY_TIME_CRITICAL

26	Real-time class, THREAD_PRIORITY_HIGHEST

25	Real-time class, THREAD_PRIORITY_ABOVE_NORMAL

24	Real-time class, THREAD_PRIORITY_NORMAL

23	Real-time class, THREAD_PRIORITY_BELOW_NORMAL

22	Real-time class, THREAD_PRIORITY_LOWEST

16	Real-time class, THREAD_PRIORITY_IDLE

15	Idle, normal, or high class, THREAD_PRIORITY_TIME_CRITICAL High class, THREAD_PRIORITY_HIGHEST

14	High class, THREAD_PRIORITY_ABOVE_NORMAL

13	High class, THREAD_PRIORITY_NORMAL

12	High class, THREAD_PRIORITY_BELOW_NORMAL

11	High class, THREAD_PRIORITY_LOWEST  Foreground normal class, THREAD_PRIORITY_HIGHEST

10	Foreground normal class, THREAD_PRIORITY_ABOVE_NORMAL

9	Foreground normal class, THREAD_PRIORITY_NORMAL  Background normal class, THREAD_PRIORITY_HIGHEST

8	Foreground normal class, THREAD_PRIORITY_BELOW_NORMAL  Background normal class, THREAD_PRIORITY_ABOVE_NORMAL

7	Foreground normal class, THREAD_PRIORITY_LOWEST  Background normal class, THREAD_PRIORITY_NORMAL

6	Background normal class, THREAD_PRIORITY_BELOW_NORMAL  Idle class, THREAD_PRIORITY_HIGHEST

5	Background normal class, THREAD_PRIORITY_LOWEST  Idle class, THREAD_PRIORITY_ABOVE_NORMAL

4	Idle class, THREAD_PRIORITY_NORMAL

3	Idle class, THREAD_PRIORITY_BELOW_NORMAL

2	Idle class, THREAD_PRIORITY_LOWEST

1	Idle, normal, or high class, THREAD_PRIORITY_IDLE

See Also

CreateProcess, CreateThread, GetPriorityClass, GetThreadPriority, SetThreadPriority


SetProcessShutdownParameters function
SetProcessShutdownParameters (Win32)

BOOL SetProcessShutdownParameters(dwLevel, dwFlags)

DWORD dwLevel;	/* shutdown priority	*/
DWORD dwFlags;	/* shutdown flags	*/

The SetProcessShutdownParameters function sets shutdown parameters for the currently calling process. This function sets a process's shutdown order relative to the other processes in the system.

Parameter	Description

dwLevel	Specifies the process's shutdown priority 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. The flags can be added together:

Value	Meaning

SHUTDOWN_NORETRY	Specifies whether to retry the shutdown if the specified timeout period expires. If this flag is specified, the system terminates the process without displaying a retry dialog for the user.

Returns

If the function is succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 installable via SetConsoleCtrlHandler. They also get notified in the order specified by the dwLevel parameter.

See Also

GetProcessShutdownParameters


SetStdHandle function
SetStdHandle (Win32)

BOOL SetStdHandle( IDStdHandle, hHandle)

DWORD IDStdHandle;	/* input, output, or error device	*/
HANDLE hHandle;	/* handle to be a standard handle	*/

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.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 "CONIN$" in a call to the CreateFile function to get a handle of a console's input buffer. Similarly, you can specify "CONOUT$" to get a handle of the console's active screen buffer.

See Also

GetStdHandle


SetSystemTime function
SetSystemTime (Win32)

BOOL SetSystemTime(lpst)

CONST SYSTEMTIME * lpst;	/* address of system time to set	*/

The SetSystemTime function sets the current system time and date. The system time is expressed in the Universal Time Convention (UTC).

Parameter	Description

lpst	Points to a SYSTEMTIME structure that contains the current system date and time.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The application must have system-time privilege (the SE_SYSTEMTIME_NAME privilege) for this function to succeed. This privilege is disabled by default. Use the AdjustTokenPrivileges function to enable the privilege and again to disable it after the time has been set.

For more information about security privileges, see Security.

See Also

AdjustTokenPrivileges, GetSystemTime, SYSTEMTIME


SetTapeParameters function
SetTapeParameters (Win32)

DWORD SetTapeParameters(hDevice, dwOperation, lpTapeInformation)

HANDLE hDevice;	/* handle of open device	*/
DWORD dwOperation;	/* type of information to set	*/
LPVOID lpTapeInformation;	/* buffer for information to set	*/

The SetTapeParameters function either specifies the block size of a tape or configures the tape device.

Parameter	Description

hDevice	Identifies the device for which to set configuration information. This handle is created by using CreateFile.

dwOperation	Specifies the type of information to set. This 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.

Returns

If the function succeeds, the return value is NO_ERROR; otherwise, it 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


SetTapePosition function
SetTapePosition (Win32)

DWORD SetTapePosition(hDevice, dwPositionMethod, dwPartition, dwOffsetLow, lpdwOffsetHigh, bImmediate)

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

The SetTapePosition sets the tape position on the specified device.

Parameter	Description

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.

Returns

If the function succeeds, the return value is NO_ERROR; otherwise, it 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.

Comments

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.

Call the GetTapeParameters function to obtain information about the status, capabilities, and capacities of tape drives and media.

See Also

GetTapeParameters, GetTapePosition


SetThreadContext function
SetThreadContext (Win32)

BOOL SetThreadContext(hThread, lpContext)

HANDLE hThread;	/* handle of thread with context	*/
CONST CONTEXT * lpContext;	/* address of context structure	*/

The SetThreadContext function sets the context in the specified thread.

Parameter	Description

hThread	Identifies an open handle of a thread whose context is to be written to. The handle must have THREAD_SET_CONTEXT access to the thread.

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

Returns

If the context was set, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The function allows the selective context to be set based on the value of the ContextFlags member of the context structure. The thread identified by the hThread handle is typically being debugged, but the function can also operate even when it is not being debugged.

See Also

GetThreadContext


SetThreadPriority function
SetThreadPriority (Win32)

BOOL SetThreadPriority(hThread, nPriority)

HANDLE hThread;	/* handle to the thread	*/
int nPriority;	/* thread priority level	*/

The SetThreadPriority function sets the priority value for the given thread. This value together with the priority class of the thread's process determines the thread's base priority level.

Parameter	Description

hThread	Identifies the thread. The handle must have THREAD_SET_INFORMATION access.

nPriority	Specifies the priority value for the thread. This parameter can be one of the following values:

Priority	Meaning

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 CPU intensive calculations.

Be very careful when manipulating priorities--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

GetThreadPriority, GetPriorityClass, SetPriorityClass


SetTimeZoneInformation function
SetTimeZoneInformation (Win32)

BOOL SetTimeZoneInformation(lptzi)

CONST TIME_ZONE_INFORMATION * lptzi;	/* address of time-zone settings	*/

The SetTimeZoneInformation function sets the current time-zone parameters. These parameters control translations from Coordinated Universal Time (UTC) time to local time.

Parameter	Description

lptzi	Points to a TIME_ZONE_INFORMATION structure that contains the time-zone parameters to set.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

GetTimeZoneInformation


SetUnhandledExceptionFilter function
SetUnhandledExceptionFilter (Win32)

LPTOP_LEVEL_EXCEPTION_FILTER SetUnhandledExceptionFilter( LPTOP_LEVEL_EXCEPTION_FILTER lpTopLevelExceptionFilter)

LPTOP_LEVEL_EXCEPTION_FILTER lpTopLevelExceptionFilter;	/* exception filter function	*/

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.

Parameter	Description

lpTopLevelExceptionFilter	Supplies the address of a top level exception filter function that will be called whenever the Win32 UnhandledExceptionFilter gets control, and the process is not being debugged. A value of NULL for this parameter specifies default handling within the Win32 UnhandledExceptionFilter.

The filter function has syntax congruent to that of the UnhandledExceptionFilter function: 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 the Win32 UnhandledExceptionFilter and execute the associated exception handler. This usually results in process termination

EXCEPTION_CONTINUE_EXECUTION	Return from the Win32 UnhandledExceptionFilter function 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 via its LPEXCEPTION_POINTERS parameter.

EXCEPTION_CONTINUE_SEARCH	Proceed with normal execution of the Win32 UnhandledExceptionFilter. That means obeying the SetErrorMod flags, or invoking the Application Error popup message box.

Returns

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.

Comments

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 function
SetupComm (Win32)

BOOL SetupComm(hCommDev, cbInQueue, cbOutQueue)

HANDLE hCommDev;	/* handle of the communications device	*/
DWORD cbInQueue;	/* size of the input buffer	*/
DWORD cbOutQueue;	/* size of the output buffer	*/

The SetupComm function initializes the communications parameters for a given communications device.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

cbInQueue	Specifies the recommended size, in bytes, of the device's internal input buffer.

cbOutQueue	Specifies the recommended size, in bytes, of the device's internal output buffer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

After a process uses the CreateFile function to open a handle to a communications device, it can call the SetupComm function to set the communications parameters for the device. If it does not set them, the device uses the default parameters upon the first call to another communications function.

The cbInQueue and cbOutQueue 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/output 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

SetCommState


SetVolumeLabel function
SetVolumeLabel (Win32)

BOOL SetVolumeLabel(lpRootPathName, lpVolumeName)

LPCTSTR lpRootPathName;	/* name of root directory of volume	*/
LPCTSTR lpVolumeName;	/* name for the volume	*/

The SetVolumeLabel function sets a file system volume's label.

Parameter	Description

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 specified volume's volume name.

Returns

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. Call GetLastError for extended error information.

See Also

GetVolumeInformation


SizeofResource function
SizeofResource (Win32)

DWORD SizeofResource(hModule, hrsrc)

HINSTANCE hModule;	/* resource-module handle	*/
HRSRC hrsrc;	/* resource handle	*/

The SizeofResource function returns the size, in bytes, of the given resource.

Parameter	Description

hModule	Identifies the module whose executable file contains the resource.

hrsrc	Identifies the resource. This handle must be created by using the FindResource or FindResourceEx function.

Returns

If the function succeeds, the return value is the number of bytes in the resource; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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 function
Sleep (Win32)

VOID Sleep(cMilliseconds)

DWORD cMilliseconds;	/* sleep time in milliseconds	*/

The Sleep function suspends the execution of the current thread for a specified interval.

Parameter	Description

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

Returns

This function does not return a value.

Comments

A thread can relinquish the remainder of its timeslice by calling this function with a sleep time of zero milliseconds.

See Also

SleepEx


SleepEx function
SleepEx (Win32)

DWORD SleepEx(dwTimeout, fAlertable)

DWORD dwTimeout;	/* time-out interval in milliseconds	*/
BOOL fAlertable;	/* return if I/O is completed?	*/

The SleepEx function causes the current thread to enter a waiting state until the specified interval of time has passed, or until an I/O completion callback function is called.

This function is available only in the Win32 API.

Parameter	Description

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

fAlertable	Specifies whether the function may terminate early due to an I/O completion callback. If fAlertable 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 fAlertable 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 occurs. If an I/O completion callback occurs, the I/O completion function is executed.

Returns

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 callbacks. This can happen only if fAlertable is TRUE, and if the thread that called the SleepEx function is the same thread that called the extended I/O function.

Comments

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 when the completion callback occurs. A thread goes into an alertable wait by calling either SleepEx, WaitForSingleObjectEx, or WaitForMultipleObjectsEx with the function's fAlertable parameter set to TRUE.

A thread can relinquish the remainder of its timeslice by calling this function with a sleep time of zero milliseconds.

See Also

ReadFileEx, Sleep, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx


SuspendThread function
SuspendThread (Win32)

DWORD SuspendThread(hThread)

HANDLE hThread;	/* handle to the thread	*/

The SuspendThread function suspends the given thread.

Parameter	Description

hThread	Identifies the thread. The handle must have THREAD_SUSPEND_RESUME access.

Returns

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.

Comments

If the function is 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


SystemTimeToFileTime function
SystemTimeToFileTime (Win32)

BOOL SystemTimeToFileTime(lpst, lpft)

CONST SYSTEMTIME * lpst;	/* address of system time to convert	*/
LPFILETIME lpft;	/* address of buffer for converted file time	*/

The SystemTimeToFileTime function converts a system time to a file time.

Parameter	Description

lpst	Points to a SYSTEMTIME structure that contains the time to be converted.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

lpft	Points to a FILETIME structure to receive the converted system time.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

DosDateTimeToFileTime, FileTimeToDosDateTime, FileTimeToSystemTime


TerminateProcess function
TerminateProcess (Win32)

BOOL TerminateProcess(hProcess, uExitCode)

HANDLE hProcess;	/* handle to the process	*/
UINT uExitCode;	/* exit code for the process	*/

The TerminateProcess function terminates the given process and all of its threads.

Parameter	Description

hProcess	Identifies the process to terminate. The handle must have PROCESS_TERMINATE access.

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 code. Use the GetExitCodeThread function to retrieve a thread's exit code.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 DLLs may be compromised if TerminateProcess is used rather that 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 code 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


TerminateThread function
TerminateThread (Win32)

BOOL TerminateThread(hThread, dwExitCode)

HANDLE hThread;	/* handle to the thread	*/
DWORD dwExitCode;	/* exit code for the thread	*/

The TerminateThread function terminates a thread.

Parameter	Description

hThread	Identifies the thread to terminate. The handle must have THREAD_TERMINATE access.

dwExitCode	Specifies the exit code for the thread. Use the GetExitCodeThread function to retrieve a thread's exit code.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

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

ExitThread


TlsAlloc function
TlsAlloc (Win32)

DWORD TlsAlloc(VOID)

The TlsAlloc function allocates a TLS (thread local storage) index. Any thread of the process can subsequently use this index to store and retrieve values that are local to the thread.

Returns

If the function succeeds, the return value is a TLS index; otherwise, it is 0xFFFFFFFF. To get extended error information, use the GetLastError function.

Comments

The threads of the process can use the TLS index in subsequent calls to the TlsFree, TlsSetValue, or TlsGetValue functions.

TLS indices are typically allocated during process or 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 indices available in each process. This minimum is guaranteed to be at least 64 for all systems.

TLS indices 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.

See Also

TlsFree, TlsGetValue, TlsSetValue


TlsFree function
TlsFree (Win32)

BOOL TlsFree(dwTlsIndex)

DWORD dwTlsIndex;	/* TLS index to free	*/

The TlsFree function releases a thread local storage (TLS) index, making it available for reuse.

Parameter	Description

dwTlsIndex	Specifies a TLS index that was allocated by the TlsAlloc function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 Comments section of TlsAlloc.

See Also

TlsAlloc, TlsGetValue, TlsSetValue


TlsGetValue function
TlsGetValue (Win32)

LPVOID TlsGetValue(dwTlsIndex)

DWORD dwTlsIndex;	/* TLS index to retrieve value for	*/

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.

Parameter	Description

dwTlsIndex	Specifies a TLS index that was allocated by the TlsAlloc function.

Returns

If the function succeeds, the return value is the value stored in the calling thread's TLS slot associated with the specified index; otherwise, it is zero. To get extended error information, use the GetLastError function.

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. See the Comments section for some further explanation.

Comments

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 API 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

TlsAlloc, TlsSetValue, TlsFree, SetLastError, GetLastError


TlsSetValue function
TlsSetValue (Win32)

BOOL TlsSetValue(dwTlsIndex, lpvTlsValue)

DWORD dwTlsIndex;	/* TLS index to set value for	*/
LPVOID lpvTlsValue;	/* value to be stored	*/

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.

Parameter	Description

dwTlsIndex	Specifies a TLS index that was allocated by the TlsAlloc function.

lpvTlsValue	Specifies the value to be stored in the calling thread's TLS slot specified by dwTlsIndex.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, TlsGetValue, TlsFree


TransactNamedPipe function
TransactNamedPipe (Win32)

BOOL TransactNamedPipe(hNamedPipe, lpvWriteBuf, cbWriteBuf, lpvReadBuf, cbReadBuf, lpcbRead, lpo)

HANDLE hNamedPipe;	/* handle of named pipe	*/
LPVOID lpvWriteBuf;	/* address of the write buffer	*/
DWORD cbWriteBuf;	/* size of the write buffer in bytes	*/
LPVOID lpvReadBuf;	/* address of the read buffer	*/
DWORD cbReadBuf;	/* size of the read buffer in bytes	*/
LPDWORD lpcbRead;	/* address of variable for bytes actually read	*/
LPOVERLAPPED lpo;	/* address of overlapped structure	*/

The TransactNamedPipe function combines into a single network operation the functions that write a message to and read a message from the given named pipe.

Parameter	Description

hNamedPipe	Identifies the named pipe returned by the CreateNamedPipe or CreateFile function.

lpvWriteBuf	Points to the buffer containing the data written to the pipe.

cbWriteBuf	Specifies the size, in bytes, of the write buffer.

lpvReadBuf	Points to the buffer that receives the data read from the pipe.

cbReadBuf	Specifies the size, in bytes, of the read buffer.

lpcbRead	Points to the variable that receives the number of bytes read from the pipe.

lpo	Points to an OVERLAPPED structure. If this parameter is NULL or if the FILE_FLAG_OVERLAPPED flag was not specified in the CreateNamedPipe or CreateFile function when the handle was created, TransactNamedPipe does not return until the operation is finished.

If lpo is not NULL and FILE_FLAG_OVERLAPPED was specified when the handle was created, TransactNamedPipe is executed as an overlapped operation. The OVERLAPPED structure should contain a manual reset event object (which can be created 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 not-signaled state before TransactNamedPipe returns, and is set to the signaled state when the transaction has finished. For more information about overlapped operations, see Pipes.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The TransactNamedPipe function 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. A pipe handle can be set to message-read mode with the SetNamedPipeHandleState function. The wait mode of the specified pipe handle (blocking or nonblocking) has no effect on the TransactNamedPipe function.

This function cannot be completed successfully until data is written into the lpvReadBuf buffer. The lpo 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 cbReadBuf, 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, PeekNamedPipe, ReadFile, ReadFileEx, SetNamedPipeHandleState


TransmitCommChar function
TransmitCommChar (Win32)

BOOL TransmitCommChar(hCommDev, chTransmit)

HANDLE hCommDev;	/* handle of the communications device	*/
char chTransmit;	/* character to transmit	*/

The TransmitCommChar function transmits a specified character ahead of any pending data in the output buffer of the specified communications device.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

chTransmit	Specifies the character to transmit.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

WaitCommEvent


UnhandledExceptionFilter function
UnhandledExceptionFilter (Win32)

LONG UnhandledExceptionFilter(lpexpExceptionInfo)

STRUCT _EXCEPTION_POINTERS * lpexpExceptionInfo;	/* address of exception info	*/

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.

Parameter	Description

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

Returns

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.

Comments

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

GetExceptionInformation, SetErrorMode, SetUnhandledExceptionFilter


UnlockFile function
UnlockFile (Win32)

BOOL UnlockFile(hFile, dwFileOffsetLow, dwFileOffsetHigh, cbUnlockLow, cbUnlockHigh)

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 cbUnlockLow;	/* low-order word of length to unlock	*/
DWORD cbUnlockHigh;	/* high-order word of length to unlock	*/

The UnlockFile function unlocks a region in an open file. Unlocking a region enables other processes to access the region.

Parameter	Description

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.

cbUnlockLow	Specifies the low-order word of the length of the byte range to be unlocked.

cbUnlockHigh	Specifies the high-order word of the length of the byte range to be unlocked.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

Do not terminate a process with a portion of a file locked or close a file that has locked regions.

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 function
UnlockFileEx (Win32)

BOOL UnlockFileEx(hFile, dwReserved, nNumberOfBytesToUnlockLow, nNumberOfBytesToUnlockHigh, lpOverlapped)

HANDLE hFile;	/* handle of file to lock	*/
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;	/* pointer to struct with unlock region start offset	*/

The UnlockFileEx function unlocks a previously locked byte range in an open file.

Parameter	Description

hFile	Supplies 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 that must be zero.

nNumberOfBytesToUnlockLow	Supplies the low order 32-bits of the length of the byte range to unlock.

nNumberOfBytesToUnlockHigh	Supplies the high order 32-bits of the length of the byte range to unlock.

lpOverlapped	Required pointer to an OVERLAPPED data structure that the function uses with the unlocking request. This structure contains the file offset of the beginning of the unlock range.

Returns

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE/NULL. Use the GetLastError function to obtain extended error information.

Comments

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, UnlockFile


UnlockResource function
UnlockResource (Win32)

The UnlockResource function is obsolete. It is not necessary for Win32 applications to unlock resources.

See Also

LoadResource, LockResource


UnmapViewOfFile function
UnmapViewOfFile (Win32)

BOOL UnmapViewOfFile(lpBaseAddress)

LPVOID lpBaseAddress;	/* address where mapped view begins	*/

The UnmapViewOfFile function unmaps a mapped view of a file from the calling process's address space.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE and all dirty pages within the specified range are stored in the on-disk representation of the mapped file. Otherwise, the return value is FALSE. To get extended error information, use the GetLastError function.

See Also

MapViewOfFile, MapViewOfFileEx


UpdateResource function
UpdateResource (Win32)

BOOL UpdateResource(hUpdateFile, lpszType, lpszName, IDLanguage, lpvData, cbData)

HANDLE hUpdateFile;	/* update-file handle	*/
LPCTSTR lpszType;	/* address of resource type to update	*/
LPCTSTR lpszName;	/* address of resource name to update	*/
WORD IDLanguage;	/* language identifier of resource	*/
LPVOID lpvData;	/* address of resource data	*/
DWORD cbData;	/* length of resource data, in bytes	*/

The UpdateResource function adds, deletes, or replaces a resource in an executable file.

Parameter	Description

hUpdateFile	Specifies an update-file handle. This handle is returned by the BeginUpdateResource function.

lpszType	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_BITMAP	Bitmap resource

RT_DIALOG	Dialog box

RT_FONT	Font resource

RT_FONTDIR	Font directory resource

RT_MENU	Menu resource

RT_RCDATA	Application-defined resource (raw data)

RT_STRING	String-table entry

RT_MESSAGETABLE	Message-table entry

RT_CURSOR	Hardware-dependent cursor resource

RT_GROUP_CURSOR	Hardware-independent cursor resource

RT_ICON	Hardware-dependent icon resource

RT_GROUP_ICON	Hardware-independent icon resource

RT_VERSION	Version resource

lpszName	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. For more information about the MAKEINTRESOURCE macro, see the <Microsoft Win32 Programmer's Reference, Volume 5>.

IDLanguage	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 in the <Microsoft Win32 Programmer's Reference, Volume 5>.

lpvData	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; lpvData must not point to ANSI data.

If lpvData is NULL, the specified resource is deleted from the executable file.

cbData	Specifies the size of the resource data at lpvData, in bytes.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, LockResource, SizeofResource


VirtualAlloc function
VirtualAlloc (Win32)

LPVOID VirtualAlloc(lpvAddress, cbSize, fdwAllocationType, fdwProtect)

LPVOID lpvAddress;	/* address of region to reserve or commit	*/
DWORD cbSize;	/* size of the region	*/
DWORD fdwAllocationType;	/* type of allocation	*/
DWORD fdwProtect;	/* type of access protection	*/

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.

Parameter	Description

lpvAddress	Specifies the desired starting address of the region. If the memory is being reserved, the specified address is rounded down to the next 64K byte 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.

cbSize	Specifies the size, in bytes, of the region. If the lpvAddress 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 lpvAddress to (lpvAddress+cbSize). This means that a 2-byte range straddling a page boundary causes both pages to be included in the allocated region.

fdwAllocationType	Specifies the type of allocation. An application can specify combinations of the following flags:

Value	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/decommited pages can be commited 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.

fdwProtect	Specifies the type of access protection. If the pages are being reserved but not committed, this parameter must specify the PAGE_NOACCESS flag. 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:

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 execution 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 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/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 value 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	No cacheing of the committed regions of pages is allowed. 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 no cache. This value is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.

Returns

If the function succeeds, the return value is the base address of the allocated region of pages; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The VirtualAlloc function 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 that page. When the process terminates, the system releases the storage for committed pages. VirtualAlloc can commit an already-committed page; this means that a range of committed/uncommitted pages can be committed without having to worry about a failure. The VirtualFree function can decommit a committed page, releasing the page's storage, or it can simultaneously decommit and release a committed page.

If the lpvAddress parameter is not NULL, the function uses the lpvAddress and cbSize 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 fdwAllocationType 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 comments above in this regard.

See Also

GlobalAlloc, VirtualFree, VirtualLock, VirtualProtect, VirtualQuery


VirtualFree function
VirtualFree (Win32)

BOOL VirtualFree(lpvAddress, cbSize, fdwFreeType)

LPVOID lpvAddress;	/* address of region of committed pages	*/
DWORD cbSize;	/* size of the region	*/
DWORD fdwFreeType;	/* type of free operation	*/

The VirtualFree function releases or decommits (or both) a region of pages within the virtual address space of the calling process.

Parameter	Description

lpvAddress	Points to the base address of the region of pages to be freed. If the fdwFreeType 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.

cbSize	Specifies the size, in bytes, of the region to be freed. If the fdwFreeType 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 lpvAddress parameter to (lpvAddress+cbSize). This means that a 2-byte range straddling a page boundary causes both pages to be freed.

fdwFreeType	Specifies the type of free operation. You may use one, but NOT both, of the following flags:

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/uncommited pages can be decommited without having to worry about a failure.

MEM_RELEASE	Releases the specified region of reserved pages. If this flag is specified, the cbSize parameter must be zero, or the function fails.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The VirtualFree function can perform one of the following operations:

Decommit a region of committed/uncommitted pages.

Release a region of reserved pages.

Decommit and release a region of committed/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/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 fdwFreeType parameter. Otherwise, the function fails and no pages are released or decommitted.

See Also

GlobalAlloc, GlobalFree, VirtualAlloc


VirtualLock function
VirtualLock (Win32)

BOOL VirtualLock(lpvAddress, cbSize)

LPVOID lpvAddress;	/* address of first byte of range to lock	*/
DWORD cbSize;	/* number of bytes in range to lock	*/

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.

Parameter	Description

lpvAddress	Points to the base address of the region of pages to be locked.

cbSize	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 lpvAddress parameter to (lpvAddress+cbSize). This means that a 2-byte range straddling a page boundary causes both pages to be locked.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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. There is a limit on the number of pages that can be locked: 30 pages. The limit is intentionally small to avoid severe performance degradation.

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.

See Also

GlobalLock, LocalLock, VirtualUnlock


VirtualProtect function
VirtualProtect (Win32)

BOOL VirtualProtect(lpvAddress, cbSize, fdwNewProtect, pfdwOldProtect)

LPVOID lpvAddress;	/* address of region of committed pages	*/
DWORD cbSize;	/* size of the region	*/
DWORD fdwNewProtect;	/* desired access protection	*/
PDWORD pfdwOldProtect;	/* address of variable to get old protection	*/

The VirtualProtect function changes the access protection on a region of committed pages in the virtual address space of the calling process.

Parameter	Description

lpvAddress	Points to the base address of the region of pages whose access protection attributes are changed.

cbSize	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 lpvAddress parameter to (lpvAddress+cbSize). This means that a 2-byte range straddling a page boundary causes the protection attributes of both pages to be changed.

fdwNewProtect	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 execution 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 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/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 value 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	No cacheing of the committed regions of pages is allowed. 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 no cache. This value is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.

pfdwOldProtect	Points to a variable to receive the previous access protection of the first page within the specified region of pages. If this parameter is NULL or does not point to a valid variable, the function fails.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The access protection value can only be set 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.

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

See Also

VirtualAlloc, VirtualProtectEx


VirtualProtectEx function
VirtualProtectEx (Win32)

BOOL VirtualProtectEx(hProcess, lpvAddress, cbSize, fdwNewProtect, pfdwOldProtect)

HANDLE hProcess;	/* handle of the process	*/
LPVOID lpvAddress;	/* address of region of committed pages	*/
DWORD cbSize;	/* size of the region	*/
DWORD fdwNewProtect;	/* desired access protection	*/
PDWORD pfdwOldProtect;	/* address of variable to get old protection	*/

The VirtualProtectEx function changes the access protection on a region of committed pages in the virtual address space of the specified process.

Parameter	Description

hProcess	Identifies the process whose memory protection is changed. The handle must have PROCESS_VM_OPERATION access.

lpvAddress	Points to the base address of the region of pages whose access protection attributes are changed.

cbSize	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 lpvAddress parameter to (lpvAddress+cbSize). This means that a 2-byte range straddling a page boundary causes the protection attributes of both pages to be changed.

fdwNewProtect	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 execution 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 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/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 value 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	No cacheing of the committed regions of pages is allowed. 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 no cache. This value is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.

pfdwOldProtect	Points to a variable to receive 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The access protection value can only be set 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.

This function is identical to the VirtualProtect function except that it enables changing the access protection of memory in a specified process.

See Also

VirtualAlloc, VirtualProtect, VirtualQueryEx


VirtualQuery function
VirtualQuery (Win32)

DWORD VirtualQuery(lpvAddress, pmbiBuffer, cbLength)

LPCVOID lpvAddress;	/* address of region	*/
PMEMORY_BASIC_INFORMATION pmbiBuffer;	/* address of information buffer	*/
DWORD cbLength;	/* size of buffer	*/

The VirtualQuery function provides information about a range of pages in the virtual address space of the calling process.

Parameter	Description

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

pmbiBuffer	Points to a MEMORY_BASIC_INFORMATION structure in which information about the specified page range is returned.

cbLength	Specifies the size, in bytes, of the buffer pointed to by the pmbiBuffer parameter.

Returns

The return value is the actual number of bytes returned in the information buffer.

Comments

The VirtualQuery function 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 flags.

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

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 region of free memory, and VirtualQuery is called on a page that is 10 megabytes into the region, the function will obtain a state of MEM_FREE and a size of 30 megabytes.

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

VirtualQueryEx, MEMORY_BASIC_INFORMATION


VirtualQueryEx function
VirtualQueryEx (Win32)

DWORD VirtualQueryEx(hProcess, lpvAddress, pmbiBuffer, cbLength)

HANDLE hProcess;	/* handle of the process	*/
LPCVOID lpvAddress;	/* address of region	*/
PMEMORY_BASIC_INFORMATION pmbiBuffer;	/* address of information buffer	*/
DWORD cbLength;	/* size of buffer	*/

The VirtualQueryEx function provides information about a range of pages within the virtual address space of the specified process.

Parameter	Description

hProcess	Identifies the process whose memory information is queried. The handle must have PROCESS_QUERY_INFORMATION access.

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

pmbiBuffer	Points to a MEMORY_BASIC_INFORMATION structure in which information about the specified page range is returned.

cbLength	Specifies the size, in bytes, of the buffer pointed to by the pmbiBuffer parameter.

Returns

The return value is the actual number of bytes returned in the information buffer.

Comments

The VirtualQueryEx function 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 flags.

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

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 region of free memory, and VirtualQueryEx is called on a page that is 10 megabytes into the region, the function will obtain a state of MEM_FREE and a size of 30 megabytes.

This function is identical to the VirtualQuery function, except that it enables access to information about memory in a specified process.

See Also

VirtualProtectEx, VirtualQuery, MEMORY_BASIC_INFORMATION


VirtualUnlock function
VirtualUnlock (Win32)

BOOL VirtualUnlock(lpvAddress, cbSize)

LPVOID lpvAddress;	/* address of first byte of range	*/
DWORD cbSize;	/* number of bytes in range	*/

The VirtualUnlock function unlocks a specified range of pages in the process's virtual address space, enabling the system to swap the pages out to the paging file if necessary.

Parameter	Description

lpvAddress	Points to the base address of the region of pages to be unlocked.

cbSize	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 lpvAddress parameter to (lpvAddress+cbSize). This means that a 2-byte range straddling a page boundary causes both pages to be unlocked.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

For the function to succeed, the range specified need not match a range passed to a previous VirtualLock call, but all pages in the range must be locked.

See Also

VirtualLock


WaitCommEvent function
WaitCommEvent (Win32)

BOOL WaitCommEvent(hCommDev, lpfdwEvtMask, lpo)

HANDLE hCommDev;	/* handle of the communications device	*/
LPDWORD lpfdwEvtMask;	/* address of variable for event that occurred	*/
LPOVERLAPPED lpo;	/* address of overlapped structure	*/

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.

Parameter	Description

hCommDev	Identifies the communications device. The CreateFile function returns this handle.

lpfdwEvtMask	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	Any 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.

lpo	Points to an OVERLAPPED structure. This parameter is ignored if the hCommDev handle was opened without specifying the FILE_FLAG_OVERLAPPED flag. If overlapped operation is not desired, this parameter can be NULL.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 lpo parameter is NULL or the hCommDev handle was opened without specifying the FILE_FLAG_OVERLAPPED flag, the WaitCommEvent function does not return until one of the specified events or an error occurs.

If lpo points to an OVERLAPPED structure and FILE_FLAG_OVERLAPPED was specified when the hCommDev handle was opened, 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 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 system sets the hEvent member of the OVERLAPPED stucture 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 wait function to determine the event object's state, 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 lpfdwEvtMask 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 a WaitCommEvent operation is in progress, WaitCommEvent returns immediately. The variable pointed to by the lpfdwEvtMask parameter is set to zero.

See Also

GetCommMask, SetCommMask


WaitForDebugEvent function
WaitForDebugEvent (Win32)

BOOL WaitForDebugEvent(lpde, dwTimeout)

LPDEBUG_EVENT lpde;	/* address of structure for event information	*/
DWORD dwTimeout;	/* number of milliseconds to wait for event	*/

The WaitForDebugEvent function waits for a debugging event to occur in a process being debugged.

Parameter	Description

lpde	Points to a DEBUG_EVENT structure that is filled with information about the debugging event.

dwTimeout	Specifies the number of milliseconds to wait for a debugging event. If dwTimeout is zero, the function tests for a debugging event and returns immediately. If dwTimeout is INFINITE, the function does not return until a debugging event has occurred.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Only the thread that created the process being debugged can call WaitForDebugEvent.

See Also

ContinueDebugEvent, CreateProcess, DebugActiveProcess, DebugBreak, OutputDebugString


WaitForInputIdle function
WaitForInputIdle (Win32)

DWORD WaitForInputIdle(hProcess, dwTimeout)

HANDLE hProcess;	/* handle to process	*/
DWORD dwTimeout;	/* time-out interval in milliseconds	*/

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.

Parameter	Description

hProcess	Identifies the process.

dwTimeout	Specifies the time-out interval, in milliseconds. If dwTimeout is INFINITE, the function does not return until the process is idle.

Returns

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.

Comments

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 function
WaitForMultipleObjects (Win32)

DWORD WaitForMultipleObjects(cObjects, lphObjects, fWaitAll, dwTimeout)

DWORD cObjects;	/* number of handles in handle array	*/
CONST HANDLE * lphObjects;	/* address of object-handle array	*/
BOOL fWaitAll;	/* wait flag	*/
DWORD dwTimeout;	/* time-out interval in milliseconds	*/

The WaitForMultipleObjects 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.

Parameter	Description

cObjects	Specifies the number of object handles in the array pointed to by lphObjects. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS.

lphObjects	Points to an array of object handles. For a list of the object types whose handles can be specified, see the Comments section. The array can contain handles of objects of different types. The handles must have SYNCHRONIZE access.

fWaitAll	Specifies the wait type. If TRUE, the function returns when all objects in the lphObjects array are signaled at the same time. If FALSE, the function returns when any one of the objects is signaled. In the latter case, the return value indicates the object whose state caused the function to return.

dwTimeout	Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the conditions specified by the fWaitAll parameter are not satisfied. If dwTimeout is zero, the function tests the states of the specified objects and returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

Returns

If the function succeeds, the return value indicates the event that caused the function to return; otherwise, it is WAIT_FAILED. To get extended error information, use the GetLastError function.

The return value on success is one of the following values:

Value	Meaning

WAIT_OBJECT_0 to (WAIT_OBJECT_0 + cObjects - 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 lphObjects array index of the object that satisfied the wait.

WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + cObjects - 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 lphObjects 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 parameter are not satisfied.

Comments

The WaitForMultipleObjects function determines whether the conditions exist that satisfy the wait. If the wait is not satisfied, the calling thread enters an efficient wait state, consuming very little processor time while waiting for one of the conditions of the wait to be satisfied.

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. For example, a mutex can be signaled, but the thread does not get ownership until the other objects are also signaled. In the meantime, some other thread may get ownership of the mutex, thereby delaying satisfaction of the wait condition.

The system adjusts the state of some types of objects after the object's signaled state satisfies a wait condition. 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 lphObjects array:

Object	Description

change notification	The handle is returned by the FindFirstChangeNotification function. 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 CONIN$ 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 handle is returned by the CreateEvent or OpenEvent function. 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 handle is returned by the CreateMutex or OpenMutex function. 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 handle is returned by the CreateProcess or OpenProcess function. A process object's state is signaled when the process terminates.

thread	The handle is returned by the CreateProcess, CreateThread, or CreateRemoteThread function. A thread object's state is signaled when the thread terminates.

semaphore	The handle is returned by the CreateSemaphore or OpenSemaphore function. 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.

In some circumstances, a wait function can specify a handle of a file, named pipe, or communications device as an object to wait for. However, their use for this purpose is discouraged. For more information, see Synchronization.

See Also

MsgWaitForMultipleObjects, Sleep, WaitForMultipleObjectsEx, WaitForSingleObject


WaitForMultipleObjectsEx function
WaitForMultipleObjectsEx (Win32)

DWORD WaitForMultipleObjectsEx(cObjects, lphObjects, fWaitAll, dwTimeout, fAlertable)

DWORD cObjects;	/* number of handles in handle array	*/
CONST HANDLE * lphObjects;	/* address of object-handle array	*/
BOOL fWaitAll;	/* wait flag	*/
DWORD dwTimeout;	/* time-out interval in milliseconds	*/
BOOL fAlertable;	/* alertable wait flag	*/

The WaitForMultipleObjectsEx function is an extended wait function that can be used to perform an alertable wait. This enables the function to return when the system queues an input and output (I/O) completion routine to be executed by the calling thread. The function also 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 available only in Microsoft® Windows NT™.

Parameter	Description

cObjects	Specifies the number of object handles to wait for in the array pointed to by lphObjects. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS.

lphObjects	Points to an array of object handles. For a list of the object types whose handles can be specified, see the Comments section. The array can contain handles of objects of different types. The handles must have SYNCHRONIZE access.

fWaitAll	Specifies the wait type. If TRUE, the function returns when all objects in the lphObjects array are signaled at the same time. If FALSE, the function returns when any one of the objects is signaled. In the latter case, the return value indicates the object whose state caused the function to return.

dwTimeout	Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the conditions specified by the fWaitAll parameter are not satisfied and no completion routines are queued. If dwTimeout is zero, the function tests the states of the specified objects and checks for queued completion routines and then returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

fAlertable	Specifies whether the function returns when the system queues an I/O completion routine for execution by the calling thread. If TRUE, the function returns and the completion routine is executed. If FALSE, the function does not return and the completion routine is not executed.

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 fAlertable is TRUE and the calling thread is the thread that initiated the read or write operation.

Returns

If the function succeeds, the return value indicates the event that caused the function to return; otherwise, it is 0xFFFFFFFF. To get extended error information, use the GetLastError function.

The return value on success is one of the following values:

Value	Meaning

WAIT_OBJECT_0 to (WAIT_OBJECT_0 + cObjects - 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 lphObjects array index of the object that satisfied the wait.

WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + cObjects - 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 lphObjects 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 fWaitAll parameter were not satisfied, and no completion routines are queued.

Comments

The WaitForMultipleObjectsEx function determines whether the conditions exist that satisfy the wait. If the wait is not satisfied, the calling thread enters an efficient wait state, consuming very little processor time while waiting for one of the conditions of the wait to be satisfied.

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. For example, a mutex can be signaled, but the thread does not get ownership until the other objects are also signaled. In the meantime, some other thread may get ownership of the mutex, thereby delaying satisfaction of the wait condition.

The system adjusts the state of some types of objects after the object's signaled state satisfies a wait condition. 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 lphObjects array:

Object	Description

change notification	The handle is returned by the FindFirstChangeNotification function. 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 CONIN$ 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 handle is returned by the CreateEvent or OpenEvent function. 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 handle is returned by the CreateMutex or OpenMutex function. 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 handle is returned by the CreateProcess or OpenProcess function. A process object's state is signaled when the process terminates.

thread	The handle is returned by the CreateProcess, CreateThread, or CreateRemoteThread function. A thread object's state is signaled when the thread terminates.

semaphore	The handle is returned by the CreateSemaphore or OpenSemaphore function. 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.

In some circumstances, a wait function can specify a handle of a file, named pipe, or communications device as an object to wait for. However, their use for this purpose is discouraged. For more information, see Synchronization.

See Also

MsgWaitForMultipleObjects, ReadFileEx, SleepEx, WaitForMultipleObjects, WaitForSingleObjectEx, WriteFileEx


WaitForSingleObject function
WaitForSingleObject (Win32)

DWORD WaitForSingleObject(hObject, dwTimeout)

HANDLE hObject;	/* handle of object to wait for	*/
DWORD dwTimeout;	/* time-out interval in milliseconds	*/

The WaitForSingleObject function returns when the specified object is in the signaled state or when the time-out interval elapses.

Parameter	Description

hObject	Identifies the object. For a list of the object types whose handles can be specified, see the Comments section. The handle must have SYNCHRONIZE access.

dwTimeout	Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the object's state is nonsignaled. If dwTimeout is zero, the function tests the object's state and returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

Returns

If the function succeeds, the return value indicates the event that caused the function to return; otherwise, it is WAIT_FAILED. To get extended error information, use the GetLastError function.

The return value on success is one of the following values:

Value	Meaning

WAIT_OBJECT_0	The state of the specified object is signaled.

WAIT_ABANDONED	All of the following conditions are true: the specified object is a mutex object, the object's state is signaled, and the thread that owned the mutex object terminated without releasing its ownership.

WAIT_TIMEOUT	The time-out interval elapsed, and the object's state is nonsignaled.

Comments

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 one of the conditions of the wait to be satisfied.

The system adjusts the state of some types of objects after the object's signaled state satisfies a wait condition. 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 handle is returned by the FindFirstChangeNotification function. 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 CONIN$ 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 handle is returned by the CreateEvent or OpenEvent function. 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 handle is returned by the CreateMutex or OpenMutex function. 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 handle is returned by the CreateProcess or OpenProcess function. A process object's state is signaled when the process terminates.

thread	The handle is returned by the CreateProcess, CreateThread, or CreateRemoteThread function. A thread object's state is signaled when the thread terminates.

semaphore	The handle is returned by the CreateSemaphore or OpenSemaphore function. 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.

In some circumstances, a wait function can specify a handle of a file, named pipe, or communications device as an object to wait for. However, their use for this purpose is discouraged. For more information, see Synchronization.

See Also

Sleep, WaitForMultipleObjects, WaitForSingleObjectsEx


WaitForSingleObjectEx function
WaitForSingleObjectEx (Win32)

DWORD WaitForSingleObjectEx(hObject, dwTimeout, fAlertable)

HANDLE hObject;	/* handle of object to wait for	*/
DWORD dwTimeout;	/* time-out interval in milliseconds	*/
BOOL fAlertable;	/* return to execute I/O completion routine if TRUE	*/

The WaitForSingleObjectEx function is an extended wait function that can be used to perform an alertable wait. This enables the function to return when the system queues an input and output (I/O) completion routine to be executed by the calling thread. The function also returns when the specified object is in the signaled state or when the time-out interval elapses.

This function is available only in Microsoft® Windows NT™.

Parameter	Description

hObject	Identifies the object. For a list of the object types whose handles can be specified, see the Comments section. The handle must have SYNCHRONIZE access.

dwTimeout	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 are queued. If dwTimeout is zero, the function tests the object's state and checks for queued completion routines and then returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

fAlertable	Specifies whether the function returns when the system queues an I/O completion routine for execution by the calling thread. If TRUE, the function returns and the completion routine is executed. If FALSE, the function does not return, and the completion routine is not executed.

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 fAlertable is TRUE and the calling thread is the thread that initiated the read or write operation.

Returns

If the function succeeds, the return value indicates the event that caused the function to return; otherwise, it is 0xFFFFFFFF. To get extended error information, use the GetLastError function.

The successful return value is one of the following:

Value	Meaning

WAIT_OBJECT_0

The state of the specified object is signaled.

WAIT_ABANDONED

All of the following conditions are true: the specified object is a mutex object, the object's state is signaled, and the thread that owned the mutex object terminated without releasing its ownership.

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.

Comments

The WaitForSingleObjectEx function determines whether the conditions exist that satisfy the wait. If the wait is not satisfied, the calling thread enters an efficient wait state, consuming very little processor time while waiting for one of the conditions of the wait to be satisfied.

The system adjusts the state of some types of objects after the object's signaled state satisfies a wait condition. 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 handle is returned by the FindFirstChangeNotification function. 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 CONIN$ 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 handle is returned by the CreateEvent or OpenEvent function. 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 handle is returned by the CreateMutex or OpenMutex function. 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 handle is returned by the CreateProcess or OpenProcess function. A process object's state is signaled when the process terminates.

thread	The handle is returned by the CreateProcess, CreateThread, or CreateRemoteThread function. A thread object's state is signaled when the thread terminates.

semaphore	The handle is returned by the CreateSemaphore or OpenSemaphore function. 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.

In some circumstances, a wait function can specify a handle of a file, named pipe, or communications device as an object to wait for. However, their use for this purpose is discouraged. For more information, see Synchronization.

See Also

ReadFileEx, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObject, WriteFileEx


WaitNamedPipe function
WaitNamedPipe (Win32)

BOOL WaitNamedPipe(lpszPipeName, dwTimeout)

LPCTSTR lpszPipeName;	/* address of name of pipe to wait for	*/
DWORD dwTimeout;	/* time-out interval in milliseconds	*/

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

Parameter	Description

lpszPipeName	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. Use the following pipe name format:

\\servername\pipe\pipename

dwTimeout	Specifies the number of milliseconds the function will wait for an instance of the named pipe to be available. Use one of the following constants 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.

Returns

If an instance of the pipe is available before the time-out interval elapses the return value is TRUE. Otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 CreateFile 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


WinExec function
WinExec (Win32)

UINT WinExec(lpszCmdLine, fuCmdShow)

LPCSTR lpszCmdLine;	/* address of command line	*/
UINT fuCmdShow;	/* window style for new app	*/

The WinExec function runs the specified application.

This function is provided for compatibility with earlier versions of Windows, For Win32 applications, use the CreateProcess function.

Parameter	Description

lpszCmdLine	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 lpszCmdLine string 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.

fuCmdShow	Specifies how a Windows-based application window is to be shown and is used to supply the wShowWindow member of the STARTUPINFO parameter to CreateProcess. See the description of the nCmdShow parameter of the ShowWindow function for a list of the acceptable values. For a non-Windows-based application, the PIF file, if any, for the application determines the window state.

Returns

If the function succeeds, the return value is greater than 31; otherwise, it is one of the following error values:

Value	Meaning

0	The 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).

Comments

Win32 applications should use the CreateProcess function rather than this function. The WinExec function exists in Win32 to provide compatibility with earlier versions of Windows.

The WinExec function is implemented in the Win32 API by a call to the CreateProcess function. The following list shows how the appropriate CreateProcess parameters are formed:

CreateProcess parameter	Value

lpszImageName	NULL

lpszCommandLine	WinExec lpszCmdLine parameter

lpsaProc	NULL

lpsaThread	NULL

fInheritHandles	FALSE

fdwCreate	0

lpvEnvironment	NULL

lpszCurDir	NULL

lpsi	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 WinExec fuCmdShow parameter.

lppi->hProcess	The handle is immediately closed.

lppi->hThread	The handle is immediately closed.

In Win32, the WinExec function returns when the launched process calls the GetMessage function or a timeout limit is reached. To avoid waiting on the timeout delay, call the GetMessage function as soon as possible in any process launched by a call to WinExec.

See Also

CreateProcess, GetSystemDirectory, GetWindowsDirectory, ShowWindow


WNetAddConnection function
WNetAddConnection (Win32)

DWORD WNetAddConnection(lpszRemoteName, lpszPassword, lpszLocalName)

LPTSTR lpszRemoteName;	/* address of network device name	*/
LPTSTR lpszPassword;	/* address of password	*/
LPTSTR lpszLocalName;	/* address of local device name	*/

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.

Parameter	Description

lpszRemoteName	Points to a null-terminated string that specifies the network resource to connect to.

lpszPassword	Points to a null-terminated string that specifies the password to be used to make a connection. This is usually the password associated with the current user.

If lpszPassword is NULL, the default password is used. If the string is empty, no password is used.

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

Returns

If the function succeeds, the return value is NO_ERROR. Otherwise, it is an error code, which can be retrieved by calling the GetLastError function. Possible return values from GetLastError include the following:

Value	Meaning

ERROR_ACCESS_DENIED	Access is denied.

ERROR_ALREADY_ASSIGNED	The device specified in the lpszLocalName 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 lpszLocalName is invalid.

ERROR_BAD_NET_NAME	The value specified in lpszRemoteName 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 lpszLocalName is already in the user profile.

ERROR_EXTENDED_ERROR	A network-specific error occurred. Use the WNetGetLastError function to obtain a description of the error.

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.

This function returns error codes for compatibility with Windows 3.1. For compatibility with Windows NT, the function also sets the error-code value returned by the GetLastError function.

See Also

WNetAddConnection2, WNetCancelConnection, WNetCancelConnection2, WNetGetConnection


WNetAddConnection2 function
WNetAddConnection2 (Win32)

DWORD WNetAddConnection2(lpNetResource, lpszPassword, lpszUserName, fdwConnection)

LPNETRESOURCE lpNetResource;	/* address of net resource	*/
LPTSTR lpszPassword;	/* address of password	*/
LPTSTR lpszUserName;	/* address of user name	*/
DWORD fdwConnection;	/* connection-type flags	*/

The WNetAddConnection2 function enables the caller to connect a local device to a network resource. This function supersedes the WNetAddConnection function.

Parameter	Description

lpNetResource	Points to an NETRESOURCE structure that specifies the network resource to connect to.

The following members must be set in the NETRESOURCE structure:

Member	Description

lpRemoteName	Points to a null-terminated string that specifies the network resource to connect to.

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.

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, Windows attempts to determine the correct provider.

An application should set lpProvider only when it must specify a network provider. Otherwise, the application should allow Windows to determine which provider the network name maps to.

If lpProvider is not NULL, Windows attempts to make a connection only to the named provider.

dwType	Specifies the type of resource with which to connect. It can be RESOURCETYPE_DISK, RESOURCETYPE_PRINT, or RESOURCETYPE_ANY. The value RESOURCETYPE_ANY is used when the resource type is unimportant or unknown.

The other members of the NETRESOURCE structure are ignored.

lpszPassword	Points to a null-terminated string that specifies the password to be used to make the connection. This is usually the password associated with the current user.

If lpszPassword is NULL, the default password is used. If the string is empty, no password is used.

lpszUserName	Points to a null-terminated string that specifies the user name used to make the connection. If lpszUserName is NULL, the default user security context for the process is applied. Specify NULL when the user wants to connect to a resource, but has a different user name or account assigned for that resource. This name represents a security context and is provider-specific.

fdwConnection	Specifies a bitmask for the connection type. The following values are defined:

Value	Meaning

0	No information about the connection is stored.

CONNECT_UPDATE_PROFILE	Information about the connection is stored in the user profile. If the connection is successful, Windows automatically restores this connection during subsequent logon operations.

Note, however, that if the connection is made with lpLocalName set to NULL, the system will neither store information about the connection nor automatically restore it during subsequent logons.

Returns

If the function succeeds, the return value is NO_ERROR. Otherwise, the return value is an error code, which can be retrieved by calling the GetLastError function. Possible return values from GetLastError include the following:

Value	Meaning

ERROR_ACCESS_DENIED	Access is denied.

ERROR_ALREADY_ASSIGNED	The device specified in the lpszLocalName 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 lpszLocalName is invalid.

ERROR_BAD_NET_NAME	The value specified in lpszRemoteName 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 lpszLocalName is already in the user profile.

ERROR_EXTENDED_ERROR	A network-specific error occurred. Use the WNetGetLastError function to obtain a description of the error.

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.

This function returns error codes for compatibility with Windows 3.1. For compatibility with Windows NT, the function also sets the error-code value returned by the GetLastError function.

Comments

See Also

WNetAddConnection, WNetAddConnection2, WNetCancelConnection2, WNetGetConnection


WNetCancelConnection function
WNetCancelConnection (Win32)

DWORD WNetCancelConnection(lpszName, fForce)

LPTSTR lpszName;	/* address of resource name to disconnect	*/
BOOL fForce;	/* flag for unconditional disconnect	*/

The WNetCancelConnection function breaks an existing network connection.

This function is provided for compatibility with earlier versions of Microsoft Windows. For new applications, use the WNetCancelConnection2 function.

Parameter	Description

lpszName	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 lpszName specifies a redirected local device, only the specified redirection is broken, and Windows will not restore the connection during subsequent logon operations. When lpszName specifies a remote network resource, the connection to that remote network resource is broken.

fForce	Specifies whether the disconnection is to occur even if there are open files or jobs on the connection. If fForce is FALSE, the function fails if there are open files or jobs.

Returns

If the function succeeds, the return value is NO_ERROR. Otherwise, the return value is an error code, which can be retrieved by calling the GetLastError function. Possible return values from GetLastError include the following:

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. Use the WNetGetLastError function to obtain a description of the error.

ERROR_NOT_CONNECTED	The name specified by the lpszName parameter is not a redirected device, or the system is not currently connected to the device specified by the lpszName parameter.

ERROR_OPEN_FILES	There are open files and the fForce parameter is FALSE.

This function returns error codes for compatibility with Windows 3.1. For compatibility with Windows NT, the function also sets the error-code value returned by the GetLastError function.

See Also

WNetAddConnection, WNetAddConnection2, WNetCancelConnection2, WNetGetConnection


WNetCancelConnection2 function
WNetCancelConnection2 (Win32)

DWORD WNetCancelConnection2(lpszName, fdwConnection, fForce)

LPTSTR lpszName;	/* address of resource name to disconnect	*/
DWORD fdwConnection;	/* connection-type flags	*/
BOOL fForce;	/* flag for unconditional disconnect	*/

The WNetCancelConnection2 function breaks an existing network connection. It can also be used to remove remembered network connections that are not currently connected.

Parameter	Description

lpszName	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 lpszName specifies a redirected local resource, only the specified redirection is broken; otherwise, all connections to the remote network resource are broken.

fdwConnection	Specifies a bitmask for the connection type. The following values are defined:

Value	Meaning

0	No information about the connection is stored.

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 fForce is FALSE, the function fails if there are open files or jobs.

Returns

If the function succeeds, the return value is NO_ERROR. Otherwise, the return value is an error code, which can be retrieved by calling the GetLastError function. Possible return values from GetLastError include the following:

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. Use the WNetGetLastError function to obtain a description of the error.

ERROR_NOT_CONNECTED	The name specified by the lpszName parameter is not a redirected device, or the system is not currently connected to the device specified by the lpszName parameter.

ERROR_OPEN_FILES	There are open files and the fForce parameter is FALSE.

See Also

WNetAddConnection, WNetAddConnection2, WNetCancelConnection, WNetGetConnection


WNetCloseEnum function
WNetCloseEnum (Win32)

DWORD WNetCloseEnum(hEnum)

HANDLE hEnum;	/* handle of enumeration	*/

The WNetCloseEnum function ends a network-resource enumeration started by the WNetOpenEnum function.

Parameter	Description

hEnum	Identifies an enumeration instance. This handle must have been returned by the WNetOpenEnum function.

Returns

If the function succeeds, the return value is NO_ERROR. Otherwise, the return value is an error code, which can be retrieved by calling the GetLastError function. Possible return values from GetLastError include the following:

Value	Meaning

ERROR_NO_NETWORK	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. Use the WNetGetLastError function to obtain a description of the error.

This function returns error codes for compatibility with Windows 3.1. For compatibility with Windows NT, the function also sets the error-code value returned by the GetLastError function.

See Also

WNetEnumResource, WNetOpenEnum


WNetConnectionDialog function
WNetConnectionDialog (Win32)

DWORD WNetConnectionDialog(hwnd, fdwResourceType)

HWND hwnd;	/* handle of window owning dialog box	*/
DWORD fdwResourceType;	/* resource type to allow connections to	*/

The WNetConnectionDialog function starts a general browsing dialog box for connecting to network resources.

Parameter	Description

hwnd	Identifies the owning window.

fdwResourceType	Specifies the resource type to allow connections to. This parameter can be one of the following values:

Value	Meaning

RESOURCETYPE_DISK	Connect to disk resources.

Returns

If the function completes successfully, the return value is NO_ERROR.

If the user cancels out of the dialog, the return value is 0xFFFFFFFF.

In all other cases, the function returns an error code. The same error code can be obtained by calling GetLastError. Possible error codes for the function include :

Value	Meaning

ERROR_EXTENDED_ERROR	A network-specific error occurred. Use the WNetGetLastError function to obtain a description of the error.

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.

This function returns error codes for compatibility with Windows 3.1. For compatibility with Windows NT, the function also sets the error-code value returned by the GetLastError function.

Comments

If the user chooses OK in the dialog box, the requested network connections will have been performed when this function returns.

If the function attempts to make a connection and the provider returns 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


WNetDisconnectDialog function
WNetDisconnectDialog (Win32)

DWORD WNetDisconnectDialog(hwnd, fdwResourceType)

HWND hwnd;	/* handle of window owning dialog box	*/
DWORD fdwResourceType;	/* resource type to disconnect from	*/

The WNetDisconnectDialog function starts a general browsing dialog box for disconnecting from network resources.

Parameter	Description

hwnd	Specifies the handle of the owning window.

fdwResourceType	Specifies the resource type to disconnect from. This parameter may be may be one of the following values:

Value	Meaning

RESOURCETYPE_DISK	Disconnect from disk resources.

RESOURCETYPE_PRINT	Disconnect from print resources.

Returns

If the function completes successfully, the return value is NO_ERROR.

If the user cancels out of the dialog, the return value is 0xFFFFFFFF.

In all other cases, the function returns an error code. The same error code can be obtained by calling GetLastError. Possible error codes for the function include :

Value	Meaning

ERROR_EXTENDED_ERROR	A network-specific error occurred. Use the WNetGetLastError function to obtain a description of the error.

ERROR_NO_NETWORK	No network is present.

ERROR_NOT_ENOUGH_MEMORY	There is insufficient memory to start the dialog box.

This function returns error codes for compatibility with Windows 3.1. For compatibility with Windows NT, the function also sets the error-code value returned by the GetLastError function.

Comments

If the user chooses OK in the dialog box, the requested network disconnections will have been performed when this function returns.

See Also

WNetAddConnection2, WNetCancelConnection2, WNetConnectionDialog


WNetEnumResource function
WNetEnumResource (Win32)

DWORD WNetEnumResource(hEnum, lpcEntries, lpvBuffer, lpcbBuffer)

HANDLE hEnum;	/* handle of enumeration	*/
LPDWORD lpcEntries;	/* address of entries to list	*/
LPVOID lpvBuffer;	/* address of buffer for results	*/
LPDWORD lpcbBuffer;	/* address of buffer-size variable	*/

The WNetEnumResource function continues a network-resource enumeration started by the WNetOpenEnum function.

Parameter	Description

hEnum	Identifies an enumeration instance. This handle must have been returned by the WNetOpenEnum function.

lpcEntries	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 the lpcEntries parameter contains the number of entries actually read.

lpvBuffer	Points to the buffer to receive 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 the NETRESOURCE structures in the array is not predictable.

lpcbBuffer	Points to a variable that specifies the size, in bytes, of the lpvBuffer parameter. If the buffer is too small to receive even one entry, this variable receives the required size of the buffer.

Returns

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 the WNetEnumResource function to complete the enumeration.

ERROR_NO_MORE_ITEMS	There are no more entries. The buffer contents are undefined.

If the return value is not NO_ERROR or ERROR_NO_MORE_ITEMS, it is an error code, which can be retrieved by calling the GetLastError function. Possible return values from GetLastError include the following:

Value	Meaning

ERROR_MORE_DATA	The buffer is too small for even one entry.

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. Use the WNetGetLastError function to obtain a description of the error.

This function returns error codes for compatibility with Windows 3.1. For compatibility with Windows NT, the function also sets the error-code value returned by the GetLastError function.

Comments

An application cannot set the lpvBuffer parameter to NULL and retrieve the required buffer size from the lpcbBuffer parameter. Instead, the application should allocate a buffer of a reasonable size (16K is typical) and use the value of lpcbBuffer for error-detection.

See Also

WNetCloseEnum, WNetOpenEnum, NETRESOURCE


WNetGetConnection function
WNetGetConnection (Win32)

DWORD WNetGetConnection(lpszLocalName, lpszRemoteName, lpcchBuffer)

LPTSTR lpszLocalName;	/* address of local name	*/
LPTSTR lpszRemoteName;	/* address of buffer for remote name	*/
LPDWORD lpcchBuffer;	/* address of buffer size, in characters	*/

The WNetGetConnection function retrieves the name of the network resource associated with a local device.

Parameter	Description

lpszLocalName	Points to a null-terminated string that specifies the name of the local device to get the network name for.

lpszRemoteName	Points to a buffer that will receive the null-terminated remote name used to make the connection.

lpcchBuffer	Points to a variable that specifies the size, in characters, of the buffer pointed to by the lpszRemoteName parameter. If the function fails because the buffer is not big enough, this variable returns the required buffer size.

Returns

If the function succeeds,the return value is NO_ERROR. Otherwise, it is an error code, which can be retrieved by calling the GetLastError function. Possible return values from GetLastError include the following:

Value	Meaning

ERROR_BAD_DEVICE	The string pointed to by lpszLocalName is invalid.

ERROR_NOT_CONNECTED	The device specified by lpszLocalName is not redirected.

ERROR_MORE_DATA	The buffer is too small. The lpcchBuffer parameter points to a variable that contains the required buffer size.

ERROR_CONNECTION_UNAVAIL	The device is not currently connected, but it is a remembered (persistent) connection.

ERROR_NO_NETWORK	No network is present.

ERROR_EXTENDED_ERROR	A network-specific error occurred. Use the WNetGetLastError function to obtain a description of the error.

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.

This function returns error codes for compatibility with Windows 3.1. For compatibility with Windows NT, the function also sets the error-code value returned by the GetLastError function.

See Also

WNetGetLastError, WNetGetUser


WNetGetLastError function
WNetGetLastError (Win32)

DWORD WNetGetLastError(lpdwErrorCode, lpszDescription, cchDescription, lpszName, cchName)

LPDWORD lpdwErrorCode;	/* address of error code	*/
LPTSTR lpszDescription;	/* address of string describing error	*/
DWORD cchDescription;	/* size of the description buffer, in characters	*/
LPTSTR lpszName;	/* address of buffer for provider name	*/
DWORD cchName;	/* size of the provider-name buffer	*/

The WNetGetLastError function retrieves the most recent extended error code set by a Windows network function.

Parameter	Description

lpdwErrorCode	Points to the variable that will receive the error code reported by the network provider. This error code is network-provider specific.

lpszDescription	Points to the buffer that will receive the null-terminated string describing the error.

cchDescription	Specifies the size, in characters, of the buffer pointed to by the lpszDescription 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.

lpszName	Points to the buffer that will receive the null-terminated string identifying the network provider that raised the error.

cchName	Specifies the size, in characters, of the buffer pointed to by the lpszName parameter. If the buffer is too small for the error string, the string is truncated, but still null-terminated.

Returns

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, the return value is ERROR_INVALID_ADDRESS.

Comments

The WNetGetLastError function is used to retrieve errors that are specific to a network provider. It should be called when a Windows network function (or the GetLastError function) returns ERROR_EXTENDED_ERROR. Like the GetLastError function, this function returns extended error information, which is maintained on a per-thread basis. Unlike GetLastError, this function can also return a string for reporting errors that are not described by any existing error code.

See Also

GetLastError


WNetGetUser function
WNetGetUser (Win32)

DWORD WNetGetUser(lpszLocalName, lpszUserName, lpcchBuffer)

LPTSTR lpszLocalName;	/* address of local name to get user name for	*/
LPTSTR lpszUserName;	/* address of buffer for user name	*/
LPDWORD lpcchBuffer;	/* address of buffer-size variable	*/

The WNetGetUser function retrieves the current default user name or the user name used to establish a network connection.

Parameter	Description

lpszLocalName	Points to a null-terminated string that specifies either the name of the local device to return the user name for, or the name of a network that the user has made a connection to.

If lpszLocalName is NULL, Windows returns the name of the current user for the process.

If lpszLocalName is a network name and the user is connected to that resource using different names, the network provider may not be able to resolve which user name to return. In this case, the provider may make an arbitrary choice from the possible user names.

lpszUserName	Points to a buffer that will receive the null-terminated user name.

lpcchBuffer	Points to a variable that specifies the size, in characters, of the buffer pointed to by the lpszUserName parameter. If the call fails because the buffer is not big enough, this variable returns the required buffer size.

Returns

If the function succeeds, the return value is NO_ERROR. Otherwise, the return value is an error code, which can be retrieved by calling the GetLastError function. Possible return values from GetLastError include the following:

Value	Meaning

ERROR_NOT_CONNECTED	The device specified by lpszLocalName is not a redirected device or a connected network name.

ERROR_MORE_DATA	The buffer is too small.

ERROR_NO_NETWORK	No network is present.

ERROR_EXTENDED_ERROR	A network-specific error occurred. Use the WNetGetLastError function to obtain a description of the error.

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.

This function returns error codes for compatibility with Windows 3.1. For compatibility with Windows NT, the function also sets the error-code value returned by the GetLastError function.

See Also

WNetGetConnection, WNetGetLastError


WNetOpenEnum function
WNetOpenEnum (Win32)

DWORD WNetOpenEnum(fdwScope, fdwType, fdwUsage, lpNetResource, lphEnum)

DWORD fdwScope;	/* scope of enumeration	*/
DWORD fdwType;	/* resource types to list	*/
DWORD fdwUsage;	/* resource usage to list	*/
LPNETRESOURCE lpNetResource;	/* address of resource structure	*/
LPHANDLE lphEnum;	/* address of enumeration handle buffer	*/

The WNetOpenEnum function starts an enumeration of network resources or existing connections.

Parameter	Description

fdwScope	Specifies the scope of the enumeration. This parameter can be one of the following values:

Value	Meaning

RESOURCE_CONNECTED	All currently connected resources (fdwUsage is ignored).

RESOURCE_GLOBALNET	All resources on the network.

RESOURCE_REMEMBERED	All remembered (persistent) connections (fdwUsage is ignored).

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

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

The fdwUsage parameter is ignored if the fdwScope parameter is not RESOURCE_GLOBALNET.

lpNetResource	Points to a NETRESOURCE structure specifying the container to enumerate.

If lpNetResource 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. For more information about the Windows network functions, see Networks.

If lpNetResource is not NULL, it must point to a NETRESOURCE structure. This structure can be filled in by the application or returned by a call to the WNetEnumResource function. This NETRESOURCE structure must specify a container resource; that is, the RESOURCEUSAGE_CONTAINER bit must be set 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 the WNetEnumResource function to enumerate resources. If one of the resources in the NETRESOURCE array returned by the WNetEnumResource function is a container resource, the WNetOpenEnum function can be used to open the resource for further enumeration.

If the fdwScope parameter is not RESOURCE_GLOBALNET, lpNetResource must be NULL.

lphEnum	Points to variable filled in with an enumeration handle that can be used in a subsequent call to the WNetEnumResource function.

Returns

If the function succeeds, the return value is NO_ERROR. Otherwise, the return value is an error code, which can be retrieved by calling the GetLastError function. Possible return values from GetLastError include the following:

Value	Meaning

ERROR_NOT_CONTAINER	The lpNetResource parameter does not point to a container.

ERROR_INVALID_PARAMETER	Either the fdwScope or the fdwType 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. Use the WNetGetLastError function to obtain a description of the error.

This function returns error codes for compatibility with Windows 3.1. For compatibility with Windows NT, the function also sets the error-code value returned by the GetLastError function.

Comments

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

WNetCloseEnum, WNetEnumResource


WriteConsole function
WriteConsole (Win32)

BOOL WriteConsole(hConsoleOutput, lpvBuffer, cchToWrite, lpcchWritten, lpvReserved)

HANDLE hConsoleOutput;	/* handle of a console screen buffer	*/
CONST VOID *lpvBuffer;	/* address of buffer to write from	*/
DWORD cchToWrite;	/* number of characters to write	*/
LPDWORD lpcchWritten;	/* address of number of characters written	*/
LPVOID lpvReserved;	/* reserved	*/

The WriteConsole function writes a character string to a console screen buffer beginning at the current cursor location.

Parameter	Description

hConsoleOutput	Identifies the console screen buffer to write to. The handle must have GENERIC_WRITE access.

lpvBuffer	Points to a buffer that contains characters to be written to the screen buffer.

cchToWrite	Specifies the number of characters to write.

lpcchWritten	Points to a 32-bit variable that receives the number of characters actually written.

lpvReserved	Reserved; must be NULL.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

WriteConsole writes characters to a console screen buffer. It behaves like the WriteFile function except that 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. However, WriteConsole can only be used with a console screen buffer handle; WriteFile can also be used with other handles (such as files or pipes). This means that 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. There are, however, Win32 functions that provide equivalent functionality: SetCursorPos, SetConsoleTextAttribute, and GetConsoleCursorInfo, for example.

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 this 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 query and set the output modes of a console screen buffer, use the GetConsoleMode and SetConsoleMode functions.

See Also

GetConsoleMode, GetConsoleScreenBufferInfo, ReadConsole, SetConsoleMode, SetConsoleTextAttribute, WriteFile


WriteConsoleInput function
WriteConsoleInput (Win32)

BOOL WriteConsoleInput(hConsoleInput, pirBuffer, cInRecords, lpcWritten)

HANDLE hConsoleInput;	/* handle of a console input buffer	*/
PINPUT_RECORD pirBuffer;	/* address of the buffer for write data	*/
DWORD cInRecords;	/* number of records to write	*/
LPDWORD lpcWritten;	/* address of number of records written	*/

The WriteConsoleInput function writes data directly to the console input buffer.

Parameter	Description

hConsoleInput	Identifies the input buffer. The handle must have GENERIC_WRITE access.

pirBuffer	Points to an INPUT_RECORD buffer containing data to be written to the input buffer.

cInRecords	Specifies the number of input records to write.

lpcWritten	Points to a 32-bit variable that receives the number of input records actually written.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

See Also

PeekConsoleInput, ReadConsoleInput


WriteConsoleOutput function
WriteConsoleOutput (Win32)

BOOL WriteConsoleOutput(hConsoleOutput, pchiSrcBuffer, coordSrcBufferSize, coordSrcBufferCoord, psrctDestRect)

HANDLE hConsoleOutput;	/* handle of a console screen buffer	*/
PCHAR_INFO pchiSrcBuffer;	/* address of buffer with data to write	*/
COORD coordSrcBufferSize;	/* column-row size of source buffer	*/
COORD coordSrcBufferCoord;	/* upper left cell to write from	*/
PSMALL_RECT psrctDestRect;	/* address of rectangle to write to	*/

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 given location in the source buffer.

Parameter	Description

hConsoleOutput	Identifies the screen buffer. The handle must have GENERIC_WRITE access.

pchiSrcBuffer	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 coordSrcBufferSize parameter.

coordSrcBufferSize	Specifies the size, in character cells, of the buffer pointed to by the pchiSrcBuffer parameter. The X member of the COORD structure is the number of columns; the Y member is the number of rows.

coordSrcBufferCoord	Specifies the coordinates of the upper left cell in the buffer pointed to by the pchiSrcBuffer parameter to write data from. The X member of the COORD structure is the column, and the Y member is the row.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 psrctDestRect parameter specifies the size and location of the block to write to in the screen buffer. A rectangle of the same size is located with its upper left cell at the coordinates of the coordSrcBufferCoord parameter in the pchiSrcBuffer array. Data from the cells that are in the intersection of this rectangle and the source buffer rectangle (whose dimensions are specified by the coordSrcBufferSize 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 there is no data available to be written.

Before WriteConsoleOutput returns, it sets the members of psrctDestRect to the actual screen buffer rectangle affected by the write operation. This reflects the cells in the destination rectangle for which there existed a corresponding cell in the source buffer; and it clips the dimensions of the destination rectangle to the boundaries of the screen buffer.

If the rectangle specified by psrctDestRect 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 psrctDestRect 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.

See Also

ReadConsoleOutput, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, WriteConsoleOutputAttribute, WriteConsoleOutputCharacter


WriteConsoleOutputAttribute function
WriteConsoleOutputAttribute (Win32)

BOOL WriteConsoleOutputAttribute(hConsoleOutput, lpwAttribute, cWriteCells, coordWrite, lpcWritten)

HANDLE hConsoleOutput;	/* handle of a console screen buffer	*/
LPWORD lpwAttribute;	/* address of buffer to write attributes from	*/
DWORD cWriteCells;	/* number of character cells to write to	*/
COORD coordWrite;	/* coordinates of first cell to write to	*/
LPDWORD lpcWritten;	/* address of number of cells written to	*/

The WriteConsoleOutputAttribute function copies a specified number of foreground and background color attributes to consecutive cells of a console screen buffer, beginning at a given location.

Parameter	Description

hConsoleOutput	Identifies the screen buffer. The handle must have GENERIC_WRITE access.

lpwAttribute	Points to a buffer that contains the attributes to write to the screen buffer.

cWriteCells	Specifies the number of screen buffer character cells to write to.

coordWrite	Specifies the column and row coordinates of the first cell in the screen buffer to write to.

lpcWritten	Points to a 32-bit variable that receives the number of attributes actually written to the screen buffer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If the number of attributes to write 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 write 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 function
WriteConsoleOutputCharacter (Win32)

BOOL WriteConsoleOutputCharacter(hConsoleOutput, lpWriteBuffer, cchWrite, coordWriteCoord, lpcWritten)

HANDLE hConsoleOutput;	/* handle of a console screen buffer	*/
LPTSTR lpWriteBuffer;	/* address of buffer to write characters from	*/
DWORD cchWrite;	/* number of character cells to write to	*/
COORD coordWriteCoord;	/* coordinates of first cell to write to	*/
LPDWORD lpcWritten;	/* address of number of cells written to	*/

The WriteConsoleOutputCharacter function copies a specified number of characters to consecutive cells of a console screen buffer, beginning at a given location.

Parameter	Description

hConsoleOutput	Identifies the screen buffer. The handle must have GENERIC_WRITE access.

lpWriteBuffer	Points to a buffer that contains the characters to write to the screen buffer.

cchWrite	Specifies the number of screen buffer character cells to write to.

coordWriteCoord	Specifies the column and row coordinates of the first cell in the screen buffer to write to.

lpcWritten	Points to a doubleword that the function sets on exit to the number of characters written to the screen buffer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, characters are written up to the end of the screen buffer.

The attribute values at the positions written to are not changed.

See Also

ReadConsoleOutput, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, WriteConsoleOutput, WriteConsoleOutputAttribute


WriteFile function
WriteFile (Win32)

BOOL WriteFile(hFile, lpBuffer, nNumberOfBytesToWrite, lpNumberOfBytesWritten, lpOverlapped)

HANDLE hFile;	/* file to write to	*/
LPCVOID lpBuffer;	/* address of data to write to file	*/
DWORD nNumberOfBytesToWrite;	/* number of bytes to write	*/
LPDWORD lpNumberOfBytesWritten;	/* address of number of bytes written	*/
LPOVERLAPPED lpOverlapped;	/* addr. of structure needed for overlapped I/O	*/

The WriteFile function writes data to a file. The function starts writing data to the file at the position indicated by the file pointer. After the write 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 is finished.

Parameter	Description

hFile	Identifies the file to be written. The file handle must have been created with GENERIC_WRITE access to the file.

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.

lpNumberOfBytesWritten	Specifies the number of bytes written by this call. WriteFile sets this value to zero before doing any work or error checking.

lpOverlapped	Points to an OVERLAPPED structure that is required if hFile was opened with FILE_FLAG_OVERLAPPED.

This parameter must not be NULL if hFile was opened with FILE_FLAG_OVERLAPPED. It must point to a valid OVERLAPPED structure. If hFile was created with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function fails in unpredictable ways.

If hFile was not created 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 created 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 created 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If part of the file is locked by another process and the write overlaps the locked portion, this function fails.

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.

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. Use the SetEndOfFile function to truncate or extend a file.

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.

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

CreateFile, GetOverlappedResult, ReadFile, SetEndOfFile, WriteFileEx


WriteFileEx function
WriteFileEx (Win32)

BOOL WriteFileEx(hFile, lpBuffer, nNumberOfBytesToWrite, lpOverlapped, lpCompletionRoutine)

HANDLE hFile;	/* file to write	*/
LPCVOID lpBuffer;	/* address of buffer	*/
DWORD nNumberOfBytesToWrite;	/* no. of bytes to write	*/
LPOVERLAPPED lpOverlapped;	/* address of offset	*/
LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine;	/* addr. of routine	*/

The WriteFileEx function writes data to a file and reports its completion status asynchronously. This function is an extension to the WriteFile function that enables an application to continue with other processing.

Parameter	Description

hFile	Identifies the file to write to. The file handle must have been created with the FILE_FLAG_OVERLAPPED flag and must have GENERIC_WRITE access to the file.

lpBuffer	Points to the buffer that contains the data to write to the file. The application must not use this buffer until overlapped input and output (I/O) has been completed.

nNumberOfBytesToWrite	Specifies the number of bytes to write to the file. If nNumberOfBytesToWrite is zero, this function does nothing.

lpOverlapped	Points to an OVERLAPPED structure. This structure must be valid for the duration of the write operation. It should not be a local variable if the calling application can return while the write operation is pending.

lpCompletionRoutine	Points to the completion routine called when the write operation has been completed. For more information about the completion routine, see the description of the FileIOCompletionRoutine function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

If the write operation is not yet completed, the function returns TRUE. If the calling thread is in an alertable wait (using the SleepEx, WaitForSingleObjectEx, or WaitForMultipleObjectsEx function) when the write operation is completed, the completion routine is called and the wait is completed with a return value of WAIT_IO_COMPLETION.

If the calling thread is not in an alertable wait when the write operation finishes, Windows queues the completion routine call until the thread enters an alertable wait.

Comments

If part of the file is locked by another process and the read overlaps the locked portion, this function fails.

The WriteFileEx function may fail with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

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

CreateFile, ReadFileEx, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFile


WritePrivateProfileSection function
WritePrivateProfileSection (Win32)

BOOL WritePrivateProfileSection(lpszSection, lpszKeysAndValues, lpszFile)

LPCTSTR lpszSection;	/* address of string with section name	*/
LPCTSTR lpszKeysAndValues;	/* address of string with data	*/
LPCTSTR lpszFile;	/* address of string with filename	*/

The WritePrivateProfileSection function replaces the keys and values under the specified section in the given initialization file.

This function is provided for compatibility with 16-bit Windows-based applications. New applications should store initialization information in the registry.

Parameter	Description

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

lpszKeysAndValues	Points to a buffer containing the new key names and associated values that are written to the named section.

lpszFile	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 lpszFile does not contain a full path, the function creates the file in the Windows directory. The function does not create a file if lpszFile contains the full path and filename of a file that does not exist.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The data in the buffer pointed to by the lpszKeysAndValues 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 lpszSection parameter can be a combination of uppercase and lowercase letters.

If no section name matches the string pointed to by the lpszSection 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 lpszKeysAndValues 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.

Calls to PrivateProfile 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 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.

See Also

GetPrivateProfileSection, RegCreateKeyEx, RegSetValueEx, WriteProfileSection


WritePrivateProfileString function
WritePrivateProfileString (Win32)

BOOL WritePrivateProfileString(lpszSection, lpszKey, lpszString, lpszFile)

LPCTSTR lpszSection;	/* address of section name	*/
LPCTSTR lpszKey;	/* address of key name	*/
LPCTSTR lpszString;	/* address of string to add	*/
LPCTSTR lpszFile;	/* address of initialization filename	*/

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. New applications should store initialization information in the registry.

Parameter	Description

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 entries within the section, is deleted.

lpszString	Points to a null-terminated string to be written to the file. If this parameter is NULL, the key pointed to by the lpszKey parameter is deleted.

lpszFile	Points to a null-terminated string that names the initialization file.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

To improve performance, Windows keeps a cached version of the most-recently accessed initialization file. If that filename is specified and the other three parameters are NULL, Windows flushes the cache. In that case, the function returns FALSE, even if the flush succeeds.

A section in the initialization file must have the following form:

[section]

key=string

      .

      .

      .

If the lpszFile 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 lpszFile contains a full path and filename and the file does not exist, WriteProfileString creates the file. The specified directory must already exist.

An application can use the WritePrivateProfileString function to enter .INI file information into the registry. To do so, an application 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.

Enter 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, an application should specify SYS for an added value.

For application files, an application should 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".

The following sample code illustrates the foregoing guidelines. These assumptions are made :

There is an application named "Foo Bar"

That application uses an .INI file named "foobar.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.

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\\foobar.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 foobar.ini key\n");

    return (0) ;

    }

  /* try to set a section value */

  lRetCode = RegSetValueEx ( hKey1,

                             "Section1",

                             0,

                             REG_SZ,

                             "USR:Foo Bar\\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 a Foo Bar key */

  lRetCode = RegCreateKeyEx ( HKEY_CURRENT_USER,

                              "Foo Bar",

                              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 Foo Bar key\n");

    return (0) ;

    }

  /* if we get this far, all has gone well */

  /* let's write some added values */

  WritePrivateProfileString ("Section1", "FirstKey",

                             "It all worked out okay.", "foobar.ini");

  WritePrivateProfileString ("Section1", "SecondKey",

                             "By golly, it works.", "foobar.ini");

  WritePrivateProfileSection ("Section1", "ThirdKey = Another Test.",

                              "foobar.ini");

  /* let's test our work */

  GetPrivateProfileString ("Section1", "FirstKey",

                           "Bogus Value: Get didn't work", inBuf, 80,

                           "foobar.ini");

  printf ("%s", inBuf);

  /* okay, we are outta here */

  return(0);

}

See Also

GetPrivateProfileString, WriteProfileString


WriteProcessMemory function
WriteProcessMemory (Win32)

BOOL WriteProcessMemory(hProcess, lpBaseAddress, lpBuffer, cbWrite, lpNumberOfBytesWritten)

HANDLE hProcess;	/* handle of process whose memory is written to	*/
LPVOID lpBaseAddress;	/* address to start writing to	*/
LPVOID lpBuffer;	/* address of buffer to write data to	*/
DWORD cbWrite;	/* number of bytes to write	*/
LPDWORD lpNumberOfBytesWritten;	/* actual number of bytes written	*/

The WriteProcessMemory function writes memory in a specified process. The entire area to be written to must be accessible, or the operation fails.

Parameter	Description

hProcess	Identifies an open handle of 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 specified process address space.

cbWrite	Specifies the requested number of bytes to write into the specified process.

lpNumberOfBytesWritten	Specifies an optional parameter that, if supplied, receives the actual number of bytes transferred into the specified process. If lpNumberOfBytesWritten is NULL, the parameter is ignored.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function. The function will fail if the requested write operation crosses into an area of the process that is inaccessible.

Comments

This function 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 WriteProcessMemory. 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 above.

See Also

ReadProcessMemory


WriteProfileSection function
WriteProfileSection (Win32)

BOOL WriteProfileSection(lpszSection, lpszKeysAndValues)

LPCTSTR lpszSection;	/* address of section name	*/
LPCTSTR lpszKeysAndValues;	/* address of buffer with data	*/

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. New applications should store initialization information in the registry.

Parameter	Description

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

lpszKeysAndValues	Points to a buffer containing the new key names and associated values that are written to the named section.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 lpszKeysAndValues parameter.

Keys and values in the lpszKeysAndValues buffer, consists 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 lpszKeysAndValues. 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.

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

See Also

GetProfileSection, WritePrivateProfileSection


WriteProfileString function
WriteProfileString (Win32)

BOOL WriteProfileString(lpszSection, lpszKey, lpszString)

LPCTSTR lpszSection;	/* address of section name	*/
LPCTSTR lpszKey;	/* address of key name	*/
LPCTSTR lpszString;	/* address of string to write	*/

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. New applications should store initialization information in the registry.

Parameter	Description

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

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

lpszString	Points to a null-terminated string to be written to the file. If this parameter is NULL, the key pointed to by the lpszKey parameter is deleted.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Windows keeps a cached version of WIN.INI to improve performance. If all three parameters are NULL, Windows flushes the cache.

A section in the WIN.INI file must have the following form:

[section]

key=string

    .

    .

    .

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

See Also

GetProfileString, WritePrivateProfileString


WriteTapemark function
WriteTapemark (Win32)

DWORD WriteTapemark(hDevice, dwTapemarkType, dwTapemarkCount, bImmediate)

HANDLE hDevice;	/* handle of open device	*/
DWORD dwTapemarkType;	/* type of tapemarks to write	*/
DWORD dwTapemarkCount;	/* number of tapemarks to write	*/
BOOL bImmediate;	/* return after write begins	*/

Parameter	Description

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.

Returns

If the function succeeds, the return value is NO_ERROR; otherwise, it can be 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.

Comments

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.


wsprintf function
wsprintf (Win32)

int wsprintf(lpOut, lpFmt [[, argument]. . .)

LPTSTR lpOut;	/* address of buffer for output	*/
LPCTSTR lpFmt;	/* address of format-control string	*/

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.

Parameter	Description

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 Comments section.

argument	Specifies one or more optional arguments. The number and type of argument parameters depend on the corresponding format-control specifications in the lpFmt parameter.

Returns

If the function succeeds, the return value is the number of characters stored in the output buffer, not counting the terminating null character. Otherwise, the return value is less than the length of the format-control string. To get extended error information, use the GetLastError function.

Comments

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 calling process's responsibility 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 function
wvsprintf (Win32)

int wvsprintf(lpOutput, lpFormat, arglist)

LPTSTR lpOutput;	/* address of buffer for output	*/
LPCTSTR lpFormat;	/* address of format-control string	*/
va_list arglist;	/* variable argument list of format-control arguments	*/

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.

Parameter	Description

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 description of 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.

Returns

If the function succeeds, the return value is the number of characters stored in the buffer, not counting the terminating null character. Otherwise, the return value is less than the length of the format-control string. To get extended error information, use the GetLastError function.

See Also

wsprintf


ZeroMemory function
ZeroMemory (Win32)

VOID ZeroMemory (Destination, Length)

PVOID Destination;	/* address of block to fill with zeroes	*/
DWORD Length;	/* size in bytes of block to fill with zeroes	*/

The ZeroMemory function fills a block of memory with zeroes.

Parameter	Description

Destination	Points to the starting address of the block of memory to fill with zeroes.

Length	Specifies the size in bytes of the block of memory to fill with zeroes.

Returns

This function has no return value.

See Also

CopyMemory, FillMemory, MoveMemory


AccessResource function
AccessResource (Win32)

The AccessResource function has been deleted. For Win32 applications, use the LoadResource, LockResource, and FindResource functions.


AllocDStoCSAlias function
AllocDStoCSAlias (Win32)

The AllocDStoCSAlias function is obsolete.


AllocResource function
AllocResource (Win32)

The AllocResource function has been deleted. For Win32 applications, use the LoadResource, LockResource, and FindResource functions.


AllocSelector function
AllocSelector (Win32)

The AllocSelector function has been deleted.


Catch function
Catch (Win32)

The Catch function has been deleted.

Structured exception handling is built into the Win32 application programming interface. For more information about structured exception handling, see Structured Exception Handling.


ChangeSelector function
ChangeSelector (Win32)

The ChangeSelector function has been deleted.


CloseSound function
CloseSound (Win32)

The CloseSound function has been deleted.

See Also

Beep, MessageBeep, PlaySound


CountVoiceNotes function
CountVoiceNotes (Win32)

The CountVoiceNotes function has been deleted.

See Also

Beep, MessageBeep, PlaySound


DefineHandleTable function
DefineHandleTable (Win32)

The DefineHandleTable function is obsolete.


DOS3Call function
DOS3Call (Win32)

The DOS3Call function is obsolete. Win32 applications cannot call MS-DOS directly.


FreeModule function
FreeModule (Win32)

The FreeModule function is obsolete.

This function is provided only for compatibility with earlier versions of Windows. Win32 functions should not use this function.

See Also

FreeLibrary


FreeProcInstance function
FreeProcInstance (Win32)

The FreeProcInstance function is obsolete.

This function is provided only for compatibility with earlier versions of Windows. Win32 applications should not use this function.


FreeSelector function
FreeSelector (Win32)

The FreeSelector function has been deleted.


GetAtomHandle function
GetAtomHandle (Win32)

The GetAtomHandle function is obsolete and cannot be used by Win32 applications.


GetCodeHandle function
GetCodeHandle (Win32)

The GetCodeHandle function has been deleted. Win32 modules are mapped and do not have handles associated with their code addresses.


GetCodeInfo function
GetCodeInfo (Win32)

The GetCodeInfo function has been deleted.


GetCurrentPDB function
GetCurrentPDB (Win32)

The GetCurrentPDB function has been deleted. For Win32 applications, use the GetCommandLine and GetEnvironmentStrings functions.

See Also

GetCommandLine, GetEnvironmentStrings


GetCurrentTask function
GetCurrentTask (Win32)

The GetCurrentTask function has been deleted. For Win32 applications, use the GetCurrentThread or GetCurrentProcess function.


GetDOSEnvironment function
GetDOSEnvironment (Win32)

The GetDOSEnvironment function has been deleted. For Win32 applications, use the GetEnvironmentStrings function.

See Also

GetEnvironmentStrings


GetFreeSpace function
GetFreeSpace (Win32)

The GetFreeSpace function is obsolete. Win32 applications should use the GlobalMemoryStatus function.

See Also

GlobalMemoryStatus


GetInstanceData function
GetInstanceData (Win32)

The GetInstanceData function has been deleted. Each Win32 application runs in its own address space.


GetModuleUsage function
GetModuleUsage (Win32)

The GetModuleUsage function has been deleted. Each Win32 application runs in its own address space.


GetTempDrive function
GetTempDrive (Win32)

The GetTempDrive function is obsolete. Win32 applications should use the GetTempPath function.

See Also

GetTempPath


GetThresholdEvent function
GetThresholdEvent (Win32)

The GetThresholdEvent function has been deleted.

See Also

Beep, MessageBeep, PlaySound


GetThresholdStatus function
GetThresholdStatus (Win32)

The GetThresholdStatus function has been deleted.

See Also

Beep, MessageBeep, PlaySound


GetWinFlags function
GetWinFlags (Win32)

The GetWinFlags function has been deleted. Win32 applications should use the GetSystemInfo function.

See Also

GetSystemInfo


GlobalCompact function
GlobalCompact (Win32)

The GlobalCompact function is obsolete.


GlobalDosAlloc function
GlobalDosAlloc (Win32)

The GlobalDosAlloc function has been deleted.


GlobalDosFree function
GlobalDosFree (Win32)

The GlobalDosFree function has been deleted.


GlobalFix function
GlobalFix (Win32)

The GlobalFix function is obsolete.


GlobalLRUNewest function
GlobalLRUNewest (Win32)

The GlobalLRUNewest function is obsolete.


GlobalLRUOldest function
GlobalLRUOldest (Win32)

The GlobalLRUOldest function is obsolete.


GlobalNotify function
GlobalNotify (Win32)

The GlobalNotify function has been deleted. Win32 applications should use the GlobalFlags function.

See Also

GlobalFlags


GlobalPageLock function
GlobalPageLock (Win32)

The GlobalPageLock function has been deleted. Win32 applications should use the VirtualLock and VirtualUnlock functions.

See Also

VirtualLock, VirtualUnlock


GlobalPageUnlock function
GlobalPageUnlock (Win32)

The GlobalPageUnlock function has been deleted. Win32 applications should use the VirtualLock and VirtualUnlock functions.

See Also

VirtualLock, VirtualUnlock


GlobalUnfix function
GlobalUnfix (Win32)

The GlobalUnfix function is obsolete.


GlobalUnWire function
GlobalUnWire (Win32)

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 in Win32 only for compatibility with earlier versions of Windows. New Win32 applications should not use this function.

See Also

GlobalLock, GlobalUnlock


GlobalWire function
GlobalWire (Win32)

The GlobalWire function is obsolete. Win32 applications should use the GlobalLock and GlobalUnlock functions.

See Also

GlobalLock, GlobalUnlock


IsTask function
IsTask (Win32)

The IsTask function has been deleted.


LimitEmsPages function
LimitEmsPages (Win32)

The LimitEmsPages function is obsolete. This function is x86 specific.

This function is provided in Win32 only for compatibility with earlier versions of Windows. New Win32 applications should not use this function.


LocalCompact function
LocalCompact (Win32)

The LocalCompact function is obsolete.


LocalInit function
LocalInit (Win32)

The LocalInit function has been deleted.


LocalShrink function
LocalShrink (Win32)

The LocalShrink function is obsolete.


LockSegment function
LockSegment (Win32)

The LockSegment function is obsolete.


MakeProcInstance function
MakeProcInstance (Win32)

The MakeProcInstance function is obsolete. Win32 functions can be called directly.

This function is provided in Win32 only for compatibility with earlier versions of Windows. Win32 applications should not use this function.


OpenSound function
OpenSound (Win32)

The OpenSound function has been deleted.

See Also

Beep, MessageBeep, PlaySound


SetResourceHandler function
SetResourceHandler (Win32)

The SetResourceHandler function has been deleted. Calculated resources do not work in the Win32 application environment.


SetSoundNoise function
SetSoundNoise (Win32)

The SetSoundNoise function has been deleted.

See Also

Beep, MessageBeep, PlaySound


SetSwapAreaSize function
SetSwapAreaSize (Win32)

The SetSwapAreaSize function is obsolete.


SetVoiceAccent function
SetVoiceAccent (Win32)

The SetVoiceAccent function has been deleted.

See Also

Beep, MessageBeep, PlaySound


SetVoiceEnvelope function
SetVoiceEnvelope (Win32)

The SetVoiceEnvelope function has been deleted.

See Also

Beep, MessageBeep, PlaySound


SetVoiceNote function
SetVoiceNote (Win32)

The SetVoiceNote function has been deleted.

See Also

Beep, MessageBeep, PlaySound


SetVoiceQueueSize function
SetVoiceQueueSize (Win32)

The SetVoiceQueueSize function has been deleted.

See Also

Beep, MessageBeep, PlaySound


SetVoiceSound function
SetVoiceSound (Win32)

The SetVoiceSound function has been deleted.

See Also

Beep, MessageBeep, PlaySound


SetVoiceThreshold function
SetVoiceThreshold (Win32)

The SetVoiceThreshold function has been deleted.

See Also

Beep, MessageBeep, PlaySound


StartSound function
StartSound (Win32)

The StartSound function has been deleted.

See Also

Beep, MessageBeep, PlaySound


StopSound function
StopSound (Win32)

The StopSound function has been deleted.

See Also

Beep, MessageBeep, PlaySound


SwitchStackBack function
SwitchStackBack (Win32)

The SwitchStackBack function has been deleted.


SwitchStackTo function
SwitchStackTo (Win32)

The SwitchStackTo function has been deleted.


SyncAllVoices function
SyncAllVoices (Win32)

The SyncAllVoices function has been deleted.

See Also

Beep, MessageBeep, PlaySound


Throw function
Throw (Win32)

The Throw function has been deleted.

Structured exception handling is built into the Win32 application programming interface. For more information about structured exception handling, see Structured Exception Handling.


UnlockSegment function
UnlockSegment (Win32)

The UnlockSegment function is obsolete.


WaitSoundState function
WaitSoundState (Win32)

The WaitSoundState function has been deleted.

See Also

Beep, MessageBeep, PlaySound


Yield function
Yield (Win32)

void Yield(void)

The Yield function is obsolete. In the Win32 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 timeslice.

See Also

DispatchMessage, PeekMessage, Sleep, TranslateMessage


System Services Functions (all)

AbnormalTermination	Returns try-finally status

AbortSystemShutdown	Stops the system

AddAtom	Adds a string to the local atom table

AcsLan	Communicates with network devices using DLC protocol

AllocConsole	Creates a console for the calling process

BackupEventLog	Saves an event log in a backup file

BackupRead	Tape backup read

BackupSeek	Tape backup seek

BackupWrite	Tape backup write

Beep	Generates a tone

BeginUpdateResource	Start resource update in executable file

BuildCommDCB	Translates device definition string to a DCB

BuildCommDCBAndTimeouts	Builds up comm DCB and sets timeout values

CallNamedPipe	Multiple pipe operations

ClearCommBreak	Restores character transmission

ClearCommError	Enables communications after an error

ClearEventLog	Clears the event log

CloseEventLog	Closes an event-log handle

CloseHandle	Closes an open object handle

CompareFileTime	Compares two 64-bit file times

ConnectNamedPipe	Waits for a client to connect

ContinueDebugEvent	Causes a debugged thread to continue

CopyFile	Copies a file

CopyMemory	Copies a block of memory

CreateConsoleScreenBuffer	Returns a handle to a new screen buffer

CreateDirectory	Creates a new directory

CreateDirectoryEx	Creates a new directory with attributes of a template directory

CreateEvent	Returns a handle to a new event object

CreateFile	Creates, opens or truncates a file

CreateFileMapping	Returns handle to a new file mapping object

CreateMailslot	Creates a mailslot

CreateMutex	Returns a handle to a new mutex object

CreateNamedPipe	Creates an instance of a named pipe

CreatePipe	Creates an anonymous pipe

CreateProcess	Creates a new process and thread object

CreateRemoteThread	Creates a thread in another process

CreateSemaphore	Returns a handle to a new semaphore

CreateTapePartition	Create new tape partition

CreateThread	Creates a new thread

DefineDosDevice	Defines, redefines, or deletes DOS device names

DebugActiveProcess	Attaches a process for debugging

DebugBreak	Causes a breakpoint exception in the caller

DeleteAtom	Deletes an atom

DeleteCriticalSection	Deletes an unowned critical section object

DeleteFile	Deletes an existing file

DeregisterEventSource	Closes a registered event handle

DisconnectNamedPipe	Disconnects server end of a named pipe

DosDateTimeToFileTime	Converts MS-DOS date/time to 64 bits

DuplicateHandle	Duplicates an object handle

EndUpdateResource	End resource update in executable file

EnterCriticalSection	Requests ownership of critical section object

EnumResourceLanguages	List resource languages

EnumResourceNames	List resource names

EnumResourceTypes	List resource types

EraseTape	Erase specified portion of tape

EscapeCommFunction	Sends an extended comm function

ExitProcess	Exits the current process

ExitThread	Exits the current thread

ExpandEnvironmentStrings	Expands environment variable strings

FatalAppExit	Terminates an application

FatalExit	Returns control to the debugger

FileTimeToDosDateTime	Converts file time to MS-DOS date/time

FileTimeToLocalFileTime	Converts file time to local file time

FileTimeToSystemTime	Converts 64-bit time to system time

FillConsoleOutputAttribute	Writes attributes to the screen buffer

FillConsoleOutputCharacter	Writes characters to the screen buffer

FillMemory	Fills a block of memory with a specified value

FindAtom	Retrieves string atom from local atom table

FindClose	Close a find-file context

FindCloseChangeNotification	Close file or directory change wait

FindFirstChangeNotification	Setup file or directory change wait

FindFirstFile	Finds the first matching file

FindNextChangeNotification	Next file or directory change wait

FindNextFile	Finds the next matching file

FindResource	Locates a resource in a module

FindResourceEx	Locates a resource in a module

FlushConsoleInputBuffer	Clears the console input buffer

FlushFileBuffers	Clears the file buffers

FlushInstructionCache	Flushes the instruction cache

FlushViewOfFile	Flushes a byte range within a mapped view

FormatMessage	Formats a message string

FreeConsole	Frees the console for the calling process

FreeLibrary	Unloads a library module instance

FreeResource	Unloads a resource

GenerateConsoleCtrlEvent	Sends a signal to a console process group

GetAtomName	Retrieves a local atom string

GetCommandLine	Returns a pointer to the command line

GetCommMask	Returns comm event mask

GetCommModemStatus	Returns modem control register values

GetCommProperties	Returns comm device properties

GetCommState	Returns comm device control block

GetCommTimeouts	Returns comm device timeout characteristics

GetComputerName	Retrieves current computer name

GetConsoleCP	Gets code page for console input

GetConsoleCursorInfo	Returns cursor size and visibility

GetConsoleMode	Returns console input or output mode

GetConsoleOutputCP	Gets code page for console output

GetConsoleScreenBufferInfo	Returns screen-buffer information

GetConsoleTitle	Returns console-window title

GetCurrentDirectory	Returns process current directory

GetCurrentProcess	Returns a handle to the current process

GetCurrentProcessId	Returns the current process ID

GetCurrentThread	Returns a handle to the current thread

GetCurrentThreadId	Returns the current thread ID

GetDiskFreeSpace	Returns amount of free disk space

GetDriveType	Returns type for specified drive

GetEnvironmentStrings	Returns a pointer to the environment block

GetEnvironmentVariable	Returns process environment variable

GetExceptionCode	Returns exception type

GetExceptionInformation	Returns exception details

GetExitCodeProcess	Retrieves process termination code

GetExitCodeThread	Returns thread termination code

GetFileAttributes	Returns file attributes

GetFileInformationByHandle	Retrieves file information

GetFileSize	Returns size for specified file

GetFileTime	Returns 64-bit file times

GetFileType	Returns type for specified file

GetFullPathName	Retrieves a path name for a file name

GetLargestConsoleWindowSize	Returns largest possible window size

GetLastError	Returns extended error code

GetLocalTime	Returns local time and date

GetLogicalDrives	Returns a bitmask specifying valid drives

GetLogicalDriveStrings	Returns strings for valid drives

GetMailslotInfo	Retrieves mailslot information

GetModuleFileName	Returns path for specified module

GetModuleHandle	Returns handle for specified module

GetNamedPipeHandleState	Returns named-pipe handle information

GetNamedPipeInfo	Returns named-pipe handle information

GetNumberOfConsoleInputEvents	Retrieves number of console-queue events

GetNumberOfConsoleMouseButtons	Retrieves number of mouse buttons

GetNumberOfEventLogRecords	Gets number of records in event log

GetOldestEventLogRecord	Retrieves number of oldest record

GetOverlappedResult	Returns last overlapped result

GetPriorityClass	Returns priority class for a process

GetPrivateProfileInt	Gets an integer from private file

GetPrivateProfileSection	Returns private key and value pairs

GetPrivateProfileString	Gets a string from private file

GetProcAddress	Returns the address of a function

GetProcessHeap	Obtains handle to the calling process' heap

GetProcessShutdownParameters	Retrieves process shutdown parameters

GetProcessTimes	Obtains process timing information

GetProfileInt	Gets an integer from WIN.INI

GetProfileSection	Returns keys and values from WIN.INI

GetProfileString	Gets a string from WIN.INI

GetStartupInfo	Gets startup information for current process

GetStdHandle	Returns standard I/O handles

GetSystemDirectory	Returns path for Windows system dir

GetSystemInfo	Returns current system info

GetSystemTime	Returns system time and date

GetTapeParameters	Retrieve tape drive or media information

GetTapePosition	Returns the current tape position

GetTapeStatus	Retrieves tape-device status

GetTempFileName	Creates a temporary file name

GetTempPath	Returns path for temporary files

GetThreadContext	Returns specified thread context

GetThreadPriority	Returns specified thread priority

GetThreadSelectorEntry	Returns a thread descriptor entry

GetThreadTimes	Obtains thread timing information

GetTimeZoneInformation	Retrieves current time-zone settings

GetUserName	Returns the user's name

GetVersion	Returns Windows and operating-system version

GetVolumeInformation	Returns file-system information

GetWindowsDirectory	Returns path for Windows dir

GlobalAddAtom	Adds a string to the system atom table

GlobalAlloc	Allocates memory from the heap

GlobalDeleteAtom	Deletes an atom from the system atom table

GlobalDiscard	Discards a global memory object

GlobalFindAtom	Retrieves string atom from global atom table

GlobalFlags	Returns global memory object info

GlobalFree	Frees a global memory object

GlobalGetAtomName	Retrieves a global atom string

GlobalHandle	Translates a global pointer to a handle

GlobalLock	Locks global memory object and returns a pointer

GlobalMemoryStatus	Checks memory availability

GlobalReAlloc	Changes global memory object's size or attributes

GlobalSize	Returns the size of a global memory block

GlobalUnlock	Unlocks a global memory object

HandlerRoutine	Control handler function for a console process

HeapAlloc	Allocates memory from a private heap

HeapCreate	Creates a heap

HeapDestroy	Destroys a heap

HeapFree	Frees memory allocated from a heap

HeapReAlloc	Reallocates memory from a heap

HeapSize	Returns the size of a heap memory block

_hread	Reads from a file

_hwrite	Writes to a file

InitAtomTable	Initializes local atom table

InitializeCriticalSection	Initialize critical section object

InitiateSystemShutdown	Stops the system

InterlockedDecrement	Decrements a 32-bit variable

InterlockedExchange	Atomically exchanges 32-bit values

InterlockedIncrement	Increments a 32-bit variable

IsBadCodePtr	Determines whether a read pointer is valid

IsBadHugeReadPtr	Determines whether a read pointer is valid

IsBadHugeWritePtr	Determines whether a write pointer is valid

IsBadReadPtr	Determines whether a read pointer is valid

IsBadStringPtr	Determines whether a string pointer is valid

IsBadWritePtr	Determines whether a write pointer is valid

LeaveCriticalSection	Releases ownership of critical section object

LoadLibrary	Maps an executable module into process' address space

LoadLibraryEx	Returns a handle to a library module

LoadModule	Loads and executes a program

LoadResource	Returns a handle to a resource

LocalAlloc	Allocates memory from the heap

LocalDiscard	Discards a local memory block

LocalFileTimeToFileTime	Converts local file time to file time

LocalFlags	Returns local memory object information

LocalFree	Frees a local memory object

LocalHandle	Translates a local pointer to a handle

LocalLock	Locks local memory object and returns pointer

LocalReAlloc	Changes local memory object's size or attributes

LocalSize	Returns the size of a local memory block

LocalUnlock	Unlocks a local memory object

LockFile	Locks a region in an open file

LockFileEx	Locks a byte range in an open file

LockResource	Returns the address of a resource

lstrcat	Appends one string to another

lstrcmp	Compares two character strings

lstrcmpi	Compares two character strings

lstrcpy	Copies a string to a buffer

lstrlen	Returns the number of characters in a string

_lclose	Closes an open file

_lcreat	Creates or opens a file

_llseek	Repositions the file pointer

_lopen	Opens a file

_lread	Reads from a file

_lwrite	Writes to a file

MapViewOfFile	Maps a view into an address space

MapViewOfFileEx	Maps a view into an address space

MoveFile	Renames a file or directory

MoveFileEx	Renames a file

MoveMemory	Moves a block of memory

MulDiv	Multiplies two values and divides the result

Netbios	Executes specified NCB

OpenBackupEventLog	Opens a handle of a backup event log

OpenEvent	Opens an event object

OpenEventLog	Opens an event-log handle

OpenFile	Creates, opens or deletes a file

OpenFileMapping	Opens a named-file mapping object

OpenMutex	Opens a named mutex object

OpenProcess	Returns a handle to a process object

OpenSemaphore	Opens a named semaphore object

OutputDebugString	Sends a string to the debugger

PeekConsoleInput	Previews console input data

PeekNamedPipe	Previews pipe-queue data

PlaySound	Play a waveform sound

PrepareTape	Prepare the tape device

PulseEvent	Sets and resets an event

PurgeComm	Clears comm buffers

QueryDosDevice	Obtains information about DOS device names

QueryPerformanceCounter	Obtains performance counter value

QueryPerformanceFrequency	Returns performance-counter frequency

RaiseException	Raises an exception

ReadConsole	Reads console input data

ReadConsoleInput	Reads console input data

ReadConsoleOutput	Reads screen-buffer data

ReadConsoleOutputAttribute	Copies color attributes from a screen buffer

ReadConsoleOutputCharacter	Copies characters from a screen buffer

ReadEventLog	Reads entries from an event log

ReadFile	Reads from a file

ReadFileEx	Reads from a file asynchronously

ReadProcessMemory	Reads from memory within a process

RegisterEventSource	Returns a registered event-log handle

RegCloseKey	Closes a registration key

RegConnectRegistry	Connects to a remote registry

RegCreateKey	Creates or opens a key

RegCreateKeyEx	Creates or opens a key

RegDeleteKey	Deletes a key

RegDeleteValue	Removes a value from a registration key

RegEnumKey	Enumerates subkeys of specified key

RegEnumKeyEx	Enumerates subkeys of specified key

RegEnumValue	Enumerates values for specified key

RegFlushKey	Writes an open key to the registry

RegGetKeySecurity	Get registration key security

RegLoadKey	Loads a saved key and subkeys into the registry

RegNotifyChangeKeyValue	Indicates changes in registry key

RegOpenKey	Opens a key

RegOpenKeyEx	Opens a key

RegQueryInfoKey	Retrieves registry key information

RegQueryValue	Retrieves data for a key

RegQueryValueEx	Retrieves key type and value

RegReplaceKey	Replaces file that backs key and subkeys in the registry

RegRestoreKey	Loads a saved tree of keys into the registry

RegSaveKey	Saves a registry tree to a file

RegSetKeySecurity	Sets registration key security

RegSetValue	Associates a text string with a specified key

RegSetValueEx	Associates a text string with a specified key

RegUnLoadKey	Unloads a key and subkeys from the registry

ReleaseMutex	Releases a mutex object

ReleaseSemaphore	Releases a semaphore object

RemoveDirectory	Removes an existing directory

ReportEvent	Writes an event-log entry

ResetEvent	Resets an event object

ResumeThread	Restarts a suspended thread

ScrollConsoleScreenBuffer	Scrolls data in the screen buffer

SearchPath	Searches for a file

SetCommBreak	Suspends character transmission

SetCommMask	Sets comm event mask

SetCommState	Sets comm device to the specified state

SetCommTimeouts	Set comm read and write timeout values

SetComputerName	Sets the current computer name

SetConsoleActiveScreenBuffer	Changes displayed screen buffer

SetConsoleCP	Sets code page for console input

SetConsoleCtrlHandler	Sets signal handler for console process

SetConsoleCursorInfo	Sets console cursor size and visibility

SetConsoleCursorPosition	Sets console cursor position

SetConsoleMode	Sets console input or output mode

SetConsoleOutputCP	Sets code page for console output

SetConsoleScreenBufferSize	Changes screen-buffer size

SetConsoleTextAttribute	Sets attributes for screen text

SetConsoleTitle	Sets console-window title string

SetConsoleWindowInfo	Sets console window size

SetCurrentDirectory	Changes the current directory

SetDebugErrorLevel	Set error level for debug events

SetEndOfFile	Sets end-of-file pointer

SetEnvironmentVariable	Sets an environment variable

SetErrorMode	Control hard-error handling

SetEvent	Sets an event object

SetFileApisToOEM	Sets OEM character set for file APIs

SetFileAttributes	Sets file attributes

SetFilePointer	Sets file-pointer position

SetFileTime	Sets a file's 64-bit time

SetHandleCount	Sets the number of available file handles

SetLastError	Sets extended error code

SetLastErrorEx	Sets extended error code and type

SetLocalTime	Sets the local time and date

SetMailslotInfo	Sets mailslot read timeout

SetNamedPipeHandleState	Sets pipe read and blocking mode and controls local buffering

SetPriorityClass	Sets priority class for a process

SetProcessShutdownParameters	Sets process shutdown parameters

SetStdHandle	Sets the standard device handles

SetSystemTime	Sets the system time and date

SetTapeParameters	Set tape drive or media information

SetTapePosition	Sets the tape position

SetThreadContext	Sets a specified thread context

SetThreadPriority	Sets thread priority

SetTimeZoneInformation	Sets current time-zone settings

SetUnhandledExceptionFilter	Set filter function for exception handler

SetupComm	Sets communication parameters

SetVolumeLabel	Sets a volume's label string

SizeofResource	Returns resource size

Sleep	Suspends a thread for a set time

SleepEx	Suspends a thread until I/O completes

SuspendThread	Suspends a thread

SystemTimeToFileTime	Converts system time to 64-bit

TerminateProcess	Kills a process and its threads

TerminateThread	Kills a thread

TlsAlloc	Allocates thread local storage index

TlsFree	Frees thread local storage index

TlsGetValue	Returns a TLS value

TlsSetValue	Sets a TLS value

TransactNamedPipe	Reads and writes a named pipe

TransmitCommChar	Places a character in the transmit buffer

UnhandledExceptionFilter	Filter function for exception handler

UnlockFile	Unlocks a byte range in a file

UnlockFileEx	Unlocks a byte range in an open file

UnlockResource	Decrements resource lock count

UnmapViewOfFile	Unmaps a file view

UpdateResource	Modifies a resource in an executable file

VirtualAlloc	Reserves or commits a range of virtual pages

VirtualFree	Frees a range of virtual pages

VirtualLock	Locks a range of virtual pages

VirtualProtect	Changes virtual-memory protection

VirtualProtectEx	Changes virtual-memory access protection

VirtualQuery	Returns virtual-memory information

VirtualQueryEx	Returns virtual-memory information

VirtualUnlock	Unlocks a range of virtual pages

WaitCommEvent	Waits for masked comm events

WaitForDebugEvent	Waits for a debug event

WaitForInputIdle	Waits until a process is idle

WaitForMultipleObjects	Waits for multiple waitable objects

WaitForMultipleObjectsEx	Waits for multiple objects or I/O completion

WaitForSingleObject	Waits for single waitable object

WaitForSingleObjectEx	Waits for single object or I/O completion

WaitNamedPipe	Waits for a named pipe

WinExec	Runs a program

WNetAddConnection	Redirects a local device to a network resource

WNetAddConnection2	Redirects a local device to a network resource

WNetCancelConnection	Breaks an existing network connection

WNetCancelConnection2	Breaks an existing network connection

WNetCloseEnum	Ends a network resource list

WNetConnectionDialog	Starts a network connection dialog box

WNetDisconnectDialog	Starts a network disconnection dialog box

WNetEnumResource	Continue listing network resources

WNetGetConnection	Gets name of network resource

WNetGetLastError	Returns last error for network functions

WNetGetUser	Gets the current network user name

WNetOpenEnum	Starts listing network resources

WriteConsole	Writes to console screen buffer

WriteConsoleInput	Writes to console input buffer

WriteConsoleOutput	Writes directly to screen buffer

WriteConsoleOutputAttribute	Writes color attributes to screen buffer

WriteConsoleOutputCharacter	Writes characters to screen buffer

WriteFile	Writes data to file or device

WriteFileEx	Writes data to file or device

WritePrivateProfileSection	Writes a section to private INI file

WritePrivateProfileString	Writes a string to private INI file

WriteProcessMemory	Writes memory within a specified process

WriteProfileSection	Writes a section to WIN.INI

WriteProfileString	Writes a string to WIN.INI

WriteTapemark	Writes tape marks

wsprintf	Formats a string

wvsprintf	Formats a string

ZeroMemory	Fills a block of memory with zeroes

AccessResource	Obsolete

AllocDStoCSAlias	Obsolete

AllocResource	Obsolete

AllocSelector	Obsolete

Catch	Obsolete

ChangeSelector	Obsolete

CloseSound	Obsolete

CountVoiceNotes	Obsolete

DefineHandleTable	Obsolete

DOS3Call	Obsolete

FreeModule	Obsolete

FreeProcInstance	Obsolete

FreeSelector	Obsolete

GetAtomHandle	Obsolete

GetCodeHandle	Obsolete

GetCodeInfo	Obsolete

GetCurrentPDB	Obsolete

GetCurrentTask	Obsolete

GetDOSEnvironment	Obsolete

GetFreeSpace	Obsolete

GetInstanceData	Obsolete

GetModuleUsage	Obsolete

GetTempDrive	Obsolete

GetThresholdEvent	Obsolete

GetThresholdStatus	Obsolete

GetWinFlags	Obsolete

GlobalCompact	Obsolete

GlobalDosAlloc	Obsolete

GlobalDosFree	Obsolete

GlobalFix	Obsolete

GlobalLRUNewest	Obsolete

GlobalLRUOldest	Obsolete

GlobalNotify	Obsolete

GlobalPageLock	Obsolete

GlobalPageUnlock	Obsolete

GlobalUnfix	Obsolete

GlobalUnWire	Obsolete

GlobalWire	Obsolete

IsTask	Obsolete

LimitEmsPages	Obsolete

LocalCompact	Obsolete

LocalInit	Obsolete

LocalShrink	Obsolete

LockSegment	Obsolete

MakeProcInstance	Obsolete

OpenSound	Obsolete

SetResourceHandler	Obsolete

SetSoundNoise	Obsolete

SetSwapAreaSize	Obsolete

SetVoiceAccent	Obsolete

SetVoiceEnvelope	Obsolete

SetVoiceNote	Obsolete

SetVoiceQueueSize	Obsolete

SetVoiceSound	Obsolete

SetVoiceThreshold	Obsolete

StartSound	Obsolete

StopSound	Obsolete

SwitchStackBack	Obsolete

SwitchStackTo	Obsolete

SyncAllVoices	Obsolete

Throw	Obsolete

UnlockSegment	Obsolete

WaitSoundState	Obsolete

Yield	Obsolete


DefScreenSaverProc function
DefScreenSaverProc (Win32)

#include <scrnsave.h>

LONG DefScreenSaverProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;	/* handle of screen saver window	*/
UINT uMsg;	/* message	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The DefScreenSaverProc function provides default processing for any messages that a screen saver application does not process.

Parameter	Description

hwnd	Identifies the screen saver window.

uMsg	Specifies the message to be processed. The DefScreenSaverProc function responds to messages that affect the screen saver's operation as detailed in the Comments 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-dependent information.

lParam	Specifies additional message-dependent information.

Returns

The return value specifies the result of the message processing and depends on the message sent.

Comments

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 the WM_SYSCOMMAND message is either SC_SCREENSAVE or SC_CLOSE.
See Also

ScreenSaverProc


RegisterDialogClasses function
RegisterDialogClasses (Win32)

#include <scrnsave.h>

BOOL RegisterDialogClasses(hinst)

HANDLE hinst;	/* handle of application instance	*/

The RegisterDialogClasses function registers any nonstandard window classes required by a screen saver's configuration dialog box.

Parameter	Description

hinst	Identifies an instance of the module registering the window classes.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


ScreenSaverConfigureDialog function
ScreenSaverConfigureDialog (Win32)

BOOL ScreenSaverConfigureDialog(hwndDlg, uMsg, wParam, lParam)

HWND hwndDlg;	/* handle of dialog box	*/
UINT uMsg;	/* message	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

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.

Parameter	Description

hwndDlg	Identifies the configuration dialog box.

uMsg	Specifies the message.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

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.

Comments

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

RegisterDialogClasses


ScreenSaverProc function
ScreenSaverProc (Win32)

LONG ScreenSaverProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;	/* handle of screen saver window	*/
UINT uMsg;	/* message	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The ScreenSaverProc function receives messages sent to the given screen saver window.

Parameter	Description

hwnd	Identifies the window.

uMsg	Specifies the message.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

The return value is the result of the message processing and depends on the message sent.

Comments

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


Screen Saver Library

DefScreenSaverProc	Calls default screen saver window procedure

RegisterDialogClasses	Registers screen-saver dialog box classes

ScreenSaverConfigureDialog	Processes config. dialog box messages

ScreenSaverProc	Processes screen saver window messages


CopyLZFile function
CopyLZFile (Win32)

The CopyLZFile function is obsolete. It is provided only for backwards compatibility. Win32 applications should use the LZCopy function.

See Also

LZCopy


GetExpandedName function
GetExpandedName (Win32)

INT GetExpandedName(lpszSource, lpszBuffer)

LPTSTR lpszSource;	/* address of name of compressed file	*/
LPTSTR lpszBuffer;	/* address of buffer for original filename	*/

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.

Parameter	Description

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.

Returns

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.

Comments

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.


LZClose function
LZClose (Win32)

VOID LZClose(hFile)

INT hFile;	/* LZ file handle identifying file to be closed	*/

The LZClose function closes a file that was opened by using the LZOpenFile function.

Parameter	Description

hFile	Identifies the source file to be closed.

Returns

This function does not return a value.

Comments

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

LZOpenFile


LZCopy function
LZCopy (Win32)

LONG LZCopy(hfSource, hfDest)

INT hfSource;	/* LZ file handle identifying source file	*/
INT hfDest;	/* LZ file handle identifying destination file	*/

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.

Parameter	Description

hfSource	Identifies the source file.

hfDest	Identifies the destination file.

Returns

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.

Comments

The handles identifying the source and destination files must be retrieved by calling the LZInit or LZOpenFile function.

This function is designed for single-file copy operations. (For multiple-file copy operations, use the CopyLZFile function.)

If the function succeeds, the file identified by the hfDest parameter is always uncompressed.

See Also

CopyLZFile, LZInit, LZOpenFile


LZDone function
LZDone (Win32)

The LZDone function is obsolete. It is provided only for backwards compatibility. Win32 applications should not use it.


LZInit function
LZInit (Win32)

INT LZInit(hfSource)

INT hfSource;	/* handle of source file	*/

The LZInit function allocates memory for the internal data structures required to decompress files and then creates and initializes them.

Parameter	Description

hfSource	Identifies the source file.

Returns

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.

Comments

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 function
LZOpenFile (Win32)

INT LZOpenFile(lpFileName, lpReOpenBuf, wStyle)

LPTSTR lpFileName;	/* address of name of file to be opened	*/
LPOFSTRUCT lpReOpenBuf;	/* address of open file structure	*/
WORD wStyle;	/* action to take	*/

The LZOpenFile function creates, opens, reopens, or deletes the specified file.

Parameter	Description

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

Returns

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.

Comments

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, OFSTRUCT


LZRead function
LZRead (Win32)

INT LZRead(hFile, lpBuffer, cbRead)

INT hFile;	/* LZ file handle of file	*/
LPSTR lpBuffer;	/* address of buffer for bytes	*/
INT cbRead;	/* count of bytes	*/

The LZRead function reads (at most) the specified number of bytes from the given file and copies them into the given buffer.

Parameter	Description

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.

Returns

If the function succeeds, the return value specifies the actual 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.

Comments

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 function
LZSeek (Win32)

LONG LZSeek(hFile, lOffset, iOrigin)

INT hFile;	/* handle identifying file	*/
LONG lOffset;	/* number of bytes to move	*/
INT iOrigin;	/* original position	*/

The LZSeek function moves a file pointer from the specified origin by the given offset.

Parameter	Description

hFile	Identifies the source file.

lOffset	Specifies the number of bytes by which the file pointer should be moved.

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.

Returns

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.

Here is a list of the LZERROR_* codes that LZSeek can return upon failure :

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.

Comments

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 function
LZStart (Win32)

The LZStart function is obsolete. It is provided only for backwards compatibility. Win32 applications should not use it.


Data Decompression Library

CopyLZFile	Copies a file and expands it if compressed

GetExpandedName	Retrieves original filename for a compressed file

LZClose	Closes a file

LZCopy	Copies a file and expands it if compressed

LZDone	Frees buffers allocated by LZStart

LZInit	Initializes data structures needed for decompression

LZOpenFile	Opens a file (both compressed and uncompressed)

LZRead	Reads a specified number of bytes from a compressed file

LZSeek	Repositions pointer in file

LZStart	Allocates buffers for CopyLZFile function


Microsoft Win32 API Programmer's Reference

Functions and Overviews

    Application Notes

    Extension Libraries

    Graphics Device Interface (GDI)

    Multimedia

    RPC

    System Services

    Window Management

Messages and Notification Codes

    Buttons

    Combo Boxes

    DDE Transactions

    Edit Controls

    List Boxes

    Static Controls

    Window Management

Macros

Structures

Constants

Data Types

Error Codes

Locale Identifiers

Glossary

Copyright


Application Notes

Control Panel Applications

File Manager Extensions

Shell DDE Interface


Extension Libraries

Common Dialog Box Library

Dynamic Data Exchange Management Library (DDEML)

Data Decompression Library

File Installation Library

Object Linking and Embedding Libraries (OLE)

Shell Library

Screen Saver Library


Graphics Device Interface
Graphics Device Interface (GDI)

Bitmaps	Brushes

Clipping	Colors

Coordinate Spaces and Transformations	Device Contexts

Filled Shapes	Fonts and Text

Lines and Curves	Metafiles

Paths	Pens

printing and print spooler	Regions

Raster Operation Codes


Multimedia

Introduction to Multimedia Services

Media Control Interface

Introduction to Audio

High-Level Audio

Low-Level Audio

Multimedia Timers

Multimedia File I/O

Multimedia Manufacturer and Product Identifiers

MCI Command String Syntax Summary


System Services

Atoms	Communications

Consoles and Character-Mode Support	Debugging

Device I/O	Dynamic-Link Libraries

Errors	Event Logging

Files	File Mapping

File Systems	Handles and Objects

Mailslots	Memory Management

Network DDE	Networks

Performance Monitoring	Pipes

Processes and Threads	Registry and Initialization Files

Remote Access	Resources

Security	Services

String Manipulation and Unicode	Structured Exception Handling

Synchronization	System Information

Tape Backup	Time


Window Management

Buttons	Carets

Clipboard	Combo Boxes

Controls	Cursors

Dialog Boxes	Edit Controls

Dynamic Data Exchange	Hooks

Icons	Keyboard Accelerators

Keyboard Input	List Boxes

Menus	Messages and Message Queues

Mouse Input	Multiple Document Interface

Painting and Drawing	Rectangles

Scroll Bars	Static Controls

Timers	Window Classes

Window Procedures	Window Properties

Windows


Atoms

AddAtom	Adds a string to the local atom table

DeleteAtom	Deletes an atom

FindAtom	Retrieves string atom from local atom table

GetAtomName	Retrieves a local atom string

GlobalAddAtom	Adds a string to the system atom table

GlobalDeleteAtom	Deletes an atom from the system atom table

GlobalFindAtom	Retrieves string atom from global atom table

GlobalGetAtomName	Retrieves a global atom string

InitAtomTable	Initializes local atom hash table

GetAtomHandle	Obsolete


Bitmaps

BitBlt	Copies a bitmap between device contexts

CreateBitmap	Creates device-dependent memory bitmap

CreateBitmapIndirect	Creates bitmap using BITMAP structure

CreateCompatibleBitmap	Creates bitmap compatible with DC

CreateDIBitmap	Creates bitmap handle from DIB spec

CreateDiscardableBitmap	Creates discardable bitmap

ExtFloodFill	Fills area with current brush

FloodFill	Fills area with current brush

GetBitmapBits	Copies bitmap bits to a buffer

GetBitmapDimensionEx	Retrieves width and height of bitmap

GetDIBits	Copies DIB bits into a buffer

GetGraphicsMode	Retrieves the graphics mode for the specified DC

GetPixel	Retrieves RGB color of specified pixel

GetStretchBltMode	Retrieves the current bitmap-stretching mode

LoadBitmap	Loads a bitmap resource

MaskBlt	Transfers a bitmap through a mask

PatBlt	Creates a bitmap pattern

PlgBlt	Transfers a block of pixels

SetBitmapBits	Sets bitmap bits from array of bytes

SetBitmapDimensionEx	Sets width and height of bitmap

SetDIBits	Sets the bits of a bitmap

SetDIBitsToDevice	Sets DIB bits to device

SetGraphicsMode	Sets the graphics mode for the specified DC

SetPixel	Sets pixel to specified color

SetPixelV	Sets pixel to specified color

SetStretchBltMode	Sets the bitmap-stretching mode

StretchBlt	Copies a bitmap, transforming if required

StretchDIBits	Moves DIB from source to destination rectangle

GetBitmapDimension	Obsolete; use GetBitmapDimensionEx

SetBitmapDimension	Obsolete; use SetBitmapDimensionEx


Brushes

CreateBrushIndirect	Creates a brush with specified attributes

CreateDIBPatternBrush	Creates a pattern brush from a DIB

CreateDIBPatternBrushPt	Creates logical brush from bitmap

CreateHatchBrush	Creates a hatched brush

CreatePatternBrush	Creates a pattern brush from a bitmap

CreateSolidBrush	Creates a solid brush with a specified color

GetBrushOrgEx	Retrieves the origin of the current brush

GetStockObject	Retrieves handle of a stock pen, brush, or font

SetBrushOrgEx	Sets the origin of the current brush

FixBrushOrgEx	Not implemented

GetBrushOrg	Obsolete; use GetBrushOrgEx

SetBrushOrg	Obsolete; use SetBrushOrgEx


Buttons

CheckDlgButton	Changes a checkmark by a dialog button

CheckRadioButton	Places a checkmark by a radio button

IsDlgButtonChecked	Determines the state of a button control

BM_GETCHECK	Retrieves the button check state

BM_GETSTATE	Determines the state of a button or check box

BM_SETCHECK	Places or removes a button checkmark

BM_SETSTATE	Sets the highlighting state of a button

BM_SETSTYLE	Sets the style of a button

BN_CLICKED	Indicates the user clicked a button

BN_DISABLE	Indicates a button is disabled

BN_DOUBLECLICKED	Indicates the user double-clicked a button

BN_HILITE	Indicates the user highlighted a button

BN_PAINT	Indicates the button should be painted

BN_UNHILITE	Indicates the highlight should be removed

DM_GETDEFID	Gets the ID of the default push-button control

DM_SETDEFID	Sets the default push-button of a dialog box


Carets

CreateCaret	Creates a new shape for the system caret

DestroyCaret	Destroys the current caret

GetCaretBlinkTime	Returns the caret blink time

GetCaretPos	Returns the current caret position

HideCaret	Removes the caret from the screen

SetCaretBlinkTime	Sets caret blink time

SetCaretPos	Sets the caret position

ShowCaret	Shows (unhides) the caret


Consoles and Character-Mode Support

AllocConsole	Creates a console for the current process

CreateConsoleScreenBuffer	Returns a handle to a new screen buffer

FillConsoleOutputAttribute	Writes attributes to the screen buffer

FillConsoleOutputCharacter	Writes characters to the screen buffer

FlushConsoleInputBuffer	Clears the console input buffer

FreeConsole	Frees the current console

GenerateConsoleCtrlEvent	Sends a signal to a console process group

GetConsoleCP	Gets code page for console input

GetConsoleCursorInfo	Returns cursor size and visibility

GetConsoleMode	Returns console input or output mode

GetConsoleOutputCP	Gets code page for console output

GetConsoleScreenBufferInfo	Returns screen-buffer information

GetConsoleTitle	Returns console-window title

GetLargestConsoleWindowSize	Returns largest possible window size

GetNumberOfConsoleInputEvents	Retrieves number of console-queue events

GetNumberOfConsoleMouseButtons	Retrieves number of mouse buttons

GetStdHandle	Returns standard I/O handles

HandlerRoutine	Control handler function of a service

PeekConsoleInput	Previews console input data

ReadConsole	Reads console input data

ReadConsoleInput	Reads console input data

ReadConsoleOutput	Reads screen-buffer data

ReadConsoleOutputAttribute	Reads a console attribute string

ReadConsoleOutputCharacter	Reads a screen-buffer string

ScrollConsoleScreenBuffer	Scrolls data in the screen buffer

SetConsoleActiveScreenBuffer	Changes displayed screen buffer

SetConsoleCP	Sets code page for console input

SetConsoleCtrlHandler	Sets signal handler for console process

SetConsoleCursorInfo	Sets console cursor size and visibility

SetConsoleCursorPosition	Sets console cursor position

SetConsoleMode	Sets console input or output mode

SetConsoleOutputCP	Sets code page for console output

SetConsoleScreenBufferSize	Changes screen-buffer size

SetConsoleTextAttribute	Sets attributes for screen text

SetConsoleTitle	Sets console-window title string

SetConsoleWindowInfo	Sets console window size

SetFileApisToOEM	Set file APIs to OEM char set

SetStdHandle	Sets the standard device handles

WriteConsole	Writes to console screen buffer

WriteConsoleInput	Writes to console input buffer

WriteConsoleOutput	Writes directly to screen buffer

WriteConsoleOutputAttribute	Writes an attribute string to console

WriteConsoleOutputCharacter	Writes a character string to console


Clipboard

ChangeClipboardChain	Removes a window from clipboard-viewer chain

CloseClipboard	Closes the clipboard

CountClipboardFormats	Returns the number of clipboard formats

EmptyClipboard	Empties the clipboard and frees data handles

EnumClipboardFormats	Returns available clipboard formats

GetClipboardData	Returns a handle to clipboard data

GetClipboardFormatName	Returns registered clipboard format name

GetClipboardOwner	Returns clipboard owner window handle

GetClipboardViewer	Returns first clipboard viewer window handle

GetOpenClipboardWindow	Returns handle to window that opened clipboard

GetPriorityClipboardFormat	Returns first clipboard format

IsClipboardFormatAvailable	Determines if a format is available

OpenClipboard	Opens the clipboard

RegisterClipboardFormat	Registers a new clipboard format

SetClipboardData	Sets the data in the clipboard

SetClipboardViewer	Adds a window to the clipboard-viewer chain


Clipping

ExcludeClipRect	Changes clipping region, excluding rectangle

ExtSelectClipRgn	Selects a region as a clip region

GetClipBox	Retrieves rectangle for clipping region

GetClipRgn	Returns current clipping region

GetMetaRgn	Returns current meta region

IntersectClipRect	Creates clipping region from intersection

OffsetClipRgn	Moves a clipping region

PtVisible	Queries whether point is within clipping region

RectVisible	Queries whether rectangle is in clip region

SelectClipPath	Selects current path as clip region

SelectClipRgn	Selects clipping region for device context

SetMetaRgn	Selects the clip region as a meta region


Colors

AnimatePalette	Replaces entries in a logical palette

CreatePalette	Creates a logical color palette

CreateHalftonePalette	Create halftone palette for a device context

GetColorAdjustment	Get color adjustment for a device context

GetNearestColor	Retrieves closest available color

GetNearestPaletteIndex	Retrieves nearest match for a color

GetPaletteEntries	Retrieves range of palette entries

GetSystemPaletteEntries	Retrieves entries from system palette

GetSystemPaletteUse	Determines use of entire system palette

RealizePalette	Maps entries from logical to system palette

ResizePalette	Changes the size of a logical palette

SelectPalette	Selects a palette into a device context

SetColorAdjustment	Set color adjustment for a device context

SetPaletteEntries	Sets colors and flags for a color palette

SetSystemPaletteUse	Use of system palette static colors

UpdateColors	Updates colors in client area

UnrealizeObject	Obsolete


Combo Boxes

DlgDirListComboBox	Fills a directory list box

DlgDirSelectComboBoxEx	Retrieves selection from dir. list box

DlgDirSelect	Obsolete; use DlgDirSelectEx

DlgDirSelectComboBox	Obsolete; use DlgDirSelectComboBoxEx

CB_ADDSTRING	Adds a string to the list box of a combo box

CB_DELETESTRING	Deletes list-box string in a combo box

CB_DIR	Adds file names to the list box of a combo box

CB_FINDSTRING	Finds a string in the list box of a combo box

CB_FINDSTRINGEXACT	Finds prefix string in the list box of a combo box

CB_GETCOUNT	Gets the number of list-box items in a combo box

CB_GETCURSEL	Gets index of selected list-box item in combo box

CB_GETDROPPEDCONTROLRECT	Gets rectangle of combo-box drop-down list box

CB_GETDROPPEDSTATE	Determines if a combo box's list box is visible

CB_GETEDITSEL	Gets position of selection in edit control

CB_GETEXTENDEDUI	Determines if combo box has the extended interface

CB_GETITEMDATA	Retrieves an application supplied value

CB_GETITEMHEIGHT	Retrieves the height of items in a combo box

CB_GETLBTEXT	Gets a string from the list box of a combo box

CB_GETLBTEXTLEN	Gets length of a list-box string in a combo box

CB_GETLOCALE	Get current combo box locale

CB_INSERTSTRING	Inserts a string into the list box of a combo box

CB_LIMITTEXT	Limits amount of edit-control text in a combo box

CB_RESETCONTENT	Removes all items from the list box of a combo box

CB_SELECTSTRING	Selects a string in the list box of a combo box

CB_SETCURSEL	Selects a string in the list box of a combo box

CB_SETEDITSEL	Sets the edit-control selection of a combo box

CB_SETEXTENDEDUI	Sets the default or extended user interface

CB_SETITEMDATA	Sets an application-defined value

CB_SETITEMHEIGHT	Sets the height of items in a combo box

CB_SETLOCALE	Set current combo box locale

CB_SHOWDROPDOWN	Shows or hides the list box of a combo box

CBN_CLOSEUP	Indicates the list box of a combo box has closed

CBN_DBLCLK	Indicates the user double-clicked a string

CBN_DROPDOWN	Indicates the list box of a combo box is dropping down

CBN_EDITCHANGE	Indicates the user has changed text in the edit control

CBN_EDITUPDATE	Indicates altered text is about to be displayed

CBN_ERRSPACE	Indicates the combo box is out of memory

CBN_KILLFOCUS	Indicates the combo box is losing the input focus

CBN_SELCHANGE	Indicates a new combo box list item is selected

CBN_SELENDCANCEL	Indicates the user's selection should be cancelled

CBN_SELENDOK	Indicates the user's selection is valid

CBN_SETFOCUS	Indicates the combo box is receiving the input focus


Common Dialog Box Library

ChooseColor	Creates a color-selection dialog box

ChooseFont	Creates a font-selection dialog box

CommDlgExtendedError	Retrieves Error Data

FindText	Creates a find-text dialog box

GetFileTitle	Retrieves a filename

GetOpenFileName	Creates an open-filename dialog box

GetSaveFileName	Creates a save-filename dialog box

PrintDlg	Creates a print-text dialog box

ReplaceText	Creates a replace-text dialog box


Communications

BuildCommDCB	Translates device definition string to a DCB

BuildCommDCBAndTimeouts	Builds up comm DCB and sets timeout values

ClearCommBreak	Restores character transmission

ClearCommError	Enables communications after an error

EscapeCommFunction	Sends an extended comm function

GetCommMask	Returns comm event mask

GetCommModemStatus	Returns modem control register values

GetCommProperties	Returns comm device properties

GetCommState	Returns comm device control block

GetCommTimeouts	Returns comm device timeout characteristics

PurgeComm	Clears comm queues

SetCommBreak	Suspends character transmission

SetCommMask	Sets comm event mask

SetCommState	Sets comm device to the specified state

SetCommTimeouts	Set comm read and write timeout values

SetupComm	Sets communication parameters

TransmitCommChar	Places a character in the transmit queue

WaitCommEvent	Waits for masked comm events


Coordinate Spaces and Transformations

ClientToScreen	Converts client point to screen coordinates

CombineTransform	Combines two transforms

DPtoLP	Converts device coordinates to logical

GetCurrentPositionEx	Retrieves position in logical units

GetMapMode	Retrieves mapping mode

GetViewportExtEx	Retrieves viewport extent

GetViewportOrgEx	Retrieves viewport origin

GetWindowExtEx	Retrieves window extents

GetWindowOrgEx	Retrieves window origin

GetWorldTransform	Returns current world transform

LPtoDP	Converts logical points to device points

MapWindowPoints	Converts points to another coordinate system

ModifyWorldTransform	Changes the current world transform

OffsetViewportOrgEx	Moves viewport origin

OffsetWindowOrgEx	Moves window origin

ScaleViewportExtEx	Scales viewport extents

ScaleWindowExtEx	Scales window extents

ScreenToClient	Converts screen point to client coordinates

SetMapMode	Sets mapping mode

SetViewportExtEx	Sets viewport extents

SetViewportOrgEx	Sets viewport origin

SetWindowExtEx	Sets window extents

SetWindowOrgEx	Sets the window origin

SetWorldTransform	Sets the current world transform

GetCurrentPosition	Obsolete; use GetCurrentPositionEx

GetViewportExt	Obsolete; use GetViewportExtEx

GetViewportOrg	Obsolete; use GetViewportOrgEx

GetWindowExt	Obsolete; use GetWindowExtEx

GetWindowOrg	Obsolete; use GetWindowOrgEx

OffsetViewportOrg	Obsolete; use OffsetViewportOrgEx

OffsetWindowOrg	Obsolete; use OffsetWindowOrgEx

ScaleViewportExt	Obsolete; use ScaleViewportExtEx

ScaleWindowExt	Obsolete; use ScaleWindowExtEx

SetViewportExt	Obsolete; use SetViewportExtEx

SetViewportOrg	Obsolete; use SetViewportOrgEx

SetWindowExt	Obsolete; use SetWindowExtEx

SetWindowOrg	Obsolete; use SetWindowOrgEx


Debugging

ContinueDebugEvent	Causes a debugged thread to continue

DebugActiveProcess	Attaches a process for debugging

DebugBreak	Causes a breakpoint exception in the caller

FatalAppExit	Terminates an application

FatalExit	Returns control to the debugger

FlushInstructionCache	Flushes the instruction cache

GetThreadContext	Returns specified thread context

GetThreadSelectorEntry	Returns a thread descriptor entry

OutputDebugString	Sends a string to the debugger

ReadProcessMemory	Reads from memory within a process

SetDebugErrorLevel	Set error level for debug events

SetThreadContext	Sets a specified thread context

WaitForDebugEvent	Waits for a debug event

WriteProcessMemory	Writes memory within a specified process


Device Contexts

CancelDC	Cancels any pending operation on specified DC

CreateCompatibleDC	Creates a DC compatible with specified DC

CreateDC	Creates a device context

CreateIC	Creates an information context

DeleteDC	Deletes a device context

DeleteObject	Deletes an object from memory

EnumObjects	Enumerates pens and brushes in a device context

EnumObjectsProc	Processes objects data

GetCurrentObject	Returns the currently selected object

GetDC	Returns window device-context handle

GetDCEx	Retrieves the handle of a display context

GetDCOrgEx	Retrieves translation origin for device context

GetDeviceCaps	Retrieves device capabilities

GetObject	Retrieves information about an object

GetObjectType	Returns object type

ReleaseDC	Frees a device context

ResetDC	Updates a device context

RestoreDC	Restores device context

SaveDC	Saves current state of device context

SelectObject	Selects object into a device context

GetDCOrg	Obsolete; use GetDCOrgEx


Device I/O

DeviceIoControl	Calls a device driver directly

IOCTL_DISK_CHECK_VERIFY	Checks for change in removable-media device

IOCTL_DISK_EJECT_MEDIA	Ejects media from a SCSI device

IOCTL_DISK_FORMAT_TRACKS	Formats a contiguous set of disk tracks

IOCTL_DISK_GET_DRIVE_GEOMETRY	Obtain info on the physical disk's geometry

IOCTL_DISK_GET_DRIVE_LAYOUT	Provides info on each partition on a disk

IOCTL_DISK_GET_MEDIA_TYPES	Obtains information about media support

IOCTL_DISK_GET_PARTITION_INFO	Obtain disk partition information

IOCTL_DISK_LOAD_MEDIA	Loads media into a device

IOCTL_DISK_MEDIA_REMOVAL	Enables or disables media eject mechanism

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	Set disk partition type

IOCTL_DISK_VERIFY	Performs logical format of a disk extent

IOCTL_SERIAL_LSRMST_INSERT	Places modem and line status data into stream


Remote Access

RasDial	Establishes a RAS connection

RasDialFunc	Callback function called by RasDial on state changes

RasEnumConnections	Lists active RAS connections

RasEnumEntries	Lists entries in a RAS phone book

RasGetConnectStatus	Reports current status of a RAS connection

RasGetErrorString	Converts RAS error code to error string

RasHangUp	Terminates a RAS connection


Network DDE

NDdeGetErrorString	Converts net DDE error code to error string

NDdeGetShareSecurity	Obtain a net DDE share's security attributes

NDdeGetTrustedShare	Obtains a trusted share's trust options

NDdeIsValidAppTopicList	Validates net DDE app and topic string syntax

NDdeIsValidShareName	Validates net DDE share name syntax

NDdeSetTrustedShare	Applies trust options to a net DDE share

NDdeShareAdd	Adds a net DDE share

NDdeShareDel	Deletes a net DDE share

NDdeShareEnum	Lists net DDE shares

NDdeShareGetInfo	Obtains information about a net DDE share

NDdeShareSetInfo	Modifies an existing net DDE share's info

NDdeTrustedShareEnum	Lists trusted shares in calling process' context


Dialog Boxes

CreateDialog	Creates a modeless dialog box

CreateDialogIndirect	Creates modeless dialog box from memory template

CreateDialogIndirectParam	Creates modeless dialog box from memory template

CreateDialogParam	Creates a modeless dialog box

DefDlgProc	Provides default window message processing

DialogBox	Creates a modal dialog box

DialogBoxIndirect	Creates modal dialog box from template in memory

DialogBoxIndirectParam	Creates modal dialog box from template in memory

DialogBoxParam	Creates a modal dialog box

DialogProc	Processes input to a modeless dialog box

EndDialog	Hides a modal dialog box

GetDialogBaseUnits	Returns dialog base units

GetDlgCtrlID	Returns child window ID

GetDlgItem	Returns handle of a dialog control

GetDlgItemInt	Translates dialog text into an integer

GetDlgItemText	Retrieves dialog control text

GetNextDlgGroupItem	Returns handle of previous or next group control

GetNextDlgTabItem	Returns the next or previous WS_TABSTOP control

IsDialogMessage	Determines if a message is for a dialog box

MapDialogRect	Maps dialog-box units to pixels

MessageBox	Creates a message-box window

MessageBoxEx	Creates a message-box window

SendDlgItemMessage	Sends a message to a dialog-box control

SetDlgItemInt	Converts an integer to a dialog text string

SetDlgItemText	Sets dialog title or item text


Dynamic Data Exchange

DdeImpersonateClient	Impersonates a DDE client window

DdeSetQualityOfService	Specify DDE quality of service

FreeDDElParam	Frees a DDE message lParam

ImpersonateDdeClientWindow	Impersonates a DDE client window

PackDDElParam	Packs data into a DDE message lParam

ReuseDDElParam	Reuse a DDE message lParam

UnpackDDElParam	Unpacks data from a DDE message lParam

See Also

Dynamic Data Exchange Management Library


Dynamic-Link Libraries

DllEntryPoint	Called for DLL initialization and cleanup

FreeLibrary	Unloads a library module instance

GetModuleFileName	Returns path for specified module

GetModuleHandle	Returns handle for specified module

GetProcAddress	Returns the address of a function

LoadLibrary	Maps an executable module into process' address space

LoadLibraryEx	Returns a handle to a library module

FreeModule	Obsolete

FreeProcInstance	Obsolete

GetCodeHandle	Obsolete

GetInstanceData	Obsolete

GetModuleUsage	Obsolete

MakeProcInstance	Obsolete


Errors

Beep	Generates a tone

ExitWindows	Shuts down Windows

ExitWindowsEx	Shuts down Windows

FlashWindow	Flashes a window once

GetLastError	Returns extended error code

MessageBeep	Generates a sound

PlaySound	Play a waveform sound

SetErrorMode	Control hard-error handling

SetLastError	Sets extended error code

SetLastErrorEx	Sets extended error code and type

CloseSound	Obsolete

CountVoiceNotes	Obsolete

GetThresholdEvent	Obsolete

GetThresholdStatus	Obsolete

OpenSound	Obsolete

SetSoundNoise	Obsolete

SetVoiceAccent	Obsolete

SetVoiceEnvelope	Obsolete

SetVoiceNote	Obsolete

SetVoiceQueueSize	Obsolete

SetVoiceSound	Obsolete

SetVoiceThreshold	Obsolete

StartSound	Obsolete

StopSound	Obsolete

SyncAllVoices	Obsolete

WaitSoundState	Obsolete


Event Logging

BackupEventLog	Saves an event log in a backup file

ClearEventLog	Clears the event log

CloseEventLog	Closes an event-log handle

DeregisterEventSource	Closes a registered event handle

GetNumberOfEventLogRecords	Gets number of records in event log

GetOldestEventLogRecord	Retrieves number of oldest record

OpenBackupEventLog	Opens a handle to a backup event log

OpenEventLog	Opens an event-log handle

ReadEventLog	Reads entries from an event log

RegisterEventSource	Returns a registered event-log handle

ReportEvent	Writes an event-log entry


Files

CloseHandle	Closes an open object handle

CopyFile	Copies a file

CreateDirectory	Creates a new directory

CreateDirectoryEx	Creates new directory with attributes of template directory

CreateFile	Creates, opens or truncates a file

DefineDosDevice	Defines, redefines, or deletes DOS device names

DeleteFile	Deletes an existing file

FileIOCompletionRoutine	Called when asynchronous I/O completes

FindClose	Close a find-file context

FindCloseChangeNotification	Close file or directory change wait

FindFirstChangeNotification	Setup file or directory change wait

FindFirstFile	Finds the first matching file

FindNextChangeNotification	Next file or directory change wait

FindNextFile	Finds the next matching file

FlushFileBuffers	Clears the file buffers

GetCurrentDirectory	Returns process current directory

GetDiskFreeSpace	Returns amount of free disk space

GetDriveType	Returns type for specified drive

GetFileAttributes	Returns file attributes

GetFileInformationByHandle	Retrieves file information

GetFileSize	Returns size for specified file

GetFileType	Returns type for specified file

GetFullPathName	Retrieves a path name for a file name

GetLogicalDrives	Returns a bitmask specifying valid drives

GetLogicalDriveStrings	Returns strings for valid drives

GetTempFileName	Creates a temporary file name

GetTempPath	Returns path for temporary files

GetVolumeInformation	Returns file-system information

LockFile	Locks a byte range in an open file

LockFileEx	Locks a byte range in an open file

MoveFile	Renames a file

MoveFileEx	Renames a file

OpenFile	Creates, opens or deletes a file

QueryDosDevice	Obtains information about DOS device names

ReadFile	Reads from a file

ReadFileEx	Reads from a file asynchronously

RemoveDirectory	Removes an existing directory

SearchPath	Searches for a file

SetCurrentDirectory	Changes the current directory

SetEndOfFile	Sets end-of-file pointer

SetFileAttributes	Sets file attributes

SetFilePointer	Sets file-pointer position

SetHandleCount	Sets the number of available file handles

SetVolumeLabel	Sets a volume label

UnlockFile	Unlocks a byte range in a file

UnlockFileEx	Unlocks a byte range in a file

WriteFile	Writes data to file or device

WriteFileEx	Writes data to file or device

_hread	Reads from a file

_hwrite	Writes to a file

_lclose	Closes an open file

_lcreat	Creates or opens a file

_llseek	Repositions the file pointer

_lopen	Opens a file

_lread	Reads from a file

_lwrite	Writes to a file

GetTempDrive	Obsolete


Filled Shapes

Chord	Draws a chord

Ellipse	Draws an ellipse

FillRect	Fills a rectangle with the specified brush

FrameRect	Draws a window border with a specified brush

InvertRect	Inverts a rectangular region

Pie	Draws a pie-shaped wedge

Polygon	Draws a polygon

PolyPolygon	Draws a series of polygons

Rectangle	Draws a rectangle

RoundRect	Draws a rectangle with rounded corners


Fonts and Text

AddFontResource	Adds a font to the font table

CreateFont	Creates a logical font

CreateFontIndirect	Creates a font using LOGFONT structure

CreateScalableFontResource	Creates resource file with font info

DrawText	Draws formatted text in a rectangle

EnumFontFamilies	Retrieves fonts in a specified family

EnumFontFamProc	Retrieves fonts in a specified family

EnumFonts	Enumerates fonts on specified device

EnumFontsProc	Processes font data

ExtTextOut	Writes a character string in rectangular region

GetAspectRatioFilterEx	Retrieves current aspect-ratio filter

GetCharABCWidths	Retrieves widths of consecutive characters

GetCharABCWidthsFloat	Retrieves widths of consecutive characters

GetCharWidth	Retrieves character widths

GetCharWidth32	Retrieves character widths

GetCharWidthFloat	Returns fractional character widths

GetFontData	Retrieves font metric data

GetGlyphOutline	Retrieves data for individual outline character

GetKerningPairs	Returns current font kerning pairs

GetOutlineTextMetrics	Retrieves metrics for TrueType fonts

GetRasterizerCaps	Retrieves status of TrueType on system

GetTabbedTextExtent	Determines dimensions of tabbed string

GetTextAlign	Retrieves text-alignment flags

GetTextCharacterExtra	Retrieves intercharacter spacing

GetTextColor	Retrieves current text color

GetTextExtentExPoint	Retrieves an array of sub-string lengths

GetTextExtentPoint	Retrieves dimensions of string

GetTextExtentPoint32	Retrieves dimensions of string

GetTextFace	Retrieves typeface name of the current font

GetTextMetrics	Retrieves the metrics for the current font

MulDiv	Multiplies two values and divides the result

PolyTextOut	Draws several strings

RemoveFontResource	Removes font resource

SetMapperFlags	Sets font-mapper flag

SetTextAlign	Sets text-alignment flags

SetTextCharacterExtra	Sets intercharacter spacing

SetTextColor	Sets the foreground color of text

SetTextJustification	Sets justification for text output

TabbedTextOut	Writes a tabbed character string

TextOut	Writes a character string at specified location

GetAspectRatioFilter	Obsolete; use GetAspectRatioFilterEx

GetTextExtent	Obsolete; use GetTextExtentPoint


Hooks

CallMsgFilter	Passes a message to a message-filter procedure

CallNextHookEx	Calls the next hook procedure in a chain

CallWndProc	Filters messages sent by the SendMessage function

CBTProc	Allows a CBT application to prevent an operation

DebugProc	Examines data before it is sent to a hook

GetMsgProc	Filters messages retrieved by GetMessage

JournalPlaybackProc	Places recorded events into the system queue

JournalRecordProc	Records event messages

KeyboardProc	Filters keystroke messages

MessageProc	Filters dialog box, menu, or scroll bar messages

MouseProc	Filters mouse messages

SetWindowsHook	Installs a hook procedure

SetWindowsHookEx	Installs a hook procedure

ShellProc	Receives notifications from the system

SysMsgProc	Filters dialog, message box, or menu messages

UnhookWindowsHook	Removes a filter function

UnhookWindowsHookEx	Removes a function from the hook chain

DefHookProc	Obsolete


Icons

ArrangeIconicWindows	Arranges minimized child windows

CopyIcon	Copies an icon

CreateIcon	Creates an icon with specified attributes

CreateIconFromResource	Creates an icon or cursor

CreateIconIndirect	Creates an icon or cursor

DestroyIcon	Destroys an icon created by CreateIcon

DrawIcon	Draws an icon in the specified device context

GetIconInfo	Returns icon or cursor information

IsIconic	Determines if a window is minimized

LoadIcon	Loads an icon resource

LookupIconIdFromDirectory	Returns an icon or cursor ID

OpenIcon	Activates a minimized window


Keyboard Accelerators

CopyAcceleratorTable	Copies an accelerator table

CreateAcceleratorTable	Creates an accelerator table

DestroyAcceleratorTable	Destroys an accelerator table

LoadAccelerators	Loads an accelerator table

TranslateAccelerator	Processes accelerator keys for menu commands


Keyboard Input

ActivateKeyboardLayout	Activates a new keyboard layout

EnableWindow	Sets the window-enable state

GetActiveWindow	Retrieves the handle of the active window

GetAsyncKeyState	Determines key state

GetFocus	Returns current focus window handle

GetKBCodePage	Get OEM system code page

GetKeyboardLayoutName	Retrieves name of active keyboard layout

GetKeyboardState	Returns virtual-keyboard keys status

GetKeyNameText	Retrieves string representing the name of a key

GetKeyState	Retrieves the status of a virtual key

IsWindowEnabled	Determines if a window accepts user input

keybd_event	Synthesizes a keystroke

LoadKeyboardLayout	Loads a keyboard layout into memory

MapVirtualKey	Translates a virual-key code or scan code

OemKeyScan	Maps OEM ASCII to scan codes

RegisterHotKey	Registers hot key with a thread

SetActiveWindow	Activates a top-level window

SetFocus	Sets the keyboard focus to a window

SetKeyboardState	Sets the keyboard state table

ToAscii	Translates virtual-key code to Windows character

ToUnicode	Translates virtual-key code to ANSI character

UnloadKeyboardLayout	Removes a keyboard layout from memory

UnregisterHotKey	Releases a hot key from a thread

VkKeyScan	Translates character to virtual-key code


Lines and Curves

AngleArc	Draws an arc with specified angle

Arc	Draws an arc

ArcTo	Draws an elliptical arc

GetArcDirection	Returns arc and rectangle drawing direction

LineDDA	Computes successive points in a line

LineDDAProc	Processes line data

LineTo	Draws a line from the current position

MoveToEx	Moves the current position

PolyBezier	Draws Bezier curves

PolyBezierTo	Draws Bezier curves

PolyDraw	Draws a set of lines and Bezier splines

Polyline	Draws line segments to connect specified points

PolylineTo	Draws one or more straight lines

PolyPolyline	Draws connected line segments

SetArcDirection	Sets arc and rectangle drawing direction

MoveTo	Obsolete; use MoveToEx


List Boxes

DlgDirList	Fills a directory list box

DlgDirSelectEx	Retrieves a selection from a directory list box

LB_ADDFILE	Adds a file to a list box

LB_ADDSTRING	Adds a string to a list box

LB_DELETESTRING	Deletes a string in a list box

LB_DIR	Adds file names to a list box

LB_FINDSTRING	Finds a string in a list box

LB_FINDSTRINGEXACT	Finds a string that matches a prefix

LB_GETANCHORINDEX	Gets item that was last selected by the mouse

LB_GETCARETINDEX	Gets index of list-box item with focus rectangle

LB_GETCOUNT	Gets the number of items in a list box

LB_GETCURSEL	Gets index of selected item in a list box

LB_GETHORIZONTALEXTENT	Gets the horizontal extent of a list box

LB_GETITEMDATA	Retrieves value associated with a list-box item

LB_GETITEMHEIGHT	Retrieves the height of items in a list box

LB_GETITEMRECT	Retrieves the bounding rectangle for an item

LB_GETLOCALE	Get current list box locale

LB_GETSEL	Retrieves the selection state of an item

LB_GETSELCOUNT	Retrieves a count of selected list-box items

LB_GETSELITEMS	Lists item numbers of selected list-box items

LB_GETTEXT	Retrieves a string from a list box

LB_GETTEXTLEN	Gets the length of a string in a list box

LB_GETTOPINDEX	Retrieves index of first visible list-box item

LB_INSERTSTRING	Inserts a string into a list box

LB_RESETCONTENT	Removes all items from a list box

LB_SELECTSTRING	Selects a string in a list box

LB_SELITEMRANGE	Selects consecutive items in a list box

LB_SELITEMRANGEEX	Selects consecutive items in a list box

LB_SETANCHORINDEX	Sets item that was last selected by the mouse

LB_SETCARETINDEX	Sets the focus rectangle in a list box

LB_SETCOLUMNWIDTH	Sets the width of columns in a list box

LB_SETCOUNT	Sets the count of items in a no-data list box

LB_SETCURSEL	Selects a string in a list box

LB_SETHORIZONTALEXTENT	Sets the horizontal extent of a list box

LB_SETITEMDATA	Associates a value with a list-box item

LB_SETITEMHEIGHT	Sets the height of items in a list box

LB_SETLOCALE	Set current list box locale

LB_SETSEL	Selects a string in a multi-selection list box

LB_SETTABSTOPS	Sets tab stops in a list box

LB_SETTOPINDEX	Ensures that a list-box item is visible

LBN_DBLCLK	Indicates that the user double-clicked a string

LBN_ERRSPACE	Indicates the list box is out of memory

LBN_KILLFOCUS	Indicates the list box is losing the input focus

LBN_SELCANCEL	Indicates the selection is cancelled

LBN_SELCHANGE	Indicates the selection is about to change

LBN_SETFOCUS	Indicates the list box is receiving the input focus


Mailslots

CreateMailslot	Creates a mailslot

GetMailslotInfo	Retrieves mailslot information

SetMailslotInfo	Sets mailslot read timeout


File Mapping

CreateFileMapping	Returns handle to a new file mapping object

FlushViewOfFile	Flushes a byte range within a mapped view

MapViewOfFile	Maps a view into an address space

MapViewOfFileEx	Maps a view into an address space

OpenFileMapping	Opens a named-file mapping object

UnmapViewOfFile	Unmaps a file view


Memory Management

CopyMemory	Copies a block of memory

FillMemory	Fills a block of memory with a spec'd value

GetProcessHeap	Obtains handle to the calling process' heap

GlobalAlloc	Allocates memory from the heap

GlobalDiscard	Discards a global memory block

GlobalFlags	Returns global memory block info

GlobalFree	Frees a global memory block

GlobalHandle	Translates a global pointer to a handle

GlobalLock	Locks global memory object and returns a pointer

GlobalMemoryStatus	Checks memory availability

GlobalReAlloc	Changes global memory block size/attributes

GlobalSize	Returns the size of a global memory block

GlobalUnlock	Unlocks a global memory block

HeapAlloc	Allocates memory from a heap

HeapCreate	Creates a heap

HeapDestroy	Destroys a heap

HeapFree	Frees memory allocated from a heap

HeapReAlloc	Reallocates memory from a heap

HeapSize	Returns the size of a heap object

IsBadCodePtr	Determines whether a read pointer is valid

IsBadHugeReadPtr	Determines whether a read pointer is valid

IsBadHugeWritePtr	Determines if a process has write access

IsBadReadPtr	Determines whether a process has read access

IsBadStringPtr	Determines whether a string pointer is valid

IsBadWritePtr	Determines whether a write pointer is valid

LocalAlloc	Allocates memory from the heap

LocalDiscard	Discards a local memory block

LocalFlags	Returns local memory block information

LocalFree	Frees a local memory block

LocalHandle	Returns local handle for pointer

LocalLock	Locks local memory object and returns pointer

LocalReAlloc	Changes local memory size or attributes

LocalSize	Returns the size of a local memory block

LocalUnlock	Unlocks a local memory block

MoveMemory	Moves a block of memory

VirtualAlloc	Reserves a range of virtual pages

VirtualFree	Frees a range of virtual pages

VirtualLock	Locks a range of virtual pages

VirtualProtect	Changes virtual-memory protection

VirtualProtectEx	Change virtual-memory protection

VirtualQuery	Returns virtual-memory information

VirtualQueryEx	Retrieve virtual-memory protection

VirtualUnlock	Unlocks a range of virtual pages

ZeroMemory	Zeroes a block of memory

AllocDStoCSAlias	Obsolete

AllocSelector	Obsolete

ChangeSelector	Obsolete

DefineHandleTable	Obsolete

FreeSelector	Obsolete

GetCodeInfo	Obsolete

GetFreeSpace	Obsolete

GlobalCompact	Obsolete

GlobalDosAlloc	Obsolete

GlobalDosFree	Obsolete

GlobalFix	Obsolete

GlobalLRUNewest	Obsolete

GlobalLRUOldest	Obsolete

GlobalNotify	Obsolete

GlobalPageLock	Obsolete

GlobalPageUnlock	Obsolete

GlobalUnfix	Obsolete

GlobalUnwire	Obsolete

GlobalWire	Obsolete

LimitEMSPages	Obsolete

LocalCompact	Obsolete

LocalInit	Obsolete

LocalShrink	Obsolete

LockSegment	Obsolete

SetSwapAreaSize	Obsolete

SwitchStackBack	Obsolete

SwitchStackTo	Obsolete

UnlockSegment	Obsolete


Menus

AppendMenu	Appends a new item to a menu

CheckMenuItem	Changes a menu-item's check mark attribute

CreateMenu	Creates a menu

CreatePopupMenu	Creates a pop-up menu

DeleteMenu	Deletes an item from a menu

DestroyMenu	Destroys a menu and frees memory

DrawMenuBar	Redraws the menu bar

EnableMenuItem	Enabls, disables, or grays a menu item

GetMenu	Returns menu handle for the specified window

GetMenuCheckMarkDimensions	Returns default check mark bitmap dimensions

GetMenuItemCount	Returns the number of items in a menu

GetMenuItemID	Returns a menu-item identifier

GetMenuState	Returns menu flags for the specified menu item

GetMenuString	Copies a menu-item string into a buffer

GetSubMenu	Returns pop-up menu handle

GetSystemMenu	Provides access to the System menu

HiliteMenuItem	Changes highlight of top-level menu item

InsertMenu	Inserts a new item in a menu

IsMenu	Determines whether handle is a menu handle

LoadMenu	Loads a menu resource

LoadMenuIndirect	Obtains a menu handle for a menu template

ModifyMenu	Changes an existing menu item

RemoveMenu	Deletes a menu item and pop-up menu

SetMenu	Sets the menu for a window

SetMenuItemBitmaps	Associates check mark bitmaps with a menu item

TrackPopupMenu	Displays and tracks a pop-up menu

ChangeMenu	Obsolete


Messages and Message Queues

CallWndProc	Filters messages sent by the SendMessage function

DefWindowProc	Calls the default window procedure

DispatchMessage	Dispatches a message to a window

GetInputState	Determines mouse, keyboard and timer queuing status

GetMessage	Retrieves a message from a thread message queue

GetMessageExtraInfo	Retrieves information about a hardware message

GetMessagePos	Returns cursor position for last message

GetMessageTime	Returns the time for the last message

GetMsgProc	Filters messages retrieved by GetMessage

GetQueueStatus	Determines content of message queue

InSendMessage	Determines if a window is processing SendMessage

IsDialogMessage	Determines if a message is for a dialog box

PeekMessage	Checks message queue

PostMessage	Places a message in a thread's message queue

PostQuitMessage	Tells Windows that a thread is terminating

PostThreadMessage	Posts a message to a thread

RegisterWindowMessage	Defines a new unique window message

ReplyMessage	Replies to a message sent through SendMessage

SendAsyncProc	Receives the result of message processing

SendDlgItemMessage	Sends a message to a dialog-box control

SendMessage	Sends a message to a window procedure

SendMessageCallback	Sends a message to a window procedure

SendMessageTimeout	Sends a message to a window procedure

SendNotifyMessage	Sends a message to a window procedure

SetMessageQueue	Create a message queue

TranslateAccelerator	Processes accelerator keys for menu commands

TranslateMessage	Translates virtual-key messages

WaitMessage	Suspends an application and yields control

PostAppMessage	Obsolete


Metafiles

Enhanced Metafile Functions

CloseEnhMetaFile	Closes an enhanced metafile DC

CopyEnhMetaFile	Copies an enhanced metafile

CreateEnhMetaFile	Creates an enhanced metafile DC

DeleteEnhMetaFile	Invalidates enhanced metafile handle

EnhMetaFileProc	Processes enhanced metafile data

EnumEnhMetaFile	Returns GDI calls within an enhanced metafile

GdiComment	Adds a comment to an enhanced metafile

GetEnhMetaFile	Creates an enhanced metafile

GetEnhMetaFileBits	Copies enhanced metafile bits to a buffer

GetEnhMetaFileDescription	Returns creator and title for enhanced metafile

GetEnhMetaFileHeader	Returns enhanced metafile header

GetEnhMetaFilePaletteEntries	Returns enhanced metafile palette entries

GetWinMetaFileBits	Retrieves metafile contents in Windows format

PlayEnhMetaFile	Plays an enhanced metafile to a DC

PlayEnhMetaFileRecord	Plays an enhanced metafile record

SetEnhMetaFileBits	Creates a memory-based enhanced metafile from data

SetWinMetaFileBits	Creates enhanced metafile from Windows metafile data

Windows Metafile Functions

CloseMetaFile	Closes a Windows metafile DC

CopyMetaFile	Copies a Windows metafile

CreateMetaFile	Creates a Windows metafile DC

DeleteMetaFile	Invalidates Windows metafile handle

EnumMetaFile	Returns GDI calls within a Windows metafile

EnumMetaFileProc	Processes metafile data

GetMetaFile	Creates a Windows metafile

GetMetaFileBitsEx	Copies Windows metafile bits to a buffer

PlayMetaFile	Plays a Windows metafile to a DC

PlayMetaFileRecord	Plays a Windows metafile record

SetMetaFileBitsEx	Creates a memory-based Windows metafile from data

GetMetaFileBits	Obsolete; use GetMetaFileBitsEx

SetMetaFileBits	Obsolete; use SetMetaFileBitsEx


Cursors

ClipCursor	Confines cursor to a specified rectangle

CopyCursor	Copies a cursor

CreateCursor	Creates a cursor with specified dimensions

DestroyCursor	Destroys a cursor created by CreateCursor

GetClipCursor	Returns coordinates of cursor-confining rectangle

GetCursor	Retrieves the handle to the current cursor

GetCursorPos	Returns current cursor position

LoadCursor	Loads a cursor resource

SetCursor	Changes the mouse cursor

SetCursorPos	Sets mouse-cursor position in screen coordinates

ShowCursor	Shows or hides the mouse cursor


Mouse Input

GetCapture	Returns the handle of the mouse-capture window

GetDoubleClickTime	Returns mouse double click time

mouse_event	Records mouse motion and button clicks

ReleaseCapture	Releases the mouse capture

SetCapture	Sets the mouse capture to a window

SetDoubleClickTime	Sets the mouse double-click time

SwapMouseButton	Reverses the meaning of the mouse buttons


Multiple Document Interface

CreateMDIWindow	Creates a new MDI window

DefFrameProc	Default MDI frame window message processing

DefMDIChildProc	Default MDI child window message processing

TranslateMDISysAccel	Processes MDI keyboard accelerators


Networks

AcsLan	Communicates with network devices using DLC protocol

Netbios	Executes specified NCB

WNetAddConnection	Redirects a local device to a network resource

WNetAddConnection2	Redirects a local device to a network resource

WNetCancelConnection	Breaks an existing network connection

WNetCancelConnection2	Breaks an existing network connection

WNetCloseEnum	Ends a network resource list

WNetConnectionDialog	Starts a network connection dialog box

WNetDisconnectDialog	Starts a network disconnection dialog box

WNetEnumResource	Continue listing network resources

WNetGetConnection	Gets name of network resource

WNetGetLastError	Returns last error for network functions

WNetGetUser	Gets the current network user name

WNetOpenEnum	Starts listing network resources


Painting and Drawing

BeginPaint	Prepares a window for painting

DrawFocusRect	Draws a rectangle in the focus style

EndPaint	Marks end of painting in the specified window

ExcludeUpdateRgn	Excludes updated region from clipping region

FrameRect	Draws a window border with a specified brush

GdiFlush	Flushes the current GDI batch

GdiGetBatchLimit	Returns number of buffered GDI functions

GdiSetBatchLimit	Sets number of buffered GDI functions

GetBkColor	Retrieves the current background color

GetBkMode	Retrieves the background mode

GetBoundsRect	Returns current accumulated bounding rectangle

GetROP2	Retrieves the current drawing mode

GetUpdateRect	Returns window update region dimensions

GetUpdateRgn	Returns window update region

GetWindowDC	Returns window device context

GrayString	Draws gray text at the specified location

InvalidateRect	Adds a rectangle to the update region

InvalidateRgn	Adds a region to the update region

LockWindowUpdate	Disables or reenables drawing in a window

OutputProc	Outputs text for the GrayString function

RedrawWindow	Updates a client rectangle or region

SetBkColor	Sets the current background color

SetBkMode	Sets the background mode

SetBoundsRect	Controls bounding-rectangle accumulation

SetRectRgn	Changes a region into specified rectangle

SetROP2	Sets the current drawing mode

UpdateWindow	Updates a window's client area

ValidateRect	Removes a rectangle from the update region

ValidateRgn	Removes a region from the update region

WindowFromDC	Returns a window for a device context


Paths

AbortPath	Aborts and discards any paths in a DC

BeginPath	Starts a path bracket

CloseFigure	Closes a figure in a path

EndPath	Ends a path bracket

ExtCreatePen	Creates a logical pen

FillPath	Fills the current path

FlattenPath	Transforms curves to lines

GetMiterLimit	Returns current miter-join length

GetPath	Returns all lines and curves in path

PathToRegion	Creates a region from a path

SetMiterLimit	Sets miter-join length

StrokeAndFillPath	Closes, strokes and fills a path

StrokePath	Renders a path with the current pen

WidenPath	Sets the current path to pen width


Pens

CreatePen	Creates a logical pen

CreatePenIndirect	Creates a pen using a LOGPEN structure

ExtCreatePen	Creates a logical pen


Pipes

CallNamedPipe	Multiple pipe operations

ConnectNamedPipe	Waits for a client to connect

CreateNamedPipe	Creates an instance of a named pipe

CreatePipe	Creates an anonymous pipe

DisconnectNamedPipe	Disconnects server end of a named pipe

GetNamedPipeHandleState	Returns named-pipe handle information

GetNamedPipeInfo	Returns named-pipe handle information

PeekNamedPipe	Previews pipe-queue data

SetNamedPipeHandleState	Sets pipe read and blocking mode and controls local buffering

TransactNamedPipe	Reads and writes a named pipe

WaitNamedPipe	Waits for a named pipe


Printing and Print Spooler

AbortDoc	Terminates a print job

AbortPrinter	Delete printer spool file

AbortProc	Processes a canceled print job

AddForm	Add a printer form

AddJob	Start a printer job

AddMonitor	Add a printer monitor

AddPort	Add a printer port

AddPrinter	Creates a printer on a printer server

AddPrinterConnection	Adds connection to printer for current user

AddPrinterDriver	Copies a printer driver to a print server

AddPrintProcessor	Copies a print processor to a server

AddPrintProvidor	Add a printer providor

AdvancedDocumentProperties	Configure printer advanced settings

ClosePrinter	Close an open printer

ConfigurePort	Configure printer port

ConnectToPrinterDlg	Displays dialog for browsing and connecting to network printers

DeleteForm	Remove printer form

DeleteMonitor	Remove a printer monitor

DeletePort	Deletes a printer port

DeletePrinter	Deletes a printer on a printer server

DeletePrinterConnection	Deletes a connection to a printer

DeletePrinterDriver	Remove printer driver

DeletePrintProcessor	Remove printer processor

DeletePrintProvidor	Remove printer providor

DeviceCapabilities	Returns device-driver capabilities

DeviceCapabilitiesEx	Not implemented; use DeviceCapabilities

DocumentProperties	Configure printer settings

EndDoc	Ends a print job

EndDocPrinter	End a print job

EndPage	Ends a page

EndPagePrinter	End a printer page

EnumForms	Enumerate supported printer forms

EnumJobs	Get printer job information

EnumMonitors	Enumerate available monitors

EnumPorts	Enumerate available printer ports

EnumPrinterDrivers	Enumerate installed printer drivers

EnumPrinters	Enumerate available printers

EnumPrintProcessors	Enumerate installed print processors

Escape	Allows access to device

ExtEscape	Allows access to private device

GetForm	Get printer form information

GetJob	Get print-job information

GetPrinter	Get printer information

GetPrinterData	Gets printer configuration information

GetPrinterDriver	Get printer driver information

GetPrinterDriverDirectory	Get path for printer driver

GetPrintProcessorDirectory	Get path for print processor

OpenPrinter	Get handle for specified printer

PrinterMessageBox	Displays printing job error message

PrinterProperties	Modify printer properties

ReadPrinter	Read printer data

ResetPrinter	Set printer data type and device mode values

ScheduleJob	Schedule added job

SetAbortProc	Sets the abort function for a print job

SetForm	Set form information

SetJob	Set print job information

SetPrinter	Set printer information

SetPrinterData	Set printer configuration information

StartDoc	Starts a print job

StartDocPrinter	Start print job

StartPage	Prepares printer driver to receive data

StartPagePrinter	Start a printer page

WaitForPrinterChange	Wait for change(s) on a printer or print server

WritePrinter	Write data to printer


Processes and Threads

AttachThreadInput	Attach one thread to another

CreateProcess	Creates a new process and thread object

CreateRemoteThread	Creates a thread in another process

CreateThread	Creates a new thread

DuplicateHandle	Duplicates an object handle

ExitProcess	Exits the current process

ExitThread	Exits the current thread

GetCommandLine	Returns a pointer to the command line

GetCurrentProcess	Returns a handle to the current process

GetCurrentProcessId	Returns the current process ID

GetCurrentThread	Returns a handle to the current thread

GetCurrentThreadId	Returns the current thread ID

GetEnvironmentStrings	Returns a pointer to the environment block

GetEnvironmentVariable	Returns process environment variable

GetExitCodeProcess	Retrieves process termination code

GetExitCodeThread	Returns thread termination code

GetPriorityClass	Returns priority class for a process

GetProcessShutdownParameters	Retrieves process shutdown parameters

GetProcessTimes	Obtains timing information for a process

GetStartupInfo	Gets startup information for current process

GetThreadPriority	Returns specified thread priority

GetThreadTimes	Obtains timing information for a thread

LoadModule	Loads and executes a program

OpenProcess	Returns a handle to a process object

ResumeThread	Restarts a suspended thread

SetEnvironmentVariable	Sets an environment variable

SetPriorityClass	Sets priority class for a process

SetProcessShutdownParameters	Sets process shutdown parameters

SetThreadPriority	Sets thread priority

Sleep	Suspends a thread for a set time

SleepEx	Suspends a thread until I/O completes

SuspendThread	Suspends a thread

TerminateProcess	Kills a process and its threads

TerminateThread	Kills a thread

TlsAlloc	Allocates thread local storage index

TlsFree	Frees thread local storage index

TlsGetValue	Returns a TLS value

TlsSetValue	Sets a TLS value

WaitForInputIdle	Waits until a process is idle

WinExec	Runs a program

Yield	Obsolete


Window Properties

EnumProps	Returns window property list

EnumPropsEx	Returns window property list

GetProp	Returns data handle from a window property list

PropEnumProc	Receives enumerated property for a window

PropEnumProcEx	Receives enumerated property for a window

RemoveProp	Removes a property-list entry

SetProp	Adds or changes a property-list entry


Regions

CombineRgn	Creates a region by combining two regions

CreateEllipticRgn	Creates an elliptical region

CreateEllipticRgnIndirect	Creates an elliptical region

CreatePolygonRgn	Creates a polygonal region

CreatePolyPolygonRgn	Creates a region consisting of polygons

CreateRectRgn	Creates a rectangular region

CreateRectRgnIndirect	Creates a region using a RECT structure

CreateRoundRectRgn	Creates rectangular region with round corners

EqualRgn	Compares two regions for equality

ExtCreateRegion	Creates a region from region data

FillRgn	Fills a region with a brush

FrameRgn	Draws a border around a region

GetPolyFillMode	Retrieves the current polygon-filling mode

GetRegionData	Retrieves region data

GetRgnBox	Retrieves bounding rectangle for region

InvertRgn	Inverts the colors in a region

OffsetRgn	Moves a region by a specified offset

PaintRgn	Fills region with brush in device context

PtInRegion	Queries whether a point is in a region

RectInRegion	Queries whether rectangle overlaps region

SetPolyFillMode	Sets the polygon-filling mode


Registry and Initialization Files

GetPrivateProfileInt	Gets an integer from private file

GetPrivateProfileSection	Returns private key and value pairs

GetPrivateProfileString	Gets a string from private file

GetProfileInt	Gets an integer from WIN.INI

GetProfileSection	Returns keys and values from WIN.INI

GetProfileString	Gets a string from WIN.INI

RegCloseKey	Closes a registration key

RegConnectRegistry	Connects to a remote registry

RegCreateKey	Creates or opens a key

RegCreateKeyEx	Creates or opens a key

RegDeleteKey	Deletes a key

RegDeleteValue	Removes a value from a registration key

RegEnumKey	Enumerates subkeys of specified key

RegEnumKeyEx	Enumerates subkeys of specified key

RegEnumValue	Enumerates values for specified key

RegFlushKey	Writes an open key to the registry

RegGetKeySecurity	Get registration key security

RegLoadKey	Writes a saved key and subkeys to the registry

RegNotifyChangeKeyValue	Indicates changes in registry key

RegOpenKey	Opens a key

RegOpenKeyEx	Opens a key

RegQueryInfoKey	Retrieves registry key information

RegQueryValue	Retrieves name for specified key

RegQueryValueEx	Retrieves key type and value

RegReplaceKey	Replaces an existing hive in the registry

RegRestoreKey	Writes a saved tree to the registry

RegSaveKey	Saves a registry tree to a file

RegSetKeySecurity	Sets registration key security

RegSetValue	Associates a text string with a specified key

RegSetValueEx	Associates a text string with a specified key

RegUnLoadKey	Unloads a key and subkeys from the registry

WritePrivateProfileSection	Writes a section to private INI file

WritePrivateProfileString	Writes a string to private INI file

WriteProfileSection	Writes a section to WIN.INI

WriteProfileString	Writes a string to WIN.INI


Resources

BeginUpdateResource	Start resource update in executable file

EndUpdateResource	End resource update in executable file

EnumResLangProc	Enumerate language resources

EnumResNameProc	List resource names

EnumResourceLanguages	List language resources

EnumResourceNames	List resource names

EnumResourceTypes	List resource types

EnumResTypeProc	List resource types

FindResource	Locates a resource in a module

FindResourceEx	Locates a resource in a module

LoadResource	Returns a handle to a resource

LockResource	Returns the address of a resource

SizeofResource	Returns resource size

UpdateResource	Modifies a resource in an executable file

AccessResource	Obsolete

AllocResource	Obsolete

FreeResource	Obsolete

SetResourceHandler	Obsolete

UnlockResource	Obsolete


Scroll Bars

EnableScrollBar	Enables or disables scroll-bar arrows

GetScrollPos	Returns the scroll-bar position

GetScrollRange	Returns minimcmum and maximum scroll-bar positions

ScrollDC	Scrolls a rectangle horizontally and vertically

ScrollWindow	Scrolls a window's client area

ScrollWindowEx	Scrolls a window's client area

SetScrollPos	Sets scroll-box position

SetScrollRange	Sets minimum and maximum scroll-bar positions

ShowScrollBar	Shows or hides a scroll bar

SBM_ENABLE_ARROWS	Enables or disables scroll-bar arrows

SBM_GETPOS	Retrieves the position of a scroll box

SBM_GETRANGE	Retrieves scroll range of scroll bar control

SBM_SETPOS	Sets the position of a scroll box

SBM_SETRANGE	Sets the scroll range of a scroll bar control

SBM_SETRANGEREDRAW	Sets scroll range and redraws scroll bar control


String Manipulation and Unicode

CharLower	Converts a character or string to lower case

CharLowerBuff	Converts a character string to lower case

CharNext	Moves to the next character in a string

CharPrev	Moves to the previous character in a string

CharToOem	Translates a string to OEM characters

CharToOemBuff	Translates a string to OEM characters

CharUpper	Converts a character or string to upper case

CharUpperBuff	Converts a string to upper case

CompareStringW	Compare two wide character strings

FoldStringW	Translate one wide character string to another

FormatMessage	Formats a message string

GetACP	Get ANSI system codepage

GetCPInfo	Get code page information

GetDateFormatW	Get locale-formatted date string

GetLocaleInfoW	Get locale information from registry

GetOEMCP	Get OEM system codepage

GetStringTypeW	Get Unicode string type

GetSystemDefaultLangID	Get system default language ID

GetSystemDefaultLCID	Get system default locale ID

GetThreadLocale	Get locale information for a thread

GetTimeFormatW	Get locale-formatted time string

GetUserDefaultLangID	Get user default language ID

GetUserDefaultLCID	Get user default locale ID

IsCharAlpha	Determines if a character is alphabetical

IsCharAlphaNumeric	Determines is a character is alphanumeric

IsCharLower	Determines if a character is lower case

IsCharUpper	Determines if a character is upper case

IsDBCSLeadByte	Is character a DBCS lead byte

IsValidCodePage	Determines if a code page is valid

LCMapStringW	Map character string by locale

LoadString	Loads a string resource

lstrcat	Appends one string to another

lstrcmp	Compares two character strings

lstrcmpi	Compares two character strings

lstrcpy	Copies a string to a buffer

lstrlen	Returns the number of characters in a string

MultiByteToWideChar	Map multibyte string to wide-character string

OemToChar	Translates an OEM string

OemToCharBuff	Translates an OEM string

SetThreadLocale	Set locale information for a thread

WideCharToMultiByte	Map wide-character string to multibyte

wsprintf	Formats a string

wvsprintf	Formats a string

AnsiLower	Obsolete

AnsiLowerBuff	Obsolete

AnsiNext	Obsolete

AnsiPrev	Obsolete

AnsiToOem	Obsolete

AnsiToOemBuff	Obsolete

AnsiUpper	Obsolete

AnsiUpperBuff	Obsolete

OemToAnsi	Obsolete

OemToAnsiBuff	Obsolete


Structured Exception Handling

AbnormalTermination	Returns try-finally status

GetExceptionCode	Returns exception type

GetExceptionInformation	Returns exception details

RaiseException	Raises an exception

SetUnhandledExceptionFilter	Sets superseding filter exception functions

UnhandledExceptionFilter	Filter exceptions to application

Catch	Obsolete

Throw	Obsolete


Synchronization

CreateEvent	Returns a handle to a new event object

CreateMutex	Returns a handle to a new mutex object

CreateSemaphore	Returns a handle to a new semaphore

DeleteCriticalSection	Deletes an unowned critical section

EnterCriticalSection	Enters a critical section

GetOverlappedResult	Returns last overlapped result

InitializeCriticalSection	Initialize crit sec object

InterlockedDecrement	Decrements a LONG

InterlockedExchange	Atomically exchanges 32-bit values

InterlockedIncrement	Increments a LONG

LeaveCriticalSection	Leaves a previously entered crit sec

MsgWaitForMultipleObjects	Waits for mulitple object handles

OpenEvent	Opens an event object

OpenMutex	Opens a named mutex object

OpenSemaphore	Opens a named semaphore object

PulseEvent	Sets and resets an event

ReleaseMutex	Releases a mutex object

ReleaseSemaphore	Releases a semaphore object

ResetEvent	Resets an event object

SetEvent	Sets an event object

WaitForMultipleObjects	Waits for multiple waitable objects

WaitForMultipleObjectsEx	Waits for multiple objects or I/O completion

WaitForSingleObject	Waits for single waitable object

WaitForSingleObjectEx	Waits for single object or I/O completion


System Information

AbortSystemShutdown	Stops the system

ExpandEnvironmentStrings	Expands environment variable strings

GetComputerName	Retrieves current computer name

GetKeyboardType	Retrieves keyboard information

GetSysColor	Returns display-element color

GetSystemDirectory	Returns path for Windows system dir

GetSystemInfo	Returns current system info

GetSystemMetrics	Retrieves the system metrics

GetThreadDesktop	Returns thread desktop handle

GetUserName	Returns the user's name

GetVersion	Returns Windows and operating-system version

GetWindowsDirectory	Returns path for Windows dir

InitiateSystemShutdown	Stops the system

SetComputerName	Sets the current computer name

SetSysColors	Sets one or more system colors

SystemParametersInfo	Queries or sets system-wide parameters

WinHelp	Invokes Windows Help

DOS3Call	Obsolete

GetCurrentPDB	Obsolete

GetCurrentTask	Obsolete; use GetCurrentThread or GetCurrentProcess

GetDOSEnvironment	Obsolete

GetSystemDir	Obsolete; use GetSystemDirectory

GetWindowsDir	Obsolete; use GetWindowsDirectory

GetWinFlags	Obsolete; use GetSystemInfo

IsTask	Obsolete


Tape Backup

BackupRead	Tape backup read

BackupSeek	Tape backup seek

BackupWrite	Tape backup write

CreateTapePartition	Create new tape partition

EraseTape	Erase specified portion of tape

GetTapeParameters	Retrieve tape drive or media information

GetTapePosition	Returns the current tape position

GetTapeStatus	Retrieves tape-device status

PrepareTape	Prepare the tape device

SetTapeParameters	Set tape drive or media information

SetTapePosition	Sets the tape position

WriteTapemark	Writes tape marks


Time

CompareFileTime	Compares two 64-bit file times

DosDateTimeToFileTime	Converts MS-DOS date/time to 64 bits

FileTimeToDosDateTime	Converts file time to MS-DOS date/time

FileTimeToSystemTime	Converts 64-bit time to system time

GetCurrentTime	Returns elapsed time since Windows started

GetFileTime	Returns 64-bit file times

GetLocalTime	Returns local time and date

GetSystemTime	Returns system time and date

GetTickCount	Returns amount of time Windows has been running

GetTimeZoneInformation	Retrieves current time-zone settings

FileTimeToLocalFileTime	Converts UTC file time to local file time

LocalFileTimeToFileTime	Converts local file time to UTC file time

SetFileTime	Sets a file's 64-bit time

SetLocalTime	Sets the local time and date

SetSystemTime	Sets the system time and date

SetTimeZoneInformation	Sets current time-zone settings

SystemTimeToFileTime	Converts system time to 64-bit

Also see Multimedia Timer Services


Timers

KillTimer	Removes a timer

SetTimer	Installs a system timer

TimerProc	Processes WM_TIMER message


Window Classes

GetClassInfo	Returns window class information

GetClassLong	Returns window-class data

GetClassName	Returns window class name

GetClassWord	Returns window class memory word

GetWindowLong	Returns long value from extra window memory

GetWindowWord	Returns word value from extra window memory

RegisterClass	Registers a window class

SetClassLong	Sets a long value in extra class memory

SetClassWord	Sets a word value in extra class memory

SetWindowLong	Sets a long value in extra window memory

SetWindowWord	Sets a word value in extra window memory

UnregisterClass	Removes a window class


Windows

AdjustWindowRect	Computes required size of window rectangle

AdjustWindowRectEx	Computes required size of window rectangle

AnyPopup	Indicates if a popup window exists

ArrangeIconicWindows	Arranges minimized child windows

BeginDeferWindowPos	Creates a window-position structure

BringWindowToTop	Uncovers an overlapped window

ChildWindowFromPoint	Determines the window containing a point

CloseWindow	Minimizes a window

CreateWindow	Creates a window

CreateWindowEx	Creates a window

DeferWindowPos	Updates a multiple window position structure

DestroyWindow	Destroys a window

EndDeferWindowPos	Updates position and size of multiple windows

EnumChildProc	Processes child window handles during enumeration

EnumChildWindows	Passes child-window handles to callback function

EnumThreadWindows	Returns thread windows

EnumThreadWndProc	Processes thread window handles during enumeration

EnumWindows	Returns parent windows

EnumWindowsProc	Processes parent window handles during enumeration

FindWindow	Returns window handle for class and window name

GetClientRect	Returns window client area coordinates

GetDesktopWindow	Returns desktop window handle

GetForegroundWindow	Returns handle for foreground window

GetLastActivePopup	Determines most recently active pop-up window

GetNextWindow	Returns next or previous window-manager window

GetParent	Returns parent window handle

GetTopWindow	Returns handle for top child of given window

GetWindow	Returns specified window handle

GetWindowPlacement	Returns window show state and min/max position

GetWindowRect	Returns window coordinates

GetWindowText	Copies window title-bar text to a buffer

GetWindowTextLength	Returns length of window title-bar text

GetWindowThreadProcessId	Returns window thread and process IDs

IsChild	Determines if a window is a child

IsIconic	Determines if a window is minimized

IsWindow	Determines if a window handle is valid

IsWindowUnicode	Determines if a window uses Unicode

IsWindowVisible	Determines if a window exists on the screen

IsZoomed	Determines if a window is maximized

MoveWindow	Changes the position and dimensions of a window

OpenIcon	Activates a minimized window

SetForegroundWindow	Puts a window in the foreground

SetParent	Changes a child's parent window

SetWindowPlacement	Sets window show state and min/max position

SetWindowPos	Sets a windows size, position, and order

SetWindowText	Sets text in a caption title or control window

ShowOwnedPopups	Shows or hides pop-up windows

ShowWindow	Sets window visibility state

WindowFromPoint	Returns window containing a point

WinMain	Initializes an application and processes message loop

EnumTaskWindows	Obsolete

GetSysModalWindow	Obsolete

GetWindowTask	Obsolete

SetSysModalWindow	Obsolete


Performance Monitoring

QueryPerformanceCounter	Obtains performance counter value

QueryPerformanceFrequency	Returns performance counter frequency

ProfClear	Obsolete

ProfFinish	Obsolete

ProfFlush	Obsolete

ProfInsChk	Obsolete

ProfSampRate	Obsolete

ProfSetup	Obsolete

ProfStart	Obsolete

ProfStop	Obsolete


Window Procedures

CallWindowProc	Passes a message to a window function

DefWindowProc	Calls the default window procedure

WindowProc	Processes input to a window


Edit Controls

EditWordBreakProc Determines line breaks in an edit control

EM_CANUNDO	Determines if edit-control operation can be undone

EM_EMPTYUNDOBUFFER	Resets (clears) the edit-control undo flag

EM_FMTLINES	Sets soft line break characters on or off

EM_GETFIRSTVISIBLELINE	Gets index of top line in an edit control

EM_GETHANDLE	Gets the handle of the memory for an MLE

EM_GETLINE	Retrieves a line from an MLE

EM_GETLINECOUNT	Retrieves number of lines in an MLE

EM_GETMODIFY	Checks whether edit-control contents have changed

EM_GETPASSWORDCHAR	Retrieves edit-control password character

EM_GETRECT	Gets the coordinates of an edit-control rectangle

EM_GETSEL	Gets position of current edit-contol selection

EM_GETWORDBREAKPROC	Retrieves the edit-control wordwrap function

EM_LIMITTEXT	Limits amount of text in an edit control

EM_LINEFROMCHAR	Retrieves a line number from a character index

EM_LINEINDEX	Retrieves the character index of an MLE line

EM_LINELENGTH	Retrieves the length of a line in an MLE

EM_LINESCROLL	Scrolls text in an MLE

EM_REPLACESEL	Replaces current selection in an edit control

EM_SCROLL	Vertically scrolls an MLE

EM_SCROLLCARET	Scrolls the caret into view

EM_SETHANDLE	Sets the memory handle for an MLE

EM_SETMODIFY	Sets or clears edit-control modification flag

EM_SETPASSWORDCHAR	Sets or removes edit-control password character

EM_SETREADONLY	Sets the read-only style of an edit control

EM_SETRECT	Sets the formatting rectangle of an MLE

EM_SETRECTNP	Sets the formatting rectangle of an MLE

EM_SETSEL	Selects text within an edit control

EM_SETTABSTOPS	Sets the tab stops in an MLE

EM_SETWORDBREAKPROC	Provides custom word breaks in an edit control

EM_UNDO	Undoes the last operation in an edit control

EN_CHANGE	Indicates the display is updated after text changes

EN_ERRSPACE	Indicates the edit control is out of memory

EN_HSCROLL	Indicates the user clicked the scroll bar

EN_KILLFOCUS	Indicates the edit control is losing the input focus

EN_MAXTEXT	Indicates the insertion is truncated

EN_SETFOCUS	Indicates the edit-control is receiving the input focus

EN_UPDATE	Indicates edit-control is about to display altered text

EN_VSCROLL	Indicates the user clicked the vertical scroll bar

EM_SETWORDBREAK	Obsolete


Static Controls

STM_GETICON	Gets icon handle associated with an icon control

STM_SETICON	Associates an icon handle with an icon control


Rectangles

CopyRect	Copies the dimensions of a rectangle

EqualRect	Determines whether two rectangles are equal

InflateRect	Changes rectangle dimensions

IntersectRect	Calculates the intersection of two rectangles

IsRectEmpty	Determines whether rectangle is empty

OffsetRect	Moves a rectangle by an offset

PtInRect	Determines if a point is in a rectangle

SetRect	Sets a rectangle's dimensions

SetRectEmpty	Creates an empty rectangle

SubtractRect	Subtracts one rectangle from another

UnionRect	Creates the union of two rectangles


High-Level Audio

mciGetCreatorTask	Retrieves creator task

mciGetDeviceID	Returns device ID for device name

mciGetErrorString	Retrieve text description for MCI error code

mciGetYieldProc	Get yield procedure address

mciSendCommand	Send a command message to MCI device

mciSendString	Send a command string to MCI device

mciSetYieldProc	Set yield procedure address

PlaySound	Play a waveform sound

sndPlaySound	Play a waveform sound

MCI_HMS_HOUR	Returns hours from HMS time

MCI_HMS_MINUTE	Returns minutes from HMS time

MCI_HMS_SECOND	Returns seconds from HMS time

MCI_MAKE_HMS	Returns HMS time from hours, minutes and seconds

MCI_MAKE_MSF	Returns MSF time from minutes, seconds, and frames

MCI_MAKE_TMSF	Returns TMSF time from individual values

MCI_MSF_FRAME	Returns frames from MSF time

MCI_MSF_MINUTE	Returns minutes from MSF time

MCI_MSF_SECOND	Returns seconds from MSF time

MCI_TMSF_FRAME	Returns frames from TMSF time

MCI_TMSF_MINUTE	Returns minutes from TMSF time

MCI_TMSF_SECOND	Returns seconds from TMSF time

MCI_TMSF_TRACK	Returns tracks from TMSF time


Low-Level Audio

auxGetDevCaps	Retrieve auxiliary device capabilities

auxGetNumDevs	Return number of auxiliary devices

auxGetVolume	Retrieve current volume setting

auxOutMessage	Send message to output device

auxSetVolume	Set auxiliary device volume

midiInAddBuffer	Send input buffer to MIDI device

midiInClose	Close MIDI input device

midiInGetDevCaps	Determine MIDI device capabilities

midiInGetErrorText	Retrieve text description for MIDI error code

midiInGetID	Retrieve device ID for MIDI device handle

midiInGetNumDevs	Return number of MIDI devices

midiInMessage	Send message to MIDI device driver

midiInOpen	Open MIDI device

midiInPrepareHeader	Prepare MIDI output buffer

midiInReset	Stop MIDI input and mark input buffers as done

midiInStart	Start MIDI input device

midiInStop	Stop MIDI input

midiInUnprepareHeader	Cleans up prepared header

midiOutCacheDrumPatches	Preload MIDI percussion patches

midiOutCachePatches	Preload MIDI patches

midiOutClose	Close MIDI output device

midiOutGetDevCaps	Retrieve MIDI output device capabilities

midiOutGetErrorText	Retrieve text for MIDI output error

midiOutGetID	Retrieve MIDI output device ID for handle

midiOutGetNumDevs	Get number of MIDI output devices

midiOutGetVolume	Retrieve MIDI output device volume

midiOutLongMsg	Send system-exclusive MIDI message

midiOutMessage	Send message to MIDI device driver

midiOutOpen	Open MIDI output device

midiOutPrepareHeader	Prepare MIDI output data block

midiOutReset	Stop MIDI output and mark buffers as done

midiOutSetVolume	Set MIDI output device volume

midiOutShortMsg	Send short message to MIDI output device

midiOutUnprepareHeader	Clean up prepared MIDI output header

MidiProc	Processes MIDI device messages

waveInAddBuffer	Send buffer to waveform input device

waveInClose	Close waveform input device

waveInGetDevCaps	Get waveform input device capabilities

waveInGetErrorText	Get text description for waveform error

waveInGetID	Get waveform input device ID for handle

waveInGetNumDevs	Return number of waveform input devices

waveInGetPosition	Get current waveform device input position

waveInMessage	Send messageto waveform input device

waveInOpen	Open waveform input device for recording

waveInPrepareHeader	Prepare buffer for waveform input

waveInReset	Stops waveform input device

waveInStart	Start waveform input device

waveInStop	Stop waveform input

waveInUnprepareHeader	Clean up prepared waveform header

waveOutBreakLoop	Break waveform output loop

waveOutClose	Close waveform output device

waveOutGetDevCaps	Get waveform output device capabilities

waveOutGetErrorText	Get text description for waveform error

waveOutGetID	Get waveform output device ID for handle

waveOutGetNumDevs	Get number of waveform output devices

waveOutGetPitch	Get current waveform output pitch

waveOutGetPlaybackRate	Get current waveform playback rate

waveOutGetPosition	Get current waveform playback position

waveOutGetVolume	Get current waveform volume

waveOutMessage	Send message to waveform output drivers

waveOutOpen	Open waveform output device

waveOutPause	Pause waveform playback

waveOutPrepareHeader	Prepare waveform playback data block

waveOutReset	Stop waveform playback

waveOutRestart	Restart paused waveform playback

waveOutSetPitch	Set waveform output pitch

waveOutSetPlaybackRate	Set waveform playback rate

waveOutSetVolume	Set waveform output volume

waveOutUnprepareHeader	Clean up prepared waveform data block

waveOutWrite	Write to waveform output device

WaveProc	Waveform device callback function


Multimedia Timers and Joystick Support

joyGetDevCaps	Determine joystick device capabilities

joyGetNumDevs	Return number of joystick devices

joyGetPos	Retrieve joystick position and button activity

joyGetThreshold	Retrieve joystick movement threshold

joyReleaseCapture	Release joystick capture

joySetCapture	Capture joystick messages to specified window

joySetThreshold	Set joystick movement threshold

timeBeginPeriod	Set minimum timer resolution

timeEndPeriod	Clear minimum timer resolution

timeGetDevCaps	Retrieve timer device capabilities

timeGetSystemTime	Retrieve elapsed time since Windows started

timeGetTime	Return elapsed time since Windows started

timeKillEvent	Destroy specified timer callback event

TimeProc	Timer event callback function

timeSetEvent	Set up timed callback event


Multimedia File I/O

mmioAdvance	Advance direct I/O buffer

mmioAscend	Ascend out of RIFF chunk

mmioClose	Close MM file

mmioCreateChunk	Create RIFF file chunk

mmioDescend	Descend into RIFF chunk

mmioFlush	Flush MM I/O buffer to disk

mmioFOURCC	Converts four characters to FOURCC

mmioGetInfo	Retrieve MM file info

mmioInstallIOProc	Install or remove custom I/O procedure

mmioOpen	Open a multimedia file

MMIOProc	MMIO callback procedure

mmioRead	Read from a file

mmioRename	Rename a multimedia file

mmioSeek	Change current file position

mmioSendMessage	Send message to I/O procedure

mmioSetBuffer	Control I/O buffering

mmioSetInfo	Set file information

mmioStringToFOURCC	Convert string to four-character code

mmioWrite	Write to a file

mmsystemGetVersion	Return current MM software version


Dynamic Data Exchange Management Library

DdeAbandonTransaction	Abandons an asynchronous transaction

DdeAccessData	Accesses a DDE data object

DdeAddData	Adds data to a DDE data object

DdeCallback	Processes DDEML transactions

DdeClientTransaction	Begins a DDE data transaction

DdeCmpStringHandles	Compares two DDE string handles

DdeConnect	Establishes a conversation with a server

DdeConnectList	Establishes multiple DDE conversations

DdeCreateDataHandle	Creates a DDE data handle

DdeCreateStringHandle	Creates a DDE string handle

DdeDisconnect	Terminates a DDE conversation

DdeDisconnectList	Destroys a DDE conversation list

DdeEnableCallback	Enables or disables one or more DDE conversations

DdeFreeDataHandle	Frees a DDE data object

DdeFreeStringHandle	Frees a DDE string handle

DdeGetData	Copies data from a DDE data object to a buffer

DdeGetLastError	Returns an error code set by a DDEML function

DdeInitialize	Registers an application with the DDEML

DdeKeepStringHandle	Increments the usage count for a string handle

DdeNameService	Registers or unregisters a service name

DdePostAdvise	Prompts a server to send advise data to a client

DdeQueryConvInfo	Retrieves information about a DDE conversation

DdeQueryNextServer	Obtains the next handle in a conversation list

DdeQueryString	Copies string-handle text to a buffer

DdeReconnect	Reestablishes a DDE conversation

DdeSetUserHandle	Associates a user-defined handle with a transaction

DdeUnaccessData	Frees a DDE data object

DdeUninitialize	Frees an application's DDEML resources


Control Panel Applications

CPlApplet	Processes messages for a Control Panel DLL

CPL_DBLCLK	Indicates a Control Panel applet was selected

CPL_EXIT	Indicates an applet DLL is being freed

CPL_GETCOUNT	Requests number of applications serviced

CPL_INIT	Initiates Control Panel DLL initialization

CPL_INQUIRE	Requests information about an application

CPL_NEWINQUIRE	Requests information about an application

CPL_SELECT	Indicates the user selected an application

CPL_STOP	Indicates Control Panel is exiting

WM_CPL_LAUNCHED	Indicates a Control Panel application has ended

WM_CPL_LAUNCH	Starts a Control Panel application


File Manager Extensions

FMExtensionProc	Processes messages for a File Manager extension

UndeleteFile	Processes the File Manager Undelete command

FMEVENT_HELPMENUITEM	Indicates user wants help for a button item

FMEVENT_HELPSTRING	Indicates File Manager wants help string for a button item

FMEVENT_INITMENU	Initializes File Manager menu extension

FMEVENT_LOAD	Indicates File Manager is loading extension

FMEVENT_SELCHANGE	Indicates user selected a filename

FMEVENT_TOOLBARLOAD	Indicates File Manager is loading its toolbar

FMEVENT_UNLOAD	Indicates an extension DLL is being unloaded

FMEVENT_USER_REFRESH	Indicates user invoked Refresh command

FM_GETDRIVEINFO	Retrieves drive data from active window

FM_GETFOCUS	Retrieves the type of the File Manager focus window

FM_GETFILESEL	Retrieves data about a selected file

FM_GETFILESELLFN	Retrieves data about a selected file

FM_GETSELCOUNTLFN	Retrieves the count of selected files

FM_GETSELCOUNT	Retrieves the count of selected files

FM_REFRESH_WINDOWS	Repaints File Manager's windows

FM_RELOAD_EXTENSIONS	Reloads File Manager extension DLLs


Window Management Messages

WM_ACTIVATE	Indicates a change in activation state

WM_ACTIVATEAPP	Notifies applications when a new task activates

WM_ASKCBFORMATNAME	Retrieves the name of the clipboard format

WM_CANCELJOURNAL	Notifies application when user cancels journaling

WM_CANCELMODE	Notifies a window to cancel internal modes

WM_CHANGECBCHAIN	Notifies clipboard viewer of removal from chain

WM_CHAR	Indicates the user pressed a character key

WM_CHARTOITEM	Provides list-box keystrokes to owner window

WM_CHILDACTIVATE	Notifies a child window of activation

WM_CHOOSEFONT_GETLOGFONT	Retrieves LOGFONT structure for Font dialog box

WM_CLEAR	Clears an edit control

WM_CLOSE	System Close menu command was chosen

WM_COMMAND	Specifies a command message

WM_COMPACTING	Indicates a low memory condition

WM_COMPAREITEM	Determines position of combo- or list-box item

WM_COPY	Copies a selection to the clipboard

WM_COPYDATA	Passes data to another application

WM_CREATE	Indicates a window is being created

WM_CTLCOLORBTN	Button is about to be drawn

WM_CTLCOLORDLG	Dialog box is about to be drawn

WM_CTLCOLOREDIT	Control is about to be drawn

WM_CTLCOLORLISTBOX	List box is about to be drawn

WM_CTLCOLORMSGBOX	Message box is about to be drawn

WM_CTLCOLORSCROLLBAR	Indicates scroll bar is about to be drawn

WM_CTLCOLORSTATIC	Control is about to be drawn

WM_CUT	Deletes a selection and copies it to the clipboard

WM_DDE_ACK	Acknowledges a DDE message

WM_DDE_ADVISE	Requests a DDE data-change update

WM_DDE_DATA	Sends data to a DDE client

WM_DDE_EXECUTE	Sends a string to a DDE server

WM_DDE_INITIATE	Initiates a DDE conversation

WM_DDE_POKE	Send unsolicited data to a server

WM_DDE_REQUEST	Requests data from a DDE server

WM_DDE_TERMINATE	Ends a DDE conversation

WM_DDE_UNADVISE	Stops a DDE data-update request

WM_DEADCHAR	Indicates the user pressed a dead key

WM_DELETEITEM	Indicates owner-draw item or control was altered

WM_DESTROY	Indicates window is about to be destroyed

WM_DESTROYCLIPBOARD	Notifies owner that the clipboard was emptied

WM_DEVMODECHANGE	Indicates the device-mode settings have changed

WM_DRAWCLIPBOARD	Indicates the clipboard's contents have changed

WM_DRAWITEM	Indicates owner-draw control/menu needs redrawing

WM_DROPFILES	Indicates that a file has been dropped

WM_ENABLE	Indicates a window's enable state is changing

WM_ENDSESSION	Indicates whether the Windows session is ending

WM_ENTERIDLE	Indicates a modal dialog box or menu is idle

WM_ENTERMENULOOP	Indicates entry into menu modal loop

WM_EXITMENULOOP	Indicates exit from menu modal loop

WM_ERASEBKGND	Indicates a window's background need erasing

WM_FONTCHANGE	Indicates a change in the font-resource pool

WM_GETDLGCODE	Allows dialog procedure to process control input

WM_GETFONT	Retrieves the font that a control is using

WM_GETHOTKEY	Gets the virtual-key code of a window's hot key

WM_GETMINMAXINFO	Gets minimum and maximum sizing information

WM_GETTEXT	Gets the text that corresponds to a window

WM_GETTEXTLENGTH	Gets length of text associated with a window

WM_HOTKEY	Hot key has been detected

WM_HSCROLL	Indicates a click in a horizontal scroll bar

WM_HSCROLLCLIPBOARD	Prompts owner to scroll clipboard contents

WM_ICONERASEBKGND	Notifies minimized window to fill icon background

WM_INITDIALOG	Initializes a dialog box

WM_INITMENU	Indicates a menu is about to become active

WM_INITMENUPOPUP	Indicates a pop-up menu is being created

WM_KEYDOWN	Indicates a nonsystem key was pressed

WM_KEYUP	Indicates a nonsystem key was released

WM_KILLFOCUS	Indicates the window is losing keyboard focus

WM_LBUTTONDBLCLK	Indicates double-click of left button

WM_LBUTTONDOWN	Indicates when left mouse button is pressed

WM_LBUTTONUP	Indicates when left mouse button is released

WM_MBUTTONDBLCLK	Indicates double-click of middle mouse button

WM_MBUTTONDOWN	Indicates when middle mouse button is pressed

WM_MBUTTONUP	Indicates when middle mouse button is released

WM_MDIACTIVATE	Activates an MDI child window

WM_MDICASCADE	Arranges MDI child windows in cascade format

WM_MDICREATE	Prompts MDI client to create a child window

WM_MDIDESTROY	Closes an MDI child window

WM_MDIGETACTIVE	Retrieves data about the active MDI child window

WM_MDIICONARRANGE	Arranges minimized MDI child windows

WM_MDIMAXIMIZE	Maximizes an MDI child window

WM_MDINEXT	Activates the next MDI child window

WM_MDIREFRESHMENU	Refreshes an MDI frame window's menu

WM_MDIRESTORE	Prompts MDI client to restore a child window

WM_MDISETMENU	Replaces an MDI frame window's menu

WM_MDITILE	Arranges MDI child windows in tiled format

WM_MEASUREITEM	Requests dimensions of owner-draw control or item

WM_MENUCHAR	Indicates an unknown menu mnemonic was pressed

WM_MENUSELECT	Indicates that the user selected a menu item

WM_MOUSEACTIVATE	Indicates a mouse click in an inactive window

WM_MOUSEMOVE	Indicates mouse-cursor movement

WM_MOVE	Indicates a window's position has changed

WM_NCACTIVATE	Changes the active state of nonclient area

WM_NCCALCSIZE	Calculates the size of a window's client area

WM_NCCREATE	Indicates a window's nonclient area being created

WM_NCDESTROY	Indicates window's nonclient area being destroyed

WM_NCHITTEST	Indicates mouse-cursor movement

WM_NCLBUTTONDBLCLK	Indicates nonclient left button double-click

WM_NCLBUTTONDOWN	Indicates left button pressed in nonclient area

WM_NCLBUTTONUP	Indicates left button released in nonclient area

WM_NCMBUTTONDBLCLK	Indicates nonclient middle button double-click

WM_NCMBUTTONDOWN	Indicates middle button pressed in nonclient area

WM_NCMBUTTONUP	Indicates middle button released in nonclient area

WM_NCMOUSEMOVE	Indicates mouse-cursor movement in nonclient area

WM_NCPAINT	Indicates a window's frame needs painting

WM_NCRBUTTONDBLCLK	Indicates nonclient right button double-click

WM_NCRBUTTONDOWN	Indicates right button pressed in nonclient area

WM_NCRBUTTONUP	Indicates right button released in nonclient area

WM_NEXTDLGCTL	Sets focus to different dialog box control

WM_PAINT	Indicates a window's client area need painting

WM_PAINTCLIPBOARD	Prompts owner to display clipboard contents

WM_PAINTICON	Icon is about to be painted

WM_PALETTECHANGED	Indicates the focus-window realized its palette

WM_PALETTEISCHANGING	Informs windows that palette is changing

WM_PARENTNOTIFY	Notifies parent of child-window activity

WM_PASTE	Inserts clipboard data into an edit control

WM_POWER	Indicates the system is entering suspended mode

WM_QUERYDRAGICON	Requests a cursor handle for a minimized window

WM_QUERYENDSESSION	Requests that the Windows session be ended

WM_QUERYNEWPALETTE	Allows a window to realize its logical palette

WM_QUERYOPEN	Requests that a minimized window be restored

WM_QUEUESYNC	Delimits CBT messages

WM_QUIT	Requests that an application be terminated

WM_RBUTTONDBLCLK	Indicates double-click of right mouse button

WM_RBUTTONDOWN	Indicates when right mouse button is pressed

WM_RBUTTONUP	Indicates when right mouse button is released

WM_RENDERALLFORMATS	Notifies owner to render all clipboard formats

WM_RENDERFORMAT	Notifies owner to render clipboard data

WM_SETCURSOR	Prompts a window to set the cursor shape

WM_SETFOCUS	Indicates the window gained the keyboard focus

WM_SETFONT	Sets the font for a control

WM_SETHOTKEY	Associates a hot key with a window

WM_SETREDRAW	Allows or prevents redrawing in a window

WM_SETTEXT	Sets the text of a window

WM_SHOWWINDOW	Indicates a window is about to be hidden or shown

WM_SIZE	Indicates a change in a window's size

WM_SIZECLIPBOARD	Indicates a change in the chipboard's size

WM_SPOOLERSTATUS	Indicates a print job was added or removed

WM_SYSCHAR	Indicates a System-menu key was pressed

WM_SYSCOLORCHANGE	Indicates a system color value was changed

WM_SYSCOMMAND	Indicates a system command was requested

WM_SYSDEADCHAR	Indicates a system dead key was pressed

WM_SYSKEYDOWN	Indicates that ALT plus another key was pressed

WM_SYSKEYUP	Indicates that ALT plus another key was released

WM_TIMECHANGE	Indicates the system time has been set

WM_TIMER	Indicates timeout interval for a timer has elapsed

WM_UNDO	Undoes the last operation in an edit control

WM_USER	Indicates a range of message values

WM_VKEYTOITEM	Provides list-box keystrokes to owner window

WM_VSCROLL	Indicates a click in a vertical scroll bar

WM_VSCROLLCLIPBOARD	Prompts owner to scroll clipboard contents

WM_WINDOWPOSCHANGED	Notifies window of size or position change

WM_WINDOWPOSCHANGING	Notifies window of new size or position

WM_WININICHANGE	Notifies applications that WIN.INI has changed


Microsoft Win32 API Functions and Overviews

Atoms	Bitmaps

Brushes	Buttons

Carets	Clipboard

Clipping	Colors

Combo Boxes	Common Dialog Box Library

Communications	Consoles and Character-Mode Support

Control Panel Applications	Controls

Coordinate Spaces and Transformations	Cursors

Data Decompression Library	Debugging

Device Contexts	Device I/O

Dialog Boxes	Dynamic Data Exchange Management Library (DDEML)

Dynamic Data Exchange	Dynamic-Link Libraries

Edit Controls	Errors

Event Logging	Files

File Installation Library	File Manager Extensions

File Mapping	File Systems

Filled Shapes	Fonts and Text

Handles and Objects	High-Level Audio

Hooks	Icons

Introduction to Audio	Introduction to Multimedia Services

Keyboard Accelerators	Keyboard Input

Lines and Curves	List Boxes

Low-Level Audio	Mailslots

Media Control Interface	Memory Management

Menus	Messages and Message Queues

Metafiles	Mouse Input

Multimedia File I/O	Multimedia Timers

Multiple Document Interface	Network DDE

Networks	Object Linking and Embedding Libraries (OLE)

Painting and Drawing	Paths

Pens	Performance Monitoring

Pipes	Printing and Print Spooler

Processes and Threads	Rectangles

Regions	Registry and Initialization Files

Remote Access	Resources

Screen Saver Library	Scroll Bars

Security	Services

Shell DDE Interface	Shell Library

Static Controls	String Manipulation and Unicode

Structured Exception Handling	Synchronization

System Information	Tape Backup

Time	Timers

Window Classes	Window Procedures

Window Properties	Windows


FN_NEW
This function, structure, or message is new for Win32.


FN_WIN32S
This function, structure, or message can be used for both Win32 and Win32s applications.


FN_GLOBE
This function, structure, or message can be used with either Windows or Unicode characters.


Microsoft Windows 32-bit API Reference

Information in this on-line help system is subject to change without notice and does not represent a commitment on the part of Microsoft Corporation. The software and/or files described in this on-line help system are furnished under a license agreement or nondisclosure agreement. The software and/or files may be used or copied only in accordance with the terms of the agreement. The purchaser may make one copy of the software for backup purposes. No part of this on-line help system may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information and retrieval systems, for any purpose other than the purchaser's personal use, without the written permission of Microsoft Corporation.

(C)  Copyright Microsoft Corporation, 1992-1993. All rights reserved.

     Simultaneously published in the U.S. and Canada.

Portions of this documentation are provided under license from Digital

Equipment Corporation.

(C)  Copyright Digital Equipment Corporation, 1990, 1992-1993. All rights

     reserved.

     Help Database Build Date: 13 Jul 1993


N
This function, structure, or message is new for Win32.


W
This function, structure, or message can be used for both Win32 and Win32s applications.


G
This function, structure, or message can be used with either Windows or Unicode characters.


auxGetDevCaps function
auxGetDevCaps (Win32)

MMRESULT auxGetDevCaps(IDAuxDev, lpauxc, cbAuxc)

UINT IDAuxDev;	/* identifier of aux device to query	*/
LPAUXCAPS lpauxc;	/* address of AUXCAPS structure for results	*/
UINT cbAuxc;	/* size of AUXCAPS structure, in bytes	*/

The auxGetDevCaps function queries a specified auxiliary output device to determine its capabilities.

Parameter	Description

IDAuxDev	Identifies the auxiliary output device to be queried. Specify a valid device identifier. The device identifier varies from zero to one less than the number of devices present. Use auxGetNumDevs to determine the number of auxiliary devices present in the system. The special value AUX_MAPPER also be used to specify an auxiliary audo mapper. If AUX_MAPPER is used, the function will return an error if no auxiliary audio mapper is installed.

lpauxc	Points to an AUXCAPS structure that receives information about the capabilities of the device.

cbAuxc	Specifies the size, in bytes, of the AUXCAPS structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error number. Following are possible error returns.

Value	Meaning

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.

MMSYSERR_NODRIVER	The driver failed to install.

Comments

The device identifier specified by IDAuxDev 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 devices present in the system.

See Also

auxGetNumDevs, AUXCAPS


auxGetNumDevs function
auxGetNumDevs (Win32)

UINT auxGetNumDevs(VOID)

The auxGetNumDevs function retrieves the number of auxiliary output devices present in the system.

Returns

If the function succeeds, the return value is the number of auxiliary output devices present in the system.

See Also

auxGetDevCaps


auxGetVolume function
auxGetVolume (Win32)

MMRESULT auxGetVolume(IDAuxDev, lpdwVolume)

UINT IDAuxDev;	/* identifier of aux device to query	*/
LPDWORD lpdwVolume;	/* address of buffer for volume settings	*/

The auxGetVolume function returns the current volume setting of an auxiliary output device.

Parameter	Description

IDAuxDev	Identifies the auxiliary output device to be queried.

lpdwVolume	Points to a variable that receives the current volume setting. The low-order word of this variable 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 variable contains the volume level.

The full 16-bit settings set with the auxSetVolume function are returned, regardless of whether the device supports the full 16 bits of volume-level control.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.

MMSYSERR_NODRIVER	The driver failed to install.

Comments

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

See Also

auxGetDevCaps, auxSetVolume, AUXCAPS


auxOutMessage function
auxOutMessage (Win32)

MMRESULT auxOutMessage(IDAuxDev, uMsg, dwParam1, dwParam2)

UINT IDAuxDev;	/* identifier of aux device to send message to	*/
UINT uMsg;	/* message	*/
DWORD dwParam1;	/* message-specific parameter	*/
DWORD dwParam2;	/* message-specific parameter	*/

The auxOutMessage function sends a message to an auxiliary output device.

Parameter	Description

IDAuxDev	Identifies the auxiliary output device to send the message to. Specify a valid device identifier. The device identifier varies from zero to one less than the number of devices present. Use auxGetNumDevs to determine the number of auxiliary devices present in the system. The special value AUX_MAPPER can also be used to specify an auxiliary audio mapper. If AUX_MAPPER is used, the function will return an error if no auxiliary audio mapper is installed.

uMsg	The message to send.

dwParam1	Parameter.

dwParam2	Parameter.

Returns

If the function succeeds, the return value is the value returned by the device driver.

See Also

auxGetNumDevs


auxSetVolume function
auxSetVolume (Win32)

MMRESULT auxSetVolume(IDAuxDev, dwVolume)

UINT IDAuxDev;	/* identifier of aux device to set volume for	*/
DWORD dwVolume;	/* new volume setting	*/

The auxSetVolume function sets the volume in an auxiliary output device.

Parameter	Description

IDAuxDev	Identifies the auxiliary output device to set the volume for. 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 auxGetNumDevs 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 the dwVolume parameter specifies the volume level, and the high-order word is ignored.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.

MMSYSERR_NODRIVER	The driver failed to install.

Comments

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 all produce the same physical volume setting, 0x4000. The auxGetVolume function will return the full 16-bit setting set with the auxSetVolume function.

Volume settings are interpreted logarithmically. This means the perceived volume increase is the same from volume level 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

See Also

auxGetDevCaps, auxGetVolume, AUXCAPS


joyGetDevCaps function
joyGetDevCaps (Win32)

MMRESULT joyGetDevCaps(IDDevice, lpjc, cbjc)

UINT IDDevice;	/* identifies device to query	*/
LPJOYCAPS lpjc;	/* address of structure for device capabilities	*/
UINT cbjc;	/* size of structure in bytes	*/

The joyGetDevCaps function queries a joystick device to determine its capabilities.

Parameter	Description

IDDevice	Identifies the device to be queried. This value is either JOYSTICKID1 or JOYSTICKID2.

lpjc	Points to a JOYCAPS structure. This structure is filled with information about the capabilities of the joystick device.

cbjc	Specifies the size, in bytes, of the JOYCAPS structure.

Returns

If the function succeeds, the return value is JOYERR_NOERROR. Otherwise, the return value is an error code that can be one of the following:

Value	Meaning

MMSYSERR_NODRIVER	The joystick driver is not present.

JOYERR_PARMS	The specified joystick device identifier IDDevice is invalid.

Comments

Use the joyGetNumDevs function to determine the number of joystick devices supported by the driver.

See Also

joyGetNumDevs


joyGetNumDevs function
joyGetNumDevs (Win32)

UINT joyGetNumDevs(VOID)

The joyGetNumDevs function returns the number of joystick devices supported by the system.

Returns

If the function succeeds, the return value is the number of joystick devices supported by the joystick driver. If no driver is present, the function returns zero.

Comments

Use the joyGetPos function to determine whether a given joystick is actually attached to the system. The joyGetPos function returns a JOYERR_UNPLUGGED error code if the specified joystick is not connected.

See Also

joyGetDevCaps, joyGetPos


joyGetPos function
joyGetPos (Win32)

MMRESULT joyGetPos(IDDevice, lpji)

UINT IDDevice;	/* identifies device to query	*/
LPJOYINFO lpji;	/* address of structure for information	*/

The joyGetPos function queries for the position and button activity of a joystick device.

Parameter	Description

IDDevice	Identifies the joystick device to be queried. This value is either JOYSTICKID1 or JOYSTICKID2.

lpji	Points to a JOYINFO structure. This structure is filled with information about the position and button activity of the joystick device.

Returns

If the function succeeds, the return value is JOYERR_NOERROR. Otherwise, the return value is an error code that can be one of the following:

Value	Meaning

MMSYSERR_NODRIVER	The joystick driver is not present.

JOYERR_PARMS	The specified joystick device identifier IDDevice is invalid.

JOYERR_UNPLUGGED	The specified joystick is not connected to the system.


joyGetThreshold function
joyGetThreshold (Win32)

MMRESULT joyGetThreshold(IDDevice, puThreshold)

UINT IDDevice;	/* identifies device to query	*/
PUINT puThreshold;	/* address of variable for threshold	*/

The joyGetThreshold function queries the current movement threshold of a joystick device.

Parameter	Description

IDDevice	Identifies the joystick device to be queried. This value is either JOYSTICKID1 or JOYSTICKID2.

puThreshold	Points to a variable that will receive the movement threshold value.

Returns

If the function succeeds, the return value is JOYERR_NOERROR. Otherwise, the return value is an error code that can be one of the following:

Value	Meaning

MMSYSERR_NODRIVER	The joystick driver is not present.

JOYERR_PARMS	The specified joystick device identifier IDDevice is invalid.

Comments

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.

See Also

joySetThreshold


joyReleaseCapture function
joyReleaseCapture (Win32)

MMRESULT joyReleaseCapture(IDDevice)

UINT IDDevice;	/* identifies device to release	*/

The joyReleaseCapture function releases the capture set by the joySetCapture function on the specified joystick device.

Parameter	Description

IDDevice	Identifies the joystick device to be released. This value is either JOYSTICKID1 or JOYSTICK2.

Returns

If the function succeeds, the return value is JOYERR_NOERROR. Otherwise, the return value is an error code that can be one of the following:

Value	Meaning

MMSYSERR_NODRIVER	The joystick driver is not present.

JOYERR_PARMS	The specified joystick device identifier IDDevice is invalid.

See Also

joySetCapture


joySetCapture function
joySetCapture (Win32)

MMRESULT joySetCapture(hwnd, IDDevice, cPollingMS, fChanged)

HWND hwnd;	/* handle of window that receives messages	*/
UINT IDDevice;	/* identifies device to capture	*/
UINT cPollingMS;	/* polling rate in milliseconds	*/
BOOL fChanged;	/* send messages only above threshold	*/

The joySetCapture function causes joystick messages to be sent to the specified window.

Parameter	Description

hwnd	Identifies the window to which messages are to be sent.

IDDevice	Identifies the joystick device to be captured. This value is either JOYSTICKID1 or JOYSTICKID2.

cPollingMS	Specifies the polling rate in milliseconds.

fChanged	If this parameter is set to TRUE, messages are sent only when the position changes by a value greater than the joystick-movement threshold.

Returns

If the function succeeds, the return value is JOYERR_NOERROR. Otherwise, the return value is an error code that can be one of the following:

Value	Meaning

MMSYSERR_NODRIVER	The joystick driver is not present.

JOYERR_PARMS	The specified window handle hwnd or joystick device identifier IDDevice is invalid.

JOYERR_NOCANDO	Cannot capture joystick input because some required service (for example, a Windows timer) is unavailable.

JOYERR_UNPLUGGED	The specified joystick is not connected to the system.

Comments

This function fails if the specified joystick device is currently captured. Call the joyReleaseCapture function when the joystick capture is no longer needed. If the window is destroyed, the joystick will be released automatically.

See Also

joyGetThreshold, joyReleaseCapture, joySetThreshold


joySetThreshold function
joySetThreshold (Win32)

MMRESULT joySetThreshold(IDDevice, uThreshold)

UINT IDDevice;	/* identifies device to set threshold for	*/
UINT uThreshold;	/* new threshold value	*/

The joySetThreshold function sets the movement threshold of a joystick device.

Parameter	Description

IDDevice	Identifies the joystick device. This value is either JOYSTICKID1 or JOYSTICKID2.

uThreshold	Specifies the new movement threshold.

Returns

If the function succeeds, the return value is JOYERR_NOERROR. Otherwise, the return value is an error code that can be one of the following:

Value	Meaning

MMSYSERR_NODRIVER	The joystick driver is not present.

JOYERR_PARMS	The specified joystick device identifier IDDevice is invalid.

Comments

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.

See Also

joyGetThreshold, joySetCapture


mciGetCreatorTask function
mciGetCreatorTask (Win32)

HANDLE mciGetCreatorTask(IDDevice)

MCIDEVICEID IDDevice;	/* device to get creator task for	*/

The mciGetCreatorTask function retrieves the creator task for the specified device.

Parameter	Description

IDDevice	Identifies the device whose creator task is to be returned.

Returns

If the function succeeds, the return value is the handle of the creator task responsible for opening the device. If the device identifier is invalid, the return value is NULL.


mciGetDeviceID function
mciGetDeviceID (Win32)

MCIDEVICEID mciGetDeviceID(lpszDevice)

LPCTSTR lpszDevice;	/* address of device name	*/

The mciGetDeviceID function returns the device identifier corresponding to the name of an open device.

Parameter	Description

lpszDevice	Points to a null-terminated string that specifies the device name or the alias name by which the device is known.

Returns

If the function succeeds, the return value is the device identifier assigned to the device when it was opened. It is used in the mciSendCommand function.

The return value is zero if the device name is not known, if the device is not open, or if there was not enough memory to complete the operation.

Comments

Each compound device element has a unique device identifier. The identifier of the "all" device is MCI_ALL_DEVICE_ID.


mciGetErrorString function
mciGetErrorString (Win32)

BOOL mciGetErrorString(fdwError, lpszErrorText, cchErrorText)

DWORD fdwError;	/* error code	*/
LPTSTR lpszErrorText;	/* address of buffer for error string	*/
UINT cchErrorText;	/* size of buffer, in characters	*/

The mciGetErrorString function retrieves a string that describes the specified Media Control Interface (MCI) error code.

Parameter	Description

fdwError	Specifies the error code returned by the mciSendCommand or mciSendString function.

lpszErrorText	Points to a buffer that receives a null-terminated string describing the specified error.

cchErrorText	Specifies the length of the buffer, in characters, pointed to by the lpszErrorText parameter .

Returns

If the function succeeds, the return value is TRUE. If the error code is not known, the return value is FALSE.


mciGetYieldProc function
mciGetYieldProc (Win32)

YIELDPROC mciGetYieldProc(IDDevice, lpdwYieldData)

MCIDEVICEID IDDevice;	/* device being monitored	*/
LPDWORD lpdwYieldData;	/* address of yield data to be passed	*/

The mciGetYieldProc function returns the address of the callback function associated with the mci WAIT flag; the callback function is called periodically while an MCI device waits for a command specified with the WAIT flag to finish.

Parameter	Description

IDDevice	Specifies the MCI device being monitored (the device performing an MCI command).

lpdwYieldData	Points to a buffer containing yield data to be passed to the callback function. This parameter can be NULL if there is no yield data.

Returns

If the function succeeds, the return value is the address of the current yield callback function. If the device identifier is invalid, the return value is NULL.

See Also

mciSetYieldProc


mciSendCommand function
mciSendCommand (Win32)

MCIERROR mciSendCommand(IDDevice, uMsg, fdwCommand, dwParam)

MCIDEVICEID IDDevice;	/* device to send message to	*/
UINT uMsg;	/* message to send	*/
DWORD fdwCommand;	/* message-specific parameter	*/
DWORD dwParam;	/* message-specific parameter	*/

The mciSendCommand function sends a command message to the specified Media Control Interface (MCI) device.

Parameter	Description

IDDevice	Specifies the 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	Specifies the command message.

fdwCommand	Specifies flags for the command message.

dwParam	Specifies a pointer to a structure that contains parameters for the command message.

Returns

If the function succeeds, the return value is zero. Otherwise, the return value is an error code. The low-order word of the return value is 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 more information about possible error values, see the Comments section in this entry.

To get a text description of mciSendCommand return values, pass the return value to the mciGetErrorString function.

Comments

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 following values:

Value	Meaning

MCIERR_BAD_TIME_FORMAT	The value for the time format is illegal.

MCIERR_CANNOT_USE_ALL	The device name "all" is not allowed for this command.

MCIERR_CREATEWINDOW	The window could not be created or used.

MCIERR_DEVICE_LOCKED	The device is locked until it is closed automatically.

MCIERR_DEVICE_NOT_READY	The device is not ready.

MCIERR_DEVICE_TYPE_REQUIRED	The device name must be a valid device type.

MCIERR_DRIVER	There was an unspecified device error.

MCIERR_DRIVER_INTERNAL	There was an internal driver error.

MCIERR_FILE_NOT_FOUND	The requested file was not found.

MCIERR_FILE_NOT_SAVED	The file was not saved.

MCIERR_FILE_READ	A read operation from the file failed.

MCIERR_FILE_WRITE	A write operation to the file failed.

MCIERR_FLAGS_NOT_COMPATIBLE	Incompatible parameters were specified.

MCIERR_HARDWARE	There was a hardware error on the media device.

MCIERR_INTERNAL	There was an internal error.

MCIERR_INVALID_DEVICE_ID	The device identifier is invalid.

MCIERR_INVALID_DEVICE_NAME	The device is not open or is not known.

MCIERR_INVALID_FILE	The file format is invalid.

MCIERR_MULTIPLE	Errors occurred in more than one device.

MCIERR_NO_WINDOW	There is no display window.

MCIERR_NULL_PARAMETER_BLOCK	The pointer to the structure containing the command-message parameters was NULL.

MCIERR_OUT_OF_MEMORY	There is not enough memory for the requested operation.

MCIERR_OUTOFRANGE	The parameter value is out of range.

MCIERR_UNNAMED_RESOURCE	The file to be saved was unnamed.

MCIERR_UNRECOGNIZED_COMMAND	The requested command is unknown.

MCIERR_UNSUPPORTED_FUNCTION	The action is not available for this device.

The following additional return values are defined for MCI sequencers:

Value	Meaning

MCIERR_SEQ_DIV_INCOMPATIBLE	The set song pointer is incompatible with SMPTE files.

MCIERR_SEQ_PORT_INUSE	The specified port is in use.

MCIERR_SEQ_PORT_MAPNODEVICE	The current map uses nonexistent device.

MCIERR_SEQ_PORT_MISCERROR	A miscellaneous error occurred with specified port.

MCIERR_SEQ_PORT_NONEXISTENT	The specified port does not exist.

MCIERR_SEQ_PORTUNSPECIFIED	No current MIDI port is specified.

MCIERR_SEQ_NOMIDIPRESENT	No MIDI ports are present.

MCIERR_SEQ_TIMER	A timer error occurred.

The following additional return values are defined for MCI waveform audio devices:

Value	Meaning

MCIERR_WAVE_INPUTSINUSE	No compatible waveform recording device is free.

MCIERR_WAVE_INPUTSUNSUITABLE	No compatible waveform recording devices are available.

MCIERR_WAVE_INPUTUNSPECIFIED	Any compatible waveform recording device may be used.

MCIERR_WAVE_OUTPUTSINUSE	No compatible waveform playback device is free.

MCIERR_WAVE_OUTPUTSUNSUITABLE	No compatible waveform playback devices are available.

MCIERR_WAVE_OUTPUTUNSPECIFIED	Any compatible waveform playback device may be used.

MCIERR_WAVE_SETINPUTINUSE	The set waveform recording device is in use.

MCIERR_WAVE_SETINPUTUNSUITABLE	The set waveform recording device is incompatible with the set format.

MCIERR_WAVE_SETOUTPUTINUSE	The set waveform playback device is in use.

MCIERR_WAVE_SETOUTPUTUNSUITABLE	The set waveform playback device is incompatible with the set format.

Use the MCI_OPEN command message to obtain the device identifier specified by the IDDevice parameter.

See Also

mciGetErrorString, mciSendString


mciSendString function
mciSendString (Win32)

MCIERROR mciSendString(lpszCommand, lpszReturnString, cchReturn, hwndCallback)

LPCTSTR lpszCommand;	/* address of MCI command string	*/
LPTSTR lpszReturnString;	/* address of return buffer	*/
UINT cchReturn;	/* size of return buffer, in characters	*/
HANDLE hwndCallback;	/* callback-window handle	*/

The mciSendString function sends a command string to a Media Control Interface (MCI) device. The device that the command is sent to is specified in the command string.

Parameter	Description

lpszCommand	Points to a null-terminated string that specifies an MCI command string of the following form:

    [command] [device] [parameters]

lpszReturnString	Points to a buffer that receives return information. If no return information is needed, this parameter can be NULL.

cchReturn	Specifies the size, in characters, of the return buffer specified by the lpszReturnString parameter.

hwndCallback	Specifies a handle of a callback window if "notify" was specified in the command string.

Returns

If the function succeeds, the return value is zero. Otherwise, the return value is an error code. The low-order word of the returned doubleword contains the error return value. For more information about possible error values, see the Comments section in this entry.

To get a text description of mciSendString return values, pass the return value to the mciGetErrorString function.

Comments

The error values listed for the mciSendCommand function also apply to mciSendString. The following error values are unique to mciSendString:

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.

See Also

mciGetErrorString, mciSendCommand


mciSetYieldProc function
mciSetYieldProc (Win32)

BOOL mciSetYieldProc(IDDevice, yp, dwYieldData)

MCIDEVICEID IDDevice;	/* device to set yield procedure for	*/
YIELDPROC yp;	/* address of yield procedure	*/
DWORD dwYieldData;	/* yield-procedure data	*/

The mciSetYieldProc function sets the address of a procedure to be called periodically when a Media Control Interface (MCI) device is waiting for a command to finish because the WAIT flag was specified.

Parameter	Description

IDDevice	Specifies the identifier of the device to assign a procedure to.

yp	Specifies the address of the procedure to call when yielding for the given device. If this parameter is NULL, the function disables any existing yield procedure.

dwYieldData	Specifies the data to be sent to the yield procedure when it is called for the given device.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

This function overrides any previous yield procedure for this device.

See Also

mciGetYieldProc


midiInAddBuffer function
midiInAddBuffer (Win32)

MMRESULT midiInAddBuffer(hMidiIn, lpmidiih, cbMidiIh)

HMIDIIN hMidiIn;	/* MIDI input device	*/
LPMIDIHDR lpmidiih;	/* address of MIDI header structure	*/
UINT cbMidiIh;	/* size of MIDI header structure, in bytes	*/

The midiInAddBuffer function sends an input buffer to a specified open Musical Instrument Digital Interface (MIDI) input device. When the buffer is filled, its address is sent back to the application. Input buffers are used only for system-exclusive messages.

Parameter	Description

hMidiIn	Identifies to the MIDI input device.

lpmidiih	Points to a MIDIHDR structure that identifies the buffer.

cbMidiIh	Specifies the size, in bytes, of the MIDIHDR structure.

Returns

If the function succeeds, the return value is zero; otherwise, the return value is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	Specified device handle is invalid.

MIDIERR_UNPREPARED	lpmidiih hasn't been prepared.

Comments

The data buffer must be prepared with the midiInPrepareHeader function before it is passed to midiInAddBuffer. The MIDIHDR  structure and the data buffer pointed to by its lpData member must be allocated by using the GlobalAlloc function and the GMEM_MOVEABLE and GMEM_SHARE flags, and must be locked using the GlobalLock function.

See Also

midiInPrepareHeader


midiInClose function
midiInClose (Win32)

MMRESULT midiInClose(hMidiIn)

HMIDIIN hMidiIn;	/* handle of input device to close	*/

The midiInClose function closes the specified Musical Instrument Digital Interface (MIDI) input device.

Parameter	Description

hMidiIn	Identifies the MIDI input device. If the function succeeds, the handle is no longer valid after this call.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

Musical Instrument Digital Interface (MIDI)ERR_STILLPLAYING	There are still buffers in the queue.

Comments

If there are input buffers that have been sent using the midiInAddBuffer function and have not been returned to the application, the close operation will fail. Call the midiInReset function to mark all pending buffers as done.

See Also

midiInOpen, midiInReset


midiInGetDevCaps function
midiInGetDevCaps (Win32)

MMRESULT midiInGetDevCaps(IDDevice, lpmic, cbmic)

UINT IDDevice;	/* identifier of device to query	*/
LPMIDIINCAPS lpmic;	/* address of structure for capabilities	*/
UINT cbmic;	/* size of structure, in bytes	*/

The midiInGetDevCaps function queries a specified Musical Instrument Digital Interface (MIDI) input device to determine its capabilities.

Parameter	Description

IDDevice	Identifies the MIDI input device.

lpmic	Points to a MIDIINCAPS structure that will receive information about the capabilities of the device.

cbmic	Specifies the size, in bytes, of the MIDIINCAPS structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_BADDEVICEID	Specified device identifier is out of range.

MMSYSERR_NODRIVER	The driver was not installed.

Comments

Use the midiInGetNumDevs function to determine the number of MIDI input devices present in the system. The device identifier specified by IDDevice varies from zero to one less than the number of devices present. The MIDI_MAPPER constant may also be used as a device identifier. Only cbmic (or fewer) bytes of information are copied to the location pointed to by lpmic. If cbmic is zero, nothing is copied, and the function returns zero.

See Also

midiInGetNumDevs


midiInGetErrorText function
midiInGetErrorText (Win32)

MMRESULT midiInGetErrorText(mmrError, lpszDesc, cchDesc)

MMRESULT mmrError;	/* error code to get description for	*/
LPTSTR lpszDesc;	/* address of buffer for description	*/
UINT cchDesc;	/* length of buffer, in characters	*/

The midiInGetErrorText function retrieves a text description of the specified error.

Parameter	Description

mmrError	Specifies the error number.

lpszDesc	Points to a buffer that receives a null-terminated string that describes the error.

cchDesc	Specifies the length, in characters, of the buffer pointed to by lpszDesc.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code that can be MMYSYSERR_BADERRNUM, indicating that the specified error number is out of range.

Comments

If the text error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchDesc is zero, nothing is copied, and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long.


midiInGetID function
midiInGetID (Win32)

MMRESULT midiInGetID(hMidiIn, lpIDDevice)

HMIDIIN hMidiIn;	/* identifier of MIDI input device to query	*/
PUINT lpIDDevice;	/* address of buffer for device identifier	*/

The midiInGetID function gets the device identifier for a Musical Instrument Digital Interface (MIDI) input device.

Parameter	Description

hMidiIn	Identifies a handle of the MIDI input device.

lpIDDevice	Points to a variable that will receive the device identifier.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code that can be MMSYSERR_INVALHANDLE, indicating that the hMidiIn parameter specifies an invalid handle.


midiInGetNumDevs function
midiInGetNumDevs (Win32)

UINT midiInGetNumDevs(VOID)

The midiInGetNumDevs function retrieves the number of Musical Instrument Digital Interface (MIDI) input devices in the system.

Returns

If the return succeeds, the value is the number of MIDI input devices present in the system.

See Also

midiInGetDevCaps


midiInMessage function
midiInMessage (Win32)

MMRESULT midiInMessage(hMidiIn, uMsg, dwParam1, dwParam2)

HMIDIIN hMidiIn;	/* handle of MIDI device to receive message	*/
UINT uMsg;	/* message	*/
DWORD dwParam1;	/* application-defined parameter	*/
DWORD dwParam2;	/* application-defined parameter	*/

The midiInMessage function sends a message to a Musical Instrument Digital Interface (MIDI) input device.

Parameter	Description

hMidiIn	Identifies the MIDI device.

uMsg	Specifies the message to send.

dwParam1	Application-defined parameter.

dwParam2	Application-defined parameter.

Returns

If the function succeeds, the return value is the value of the message sent.


midiInOpen function
midiInOpen (Win32)

MMRESULT midiInOpen(lphMidiIn, IDDevice, dwCallback, dwCallbackInstance, fdwCallback)

LPHMIDIIN lphMidiIn;	/* address of variable for device handle	*/
UINT IDDevice;	/* device identifier	*/
DWORD dwCallback;	/* address of callback function	*/
DWORD dwCallbackInstance;	/* callback instance data	*/
DWORD fdwCallback;	/* callback type	*/

The midiInOpen function opens the specified Musical Instrument Digital Interface (MIDI) input device.

Parameter	Description

lphMidiIn	Points to a variable that will receive a handle identifying the opened MIDI input device. Use the handle of identify the device when calling other MIDI input functions.

IDDevice	Identifies the MIDI input device to be opened.

dwCallback	Specifies either the address of a fixed callback function or a handle of a window called with information about incoming MIDI messages. This parameter can be NULL if no callback is required.

For more information about the callback function, see the description of the MidiProc callback function.

dwCallbackInstance	Specifies user instance data passed to the callback function. This parameter is not used with window callbacks.

fdwCallback	Specifies a callback flag for opening the device. This parameter can be one of the following values:

Value	Meaning

CALLBACK_WINDOW	The dwCallback parameter is assumed to be a window handle.

CALLBACK_FUNCTION	The dwCallback parameter is assumed to be a callback procedure address.

CALLBACK_NULL	The dwCallback parameter is assumed to be NULL.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.

MMSYSERR_ALLOCATED	The specified resource is already allocated.

MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

Comments

Use the midiInGetNumDevs function to determine the number of MIDI input devices present in the system. The device identifier specified by IDDevice varies from zero to one less than the number of devices present.

The MIDI_MAPPER constant may not be used with this function.

If a window is chosen to receive callback information, the following messages are sent to the window procedure function 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

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

The callback function must reside in a DLL.

See Also

midiInClose, MidiProc


midiInPrepareHeader function
midiInPrepareHeader (Win32)

MMRESULT midiInPrepareHeader(hMidiIn, lpmidih, cbmidih)

HMIDIIN hMidiIn;	/* handle of MIDI input device	*/
LPMIDIHDR lpmidih;	/* address of structure for buffer to prepare	*/
UINT cbmidih;	/* size of structure in bytes	*/

The midiInPrepareHeader function prepares a buffer for Musical Instument Digital Interface (MIDI) input.

Parameter	Description

hMidiIn	Identifies the MIDI input device.

lpmidih	Points to a MIDIHDR structure that identifies the buffer to be prepared.

cbmidih	Specifies the size, in bytes, of the MIDIHDR structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

Comments

The MIDIHDR structure and the data block pointed to by its lpData member must be allocated by using the GlobalAlloc function and the GMEM_MOVEABLE and GMEM_SHARE flags, and must be locked by using the GlobalLock function. Preparing a header that has already been prepared has no effect, and the function returns zero.

See Also

midiInUnprepareHeader


midiInReset function
midiInReset (Win32)

MMRESULT midiInReset(hMidiIn)

HMIDIIN hMidiIn;	/* handle of device to reset	*/

The midiInReset function stops input on a given Musical Instument Digital Interface (MIDI) input device and marks all pending input buffers as done.

Parameter	Description

hMidiIn	Identifies the MIDI input device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be MMSYSERR_INVALHANDLE, indicating that the specified device handle is invalid.

See Also

midiInStart, midiInStop, midiInAddBuffer, midiInClose


midiInStart function
midiInStart (Win32)

MMRESULT midiInStart(hMidiIn)

HMIDIIN hMidiIn;	/* handle of device to start	*/

The midiInStart function starts Musical Instument Digital Interface (MIDI) input on the specified input device.

Parameter	Description

hMidiIn	Identifies the MIDI input device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be MMSYSERR_INVALHANDLE, indicating that the specified device handle is invalid.

Comments

This function resets the time-stamps to zero; time-stamp values for subsequently received messages are relative to the time this function was called.

All messages other than system-exclusive messages are sent directly to the client when received. System-exclusive messages are placed in the buffers supplied by the midiInAddBuffer function; if there are no buffers in the queue, the data is thrown away without notification to the client, and input continues.

Buffers are returned to the client when full, when a complete system-exclusive message has been received, or when the midiInReset function is called. The dwBytesRecorded member in the header 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

midiInReset, midiInStop


midiInStop function
midiInStop (Win32)

MMRESULT midiInStop(hMidiIn)

HMIDIIN hMidiIn;	/* handle of device to stop	*/

The midiInStop function stops Musical Instument Digital Interface (MIDI) input on the specified MIDI input device.

Parameter	Description

hMidiIn	Identifies the MIDI input device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be MMSYSERR_INVALHANDLE, indicating that thew speicified handle is invalid.

Comments

Current status (running status, parsing state, etc.) is maintained across calls to the midiInStop and midiInStart functions. If there are any system-exclusive message buffers in the queue, the current buffer is marked as done. (The dwBytesRecorded member in the header will contain the actual length of data.) However, any empty buffers in the queue remain there. Calling this function when input is not started has no effect, and the function returns zero.

See Also

midiInReset, midiInStart


midiInUnprepareHeader function
midiInUnprepareHeader (Win32)

MMRESULT midiInUnprepareHeader(hMidiIn, lpmidih, cbmidih)

HMIDIIN hMidiIn;	/* handle of the MIDI input device	*/
LPMIDIHDR lpmidih;	/* address of structure for data buffer	*/
UINT cbmidih;	/* size of structure, in bytes	*/

The midiInUnprepareHeader function cleans up the preparation performed by the midiInPrepareHeader function. The midiInUnprepareHeader function must be called after the device driver fills a data buffer and returns it to the application. You must call this function before freeing the data buffer.

Parameter	Description

hMidiIn	Identifies the Musical Instument Digital Interface (MIDI) input device.

lpmidih	Points to a MIDIHDR structure that identifies the data buffer to be cleaned up.

cbmidih	Specifies the size, in bytes, of the MIDIHDR structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MIDIERR_STILLPLAYING	The lpmidih buffer is still in the queue.

Comments

This function complements the midiInPrepareHeader function. You must call this function before freeing the data buffer by using the GlobalFree function. 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 calling midiInUnprepareHeader. Unpreparing a buffer that has not been prepared has no effect, and the function returns zero.

See Also

midiInPrepareHeader


midiOutCacheDrumPatches function
midiOutCacheDrumPatches (Win32)

MMRESULT midiOutCacheDrumPatches(hMidiOut, uPatch, lpwkya, fuCache)

HMIDIOUT hMidiOut;	/* handle of MIDI output device	*/
UINT uPatch;	/* patch number	*/
LPWORD lpwkya;	/* address of key array	*/
UINT fuCache;	/* cache options	*/

The midiOutCacheDrumPatches function requests that an internal Musical Instument Digital Interface (MIDI) synthesizer device preload a specified set of key-based percussion patches. Some synthesizers are not capable of keeping all percussion patches loaded simultaneously. Caching patches ensures specified patches are available.

Parameter	Description

hMidiOut	Identifies the open MIDI output device. This device must be an internal MIDI synthesizer.

uPatch	Specifies which drum patch number to use. Set this parameter to zero to cache the default drum patch.

lpwkya	Points to a KEYARRAY array (an array of unsigned integer values) indicating the key numbers of the specified percussion patches to be cached or uncached.

fuCache	Specifies options for the cache operation. Only one of the following flags can be specified:

Value	Meaning

MIDI_CACHE_ALL	Cache all of the specified patches. If they can't all be cached, cache none, clear the KEYARRAY array, and return MMSYSERR_NOMEM.

MIDI_CACHE_BESTFIT	Cache all of the specified patches. If all patches can't be cached, cache as many patches as possible, change the KEYARRAY array to reflect which patches were cached, and return MMSYSERR_NOMEM.

MIDI_CACHE_QUERY	Change the KEYARRAY array to indicate which patches are currently cached.

MIDI_UNCACHE	Uncache the specified patches and clear the KEYARRAY array.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED	The specified device does not support patch caching.

MMSYSERR_NOMEM	The device does not have enough memory to cache all of the requested patches.

Comments

The KEYARRAY data type is defined as:

typedef WORD KEYARRAY[MIDIPATCHSIZE];

Each element of the array represents one of the 128 key-based percussion patches and has bits set for each of the 16 MIDI channels that use that particular patch. The least-significant bit represents physical channel 0; 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. Use the MIDICAPS_CACHE flag to test the dwSupport  member of the MIDIOUTCAPS structure filled by the midiOutGetDevCaps function to see if the device supports patch caching.

See Also

midiOutCachePatches


midiOutCachePatches function
midiOutCachePatches (Win32)

MMRESULT midiOutCachePatches(hMidiOut, uBank, lpwpa, fuCache)

HMIDIOUT hMidiOut;	/* handle of MIDI output device	*/
UINT uBank;	/* patch bank number	*/
LPWORD lpwpa;	/* address of patch array	*/
UINT fuCache;	/* cache options	*/

The midiOutCachePatches function requests that an internal Musical Instument Digital Interface (MIDI) synthesizer device preload a specified set of patches. 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 specified patches are immediately available.

Parameter	Description

hMidiOut	Identifies the open MIDI output device. This device must be an internal MIDI synthesizer.

uBank	Specifies which bank of patches should be used. This parameter should be set to zero to cache the default patch bank.

lpwpa	Points to a PATCHARRAY array indicating the patches to be cached or uncached.

fuCache	Specifies options for the cache operation. Only one of the following flags can be specified:

Value	Meaning

MIDI_CACHE_ALL	Cache all of the specified patches. If they can't all be cached, cache none, clear the PATCHARRAY array, and return MMSYSERR_NOMEM.

MIDI_CACHE_BESTFIT	Cache all of the specified patches. If all patches can't be cached, cache as many patches as possible, change the PATCHARRAY array to reflect which patches were cached, and return MMSYSERR_NOMEM.

MIDI_CACHE_QUERY	Change the PATCHARRAY array to indicate which patches are currently cached.

MIDI_UNCACHE	Uncache the specified patches and clear the PATCHARRAY array.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED	The specified device does not support patch caching.

MMSYSERR_NOMEM	The device does not have enough memory to cache all of the requested patches.

Comments

The PATCHARRAY data type is defined as follows:

typedef WORD PATCHARRAY[MIDIPATCHSIZE];

Each element of the array represents one of the 128 patches and has bits set for each of the 16 MIDI channels that use that particular patch. The least-significant bit represents physical channel 0; 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 only applies to internal MIDI synthesizer devices. Not all internal synthesizers support patch caching. Use the MIDICAPS_CACHE flag to test the dwSupport member of the MIDIOUTCAPS structure filled by the midiOutGetDevCaps function to see if the device supports patch caching.

See Also

midiOutCacheDrumPatches


midiOutClose function
midiOutClose (Win32)

MMRESULT midiOutClose(hMidiOut)

HMIDIOUT hMidiOut;	/* handle of device to close	*/

The midiOutClose function closes the specified Musical Instument Digital Interface (MIDI) output device.

Parameter	Description

hMidiOut	Identifies the MIDI output device. If the function is successful, the handle is no longer valid after the function returns.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the follow:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MIDIERR_STILLPLAYING	There are still buffers in the queue.

Comments

If there are output buffers that have been sent with the midiOutLongMsg function and haven't been returned to the application, the close operation will fail. Call the midiOutReset function to mark all pending buffers as done.

See Also

midiOutOpen, midiOutReset


midiOutGetDevCaps function
midiOutGetDevCaps (Win32)

MMRESULT midiOutGetDevCaps(IDDevice, lpmidioc, cbmidioc)

UINT IDDevice;	/* device identifier to query	*/
LPMIDIOUTCAPS lpmidioc;	/* address of structure for device caps	*/
UINT cbmidioc;	/* size of structure, in bytes	*/

The midiOutGetDevCaps function queries a specified Musical Instument Digital Interface (MIDI) output device to determine its capabilities.

Parameter	Description

IDDevice	Identifies the MIDI output device to query.

lpmidioc	Points to a MIDIOUTCAPS structure that receives information about the capabilities of the device.

cbmidioc	Specifies the size, in bytes, of the MIDIOUTCAPS structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the follow:

Value	Meaning

MMSYSERR_BADDEVICEID	The specified device ID is out of range.

MMSYSERR_NODRIVER	The driver was not installed.

MMSYSERR_NOMEM	The system is unable to load the mapper string description.

Comments

Use the midiOutGetNumDevs function to determine the number of MIDI output devices present in the system. The device identifier specified by IDDevice varies from zero to one less than the number of devices present. The MIDI_MAPPER constant may also be used as a device identifier. Only cbmidioc (or fewer) bytes of information are copied to the location pointed to by lpmidioc. If cbmidioc is zero, nothing is copied, and the function returns zero.

See Also

midiOutGetNumDevs


midiOutGetErrorText function
midiOutGetErrorText (Win32)

MMRESULT midiOutGetErrorText(mmrError, lpszDesc, cchDesc)

MMRESULT mmrError;	/* error code	*/
LPTSTR lpszDesc;	/* address of buffer for description	*/
UINT cchDesc;	/* size of buffer, in characters	*/

The midiOutGetErrorText function retrieves a text description of the specified error.

Parameter	Description

mmrError	Specifies the error number.

lpszDesc	Points to a buffer that will receive the error-description text.

cchDesc	Specifies the length, in characters, of the buffer at lpszDesc.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be MMSYSERR_BADERRNUM, indicating that the specified error number is out of range.

Comments

If the text error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchDesc is zero, nothing is copied, and the function returns MMSYSERR_NOERROR. All error descriptions are less than MAXERRORLENGTH characters long.


midiOutGetID function
midiOutGetID (Win32)

MMRESULT midiOutGetID(hMidiOut, lpIDDevice)

HMIDIOUT hMidiOut;	/* handle of device to return ID for	*/
PUINT lpIDDevice;	/* address of buffer for device ID	*/

The midiOutGetID function retrieves the device identifier for the specified Musical Instument Digital Interface (MIDI) output device.

Parameter	Description

hMidiOut	Identifies the MIDI output device.

lpIDDevice	Points to a variable that will receive the the device identifier.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be MMSYSERR_INVALHANDLE, indicating that the hMidiOut parameter specifies an invalid handle.


midiOutGetNumDevs function
midiOutGetNumDevs (Win32)

UINT midiOutGetNumDevs(VOID)

The midiOutGetNumDevs function retrieves the number of Musical Instument Digital Interface (MIDI) output devices present in the system.

Returns

If the function succeeds, the return value is the number of MIDI output devices present in the system.

See Also

midiOutGetDevCaps


midiOutGetVolume function
midiOutGetVolume (Win32)

MMRESULT midiOutGetVolume(IDDevice, lpdwVolume)

UINT IDDevice;	/* identifier of device to get volume for	*/
LPDWORD lpdwVolume;	/* address of buffer for volume setting	*/

The midiOutGetVolume function returns the current volume setting of a Musical Instument Digital Interface (MIDI) output device.

Parameter	Description

IDDevice	Identifies the MIDI output device.

lpdwVolume	Points to a location 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 settings set with the midiOutSetVolume function is returned, regardless of whether the device supports the full 16 bits of volume-level control.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED	The function is not supported.

MMSYSERR_NODRIVER	The driver was not installed.

Comments

Not all devices support volume control. To determine whether the device supports volume control, use the MIDICAPS_VOLUME flag to test the dwSupport member of the MIDIOUTCAPS structure (filled by the midiOutGetDevCaps function).

To determine whether the device supports volume control on both the left and right channels, use the MIDICAPS_LRVOLUME flag to test the dwSupport member of the MIDIOUTCAPS structure (filled by midiOutGetDevCaps).

See Also

midiOutSetVolume


midiOutLongMsg function
midiOutLongMsg (Win32)

MMRESULT midiOutLongMsg(hMidiOut, lpmidih, cbmidih)

HMIDIOUT hMidiOut;	/* handle of device to send message to	*/
LPMIDIHDR lpmidih;	/* structure with data buffer	*/
UINT cbmidih;	/* size of structure, in bytes	*/

The midiOutLongMsg function sends a system-exclusive Musical Instument Digital Interface (MIDI) message to the specified MIDI output device.

Parameter	Description

hMidiOut	Identifies the MIDI output device.

lpmidih	Points to a MIDIHDR structure that identifies the MIDI data buffer.

cbmidih	Specifies the size, in bytes, of the MIDIHDR structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MIDIERR_UNPREPARED	The lpmidih buffer has not been prepared.

MIDIERR_NOTREADY	The hardware is busy with other data.

Comments

The data buffer must be prepared by using the midiOutPrepareHeader function before it is passed to midiOutLongMsg. The MIDIHDR structure and the data buffer pointed to by its lpData member must be allocated by using the GlobalAlloc function and using the GMEM_MOVEABLE and GMEM_SHARE flags, and must be locked by using the GlobalLock function. The MIDI output device driver determines whether the data is sent synchronously or asynchronously.

See Also

midiOutPrepareHeader, midiOutShortMsg


midiOutMessage function
midiOutMessage (Win32)

MMRESULT midiOutMessage(hMidiOut, uMsg, dwParam1, dwParam2)

HMIDIOUT hMidiOut;	/* handle of device to send message to	*/
UINT uMsg;	/* message	*/
DWORD dwParam1;	/* application-defined parameter	*/
DWORD dwParam2;	/* application-defined parameter	*/

The midiOutMessage function sends a message to a Musical Instument Digital Interface (MIDI) device driver.

Parameter	Description

hMidiOut	Identifies the MIDI device to send a message to.

uMsg	Specifies the message to send.

dwParam1	Application-defined parameter.

dwParam2	Application-defined parameter.

Returns

If the function succeeds, the Return the value is the message sent.


midiOutOpen function
midiOutOpen (Win32)

MMRESULT midiOutOpen(lphMidiOut, IDDevice, dwCallback, dwCallbackInstance, fdwCallback)

LPHMIDIOUT lphMidiOut;	/* variable to receive output device handle	*/
UINT IDDevice;	/* device ID	*/
DWORD dwCallback;	/* address of callback function	*/
DWORD dwCallbackInstance;	/* callback instance data	*/
DWORD fdwCallback;	/* callback type	*/

The midiOutOpen function opens a specified Musical Instument Digital Interface (MIDI) output device for playback.

Parameter	Description

lphMidiOut	Points to a variable that receives a handle identifying the opened MIDI output device. Use the handle of identify the device when calling other MIDI output functions.

IDDevice	Identifies the MIDI output device to be opened.

dwCallback	Specifies the address of a fixed callback function or a handle of a window called with information about incoming MIDI messages. This parameter can be NULL if no callback is required.

For more information about the callback function, see the description of the MidiProc callback function.

dwCallbackInstance	Specifies user instance data passed to the callback function. This parameter is not used with window callbacks.

fdwCallback	Specifies a callback flag for opening the device. This parameter can have one of the following values:

Value	Meaning

CALLBACK_WINDOW	The dwCallback parameter is assumed to be a window handle.

CALLBACK_FUNCTION	The dwCallback parameter is assumed to be a callback procedure address.

CALLBACK_NULL	The dwCallback parameter is assumed to be NULL.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.

MMSYSERR_ALLOCATED	The specified resource is already allocated.

MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

MIDIERR_NOMAP	There is no current MIDI map. This occurs only when opening the mapper.

MIDIERR_NODEVICE	A port in the current MIDI map doesn't exist. This occurs only when opening the mapper.

Comments

Use the midiOutGetNumDevs function to determine the number of MIDI output devices present in the system. The device identifier specified by IDDevice varies from zero to one less than the number of devices present. You can also specify MIDI_MAPPER as the device identifier to open the MIDI mapper.

If a window is chosen to receive callback information, the following messages are sent to the window procedure function to indicate the progress of MIDI output: MM_MOM_OPEN, MM_MOM_CLOSE, 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, MOM_DONE. The callback function must reside in a dynamic-link library (DLL).

See Also

midiOutClose


midiOutPrepareHeader function
midiOutPrepareHeader (Win32)

MMRESULT midiOutPrepareHeader(hMidiOut, lpmidih, cbmidih)

HMIDIOUT hMidiOut;	/* handle of MIDI output device	*/
LPMIDIHDR lpmidih;	/* address of structure for buffer to prepare	*/
UINT cbmidih;	/* size of structure in bytes	*/

The midiInPrepareHeader function prepares a buffer for Musical Instument Digital Interface (MIDI) output.

Parameter	Description

hMidiOut	Identifies the MIDI output device.

lpmidih	Points to a MIDIHDR structure that identifies the buffer to be prepared.

cbmidih	Specifies the size, in bytes, of the MIDIHDR structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

Comments

The MIDIHDR structure and the data block pointed to by its lpData member must be allocated by using the GlobalAlloc function and the GMEM_MOVEABLE and GMEM_SHARE flags and must be locked using the GlobalLock function. Preparing a header that has already been prepared has no effect, and the function returns zero.

See Also

midiOutUnprepareHeader


midiOutReset function
midiOutReset (Win32)

MMRESULT midiOutReset(hMidiOut)

HMIDIOUT hMidiOut;	/* handle of output device to stop	*/

The midiOutReset function turns off all notes on all Musical Instument Digital Interface (MIDI) channels for the specified MIDI output device. Any pending system-exclusive output buffers are marked as done and returned to the application.

Parameter	Description

hMidiOut	Identifies the MIDI output device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be MMSYSERR_INVALHANDLE, indicating that the specified device handle is invalid.

Comments

To turn off all notes, a note-off message for each note for each channel is sent. In addition, the sustain controller is turned off for each channel.

See Also

midiOutClose, midiOutLongMsg


midiOutSetVolume function
midiOutSetVolume (Win32)

MMRESULT midiOutSetVolume(IDDevice, dwVolume)

UINT IDDevice;	/* identifier of MIDI device to set volume for	*/
DWORD dwVolume;	/* new volume setting	*/

The midiOutSetVolume function sets the volume of a Musical Instument Digital Interface (MIDI) output device.

Parameter	Description

IDDevice	Identifies the MIDI output device.

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 the dwVolume parameter specifies the volume level, and the high-order word is ignored.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED	The function isn't supported.

MMSYSERR_NODRIVER	The driver was not installed.

Comments

Not all devices support volume changes. To determine whether the device supports volume control, use the MIDICAPS_VOLUME flag to test the dwSupport member of the MIDIOUTCAPS structure (filled by the midiOutGetDevCaps function).

To determine whether the device supports volume control on both the left and right channels, use the MIDICAPS_LRVOLUME flag to test the dwSupport member of the MIDIOUTCAPS structure (filled by midiOutGetDevCaps).

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 all produce the same physical volume setting, 0x4000. The midiOutGetVolume function will return the full 16-bit setting set with midiOutSetVolume.

Volume settings are interpreted logarithmically. This means the perceived increase in volume is the same from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

See Also

midiOutGetVolume


midiOutShortMsg function
midiOutShortMsg (Win32)

MMRESULT midiOutShortMsg(hMidiOut, dwMsg)

HMIDIOUT hMidiOut;	/* handle of output device to send message to	*/
DWORD dwMsg;	/* message to send	*/

The midiOutShortMsg function sends a short Musical Instument Digital Interface (MIDI) message to the specified MIDI output device. Use this function to send any MIDI message except for system-exclusive messages.

Parameter	Description

hMidiOut	Identifies the MIDI output device.

dwMsg	Specifies the MIDI message. The message is packed into a doubleword with the first byte of the message in the low-order byte.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MIDIERR_NOTREADY	The hardware is busy with other data.

Comments

This function may not return until the message has been sent to the output device.

See Also

midiOutLongMsg


midiOutUnprepareHeader function
midiOutUnprepareHeader (Win32)

MMRESULT midiOutUnprepareHeader(hMidiOut, lpmidih, cbmidih)

HMIDIOUT hMidiOut;	/* handle of the MIDI output device	*/
LPMIDIHDR lpmidih;	/* address of structure for data buffer	*/
UINT cbmidih;	/* size of structure, in bytes	*/

The midiOutUnprepareHeader function cleans up the preparation performed by the midiOutPrepareHeader function. The midiOutUnprepareHeader function must be called after the device driver fills a data buffer and returns it to the application. You must call this function before freeing the data buffer.

Parameter	Description

hMidiOut	Identifies the Musical Instument Digital Interface (MIDI) output device.

lpmidih	Points to a MIDIHDR structure that identifies the data buffer to be cleaned up.

cbmidih	Specifies the size of the MIDIHDR structure in bytes.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MIDIERR_STILLPLAYING	The lpMidiOutHdr buffer is still in the queue.

Comments

This function complements the midiOutPrepareHeader function. You must call this function before freeing the data buffer using the GlobalFree function. After passing a buffer to the device driver by using the midiOutLongMsg function, you must wait until the driver is finished with the buffer before calling midiOutUnprepareHeader.

Unpreparing a buffer that has not been prepared has no effect, and the function returns zero.

See Also

midiOutPrepareHeader


MidiProc function
MidiProc (Win32)

void CALLBACK MidiProc(hMidiIn, uMsg, dwInstance, dwParam1, dwParam2)

HMIDIIN hMidiIn;	/* handle of MIDI device	*/
UINT uMsg;	/* MIDI message	*/
DWORD dwInstance;	/* callback instance data	*/
DWORD dwParam1;	/* application-defined parameter	*/
DWORD dwParam2;	/* application-defined parameter	*/

The MidiProc function is an application-defined callback function that processes Musical Instument Digital Interface (MIDI) device messages. An application can specify the address of this function when it calls the midiInOpen or midiOutOpen function.

Parameter	Description

hMidiIn	Identifies the MIDI device.

uMsg	Specifies a MIDI message.

dwInstance	Specifies the instance data supplied by using the midiInOpen or midiOutOpen function.

dwParam1	Specifies a parameter for the message.

dwParam2	Specifies a parameter for the message.

Returns

This function does not return a value.

Comments

MidiProc is a placeholder for the application-defined function name.

There are several differences between MidiProc functions under Windows NT and under Windows 3.1 :

Under Windows 3.1, a MidiProc function is called at interrupt time. The call to a MidiProc function occurs on a separate thread under Windows NT.

Under Windows 3.1, a MidiProc function has to be in a dynamic link library. Under Windows NT, there is no such restriction.

Under Windows 3.1, a MidiProc function must be exported in a .DEF file. Under Windows NT, that is not necessary.

If source code must be compatible with Windows 3.1, it should follow the Windows 3.1 rules as noted briefly above and specified more fully in the Windows 3.1 documentation.

One other item should be noted carefully. There is a limited set of APIs that a Windows 3.1 MidiProc function may call. In Win32, that strict limitation has been removed. However, it is strongly recommended that a Windows NT MidiProc function restrain its calls to APIs in the same set, with the addition of the API SetEvent. Here is the Windows NT recommended list:

EnterCriticalSection	PostThreadMessage

LeaveCriticalSection	SetEvent

midiOutLongMsg	timeGetSystemTime

midiOutShortMsg	timeGetTime

OutputDebugString	timeKillEvent

PostMessage	timeSetEvent

If an application's MidiProc function does stray from this list, it should be careful not to call APIs that take a long time to complete.

If a Win32 MidiProc shares data with other code, a Critical Section or similar mutual exclusion mechanism should be used to protect the integrity of the data.

See Also

midiInOpen, TimeProc, WaveProc, MMIOProc


mmioAdvance function
mmioAdvance (Win32)

MMRESULT mmioAdvance(hmmio, lpmmioinfo, fuOperation)

HMMIO hmmio;	/* file handle	*/
LPMMIOINFO lpmmioinfo;	/* address of structure for file operation	*/
UINT fuOperation;	/* specifies operation	*/

The mmioAdvance function advances the input/output (I/O) buffer of a file set up for direct I/O buffer access with the mmioGetInfo function. 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.

Parameter	Description

hmmio	Identifies the file. This handle is returned by the mmioOpen function.

lpmmioinfo	Points to an MMIOINFO structure obtained with mmioGetInfo. The structure is used to set the current file information, then updated after the buffer is advanced.

fuOperation	Specifies the operation to perform. This parameter must be one of the following values:

Value	Meaning

MMIO_READ	The buffer is filled from the file.

MMIO_WRITE	The buffer is written to the file.

Returns

If the function is succeeds, the return value is zero; otherwise, it is an error code than can be one of the following:

Value	Meaning

MMIOERR_CANNOTWRITE	The contents of the buffer could not be written to disk.

MMIOERR_CANNOTREAD	An error occurred while re-filling the buffer.

MMIOERR_UNBUFFERED	The specified file is not opened for buffered I/O.

MMIOERR_CANNOTEXPAND	The specified memory file cannot be expanded, probably because the adwInfo[0] member was set to zero in the initial call to the mmioOpen function.

MMIOERR_OUTOFMEMORY	There was not enough memory to expand a memory file for further writing.

Comments

The mmioAdvance function advances the buffer by (pchNext - pchBuffer) bytes. All data in the buffer before pchNext is assumed to have already been read, while all data from pchNext to pchEndRead will be considered unread. So, when mmioAdvance is called, all data before pchNext will be overwritten. The buffer must not be treated as an array and pchNext must be incremented until pchNext equals pchEndRead.

If the specified file is opened for writing or for both reading and writing, the I/O buffer will be flushed to disk before the next buffer is read. If the I/O buffer cannot be written to disk because the disk is full, then mmioAdvance will return MMIOERR_CANNOTWRITE.

If the specified file is only open 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 will still return successfully, even though no more data can be read. Thus, to check for the end of the file, it is necessary to see if the pchNext and pchEndRead members of the MMIOINFO structure are equal after calling mmioAdvance.

See Also

mmioGetInfo


mmioAscend function
mmioAscend (Win32)

MMRESULT mmioAscend(hmmio, lpmmcki, uReserved)

HMMIO hmmio;	/* handle of RIFF file	*/
LPMMCKINFO lpmmcki;	/* address of chunk information structure	*/
UINT uReserved;	/* reserved; must be zero	*/

The mmioAscend function ascends out of a chunk in a RIFF file descended into by using the mmioDescend function or created using the mmioCreateChunk function.

Parameter	Description

hmmio	Identifies an open RIFF file.

lpmmcki	Points to a MMCKINFO structure previously filled by mmioDescend or mmioCreateChunk.

uReserved	Reserved. Must be zero.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code than can be one of the following:

Value	Meaning

MMIOERR_CANNOTWRITE	The contents of the buffer could not be written to disk.

MMIOERR_CANNOTSEEK	There was an error while seeking to the end of the chunk.

Comments

If the chunk was descended into using the mmioDescend function, then the mmioAscend function 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 using the mmioCreateChunk function, or if the MMIO_DIRTY flag is set in the dwFlags member of the MMCKINFO structure referenced by lpmmcki, then 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 when mmioCreateChunk was called, then 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


mmioClose function
mmioClose (Win32)

MMRESULT mmioClose(hmmio, fuOption)

HMMIO hmmio;	/* handle of file to close	*/
UINT fuOption;	/* specifies optional operation	*/

The mmioClose function closes a file opened by using the mmioOpen function.

Parameter	Description

hmmio	Indentifies the file to close.

fuOption	Specifies options for the close operation.

Value	Meaning

MMIO_FHOPEN	If the file was opened by passing the Windows file handle of an already-opened file to mmioOpen, then using this flag tells mmioClose to close the MMIO file handle, but not the Windows file handle. (This is done by the I/O Proc).

Returns

The return value is zero if the function is successful. Otherwise, the return value is an error code either from the mmioFlush function or from the I/O procedure. The error code can be one of the following:

Value	Meaning

MMIOERR_CANNOTWRITE	The contents of the buffer could not be written to disk.

MMIOERR_CANNOTCLOSE	There was a Windows file system error when the I/O Proc attempted to close the Windows file.

See Also

mmioOpen, mmioFlush


mmioCreateChunk function
mmioCreateChunk (Win32)

MMRESULT mmioCreateChunk(hmmio, lpmmcki, fuOptions)

HMMIO hmmio;	/* identifies file	*/
LPMMCKINFO lpmmcki;	/* address of chunk information structure	*/
UINT fuOptions;	/* chunk creation options	*/

The mmioCreateChunk function creates a chunk in a RIFF file opened with 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.

Parameter	Description

hmmio	Identifies an open RIFF file.

lpmmcki	Points to a caller-supplied MMCKINFO structure that contains information about the chunk to be created. For information about how the MMCKINFO structure should be set up, see the Comments section.

fuOptions	Specifies flags to optionally create either a "RIFF" chunk or a "LIST" chunk. Can contain one of the following flags:

Value	Meaning

MMIO_CREATERIFF	Creates a "RIFF" chunk.

MMIO_CREATELIST	Creates a "LIST" chunk.

Returns

If the function is succeeds, the return value is zero; otherwise, it is an error code than can be one of the following:

Value	Meaning

MMIOERR_CANNOTWRITE	Unable to write the chunk header.

MMIOERR_CANNOTSEEK	Unable to determine offset of data portion of the chunk.

Comments

The MMCKINFO structure pointed to lpmmcki should be set up as follows:

The ckid member specifies the chunk identifier of the chunk. If fuOptions 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, them mmioAscend will correct 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 need not be filled in.

The dwDataOffset member need not be filled in. The mmioCreateChunk function will fill this member with the file offset of the data portion of the chunk.

The dwFlags member need not be filled in. The mmioCreateChunk function will set the MMIO_DIRTY flag in dwFlags.

This function cannot insert a chunk into the middle of a file. If a chunk is created anywhere but the end of a file, mmioCreateChunk will overwrite existing information in the file.


mmioDescend function
mmioDescend (Win32)

MMRESULT mmioDescend(hmmio, lpmmcki, lpmmckiParent, fuSearch)

HMMIO hmmio;	/* handle of open RIFF file	*/
LPMMCKINFO lpmmcki;	/* address of chunk information structure	*/
LPMMCKINFO lpmmckiParent;	/* address of optional parent structure	*/
UINT fuSearch;	/* search-option flags	*/

The mmioDescend function descends into a chunk of a RIFF file opened by using the mmioOpen function. It can also search for a given chunk.

Parameter	Description

hmmio	Identifies an open RIFF file.

lpmmcki	Points to an MMCKINFO structure that mmioDescend fills with the following information:

The ckid member is the chunk identifier of the chunk.

The cksize member is the size of the data portion of the chunk. The data 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, then dwDataOffset 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.

If the MMIO_FINDCHUNK, MMIO_FINDRIFF, or MMIO_FINDLIST flag is specified for fuSearch, then the MMCKINFO structure is also used to pass parameters to mmioDescend.

The ckid member specifies the four-character code of the chunk identifier, form type, or list type to search for.

lpmmckiParent	Points to an MMCKINFO structure identifying the parent of the chunk being searched for. A parent of a chunk is the enclosing chunk--only "RIFF" and "LIST" chunks can be parents. If lpmmckiParent is not NULL, then mmioDescend assumes the MMCKINFO structure it refers to was filled when mmioDescend was called to descend into the parent chunk, and mmioDescend will only search for a chunk within lpmmckiParent.

If lpmmckiParent is NULL, no parent chunk is being specified.

fuSearch	Specifies search options. Contains up to one of the following flags. If no flags are specified, mmioDescend descends into the chunk beginning at the current file position.

Value	Meaning

MMIO_FINDCHUNK	Searches for a chunk with the specified chunk identifier.

MMIO_FINDRIFF	Searches for a chunk with chunk identifier "RIFF" and with the specified form type.

MMIO_FINDLIST	Searches for a chunk with chunk identifier "LIST" and with the specified form type.

Returns

The return value is zero if the function succeeds. Otherwise, the return value specifies an error code. If the end of the file (or the end of the parent chunk, if given) is reached before the desired chunk is found, the return value is MMIOERR_CHUNKNOTFOUND. Other error return values are possible, for instance MMIOERR_CANNOTSEEK.

Comments

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 mmioDescend is used to search for a chunk, the file position should be at the beginning of a chunk before calling mmioDescend. 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).

For efficient RIFF file input/output (I/O), use buffered I/O.

See Also

mmioAscend


mmioFlush function
mmioFlush (Win32)

MMRESULT mmioFlush(hmmio, uReserved)

HMMIO hmmio;	/* handle of file to flush to	*/
UINT uReserved;	/* reserved; must be zero	*/

The mmioFlush function writes the input/output (I/O) buffer of a file to disk, if the I/O buffer has been written to.

Parameter	Description

hmmio	Identifies a file opened by using the mmioOpen function.

uReserved	Reserved. Must be zero.

Returns

If the function is succeeds, the return value is zero; otherwise, it is an error code than can be MMIOERR_CANNOTWRITE, indicating that the contents of the buffer could not be written to disk.

Comments

Closing a file by using the mmioClose function will automatically flush the file's buffer.

If there is insufficient disk space to write the buffer, mmioFlush will fail, even if the preceding calls to the mmioWrite function were successful.


mmioFOURCC function
mmioFOURCC (Win32)

FOURCC mmioFOURCC(ch0, ch1, ch2, ch3)

CHAR ch0;	/* character one	*/
CHAR ch1;	/* character two	*/
CHAR ch2;	/* character three	*/
CHAR ch3;	/* character four	*/

This macro converts four characters to a four-character code.

Parameter	Description

ch0	The first character of the four-character code.

ch1	The second character of the four-character code.

ch2	The third character of the four-character code.

ch3	The fourth character of the four-character code.

Returns

The return value is the four-character code created from the given characters.

Comments

This macro does not check to see if the four character code follows any conventions regarding which characters to include in a four-character code.

See Also

mmioStringToFOURCC


mmioGetInfo function
mmioGetInfo (Win32)

MMRESULT mmioGetInfo(hmmio, lpmmioi, uReserved)

HMMIO hmmio;	/* handle of file to get information for	*/
LPMMIOINFO lpmmioi;	/* address of structure for file information	*/
UINT uReserved;	/* reserved; must be zero	*/

The mmioGetInfo function retrieves information about a file opened by using the mmioOpen function. This information allows the caller to access the input/output (I/O) buffer directly, if the file is open for buffered I/O.

Parameter	Description

hmmio	Identifies the file.

lpmmioi	Points to an MMIOINFO structure that receives information about the file.

uReserved	Reserved. Must be zero.

Returns

The return value is zero if the function is successful.

Comments

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 one byte past the last valid byte in the buffer that can be read.

The pchEndWrite member points to one byte past the last location in the buffer that can be written.

Once you read or write to the buffer and modify pchNext, do not call any MMIO function 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 pchEndRead or pchEndWrite, call the mmioAdvance function to fill the buffer from the disk, or write the buffer to the disk. The mmioAdvance function will update 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

mmioSetInfo


mmioInstallIOProc function
mmioInstallIOProc (Win32)

LPMMIOPROC mmioInstallIOProc(fccProc, lpmmioproc, fdwInstall)

FOURCC fccProc;	/* four-character code for procedure	*/
LPMMIOPROC lpmmioproc;	/* address of procedure to install	*/
DWORD fdwInstall;	/* install option flags	*/

The mmioInstallIOProc function installs or removes a custom I/O procedure. It will also locate an installed I/O procedure, given its corresponding four-character code.

Parameter	Description

fccProc	Specifies a four-character code identifying the I/O procedure to install, remove, or locate. All characters in this four-character code should be uppercase characters.

lpmmioproc	Points to 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 the description of the MMIOProc function.

fdwInstall	Specifies one of the following flags indicating whether the I/O procedure is being installed, removed, or located:

Value	Meaning

MMIO_INSTALLPROC	Installs the specified I/O procedure.

MMIO_GLOBALPROC	This flag only exists for Windows 3.1 compatibility. It is ignored under Windows NT. Under Windows 3.1, it is a modifier to the install flag, and indicates that the I/O procedure should be installed for global use. Windows NT, because of security needs, does not allow global I/O procedures.

MMIO_REMOVEPROC	Removes the specified I/O procedure.

MMIO_FINDPROC	Searches for the specified I/O procedure.

Returns

The return value is the address of the I/O procedure installed, removed, or located. If there is an error, the return value is NULL.

See Also

mmioOpen, MMIOProc


mmioOpen function
mmioOpen (Win32)

HMMIO mmioOpen(lpszFilename, lpmmioinfo, fdwOpen)

LPTSTR lpszFilename;	/* specifies name of file to open	*/
LPMMIOINFO lpmmioinfo;	/* address of structure for file information	*/
DWORD fdwOpen;	/* open option flags	*/

The mmioOpen function opens a file for unbuffered or buffered input/output (I/O). The file can be a Windows-based file, a memory file, or an element of a custom storage system.

Parameter	Description

lpszFilename	Points to a null-terminated string that specifies the name of the file to open. If no I/O procedure is specified to open the file, then the filename determines how the file is opened, as follows:

If the filename does not contain "+", then it is assumed to be the name of a Windows file.

If the filename is of the form "foo.ext+bar" the extension EXT is assumed to identify an installed I/O procedure that is called to perform I/O on the file (see the description of the mmioInstallIOProc function).

If lpszFilename is NULL and no I/O procedure is given, then adwInfo[0] is assumed to be the file handle of a currently open Windows-based file.

When opening a memory file, set lpszFilename to NULL.

lpmmioinfo	Points to 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 lpmmioinfo is not NULL, all unused members of the MMIOINFO structure it references must be set to zero, including the reserved members.

fdwOpen	Specifies option flags for the open operation. The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are mutually exclusive--only one should be specified.

Value	Meaning

MMIO_READ	Opens the file for reading only. This is the default if MMIO_WRITE and MMIO_READWRITE are not specified.

MMIO_WRITE	Opens the file for writing. Do not read from a file opened in this mode.

MMIO_READWRITE	Opens the file for both reading and writing.

MMIO_CREATE	Creates a new file. If the file already exists, it is truncated to zero length. For memory files, MMIO_CREATE indicates the end of the file is initially at the start of the buffer.

MMIO_DELETE	Deletes a file. If this flag is specified, lpszFilename should not be NULL. The return value will be TRUE (cast to HMMIO) if the file was deleted successfully, FALSE otherwise. Do not call the mmioClose function for a file that has been deleted. If this flag is specified, all other file-opening flags are ignored.

MMIO_PARSE	Creates a fully qualified filename from the path specified in lpszFileName. The fully qualified filename is placed back into lpszFileName. The return value will be TRUE (cast to HMMIO) if the qualification was successful, FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file. If this flag is specified, all other file opening flags are ignored.

MMIO_EXIST	Determines whether the specified file exists and creates a fully qualified filename from the path specified in lpszFileName. The fully qualified filename is placed back into lpszFileName. The return value will be TRUE (cast to HMMIO) if the qualification was successful and the file exists, FALSE otherwise. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file.

MMIO_ALLOCBUF	Opens a file for buffered I/O. To allocate a buffer larger or smaller than the default buffer size (8K), set the cchBuffer member of the MMIOINFO structure to the desired buffer size. If cchBuffer is zero, then the default buffer size is used. If you are providing your own I/O buffer, the MMIO_ALLOCBUF 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. mmioOpen fails if the file has been opened with any of the other sharing modes.

MMIO_EXCLUSIVE	Opens the file with exclusive mode, denying other processes both read and write access to the file. mmioOpen fails if the file has been opened in any other mode for read or write access, even by the current process.

MMIO_DENYWRITE	Opens the file and denies other processes write access to the file. mmioOpen fails if the file has been opened in compatibility or for write access by any other process.

MMIO_DENYREAD	Opens the file and denies other processes read access to the file. mmioOpen fails if the file has been opened in compatibility mode or for read access by any other process.

MMIO_DENYNONE	Opens the file without denying other processes read or write access to the file. mmioOpen fails if the file has been opened in compatibility mode by any other process.

MMIO_GETTEMP	Creates a temporary filename and places the name in the buffer pointed to by lpszFileName. The filename is hard-coded into the mmioOpen function. The return value is TRUE (cast to HMMIO) if the temporary filename is created successfully; otherwise, it is FALSE. The file is not opened, and the function does not return a valid MMIO file handle, so do not attempt to close the file. This flag overrides all other flags.

Returns

The return value is a handle of the opened file. This handle is an MMIO file handle--do not use it with any file I/O functions other than MMIO functions.

If the file cannot be opened, the return value is NULL. If lpmmioinfo is not NULL, then its wErrorRet member will contain extended error information returned by the I/O procedure.

Comments

You must call the mmioClose function to close a file opened with mmioOpen. Open files are not automatically closed when an application exits.

If lpmmioinfo references an MMIOINFO structure, set up the members 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 the fccIOProc member to the four-character code of the I/O procedure,and set the pIOProc member to NULL.

To request that a file be opened with an uninstalled I/O procedure, set the pIOProc member 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 lpszFilename, set both 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 the pchBuffer member to NULL, fccIOProc to FOURCC_MEM, cchBuffer to the initial size of the buffer, and adwInfo[0] to the incremental expansion size of the buffer. This memory file will automatically be expanded in increments of adwInfo[0] bytes when necessary. Specify the MMIO_CREATE flag for the fdwOpen parameter to initially set the end of the file to be the beginning of the buffer.

To open a memory file using a caller-supplied buffer, set the pchBuffer member to point to the memory buffer, fccIOProc to FOURCC_MEM, cchBuffer to the size of the buffer, and adwInfo[0] to the incremental expansion size of the buffer. The expansion size in adwInfo[0] should only be nonzero if pchBuffer is a pointer obtained by calling the GlobalAlloc and GlobalLock functions, since the GlobalReAlloc function will be called to expand the buffer. In particular, if pchBuffer points to a local or global array, a block of memory in the local heap, or a block of memory allocated by the GlobalDosAlloc function, adwInfo[0] must be zero. Specify the MMIO_CREATE flag for the fdwOpen parameter to initially set the end of the file to be the beginning of the buffer; otherwise, the entire block of memory will be considered readable.

To use a currently open Windows-based file handle with MMIO, set the fccIOProc member to FOURCC_DOS, pchBuffer to NULL, and adwInfo[0] to the Windows file handle. Note that offsets within the file will be relative to the beginning of the file, and will not depend on the Wfile position at the time mmioOpen is called; the initial MMIO offset will be the same as the Windows-based offset when mmioOpen is called. Later, to close the MMIO file handle without closing the Windows-based file handle, pass the MMIO_FHOPEN flag to the mmioClose function.

See Also

mmioClose


MMIOProc function
MMIOProc (Win32)

LRESULT CALLBACK MMIOProc(lpmmioinfo, uMsg, lParam1, lParam2)

LPSTR lpmmioinfo;	/* address of structure with file information	*/
UINT uMsg;	/* specifies sent message	*/
LONG lParam1;	/* application-defined parameter	*/
LONG lParam2;	/* application-defined parameter	*/

An MMIOProc function is a custom input/output (I/O) procedure installed by the mmioInstallIOProc function. It is application-defined, and of type MMIOPROC.

Parameter	Description

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_RENAME, 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.

Returns

The return value depends on the message specified by uMsg. If the I/O procedure does not recognize a message, it should return zero.

Comments

MMIOProc is a placeholder for the application-defined function name.

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 however 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

mmioInstallIOProc


mmioRead function
mmioRead (Win32)

LRESULT mmioRead(hmmio, pb, cbRead)

HMMIO hmmio;	/* handle of file to read from	*/
LPSTR pb;	/* address of buffer for read bytes	*/
LONG cbRead;	/* number of bytes to read	*/

The mmioRead function reads a specified number of bytes from a file opened by using the mmioOpen function.

Parameter	Description

hmmio	Identifies the file to be read.

pb	Points to the buffer that receives the data read from the file.

cbRead	Specifies the number of bytes to read from the file.

Returns

The return value is 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 zero. If there is an error reading from the file, the return value is -1.

See Also

mmioWrite


mmioRename function
mmioRename (Win32)

MMRESULT mmioRename(lpszOldName, lpszNewName, lpmmioinfo, dwReserved)

LPCTSTR lpszOldName;	/* address of old filename	*/
LPCTSTR lpszNewName;	/* address of new filename	*/
LPMMIOINFO lpmmioinfo;	/* address of structure with additional info	*/
DWORD dwReserved;	/* reserved; must be zero	*/

The mmioRename function renames the specified file.

Parameter	Description

lpszOldName	Points to a null-terminated string that specifies the name of the file to rename.

lpszNewName	Points to a null-terminated string that specifies the new name for the file.

lpmmioinfo	Points to an MMIOINFO structure containing extra parameters used by mmioRename.

If lpmmioinfo is not NULL, all unused members of the MMIOINFO structure it references must be set to zero, including the reserved members.

dwReserved	Reserved. Must be zero.

Returns

The return value is zero if the file was renamed. Otherwise, the return value is an error code returned by the mmioRename function or from the I/O procedure.


mmioSeek function
mmioSeek (Win32)

LRESULT mmioSeek(hmmio, lOffset, nOrigin)

HMMIO hmmio;	/* handle of file to seek in	*/
LONG lOffset;	/* specifies change in file position	*/
int nOrigin;	/* specifies how to change file position	*/

The mmioSeek function changes the current file position in a file opened by using the mmioOpen function. The current file position is the location in the file where data is read or written.

Parameter	Description

hmmio	Identifies the file to seek in.

lOffset	Specifies an offset to change the file position.

nOrigin	Specifies how the offset specified by lOffset is interpreted. Contains one of the following flags:

Value	Meaning

SEEK_SET	Seeks to lOffset bytes from the beginning of the file.

SEEK_CUR	Seeks to lOffset bytes from the current file position.

SEEK_END	Seeks to lOffset bytes from the end of the file.

Returns

The return value is the new file position in bytes, relative to the beginning of the file. If there is an error, the return value is -1.

Comments

Seeking to an invalid location in the file, such as past the end of the file, may not cause mmioSeek to return an error but may cause subsequent I/O operations on the file to fail.

To seek to the beginning a file, call mmioSeek with lOffset set to zero and nOrigin set to SEEK_SET.

To locate the end of a file, call mmioSeek with lOffset set to zero and nOrigin set to SEEK_END.


mmioSendMessage function
mmioSendMessage (Win32)

LRESULT mmioSendMessage(hmmio, uMsg, lParam1, lParam2)

HMMIO hmmio;	/* handle of file associated with I/O procedure	*/
UINT uMsg;	/* message to send	*/
LONG lParam1;	/* application-defined parameter	*/
LONG lParam2;	/* application-defined parameter	*/

The mmioSendMessage function sends a message to the input/output (I/O) procedure associated with the specified file.

Parameter	Description

hmmio	Identifies a file opened by using the mmioOpen function.

uMsg	Specifies the message to send to the I/O procedure.

lParam1	Specifies an application-defined parameter for the message.

lParam2	Specifies an application-defined parameter for the message.

Returns

The return value depends on the message. If the I/O procedure does not recognize the message, the return value is zero.

Comments

Use this function to send custom user-defined messages. Do not use it to send the following messages:

MMIOM_OPEN

MMIOM_CLOSE

MMIOM_READ

MMIOM_RENAME

MMIOM_SEEK

MMIOM_WRITE

MMIOM_WRITEFLUSH

Define custom messages to be greater than or equal to the MMIOM_USER constant.

See Also

mmioInstallIOProc


mmioSetBuffer function
mmioSetBuffer (Win32)

MMRESULT mmioSetBuffer(hmmio, pbBuffer, cbBuffer, uReserved)

HMMIO hmmio;	/* handle of file to set buffer for	*/
LPSTR pbBuffer;	/* address of buffer	*/
LONG cbBuffer;	/* size of buffer	*/
UINT uReserved;	/* reserved; must be zero	*/

The mmioSetBuffer function enables or disables buffered input/output (I/O), or changes the buffer or buffer size for a file opened by using the mmioOpen function.

Parameter	Description

hmmio	Identifies the file.

pbBuffer	Points to a buffer. If this parameter is NULL, mmioSetBuffer allocates an internal buffer.

cbBuffer	Specifies the size of the buffer, or the size of the buffer to allocate if pbBuffer is NULL.

uReserved	Reserved. Must be zero.

Returns

If the function is succeeds, the return value is zero; otherwise, it is an error code than can be one of the following:

Value	Meaning

MMIOERR_CANNOTWRITE	The contents of the old buffer could not be written to disk, so the operation was not completed.

MMIOERR_OUTOFMEMORY	The new buffer could not be allocated, probably due to a lack of available memory.

If an error occurs, the file handle remains valid.

Comments

To enable buffering using an internal buffer, set pbBuffer to NULL and cbBuffer to the desired buffer size.

To supply your own buffer, set pbBuffer to point to the buffer,and set cbBuffer to the size of the buffer.

To disable buffered I/O, set pbBuffer to NULL and cbBuffer to zero.

If buffered I/O is already enabled using an internal buffer, you can reallocate the buffer to a different size by setting pbBuffer to NULL and cbBuffer to the new buffer size. The contents of the buffer may be changed after resizing.


mmioSetInfo function
mmioSetInfo (Win32)

MMRESULT mmioSetInfo(hmmio, lpmmioinfo, uReserved)

HMMIO hmmio;	/* handle of the file to set	*/
LPMMIOINFO lpmmioinfo;	/* address of file-information structure	*/
UINT uReserved;	/* reserved; must be zero	*/

The mmioSetInfo function updates the information retrieved by mmioGetInfo about a file opened with mmioOpen. Use this function to terminate direct buffer access of a file opened for buffered input/output (I/O).

Parameter	Description

hmmio	Identifies the file.

lpmmioinfo	Points to an MMIOINFO structure filled with information with mmioGetInfo.

uReserved	Reserved. Must be zero.

Returns

The return value is zero if the function is successful.

Comments

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 be flushed to disk.

See Also

mmioGetInfo


mmioStringToFOURCC function
mmioStringToFOURCC (Win32)

FOURCC mmioStringToFOURCC(lpsz, fuOptions)

LPCTSTR lpsz;	/* address of string to convert	*/
UINT fuOptions;	/* options flags	*/

The mmioStringToFOURCC function converts a null-terminated string to a four-character code.

Parameter	Description

lpsz	Points to a null-terminated string to convert to a four-character code.

fuOptions	Specifies options for the conversion.

Value	Meaning

MMIO_TOUPPER	Convert all characters to uppercase.

Returns

The return value is the four character code created from the given string.

Comments

This function does not check to see if the string referenced by lpsz follows any conventions regarding which characters to include in a four-character code. The string is simply copied to a four-character code and padded with blanks or truncated to four characters if required.

See Also

mmioFOURCC


mmioWrite function
mmioWrite (Win32)

LRESULT mmioWrite(hmmio, pb, cbWrite)

HMMIO hmmio;	/* identifies file to write to	*/
LPSTR pb;	/* address of data to write	*/
LONG cbWrite;	/* number of bytes to write	*/

The mmioWrite function writes a specified number of bytes to a file opened by using the mmioOpen function.

Parameter	Description

hmmio	Identifies the file.

pb	Points to the data to be written to the file.

cbWrite	Specifies the number of bytes to write to the file.

Returns

The return value is the number of bytes actually written. If there is an error writing to the file, the return value is -1.

Comments

The current file position is incremented by the number of bytes written.

See Also

mmioRead


mmsystemGetVersion function
mmsystemGetVersion (Win32)

UINT mmsystemGetVersion(VOID)

The mmsystemGetVersion function returns the current version number of the Multimedia extensions system software.

Returns

The low-order word of the return value specifies the major and minor version numbers of the Multimedia extensions. The high-order byte specifies the major version number. The low-order byte specifies the minor version number.


sndPlaySound function
sndPlaySound (Win32)

BOOL sndPlaySound(lpszSoundName, fuOptions)

LPCTSTR lpszSoundName;	/* name of sound to play	*/
UINT fuOptions;	/* options flags	*/

The sndPlaySound function plays a waveform sound specified by a filename or by an entry in the [sounds] section of the registry. If the sound can not be found, the function plays the default sound specified by the SystemDefault entry in the [sounds] section of the registry. If there is no SystemDefault entry or if the default sound can't be found, the function makes no sound and returns FALSE.

Parameter	Description

lpszSoundName	Specifies the name of the sound to play. The function searches the [sounds] section of the registry for an entry with this name and plays the associated waveform file. If no entry by this name exists, the function assumes the name is the name of a waveform file. If this parameter is NULL, any currently playing sound is stopped.

fuOptions	Specifies options for playing the sound. This value can be one or more of the following flags:

Value	Meaning

SND_SYNC	The sound is played synchronously, and the function does not return until the sound ends.

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 the lpszSoundName parameter set to NULL.

SND_NODEFAULT	If the sound can not be found, the function returns silently without playing the default sound.

SND_MEMORY	The parameter specified by lpszSoundName points to an in-memory image of a waveform sound.

SND_LOOP	The sound continues to play 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_NOSTOP	If a sound is currently playing, the function immediately returns FALSE without playing the requested sound.

Returns

If the sound is played, the return value is TRUE; otherwise it is FALSE.

Comments

The sound must fit in available physical memory and be playable by an installed waveform audio device driver. The directories searched for sound files are, in order, the current directory, the Windows directory, the Windows system directory, the directories listed in the PATH environment variable, and the directories mapped in a network. See the Win32 OpenFile function for more information about the directory search order.

If you specify the SND_MEMORY flag, the lpszSoundName parameter must point to an in-memory image of a waveform sound. If the sound is stored as a resource, use the LoadResource and LockResource functions to load and lock the resource and get a pointer to it. If the sound is not a resource, use the GlobalAlloc function with the GMEM_MOVEABLE flag set to allocate memory for the sound, and the GlobalLock function to lock the memory.

See Also

MessageBeep, PlaySound


timeBeginPeriod function
timeBeginPeriod (Win32)

MMRESULT timeBeginPeriod(cMilliseconds)

UINT cMilliseconds;	/* new minimum timer period in milliseconds	*/

The timeBeginPeriod function sets the minimum (lowest number of milliseconds) timer resolution that an application or driver will use. Call this function immediately before starting to use timer-event services, and call the timeEndPeriod function immediately after finishing with the timer-event services.

Parameter	Description

cMilliseconds	Specifies the minimum timer-event resolution, in milliseconds, that the application or driver will use.

Returns

If the function succeeds, the return value is zero. If the resolution value specified in the cMilliseconds parameter is out of range, the return value is TIMERR_NOCANDO.

Comments

For each call to the timeBeginPeriod function, you must call the timeEndPeriod function with a matching cMilliseconds value. An application or driver can make multiple calls to timeBeginPeriod, as long as each timeBeginPeriod call is matched with a timeEndPeriod call.

See Also

timeEndPeriod, timeSetEvent


timeEndPeriod function
timeEndPeriod (Win32)

MMRESULT timeEndPeriod(cMilliseconds)

UINT cMilliseconds;	/* old timer period in milliseconds	*/

The timeEndPeriod function clears a previously set minimum (lowest number of milliseconds) timer resolution that an application or driver will use. Call this function immediately after using timer event services.

Parameter	Description

cMilliseconds	Specifies the minimum timer-event resolution value specified in the previous call to the timeBeginPeriod function.

Returns

If the function succeeds, the return value is zero. If the resolution value specified in the cMilliseconds parameter is out of range, the return value is TIMERR_NOCANDO.

Comments

For each call to the timeBeginPeriod function, you must call the timeEndPeriod function with a matching cMilliseconds value. An application or driver can make multiple calls to timeBeginPeriod, as long as each timeBeginPeriod call is matched with a timeEndPeriod call.

See Also

timeBeginPeriod, timeSetEvent


timeGetDevCaps function
timeGetDevCaps (Win32)

MMRESULT timeGetDevCaps(lptc, cbtc)

LPTIMECAPS lptc;	/* address of structure for returned capabilities	*/
UINT cbtc;	/* size of structure in bytes	*/

The timeGetDevCaps function queries the timer device to determine its capabilities.

Parameter	Description

lptc	Points to a TIMECAPS structure that receives information about the capabilities of the timer device.

cbtc	Specifies the size, in bytes, of the TIMECAPS structure.

Returns

If the function succeeds, the return value is zero. If the function fails to return the timer device capabilities, the return value is TIMERR_NOCANDO.


timeGetSystemTime function
timeGetSystemTime (Win32)

MMRESULT timeGetSystemTime(lpmmt, cbmmt)

LPMMTIME lpmmt;	/* address of structure for returned time	*/
UINT cbmmt;	/* size of structure in bytes	*/

The timeGetSystemTime function retrieves the number of milliseconds elapsed since Windows was started.

Parameter	Description

lpmmt	Points to an MMTIME structure that receives the time.

cbmmt	Specifies the size, in bytes, of the MMTIME structure.

Returns

The return value is zero, and the ms member of the MMTIME structure contains the number of milliseconds elapsed since Windows was started.

Comments

The only difference between this function and the timeGetTime function is that this function uses the standard multimedia time structure MMTIME to return time. The timeGetTime function has less overhead than timeGetSystemTime.

See Also

timeGetTime


timeGetTime function
timeGetTime (Win32)

DWORD timeGetTime(VOID)

The timeGetTime function returns the number of milliseconds elapsed since Windows was started.

Returns

The return value is the number of milliseconds elapsed since Windows was started.

Comments

The only difference between this function and the timeGetSystemTime function is that timeGetSystemTime uses the standard multimedia time structure MMTIME to return time. The timeGetTime function has less overhead than timeGetSystemTime.

See Also

timeGetSystemTime


timeKillEvent function
timeKillEvent (Win32)

MMRESULT timeKillEvent(IDEvent)

UINT IDEvent;	/* identifies event to be destroyed	*/

The timeKillEvent function destroys a specified timer callback event.

Parameter	Description

IDEvent	Identifies the event to be destroyed.

Returns

If the function succeeds, the return value is zero. If the specified timer event does not exist, the return value is TIMERR_NOCANDO.

Comments

The timer-event identifier specified by IDEvent must be an identifier returned by timeSetEvent.

See Also

timeSetEvent


TimeProc function
TimeProc (Win32)

void CALLBACK TimeProc(IDEvent, uReserved, dwUser, dwReserved1, dwReserved2)

UINT IDEvent;	/* identifies timer event	*/
UINT uReserved;	/* not used	*/
DWORD dwUser;	/* application-defined instance data	*/
DWORD dwReserved1;	/* not used	*/
DWORD dwReserved2;	/* not used	*/

The TimeProc function is an application-defined callback function that may be called once or periodically upon the occurence of a timer event, depending upon parameters sent to the timeSetEvent function.

messages.

Parameter	Description

IDEvent	The identifier of the timer event. This is the identifier returned by timeSetEvent.

uReserved	Not used.

dwUser	User instance data supplied to the dwUser parameter of timeSetEvent.

dwReserved1	Not used.

dwReserved2	Not used.

Comments

TimeProc is a placeholder for an application-defined function name.

There are several differences between TimeProc functions under Windows NT and under Windows 3.1 :

Under Windows 3.1, a TimeProc function is called at interrupt time. The call to a TimeProc function occurs on a separate thread under Windows NT.

Under Windows 3.1, a TimeProc function has to be in a dynamic link library. Under Windows NT, there is no such restriction.

Under Windows 3.1, a TimeProc function must be exported in a .DEF file. Under Windows NT, that is not necessary.

If source code must be compatible with Windows 3.1, it should follow the Windows 3.1 rules as noted briefly above and specified more fully in the Windows 3.1 documentation.

One other item should be noted carefully. There is a limited set of APIs that a Windows 3.1 TimeProc function may call. In Win32, that strict limitation has been removed. However, it is strongly recommended that a Windows NT TimeProc function restrain its calls to APIs in the same set, with the addition of the API SetEvent. Here is the Windows NT recommended list:

EnterCriticalSection	PostThreadMessage

LeaveCriticalSection	SetEvent

midiOutLongMsg	timeGetSystemTime

midiOutShortMsg	timeGetTime

OutputDebugString	timeKillEvent

PostMessage	timeSetEvent

If an application's TimeProc function does stray from this list, it should be careful not to call APIs that take a long time to complete. Calls to such functions may interfere with other uses of the timeXXX APIs because TimeProcs are all called from the same thread within a given Process.

If a Win32 TimeProc shares data with other code, a Critical Section or similar mutual exclusion mechanism should be used to protect the integrity of the data. This Critical Section should not be held when calling timeKillEvent, or a deadlock can occur.

See Also

timeSetEvent, MidiProc, WaveProc


timeSetEvent function
timeSetEvent (Win32)

UINT timeSetEvent(wDelay, wResolution, lptc, dwUser, fuCallbackType)

UINT wDelay;	/* specifies event period	*/
UINT wResolution;	/* specifies delay accuracy	*/
LPTIMECALLBACK lptc;	/* address of callback function	*/
DWORD dwUser;	/* application-defined data	*/
UINT fuCallbackType;	/* callback type flags	*/

The timeSetEvent function sets up a timed callback event. The event can be a one-time event or a periodic event. Once activated, the event calls the specified callback function.

Parameter	Description

wDelay	Specifies the event period in milliseconds. If the delay is less than the minimum period supported by the timer, or greater than the maximum period supported by the timer, the function returns an error.

wResolution	Specifies the accuracy of the delay in milliseconds. The resolution of the timer event increases with smaller wResolution values. To reduce system overhead, use the maximum wResolution value appropriate for your application.

lptc	Points to a callback function that is called once upon expiration of a one-shot event or periodically upon expiration of periodic events. For more information on the callback function, see the description of the TimeProc function.

dwUser	Contains user-supplied callback data.

fuCallbackType	Specifies the type of timer event, using one of the following flags:

Value	Meaning

TIME_ONESHOT	Event occurs once, after wPeriod milliseconds.

TIME_PERIODIC	Event occurs every wPeriod milliseconds.

Returns

If the function succeeds, the return value is an identifier code that identifies the timer event. The ID code is also passed to the callback function. If the timer event was not created, the return value is zero.

Comments

Using this function to generate a high-frequency periodic-delay event (with a period less than 10 milliseconds) can consume a significant portion of the system CPU bandwidth. Any call to timeSetEvent for a periodic-delay timer must be paired with a call to the timeKillEvent function.

See Also

timeBeginPeriod, timeEndPeriod, timeKillEvent


waveInAddBuffer function
waveInAddBuffer (Win32)

MMRESULT waveInAddBuffer(hWaveIn, lpwh, cbwh)

HWAVEIN hWaveIn;	/* handle of input the device to send to	*/
LPWAVEHDR lpwh;	/* address of structure identifying buffer	*/
UINT cbwh;	/* size of structure, in bytes	*/

The waveInAddBuffer function sends an input buffer to a waveform input device. When the buffer is filled, it is sent back to the application.

Parameter	Description

hWaveIn	Identifies a handle to the waveform input device.

lpwh	Points to a WAVEHDR structure that identifies the buffer.

cbwh	Specifies the size, in bytes, of the WAVEHDR structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

WAVERR_UNPREPARED	The lpwh buffer hasn't been prepared.

MMSYSERR_HANDLEBUSY	The handle hWaveIn is in use on another thread.

Comments

The data buffer must be prepared by using the waveInPrepareHeader function before it is passed to waveInAddBuffer. The WAVEHDR structure and the data buffer pointed to by its lpData member must be allocated by using the GlobalAlloc function using the GMEM_MOVEABLE flag, and must be locked by using the GlobalLock function.

See Also

waveInPrepareHeader


waveInClose function
waveInClose (Win32)

MMRESULT waveInClose(hWaveIn)

HWAVEIN hWaveIn;	/* handle of device to close	*/

The waveInClose function closes the specified waveform input device.

Parameter	Description

hWaveIn	Identifies the waveform input device. If the function is successful, the handle is no longer valid after the function returns.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

WAVERR_STILLPLAYING	There are still buffers in the queue.

Comments

If there are input buffers that have been sent by using 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

waveInOpen, waveInReset


waveInGetDevCaps function
waveInGetDevCaps (Win32)

MMRESULT waveInGetDevCaps(IDDevice, lpwic, cbwic)

UINT IDDevice;	/* identifiee of the device to query	*/
LPWAVEINCAPS lpwic;	/* address of structure for capabilities	*/
UINT cbwic;	/* size of structure, in bytes	*/

The waveInGetDevCaps function queries a specified waveform input device to determine its capabilities.

Parameter	Description

IDDevice	Identifies the waveform input device.

lpwic	Points to a WAVEINCAPS structure that receives information about the capabilities of the device.

cbwic	Specifies the size, in bytes, of the WAVEINCAPS structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.

MMSYSERR_NODRIVER	The driver was not installed.

Comments

Use the waveInGetNumDevs function to determine the number of waveform input devices present in the system. The device identifier specified by IDDevice varies from zero to one less than the number of devices present. The WAVE_MAPPER constant may also be used as a device identifier. Only cbwic (or fewer) bytes of information are copied to the location pointed to by lpwic. If cbwic is zero, nothing is copied, and the function returns zero.

See Also

waveInGetNumDevs


waveInGetErrorText function
waveInGetErrorText (Win32)

MMRESULT waveInGetErrorText(mmrError, lpszDesc, cchDesc)

MMRESULT mmrError;	/* error code	*/
LPTSTR lpszDesc;	/* address of buffer for text description	*/
UINT cchDesc;	/* size of buffer, in characters	*/

The waveInGetErrorText function retrieves a text description of the error identified by the specified error number.

Parameter	Description

mmrError	Specifies the error number.

lpszDesc	Points to a buffer that will receive a text description of the error.

cchDesc	Specifies the size, in characters, of the buffer pointed to by lpszDesc.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be MMSYSERR_BADERRNUM, indicating that the specified error number is out of range.

Comments

If the text error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchDesc is zero, nothing is copied, and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long.


waveInGetID function
waveInGetID (Win32)

MMRESULT waveInGetID(hWaveIn, lpIDDevice)

HWAVEIN hWaveIn;	/* handle of the device	*/
PUINT lpIDDevice;	/* address of variable for device ID	*/

The waveInGetID function gets the device identifier for a waveform input device.

Parameter	Description

hWaveIn	Identifies the waveform input device.

lpIDDevice	Points to a variable that receives the device identifier.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The hWaveIn parameter specifies an invalid handle.

MMSYSERR_HANDLEBUSY	The handle hWaveIn is in use on another thread.


waveInGetNumDevs function
waveInGetNumDevs (Win32)

UINT waveInGetNumDevs(VOID)

The waveInGetNumDevs function returns the number of waveform input devices.

Returns

If the function succeeds, the return value is the number of waveform input devices present in the system.

See Also

waveInGetDevCaps


waveInGetPosition function
waveInGetPosition (Win32)

MMRESULT waveInGetPosition(hWaveIn, lpmmt, cbmmt)

HWAVEIN hWaveIn;	/* handle of device to query	*/
LPMMTIME lpmmt;	/* address of structure for current position	*/
UINT cbmmt;	/* size of structure, in bytes	*/

The waveInGetPosition function retrieves the current input position of the specified waveform input device.

Parameter	Description

hWaveIn	Identifies the waveform input device.

lpmmt	Points to an MMTIME structure that specifies the current input position.

cbmmt	Specifies the size of the MMTIME structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be MMSYSERR_INVALHANDLE, indicating that the specified device handle is invalid.

Comments

Before calling waveInGetPosition, set the wType member of the MMTIME structure to indicate the time format. After calling waveInGetPosition, be sure to check the wType member to determine if the requested time format is supported. If the requested format is not supported, wType will specify an alternative format.

The position is set to zero when the device is opened or reset.


waveInMessage function
waveInMessage (Win32)

MMRESULT waveInMessage(hWaveIn, uMsg, dwParameter1, dwParameter2)

HWAVEIN hWaveIn;	/* handle of device to send message to	*/
UINT uMsg;	/* specifies message	*/
DWORD dwParameter1;	/* application-defined parameter	*/
DWORD dwParameter2;	/* application-defined parameter	*/

The waveInMessage function sends a message to a waveform input device driver.

Parameter	Description

hWaveIn	Identifies the waveform input device to send a message to.

uMsg	Specifies the message to send.

dwParameter1	Application-defined parameter.

dwParameter2	Application-defined parameter.

Returns

If the function succeeds, the return value is the value returned from the device driver.


waveInOpen function
waveInOpen (Win32)

MMRESULT waveInOpen(lphWaveIn, IDDevice, lpwf, dwCallback, dwCallbackInstance, fdwOpen)

LPHWAVEIN lphWaveIn;	/* variable to receive a handle to the input device	*/
UINT IDDevice;	/* identifier of the device	*/
LPWAVEFORMAT lpwf;	/* address of structure with device format	*/
DWORD dwCallback;	/* address of callback or window handle	*/
DWORD dwCallbackInstance;	/* instance data	*/
DWORD fdwOpen;	/* open option	*/

The waveInOpen function opens a specified waveform input device for recording.

Parameter	Description

lphWaveIn	Points to a variable that will receive a handle that identifies the opened waveform input device. Use this handle to identify the device when calling other waveform input functions. This parameter may be NULL if the WAVE_FORMAT_QUERY flag is specified for fdwOpen.

IDDevice	Identifies the waveform input device to open. Use a valid device identifier or the WAVE_MAPPER flag.

If WAVE_MAPPER is specified, the function selects a waveform input device capable of recording in the given format.

lpwf	Points to a WAVEFORMAT structure that identifies the requested format for recording waveform data.

dwCallback	Specifies the address of a callback function or a handle of a window to be called during waveform recording to process messages related to the progress of recording. For a description of the callback function, see the description of the WaveProc callback function. Specify NULL for this parameter if no callback mechanism is to be used.

dwCallbackInstance	Specifies user instance data passed to the callback function. This parameter is not used with window callbacks.

fdwOpen	Specifies flags for opening the device.

Value	Meaning

WAVE_FORMAT_QUERY	If this flag is specified, the device will be queried to determine if it supports the given format but will not actually be opened.

WAVE_ALLOWSYNC	If this flag is not specified, the device will fail to open if it is a synchronous device.

CALLBACK_WINDOW	If this flag is specified, dwCallback is assumed to be a window handle.

CALLBACK_FUNCTION	If this flag is specified, dwCallback is assumed to be a callback procedure address.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.

MMSYSERR_ALLOCATED	The specified resource is already allocated.

MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

WAVERR_BADFORMAT	The system attempted to open the device with an unsupported wave format.

Comments

Use the waveInGetNumDevs function to determine the number of waveform input devices present in the system. The device identifier specified by IDDevice varies from zero to one less than the number of devices present. The WAVE_MAPPER constant may also be used as a device identifier.

The WAVEFORMAT structure pointed to by lpwf may be extended to include type-specific information for certain data formats. For example, for pulse code modulated (PCM) data, an extra word is added to specify the number of bits per sample. Use the PCMWAVEFORMAT structure in this case.

If a window is chosen to receive callback information, the following messages are sent to the window-procedure function to indicate the progress of waveform input: MM_WIM_OPEN, MM_WIM_CLOSE, and MM_WIM_DATA.

If a function is chosen to receive callback information, the following messages are sent to the function to indicate the progress of waveform input: WIM_OPEN, WIM_CLOSE, WIM_DATA. The callback function must reside in a dynamic-link library (DLL).

See Also

waveInClose


waveInPrepareHeader function
waveInPrepareHeader (Win32)

MMRESULT waveInPrepareHeader(hWaveIn, lpwh, cbwh)

HWAVEIN hWaveIn;	/* handle of waveform device	*/
LPWAVEHDR lpwh;	/* address of structure with device information	*/
UINT cbwh;	/* size of structure, in bytes	*/

The waveInPrepareHeader function prepares a buffer for waveform input.

Parameter	Description

hWaveIn	Identifies the waveform input device.

lpwh	Points to a WAVEHDR structure that identifies the buffer to be prepared.

cbwh	Specifies the size, in bytes, of the WAVEHDR structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

MMSYSERR_HANDLEBUSY	The handle hWaveIn is in use on another thread.

Comments

The WAVEHDR structure and the data block pointed to by its lpData member must be allocated by using the GlobalAlloc function and the GMEM_MOVEABLE flag, and must be locked by using the GlobalLock function. Preparing a header that has already been prepared will have no effect, and the function will return zero.

See Also

waveInUnprepareHeader


waveInReset function
waveInReset (Win32)

MMRESULT waveInReset(hWaveIn)

HWAVEIN hWaveIn;	/* handle of device to reset	*/

The waveInReset function stops input on a given waveform input device and resets the current position to zero. All pending buffers are marked as done and returned to the application.

Parameter	Description

hWaveIn	Identifiers the waveform input device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_HANDLEBUSY	The handle hWaveIn is in use on another thread.

See Also

waveInAddBuffer, waveInClose, waveInStart, waveInStop


waveInStart function
waveInStart (Win32)

MMRESULT waveInStart(hWaveIn)

HWAVEIN hWaveIn;	/* handle of device to start	*/

The waveInStart function starts input on the specified waveform input device.

Parameter	Description

hWaveIn	Identifies the waveform input device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_HANDLEBUSY	The handle hWaveIn is in use on another thread.

Comments

Buffers are returned to the client when full or when the waveInReset function is called. (The dwBytesRecorded member in the header will contain the actual length of data.) If there are no buffers in the queue, the data is thrown away without notification to the client, and input continues.

Calling this function when input is already started has no effect, and the function returns zero.

See Also

waveInReset, waveInStop


waveInStop function
waveInStop (Win32)

MMRESULT waveInStop(hWaveIn)

HWAVEIN hWaveIn;	/* handle of device to stop	*/

The waveInStop function stops waveform input.

Parameter	Description

hWaveIn	Identifies the waveform input device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_HANDLEBUSY	The handle hWaveIn is in use on another thread.

Comments

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 actual length of data.). 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.

See Also

waveInReset, waveInStart


waveInUnprepareHeader function
waveInUnprepareHeader (Win32)

MMRESULT waveInUnprepareHeader(hWaveIn, lpwh, wh)

HWAVEIN hWaveIn;	/* handle of input device	*/
LPWAVEHDR lpwh;	/* address of structure identifying buffer	*/
UINT wh;	/* size of structure, in bytes	*/

The waveInUnprepareHeader function cleans up the preparation performed by the waveInPrepareHeader function. This function must be called after the device driver fills a data buffer and returns it to the application. You must call this function before freeing the data buffer.

Parameter	Description

hWaveIn	Identifies the waveform input device.

lpwh	Points to a WAVEHDR structure that identifies the data buffer to be cleaned up.

wh	Specifies the size, in bytes, of the WAVEHDR structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

WAVERR_STILLPLAYING	The lpwh buffer is still in the queue.

MMSYSERR_HANDLEBUSY	The handle hWaveIn is in use on another thread.

Comments

This function complements the waveInPrepareHeader function. You must call this function before freeing the data buffer by using the GlobalFree function. After passing a buffer to the device driver by using 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


waveOutBreakLoop function
waveOutBreakLoop (Win32)

MMRESULT waveOutBreakLoop(hWaveOut)

HWAVEOUT hWaveOut;	/* handle of output device	*/

The waveOutBreakLoop function breaks a loop on a given waveform output device and allows playback to continue with the next block in the driver list.

Parameter	Description

hWaveOut	Identifies the waveform output device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

Waveform looping is controlled by the dwLoops and dwFlags members in the WAVEHDR structures passed to the device by using 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 on a single 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.

The blocks making up the loop are played to the end before the loop is stopped.

Calling this function when the nothing is playing or looping has no effect, and the function returns zero.

See Also

waveOutPause, waveOutRestart, waveOutWrite


waveOutClose function
waveOutClose (Win32)

MMRESULT waveOutClose(hWaveOut)

HWAVEOUT hWaveOut;	/* handle of device to close	*/

The waveOutClose function closes the specified waveform output device.

Parameter	Description

hWaveOut	Identifies the waveform output device. If the function succeeds, the handle is no longer valid after the function returns.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

WAVERR_STILLPLAYING	There are still buffers in the queue.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

If the device is still playing a waveform, the close operation will fail. Use the waveOutReset function to terminate waveform playback before calling waveOutClose.

See Also

waveOutOpen, waveOutReset


waveOutGetDevCaps function
waveOutGetDevCaps (Win32)

MMRESULT waveOutGetDevCaps(IDDevice, lpwoc, cbwoc)

UINT IDDevice;	/* identifier of output device	*/
LPWAVEOUTCAPS lpwoc;	/* address of structure for device capabilities	*/
UINT cbwoc;	/* size of structure, in bytes	*/

The waveOutGetDevCaps function queries a specified waveform device to determine its capabilities.

Parameter	Description

IDDevice	Identifies the waveform output device.

lpwoc	Points to a WAVEOUTCAPS structure that receives information about the capabilities of the device.

cbwoc	Specifies the size, in bytes, of the WAVEOUTCAPS structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_BADDEVICEID	The specified device identifier is out of range.

MMSYSERR_NODRIVER	The driver was not installed.

Comments

Use the waveOutGetNumDevs function to determine the number of waveform output devices present in the system. The device identifier specified by IDDevice varies from zero to one less than the number of devices present. The WAVE_MAPPER constant may also be used as a device identifier. Only cbwoc (or fewer) bytes of information are copied to the location pointed to by lpwoc. If cbwoc is zero, nothing is copied, and the function returns zero.

See Also

waveOutGetNumDevs


waveOutGetErrorText function
waveOutGetErrorText (Win32)

MMRESULT waveOutGetErrorText(mmrError, lpszDesc, cchDesc)

MMRESULT mmrError;	/* error code	*/
LPTSTR lpszDesc;	/* address of buffer for text description	*/
UINT cchDesc;	/* size of buffer, in characters	*/

The waveOutGetErrorText function retrieves a text description of the error identified by the specified error number.

Parameter	Description

mmrError	Specifies the error number.

lpszDesc	Points to a buffer that will receive a text description of the error.

cchDesc	Specifies the size, in characters, of the buffer at lpszDesc.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be MMSYSERR_BADERRNUM, indicating that the specified error number is out of range.

Comments

If the text error description is longer than the specified buffer, the description is truncated. The returned error string is always null-terminated. If cchDesc is zero, nothing is copied and the function returns zero. All error descriptions are less than MAXERRORLENGTH characters long.


waveOutGetID function
waveOutGetID (Win32)

MMRESULT waveOutGetID(hWaveOut, lpIDDevice)

HWAVEOUT hWaveOut;	/* handle of the device	*/
PUINT lpIDDevice;	/* address of buffer for device ID	*/

The waveOutGetID function gets the device identifier for a waveform output device.

Parameter	Description

hWaveOut	Identifies the waveform output device.

lpIDDevice	Points to a variable that will receive the device identifier.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The hWaveOut parameter specifies an invalid handle.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.


waveOutGetNumDevs function
waveOutGetNumDevs (Win32)

UINT waveOutGetNumDevs(VOID)

The waveOutGetNumDevs function retrieves the number of waveform output devices present in the system.

Returns

If the function succeeds, the return value is the number of waveform output devices present in the system.

See Also

waveOutGetDevCaps


waveOutGetPitch function
waveOutGetPitch (Win32)

MMRESULT waveOutGetPitch(hWaveOut, lpdwPitch)

HWAVEOUT hWaveOut;	/* handle of output device	*/
LPDWORD lpdwPitch;	/* address of buffer for pitch	*/

The waveOutGetPitch function queries the the current pitch setting of a waveform output device.

Parameter	Description

hWaveOut	Identifies waveform output device.

lpdwPitch	Points to a variable that will receive 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 doubleword location contains the signed integer part of the number, and the low-order word contains the fractional part. The fraction is expressed as a word in which a value of 0x8000 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.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED	The function isn't supported.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

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

waveOutGetPlaybackRate, waveOutSetPitch, waveOutSetPlaybackRate


waveOutGetPlaybackRate function
waveOutGetPlaybackRate (Win32)

MMRESULT waveOutGetPlaybackRate(hWaveOut, lpdwRate)

HWAVEOUT hWaveOut;	/* handle of output device	*/
LPDWORD lpdwRate;	/* address of buffer for playback rate	*/

The waveOutGetPlaybackRate function queries the current playback rate setting of a waveform output device.

Parameter	Description

hWaveOut	Identifies the waveform output device.

lpdwRate	Points to a variable that will receive 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 doubleword location contains the signed integer part of the number, and the low-order word contains the fractional part. The fraction is expressed as a word in which a value of 0x8000 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.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED	The function isn't supported.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

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 of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).

See Also

waveOutGetPitch, waveOutSetPitch, waveOutSetPlaybackRate,


waveOutGetPosition function
waveOutGetPosition (Win32)

MMRESULT waveOutGetPosition(hWaveOut, lpmmt, cbmmt)

HWAVEOUT hWaveOut;	/* handle of output device	*/
LPMMTIME lpmmt;	/* address of structure for current position	*/
UINT cbmmt;	/* size of structure, in bytes	*/

The waveOutGetPosition function retrieves the current playback position of the specified waveform output device.

Parameter	Description

hWaveOut	Identifies the waveform output device.

lpmmt	Points to an MMTIME structure that receives the current playback position.

cbmmt	Specifies the size, in bytes, of the MMTIME structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

Before calling waveOutGetPosition, set the wType member of the MMTIME structure to indicate the time format. After calling waveOutGetPosition, check the wType field to determine if the requested time format is supported. If the requested format is not supported, wType will specify an alternative format.

The position is set to zero when the device is opened or reset.


waveOutGetVolume function
waveOutGetVolume (Win32)

MMRESULT waveOutGetVolume(IDDevice, lpdwVolume)

UINT IDDevice;	/* identifier of output device	*/
LPDWORD lpdwVolume;	/* address of buffer for volume	*/

The waveOutGetVolume function queries the current volume setting of a waveform output device.

Parameter	Description

IDDevice	Identifies the waveform output device.

lpdwVolume	Points to a buffer that will receive 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 set with waveOutSetVolume is returned, regardless of whether the device supports the full 16 bits of volume-level control.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED	The function isn't supported.

MMSYSERR_NODRIVER	The driver was not installed.

Comments

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 to test the dwSupport member of the WAVEOUTCAPS structure (filled by the waveOutGetDevCaps function).

See Also

waveOutSetVolume


waveOutMessage function
waveOutMessage (Win32)

MMRESULT waveOutMessage(hWaveOut, uMsg, dwParameter1, dwParameter2)

HWAVEOUT hWaveOut;	/* handle of output device	*/
UINT uMsg;	/* message	*/
DWORD dwParameter1;	/* application-defined parameter	*/
DWORD dwParameter2;	/* application-defined parameter	*/

The waveOutMessage function sends a message to a waveform output device driver.

Parameter	Description

hWaveOut	Identifies the audio device.

uMsg	Specifies the message to send.

dwParameter1	Application-defined parameter.

dwParameter2	Application-defined parameter.

Returns

If the function succeeds, the return value is the value returned from the driver.


waveOutOpen function
waveOutOpen (Win32)

MMRESULT waveOutOpen(lphWaveOut, IDDevice, lpwf, dwCallback, dwCallbackInstance, fdwOpen)

LPHWAVEOUT lphWaveOut;	/* variable to receive a handle of output device	*/
UINT IDDevice;	/* identifier of device	*/
LPWAVEFORMAT lpwf;	/* address of structure with device format	*/
DWORD dwCallback;	/* address of callback or window handle	*/
DWORD dwCallbackInstance;	/* instance data	*/
DWORD fdwOpen;	/* open option	*/

The waveOutOpen function opens a specified waveform output device for playback.

Parameter	Description

lphWaveOut	Points to a variable that will receive a handle that identifies the opened waveform output device. Use this handle of identify the device when calling other waveform output functions. This parameter may be NULL if the WAVE_FORMAT_QUERY flag is specified for fdwOpen.

IDDevice	Identifies the waveform output device to open. Use a valid device identifier or the WAVE_MAPPER flag.

If WAVE_MAPPER is specified, the function selects a waveform output device capable of playing the given format.

lpwf	Points to a WAVEFORMAT structure that identifies the desired format for recording waveform data.

dwCallback	Specifies the address of a callback function or a handle of a window called during waveform playback to process messages related to the progress of playback. For more information about the callback function, see the description of the WaveProc function. Specify NULL for this parameter if no callback mechanism is to be used.

dwCallbackInstance	Specifies user instance data passed to the callback function. This parameter is not used with window callbacks.

fdwOpen	Specifies flags for opening the device, as follows.

Value	Meaning

WAVE_FORMAT_QUERY	If this flag is specified, the device is queried to determine if it supports the given format but is not actually opened.

WAVE_ALLOWSYNC	If this flag is not specified, the device will fail to open if it is a synchronous device.

CALLBACK_WINDOW	If this flag is specified, dwCallback is assumed to be a window handle.

CALLBACK_FUNCTION	If this flag is specified, dwCallback is assumed to be a callback procedure address.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_BADDEVICEID	The specified device ID is out of range.

MMSYSERR_ALLOCATED	The specified resource is already allocated.

MMSYSERR_NOMEM	The system is unable to allocate or lock memory.

WAVERR_BADFORMAT	The system attempted to open with an unsupported wave format.

Comments

Use waveOutGetNumDevs to determine the number of waveform output devices present in the system. The device identifier specified by IDDevice varies from zero to one less than the number of devices present. The WAVE_MAPPER constant may also be used as a device identifier.

The WAVEFORMAT structure pointed to by lpwf may be extended to include type-specific information for certain data formats. For example, for pulse code modulated (PCM) data, an extra word is added to specify the number of bits per sample. Use the PCMWAVEFORMAT structure in this case.

If a window is chosen to receive callback information, the following messages are sent to the window procedure function to indicate the progress of waveform output: MM_WOM_OPEN, MM_WOM_CLOSE, and MM_WOM_DONE.

If a function is chosen to receive callback information, the following messages are sent to the function to indicate the progress of waveform output: WOM_OPEN, WOM_CLOSE, and WOM_DONE. The callback function must reside in a dynamic-link library (DLL).

See Also

waveOutClose


waveOutPause function
waveOutPause (Win32)

MMRESULT waveOutPause(hWaveOut)

HWAVEOUT hWaveOut;	/* handle of output device	*/

The waveOutPause function pauses playback on a specified waveform output device. The current playback position is saved. Use the waveOutRestart function to resume playback from the current playback position.

Parameter	Description

hWaveOut	Identifies the waveform output device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

Calling this function when the output is already paused has no effect, and the function returns zero.

See Also

waveOutRestart, waveOutBreakLoop


waveOutPrepareHeader function
waveOutPrepareHeader (Win32)

MMRESULT waveOutPrepareHeader(hWaveOut, lpwh, cbwh)

HWAVEOUT hWaveOut;	/* handle of output device	*/
LPWAVEHDR lpwh;	/* address of structure with buffer information	*/
UINT cbwh;	/* size of structure, in bytes	*/

The waveOutPrepareHeader function prepares a waveform data block for playback.

Parameter	Description

hWaveOut	Identifies the waveform output device.

lpwh	Points to a WAVEHDR structure that identifies the data block to be prepared.

cbwh	Specifies the size of the WAVEHDR structure in bytes.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOMEM	Unable to allocate or lock memory.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

The WAVEHDR structure and the data block pointed to by its lpData member must be allocated by using the GlobalAlloc function and the GMEM_MOVEABLE flag, and must be locked by using the GlobalLock function. Preparing a header that has already been prepared has no effect, and the function returns zero.

See Also

waveOutUnprepareHeader


waveOutReset function
waveOutReset (Win32)

MMRESULT waveOutReset(hWaveOut)

HWAVEOUT hWaveOut;	/* handle of device to reset	*/

The waveOutReset function stops playback on a given waveform output device and resets the current position to zero. All pending playback buffers are marked as done and returned to the application.

Parameter	Description

hWaveOut	Identifies the waveform output device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

See Also

waveOutClose, waveOutWrite


waveOutRestart function
waveOutRestart (Win32)

MMRESULT waveOutRestart(hWaveOut)

HWAVEOUT hWaveOut;	/* handle of device to restart	*/

The waveOutRestart function restarts a paused waveform output device.

Parameter	Description

hWaveOut	Identifies the waveform output device.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

Calling this function when the output is not paused has no effect, and the function returns zero.

See Also

waveOutBreakLoop, waveOutPause


waveOutSetPitch function
waveOutSetPitch (Win32)

MMRESULT waveOutSetPitch(hWaveOut, dwPitch)

HWAVEOUT hWaveOut;	/* handle of device to set pitch for	*/
DWORD dwPitch;	/* new pitch	*/

The waveOutSetPitch function sets the pitch of a waveform output device.

Parameter	Description

hWaveOut	Identifies the waveform output device.

dwPitch	Specifies the new pitch-multiplier setting. The pitch-multiplier 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 of the location contains the signed integer part of the number, and the low-order word contains the fractional part. The fraction is expressed as a word in which a value of 0x8000 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.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED	The function isn't supported.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

Changing the pitch does not change the playback rate or the sample rate. The playback time is also unchanged. 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

waveOutGetPitch, waveOutSetPlaybackRate, waveOutGetPlaybackRate


waveOutSetPlaybackRate function
waveOutSetPlaybackRate (Win32)

MMRESULT waveOutSetPlaybackRate(hWaveOut, dwRate)

HWAVEOUT hWaveOut;	/* handle of device to set rate for	*/
DWORD dwRate;	/* specifies the new rate	*/

The waveOutSetPlaybackRate function sets the playback rate of a waveform output device.

Parameter	Description

hWaveOut	Identifies the waveform output device.

dwRate	Specifies the new playback-rate setting. 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 contains the signed integer part of the number, and the low-order word contains the fractional part. The fraction is expressed as a word in which a value of 0x8000 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.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED	The function isn't supported.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

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

waveOutGetPitch, waveOutGetPlaybackRate, waveOutSetPitch


waveOutSetVolume function
waveOutSetVolume (Win32)

MMRESULT waveOutSetVolume(IDDevice, dwVolume)

UINT IDDevice;	/* handle of device to set volume for	*/
DWORD dwVolume;	/* new volume	*/

The waveOutSetVolume function sets the volume of a waveform output device.

Parameter	Description

IDDevice	Identifies the waveform output device.

dwVolume	Specifies the 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.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

MMSYSERR_NOTSUPPORTED	The function isn't supported.

MMSYSERR_NODRIVER	The driver was not installed.

Comments

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 to test the dwSupport member of the WAVEOUTCAPS structure (filled by waveOutGetDevCaps).

Most devices don't 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 by using waveOutSetVolume.

Volume settings are interpreted logarithmically. This means the perceived increase in volume is the same from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

See Also

waveOutGetVolume


waveOutUnprepareHeader function
waveOutUnprepareHeader (Win32)

MMRESULT waveOutUnprepareHeader(hWaveOut, lpwh, cbwh)

HWAVEOUT hWaveOut;	/* handle of wave device	*/
LPWAVEHDR lpwh;	/* address of structure with buffer information	*/
UINT cbwh;	/* size of structure, in bytes	*/

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 data buffer.

Parameter	Description

hWaveOut	Identifies the waveform output device.

lpwh	Points to a WAVEHDR structure identifying the data block to be cleaned up.

cbwh	Specifies the size, in bytes, of the WAVEHDR structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

WAVERR_STILLPLAYING	The lpwh buffer is still in the queue.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

This function complements the waveOutPrepareHeader function. You must call this function before freeing the data buffer using the GlobalFree function. After passing a buffer to the device driver by using 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


waveOutWrite function
waveOutWrite (Win32)

MMRESULT waveOutWrite(hWaveOut, lpwh, cbwh)

HWAVEOUT hWaveOut;	/* handle of device to write to	*/
LPWAVEHDR lpwh;	/* address of structure with buffer information	*/
UINT cbwh;	/* size of structure, in bytes	*/

The waveOutWrite function sends a data block to the specified waveform output device.

Parameter	Description

hWaveOut	Identifies the waveform output device.

lpwh	Points to a WAVEHDR structure containing information about the data block.

cbwh	Specifies the size, in bytes, of the WAVEHDR structure.

Returns

If the function succeeds, the return value is zero; otherwise, it is an error code, which can be one of the following:

Value	Meaning

MMSYSERR_INVALHANDLE	The specified device handle is invalid.

WAVERR_UNPREPARED	The lpwh buffer hasn't been prepared.

MMSYSERR_HANDLEBUSY	The handle hWaveOut is in use on another thread.

Comments

The data buffer must be prepared by using the waveOutPrepareHeader function before it is passed to waveOutWrite. The WAVEHDR structure and the data buffer pointed to by its lpData member must be allocated by using the GlobalAlloc function and the GMEM_MOVEABLE flag, and must be locked using the GlobalLock function. Unless the device is paused by calling the waveOutPause function, playback begins when the first data block is sent to the device.

See Also

waveOutPause, waveOutPrepareHeader, waveOutReset, waveOutRestart


WaveProc function
WaveProc (Win32)

void CALLBACK WaveProc(hWave, uMsg, dwInstance, dwParam1, dwParam2)

HWAVE hWave;	/* handle of waveform device	*/
UINT uMsg;	/* sent message	*/
DWORD dwInstance;	/* instance data	*/
DWORD dwParam1;	/* application-defined parameter	*/
DWORD dwParam2;	/* application-defined parameter	*/

The WaveProc function is an application-defined callback function that processes messages sent to a waveform device. The address of the WaveProc function can be specified as the callback-address parameter for the waveInOpen or waveOutOpen function.

Parameter	Description

hWave	Identifies the waveform device associated with the callback.

uMsg	Specifies the message.

dwInstance	Specifies the user instance data specified with waveInOpen or waveOutOpen.

dwParam1	Specifies an application-defined parameter for the message.

dwParam2	Specifies an application-defined parameter for the message.

Returns

This function does not return a value.

Comments

WaveProc is a placeholder for the application-defined function name.

There are several differences between WaveProc functions under Windows NT and under Windows 3.1 :

Under Windows 3.1, a WaveProc function is called at interrupt time. The call to a WaveProc function occurs on a separate thread under Windows NT.

Under Windows 3.1, a WaveProc function has to be in a dynamic link library. Under Windows NT, there is no such restriction.

Under Windows 3.1, a WaveProc function must be exported in a .DEF file. Under Windows NT, that is not necessary.

If source code must be compatible with Windows 3.1, it should follow the Windows 3.1 rules as noted briefly above and specified more fully in the Windows 3.1 documentation.

One other item should be noted carefully. There is a limited set of APIs that a Windows 3.1 WaveProc function may call. In Win32, that strict limitation has been removed. However, it is strongly recommended that a Windows NT WaveProc function restrain its calls to APIs in the same set, with the addition of the API SetEvent. Here is the Windows NT recommended list:

EnterCriticalSection	PostThreadMessage

LeaveCriticalSection	SetEvent

midiOutLongMsg	timeGetSystemTime

midiOutShortMsg	timeGetTime

OutputDebugString	timeKillEvent

PostMessage	timeSetEvent

If an application's WaveProc function does stray from this list, it should be careful not to call APIs that take a long time to complete.

A WaveProc function should not call other Wave* APIs; if it does, it will probably deadlock.

If a Win32 WaveProc shares data with other code, a Critical Section or similar mutual exclusion mechanism should be used to protect the integrity of the data.

See Also

MidiProc, TimeProc, MMIOProc


MCI_HMS_HOUR function
MCI_HMS_HOUR (Win32)

BYTE MCI_HMS_HOUR(dwHMS)

DWORD dwHMS;	/* time in HMS format	*/

The MCI_HMS_HOUR macro returns the hours field from a doubleword argument containing packed hours/minutes/seconds (HMS) information.

Parameter	Description

dwHMS	Specifies the time in HMS format.

Returns

The return value is the hours field of the given argument.

Comments

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.

See Also

MCI_HMS_MINUTE, MCI_HMS_SECOND, MCI_MAKE_HMS


MCI_HMS_MINUTE function
MCI_HMS_MINUTE (Win32)

BYTE MCI_HMS_MINUTE(dwHMS)

DWORD dwHMS;	/* time in HMS format	*/

The MCI_HMS_MINUTE macro returns the minutes field from a doubleword argument containing packed hours/minutes/seconds (HMS) information.

Parameter	Description

dwHMS	Specifies the time in HMS format.

Returns

The return value is the minutes field of the given argument.

Comments

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.

See Also

MCI_HMS_HOUR, MCI_HMS_SECOND, MCI_MAKE_HMS


MCI_HMS_SECOND function
MCI_HMS_SECOND (Win32)

BYTE MCI_HMS_SECOND(dwHMS)

DWORD dwHMS;	/* time in HMS format	*/

The MCI_HMS_SECOND macro returns the seconds field from a doubleword argument containing packed hours/minutes/seconds (HMS) information.

Parameter	Description

dwHMS	Specifies the time in HMS format.

Returns

The return value is the seconds field of the given argument.

Comments

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.

See Also

MCI_HMS_HOUR, MCI_HMS_MINUTE, MCI_MAKE_HMS


MCI_MAKE_HMS function
MCI_MAKE_HMS (Win32)

DWORD MCI_MAKE_HMS(hours, minutes, seconds)

BYTE hours;	/* hours	*/
BYTE minutes;	/* minutes	*/
BYTE seconds;	/* seconds	*/

The MCI_MAKE_HMS macro returns a time value in packed hours/minutes/seconds (HMS) format from the given hours, minutes, and seconds values.

Parameter	Description

hours	Specifies the number of hours.

minutes	Specifies the number of minutes.

seconds	Specifies the number of seconds.

Returns

The return value is a doubleword value containing the time in packed HMS format.

Comments

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.

See Also

MCI_HMS_MINUTE, MCI_HMS_SECOND, MCI_MSF_FRAME


MCI_MAKE_MSF function
MCI_MAKE_MSF (Win32)

DWORD MCI_MAKE_MSF(minutes, seconds, frames)

BYTE minutes;	/* minutes	*/
BYTE seconds;	/* seconds	*/
BYTE frames;	/* number of frames	*/

The MCI_MAKE_MSF macro returns a time value in packed minutes/seconds/frames (MSF) format from the given minutes, seconds, and frame values.

Parameter	Description

minutes	Specifies the number of minutes.

seconds	Specifies the number of seconds.

frames	Specifies the number of frames.

Returns

The return value is a doubleword value containing the time in packed MSF format.

Comments

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.

See Also

MCI_MSF_MINUTE, MCI_MSF_SECOND, MCI_MSF_FRAME


MCI_MAKE_TMSF function
MCI_MAKE_TMSF (Win32)

DWORD MCI_MAKE_TMSF(tracks, minutes, seconds, frames)

BYTE tracks;	/* number of tracks	*/
BYTE minutes;	/* minutes	*/
BYTE seconds;	/* seconds	*/
BYTE frames;	/* number of frames	*/

The MCI_MAKE_TMSF macro returns a time value in packed tracks/minutes/seconds/frames (TMSF) format from the given tracks, minutes, seconds, and frames values.

Parameter	Description

tracks	Specifies the number of tracks.

minutes	Specifies the number of minutes.

seconds	Specifies the number of seconds.

frames	Specifies the number of frames.

Returns

The return value is a doubleword value containing the time in packed TMSF format.

Comments

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.

See Also

MCI_TMSF_MINUTE, MCI_TMSF_SECOND, MCI_TMSF_FRAME


MCI_MSF_FRAME function
MCI_MSF_FRAME (Win32)

BYTE MCI_MSF_FRAME(dwMSF)

DWORD dwMSF;	/* time in MSF format	*/

The MCI_MSF_FRAME macro returns the frames field from a doubleword argument containing packed minutes/seconds/frames (MSF) information.

Parameter	Description

dwMSF	Specifies the time in MSF format.

Returns

The return value is the frames field of the given argument.

Comments

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.

See Also

MCI_MSF_MINUTE, MCI_MSF_SECOND, MCI_MAKE_MSF


MCI_MSF_MINUTE function
MCI_MSF_MINUTE (Win32)

BYTE MCI_MSF_MINUTE(dwMSF)

DWORD dwMSF;	/* time in MSF format	*/

The MCI_MSF_MINUTE macro returns the minutes field from a doubleword argument containing packed minutes/seconds/frames (MSF) information.

Parameter	Description

dwMSF	Specifies the time in MSF format.

Returns

The return value is the minutes field of the given argument.

Comments

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.

See Also

MCI_MSF_SECOND, MCI_MSF_FRAME, MCI_MAKE_MSF


MCI_MSF_SECOND function
MCI_MSF_SECOND (Win32)

BYTE MCI_MSF_SECOND(dwMSF)

DWORD dwMSF;	/* time in MSF format	*/

The MCI_MSF_SECOND macro returns the seconds field from a doubleword argument containing packed minutes/seconds/frames (MSF) information.

Parameter	Description

dwMSF	Specifies the time in MSF format.

Returns

The return value is the seconds field of the given argument.

Comments

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.

See Also

MCI_MSF_MINUTE, MCI_MSF_FRAME, MCI_MAKE_MSF


MCI_TMSF_FRAME function
MCI_TMSF_FRAME (Win32)

BYTE MCI_TMSF_FRAME(dwTMSF)

DWORD dwTMSF;	/* time in TMSF format	*/

The MCI_TMSF_FRAME macro returns the frames field from a doubleword argument containing packed tracks/minutes/seconds/frames (TMSF) information.

Parameter	Description

dwTMSF	Specifies the time in TMSF format.

Returns

The return value is the frames field of the given argument.

Comments

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.

See Also

MCI_TMSF_TRACK, MCI_TMSF_MINUTE, MCI_TMSF_SECOND, MCI_MAKE_TMSF


MCI_TMSF_MINUTE function
MCI_TMSF_MINUTE (Win32)

BYTE MCI_TMSF_MINUTE(dwTMSF)

DWORD dwTMSF;	/* time in TMSF format	*/

The MCI_TMSF_MINUTE macro returns the minutes field from a doubleword argument containing packed tracks/minutes/seconds/frames (TMSF) information.

Parameter	Description

dwTMSF	Specifies the time in TMSF format.

Returns

The return value is the minutes field of the given argument.

Comments

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.

See Also

MCI_TMSF_TRACK, MCI_TMSF_SECOND, MCI_TMSF_FRAME, MCI_MAKE_TMSF


MCI_TMSF_SECOND function
MCI_TMSF_SECOND (Win32)

BYTE MCI_TMSF_SECOND(dwTMSF)

DWORD dwTMSF;	/* time in TMSF format	*/

The MCI_TMSF_SECOND macro returns the seconds field from a doubleword argument containing packed tracks/minutes/seconds/frames (TMSF) information.

Parameter	Description

dwTMSF	Specifies the time in TMSF format.

Returns

The return value is the seconds field of the given argument.

Comments

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.

See Also

MCI_TMSF_TRACK, MCI_TMSF_MINUTE, MCI_TMSF_FRAME, MCI_MAKE_TMSF


MCI_TMSF_TRACK function
MCI_TMSF_TRACK (Win32)

BYTE MCI_TMSF_TRACK(dwTMSF)

DWORD dwTMSF;	/* time in TMSF format	*/

The MCI_TMSF_TRACK macro returns the tracks field from a doubleword argument containing packed tracks/minutes/seconds/frames (TMSF) information.

Parameter	Description

dwTMSF	Specifies the time in TMSF format.

Returns

The return value is the tracks field of the given argument.

Comments

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.

See Also

MCI_TMSF_MINUTE, MCI_TMSF_SECOND, MCI_TMSF_FRAME, MCI_MAKE_TMSF


Multimedia Functions (all)

auxGetDevCaps	Retrieve auxiliary device capabilities

auxGetNumDevs	Return number of auxiliary devices

auxGetVolume	Retrieve current volume setting

auxOutMessage	Send message to output device

auxSetVolume	Set auxiliary device volume

joyGetDevCaps	Determine joystick device capabilities

joyGetNumDevs	Return number of joystick devices

joyGetPos	Retrieve joystick position and button activity

joyGetThreshold	Retrieve joystick movement threshold

joyReleaseCapture	Release joystick capture

joySetCapture	Capture joystick messages to specified window

joySetThreshold	Set joystick movement threshold

mciGetCreatorTask	Retrieves creator task

mciGetDeviceID	Returns device ID for device name

mciGetErrorString	Retrieve text description for MCI error code

mciGetYieldProc	Get yield procedure address

mciSendCommand	Send a command message to MCI device

mciSendString	Send a command string to MCI device

mciSetYieldProc	Set yield procedure address

midiInAddBuffer	Send input buffer to MIDI device

midiInClose	Close MIDI input device

midiInGetDevCaps	Determine MIDI device capabilities

midiInGetErrorText	Retrieve text description for MIDI error code

midiInGetID	Retrieve device ID for MIDI device handle

midiInGetNumDevs	Return number of MIDI devices

midiInMessage	Send message to MIDI device driver

midiInOpen	Open MIDI device

midiInPrepareHeader	Prepare MIDI output buffer

midiInReset	Stop MIDI input and mark input buffers as done

midiInStart	Start MIDI input device

midiInStop	Stop MIDI input

midiInUnprepareHeader	Cleans up prepared header

midiOutCacheDrumPatches	Preload MIDI percussion patches

midiOutCachePatches	Preload MIDI patches

midiOutClose	Close MIDI output device

midiOutGetDevCaps	Retrieve MIDI output device capabilities

midiOutGetErrorText	Retrieve text for MIDI output error

midiOutGetID	Retrieve MIDI output device ID for handle

midiOutGetNumDevs	Get number of MIDI output devices

midiOutGetVolume	Retrieve MIDI output device volume

midiOutLongMsg	Send system-exclusive MIDI message

midiOutMessage	Send message to MIDI device driver

midiOutOpen	Open MIDI output device

midiOutPrepareHeader	Prepare MIDI output data block

midiOutReset	Stop MIDI output and mark buffers as done

midiOutSetVolume	Set MIDI output device volume

midiOutShortMsg	Send short message to MIDI output device

midiOutUnprepareHeader	Clean up prepared MIDI output header

MidiProc	Processes MIDI device messages

mmioAdvance	Advance direct I/O buffer

mmioAscend	Ascend out of RIFF chunk

mmioClose	Close MM file

mmioCreateChunk	Create RIFF file chunk

mmioDescend	Descend into RIFF chunk

mmioFlush	Flush MM I/O buffer to disk

mmioFOURCC	Converts four characters to FOURCC

mmioGetInfo	Retrieve MM file info

mmioInstallIOProc	Install or remove custom I/O procedure

mmioOpen	Open a multimedia file

MMIOProc	MMIO callback procedure

mmioRead	Read from a file

mmioRename	Rename a multimedia file

mmioSeek	Change current file position

mmioSendMessage	Send message to I/O procedure

mmioSetBuffer	Control I/O buffering

mmioSetInfo	Set file information

mmioStringToFOURCC	Convert string to four-character code

mmioWrite	Write to a file

mmsystemGetVersion	Return current MM software version

sndPlaySound	Play a waveform sound

timeBeginPeriod	Set minimum timer resolution

timeEndPeriod	Clear minimum timer resolution

timeGetDevCaps	Retrieve timer device capabilities

timeGetSystemTime	Retrieve elapsed time since Windows started

timeGetTime	Return elapsed time since Windows started

timeKillEvent	Destroy specified timer callback event

TimeProc	Timer event callback function

timeSetEvent	Set up timed callback event

waveInAddBuffer	Send buffer to waveform input device

waveInClose	Close waveform input device

waveInGetDevCaps	Get waveform input device capabilities

waveInGetErrorText	Get text description for waveform error

waveInGetID	Get waveform input device ID for handle

waveInGetNumDevs	Return number of waveform input devices

waveInGetPosition	Get current waveform device input position

waveInMessage	Send messageto waveform input device

waveInOpen	Open waveform input device for recording

waveInPrepareHeader	Prepare buffer for waveform input

waveInReset	Stops waveform input device

waveInStart	Start waveform input device

waveInStop	Stop waveform input

waveInUnprepareHeader	Clean up prepared waveform header

waveOutBreakLoop	Break waveform output loop

waveOutClose	Close waveform output device

waveOutGetDevCaps	Get waveform output device capabilities

waveOutGetErrorText	Get text description for waveform error

waveOutGetID	Get waveform output device ID for handle

waveOutGetNumDevs	Get number of waveform output devices

waveOutGetPitch	Get current waveform output pitch

waveOutGetPlaybackRate	Get current waveform playback rate

waveOutGetPosition	Get current waveform playback position

waveOutGetVolume	Get current waveform volume

waveOutMessage	Send message to waveform output drivers

waveOutOpen	Open waveform output device

waveOutPause	Pause waveform playback

waveOutPrepareHeader	Prepare waveform playback data block

waveOutReset	Stop waveform playback

waveOutRestart	Restart paused waveform playback

waveOutSetPitch	Set waveform output pitch

waveOutSetPlaybackRate	Set waveform playback rate

waveOutSetVolume	Set waveform output volume

waveOutUnprepareHeader	Clean up prepared waveform data block

waveOutWrite	Write to waveform output device

WaveProc	Waveform device callback function

MCI_HMS_HOUR	Returns hours from HMS time

MCI_HMS_MINUTE	Returns minutes from HMS time

MCI_HMS_SECOND	Returns seconds from HMS time

MCI_MAKE_HMS	Returns HMS time from hours, minutes and seconds

MCI_MAKE_MSF	Returns MSF time from minutes, seconds, and frames

MCI_MAKE_TMSF	Returns TMSF time from individual values

MCI_MSF_FRAME	Returns frames from MSF time

MCI_MSF_MINUTE	Returns minutes from MSF time

MCI_MSF_SECOND	Returns seconds from MSF time

MCI_TMSF_FRAME	Returns frames from TMSF time

MCI_TMSF_MINUTE	Returns minutes from TMSF time

MCI_TMSF_SECOND	Returns seconds from TMSF time

MCI_TMSF_TRACK	Returns tracks from TMSF time


BM_GETCHECK message
BM_GETCHECK (Win32)

BM_GETCHECK

wParam = 0;     /* not used, must be zero */

lParam = 0;     /* not used, must be zero */

An application sends a BM_GETCHECK message to retrieve the check state of a radio button or check box.

Parameters

This message has no parameters.

Returns

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

0	Button state is unchecked.

1	Button state is checked.

2	Button state is indeterminate (applies only if the button has the BS_3STATE or BS_AUTO3STATE style).

If the button has any other style, the return value is 0.

See Also

BM_GETSTATE, BM_SETCHECK, IsDlgButtonChecked, SendDlgItemMessage


BM_GETSTATE message
BM_GETSTATE (Win32)

BM_GETSTATE

wParam = 0;     /* not used, must be zero */

lParam = 0;     /* not used, must be zero */

An application sends a BM_GETSTATE message to determine the state of a button or check box.

Parameters

This message has no parameters.

Returns

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 0 indicates the button is unchecked. A value of 1 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 2 indicates the check state is indeterminate (three-state check boxes only). The state of a three-state check box is indeterminate when it is grayed.

0x0004	Specifies the highlight state. A nonzero value indicates that the button is highlighted. A button is highlighted when the user presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.

0x0008	Specifies the focus state. A nonzero value indicates that the button has the keyboard focus.

See Also

BM_GETCHECK, BM_SETSTATE


BM_SETCHECK message
BM_SETCHECK (Win32)

BM_SETCHECK

wParam = (WPARAM) fCheck; /* check state            */

lParam = 0;               /* not used, must be zero */

An application sends a BM_SETCHECK message to set the check state of a radio button or check box.

Parameter	Description

fCheck	Value of wParam. Specifies the check state. This parameter can be one of the following values:

Value	Meaning

0	Set the button state to unchecked.

1	Set the button state to checked.

2	Set the button state to grayed. This value can be used only if the button has the BS_3STATE or BS_AUTO3STATE style.

Returns

This message always returns zero.

Comments

The BM_SETCHECK message has no effect on push buttons.

See Also

BM_GETCHECK, BM_GETSTATE, BM_SETSTATE, CheckDlgButton, CheckRadioButton


BM_SETSTATE message
BM_SETSTATE (Win32)

BM_SETSTATE

wParam = (WPARAM) fState;   /* highlight state        */

lParam = 0;                 /* not used, must be zero */

An application sends a BM_SETSTATE message to change the highlight state of a button.

Parameter	Description

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.

Returns

This message always returns zero.

Comments

Highlighting affects the exterior 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 message
BM_SETSTYLE (Win32)

BM_SETSTYLE

wParam =  (WPARAM) LOWORD(dwStyle); /* style       */

lParam =  MAKELPARAM(fRedraw, 0);   /* redraw flag */

An application sends a BM_SETSTYLE message to change the style of a button.

Parameter	Description

dwStyle	Value of wParam. Specifies the button style. For an explanation of button styles, see the Comments 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.

Returns

This message always returns zero.

Comments

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

BS_AUTOCHECKBOX	Creates a button that is the same as a check box, except that an X appears in the check box when the user selects the box; the X disappears the next time the user selects the box.

BS_AUTORADIOBUTTON	Creates a button that is the same as a radio button, except that when the user selects it, the button automatically highlights itself and removes the selection from any other buttons in the same group.

BS_CHECKBOX	Creates a small empty square, with text displayed to its right, unless this style is combined with the BS_LEFTTEXT style.

BS_DEFPUSHBUTTON	Creates a button that has a heavy black border. The user can select this button by pressing the ENTER key. 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.

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_PUSHBOX	Unsupported. Applications should use BS_PUSHBUTTON instead.

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 that has text displayed to its right, unless this style is combined with the BS_LEFTTEXT style. Use radio buttons for groups of related but mutually exclusive choices.

BS_USERBUTTON	Obsolete. Applications should use BS_OWNERDRAW instead.


BN_CLICKED message
BN_CLICKED (Win32)

BN_CLICKED

idButton = (int) LOWORD(wParam);    /* identifier of button */

hwndButton = (HWND) lParam;         /* handle of button     */

The BN_CLICKED notification message is sent when the user clicks a mouse 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.

Comments

A disabled button does not send a BN_CLICKED notification message to its parent window.

See Also

WM_COMMAND


BN_DISABLE message
BN_DISABLE (Win32)

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

WM_COMMAND, WM_DRAWITEM


BN_DOUBLECLICKED message
BN_DOUBLECLICKED (Win32)

BN_DOUBLECLICKED

The BN_DOUBLECLICKED notification message is sent when the user double-clicks a mouse button. The parent window of the button receives this notification message through the WM_COMMAND 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.

Comments

This notification message applies only to buttons with the BS_RADIOBUTTON and BS_OWNERDRAW styles.

See Also

WM_COMMAND, WM_DRAWITEM


BN_HILITE message
BN_HILITE (Win32)

BN_HILITE

The BN_HILITE notification message is sent when the user highlights a button. The parent window of the button receives this notification message through the WM_COMMAND 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_UNHILITE, WM_COMMAND, WM_DRAWITEM


BN_PAINT message
BN_PAINT (Win32)

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

WM_COMMAND, WM_DRAWITEM


BN_UNHILITE message
BN_UNHILITE (Win32)

BN_HILITE

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. 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_HILITE, WM_COMMAND, WM_DRAWITEM


CB_ADDSTRING message
CB_ADDSTRING (Win32)

CB_ADDSTRING

wParam = 0;                         /* not used, must be zero   */

lParam = (LPARAM) (LPCSTR) lpsz;    /* address of string to add */

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.

Parameter	Description

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 rather than the string it would otherwise point to.

Returns

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.

Comments

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 message
CB_DELETESTRING (Win32)

CB_DELETESTRING

wParam = (WPARAM) index;  /* item to delete         */

lParam = 0;               /* not used, must be zero */

An application sends a CB_DELETESTRING message to delete a string in the list box of a combo box.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the string to delete.

Returns

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.

Comments

If you create the combo box with an owner-draw 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 message
CB_DIR (Win32)

CB_DIR

wParam = (WPARAM) (UINT) uAttrs;          /* file attributes     */

lParam = (LPARAM) (LPCTSTR) lpszFileSpec; /* address of filename */

An application sends a CB_DIR message to add a list of file names to the list box of a combo box.

Parameter	Description

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	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 any wildcards (for example, *.*), all files that match and have the attributes specified by the uAttrs parameter are added to the list.

Returns

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

DlgDirList, DlgDirListComboBox, CB_ADDSTRING, CB_INSERTSTRING


CB_FINDSTRING message
CB_FINDSTRING (Win32)

CB_FINDSTRING

wParam = (WPARAM) indexStart;     /* item before start of search */

lParam = (LPARAM) (LPCSTR) lpszFind;    /* prefix string address */

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.

Parameter	Description

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.

Returns

The return value is the zero-based index of the matching item. If the search is unsuccessful, it is CB_ERR.

Comments

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, what the CB_FINDSTRING message does depend 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. 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 message
CB_FINDSTRINGEXACT (Win32)

CB_FINDSTRINGEXACT

wParam = (WPARAM) indexStart;   /* item before start of search */

lParam = (LPARAM)(LPCSTR)lpszFind; /* address of prefix string */

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.

Parameter	Description

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.

Returns

The return value is the zero-based index of the matching item. If the search is unsuccessful, it is CB_ERR.

Comments

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 message
CB_GETCOUNT (Win32)

CB_GETCOUNT

wParam = 0;     /* not used, must be zero */

lParam = 0;     /* not used, must be zero */

An application sends a CB_GETCOUNT message to retrieve the number of items in the list box of a combo box.

Parameters

This message has no parameters.

Returns

The return value is the number of items in the list box. If an error occurs, it is CB_ERR.

Comments

The index is zero-based, so the returned count is one greater than the index value of the last item.


CB_GETCURSEL message
CB_GETCURSEL (Win32)

CB_GETCURSEL

wParam = 0;     /* not used, must be zero */

lParam = 0;     /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

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 message
CB_GETDROPPEDCONTROLRECT (Win32)

CB_GETDROPPEDCONTROLRECT

wParam = 0;                         /* not used, must be zero    */

lParam = (LPARAM) (RECT FAR*) lprc; /* address of RECT structure */

An application sends a CB_GETDROPPEDCONTROLRECT message to retrieve the screen coordinates of the drop-down list box of a combo box.

Parameter	Description

lprc	Value of lParam. Points to the RECT structure that is to receive the coordinates.

Returns

This message always returns CB_OKAY.


CB_GETDROPPEDSTATE message
CB_GETDROPPEDSTATE (Win32)

CB_GETDROPPEDSTATE

wParam = 0;     /* not used, must be zero */

lParam = 0;     /* not used, must be zero */

An application sends a CB_GETDROPPEDSTATE message to determine whether the list box of a combo box is dropped down.

Parameters

This message has no parameters.

Returns

If the list box is visible, the return value is TRUE; otherwise, it is FALSE.

See Also

CB_SHOWDROPDOWN


CB_GETEDITSEL message
CB_GETEDITSEL (Win32)

CB_GETEDITSEL

wParam = (WPARAM) (LPDWORD) lpdwStart; /* receives starting pos. */

lParam = (LPARAM) (LPDWORD) lpdwEnd;   /* receives ending pos.   */

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.

Parameter	Description

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.

Returns

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 message
CB_GETEXTENDEDUI (Win32)

CB_GETEXTENDEDUI

wParam = 0;     /* not used, must be zero */

lParam = 0;     /* not used, must be zero */

An application sends a CB_GETEXTENDEDUI message to determine whether a combo box has the default user interface or the extended user interface.

Parameters

This message has no parameters.

Returns

If the combo box has the extended user interface, the return value is TRUE; otherwise, it is FALSE.

Comments

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_GETITEMDATA message
CB_GETITEMDATA (Win32)

CB_GETITEMDATA

wParam = (WPARAM) index;  /* item index             */

lParam = 0;               /* not used, must be zero */

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.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the item.

Returns

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 message
CB_GETITEMHEIGHT (Win32)

CB_GETITEMHEIGHT

wParam = (WPARAM) index;  /* item index             */

lParam = 0;               /* not used, must be zero */

An application sends a CB_GETITEMHEIGHT message to determine the height of list items or the selection field in a combo box.

Parameter	Description

index	Value of wParam. Specifies the component of the combo box 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.

Returns

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 message
CB_GETLBTEXT (Win32)

CB_GETLBTEXT

wParam = (WPARAM) index;                /* item index        */

lParam = (LPARAM) (LPCSTR) lpszBuffer;  /* address of buffer */

An application sends a CB_GETLBTEXT message to retrieve a string from the list of a combo box.

Parameter	Description

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.

Returns

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.

Comments

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.

See Also

CB_GETLBTEXTLEN


CB_GETLBTEXTLEN message
CB_GETLBTEXTLEN (Win32)

CB_GETLBTEXTLEN

wParam = (WPARAM) index;  /* item index             */

lParam = 0;               /* not used, must be zero */

An application sends a CB_GETLBTEXTLEN message to retrieve the length, in characters, of a string in the list of a combo box.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the string.

Returns

The return value is the length of the string, in characters, excluding the terminating null character. If the index parameter does not specify a valid index, the return value is CB_ERR.

See Also

CB_GETLBTEXT


CB_GETLOCALE message
CB_GETLOCALE (Win32)

CB_GETLOCALE

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

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 word contains the language identifier.

Comments

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_INSERTSTRING message
CB_INSERTSTRING (Win32)

CB_INSERTSTRING

wParam = (WPARAM) index;         /* item index                  */

lParam = (LPARAM) (LPCSTR) lpsz; /* address of string to insert */

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.

Parameter	Description

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.

Returns

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 message
CB_LIMITTEXT (Win32)

CB_LIMITTEXT

wParam = (WPARAM) cchLimit;   /* maximum number of characters */

lParam = 0;                   /* not used, must be zero       */

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.

Parameter	Description

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.

Returns

The return value is always TRUE.

Comments

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 message
CB_RESETCONTENT (Win32)

CB_RESETCONTENT

wParam = 0;     /* not used, must be zero */

lParam = 0;     /* not used, must be zero */

An application sends a CB_RESETCONTENT message to remove all items from the list box and edit control of a combo box.

Parameters

This message has no parameters.

Returns

This message always returns CB_OKAY.

Comments

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 message
CB_SELECTSTRING (Win32)

CB_SELECTSTRING

wParam = (WPARAM) indexStart;     /* item before first selection */

lParam = (LPARAM) (LPCSTR) lpszSelect; /* addr. of prefix string */

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.

Parameter	Description

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.

Returns

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.

Comments

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 doubleword value against the value of the lpszFind parameter.

See Also

CB_FINDSTRING, CB_FINDSTRINGEXACT, CB_SETCURSEL, WM_COMPAREITEM


CB_SETCURSEL message
CB_SETCURSEL (Win32)

CB_SETCURSEL

wParam = (WPARAM) index;  /* item index             */

lParam = 0;               /* not used, must be zero */

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.

Parameter	Description

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.

Returns

If the message is successful, the return value is the index of the item selected. If the index parameter 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_SETEDITSEL message
CB_SETEDITSEL (Win32)

CB_SETEDITSEL

wParam = 0;                           /* not used, must be zero */

lParam = MAKELPARAM((ichStart), (ichEnd);  /* start and end pos */

An application sends a CB_SETEDITSEL message to select characters in the edit control of a combo box.

Parameter	Description

ichStart	Value of the low-order word of lParam. 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. 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.

Returns

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.

Comments

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 message
CB_SETEXTENDEDUI (Win32)

CB_SETEXTENDEDUI

wParam = (WPARAM) (BOOL) fExtended;    /* extended UI flag       */

lParam = 0;                            /* not used, must be zero */

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.

Parameter	Description

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.

Returns

If the operation succeeds, the return value is CB_OKAY. If an error occurs, it is CB_ERR.

Comments

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_SETITEMDATA message
CB_SETITEMDATA (Win32)

CB_SETITEMDATA

wParam = (WPARAM) index;            /* item index */

lParam = (LPARAM) (DWORD) dwData;   /* item data  */

An application sends a CB_SETITEMDATA message to set the 32-bit value associated with the specified item in a combo box.

Parameter	Description

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.

Returns

If an error occurs, the return value is CB_ERR.

Comments

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 message
CB_SETITEMHEIGHT (Win32)

CB_SETITEMHEIGHT

wParam = (WPARAM) index;        /* item index  */

lParam = (LPARAM) (int) height; /* item height */

An application sends a CB_SETITEMHEIGHT message to set the height of list items or the selection field in a combo box.

Parameter	Description

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.

Returns

If the index or height is invalid, the return value is CB_ERR.

Comments

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 message
CB_SETLOCALE (Win32)

CB_SETLOCALE

wParam = (WPARAM) (WORD) wLocaleID; /* locale identifier      */

lParam = 0;                         /* not used, must be zero */

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.

Parameter	Description

wLocaleID	Value of wParam. Specifies the locale identifier for the combo box to use for sorting when adding text.

Returns

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.

Comments

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_SHOWDROPDOWN message
CB_SHOWDROPDOWN (Win32)

CB_SHOWDROPDOWN

wParam = (WPARAM) (BOOL) fShow;     /* the show/hide flag     */

lParam = 0;                         /* not used, must be zero */

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.

Parameter	Description

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.

Returns

The return value is always TRUE.

Comments

This message has no effect on a combo box created with the CBS_SIMPLE style.

See Also

CB_GETDROPPEDSTATE


CBN_CLOSEUP message
CBN_CLOSEUP (Win32)

CBN_CLOSEUP

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND) lParam;       /* handle of combo box     */

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.

Comments

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 may occur either before or after a CBN_CLOSEUP notification.

See Also

CBN_DROPDOWN, CBN_SELCHANGE, WM_COMMAND


CBN_DBLCLK message
CBN_DBLCLK (Win32)

CBN_DBLCLK

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND) lParam;       /* handle of combo box     */

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.

Comments

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 message
CBN_DROPDOWN (Win32)

CBN_DROPDOWN

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND) lParam;       /* handle of combo box     */

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.

Comments

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 message
CBN_EDITCHANGE (Win32)

CBN_EDITCHANGE

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND)lParam;        /* handle of combo box     */

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.

Comments

If the combo box has the CBS_DROPDOWNLIST style, this notification message does not occur.

See Also

CBN_EDITUPDATE, WM_COMMAND


CBN_EDITUPDATE message
CBN_EDITUPDATE (Win32)

CBN_EDITUPDATE

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND) lParam;       /* handle of combo box     */

The CBN_EDITUPDATE notification message is sent when the edit control portion of a combo box is about to display altered text. This notification 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.

Comments

If the combo box has the CBS_DROPDOWNLIST style, this notification message does not occur.

See Also

CBN_EDITCHANGE, WM_COMMAND


CBN_ERRSPACE message
CBN_ERRSPACE (Win32)

CBN_ERRSPACE

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND) lParam;       /* handle of combo box     */

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.

See Also

WM_COMMAND


CBN_KILLFOCUS message
CBN_KILLFOCUS (Win32)

CBN_KILLFOCUS

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND) lParam;       /* handle of combo box     */

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.

See Also

CBN_SETFOCUS, WM_COMMAND


CBN_SELCHANGE message
CBN_SELCHANGE (Win32)

CBN_SELCHANGE

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND) lParam;       /* handle of combo box     */

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.

See Also

CBN_DBLCLK, WM_COMMAND


CBN_SELENDCANCEL message
CBN_SELENDCANCEL (Win32)

CBN_SELENDCANCEL

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND) lParam;       /* handle of combo box     */

The CBN_SELENDCANCEL notification 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.

Comments

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 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_SELENDOK, WM_COMMAND


CBN_SELENDOK message
CBN_SELENDOK (Win32)

CBN_SELENDOK

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND) lParam;       /* handle of combo box     */

The CBN_SELENDOK notification is sent when the user clicks a list item, or selects an item and then closes the list. It indicates the user's selection is to be processed. The parent window of the combo box receives this notification message through the WM_COMMAND message.

Comments

In a combo box with the CBS_SIMPLE style, the CBN_SELENDOK notification message is sent immediately before every CBN_SELCHANGE 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_SELENDCANCEL, WM_COMMAND


CBN_SETFOCUS message
CBN_SETFOCUS (Win32)

CBN_SETFOCUS

idComboBox = (int) LOWORD(wParam);  /* identifier of combo box */

hwndComboBox = (HWND) lParam;       /* handle of combo box     */

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.

See Also

CBN_KILLFOCUS, WM_COMMAND


CPL_DBLCLK message
CPL_DBLCLK (Win32)

CPL_DBLCLK

uAppNum = (UINT) lParam1;   /* application number        */

lData = (LONG) lParam2;     /* application-defined value */

The CPL_DBLCLK message is sent to a Windows Control Panel dynamic-link library (DLL) when the user double-clicks the icon of an application supported by the DLL.

Parameter	Description

uAppNum	Value of lParam1. Specifies the application 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 DLL loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the application. The DLL loads lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Returns

If a Control Panel DLL processes this message successfully, the return value is zero; otherwise, it is nonzero.

Comments

In response to this message, a Control Panel DLL must display the dialog box for the application.

See Also

CPL_GETCOUNT, CPL_INQUIRE, CPL_NEWINQUIRE, CPL_SELECT, CPLINFO, NEWCPLINFO


CPL_EXIT message
CPL_EXIT (Win32)

CPL_EXIT

The CPL_EXIT message is sent once to a Windows Control Panel dynamic-link library (DLL) before Control Panel calls the FreeLibrary function to free the DLL.

Returns

If a Control Panel DLL processes this message successfully, it should return zero.

Comments

This message is sent after the last WM_STOP message is sent.

In response to this message, a Control Panel DLL must free any memory that it has allocated and perform global-level cleanup.

See Also

CPL_STOP, FreeLibrary


CPL_GETCOUNT message
CPL_GETCOUNT (Win32)

CPL_GETCOUNT

The CPL_GETCOUNT message is sent to a Windows Control Panel dynamic-link library (DLL) to retrieve the number of applications the DLL services.

Returns

A Control Panel DLL should return the number of applications it services.

Comments

This message is sent immediately after the CPL_INIT message.

See Also

CPL_INIT


CPL_INIT message
CPL_INIT (Win32)

CPL_INIT

The CPL_INIT message is sent to a Windows Control Panel dynamic-link library (DLL) to prompt the DLL to perform global initialization, especially memory allocation.

Returns

If initialization succeeds, a Control Panel DLL should return nonzero. Otherwise, it should return zero. If the DLL returns zero, Control Panel calls the FreeLibrary function and ends communication with the DLL.

Comments

Because this is the only way a Control Panel DLL can signal an error condition, the DLL should allocate memory in response to this message.

This message is sent immediately after the DLL is loaded.

See Also

FreeLibrary


CPL_INQUIRE message
CPL_INQUIRE (Win32)

CPL_INQUIRE

uAppNum = (UINT) lParam1;     /* application number              */

lpcpli = (LPCPLINFO) lParam2; /* structure for application info. */

The CPL_INQUIRE message is sent to a Windows Control Panel dynamic-link library (DLL) to request information about an application that the DLL supports.

This message is provided for backward compatibility with Windows, version 3.1. Use the CPL_NEWINQUIRE message instead of the CPL_INQUIRE message for new applications.

Parameter	Description

uAppNum	Value of lParam1. Specifies the application 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 DLL must fill this structure with resource identifiers for the icon, short name, description, and any user-defined value associated with the application.

Returns

If a Control Panel DLL processes this message successfully, it should return zero.

Comments

This message is sent once for each application serviced by the DLL. It is sent immediately after the CPL_GETCOUNT message. A DLL can perform application-level initialization when it receives this message. If the DLL must allocate memory, it should do so in response to the CPL_INIT message.

See Also

CPL_GETCOUNT, CPL_INIT, CPL_NEWINQUIRE, CPLINFO, NEWCPLINFO


CPL_NEWINQUIRE message
CPL_NEWINQUIRE (Win32)

CPL_NEWINQUIRE

uAppNum = (UINT) lParam1;         /* application number        */

lpncpli = (LPNEWCPLINFO) lParam2; /* structure for appl. info. */

The CPL_NEWINQUIRE message is sent to a Windows Control Panel dynamic-link library (DLL) to request information about an application that the DLL supports.

Parameter	Description

uAppNum	Value of lParam1. Specifies the application 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 a far pointer to a NEWCPLINFO structure. The DLL should fill this structure with information about the application.

Returns

If a Control Panel DLL processes this message successfully, it should return zero.

Comments

This message is sent once for each application serviced by the DLL. It is sent immediately after the CPL_GETCOUNT message. Upon receiving this message, a DLL can do application-level initialization. If the DLL must allocate memory, it should do so in response to the CPL_INIT message.

See Also

CPL_GETCOUNT, CPL_INIT, CPL_INQUIRE, CPLINFO, NEWCPLINFO


CPL_SELECT message
CPL_SELECT (Win32)

CPL_SELECT

uAppNum = (UINT) lParam1;   /* application number        */

lData = (LONG) lParam2;     /* application-defined value */

The CPL_SELECT message from Windows Control Panel is sent to a Control Panel dynamic-link library (DLL) when the user selects the icon of an application supported by the DLL.

Parameter	Description

uAppNum	Value of lParam1. Specifies the application number.

lData	Value of lParam2. Specifies the value that the Control Panel DLL loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the application. The DLL loads lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Returns

If a Control Panel DLL processes this message successfully, it should return zero.

See Also

CPL_DBLCLK, CPL_INQUIRE, CPL_NEWINQUIRE, CPLINFO, NEWCPLINFO


CPL_STOP message
CPL_STOP (Win32)

CPL_STOP

uAppNum = (UINT) lParam1;   /* application number        */

lData = (LONG) lParam2;     /* application-defined value */

The CPL_STOP message is sent once for each application when Windows Control Panel closes.

Parameter	Description

uAppNum	Value of lParam1. Specifies the application number.

lData	Value of lParam2. Specifies the value that the Control Panel DLL loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the application. The DLL loads lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Returns

If a Control Panel DLL processes this message successfully, it should return zero.

Comments

In response to this message, a Control Panel DLL must perform application-specific cleanup.

See Also

CPL_EXIT, CPL_GETCOUNT, CPL_INQUIRE, CPL_NEWINQUIRE, CPLINFO, NEWCPLINFO


DM_GETDEFID message
DM_GETDEFID (Win32)

DM_GETDEFID

An application sends a DM_GETDEFID message to retrieve the identifier of the default push button control for a dialog box.

Parameters

This message has no parameters.

Returns

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.

Comments

The DefDlgProc function processes this message.

See Also

DefDlgProc, DM_SETDEFID


DM_SETDEFID message
DM_SETDEFID (Win32)

DM_SETDEFID

wParam = idControl; /* identifier of new default push button */

An application sends a DM_SETDEFID message to change the identifier of the default push button for a dialog box.

Parameter	Description

idControl	Value of wParam. Specifies the identifier of a push button control that will become the default.

Comments

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

Returns

The return value is always TRUE.

See Also

DefDlgProc, BM_SETSTYLE, DM_GETDEFID, WM_GETDLGCODE


EM_CANUNDO message
EM_CANUNDO (Win32)

EM_CANUNDO

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

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_EMPTYUNDOBUFFER message
EM_EMPTYUNDOBUFFER (Win32)

EM_EMPTYUNDOBUFFER

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

This message does not return a value.

Comments

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_FMTLINES message
EM_FMTLINES (Win32)

EM_FMTLINES

wParam = (WPARAM) (BOOL) fAddEOL;   /* line break flag        */

lParam = 0;                         /* not used, must be zero */

An application sends an EM_FMTLINES message to set the inclusion flag of soft line-break characters on or off within a multiline edit control. A soft line break consists of two carriage returns and a linefeed and is inserted at the end of a line that is broken because of wordwrapping.

Parameter	Description

fAddEOL	Value of wParam. Specifies whether soft-line break characters are to be inserted. A value of TRUE inserts the characters; a value of FALSE removes them.

Returns

The return value is identical to the fAddEOL parameter.

Comments

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 line break. A hard line break 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_GETFIRSTVISIBLELINE message
EM_GETFIRSTVISIBLELINE (Win32)

EM_GETFIRSTVISIBLELINE

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an EM_GETFIRSTVISIBLELINE message to determine the uppermost visible line in an edit control.

Parameters

This message has no parameters.

Returns

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 message
EM_GETHANDLE (Win32)

EM_GETHANDLE

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an EM_GETHANDLE message to retrieve a handle of the memory currently allocated for a multiline edit control's text.

Parameters

This message has no parameters.

Returns

The return value is a memory handle identifying the buffer that holds the contents of the edit control. If an error occurs, such as sending the message to a single-line edit control, the return value is zero.

Comments

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_GETLINE message
EM_GETLINE (Win32)

EM_GETLINE

wParam = (WPARAM) line;          /* line number to retrieve    */

lParam = (LPARAM) (LPCSTR) lpch; /* address of buffer for line */

An application sends an EM_GETLINE message to copy a line of text from an edit control and place it in a specified buffer.

Parameter	Description

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.

Returns

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.

Comments

The copied line does not contain a terminating null character.

See Also

EM_LINELENGTH, WM_GETTEXT


EM_GETLINECOUNT message
EM_GETLINECOUNT (Win32)

EM_GETLINECOUNT

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an EM_GETLINECOUNT message to retrieve the number of lines in a multiline edit control.

Parameters

This message has no parameters.

Returns

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_GETMODIFY message
EM_GETMODIFY (Win32)

EM_GETMODIFY

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an EM_GETMODIFY message to determine whether the contents of an edit control have been modified.

Parameters

This message has no parameters.

Returns

If the contents of edit control have been modified, the return value is TRUE; otherwise, it is FALSE.

Comments

Windows maintains an internal flag indicating whether the contents of the edit control have 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_GETPASSWORDCHAR message
EM_GETPASSWORDCHAR (Win32)

EM_GETPASSWORDCHAR

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an EM_GETPASSWORDCHAR message to retrieve the password character displayed in an edit control when the user enters text.

Parameters

This message has no parameters.

Returns

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.

Comments

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_GETRECT message
EM_GETRECT (Win32)

EM_GETRECT

wParam = 0;                    /* not used, must be zero         */

lParam (LPARAM) (LPRECT) lprc; /* address of structure for rect. */

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.

Parameter	Description

lprc	Value of lParam. Points to the RECT structure that receives the formatting rectangle.

Returns

The return value is not a meaningful value.

Comments

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


EM_GETSEL message
EM_GETSEL (Win32)

EM_GETSEL

wParam = (WPARAM) (LPDWORD) lpdwStart; /* receives starting pos. */

lParam = (WPARAM) (LPDWORD) lpdwEnd;   /* receives ending pos.   */

An application sends an EM_GETSEL message to get the starting and ending character positions of the current selection in an edit control.

Parameter	Description

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.

Returns

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.

See Also

EM_SETSEL


EM_GETWORDBREAKPROC message
EM_GETWORDBREAKPROC (Win32)

EM_GETWORDBREAKPROC

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an EM_GETWORDBREAKPROC message to an edit control to retrieve the address of the current wordwrap function.

Parameters

This message has no parameters.

Returns

The return value specifies the address of the application-defined wordwrap function. The return value is NULL if no wordwrap function exists.

Comments

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_LIMITTEXT message
EM_LIMITTEXT (Win32)

EM_LIMITTEXT

wParam = (WPARAM) cchMax;   /* text length            */

lParam = 0;                 /* not used, must be zero */

An application sends an EM_LIMITTEXT message to limit the amount of text the user may enter into an edit control.

Parameter	Description

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.

Returns

This message does not return a value.

Comments

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.

See Also

WM_SETTEXT


EM_LINEFROMCHAR message
EM_LINEFROMCHAR (Win32)

EM_LINEFROMCHAR

wParam = (WPARAM) ich;  /* character index        */

lParam = 0;             /* not used, must be zero */

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.

Parameter	Description

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.

Returns

The return value is the zero-based line number of the line containing the character index specified by ich.

See Also

EM_LINEINDEX


EM_LINEINDEX message
EM_LINEINDEX (Win32)

EM_LINEINDEX

wParam = (WPARAM) line; /* line number            */

lParam = 0;             /* not used, must be zero */

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.

Parameter	Description

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

Returns

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 message
EM_LINELENGTH (Win32)

EM_LINELENGTH

wParam = (WPARAM) ich;  /* character index        */

lParam = 0;             /* not used, must be zero */

An application sends an EM_LINELENGTH message to retrieve the length of a line, in characters, in an edit control.

Parameter	Description

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

Returns

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.

Comments

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 message
EM_LINESCROLL (Win32)

EM_LINESCROLL

wParam = (WPARAM) cxScroll; /* characters to scroll horizontally */

lParam = (LPARAM) cyScroll; /* lines to scroll vertically        */

An application sends an EM_LINESCROLL message to scroll the text vertically or horizontally in a multiline edit control.

Parameter	Description

cxScroll	Value of wParam. Specifies the number of characters to scroll horizontally.

cyScroll	Value of lParam. Specifies the number of lines to scroll vertically.

Returns

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.

Comments

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_REPLACESEL message
EM_REPLACESEL (Win32)

EM_REPLACESEL

wParam = 0;                               /* not used, must be zero */

lParam = (LPARAM) (LPCTSTR) lpszReplace;  /* address of string      */

An application sends an EM_REPLACESEL message to replace the current selection in an edit control with the specified text.

Parameter	Description

lpszReplace	Value of lParam. Points to a null-terminated string containing the replacement text.

Returns

This message does not return a value.

Comments

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_SCROLL message
EM_SCROLL (Win32)

EM_SCROLL

wParam = (WPARAM) (INT) nScroll;    /* scroll action          */

lParam = 0;                         /* not used, must be zero */

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.

Parameter	Description

nScroll	Value of wParam. Specifies the action the scroll bar is to take. This parameter may be one of the following values:

Value	Description

SB_LINEDOWN	Scroll down one line.

SB_LINEUP	Scroll up one line.

SB_PAGEDOWN	Scroll down one page.

SB_PAGEUP	Scroll up one page.

Returns

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.

Comments

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 message
EM_SCROLLCARET (Win32)

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

An application sends an EM_SCROLLCARET message to scroll the caret into view in an edit control.

Parameter	Description

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.

Returns

The return value is nonzero if the message is sent to an edit control.

Comments

In previous versions of Windows, scrolling the caret into view was done by specifying fScroll = FALSE in the EM_SETSEL message. A Win32 application should use the EM_SCROLLCARET message to scroll the caret into view.

See Also

EM_SETSEL


EM_SETHANDLE message
EM_SETHANDLE (Win32)

EM_SETHANDLE

wParam = (WPARAM) (HLOCAL) hloc; /* handle of memory buffer */

lParam = 0;                      /* not used, must be zero  */

An application sends an EM_SETHANDLE message to set the handle of the memory that will be used by a multiline edit control.

Parameter	Description

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.

Returns

This message does not return a value.

Comments

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_SETMODIFY message
EM_SETMODIFY (Win32)

EM_SETMODIFY

wParam = (WPARAM) (UINT) fModified;    /* modification flag      */

lParam = 0;                            /* not used, must be zero */

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.

Parameter	Description

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.

Returns

This message does not return a value.

See Also

EM_GETMODIFY


EM_SETPASSWORDCHAR message
EM_SETPASSWORDCHAR (Win32)

EM_SETPASSWORDCHAR

wParam = (WPARAM) (UINT) ch;    /* character to display   */

lParam = 0;                     /* not used, must be zero */

An application sends an EM_SETPASSWORDCHAR message to set or remove a password character displayed in 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.

Parameter	Description

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.

Returns

This message does not return a value.

Comments

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_SETREADONLY message
EM_SETREADONLY (Win32)

EM_SETREADONLY

wParam = (WPARAM) (BOOL) fReadOnly;  /* read-only flag         */

lParam = 0L;                         /* not used, must be zero */

An application sends an EM_SETREADONLY message to set or remove the read-only style (ES_READONLY) of an edit control.

Parameter	Description

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.

Returns

If the operation succeeds, the return value is nonzero; otherwise, it is zero.

Comments

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 message
EM_SETRECT (Win32)

EM_SETRECT

wParam = 0;                         /* not used, must be zero   */

lParam = (LPARAM) (LPRECT) lprc;    /* address of new rectangle */

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.

Parameter	Description

lprc	Value of lParam. Points to a RECT structure that specifies the new dimensions of the rectangle.

Returns

This message does not return a value.

Comments

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


EM_SETRECTNP message
EM_SETRECTNP (Win32)

EM_SETRECTNP

wParam = 0;                         /* not used, must be zero   */

lParam = (LPARAM) (LPRECT) lprc;    /* address of new rectangle */

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.

Parameter	Description

lprc	Value of lParam. Points to a RECT structure that specifies the new dimensions of the rectangle.

Returns

This message does not return a value.

See Also

EM_SETRECT


EM_SETSEL message
EM_SETSEL (Win32)

EM_SETSEL

wParam = (WPARAM) (INT) nStart;    /* starting position */

lParam = (LPARAM) (INT) nEnd;      /* ending position   */

An application sends an EM_SETSEL message to select a range of characters in an edit control.

Parameter	Description

nStart	Value of wParam. Specifies the starting character position of the selection.

nEnd	Specifies the ending character position of the selection.

Returns

This message does not return a value.

Comments

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 FALSE to scroll the caret into view or TRUE to omit the scrolling. A Win32 application should use the EM_SCROLLCARET message to scroll the caret into view.

In previous 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_SETTABSTOPS message
EM_SETTABSTOPS (Win32)

EM_SETTABSTOPS

wParam = (WPARAM) cTabs;             /* number of tab stops */

lParam = (LPARAM) (LPWORD) lpwTabs;  /* tab stop array      */

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.

Parameter	Description

cTabs	Value of wParam. Specifies the number of tab stops contained in the lpwTabs parameter. If this parameter is zero, the lpwTabs 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 lpwTabs parameter. If the cTabs parameter is greater than 1, lpwTabs points to an array of tab stops.

lpwTabs	Value of lParam. Points to an array of unsigned integers specifying the tab stops, in dialog units. If the cTabs parameter is 1, lpwTabs points to an unsigned integer containing the distance between all tab stops, in dialog box units.

Returns

If all the tabs are set, the return value is TRUE; otherwise, it is FALSE.

Comments

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_SETWORDBREAK message
EM_SETWORDBREAK (Win32)

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 message
EM_SETWORDBREAKPROC (Win32)

EM_SETWORDBREAKPROC

wParam = 0;                                 /* not used, must be zero */

lParam = (LPARAM)(EDITWORDBREAKPROC)ewbprc; /* function address       */

An application sends the EM_SETWORDBREAKPROC message to an edit control to replace the default wordwrap function with an application-defined wordwrap function.

Parameter	Description

ewbprc	Value of lParam. Specifies the address of the application-defined wordwrap function. For more information, see the description of the EditWordBreakProc callback function.

Returns

This message does not return a value.

Comments

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_UNDO message
EM_UNDO (Win32)

EM_UNDO

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an EM_UNDO message to undo the last edit control operation.

Parameters

This message has no parameters.

Returns

For a single-line edit control, the return value is always TRUE. For a multiple-line edit control, the return value is TRUE if the undo operation is successful, or FALSE if the undo operation fails.

Comments

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 message
EN_CHANGE (Win32)

EN_CHANGE

idEditCtrl = (int) LOWORD(wParam); /* identifier of edit control */

hwndEditCtrl = (HWND) lParam;      /* handle of edit control     */

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.

See Also

EN_UPDATE, WM_COMMAND


EN_ERRSPACE message
EN_ERRSPACE (Win32)

EN_ERRSPACE

idEditCtrl = (int) LOWORD(wParam); /* identifier of edit control */

hwndEditCtrl = (HWND) lParam;      /* handle of edit control     */

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.

See Also

WM_COMMAND


EN_HSCROLL message
EN_HSCROLL (Win32)

EN_HSCROLL

idEditCtrl = (int) LOWORD(wParam); /* identifier of edit control */

hwndEditCtrl = (HWND) lParam;      /* handle of edit control     */

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.

See Also

EN_VSCROLL, WM_COMMAND


EN_KILLFOCUS message
EN_KILLFOCUS (Win32)

EN_KILLFOCUS

idEditCtrl = (int) LOWORD(wParam); /* identifier of edit control */

wNotifyCode = HIWORD(wParam);      /* notification code */

hwndEditCtrl = (HWND) lParam;      /* handle of edit control     */

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.

Comments

In previous versions of Windows, the notification code was in HIWORD(lParam).

See Also

EN_SETFOCUS, WM_COMMAND


EN_MAXTEXT message
EN_MAXTEXT (Win32)

EN_MAXTEXT

idEditCtrl = (int) LOWORD(wParam); /* identifier of edit control */

hwndEditCtrl = (HWND) lParam;      /* handle of edit control     */

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.

See Also

EM_LIMITTEXT, WM_COMMAND


EN_SETFOCUS message
EN_SETFOCUS (Win32)

EN_SETFOCUS

idEditCtrl = (int) LOWORD(wParam); /* identifier of edit control */

wNotifyCode = HIWORD(wParam);      /* notification code */

hwndEditCtrl = (HWND) lParam;      /* handle of edit control     */

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.

Comments

In previous versions of Windows, the notification code was in HIWORD(lParam).

See Also

EN_KILLFOCUS, WM_COMMAND


EN_UPDATE message
EN_UPDATE (Win32)

EN_UPDATE

idEditCtrl = (int) LOWORD(wParam); /* identifier of edit control */

hwndEditCtrl = (HWND) lParam;      /* handle of edit control     */

The EN_UPDATE notification message is sent when an edit control is about to display altered text. This notification 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.

See Also

EN_CHANGE, WM_COMMAND


EN_VSCROLL message
EN_VSCROLL (Win32)

EN_VSCROLL

idEditCtrl = (int) LOWORD(wParam); /* identifier of edit control */

hwndEditCtrl = (HWND) lParam;      /* handle of edit control     */

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.

See Also

EN_HSCROLL, WM_COMMAND


FM_GETDRIVEINFO message
FM_GETDRIVEINFO (Win32)

FM_GETDRIVEINFO

wParam = 0;                            /* not used, must be zero */

lParam = (LPARAM) (LPFMS_GETDRIVEINFO) lpfmsgdi;   /* drive data */

A File Manager extension sends an FM_GETDRIVEINFO message to retrieve drive information from the active File Manager window.

Parameter	Description

lpfmsgdi	Value of lParam. Points to an FMS_GETDRIVEINFO structure that receives drive information.

Returns

The return value is always nonzero.

Comments

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 message
FM_GETFILESEL (Win32)

FM_GETFILESEL

wParam = (WPARAM) index;               /* index of selected file */

lParam = (LPARAM) (LPFMS_GETFILESEL) lpfmsgfs;      /* file data */

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

Parameter	Description

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.

Returns

The return value is the zero-based index of the selected file that was retrieved.

Comments

An extension can use the FM_GETSELCOUNT message to get the count of selected files.

See Also

FMExtensionProc, FM_GETFILESELLFN, FM_GETSELCOUNT, FM_GETSELCOUNTLFN, FMS_GETFILESEL


FM_GETFILESELLFN message
FM_GETFILESELLFN (Win32)

FM_GETFILESELLFN

wParam = (WPARAM) index;               /* index of selected file */

lParam = (LPARAM) (LPFMS_GETFILESEL) lpfmsgfs; /* selection data */

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.

Parameter	Description

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.

Returns

The return value is the zero-based index of the selected file that was retrieved.

Comments

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, FMS_GETFILESEL


FM_GETFOCUS message
FM_GETFOCUS (Win32)

FM_GETFOCUS

wParam = 0;     /* not used, must be zero */

lParam = 0;     /* not used, must be zero */

A File Manager extension sends a FM_GETFOCUS message to retrieve the type of the File Manager window that has the input focus.

Parameters

This message has no parameters.

Returns

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 message
FM_GETSELCOUNT (Win32)

FM_GETSELCOUNT

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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

Parameters

This message has no parameters.

Returns

The return value is the number of selected files.

See Also

FM_GETFILESEL, FM_GETFILESELLFN, FM_GETSELCOUNTLFN


FM_GETSELCOUNTLFN message
FM_GETSELCOUNTLFN (Win32)

FM_GETSELCOUNTLFN

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

The return value is the number of selected files.

Comments

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 message
FM_REFRESH_WINDOWS (Win32)

FM_REFRESH_WINDOWS

wParam = (WPARAM) (BOOL) fRepaint;  /* repaint flag           */

lParam = 0;                         /* not used, must be zero */

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.

Parameter	Description

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.

Returns

This message does not return a meaningful value.

Comments

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 message
FM_RELOAD_EXTENSIONS (Win32)

FM_RELOAD_EXTENSIONS

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

This message does not return a meaningful value.

Comments

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 message
FMEVENT_HELPMENUITEM (Win32)

FMEVENT_HELPMENUITEM

uItem = (UINT) lParam;  /* command item for which help is sought */

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.

Parameter	Description

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.

Returns

An extension DLL procedure should return zero if it processes this message.

See Also

FMExtensionProc, WinHelp, FMEVENT_HELPSTRING


FMEVENT_HELPSTRING message
FMEVENT_HELPSTRING (Win32)

FMEVENT_HELPSTRING

lpfmshs = (LPFMS_HELPSTRING) lParam;  /* pointer to data transfer structure */

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.

Parameter	Description

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.

Returns

An extension DLL procedure should return zero if it processes this message.

See Also

FMExtensionProc, FMEVENT_HELPMENUITEM, FMS_HELPSTRING


FMEVENT_INITMENU message
FMEVENT_INITMENU (WIn32)

FMEVENT_INITMENU

hmenu = (HMENU) lParam; /* handle of File Manager menu */

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.

Parameter	Description

hmenu	Specifies the handle of the File Manager menu bar.

Returns

An extension DLL should return zero if it processes this message.

Comments

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 message
FMEVENT_LOAD (Win32)

FMEVENT_LOAD

lpfmsld = (LPFMS_LOAD) lParam;  /* address of struct. with delta */

The FMEVENT_LOAD message is sent to an extension DLL when File Manager is loading the DLL.

Parameter	Description

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.

Returns

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.

Comments

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


FMEVENT_SELCHANGE message
FMEVENT_SELCHANGE (Win32)

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.

Parameters

This message has no parameters.

Returns

An extension DLL should return zero if it processes this message.

Comments

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 message
FMEVENT_TOOLBARLOAD (Win32)

FMEVENT_TOOLBARLOAD

lpfmstbl = (LPFMS_TOOLBARLOAD) lParam;   /* toolbar data */

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.

Parameter	Description

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.

Returns

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


FMEVENT_UNLOAD message
FMEVENT_UNLOAD (Win32)

FMEVENT_UNLOAD

The FMEVENT_UNLOAD message is sent to an extension DLL when File Manager is unloading the DLL.

Parameters

This message has no parameters.

Returns

An extension DLL should return zero if it processes this message.

Comments

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 message
FMEVENT_USER_REFRESH (Win32)

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.

Parameters

This message has no parameters.

Returns

An extension DLL should return zero if it processes this message.

See Also

FMExtensionProc


LB_ADDFILE message
LB_ADDFILE (Win32)

LB_ADDFILE

wParam = 0;                               /* not used, must be zero */

lParam = (LPARAM) (LPCTSTR) lpszFilename; /* name of file to add    */

An application sends an LB_ADDFILE message to add the specified filename to a list box that contains a directory listing.

Parameter	Description

lpszFilename	Value of lParam. Points to the name of the file to add.

Returns

The return value is the zero-based index of the file that was added, or LB_ERR if an error occurs.

Comments

The list box to which lpszFilename is added must have been filled by the DlgDirList function.

See Also

DlgDirList, LB_ADDSTRING


LB_ADDSTRING message
LB_ADDSTRING (Win32)

LB_ADDSTRING

wParam = 0;                         /* not used, must be zero   */

lParam = (LPARAM) (LPCTSTR) lpsz;   /* address of string to add */

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.

Parameter	Description

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 instead of the string it would otherwise point to.

Returns

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.

Comments

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 message
LB_DELETESTRING (Win32)

LB_DELETESTRING

wParam = (WPARAM) index;    /* index of string to delete */

lParam = 0;                 /* not used, must be zero    */

An application sends an LB_DELETESTRING message to delete a string in a list box.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the string to be deleted.

Returns

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.

Comments

If you create 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 message
LB_DIR (Win32)

LB_DIR

wParam = (WPARAM) (UINT) uAttrs;          /* file attributes  */

lParam = (LPARAM) (LPCTSTR) lpszFileSpec; /* filename address */

An application sends an LB_DIR message to add a list of filenames to a list box.

Parameter	Description

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.

Returns

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 message
LB_FINDSTRING (Win32)

LB_FINDSTRING

wParam = (WPARAM) indexStart;     /* item before start of search */

lParam = (LPARAM) (LPCTSTR) lpszFind;   /* search string address */

An application sends an LB_FINDSTRING message to find the first string in a list box that contains the specified prefix.

Parameter	Description

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.

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.

Returns

The return value is the index of the matching item, or LB_ERR if the search was unsuccessful.

Comments

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 lpszFind parameter.

See Also

LB_ADDSTRING, LB_INSERTSTRING, LB_SELECTSTRING


LB_FINDSTRINGEXACT message
LB_FINDSTRINGEXACT (Win32)

LB_FINDSTRINGEXACT

wParam = (WPARAM) indexStart;   /* item before start of search */

lParam = (LPARAM)(LPCSTR)lpszFind; /* address of search string */

An application sends a LB_FINDSTRINGEXACT message to find the first list box string that matches the string specified in the lpszFind parameter.

Parameter	Description

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 &(EN_DASH)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.

Returns

The return value is the zero-based index of the matching item, or LB_ERR if the search was unsuccessful.

Comments

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the action taken by the LB_FINDSTRINGEXACT message depends on whether the LBS_SORT style is used. If the LBS_SORT style is used, the system sends WM_COMPAREITEM messages to the owner of the list box 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 message
LB_GETANCHORINDEX (Win32)

LB_GETANCHORINDEX

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an LB_GETANCHORINDEX message to retrieve the index of the anchor item.

Parameters

This message has no parameters.

Returns

The return value is the index of the current anchor item--that is, the item most recently selected by the user pressing a mouse button.

Comments

In a multiple-selection list box, the anchor item is the first or last item in a block of contiguous selected items.

See Also

LB_SETANCHORINDEX


LB_GETCARETINDEX message
LB_GETCARETINDEX (Win32)

LB_GETCARETINDEX

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

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 message
LB_GETCOUNT (Win32)

LB_GETCOUNT

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an LB_GETCOUNT message to retrieve the number of items in a list box.

Parameters

This message has no parameters.

Returns

The return value is the number of items in the list box, or LB_ERR if an error occurs.

Comments

The returned count is one greater then the index value of the last item (the index is zero-based).

See Also

LB_SETCOUNT


LB_GETCURSEL message
LB_GETCURSEL (Win32)

LB_GETCURSEL

wParam = 0;     /* not used, must be zero */

lParam = 0;     /* not used, must be zero */

An application sends an LB_GETCURSEL message to retrieve the index of the currently selected item, if any, in a single-selection list box.

Parameters

This message has no parameters.

Returns

The return value is the zero-based index of the currently selected item, or LB_ERR if no item is currently selected.

Comments

Use the LB_GETCARETINDEX message to retrieve the index of the item that has the focus rectangle in a multiple-selection list box. An application cannot send the LB_GETCURSEL message to a multiple-selection list box.

See Also

LB_GETCARETINDEX, LB_SETCURSEL


LB_GETHORIZONTALEXTENT message
LB_GETHORIZONTALEXTENT (Win32)

LB_GETHORIZONTALEXTENT

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

The return value is the scrollable width, in pixels, of the list box.

Comments

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 message
LB_GETITEMDATA (Win32)

LB_GETITEMDATA

wParam = (WPARAM) index;    /* item index */

lParam = 0;     /* not used, must be zero */

An application sends an LB_GETITEMDATA message to retrieve the application-defined 32-bit value associated with the specified list box item.

Parameter	Description

index	Value of wParam. Specifies the index of the item.

Returns

The return value is the 32-bit value associated with the item, or LB_ERR if an error occurs.

Comments

If the item is in an owner-drawn list box created without the LBS_HASSTRINGS style, this 32-bit value was contained 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 parameter of an LB_SETITEMDATA message.

See Also

LB_ADDSTRING, LB_INSERTSTRING, LB_SETITEMDATA


LB_GETITEMHEIGHT message
LB_GETITEMHEIGHT (Win32)

LB_GETITEMHEIGHT

wParam = (WPARAM) index;    /* item index             */

lParam = 0;                 /* not used, must be zero */

An application sends an LB_GETITEMHEIGHT message to retrieve the height of items in a list box.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the item in the list box. This parameter is used only if the list box has the LBS_OWNERDRAWVARIABLE style; otherwise, set it to zero.

Returns

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 message
LB_GETITEMRECT (Win32)

LB_GETITEMRECT

wParam = (WPARAM) index;            /* item index           */

lParam = (LPARAM) (RECT FAR*) lprc; /* address of rectangle */

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.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the item.

lprc	Value of lParam. Points to a RECT structure that will receive the client coordinates for the item in the list box.

For a full description of this structure, see Structures

Returns

If an error occurs, the return value is LB_ERR.


LB_GETLOCALE message
LB_GETLOCALE (Win32)

LB_GETLOCALE

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

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.

Comments

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_SETLOCALE, PRIMARYLANGID, SUBLANGID


LB_GETSEL message
LB_GETSEL (Win32)

LB_GETSEL

wParam = (WPARAM) index;    /* item index             */

lParam = 0;                 /* not used, must be zero */

An application sends an LB_GETSEL message to retrieve the selection state of an item.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the item.

Returns

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 message
LB_GETSELCOUNT (Win32)

LB_GETSELCOUNT

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an LB_GETSELCOUNT message to retrieve the total number of selected items in a multiple-selection list box.

Parameters

This message has no parameters.

Returns

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 message
LB_GETSELITEMS (Win32)

LB_GETSELITEMS

wParam = (WPARAM) cItems;           /* maximum number of items */

lParam = (LPARAM) (LPINT) lpnItems; /* address of buffer       */

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.

Parameter	Description

cItems	Value of wParam. Specifies the maximum number of selected items whose item numbers are to be placed in the buffer.

lpnItems	Value of lParam. Points to a buffer large enough for the number of integers specified by the cItems parameter.

Returns

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 message
LB_GETTEXT (Win32)

LB_GETTEXT

wParam = (WPARAM) index;                /* item index        */

lParam = (LPARAM) (LPCTSTR) lpszBuffer; /* address of buffer */

An application sends an LB_GETTEXT message to retrieve a string from a list box.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the string to retrieve.

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.

Returns

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.

Comments

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.

See Also

LB_GETTEXTLEN


LB_GETTEXTLEN message
LB_GETTEXTLEN (Win32)

LB_GETTEXTLEN

wParam = (WPARAM) index;    /* item index             */

lParam = 0;                 /* not used, must be zero */

An application sends an LB_GETTEXTLEN message to retrieve the length of a string in a list box.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the string.

Returns

The return value is the length of the string, in characters, excluding the terminating null character. If the index parameter does not specify a valid index, the return value is LB_ERR.

See Also

LB_GETTEXT


LB_GETTOPINDEX message
LB_GETTOPINDEX (Win32)

LB_GETTOPINDEX

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

The return value is the index of the first visible item in the list box.

See Also

LB_SETTOPINDEX


LB_INSERTSTRING message
LB_INSERTSTRING (Win32)

LB_INSERTSTRING

wParam = (WPARAM) index;          /* item index                  */

lParam = (LPARAM) (LPCTSTR) lpsz; /* address of string to insert */

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.

Parameter	Description

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 the list was created with an owner-drawn style but without the LBS_HASSTRINGS style, the value of the lpsz parameter is stored instead of the string it would otherwise point to.

Returns

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_RESETCONTENT message
LB_RESETCONTENT (Win32)

LB_RESETCONTENT

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends an LB_RESETCONTENT to remove all items from a list box.

Parameters

This message has no parameters.

Returns

This message does not return a value.

Comments

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 message
LB_SELECTSTRING (Win32)

LB_SELECTSTRING

wParam = (WPARAM) indexStart;     /* item before start of search */

lParam = (LPARAM)(LPCTSTR)lpszFind;  /* address of search string */

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.

Parameter	Description

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.

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.

Returns

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.

Comments

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 message
LB_SELITEMRANGE (Win32)

LB_SELITEMRANGE

wParam = (WPARAM) (BOOL) fSelect;   /* selection flag       */

lParam = MAKELPARAM(wFirst, wLast); /* first and last items */

An application sends an LB_SELITEMRANGE message to select one or more consecutive items in a multiple-selection list box.

Parameter	Description

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.

Returns

If an error occurs, the return value is LB_ERR.

Comments

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 message
LB_SELITEMRANGEEX (Win32)

LB_SELITEMRANGEEX

wParam = (WPARAM) wFirst; /* first item */

lParam = (LPARAM) wLast); /* last item  */

An application sends an LB_SELITEMRANGEEX message to select one or more consecutive items in a multiple-selection list box.

Parameter	Description

wFirst	Value of wParam. Specifies the zero-based index of the first item to select.

wLast	Value of lParam. Specifies the zero-based index of the last item to select.

Returns

If an error occurs, the return value is LB_ERR.

Comments

If wFirst is less than wLast, 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 message
LB_SETANCHORINDEX (Win32)

LB_SETANCHORINDEX

wParam = (WPARAM) index; /* index to set as anchor */

lParam = 0;              /* not used, must be zero */

An application sends an LB_SETANCHORINDEX message to set the position of the anchor item.

Parameter	Description

index	Value of wParam. Specifies the index of the list box item that will be the anchor.

Returns

The return value is zero.

Comments

This message sets the anchor by setting the internal value that represents the list box item most recently selected by the user pressing a mouse button. In a multiple-selection list box, the anchor item is the first or last item in a block of contiguous selected items.

See Also

LB_GETANCHORINDEX


LB_SETCARETINDEX message
LB_SETCARETINDEX (Win32)

LB_SETCARETINDEX

wParam = (WPARAM) index;            /* item index              */

lParam = MAKELPARAM(fScroll, 0);    /* flag for scrolling item */

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.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the list box item that is to receive the focus rectangle.

fScroll	Value of lParam. If this value is FALSE, the item is scrolled until it is fully visible. If this value is TRUE, the item is scrolled until it is at least partially visible.

Returns

If an error occurs, the return value is LB_ERR.

See Also

LB_GETCARETINDEX


LB_SETCOLUMNWIDTH message
LB_SETCOLUMNWIDTH (Win32)

LB_SETCOLUMNWIDTH

wParam = (WPARAM) cxColumn; /* column width in pixels */

lParam = 0;                 /* not used, must be zero */

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.

Parameter	Description

cxColumn	Value of wParam. Specifies the width, in pixels, of all columns.

Returns

This message does not return a value.

See Also

LB_SETTABSTOPS


LB_SETCOUNT message
LB_SETCOUNT (Win32)

LB_SETCOUNT

wParam = (WPARAM) (int) cItems; /* count of list box items */

lParam = 0;                     /* not used; must be zero  */

An application sends an LB_SETCOUNT message to set the count of items in a list box created with the LBS_NODATA style.

Parameter	Description

cItems	Value of wParam. Specifies the new count of items in the list box.

Returns

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.

Comments

Only list boxes created with the LBS_NODATA style support the LB_SETCOUNT message. All other list boxes return LB_ERR in response to this message.

See Also

LB_GETCOUNT


LB_SETCURSEL message
LB_SETCURSEL (Win32)

LB_SETCURSEL

wParam = (WPARAM) index;    /* item index             */

lParam = 0;                 /* not used, must be zero */

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.

Parameter	Description

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.

Returns

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.

Comments

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 message
LB_SETHORIZONTALEXTENT (Win32)

LB_SETHORIZONTALEXTENT

wParam = (WPARAM) cxExtent; /* horizontal scroll width */

lParam = 0;                 /* not used, must be zero  */

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.

Parameter	Description

cxExtent	Value of wParam. Specifies the number of pixels by which the list box can be scrolled.

Returns

This message does not return a value.

Comments

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 message
LB_SETITEMDATA (Win32)

LB_SETITEMDATA

wParam = (WPARAM) index;    /* item index                   */

lParam = (LPARAM) dwData;   /* value to associate with item */

An application sends an LB_SETITEMDATA message to set a 32-bit value associated with the specified item in a list box.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the item.

dwData	Value of lParam. Specifies the 32-bit value to be associated with the item.

Returns

If an error occurs, the return value is LB_ERR.

Comments

If the item is in an owner-drawn list box created without the LBS_HASSTRINGS style, this message replaces the 32-bit value that was 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 message
LB_SETITEMHEIGHT (Win32)

LB_SETITEMHEIGHT

wParam = (WPARAM) index;        /* item index  */

lParam = MAKELPARAM(cyItem, 0); /* item height */

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.

Parameter	Description

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.

cyItem	Value of lParam. Specifies the height, in pixels, of the item.

Returns

If the index or height is invalid, the return value is LB_ERR.

See Also

LB_GETITEMHEIGHT


LB_SETLOCALE message
LB_SETLOCALE (Win32)

LB_SETLOCALE

wParam = (WPARAM) wLocaleID;    /* locale identifier      */

lParam = 0;                     /* not used, must be zero */

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.

Parameter	Description

wLocaleID	Value of wParam. Specifies the locale identifier that the list box will use for sorting when adding text.

Returns

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.

Comments

Use the MAKELCID macro to construct a locale identifier.

See Also

LB_GETLOCALE, MAKELCID


LB_SETSEL message
LB_SETSEL (Win32)

LB_SETSEL

wParam = (WPARAM) (BOOL) fSelect;   /* selection flag */

lParam = (LPARAM) (UINT) index;     /* item index     */

An application sends an LB_SETSEL message to select a string in a multiple-selection list box.

Parameter	Description

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.

Returns

If an error occurs, the return value is LB_ERR.

Comments

Use this message only with multiple-selection list boxes.

See Also

LB_GETSEL, LB_SELITEMRANGE


LB_SETTABSTOPS message
LB_SETTABSTOPS (Win32)

LB_SETTABSTOPS

wParam = (WPARAM) cTabs;            /* number of tab stops       */

lParam = (LPARAM) (LPINT) lpnTabs;  /* address of tab-stop array */

An application sends an LB_SETTABSTOPS message to set the tab-stop positions in a list box.

Parameter	Description

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.

Returns

If all the specified tabs are set, the return value is TRUE; otherwise, it is FALSE.

Comments

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 one-fourth 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 message
LB_SETTOPINDEX (Win32)

LB_SETTOPINDEX

wParam = (WPARAM) index;    /* item index             */

lParam = 0;                 /* not used, must be zero */

An application sends an LB_SETTOPINDEX message to ensure that a particular item in a list box is visible.

Parameter	Description

index	Value of wParam. Specifies the zero-based index of the item in the list box.

Returns

If an error occurs, the return value is LB_ERR.

Comments

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 message
LBN_DBLCLK (Win32)

LBN_DBLCLK

idListBox = (int) LOWORD(wParam);  /* identifier of list box */

hwndListBox = (HWND) lParam;       /* handle of list box     */

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.

Comments

Only a list box that has the LBS_NOTIFY style will send this notification message.

See Also

LBN_SELCHANGE, WM_COMMAND


LBN_ERRSPACE message
LBN_ERRSPACE (Win32)

LBN_ERRSPACE

idListBox = (int) LOWORD(wParam);  /* identifier of list box */

hwndListBox = (HWND) lParam;       /* handle of list box     */

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.

See Also

WM_COMMAND


LBN_KILLFOCUS message
LBN_KILLFOCUS (Win32)

LBN_KILLFOCUS

idListBox = (int) LOWORD(wParam);  /* identifier of list box */

hwndListBox = (HWND) lParam;       /* handle of list box     */

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.

See Also

LBN_SETFOCUS, WM_COMMAND


LBN_SELCANCEL message
LBN_SELCANCEL (Win32)

LBN_SELCANCEL

idListBox = (int) LOWORD(wParam);  /* identifier of list box */

hwndListBox = (HWND) lParam;       /* handle of list box     */

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.

Comments

This notification message applies only to a list box that has the LBS_NOTIFY style.

See Also

LBN_DBLCLK, LBN_SELCHANGE, LB_SETCURSEL, WM_COMMAND


LBN_SELCHANGE message
LBN_SELCHANGE (Win32)

LBN_SELCHANGE

idListBox = (int) LOWORD(wParam);  /* identifier of list box */

hwndListBox = (HWND) lParam;       /* handle of list box     */

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.

Comments

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

LBN_DBLCLK, LBN_SELCANCEL, LB_SETCURSEL, WM_COMMAND


LBN_SETFOCUS message
LBN_SETFOCUS (Win32)

LBN_SETFOCUS

idListBox = (int) LOWORD(wParam);  /* identifier of list box */

hwndListBox = (HWND) lParam;       /* handle of list box     */

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.

See Also

LBN_KILLFOCUS, WM_COMMAND


MCI_BREAK message
MCI_BREAK (Win32)

This MCI command message sets a break key for an MCI device. MCI supports this message directly rather than passing it to the device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpBreak.

MCI_WAIT

Specifies that the break operation should finish before MCI returns control to the application.

MCI_BREAK_KEY

Indicates 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_HWND

Indicates the hwndBreak member of the structure identified by lpBreak contains a window handle which 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_OFF

Used to disable any existing break key for the indicated device

LPMCI_BREAK_PARMS lpBreak	Points to the MCI_BREAK_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

You might have to press the break key multiple times to interrupt a wait operation. Pressing the break key after a device wait is broken can send the break to an application. If an application has an action defined for the virtural key code, then it can inadvertantly 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.


MCI_CLOSE message
MCI_CLOSE (Win32)

This MCI command message releases access to a device or device element. All devices respond to this message.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpDefault.

MCI_WAIT

Specifies that the close operation should finish before MCI returns control to the application.

LPMCI_GENERIC_PARMS lpDefault

Points to the MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this data structure with a device-specific data structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

Exiting an application without closing any MCI devices it has opened can leave the device opened and unaccessible. Your application should explicitly close each device or device element when it is finished with it. MCI unloads the device when all instances of the device or all device elements are closed.

See Also

MCI_OPEN


MCI_COPY message
MCI_COPY (Win32)

This MCI command message copies data to the Clipboard. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_COPY:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the data structure identified by lpCopy.

MCI_WAIT

Specifies that the copy should finish before MCI returns control to the application.

LPMCI_GENERIC_PARMS lpCopy	Points to an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this data structure with a device-specific data structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

See Also

MCI_CUT, MCI_DELETE, MCI_PASTE


MCI_CUE message
MCI_CUE (Win32)

This MCI command message cues a device so that playback or recording begins with minimum delay. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_CUE:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpDefault.

MCI_WAIT

Specifies that the cue operation should finish before MCI returns control to the application.

LPMCI_GENERIC_PARMS lpDefault	Points to the MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Waveform Audio Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to wave audio devices:

Value	Meaning

MCI_WAVE_INPUT

Specifies that a wave input device should be cued.

MCI_WAVE_OUTPUT

Specifies that a wave output device should be cued. This is the default flag if a flag is not specified.

LPMCI_GENERIC_PARMS lpDefault	Points to the MCI_GENERIC_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

See Also

MCI_SEEK, MCI_PLAY, MCI_RECORD


MCI_CUT message
MCI_CUT (Win32)

This MCI command message removes data from the MCI element and copies it to the Clipboard. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_CUT:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpCut.

MCI_WAIT

Specifies that the cut operation should finish before MCI returns control to the application.

LPMCI_GENERIC_PARMS lpCut	Points to an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

See Also

MCI_COPY, MCI_DELETE, MCI_PASTE


MCI_DELETE message
MCI_DELETE (Win32)

This MCI command message removes data from the MCI element. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_DELETE:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpCut.

MCI_WAIT

Specifies that the delete operation should finish before MCI returns control to the application.

LPMCI_GENERIC_PARMS lpDelete	Points to an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Wave Audio Extensions

Parameter	Description

DWORD dwFlags	The following extensions apply to wave audio devices:

Value	Meaning

MCI_FROM

Specifies that a beginning position is included in the dwFrom member of the structure identified by lpDelete. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

MCI_TO

Specifies that an ending position is included in the dwTo member of the structure identified by lpDelete. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command.

LPMCI_WAVE_DELETE_PARMS lpDelete	Points to an MCI_WAVE_DELETE_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

The waveform audio device uses this command.

See Also

MCI_COPY, MCI_PASTE


MCI_FREEZE message
MCI_FREEZE (Win32)

This MCI command message freezes motion on the display. This command is part of the video overlay command set. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_FREEZE:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpFreeze.

MCI_WAIT

Specifies that the freeze operation should finish before MCI returns control to the application.

MCI_OVLY_RECT

Specifies that the rc member of the data structure identified by lpFreeze contains a valid rectangle. If this flag is not specified, the device driver will freeze the entire frame.

LPMCI_OVLY_RECT_PARMS lpFreeze	Points to a MCI_OVLY_RECT_PARMS structure. (Devices with additional parameters might replace this structure with a device-specific structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

See Also

MCI_UNFREEZE


MCI_GETDEVCAPS message
MCI_GETDEVCAPS (Win32)

This MCI command message is used to obtain static information about a device. All devices must respond to this message. The parameters and flags available for this message depend on the selected device. Information is returned in the dwReturn member of the structure identified by lpCapsParms.

Parameter	Description

DWORD dwFlags	The following standard and command-specific flags apply to all devices:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpCapsParms.

MCI_WAIT

Specifies that the query operation should finish before MCI returns control to the application.

MCI_GETDEVCAPS_ITEM

Specifies that the dwItem member of the structure identified by lpCapsParms contains a constant specifying which device capability to obtain. The following constants define which capability to return in the dwReturn member of the structure:

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 MCI_PAUSE and MCI_STOP as well as MCI_PLAY.

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 MCI_PAUSE and MCI_STOP as well as MCI_RECORD.

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_COMPOUND_DEVICE

The dwReturn member is set to TRUE if the device uses device elements; otherwise, it is set to FALSE.

MCI_GETDEVCAPS_DEVICE_TYPE

The dwReturn member is set to one of the following values indicating the device type:

MCI_DEVTYPE_ANIMATION

MCI_DEVTYPE_CD_AUDIO

MCI_DEVTYPE_DAT

MCI_DEVTYPE_DIGITAL_VIDEO

MCI_DEVTYPE_OTHER

MCI_DEVTYPE_OVERLAY

MCI_DEVTYPE_SCANNER

MCI_DEVTYPE_SEQUENCER

MCI_DEVTYPE_VIDEODISC

MCI_DEVTYPE_VCR

MCI_DEVTYPE_WAVEFORM_AUDIO

MCI_GETDEVCAPS_HAS_AUDIO

The dwReturn member is set to TRUE if the device has audio output; otherwise, it is set to FALSE.

MCI_GETDEVCAPS_HAS_VIDEO

The dwReturn member is set to TRUE if the device has video output; otherwise, it is set to FALSE.

For example, the member is set to TRUE for devices that support the animation or videodisc command set.

MCI_GETDEVCAPS_USES_FILES

The dwReturn member is set to TRUE if the device requires a filename as its element name; otherwise, it is set to FALSE.

Only compound devices use files.

LPMCI_GETDEVCAPS_PARMS lpCapsParms	Points to the MCI_GETDEVCAPS_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Animation Extensions

Parameter	Description

DWORD dwFlags	The following extensions apply to animation devices:

Value	Meaning

MCI_GETDEVCAPS_ITEM

Specifies that the dwItem member of the structure identified by lpCapsParms contains a constant specifying which device capability to obtain. The following additional device-capability constants are defined for animation devices and specify which value to return in the dwReturn member of the structure:

MCI_ANIM_GETDEVCAPS_CAN_REVERSE

The dwReturn member is set to TRUE if the device can play in reverse; otherwise, it is set to FALSE.

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

MCIMMP returns FALSE.

MCI_ANIM_GETDEVCAPS_FAST_RATE

The dwReturn member is set to the standard fast play rate in frames per second.

MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.

MCI_ANIM_GETDEVCAPS_MAX_WINDOWS

The dwReturn member is set to the maximum number of windows that the device can handle simultaneously.

MCI_ANIM_GETDEVCAPS_NORMAL_RATE

The dwReturn member is set to the normal rate of play in frames per second.

MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.

MCI_ANIM_GETDEVCAPS_PALETTES

The dwReturn member is set to TRUE if the device can return a palette handle; otherwise, it is set to FALSE.

MCIMMP returns TRUE.

MCI_ANIM_GETDEVCAPS_SLOW_RATE

The dwReturn member is set to the standard slow play rate in frames per second.

MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION.

LPMCI_GETDEVCAPS_PARMS lpCapsParms	Points to the MCI_GETDEVCAPS_PARMS structure.

Videodisc Extensions

Parameter	Description

DWORD dwFlags	The following extensions apply to videodisc devices:

Value	Meaning

MCI_GETDEVCAPS_ITEM

Specifies that the dwItem member of the structure identified by lpCapsParms contains a constant specifying which device capability to obtain. The following additional device-capability constants are defined for videodisc devices and specify which value to return in the dwReturn member of the structure:

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

MCI_VD_GETDEVCAPS_CLV

Indicates the information requested applies to CLV format discs. By default, the capabilities apply to the current disc.

MCI_VD_GETDEVCAPS_CAV

Indicates the information requested applies to CAV format discs. By default, the capabilities apply to the current disc.

LPMCI_GETDEVCAPS_PARMS lpCapsParms	Points to the MCI_GETDEVCAPS_PARMS structure.

Video Overlay Extensions

Parameter	Description

DWORD dwFlags	The following extensions apply to video overlay devices:

Value	Meaning

MCI_GETDEVCAPS_ITEM

Specifies that the dwItem member of the structure identified by lpCapsParms contains a constant specifying which device capability to obtain. The following additional device-capability constants are defined for video overlay devices and specify which value to return in the dwReturn member of the structure:

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.

LPMCI_GETDEVCAPS_PARMS lpCapsParms	Points to the MCI_GETDEVCAPS_PARMS structure.

Waveform Audio Extensions

Parameter	Description

DWORD dwFlags	The following extended flag applies to waveform audio devices:

Value	Meaning

MCI_GETDEVCAPS_ITEM

Specifies that the dwItem member of the structure identified by lpCapsParms contains a constant specifying which device capability to obtain. The following additional device-capability constants are defined for waveform audio devices and specify which value to return in the dwReturn member of the structure:

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.

LPMCI_GETDEVCAPS_PARMS lpCapsParms	Points to the MCI_GETDEVCAPS_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.


MCI_INFO message
MCI_INFO (Win32)

This MCI command message obtains string information from a device. All devices respond to this message. The parameters and flags available for this message depend on the selected device. Information is returned in the lpstrReturn member of the structure identified by lpInfo. The dwReturnSize member specifies the buffer length for the return data.

Parameter	Description

DWORD dwFlags	The following standard and command-specific flags apply to all devices:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpInfo.

MCI_WAIT

Specifies that the query operation should finish before MCI returns control to the application.

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.

LPMCI_INFO_PARMS lpInfo	Points to the MCI_INFO_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Animation Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to animation devices:

Value	Meaning

MCI_INFO_FILE

Obtains the filename of the current file. This flag is only supported by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES query.

MCI_ANIM_INFO_TEXT

Obtains the window caption.

LPMCI_INFO_PARMS lpInfo	Points to the MCI_INFO_PARMS structure.

Video Overlay Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to video overlay devices:

Value	Meaning

MCI_INFO_FILE

Obtains the filename of the current file. This flag is only supported by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES query.

MCI_OVLY_INFO_TEXT

Obtains the caption of the window associated with the overlay device.

LPMCI_INFO_PARMS lpInfo	Points to the MCI_INFO_PARMS structure.

Waveform Audio Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to waveform audio devices:

Value	Meaning

MCI_INFO_FILE

Obtains the filename of the current file. This flag is supported by devices that return TRUE to the MCI_GETDEVCAPS_USES_FILES query.

MCI_WAVE_INPUT

Obtains the product name of the current input.

MCI_WAVE_OUTPUT

Obtains the product name of the current output.

LPMCI_INFO_PARMS lpInfo	Points to the MCI_INFO_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.


MCI_LOAD message
MCI_LOAD (Win32)

This MCI command message loads a file. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_LOAD:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpLoad.

MCI_WAIT

Specifies that the load operation should finish before MCI returns control to the application.

MCI_LOAD_FILE

Indicates the lpfilename member of the structure identified by lpLoad contains a pointer to a buffer containing the file name.

LPMCI_LOAD_PARMS lpLoad	Points to the MCI_LOAD_PARMS structure. (Devices with additional parameters might replace this structure with a device-specific structure.)

Video Overlay Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to video overlay devices supporting MCI_LOAD:

Value	Meaning

MCI_OVLY_RECT

Specifies that the rc member of the structure identified by lpLoad contains a valid display rectangle that identifies the area of the video buffer to update.

LPMCI_OVLY_LOAD_PARMS lpLoad	Points to a MCI_OVLY_LOAD_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

This command applies to video overlay devices.

See Also

MCI_SAVE


MCI_OPEN message
MCI_OPEN (Win32)

This MCI command message initializes a device or device element. All devices respond to this message. The parameters and flags available for this message depend on the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpOpen.

MCI_WAIT

Specifies that the open operation should finish before MCI returns control to the application.

MCI_OPEN_ALIAS

Specifies that an alias is included in the lpstrAlias member of the structure identified by lpOpen.

MCI_OPEN_SHAREABLE

Specifies that the device or device element should be opened as shareable.

MCI_OPEN_TYPE

Specifies that a device type name or constant is included in the lpstrDeviceType member of the structure identified by lpOpen.

MCI_OPEN_TYPE_ID

Specifies that the low-order word of the lpstrDeviceType member of the associated structure contains a standard MCI device type ID and the high-order word optionally contains the ordinal index for the device. Use this flag with the MCI_OPEN_TYPE flag.

LPMCI_OPEN_PARMS lpOpen	Points to the MCI_OPEN_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Flags for Compound Devices

Parameter	Description

DWORD dwFlags	The following additional flags apply to compound devices:

Value	Meaning

MCI_OPEN_ELEMENT

Specifies that an element name is included in the lpstrElementName member of the structure identified by lpOpen.

MCI_OPEN_ELEMENT_ID

Specifies that the lpstrElementName member of the structure identified by lpOpen is interpreted as a DWORD and has meaning internal to the device. Use this flag with the MCI_OPEN_ELEMENT flag.

LPMCI_OPEN_PARMS lpOpen	Points to the MCI_OPEN_PARMS structure. (Devices with additional parameters might replace this structure with a device-specific structure.)

Animation Extensions

Parameter	Description

DWORD dwFlags	The following flags apply to animation devices:

Value	Meaning

MCI_ANIM_OPEN_NOSTATIC

Specifies that the device should reduce the number of static (system) colors in the palette to two.

MCI_ANIM_OPEN_PARENT

Indicates the parent window handle is specified in the hWndParent member of the structure identified by lpOpen. The parent window handle is required for some window styles.

MCI_ANIM_OPEN_WS

Indicates 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 which defines the window style. These constants are the same as the ones in WINDOWS.H (such as WS_CHILD, WS_OVERLAPPEDWINDOW, or WS_POPUP).

LPMCI_ANIM_OPEN_PARMS lpOpen	Points to the MCI_ANIM_OPEN_PARMS structure.

Video Overlay Extensions

Parameter	Description

DWORD dwFlags	The following flags apply to video overlay devices:

Value	Meaning

MCI_OVLY_OPEN_PARENT

Indicates the parent window handle is specified in the hWndParent member of the structure identified by lpOpen.

MCI_OVLY_OPEN_WS

Indicates 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 those in WINDOWS.H (for example, WS_CHILD, WS_OVERLAPPEDWINDOW, or WS_POPUP).

LPMCI_OVLY_OPEN_PARMS lpOpen	Points to the MCI_OVLY_OPEN_PARMS structure.

Waveform Audio Extensions

Parameter	Description

DWORD dwFlags	The following flags apply to waveform audio devices:

Value	Meaning

MCI_WAVE_OPEN_BUFFER

Indicates a buffer length is specified in the dwBuffer member of the structure identified by lpOpen.

LPMCI_WAVE_OPEN_PARMS lpOpen	Points to the MCI_WAVE_OPEN_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Returns

Returns zero if the open succeeds. If an error occurs, it returns the following values:

Value	Meaning

MCIERR_CANNOT_LOAD_DRIVER

Error loading media device driver.

MCIERR_DEVICE_OPEN

The device name is in use by this task. Use a unique alias.

MCIERR_DUPLICATE_ALIAS

The specified alias is an open device in this task.

MCIERR_EXTENSION_NOT_FOUND

Cannot deduce a device type from the given extension.

MCIERR_FILENAME_REQUIRED

A valid filename is required.

MCIERR_MISSING_PARAMETER

Required parameter is missing.

MCIERR_MUST_USE_SHAREABLE

The device is already open; use the shareable flag with each open.

MCIERR_NO_ELEMENT_ALLOWED

An element name cannot be used with this device.

Comments

If MCI_OPEN_SHAREABLE is not specified when a device or device element is initially opened, then all subsequent MCI_OPEN messages to the device or device element will fail. If the device or device element is already open, and this flag is not specified, the call will fail even if the first open command specified MCI_OPEN_SHAREABLE. Files for the MCIMMP, MCISEQ, and MCIWAVE devices are nonshareable.

Case is ignored in the device name, but there must not be any leading or trailing blanks.

To use automatic type selection (via the [mci extensions] section of the registry file), assign the file name (including file extension) to the lpstrElementName member, assign a NULL pointer to the lpstrDeviceType member, and set the MCI_OPEN_ELEMENT flag.

See Also

MCI_CLOSE


MCI_PASTE message
MCI_PASTE (Win32)

This MCI command message pastes data from the clipboard into a device element.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_PASTE:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpPaste.

MCI_WAIT

Specifies that the device should complete the operation before MCI returns control to the application.

LPMCI_GENERIC_PARMS lpPaste	Points to the MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

See Also

MCI_CUT, MCI_COPY, MCI_DELETE


MCI_PAUSE message
MCI_PAUSE (Win32)

This MCI command message pauses the current action.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_PAUSE:

Value	Meaning

MCI_NOTIFY

Specifies that MCi should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpPause.

MCI_WAIT

Specifies that the device should be paused before MCi returns control to the application.

LPMCI_GENERIC_PARMS lpPause	Points to the MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

The difference between MCI_STOP and MCI_PAUSE depends upon the device. If possible, MCI_PAUSE suspends device operation but leaves the device ready to resume play immediately.

See Also

MCI_PLAY, MCI_RECORD, MCI_RESUME, MCI_STOP


MCI_PLAY message
MCI_PLAY (Win32)

This MCI command message signals the device to begin transmitting output data. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_PLAY:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpPlay.

MCI_WAIT

Specifies that the play operation should finish before MCI returns control to the application.

MCI_FROM

Specifies that a starting position is included in the dwFrom member of the structure identified by lpPlay. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_FROM is not specified, the starting position defaults to the current location.

MCI_TO

Specifies that an ending position is included in the dwTo member of the structure identified by lpPlay. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_TO is not specified, the end position defaults to the end of the media.

LPMCI_PLAY_PARMS lpPlay	Points to an MCI_PLAY_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Animation Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to animation devices:

Value	Meaning

MCI_ANIM_PLAY_FAST

Specifies to play fast.

MCI_ANIM_PLAY_REVERSE

Specifies to play in reverse.

MCI_ANIM_PLAY_SCAN

Specifies to scan quickly.

MCI_ANIM_PLAY_SLOW

Specifies to play slowly.

MCI_ANIM_PLAY_SPEED

Specifies that the play speed is included in the dwSpeed member in the structure identified by lpPlay.

LPMCI_ANIM_PLAY_PARMS lpPlay	Points to an MCI_ANIM_PLAY_PARMS structure.

Videodisc Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to videodisc devices:

Value	Meaning

MCI_VD_PLAY_FAST

Specifies to play fast.

MCI_VD_PLAY_REVERSE

Specifies to play in reverse.

MCI_VD_PLAY_SCAN

Specifies to scan quickly.

MCI_VD_PLAY_SLOW

Specifies to play slowly.

MCI_VD_PLAY_SPEED

Specifies that the play speed is included in the dwSpeed member in the structure identified by lpPlay.

LPMCI_VD_PLAY_PARMS lpPlay	Points to an MCI_VD_PLAY_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

See Also

MCI_CUE, MCI_PAUSE, MCI_RECORD, MCI_RESUME, MCI_SEEK, MCI_STOP


MCI_PUT message
MCI_PUT (Win32)

This MCI command message sets the source, destination, and frame rectangles. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_PUT:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpDest.

MCI_WAIT

Specifies that the operation should finish before MCI returns control to the application.

LPMCI_GENERIC_PARMS lpDest	Points to an MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Animation Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to animation devices supporting MCI_PUT:

Value	Meaning

MCI_ANIM_RECT

Specifies that the rc member of the structure identified by lpDest contains a valid rectangle. If this flag is not specified, the default rectangle matches the coordinates of the image or window being clipped.

MCI_ANIM_PUT_DESTINATION

Indicates the rectangle defined for MCI_ANIM_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_ANIM_PUT_SOURCE

Indicates the rectangle defined for MCI_ANIM_RECT specifies a clipping rectangle for the animation image. The rectangle contains the offset and extent of the image relative to the image origin.

LPMCI_ANIM_RECT_PARMS lpDest	Points to a MCI_ANIM_RECT_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Video Overlay Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to video overlay devices supporting MCI_PUT:

Value	Meaning

MCI_OVLY_RECT

Specifies that 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.

MCI_OVLY_PUT_DESTINATION

Indicates 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

Indicates 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

Indicates that 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

Indicates that 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.

LPMCI_OVLY_RECT_PARMS lpDest	Points to a MCI_OVLY_RECT_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

See Also

MCI_WHERE


MCI_RECORD message
MCI_RECORD (Win32)

This MCI command message starts recording from the current position or from the specified position until the specified position. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_RECORD:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpRecord.

MCI_WAIT

Specifies that recording should finish before MCI returns control to the application.

MCI_RECORD_INSERT

Indicates that newly recorded information should be inserted or pasted into the existing data. (Some devices may not support this.) If supported, this is the default.

MCI_FROM

Specifies that a starting position is included in the dwFrom member of the structure identified by lpRecord. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_FROM is not specified, the starting position defaults to the current location.

MCI_RECORD_OVERWRITE

Specifies that data should overwrite existing data.

MCIWAVE returns MCIERR_UNSUPPORTED_FUNCTION in response to this flag.

MCI_TO

Specifies that an ending position is included in the dwTo member of the structure identified by lpRecord. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. If MCI_TO is not specified, the ending position defaults to the end of the media.

LPMCI_RECORD_PARMS lpRecord	Points to the MCI_RECORD_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION for this command.

Comments

This command is supported by devices that return TRUE to the MCI_GETDEVCAPS_CAN_RECORD query.

See Also

MCI_CUE, MCI_PAUSE, MCI_PLAY, MCI_RESUME, MCI_SEEK


MCI_RESUME message
MCI_RESUME (Win32)

This MCI command message resumes a paused device. Support of this message by a device is optional.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_RESUME:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpDefault.

MCI_WAIT

Specifies that the device should resume before MCI returns control to the application.

LPMCI_GENERIC_PARMS lpDefault	Points to the MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this data structure with a device-specific data structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

This command resumes playing and recording without changing the stop position set with MCI_PLAY or MCI_RECORD.

See Also

MCI_STOP, MCI_PLAY, MCI_RECORD


MCI_SAVE message
MCI_SAVE (Win32)

This MCI command message saves the current file. Devices which modify files should not destroy the original copy until they receive the save message. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_SAVE:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpSave.

MCI_WAIT

Specifies that the save operation should finish before MCI returns control to the application.

MCI_SAVE_FILE

Indicates the lpfilename member of the structure identified by lpSave contains a pointer to a buffer containing the destination file name.

LPMCI_SAVE_PARMS lpSave	Points to the MCI_SAVE_PARMS structure. (Devices with additional parameters might replace this data structure with a device-specific data structure.)

Video Overlay Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to video overlay devices supporting MCI_SAVE:

Value	Meaning

MCI_OVLY_RECT

Specifies that the rc member of the structure identified by lpSave contains a valid display rectangle indicating the area of the video buffer to save.

LPMCI_OVLY_SAVE_PARMS lpSave	Points to a MCI_OVLY_SAVE_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code. MCISEQ returns MCIERR_UNSUPPORTED_FUNCTION.

Comments

This command is supported by devices that return true to the MCI_GETDEVCAPS_CAN_SAVE query. MCIWAVE supports this command.

See Also

MCI_LOAD


MCI_SEEK message
MCI_SEEK (Win32)

This MCI command message changes the current position of media as quickly as possible. Video and audio output are disable during the seek. After the seek is complete, the device will be stopped. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_SEEK:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpSeek.

MCI_WAIT

Specifies that the seek operation should finish before MCI returns control to the application.

MCI_SEEK_TO_END

Specifies to seek to the end of the media.

MCI_SEEK_TO_START

Specifies to seek to the start of the media.

MCI_TO

Specifies a position is included in the dwTo member of the MCI_SEEK_PARMS structure. The units assigned to the position values is specified with the MCI_SET_TIME_FORMAT flag of the MCI_SET command. Do not use this flag with MCI_SEEK_END or MCI_SEEK_START.

LPMCI_SEEK_PARMS lpSeek	Points to the MCI_SEEK_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Videodisc Extensions

Parameter	Description

DWORD dwFlags	The following additional flag applies to videodisc devices.

Value	Meaning

MCI_VD_SEEK_REVERSE

Specifies to seek backward.

LPMCI_SEEK_PARMS lpSeek	Points to the MCI_SEEK_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

See Also

MCI_PLAY, MCI_RECORD


MCI_SET message
MCI_SET (Win32)

This MCI command message sets device information. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_SET:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpSet.

MCI_WAIT

Specifies that the set operation should finish before MCI returns control to the application.

MCI_SET_AUDIO

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

Value	Meaning

MCI_SET_AUDIO_ALL

Specifies all audio channels.

MCI_SET_AUDIO_LEFT

Specifies the left channel.

MCI_SET_AUDIO_RIGHT

Specifies the right channel.

MCI_SET_DOOR_CLOSED

Instructs the device to close the media cover (if any).

MCI_SET_DOOR_OPEN

Instructs the device to open the media cover (if any).

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormat member of the structure identified by lpSet. Specifying MCI_FORMAT_MILLISECONDS indicates that subsequent commands that specify time will use milliseconds for both input and output. Other units are device dependent.

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.

MCI_SET_ON

Enables the specified video or audio channel.

MCI_SET_OFF

Disables the specified video or audio channel.

LPMCI_SET_PARMS lpSet	Points to the MCI_SET_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Animation Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to animation devices:

Value	Meaning

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormat member of the structure identified by lpSet. The following constants are defined for the time format:

MCI_FORMAT_MILLISECONDS

Changes the time format to milliseconds.

MCIMMP returns MCIERR_UNSUPPORTED_FUNCTION if the time format is set to MCI_FORMAT_MILLISECONDS.

MCI_FORMAT_FRAMES

Changes the time format to frames.

LPMCI_SET_PARMS lpSet	Points to the MCI_SET_PARMS structure.

CD Audio Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to videodisc devices:

Value	Meaning

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormat member of the structure identified by lpSet. The following constants are defined for the time format:

MCI_FORMAT_MILLISECONDS

Changes the time format to milliseconds.

MCI_FORMAT_MSF

Changes the time format to minutes, seconds, and frames.

MCI_FORMAT_TMSF

Changes the time format to tracks, minutes, seconds, and frames. (MCI uses continuous track numbers.)

LPMCI_SET_PARMS lpSet	Points to the MCI_SET_PARMS structure.

MIDI Sequencer Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to MIDI sequencer devices:

Value	Meaning

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:

Value	Meaning

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 only affects 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 ID in the dwPort member of the structure identified by lpSet. The device will close the previous port (if any), and attempt to open and use the new port. If it fails, it will return an error and re-open 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 will behave exactly the same as if a port were open, except no MIDI message will be 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:

Value	Meaning

MCI_SEQ_FILE

Sets the sequencer to receive synchronization data contained in the MIDI file.

MCI_SEQ_SMPTE

Sets the sequencer to receive SMPTE synchronization data.

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

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormat member of the structure identified by lpSet. The following constants are defined for the time format:

Value	Meaning

MCI_FORMAT_MILLISECONDS

Changes the time format to milliseconds for both input and output.

MCI_FORMAT_SMPTE_24

Sets the time format to 24 frame SMPTE.

MCI_FORMAT_SMPTE_25

Sets the time format to 25 frame SMPTE.

MCI_FORMAT_SMPTE_30

Sets the time format to 30 frame SMPTE.

MCI_FORMAT_SMPTE_30DROP

Sets the time format to 30 drop-frame SMPTE.

MCI_SEQ_FORMAT_SONGPTR

Sets the time format to song-pointer units.

LPMCI_SEQ_SET_PARMS lpSet	Points to the MCI_SEQ_SET_PARMS structure.

Videodisc Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to videodisc devices:

Value	Meaning

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormat member of the structure identified by lpSet. The following constants are defined for the time format:

Value	Meaning

MCI_FORMAT_CHAPTERS

Changes the time format to chapters.

MCI_FORMAT_FRAMES

Changes the time format to frames.

MCI_FORMAT_HMS

Changes the time format to hours, minutes, and seconds.

MCI_FORMAT_MILLISECONDS

Changes the time format to milliseconds for both input and output.

MCI_VD_FORMAT_TRACK

Changes the time format to tracks. MCI uses continuous track numbers.

LPMCI_VD_SET_PARMS lpSet	Points to the MCI_VD_SET_PARMS structure. (Devices with additional parameters might replace this structure with a device-specific structure.)

Waveform Audio Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to waveform audio devices:

Value	Meaning

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

Specifies that any wave input compatible with the current format can be used for recording.

MCI_WAVE_SET_ANYOUTPUT

Specifies that 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 structure 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

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

MCI_SET_TIME_FORMAT

Specifies a time format parameter is included in the dwTimeFormat member of the structure identified by lpSet. The following constants are defined for the time format:

Value	Meaning

MCI_FORMAT_BYTES

Changes the time format to bytes for input or output.

MCI_FORMAT_MILLISECONDS

Changes the time format to milliseconds for input or output.

MCI_FORMAT_SAMPLES

Changes the time format to samples for input or output.

LPMCI_WAVE_SET_PARMS lpSet	Points to the MCI_WAVE_SET_PARMS data structure. This parameter replaces the standard default parameter data structure identified by lpDefault.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.


MCI_SOUND message
MCI_SOUND (Win32)

This MCI command message plays system sounds identified in the [sounds] section of the registry file. The name of the sound is specified in the buffer pointed to by the lpstrSoundName member of the structure identified by lpInfo. This is an MCI system message that is not sent to any device.

Parameter	Description

DWORD dwFlags	The following standard and command-specific flags apply to all devices:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpInfo.

MCI_WAIT

Specifies that the playing of the sound should finish before MCI returns control to the application.

MCI_SOUND_NAME

Indicates that the name of a sound to play is included in the lpstrSoundName of the structure identified by lpSound. If omitted, the default sound is played.

LPMCI_SOUND_PARMS lpInfo	Points to the MCI_SOUND_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

This command will only play files that fit into available memory. Use the MCI waveform audio device to play longer waveform files.


MCI_STATUS message
MCI_STATUS (Win32)

This MCI command message is used to obtain information about an MCI device. All devices respond to this message. The parameters and flags available for this message depend on the selected device. Information is returned in the dwReturn member of the structure identified by lpStatus.

Parameter	Description

DWORD dwFlags	The following standard and command-specific flags apply to all devices:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpStatus.

MCI_WAIT

Specifies that the status operation should finish before MCI returns control to the application.

MCI_STATUS_ITEM

Specifies that the dwItem member of the data 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:

Value	Meaning

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; otherwise, it is set to FALSE.

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

LPMCI_STATUS_PARMS lpStatus	Points to the MCI_STATUS_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Animation Extensions

Parameter	Description

DWORD dwFlags	The following extensions apply to animation devices:

Value	Meaning

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 additional status constants are defined for animation devices and indicate which item to return in the dwReturn member of the structure:

MCI_ANIM_STATUS_FORWARD

The dwReturn member is set to TRUE if playing forward; otherwise, it is set to FALSE.

MCI_ANIM_STATUS_HPAL

The dwReturn member is set to the handle of the movie palette.

MCI_ANIM_STATUS_HWND

The dwReturn member is set to the handle of the playback window.

MCI_ANIM_STATUS_SPEED

The dwReturn member is set to the animation speed.

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; otherwise, it is set to FALSE.

LPMCI_STATUS_PARMS lpStatus	Points to the MCI_STATUS_PARMS structure.

CD Audio Extensions

Parameter	Description

DWORD dwFlags	The following extensions applies to CD audio devices:

Value	Meaning

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 additional status constants are defined for CD audio devices and indicate which item to return in the dwReturn member of the structure:

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; otherwise, it is set to FALSE.

LPMCI_STATUS_PARMS lpStatus	Points to the MCI_STATUS_PARMS data structure. This parameter replaces the standard default parameter data structure.

MIDI Sequencer Extensions

Parameter	Description

DWORD dwFlags	The following extensions apply to sequencers:

Value	Meaning

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 additional status constants are defined for sequencers and indicate which item to return in the dwReturn member of the structure:

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 ID 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 for the device is present; otherwise, it is set to FALSE.

LPMCI_STATUS_PARMS lpStatus	Points to the MCI_STATUS_PARMS structure. This parameter replaces the standard default parameter structure.

Videodisc Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to videodisc devices:

Value	Meaning

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 additional status constants are defined for videodisc devices and indicate which item to return in the dwReturn member of the structure:

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; otherwise, it is set to FALSE.

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; otherwise, it is set to FALSE.

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_STATUS_MODE

The dwReturn member is set to the current mode of the device. All devices can return the following constants to indicate the current mode:

MCI_MODE_NOT_READY

MCI_MODE_PAUSE

MCI_MODE_PLAY

MCI_MODE_STOP

MCI_VD_MODE_PARK (videodisc devices)

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.

MCIPIONR returns MCIERR_UNSUPPORTED_FUNCTION.

LPMCI_STATUS_PARMS lpStatus	Points to the MCI_STATUS_PARMS structure. This parameter replaces the standard default parameter structure.

Waveform Audio Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to waveform audio devices:

Value	Meaning

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 additional status constants are defined for waveform audio devices and indicate which item to return in the dwReturn member of the structure:

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; otherwise, it is set to FALSE.

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

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_FORMATTAG

The dwReturn member is set to the current format tag used for playing, recording, and saving.

MCI_WAVE_STATUS_LEVEL

The dwReturn member is set to the current record or playback level. 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.

LPMCI_STATUS_PARMS lpStatus	Points to the MCI_STATUS_PARMS structure.

Video Overlay Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to video overlay devices:

Value	Meaning

MCI_OVLY_STATUS_HWND

The dwReturn member is set to the handle of the window associated with the video overlay device.

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 additional status constants are defined for video overlay devices and indicate which item to return in the dwReturn member of the structure:

MCI_STATUS_MEDIA_PRESENT

The dwReturn member is set to TRUE if the media is inserted in the device; otherwise, it is set to FALSE.

LPMCI_STATUS_PARMS lpStatus	Points to the MCI_STATUS_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.


MCI_STEP message
MCI_STEP (Win32)

This MCI command message steps the player one or more frames.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_STEP:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpStep.

MCI_WAIT

Specifies that the step operation should finish before MCI returns control to the application.

Animation Extensions

Parameter	Description

DWORD dwFlags	The following additional flag applies to animation devices.

Value	Meaning

MCI_ANIM_STEP_FRAMES

Indicates that the dwFrames member of the structure identified by lpStep specifies the number of frames to step.

MCI_ANIM_STEP_REVERSE

Steps in reverse.

LPMCI_ANIM_STEP_PARMS lpStep	Points to the MCI_ANIM_STEP_PARMS structure.

Videodisc Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to videodisc devices.

Value	Meaning

MCI_VD_STEP_FRAMES

Indicates that the dwFrames member of the structure identified by lpStep specifies the number of frames to step.

MCI_VD_STEP_REVERSE

Steps in reverse.

LPMCI_VD_STEP_PARMS lpStep	Points to a MCI_VD_STEP_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

Only devices that return TRUE to the MCI_GETDEVCAPS_HAS_VIDEO capability query support this command at present.

See Also

MCI_CUE, MCI_PLAY, MCI_SEEK


MCI_STOP message
MCI_STOP (Win32)

This MCI command message stops all play and record sequences, unloads all play buffers, and ceases display of video images. Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_STOP:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpStop.

MCI_WAIT

Specifies that the device should stop before MCI returns control to the application.

LPMCI_GENERIC_PARMS lpStop	Points to the MCI_GENERIC_PARMS structure. (Devices with extended command sets might replace this structure with a device-specific structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

The difference between MCI_STOP and MCI_PAUSE depends upon the device. If possible, MCI_PAUSE suspends device operation but leaves the device ready to resume play immediately.

See Also

MCI_PAUSE, MCI_PLAY, MCI_RECORD, MCI_RESUME


MCI_SYSINFO message
MCI_SYSINFO (Win32)

This MCI command message returns information about MCI devices. MCI supports this message directly rather than passing it to the devices. 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 DWORD placed in the application-supplied buffer. The dwReturnSize member specifies the buffer length.

Parameter	Description

DWORD dwFlags	The following standard and command-specific flags apply to all devices:

Value	Meaning

MCI_SYSINFO_INSTALLNAME

Obtains the name (listed in the registry) used to install the device.

MCI_SYSINFO_NAME

Obtains a device name corresponding to the device number specified in the dwNumbermember 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 [mci] section of the registry file. If the MCI_SYSINFO_OPEN flag is set, the number of open devices is returned.

LPMCI_SYSINFO_PARMS lpSysInfo	Points to the MCI_SYSINFO_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

The wDeviceType element of the lpSysInfo structure is used to indicate the device type of the query. If the wDeviceID parameter is set to MCI_ALL_DEVICE_ID it will override the value of wDeviceType.

Integer return values are doublewords returned in the buffer pointed to by the lpstrReturn member of MCI_SYSINFO_PARMS.

String return values are NULL-terminated strings returned in the buffer pointed to by the lpstrReturn member.


MCI_UNFREEZE message
MCI_UNFREEZE (Win32)

This MCI command message restores motion to an area of the video buffer frozen with MCI_FREEZE. This command is part of the video overlay command set. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_UNFREEZE:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpFreeze.

MCI_WAIT

Specifies that the unfreeze operation should finish before MCI returns control to the application.

MCI_OVLY_RECT

Specifies that the rc member of the data structure identified by lpFreeze contains a valid display rectangle. This is a required parameter.

LPMCI_OVLY_RECT_PARMS lpFreeze	Points to a MCI_OVLY_RECT_PARMS structure. (Devices with additional parameters might replace this structure with a device-specific structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

This command applies to video overlay devices.

See Also

MCI_FREEZE


MCI_WHERE message
MCI_WHERE (Win32)

This MCI command message obtains the clipping rectangle for the video device. The top and left members of the returned rectangle contain the origin of the clipping rectangle, and the right and bottom members contain the width and height of the clipping rectangle. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_WHERE:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpQuery.

MCI_WAIT

Specifies that the operation should complete before MCI returns control to the application.

DWORD lpQuery	Points to a device-specific structure. For a description of this parameter, see the lpQuery description included with the device extensions.

Animation Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to animation devices supporting MCI_WHERE:

Value	Meaning

MCI_ANIM_WHERE_DESTINATION

Obtains the destination display rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery.

MCI_ANIM_WHERE_SOURCE

Obtains the animation source rectangle. The rectangle coordinates are placed in the rc member of the data structure identified by lpQuery.

LPMCI_ANIM_RECT_PARMS lpQuery	Points to a MCI_ANIM_RECT_PARMS structure.

Video Overlay Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to video overlay devices supporting MCI_WHERE:

Value	Meaning

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.

LPMCI_OVLY_RECT_PARMS lpQuery	Points to a MCI_OVLY_RECT_PARMS structure.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

This command applies to animation and video overlay devices.

See Also

MCI_PUT


MCI_WINDOW message
MCI_WINDOW (Win32)

This MCI command message specifies the window and the window characteristics for graphic devices. Graphic devices should create a default window when a device is opened but should not display it until they receive the play command. The window command is used to supply an application-created window to the device and to change the display characteristics of an application-supplied or default display window. If the application supplies the display window, it should be prepared to update an invalid rectangle on the window.

Support of this message by a device is optional. The parameters and flags for this message vary according to the selected device.

Parameter	Description

DWORD dwFlags	The following flags apply to all devices supporting MCI_WINDOW:

Value	Meaning

MCI_NOTIFY

Specifies that MCI should post the MM_MCINOTIFY message when this command completes. The window to receive this message is specified in the dwCallback member of the structure identified by lpWindow.

MCI_WAIT

Specifies that the operation should finish before MCI returns control to the application.

DWORD lpWindow	Points to a device specific structure. For a description of this parameter, see the lpWindow description included with the device extensions.

Animation Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to animation devices supporting MCI_WINDOW:

Value	Meaning

MCI_ANIM_WINDOW_HWND

Indicates the handle of the window to use for the destination is included in the hWnd member of the structure identified by lpWindow. Set this to MCI_ANIM_WINDOW_DEFAULT to return to the default window.

MCI_ANIM_WINDOW_STATE

Indicates the nCmdShow member of the MCI_ANIM_WINDOW_PARMS 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 the ones in WINDOWS.H (such as SW_HIDE, SW_MINIMIZE, or SW_SHOWNORMAL.)

MCI_ANIM_WINDOW_TEXT

Indicates the lpstrText member of the MCI_ANIM_WINDOW_PARMS structure contains a pointer to a buffer containing the caption used for the window.

LPMCI_ANIM_WINDOW_PARMS lpWindow	Points to a MCI_ANIM_WINDOW_PARMS structure. (Devices with additional parameters might replace this structure with a device-specific structure.)

Video Overlay Extensions

Parameter	Description

DWORD dwFlags	The following additional flags apply to video overlay devices supporting MCI_WINDOW:

Value	Meaning

MCI_OVLY_WINDOW_HWND

Indicates the handle of the window used for the destination is included in the hWnd member of the MCI_OVLY_WINDOW_PARMS structure. Set this to MCI_OVLY_WINDOW_DEFAULT to return to the default window.

MCI_OVLY_WINDOW_STATE

Indicates the nCmdShow member of the lpWindow structure contains parameters for setting the window state. This flag It 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

Indicates the lpstrText member of the MCI_OVLY_WINDOWS_PARMS structure contains a pointer to buffer containing the caption used for the window.

LPMCI_OVLY_WINDOW_PARMS lpWindow	Points to a MCI_OVLY_WINDOW_PARMS structure. (Devices with additional parameters might replace this structure with a device-specific structure.)

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

This command applies to animation, and video overlay devices.


MIM_CLOSE message
MIM_CLOSE (Win32)

This message is sent to a MIDI input callback function when a MIDI input device is closed. The device handle is no longer valid once this message has been sent.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

MM_MIM_CLOSE


MIM_DATA message
MIM_DATA (Win32)

This message is sent to a MIDI input callback function when a MIDI message is received by a MIDI input device.

Parameter	Description

DWORD dwParam1	Specifies the MIDI message that was received. The message is packed into a DWORD with the first byte of the message in the low-order byte.

DWORD dwParam2	Specifies the time that the message was received by the input device driver. The timestamp is specified in milliseconds, beginning at 0 when midiInStart was called.

Returns

None.

Comments

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

MM_MIM_DATA, MIM_LONGDATA


MIM_ERROR message
MIM_ERROR (Win32)

This message is sent to a MIDI input callback function when an invalid MIDI message is received.

Parameter	Description

DWORD dwParam1	Specifies the invalid MIDI message that was received. The message is packed into a DWORD with the first byte of the message in the low-order byte.

DWORD dwParam2	Specifies the time that the message was received by the input device driver. The timestamp is specified in milliseconds, beginning at 0 when midiInStart was called.

Returns

None.

See Also

MM_MIM_ERROR


MIM_LONGDATA message
MIM_LONGDATA (Win32)

This message is sent to a MIDI input callback function when an input buffer has been filled with MIDI system-exclusive data and is being returned to the application.

Parameter	Description

DWORD dwParam1	Points to a MIDIHDR structure identifying the input buffer.

DWORD dwParam2	Specifies the time that the data was received by the input device driver. The timestamp is specified in milliseconds, beginning at 0 when midiInStart was called.

Returns

None.

Comments

The returned buffer may not be full. The dwBytesRecorded member of the MIDIHDR structure specified by dwParam1 will specify the number of bytes recorded into the buffer.

See Also

MIM_DATA, MM_MIM_LONGDATA


MIM_LONGERROR message
MIM_LONGERROR (Win32)

This message is sent to a MIDI input callback function when an invalid MIDI system-exclusive message is received.

Parameter	Description

DWORD dwParam1	Specifies a pointer to a MIDIHDR structure identifying the buffer containing the invalid message.

DWORD dwParam2	Specifies the time that the data was received by the input device driver. The timestamp is specified in milliseconds, beginning at 0 when midiInStart was called.

Returns

None.

Comments

The returned buffer may not be full. The dwBytesRecorded member of the MIDIHDR structure specified by dwParam1 will specify the number of bytes recorded into the buffer.

See Also

MM_MIM_LONGERROR


MIM_OPEN message
MIM_OPEN (Win32)

This message is sent to a MIDI input callback function when a MIDI input device is opened.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

MM_MIM_OPEN


MM_JOY1BUTTONDOWN message
MM_JOY1BUTTONDOWN (Win32)

This message is sent to the window that has captured joystick 1 when a button is pressed.

Parameter	Description

WPARAM wParam	Indicates which button has changed state. It can be any one of the following combined with any of the flags defined in MM_JOY1MOVE.

Value	Meaning

JOY_BUTTON1CHG

Set if first joystick button has changed.

JOY_BUTTON2CHG

Set if second joystick button has changed.

JOY_BUTTON3CHG

Set if third joystick button has changed.

JOY_BUTTON4CHG

Set if fourth joystick button has changed.

LPARAM lParam	The low-order word contains the current x-position of the joystick. The high-order word contains the current y-position.

Returns

None.

See Also

MM_JOY1BUTTONUP


MM_JOY1BUTTONUP message
MM_JOY1BUTTONUP (Win32)

This message is sent to the window that has captured joystick one when a button is released.

Parameter	Description

WORD wParam	Indicates which button has changed state. It can be any one of the following combined with any of the flags defined in MM_JOY1MOVE.

Value	Meaning

JOY_BUTTON1CHG

Set if first joystick button has changed.

JOY_BUTTON2CHG

Set if second joystick button has changed.

JOY_BUTTON3CHG

Set if third joystick button has changed.

JOY_BUTTON4CHG

Set if fourth joystick button has changed.

DWORD lParam	The low-order word contains the current x-position of the joystick. The high-order word contains the current y-position.

Returns

None.

See Also

MM_JOY1BUTTONDOWN


MM_JOY1MOVE message
MM_JOY1MOVE (Win32)

This message is sent to the window that has captured joystick 1 when the joystick position changes.

Parameter	Description

WPARAM wParam	Indicates which joystick buttons are pressed. It can be any combination of the following values:

Value	Meaning

JOY_BUTTON1

Set if first joystick button is pressed.

JOY_BUTTON2

Set if second joystick button is pressed.

JOY_BUTTON3

Set if third joystick button is pressed.

JOY_BUTTON4

Set if fourth joystick button is pressed.

LPARAM lParam	The low-order word contains the current x-position of the joystick. The high-order word contains the current y-position.

Returns

None.

See Also

MM_JOY1ZMOVE


MM_JOY1ZMOVE message
MM_JOY1ZMOVE (Win32)

This message is sent to the window that has captured joystick 1 when the z-axis position changes.

Parameter	Description

WPARAM wParam	Indicates which joystick buttons are pressed. It can be any combination of the following values:

Value	Meaning

JOY_BUTTON1

Set if first joystick button is pressed.

JOY_BUTTON2

Set if second joystick button is pressed.

JOY_BUTTON3

Set if third joystick button is pressed.

JOY_BUTTON4

Set if fourth joystick button is pressed.

LPARAM lParam	The low-order word contains the current z-position of the joystick.

Returns

None.

See Also

MM_JOY1MOVE


MM_JOY2BUTTONDOWN message
MM_JOY2BUTTONDOWN (Win32)

This message is sent to the window that has captured joystick 2 when a button is pressed.

Parameter	Description

WPARAM wParam	Indicates which button has changed state. It can be any one of the following combined with any of the flags defined in MM_JOY1MOVE.

Value	Meaning

JOY_BUTTON1CHG

Set if first joystick button has changed.

JOY_BUTTON2CHG

Set if second joystick button has changed.

JOY_BUTTON3CHG

Set if third joystick button has changed.

JOY_BUTTON4CHG

Set if fourth joystick button has changed.

LPARAM lParam	The low-order word contains the current x-position of the joystick. The high-order word contains the current y-position.

Returns

None.

See Also

MM_JOY2BUTTONUP


MM_JOY2BUTTONUP message
MM_JOY2BUTTONUP (Win32)

This message is sent to the window that has captured joystick 2 when a button is released.

Parameter	Description

WORD wParam	Indicates which button has changed state. It can be any one of the following combined with any of the flags defined in MM_JOY1MOVE.

Value	Meaning

JOY_BUTTON1CHG

Set if first joystick button has changed.

JOY_BUTTON2CHG

Set if second joystick button has changed.

JOY_BUTTON3CHG

Set if third joystick button has changed.

JOY_BUTTON4CHG

Set if fourth joystick button has changed.

DWORD lParam	The low-order word contains the current x-position of the joystick. The high-order word contains the current y-position.

Returns

None.

See Also

MM_JOY2BUTTONDOWN


MM_JOY2MOVE message
MM_JOY2MOVE (Win32)

This message is sent to the window that has captured joystick 2 when the joystick position changes.

Parameter	Description

WPARAM wParam	Indicates which joystick buttons are pressed. It can be any combination of the following values:

Value	Meaning

JOY_BUTTON1

Set if first joystick button is pressed.

JOY_BUTTON2

Set if second joystick button is pressed.

JOY_BUTTON3

Set if third joystick button is pressed.

JOY_BUTTON4

Set if fourth joystick button is pressed.

WPARAM lParam	The low-order word contains the current x-position of the joystick. The high-order word contains the current y-position.

Returns

None.

See Also

MM_JOY2ZMOVE


MM_JOY2ZMOVE message
MM_JOY2ZMOVE (Win32)

This message is sent to the window that has captured joystick 2 when the z-axis position changes.

Parameter	Description

WPARAM wParam	Indicates which joystick buttons are pressed. It can be any combination of the following values:

Value	Meaning

JOY_BUTTON1

Set if first joystick button is pressed.

JOY_BUTTON2

Set if second joystick button is pressed.

JOY_BUTTON3

Set if third joystick button is pressed.

JOY_BUTTON4

Set if fourth joystick button is pressed.

LPARAM lParam	The low-order word contains the current z-position of the joystick.

Returns

None.

See Also

MM_JOY2MOVE


MM_MCINOTIFY message
MM_MCINOTIFY (Win32)

This message is sent to a window to notify an application that an MCI device has completed an operation. MCI devices send this message only when the MCI_NOTIFY flag is used with an MCI command message or when the notify flag is used with an MCI command string.

Parameter	Description

WORD wParam	Contains one of the following flags:

Value	Meaning

MCI_NOTIFY_ABORTED

Specifies that the device received a command that prevented the current conditions for initiating the callback from being met. If a new command interrupts the current command and it also requests notification, the device sends only this message and not MCI_NOTIFY_SUPERCEDED.

MCI_NOTIFY_SUCCESSFUL

Specifies that the conditions initiating the callback have been met.

MCI_NOTIFY_SUPERSEDED

Specifies that the device received another command with the MCI_NOTIFY flag set and the current conditions for initiating the callback have been superseded.

MCI_NOTIFY_FAILURE

Specifies that a device error occurred while the device was executing the command.

LONG lParam	The low-order word specifies the ID of the device initiating the callback.

Returns

Returns zero if successful. Otherwise, it returns an MCI error code.

Comments

A device returns the flag MCI_NOTIFY_SUCCESSFUL with MM_MCINOTIFY when the action for a command finishes. For example, a CD audio device uses this flag for notification for MCI_PLAY when the device finishes playing. The MCI_PLAY command is successful only when it reaches the specified end position or reaches the end of the media. Similarly, MCI_SEEK and MCI_RECORD do not return MCI_NOTIFY_SUCCESSFUL until they reach the specified end position or reach the end of the media.

A device returns the flag MCI_NOTIFY_ABORTED with MM_MCINOTIFY only when it receives a command that prevents it from meeting the notification conditions. For example, the command MCI_PLAY 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 for the play command with an active notify. The MCI_RECORD and MCI_SEEK commands behave similarly.

MCI also does not send MCI_NOTIFY_ABORTED when MCI_PLAY or MCI_RECORD is paused with MCI_PAUSE. Sending the MCI_RESUME command will let them continue to meet the callback conditions.

When your application requests notification for a command, check the error return of mciSendMessage or mciSendCommand. If these functions encounter an error and return a nonzero value, MCI will not set notification for the command.


MM_MIM_CLOSE message
MM_MIM_CLOSE (Win32)

This message is sent to a window when a MIDI input device is closed. The device handle is no longer valid once this message has been sent.

Parameter	Description

DWORD wParam	Specifies a handle to the MIDI input device that was closed.

DWORD lParam	Currently unused.

Returns

None.

See Also

MIM_CLOSE


MM_MIM_DATA message
MM_MIM_DATA (Win32)

This message is sent to a window when a MIDI message is received by a MIDI input device.

Parameter	Description

DWORD wParam	Specifies a handle to the MIDI input device that received the MIDI message.

DWORD lParam	Specifies the MIDI message that was received. The message is packed into a DWORD with the first byte of the message in the low-order byte.

Returns

None.

Comments

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 timestamp is available with this message. For timestamped input data, you must use the messages that are sent to low-level callback functions.

See Also

MIM_DATA, MM_MIM_LONGDATA


MM_MIM_ERROR message
MM_MIM_ERROR (Win32)

This message is sent to a window when an invalid MIDI message is received.

Parameter	Description

DWORD wParam	Specifies a handle to the MIDI input device that received the invalid message.

DWORD lParam	Specifies the invalid MIDI message. The message is packed into a DWORD with the first byte of the message in the low-order byte.

Returns

None.

See Also

MIM_ERROR


MM_MIM_LONGDATA message
MM_MIM_LONGDATA (Win32)

This message is sent to a window when an input buffer has been filled with MIDI system-exclusive data and is being returned to the application.

Parameter	Description

DWORD wParam	Specifies a handle to the MIDI input device that received the data.

DWORD lParam	Points to a MIDIHDR structure identifying the buffer.

Returns

None.

Comments

The returned buffer may not be full. The dwBytesRecorded member of the MIDIHDR structure specified by lParam will specify the number of bytes recorded into the buffer.

No timestamp is available with this message. For timestamped input data, you must use the messages that are sent to low-level callback functions.

See Also

MM_MIM_DATA, MIM_LONGDATA


MM_MIM_LONGERROR message
MM_MIM_LONGERROR (Win32)

This message is sent to a window when an invalid MIDI system-exclusive message is received.

Parameter	Description

DWORD wParam	Specifies a handle to the MIDI input device that received the invalid message.

DWORD lParam	Points to a MIDIHDR structure identifying buffer containing the invalid message.

Returns

None.

Comments

The returned buffer may not be full. The dwBytesRecorded member of the MIDIHDR structure specified by lParam will specify the number of bytes recorded into the buffer.

See Also

MIM_LONGERROR


MM_MIM_OPEN message
MM_MIM_OPEN (Win32)

This message is sent to a window when a MIDI input device is opened.

Parameter	Description

DWORD wParam	Specifies the handle to the MIDI input device that was opened.

DWORD lParam	Currently unused.

Returns

None.

See Also

MIM_OPEN


MM_MOM_CLOSE message
MM_MOM_CLOSE (Win32)

This message is sent to a window when a MIDI output device is closed. The device handle is no longer valid once this message has been sent.

Parameter	Description

DWORD wParam	Specifies the handle to the MIDI output device.

DWORD lParam	Currently unused.

Returns

None.

See Also

MOM_CLOSE


MM_MOM_DONE message
MM_MOM_DONE (Win32)

This message is sent to a window when the specified system-exclusive buffer has been played and is being returned to the application.

Parameter	Description

DWORD wParam	Specifies a handle to the MIDI output device that played the buffer.

DWORD lParam	Points to a MIDIHDR structure identifying the buffer.

Returns

None.

See Also

MOM_DONE


MM_MOM_OPEN message
MM_MOM_OPEN (Win32)

This message is sent to a window when a MIDI output device is opened.

Parameter	Description

DWORD wParam	Specifies the handle to the MIDI output device.

DWORD lParam	Currently unused.

Returns

None.

See Also

MOM_OPEN


MM_WIM_CLOSE message
MM_WIM_CLOSE (Win32)

This message is sent to a window when a waveform input device is closed. The device handle is no longer valid once this message has been sent.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

WIM_CLOSE


MM_WIM_DATA message
MM_WIM_DATA (Win32)

This message is sent to a window when waveform 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.

Parameter	Description

DWORD dwParam1	Points to a WAVEHDR structure identifying the buffer containing the waveform data.

DWORD dwParam2	Currently unused.

Returns

None.

Comments

The returned buffer may not be full. The dwBytesRecorded member of the WAVEHDR structure specified by dwParam1 will specify the number of bytes recorded into the buffer.

See Also

WIM_DATA


MM_WIM_OPEN message
MM_WIM_OPEN (Win32)

This message is sent to a window when a waveform input device is opened.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

WIM_OPEN


MM_WOM_CLOSE message
MM_WOM_CLOSE (Win32)

This message is sent to a window when a waveform output device is closed. The device handle is no longer valid once this message has been sent.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

WOM_CLOSE


MM_WOM_DONE message
MM_WOM_DONE (Win32)

This message is sent to a window when the specified 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 waveOutReset.

Parameter	Description

DWORD dwParam1	Points to a WAVEHDR structure identifying the buffer.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

WOM_DONE


MM_WOM_OPEN message
MM_WOM_OPEN (Win32)

This message is sent to a window when a waveform output device is opened.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

WOM_OPEN


MMIOM_CLOSE message
MMIOM_CLOSE (Win32)

This message is sent to an I/O procedure by mmioClose to request that a file be closed.

Parameter	Description

LONG lParam1	Specifies options contained in the wFlags parameter of mmioClose.

LONG lParam2	Is not used.

Returns

The return value is zero if the file is successfully closed. Otherwise, the return value specifies an error code.

See Also

mmioClose, MMIOM_OPEN


MMIOM_OPEN message
MMIOM_OPEN (Win32)

This message is sent to an I/O procedure by mmioOpen to request that a file be opened or deleted.

Parameter	Description

LONG lParam1	Specifies a null-terminated string containing the name of the file to open.

LONG lParam2	Is not used.

Returns

The return value is zero if the operation is successful. Otherwise, the return value specifies an error value. Possible error returns are:

Value	Meaning

MMIOM_CANNOTOPEN

Specified file could not be opened.

MMIOM_OUTOFMEMORY

Not enough memory to perform operation.

Comments

The dwFlags member of the MMIOINFO structure contains option flags passed to the mmioOpen function. The lDiskOffset member of the MMIOINFO structure is initialized to zero. If this value is incorrect, then the I/O procedure must correct it.

If the caller passed a MMIOINFO structure to mmioOpen, the return value will be returned in the wErrorRet member.

See Also

mmioOpen, MMIOM_CLOSE


MMIOM_READ message
MMIOM_READ (Win32)

This message is sent to an I/O procedure by mmioRead to request that a specified number of bytes be read from an open file.

Parameter	Description

LONG lParam1	Points to the buffer to be filled with data read from the file.

LONG lParam2	Specifies the number of bytes to read from the file.

Returns

The return value is the number of bytes actually read from the file. If no more bytes can be read, the return value is zero. If there is an error, the return value is -1.

Comments

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, MMIOM_WRITE, MMIOM_WRITEFLUSH


MMIOM_SEEK message
MMIOM_SEEK (Win32)

This message is sent to an I/O procedure by mmioSeek to request that the current file position be moved.

Parameter	Description

LONG lParam1	Specifies the new file position according to the option flag specified in lParam2.

LONG lParam2	Specifies how the file position is changed. Only one of the following flags can be specified:

Value	Meaning

SEEK_SET

Move the file position to be lParam1 bytes from the beginning of the file.

SEEK_CUR

Move the file position to be lParam1 bytes from the current position. lParam1 may be positive or negative.

SEEK_END

Move the file position to be lParam1 bytes from the end of the file.

Returns

The return value is the new file position. If there is an error, the return value is -1.

Comments

The I/O procedure is responsible for maintaining the current file position in the lDiskOffset member of the MMIOINFO structure.

See Also

mmioSeek


MMIOM_WRITE message
MMIOM_WRITE (Win32)

This message is sent to an I/O procedure by mmioWrite to request that data be written to an open file.

Parameter	Description

LONG lParam1	Points to a buffer containing the data to write to the file.

LONG lParam2	Specifies the number of bytes to write to the file.

Returns

The return value is the number of bytes actually written to the file. If there is an error, the return value is -1.

Comments

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, MMIOM_READ, MMIOM_WRITEFLUSH


MMIOM_WRITEFLUSH message
MMIOM_WRITEFLUSH (Win32)

This message is sent to an I/O procedure by mmioWrite to request that data be written to an open file and then that any internal buffers used by the I/O procedure be flushed to disk.

Parameter	Description

LONG lParam1	Points to a buffer containing the data to write to the file.

LONG lParam2	Specifies the number of bytes to write to the file.

Returns

The return value is the number of bytes actually written to the file. If there is an error, the return value is -1.

Comments

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.

Note that this message is equivalent to the MMIOM_WRITE message except that it additionally 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, mmioFlush, MMIOM_READ, MMIOM_WRITE


MOM_CLOSE message
MOM_CLOSE (Win32)

This message is sent to a MIDI output callback function when a MIDI output device is closed. The device handle is no longer valid once this message has been sent.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

MM_MOM_CLOSE


MOM_DONE message
MOM_DONE (Win32)

This message is sent to a MIDI output callback function when the specified system-exclusive buffer has been played and is being returned to the application.

Parameter	Description

DWORD dwParam1	Points to a MIDIHDR structure identifying the buffer.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

MM_MOM_DONE


MOM_OPEN message
MOM_OPEN (Win32)

This message is sent to a MIDI output callback function when a MIDI output device is opened.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

MM_MOM_OPEN


SBM_ENABLE_ARROWS message
SBM_ENABLE_ARROWS (Win32)

SBM_ENABLE_ARROWS

wParam = (WPARAM) fuArrowFlags; /* scroll-bar arrow flags */

lParam = 0;                     /* not used, must be zero */

An application sends the SBM_ENABLE_ARROWS message to enable or disable one or both arrows of a scroll bar control.

Parameter	Description

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_ENABLE_BOTH	Enables both arrows on a 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_RTDN	Disables the right arrow on a horizontal scroll bar or the down arrow of a vertical scroll bar.

ESB_DISABLE_BOTH	Disables both arrows on a scroll bar.

Returns

If the message succeeds, the return value is TRUE; otherwise, it is FALSE.


SBM_GETPOS message
SBM_GETPOS (Win32)

SBM_GETPOS

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

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 message
SBM_GETRANGE (Win32)

SBM_GETRANGE

wParam = (WPARAM) (LPINT) lpnMinPos; /* minimum position */

lParam = (LPARAM) (LPINT) lpnMaxPos; /* maximum position */

An application sends the SBM_GETRANGE message to a scroll bar control to retrieve the minimum and maximum position values for the control.

Parameter	Description

lpnMinPos	Points to a value that receives the minimum scrolling position.

lpnfMaxPos	Points to a value that receives the maximum scrolling position.

Returns

This message does not return a value.

See Also

SBM_GETPOS, SBM_SETPOS, SBM_SETRANGE, SBM_SETRANGEREDRAW


SBM_SETPOS message
SBM_SETPOS (Win32)

SBM_SETPOS

wParam = (WPARAM) nPos;           /* new position of scroll box */

lParam = (LPARAM) (BOOL) fRedraw; /* redraw flag                */

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.

Parameter	Description

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.

Returns

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Comments

Setting the fRedraw parameter to FALSE is useful if the scroll bar control is redrawn by a subsequent call to another function.

See Also

SBM_GETPOS, SBM_GETRANGE, SBM_SETRANGE, SBM_SETRANGEREDRAW


SBM_SETRANGE message
SBM_SETRANGE (Win32)

SBM_SETRANGE

wParam = (WPARAM) nMinPos; /* minimum scrolling position */

lParam = (LPARAM) nMaxPos; /* maximum scrolling position */

An application sends the SBM_SETRANGE message to a scroll bar control to set the minimum and maximum position values for the control.

Parameter	Description

nMinPos	Specifies the minimum scrolling position.

fMaxPos	Specifies the maximum scrolling position.

Returns

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Comments

The default minimum and maximum position values are 0. The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than 32,767.

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 message
SBM_SETRANGEREDRAW (Win32)

SBM_SETRANGEREDRAW

wParam = (WPARAM) nMinPos; /* minimum scrolling position */

lParam = (LPARAM) nMaxPos  /* maximum scrolling position */

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.

Parameter	Description

nMinPos	Specifies the minimum scrolling position.

fMaxPos	Specifies the maximum scrolling position.

Returns

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Comments

The default minimum and maximum position values are 0. The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than 32,767.

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


STM_GETICON message
STM_GETICON (Win32)

STM_GETICON

wParam = 0; /* not used; must be zero */

lParam = 0; /* not used; must be zero */

An application sends the STM_GETICON message to retrieve the handle of the icon associated with an icon control.

Parameters

This message has no parameters.

Returns

The return value is the handle of the icon, or zero if either the icon control has no associated icon or if an error occurred.

See Also

STM_SETICON


STM_SETICON message
STM_SETICON (Win32)

STM_SETICON

wParam = (WPARAM) (HICON) hicon;    /* handle of icon         */

lParam = 0;                         /* not used, must be zero */

An application sends the STM_SETICON message to associate an icon with an icon control.

Parameter	Description

hicon	Value of wParam. Identifies the icon to associate with the icon control.

Returns

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


WIM_CLOSE message
WIM_CLOSE (Win32)

This message is sent to a waveform input callback function when a waveform input device is closed. The device handle is no longer valid once this message has been sent.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

MM_WIM_CLOSE


WIM_DATA message
WIM_DATA (Win32)

This message is sent to a waveform input callback function when waveform 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.

Parameter	Description

DWORD dwParam1	Points to a WAVEHDR structure identifying the buffer containing the waveform data.

DWORD dwParam2	Currently unused.

Returns

None.

Comments

The returned buffer may not be full. Use the dwBytesRecorded member of the WAVEHDR structure specified by dwParam1 to determine the number of bytes recorded into the returned buffer.

See Also

MM_WIM_DATA


WIM_OPEN message
WIM_OPEN (Win32)

This message is sent to a waveform input callback function when a waveform input device is opened.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

MM_WIM_OPEN


WM_ACTIVATE message
WM_ACTIVATE (Win32)

WM_ACTIVATE

fActive = LOWORD(wParam);           /* activation flag */

fMinimized = (BOOL) HIWORD(wParam); /* minimized flag  */

hwnd = (HWND) lParam;               /* window handle   */

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 and then to the window procedure of the top-level window being activated.

Parameter	Description

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.

hwnd	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, hwnd is the handle of the window being activated. If the value of fActive is WA_ACTIVE or WA_CLICKACTIVE, hwnd is the handle of the window being deactivated. This handle can be NULL.

Returns

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.

Comments

If the window is activated by a mouse click, it also receives a WM_MOUSEACTIVATE message.

See Also

WM_MOUSEACTIVATE, WM_NCACTIVATE, DefWindowProc, SetFocus


WM_ACTIVATEAPP message
WM_ACTIVATEAPP (Win32)

WM_ACTIVATEAPP

fActive = (BOOL) wParam;        /* activation flag   */

dwThreadID = (DWORD) lParam:    /* thread identifier */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

See Also

WM_ACTIVATE


WM_ASKCBFORMATNAME message
WM_ASKCBFORMATNAME (Win32)

WM_ASKCBFORMATNAME

cchName = (DWORD) wParam            /* size of buffer */

lpszFormatName = (LPTSTR) lParam    /* buffer to receive format name */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_CANCELJOURNAL (Win32)

WM_CANCELJOURNAL

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

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.

Comments

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-Escape, Alt-Escape, or Control-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-Escape, Alt-Escape, or Control-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-Escape, Alt-Escape, or Control-Alt-Del cause the system to cancel journaling regardless of a journaling application's behavior.

See Also

JournalPlaybackProc, JournalRecordProc, GetMsgProc, SetWindowsHookEx


WM_CANCELMODE message
WM_CANCELMODE (Win32)

WM_CANCELMODE

The WM_CANCELMODE message is sent to the focus window when a dialog box or message box is displayed, enabling the focus window to cancel modes such as mouse capture.

Parameters

This message has no parameters.

Returns

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_CHANGECBCHAIN message
WM_CHANGECBCHAIN (Win32)

WM_CHANGECBCHAIN

hwndRemove = (HWND) wParam;     /* handle of window being removed */

hwndNext = (HWND) lParam;       /* handle of next window in chain */

The WM_CHANGECBCHAIN message is sent to the first window in the clipboard viewer chain when a window is being removed from the chain.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_CHAR (Win32)

WM_CHAR

chCharCode = (TCHAR) wParam;    /* character code */

lKeyData = lParam;              /* key data       */

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.

Parameter	Description

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 a function key or a key on the numeric keypad. The value is 1 if it 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 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.

Returns

An application should return zero if it processes this message.

Comments

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 message
WM_CHARTOITEM (Win32)

WM_CHARTOITEM

nKey = LOWORD(wParam);          /* key value          */

nCaretPos = HIWORD(wParam);     /* caret position     */

hwndListBox = (HWND) lParam;    /* handle of list box */

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.

Parameter	Description

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.

Returns

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.

Comments

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 message
WM_CHILDACTIVATE (Win32)

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.

Parameters

This message has no parameters.

Returns

If an application processes this message, it should return zero.

See Also

MoveWindow, SetWindowPos


WM_CHOOSEFONT_GETLOGFONT message
WM_CHOOSEFONT_GETLOGFONT (Win32)

WM_CHOOSEFONT_GETLOGFONT

wParam = 0;                /* not used, must be zero            */

lParam = (LPLOGFONT) lplf; /* address of struct. with font data */

An application sends a WM_CHOOSEFONT_GETLOGFONT message to the Font dialog box created by the ChooseFont function to retrieve the current LOGFONT structure.

Parameter	Description

lplf	Points to a LOGFONT structure that receives information about the current logical font.

Returns

This message does not return a value.

Comments

An application uses this message to retrieve the LOGFONT structure while the Font dialog box is open. When the user closes the dialog box, the ChooseFont function receives information about the LOGFONT structure.

See Also

ChooseFont, WM_GETFONT, LOGFONT


WM_CLEAR message
WM_CLEAR (Win32)

WM_CLEAR

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

This message does not return a value.

Comments

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 contents into 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 message
WM_CLOSE (Win32)

WM_CLOSE

The WM_CLOSE message is sent as a signal that a window or an application should terminate.

Parameters

This message has no parameters.

Returns

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function calls the DestroyWindow function to destroy the window.

Comments

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 message
WM_COMMAND (Win32)

WM_COMMAND

wNotifyCode = HIWORD(wParam); /* notification code                        */

wID = LOWORD(wParam);         /* item, control, or accelerator identifier */

hwndCtl = (HWND) lParam;      /* handle of control                        */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

Accelerator keystrokes that select items from the System 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 System menu, a WM_COMMAND message is sent, even if the window is minimized.

See Also

WM_SYSCOMMAND


WM_COMPACTING message
WM_COMPACTING (Win32)

WM_COMPACTING

wCompactRatio = wParam; /* compacting ratio */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_COMPAREITEM (Win32)

WM_COMPAREITEM

idCtl = wParam;                       /* control identifier   */

lpcis = (LPCOMPAREITEMSTRUCT) lParam; /* structure with items */

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.

Parameter	Description

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.

Returns

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.

Comments

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_COPY message
WM_COPY (Win32)

WM_COPY

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

This message does not return a value.

Comments

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 message
WM_COPYDATA (Win32)

WM_COPYDATA

wParam = (WPARAM) (HWND) hwndFrom;   /* handle of sending window */

lParam = (LPARAM) (PCOPYDATASTRUCT) pcds; /* pointer to structure with data  */

The WM_COPYDATA message is sent when an application passes data to another application.

Parameter	Description

hwndData	Identifies the window passing the data.

pcds	Points to a COPYDATASTRUCT structure that contains the data to be passed.

Returns

If the receiving application processes this message, it should return TRUE; otherwise, it should return FALSE.

Comments

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 the pcds parameter. 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 message
WM_CPL_LAUNCH (win32)

WM_CPL_LAUNCH

hwnd = (HWND) wParam;          /* handle of sending window */

lpszAppName = (LPSTR) lParam;  /* application-name string  */

An application sends the WM_CPL_LAUNCH message to Windows Control Panel to request that a Control Panel application be started.

Parameter	Description

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.

Returns

If the application starts, the return value is TRUE; otherwise, it is FALSE.

See Also

WM_CPL_LAUNCHED


WM_CPL_LAUNCHED message
WM_CPL_LAUNCHED (Win32)

WM_CPL_LAUNCHED

fAppStarted = (BOOL) wParam;

The WM_CPL_LAUNCHED message is sent when a Windows 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.

Parameter	Description

fAppStarted	Value of wParam. Specifies whether the application was started. If the application was started, this parameter is TRUE; otherwise, it is FALSE.

Returns

The value returned by the application is ignored for this message.

See Also

WM_CPL_LAUNCH


WM_CREATE message
WM_CREATE (Win32)

WM_CREATE

lpcs = (LPCREATESTRUCT) lParam; /* structure with creation data */

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.

Parameter	Description

lParam	Value of lParam. Points to a CREATESTRUCT structure that contains information about the window being created. The members of the CREATESTRUCT structure are identical to the parameters of the CreateWindowEx function.

Returns

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 message
WM_CTLCOLORBTN (Win32)

WM_CTLCOLORBTN

hdcButton = (HDC) wParam;   /* handle of button display context */

hwndButton = (HWND) lParam; /* handle of button                 */

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.

Parameter	Description

hdcButton	Value of wParam. Identifies the display context for the button.

hwndButton	Value of lParam. Identifies the button.

Returns

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.

Comments

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, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC, DefWindowProc


WM_CTLCOLORDLG message
WM_CTLCOLORDLG (Win32)

WM_CTLCOLORDLG

hdcDlg = (HDC) wParam;   /* handle of dialog box display context */

hwndDlg = (HWND) lParam; /* handle of dialog box                 */

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.

Parameter	Description

hdcDlg	Value of wParam. Identifies the device context for the dialog box.

hwndDlg	Value of lParam. Identifies the dialog box.

Returns

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.

Comments

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 itself; all of the other WM_CTLCOLOR* messages are sent to the owner of the control.

See Also

DefWindowProc, WM_CTLCOLORBTN, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC, DefWindowProc


WM_CTLCOLOREDIT message
WM_CTLCOLOREDIT (Win32)

WM_CTLCOLOREDIT

hdcEdit = (HDC) wParam;   /* handle of display context */

hwndEdit = (HWND) lParam; /* handle of static control  */

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.

Parameter	Description

hdcEdit	Value of wParam. Identifies the device context for the edit control window.

hwndEdit	Value of lParam. Identifies the edit control.

Returns

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.

Comments

The WM_CTLCOLOREDIT message is never sent between threads, it is only sent within the same thread.

See Also

DefWindowProc, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORLISTBOX message
WM_CTLCOLORLISTBOX (Win32)

WM_CTLCOLORLISTBOX

hdcLB = (HDC) wParam;   /* handle of list box display context */

hwndLB = (HWND) lParam; /* handle of list box                 */

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.

Parameter	Description

hdcLB	Value of wParam. Identifies the device context for the list box.

hwndLB	Value of lParam. Identifies the list box.

Returns

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.

Comments

The WM_CTLCOLORLISTBOX message is never sent between threads. It is sent only within one thread.

See Also

DefWindowProc, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC, DefWindowProc


WM_CTLCOLORMSGBOX message
WM_CTLCOLORMSGBOX (Win32)

WM_CTLCOLORMSGBOX

hdcMB = (HDC) wParam;   /* handle of message box display context */

hwndMB = (HWND) lParam; /* handle of message box                 */

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.

Parameter	Description

hdcMB	Value of wParam. Identifies the device context for the message box.

hwndMB	Value of lParam. Identifies the message box.

Returns

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.

Comments

The WM_CTLCOLORMSGBOX message is never sent between threads. It is sent only within one thread.

See Also

DefWindowProc, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC, DefWindowProc


WM_CTLCOLORSCROLLBAR message
WM_CTLCOLORSCROLLBAR (Win32)

WM_CTLCOLORSCROLLBAR

hdcSB  = (HDC) wParam;   /* handle of scroll bar display context */

hwndSB = (HWND) lParam;  /* handle of scroll bar                  */

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.

Parameter	Description

hdcSB	Value of wParam. Identifies the display context for the scroll bar control.

hwndSB	Value of lParam. Identifies the scroll bar.

Returns

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.

Comments

The WM_CTLCOLORSCROLLBAR message is never sent between threads; it is only sent within the same thread.

See Also

DefWindowProc, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSTATIC


WM_CTLCOLORSTATIC message
WM_CTLCOLORSTATIC (Win32)

WM_CTLCOLORSTATIC

hdcStatic = (HDC) wParam;   /* handle of display context */

hwndStatic = (HWND) lParam; /* handle of static control  */

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 (DC) handle to set the text and background colors of the static control.

Parameter	Description

hdcStatic	Value of wParam. Identifies the DC for the static control window.

hwndStatic	Value of lParam. Identifies the static control.

Returns

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.

Comments

The WM_CTLCOLORSTATIC message is never sent between threads; it is sent only within the same thread.

See Also

DefWindowProc, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR


WM_CUT message
WM_CUT (Win32)

WM_CUT

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

This message does not return a value.

Comments

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 onto 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

WM_CLEAR, WM_COPY, WM_PASTE


WM_DDE_ACK message
WM_DDE_ACK (Win32)

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

The WM_DDE_ACK message notifies a dynamic data exchange (DDE) application of the receipt and processing of a WM_DDE_INITIATE, WM_DDE_EXECUTE, WM_DDE_DATA, WM_DDE_ADVISE, WM_DDE_UNADVISE, or WM_DDE_POKE message, and in some cases, of a WM_DDE_REQUEST message.

Parameter	Description

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 component is wStatus. The  High component 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.

For a full description of this structure, see Structures

hCommands	Identifies a global memory object containing 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 component is wStatus. The  High component is aItem.

Parameter	Description

wStatus	Specifies a DDEACK structure containing a series of flags that indicate the status of the response.

For a full description of this structure, see Structures

aItem	Contains a global atom that identifies the name of the data item for which the response is sent.

Comments

Posting

Except in response to the WM_DDE_INITIATE message, the application posts the WM_DDE_ACK message by calling the PostMessage function, not 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 hCommands object that accompanied 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 hOptions object posted with the original WM_DDE_ADVISE message. 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 hCommands object posted with the original WM_DDE_DATA, WM_DDE_POKE, or WM_DDE_EXECUTE message.

The application that receives a posted WM_DDE_ACK message must free the lPackedVal parameter by using the FreeDDElParam function.

See Also

FreeDDElParam, PackDDElParam, PostMessage, ReuseDDElParam, 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 message
WM_DDE_ADVISE (Win32)

WM_DDE_ADVISE

wParam = (WPARAM) hwnd;        /* handle of posting application  */

lParam = (LPARAM) lPackedVal;  /* packed DDEADVISE and item atom */

A dynamic data exchange (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.

Parameter	Description

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 component is hOptions. The  High component is aItem.

Parameter	Description

hOptions	Identifies a global memory object containing a DDEADVISE structure that specifies how the data is to be sent.

For a full description of this structure, see Structures

aItem	Contains an atom that identifies the data item requested.

Comments

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 links, not warm 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 component and aItem supplied as the High component.

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 component and aItem supplied as the High component.

See Also

FreeDDElParam, GlobalAddAtom, GlobalAlloc, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_DATA, WM_DDE_REQUEST


WM_DDE_DATA message
WM_DDE_DATA (Win32)

WM_DDE_DATA

wParam = (WPARAM) hwnd;         /* handle of posting application */

lParam = (LPARAM) lPackedVal;   /* packed DDEDATA and item atom  */

A dynamic data exchange (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.

Parameter	Description

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 component is hData or NULL. The  High component is aItem.

Parameter	Meaning

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 link. A warm link is established by the client sending a WM_DDE_ADVISE message with the fDeferUpd bit set.

For a full description of this structure, see Structures

aItem	Contains an atom that identifies the data item for which the data or notification is sent.

Comments

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 component and aItem supplied as the High component.

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 component and aItem supplied as the High component.

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 actual 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

FreeDDElParam, GlobalAddAtom, GlobalAlloc, PostMessage, ReuseDDElParam, SendMessage, WM_DDE_ACK, WM_DDE_ADVISE, WM_DDE_POKE, WM_DDE_REQUEST


WM_DDE_EXECUTE message
WM_DDE_EXECUTE (Win32)

WM_DDE_EXECUTE

wParam = (WPARAM) hwnd;        /* handle of posting application  */

lParam = (LPARAM) hCommands;   /* handle to global object */

A dynamic data exchange (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.

Parameter	Description

hwnd	Value of wParam. Identifies the client window posting the message.

hCommands	Value of lParam. Contains a global memory object which references an ANSI or UNICODE command string depending on the types of windows involved in the conversation.

Comments

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 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 always and only be used 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 an execute command string causes the server to terminate the conversation.

See Also

GlobalAlloc, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK


WM_DDE_INITIATE message
WM_DDE_INITIATE (Win32)

WM_DDE_INITIATE

wParam = (WPARAM) hwnd;             /* handle of posting appl. */

lParam = MAKELPARAM(aApp, aTopic);  /* appl. and topic atoms   */

A dynamic data exchange (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.)

Parameter	Description

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.

Comments

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 the WM_DDE_INITIATE message 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 the WM_DDE_INITIATE message.

See Also

GlobalAddAtom, GlobalAlloc, PostMessage, SendMessage, WM_DDE_ACK


WM_DDE_POKE message
WM_DDE_POKE (Win32)

WM_DDE_POKE

wParam = (WPARAM) hwnd;        /* handle of posting application  */

lParam = (LPARAM) lPackedVal;  /* packed DDEPOKE and item atom */

A dynamic data exchange (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.

Parameter	Description

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 component is hData. The  High component is aItem.

Parameter	Description

hData	Identifies a global memory object containing a DDEPOKE structure with the data and additional information.

For a full description of this structure, see Structures

aItem	Contains a global atom that identifies the data item for which the data or notification is being sent.

Comments

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 component and aItem supplied as the High component.

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 component and aItem supplied as the High component.

To free the hData object, the server should call the GlobalFree function. Additionally, if the data format is either CF_METAFILEPICT or CF_DSPMETAFILEPICT, the server also needs to call DeleteMetaFile with the embedded metafile handle. Those 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, then call DeleteMetaFile with the handle from the METAFILEPICT's hMF field.

To free the lPackedVal object, the server should call the FreeDDElParam function.

See Also

FreeDDElParam, GlobalAddAtom, GlobalAlloc, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK


WM_DDE_REQUEST message
WM_DDE_REQUEST (Win32)

WM_DDE_REQUEST

wParam = (WPARAM) hwnd;        /* handle of posting application  */

lParam = (LPARAM) lParam;      /* holds cfFormat and aItem       */

A dynamic data exchange (DDE) client application posts a WM_DDE_REQUEST message to a DDE server application to request the value of a data item.

Parameter	Description

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.

Comments

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 message
WM_DDE_TERMINATE (Win32)

WM_DDE_TERMINATE

wParam = (WPARAM) hwnd; /* handle of posting window */

lParam = 0;             /* not used, must be zero   */

A dynamic data exchange (DDE) application (client or server) posts a WM_DDE_TERMINATE message to terminate a conversation.

Parameter	Description

hwnd	Value of wParam. Identifies the client or server window posting the message.

Comments

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 message
WM_DDE_UNADVISE (Win32)

WM_DDE_UNADVISE

wParam = (WPARAM) hwnd;        /* handle of posting application  */

lParam = (LPARAM) lParam;      /* format and item atom           */

A dynamic data exchange (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 link for the specified item.

Parameter	Description

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.

Comments

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 message
WM_DEADCHAR (Win32)

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.

Parameter	Description

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 a function key or a key on the numeric keypad. The value is 1 if it 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 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.

Returns

An application should return zero if it processes this message.

Comments

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_SYSDEADCHAR


WM_DELETEITEM message
WM_DELETEITEM (Win32)

WM_DELETEITEM

idCtl = wParam;                      /* control identifier      */

lpdis = (LPDELETEITEMSTRUCT) lParam; /* structure with item info. */

The WM_DELETEITEM message is sent to the owner of an owner-drawn 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.

Parameter	Description

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.

For a full description of this structure, see Structures

Returns

An application should return TRUE if it processes this message.

See Also

CB_DELETESTRING, CB_RESETCONTENT, LB_DELETESTRING, LB_RESETCONTENT


WM_DESTROY message
WM_DESTROY (Win32)

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.

Parameters

This message has no parameters.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_DESTROYCLIPBOARD (Win32)

WM_DESTROYCLIPBOARD

The WM_DESTROYCLIPBOARD message is sent to the clipboard owner when the clipboard is emptied by a call to the EmptyClipboard function.

Parameters

This message has no parameters.

Returns

If an application processes this message, it should return zero.

See Also

EmptyClipboard


WM_DEVMODECHANGE message
WM_DEVMODECHANGE (Win32)

WM_DEVMODECHANGE

lpszDev = (LPCTSTR) lParam; /* address of device name */

The WM_DEVMODECHANGE message is sent to all top-level windows whenever the user changes device-mode settings.

Parameter	Description

lpszDev	Value of lParam. Points to the device name specified in the WIN.INI file.

Returns

An application should return zero if it processes this message.

Comments

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_DRAWCLIPBOARD message
WM_DRAWCLIPBOARD (Win32)

WM_DRAWCLIPBOARD

The WM_DRAWCLIPBOARD message is sent to the first window in the clipboard viewer chain when the contents of the clipboard change. This enables a clipboard viewer window to display the new contents of the clipboard.

Parameters

This message has no parameters.

Comments

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 the SetClipboardViewer function, and may change in response to a WM_CHANGECBCHAIN message.

See Also

SendMessage, SetClipboardViewer, WM_CHANGECBCHAIN


WM_DRAWITEM message
WM_DRAWITEM (Win32)

WM_DRAWITEM

idCtl = (UINT) wParam;             /* control identifier       */

lpdis = (LPDRAWITEMSTRUCT) lParam; /* item-drawing information */

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.

Parameter	Description

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.

Returns

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.

Comments

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


WM_DROPFILES message
WM_DROPFILES (Win32)

WM_DROPFILES

hDrop = (HANDLE) wParam;  /* handle of internal drop structure */

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.

Parameter	Description

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.

Returns

An application should return zero if it processes this message.

See Also

DragAcceptFiles, DragFinish, DragQueryFile, DragQueryPoint


WM_ENABLE message
WM_ENABLE (Win32)

WM_ENABLE

fEnabled = (BOOL) wParam;   /* enabled/disabled flag */

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_DISABLE style bit) of the window has changed.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

See Also

EnableWindow


WM_ENDSESSION message
WM_ENDSESSION (Win32)

WM_ENDSESSION

fEndSession = (BOOL) wParam;    /* end-session flag */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_ENTERIDLE (Win32)

WM_ENTERIDLE

fuSource = wParam;    /* idle-source flag                     */

hwnd = (HWND) lParam; /* handle of dialog box or owner window */

The WM_ENTERIDLE message informs an application's main window procedure that a modal dialog box or menu 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.

Parameter	Description

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

Returns

An application should return zero if it processes this message.

Comments

The DefWindowProc function returns zero.


WM_ENTERMENULOOP message
WM_ENTERMENULOOP (Win32) )

WM_ENTERMENULOOP

wParam = (BOOL) fIsTrackPopupMenu    /* flags a popup menu */

lParam = 0 ;          /* not used; must be zero */

The WM_ENTERMENULOOP message informs an application's main window procedure that a menu modal loop has been entered.

Parameter	Description

fIsTrackPopupMenu	Specifies whether the menu involved is a popup menu. Has a value of TRUE if it is a popup, FALSE if it isn't.

Returns

An application should return zero if it processes this message.

Comments

The DefWindowProc function returns zero.

See Also

WM_EXITMENULOOP


WM_EXITMENULOOP message
WM_EXITMENULOOP (Win32) )

WM_EXITLOOP

wParam = (BOOL) fIsTrackPopupMenu    /* flags a popup menu */

lParam = 0 ;          /* not used; must be zero */

The WM_ENTERMENULOOP message informs an application's main window procedure that a menu modal loop has been exited.

Parameter	Description

fIsTrackPopupMenu	Specifies whether the menu involved is a popup menu. Has a value of TRUE if it is a popup, FALSE if it isn't.

Returns

An application should return zero if it processes this message.

Comments

The DefWindowProc function returns zero.

See Also

WM_ENTERMENULOOP


WM_ERASEBKGND message
WM_ERASEBKGND (Win32)

WM_ERASEBKGND

hdc = (HDC) wParam; /* device-context handle */

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.

Parameter	Description

hdc	Value of wParam. Identifies the device context.

Returns

An application should return nonzero if it erases the background; otherwise, it should return zero.

Comments

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, WM_ICONERASEBKGND


WM_FONTCHANGE message
WM_FONTCHANGE (Win32)

WM_FONTCHANGE

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends the WM_FONTCHANGE message to all top-level windows in the system after changing the pool of font resources.

Parameters

This message has no parameters.

Comments

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 message
WM_GETDLGCODE (Win32)

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.

Parameters

This message has no parameters.

Returns

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	Non-default 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.

Comments

Although the DefWindowProc function always returns zero in response to the WM_GETDLGCODE message, the window functions 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 controls or standard controls modified by subclassing.

See Also

DefWindowProc, EM_SETSEL, WM_CHAR


WM_GETFONT message
WM_GETFONT (Win32)

WM_GETFONT

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends a WM_GETFONT message to a control to retrieve the font with which the control is currently drawing its text.

Parameters

This message has no parameters.

Returns

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 message
WM_GETHOTKEY (Win32)

WM_GETHOTKEY

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends a WM_GETHOTKEY message to determine the hot key associated with a window.

Parameters

This message has no parameters.

Returns

The return value is the virtual-key code of the hot key, or NULL if no hot key is associated with the window.

Comments

These hot keys are unrelated to the hot keys set by RegisterHotKey.

See Also

WM_SETHOTKEY


WM_GETMINMAXINFO message
WM_GETMINMAXINFO (Win32)

WM_GETMINMAXINFO

lpmmi = (LPMINMAXINFO) lParam; /* address of structure */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_GETTEXT (Win32)

WM_GETTEXT

wParam = (WPARAM) cchTextMax;   /* number of characters to copy */

lParam = (LPARAM) lpszText;     /* address of buffer for text   */

An application sends a WM_GETTEXT message to copy the text that corresponds to a window into a buffer provided by the caller.

Parameter	Description

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.

Returns

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.

Comments

For an edit control, the text to be copied is the contents of the edit control. For a combo box, the text is the contents 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.

See Also

DefWindowProc, GetWindowText, GetWindowTextLength, LB_GETTEXT, WM_GETTEXTLENGTH, WM_SETTEXT


WM_GETTEXTLENGTH message
WM_GETTEXTLENGTH (Win32)

WM_GETTEXTLENGTH

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

The return value is the length, in characters, of the text.

Default Action

The DefWindowProc function returns the length, in characters, of the text.

Comments

For an edit control, the text to be copied is the contents of the edit control. For a combo box, the text is the contents 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.

See Also

DefWindowProc, GetWindowText, GetWindowTextLength, LB_GETTEXTLEN, WM_GETTEXT


WM_HOTKEY message
WM_HOTKEY (Win32)

WM_HOTKEY

idHotKey = (int) wParam;    /* identifier of hot-key */

The WM_HOTKEY message is posted when the user presses a hot key registered by RegisterHotKey. The message is placed at the top of the message queue associated with the thread that registered the hot key.

Parameter	Description

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.

See Also

RegisterHotKey, WM_GETHOTKEY, WM_SETHOTKEY


WM_HSCROLL message
WM_HSCROLL (Win32)

WM_HSCROLL

nScrollCode = (int) LOWORD(wParam);   /* scroll bar value     */

nPos = (short int) HIWORD(wParam);   /* scroll box position  */

hwndScrollBar = (HWND) lParam;    /* handle of scroll bar */

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.

Parameter	Description

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	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_THUMBTRACK	Drag scroll box (thumb) to specified position. The current position is specified by the nPos parameter.

SB_TOP	Scroll to 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.

Returns

If an application processes this message, it should return zero.

Comments

The SB_THUMBTRACK notification code is typically used by applications that provide feedback as the user drags the scroll box.

If an application scrolls the contents 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 65535.

However, since SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange support 32-bit scrollbar position data, there is a way to circumvent the WM_*SCROLL messages' 16 bits barrier. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, SetScrollPos, WM_VSCROLL


WM_HSCROLLCLIPBOARD message
WM_HSCROLLCLIPBOARD (Win32)

WM_HSCROLLCLIPBOARD

hwndViewer = (HWND) wParam;         /* handle of clipboard viewer */

nScrollCode = (int) LOWORD(lParam); /* scroll bar code            */

nPos = (int) HIWORD(lParam);        /* scroll box position        */

The WM_HSCROLLCLIPBOARD 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 horizontal scroll bar. The owner should scroll the clipboard image and update the scroll bar values.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_ICONERASEBKGND (Win32)

WM_ICONERASEBKGND

hdc = (HDC) wParam; /* handle of device context */

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.

Parameter	Description

hdc	Value of wParam. Identifies the device context of the icon.

Returns

An application should return nonzero if it processes this message.

Comments

The DefWindowProc function fills the icon background with the class background brush of the parent window.

See Also

DefWindowProc, WM_ERASEBKGND


WM_INITDIALOG message
WM_INITDIALOG (Win32)

WM_INITDIALOG

hwndFocus = (HWND) wParam; /* handle of control to receive focus */

lInitParam = lParam;       /* initialization parameter           */

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.

Parameter	Description

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.

Returns

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.

Comments

The control to receive the default keyboard focus is always the first control in the dialog box that is visible, not disabled, and 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 message
WM_INITMENU (Win32)

WM_INITMENU

hmenuInit = (HMENU) wParam; /* handle of menu to initialize */

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.

Parameter	Description

hmenuInit	Value of wParam. Identifies the menu to be initialized.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_INITMENUPOPUP (Win32)

WM_INITMENUPOPUP

hmenuPopup = (HMENU) wParam;         /* handle of pop-up menu */

uPos = (UINT) LOWORD(lParam);        /* pop-up item position  */

fSystemMenu = (BOOL) HIWORD(lParam); /* System menu flag      */

The WM_INITMENUPOPUP message is sent when a pop-up menu is about to become active. This allows an application to modify the pop-up menu before it is displayed, without changing the entire menu.

Parameter	Description

hmenuPopup	Value of wParam. Identifies the pop-up menu.

uPos	Value of the low-order word of lParam. Specifies the zero-based relative position of the menu item that invokes the pop-up menu.

fSystemMenu	Value of the high-order word of lParam. Specifies whether the pop-up menu is the System menu. If the pop-up menu is the System menu (also known as Control menu), this parameter is TRUE; otherwise, it is FALSE.

Returns

If an application processes this message, it should return zero.

See Also

WM_INITMENU


WM_KEYDOWN message
WM_KEYDOWN (Win32)

WM_KEYDOWN

nVirtKey = (int) wParam;    /* virtual-key code */

lKeyData = lParam;          /* key data         */

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.

Parameter	Description

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.

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.

Returns

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.

Comments

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 message
WM_KEYUP (Win32)

WM_KEYUP

nVirtKey = (int) wParam;    /* virtual-key code */

lKeyData = lParam;          /* key data         */

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.

Parameter	Description

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 a function key or a key on the numeric keypad. The value is 1 if it is an extended key; otherwise, it is 0.

25-28	Reserved.

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.

Returns

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.

Comments

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 message
WM_KILLFOCUS (Win32)

WM_KILLFOCUS

hwndGetFocus = (HWND) wParam; /* handle of window receiving focus */

The WM_KILLFOCUS message is sent to a window immediately before it loses the keyboard focus.

Parameter	Description

hwndGetFocus	Value of wParam. Identifies the window that receives the keyboard focus (may be NULL).

Returns

An application should return zero if it processes this message.

Comments

If an application is displaying a caret, the caret should be destroyed at this point.

See Also

SetFocus, WM_SETFOCUS


WM_LBUTTONDBLCLK message
WM_LBUTTONDBLCLK (Win32)

WM_LBUTTONDBLCLK

fwKeys = wParam;        /* key flags                     */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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, SetCapture, SetDoubleClickTime, WM_LBUTTONDOWN, WM_LBUTTONUP, MAKEPOINTS


WM_LBUTTONDOWN message
WM_LBUTTONDOWN (Win32)

WM_LBUTTONDOWN

fwKeys = wParam;        /* key flags                     */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, SetCapture, WM_LBUTTONDBLCLK, WM_LBUTTONUP, MAKEPOINTS


WM_LBUTTONUP message
WM_LBUTTONUP (Win32)

WM_LBUTTONUP

fwKeys = wParam;        /* key flags                     */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, SetCapture, WM_LBUTTONDBLCLK, WM_LBUTTONDOWN, MAKEPOINTS


WM_MBUTTONDBLCLK message
WM_MBUTTONDBLCLK (Win32)

WM_MBUTTONDBLCLK

fwKeys = wParam;        /* key flags                     */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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, SetCapture, SetDoubleClickTime, WM_MBUTTONDOWN, WM_MBUTTONUP, MAKEPOINTS


WM_MBUTTONDOWN message
WM_MBUTTONDOWN (Win32)

WM_MBUTTONDOWN

fwKeys = wParam;        /* key flags                     */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, SetCapture, WM_MBUTTONDBLCLK, WM_MBUTTONUP, MAKEPOINTS


WM_MBUTTONUP message
WM_MBUTTONUP (Win32)

WM_MBUTTONUP

fwKeys = wParam;        /* key flags                     */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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, SetCapture, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN, MAKEPOINTS


WM_MDIACTIVATE message
WM_MDIACTIVATE (Win32)

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

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.

Parameter	Description

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.

Returns

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.

Comments

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 message
WM_MDICASCADE (Win32)

WM_MDICASCADE

wParam = (WPARAM) (UINT) fuCascade;  /* cascade flag           */

lParam = 0;                          /* not used, must be zero */

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.

Parameter	Description

fuCascade	Value of wParam. Specifies a cascade flag. The only flag currently available, MDITILE_SKIPDISABLED, prevents disabled MDI child windows from being cascaded.

Returns

If the message succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

WM_MDIICONARRANGE, WM_MDITILE


WM_MDICREATE message
WM_MDICREATE (Win32)

WM_MDICREATE

wParam = 0;                            /* not used, must be zero */

lParam = (LPARAM) (LPMDICREATESTRUCT) lpmdic;   /* creation data */

An application sends the WM_MDICREATE message to a multiple document interface (MDI) client window to create an MDI child window.

Parameter	Description

lpmdic	Points to an MDICREATESTRUCT structure containing information that Windows uses to create the MDI child window.

Returns

For a full description of this structure, see Structures

If the message succeeds, the return value is the handle of the new child window; otherwise, it is NULL.

Comments

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, WM_CREATE, WM_MDIDESTROY


WM_MDIDESTROY message
WM_MDIDESTROY (Win32)

WM_MDIDESTROY

wParam = (WPARAM) (HWND) hwndChild; /* handle of child to close   */

lParam = 0;                         /* not used, must be zero     */

An application sends the WM_MDIDESTROY message to a multiple document interface (MDI) client window to close an MDI child window.

Parameter	Description

hwndChild	Value of wParam. Identifies the MDI child window to be closed.

Returns

This message always returns zero.

Comments

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 message
WM_MDIGETACTIVE (Win32)

WM_MDIGETACTIVE

wParam = 0;  /* not used, must be zero */

lParam = (LPBOOL) lpfMaximized;  /* optional pointer to maximized state flag */

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.

Parameter	Description

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.

Returns

The return value is the handle of the active MDI child window.

Comments

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 message
WM_MDIICONARRANGE (Win32)

WM_MDIICONARRANGE

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

See Also

WM_MDICASCADE, WM_MDITILE


WM_MDIMAXIMIZE message
WM_MDIMAXIMIZE (Win32)

WM_MDIMAXIMIZE

wParam = (WPARAM) (HWND) hwndMax; /* handle of child to maximize */

lParam = 0;                       /* not used, must be zero      */

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

Parameter	Description

hwndMax	Value of wParam. Identifies the MDI child window to be maximized.

Returns

The return value is always zero.

Comments

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 message
WM_MDINEXT (Win32)

WM_MDINEXT

wParam = (WPARAM) (HWND) hwndChild; /* handle of child        */

lParam = (LPARAM) fNext;            /* next or previous child */

An application sends the WM_MDINEXT message to a multiple document interface (MDI) client window to activate the next or previous child window.

Parameter	Description

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.

Returns

The return value is always zero.

Comments

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 message
WM_MDIREFRESHMENU (Win32)

WM_MDIREFRESHMENU

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

If the message succeeds, the return value is the handle of the frame window menu; otherwise, it is NULL.

Comments

After sending this message, an application must call the DrawMenuBar function to update the menu bar.

See Also

DrawMenuBar, WM_MDISETMENU


WM_MDIRESTORE message
WM_MDIRESTORE (Win32)

WM_MDIRESTORE

wParam = (WPARAM) (HWND) hwndRes; /* handle of child to restore */

lParam = 0;                       /* not used, must be zero     */

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.

Parameter	Description

hwndRes	Value of wParam. Identifies the MDI child window to be restored.

Returns

The return value is always zero.

See Also

WM_MDIMAXIMIZE


WM_MDISETMENU message
WM_MDISETMENU (Win32)

WM_MDISETMENU

wParam = (WPARAM) (HMENU) hmenuFrame;  /* handle of frame menu  */

lParam = (LPARAM) (HMENU) hmenuWindow; /* handle of Window menu */

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.

Parameter	Description

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.

Returns

If the message succeeds, the return value is the handle of the old frame window menu; otherwise, it is zero.

Comments

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 message
WM_MDITILE (Win32)

WM_MDITILE

wParam = (WPARAM) (UINT) fuTile; /* tiling flag            */

lParam = 0;                      /* not used, must be zero */

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.

Parameter	Description

fuTile	Specifies a tiling flag. This parameter can be one of the following values:

Value	Description

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.

Returns

If the message succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

WM_MDICASCADE, WM_MDIICONARRANGE


WM_MEASUREITEM message
WM_MEASUREITEM (Win32)

WM_MEASUREITEM

idCtl = (UINT) wParam;                /* control identifier    */

lpmis = (LPMEASUREITEMSTRUCT) lParam; /* item-size information */

The WM_MEASUREITEM message is sent to the owner window of an owner-drawn button, combo box, list box, or menu item when the control or menu is created.

Parameter	Description

idCtl	Value of wParam. Contains the value of the CtlID member of the MEASUREITEMSTRUCT structure pointed to by lpmis. 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 non-zero, the message was sent by a combo box or by a list box.

If the value is non-zero, 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.

Returns

If an application processes this message, it should return TRUE.

Comments

When the owner window receives the WM_MEASUREITEM message, the owner fills in the MEASUREITEMSTRUCT structure pointed to by the lParam parameter of the messages 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

WM_INITDIALOG, MEASUREITEMSTRUCT


WM_MENUCHAR message
WM_MENUCHAR (Win32)

WM_MENUCHAR

chUser = (char) LOWORD(wParam); /* ASCII character */

fuFlag = (UINT) HIWORD(wParam); /* menu flag       */

hmenu = (HMENU) lParam;         /* handle of menu  */

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.

Parameter	Description

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	Pop-up menu

MF_SYSMENU	System menu

hmenu	Value of lParam. Identifies the active menu.

Returns

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.

Comments

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 message
WM_MENUSELECT (Win32)

WM_MENUSELECT

uItem = (UINT) LOWORD(wParam);   /* menu item or pop-up menu index */

fuFlags = (UINT) HIWORD(wParam); /* menu flags */

hmenu = (HMENU) lParam;          /* handle of menu clicked on */

The WM_MENUSELECT message is sent to a menu's owner window when the user selects a menu item.

Parameter	Description

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 invokes a pop-up menu, this parameter contains the menu index of the pop-up menu in the main menu, and the hMenu parameter then contains the handle of the main (clicked-on) menu; use the GetSubMenu function to get the menu handle of the pop-up menu.

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 invokes a pop-up menu.

MF_SYSMENU	Item is contained in the System menu (also known as Control menu). The hmenu parameter identifies the System menu associated with the message.

hmenu	Value of lParam. Identifies the menu that was clicked on.

Returns

If an application processes this message, it should return zero.

Comments

If the fuFlags parameter contains 0xFFFF and the hmenu parameter contains NULL, Windows has closed the menu because the user pressed the ESC key or clicked outside 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.


WM_MOUSEACTIVATE message
WM_MOUSEACTIVATE (Win32)

WM_MOUSEACTIVATE

hwndTopLevel = (HWND) wParam;       /* handle of top-level parent */

nHittest = (INT) LOWORD(lParam);    /* hit-test code              */

uMsg =    (UINT) HIWORD(lParam);    /* mouse message              */

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.

Parameter	Description

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 code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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.

Returns

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	Activate the window, and do not discard the mouse message.

MA_NOACTIVATE	Do not activate the window, and do not discard the mouse message.

MA_ACTIVATEANDEAT	Activate the window, and discard the mouse message.

MA_NOACTIVATEANDEAT	Do not activate the window, but discard 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 message
WM_MOUSEMOVE (Win32)

WM_MOUSEMOVE

fwKeys = wParam;        /* key flags                     */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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.

Comments

The MAKEPOINTS macro can be used to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, SetCapture, MAKEPOINTS


WM_MOVE message
WM_MOVE (Win32)

WM_MOVE

xPos = (int) LOWORD(lParam);    /* horizontal position */

yPos = (int) HIWORD(lParam);    /* vertical position   */

The WM_MOVE message is sent after a window has been moved.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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

POINTS, MAKEPOINTS


WM_NCACTIVATE message
WM_NCACTIVATE (Win32)

WM_NCACTIVATE

fActive = (BOOL) wParam;

The WM_NCACTIVATE message is sent to a window when its nonclient area needs to be changed to indicate an active or inactive state.

Parameter	Description

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.

Returns

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, DefWindowProc


WM_NCCALCSIZE message
WM_NCCALCSIZE (Win32)

WM_NCCALCSIZE

fCalcValidRects = (BOOL) wParam;        /* valid area flag */

lpncsp = (LPNCCALCSIZE_PARAMS) lParam;  /* address of data */

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 contents of the window's client area when the size or position of the window changes.

Parameter	Description

fCalcValidRects	Value of wParam. Specifies whether the application should indicate which part of the client area contains valid information. Windows will copy the valid information to the specified area within the new client area. If this parameter is TRUE, the application should specify which part of the client area is valid.

lpncsp	Value of 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.

Returns

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 message
WM_NCCREATE (Win32)

WM_NCCREATE

lpcs = (LPCREATESTRUCT) lParam; /* initialization data */

The WM_NCCREATE message is sent prior to the WM_CREATE message when a window is first created.

Parameter	Description

lpcs	Value of wParam. Points to the CREATESTRUCT structure for the window.

Returns

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 message
WM_NCDESTROY (Win32)

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.

Parameters

This message has no parameters.

Returns

If an application processes this message, it should return zero.

Comments

This message frees any memory internally allocated for the window.

See Also

DestroyWindow, WM_DESTROY, WM_NCCREATE


WM_NCHITTEST message
WM_NCHITTEST (Win32)

WM_NCHITTEST

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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.

Returns

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

Comments

The MAKEPOINTS macro can be used to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, GetCapture, MAKEPOINTS


WM_NCLBUTTONDBLCLK message
WM_NCLBUTTONDBLCLK (Win32)

WM_NCLBUTTONDBLCLK

nHittest = (INT) wParam;    /* hit-test code            */

pts = MAKEPOINTS(lParam);   /* position of cursor       */

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.

Parameter	Description

nHittest	Value of wParam. Specifies the hit-test code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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. For a full description of this structure, see Structures

Returns

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 carries out the appropriate action. If appropriate, DefWindowProc sends the WM_SYSCOMMAND message to the window.

Comments

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, WM_NCHITTEST, WM_NCLBUTTONDOWN, WM_NCLBUTTONUP, WM_SYSCOMMAND, MAKEPOINTS, POINT


WM_NCLBUTTONDOWN message
WM_NCLBUTTONDOWN (Win32)

WM_NCLBUTTONDOWN

nHittest = (INT) wParam;    /* hit-test code            */

pts = MAKEPOINTS(lParam);   /* position of cursor       */

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.

Parameter	Description

nHittest	Value of wParam. Specifies the hit-test code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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. For a full description of this structure, see Structures

Returns

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 carries out the appropriate action. If appropriate, DefWindowProc sends the WM_SYSCOMMAND message to the window.

Comments

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, WM_NCHITTEST, WM_NCLBUTTONDBLCLK, WM_NCLBUTTONUP, WM_SYSCOMMAND, MAKEPOINTS


WM_NCLBUTTONUP message
WM_NCLBUTTONUP (Win32)

WM_NCLBUTTONUP

nHittest = (INT) wParam;    /* hit-test code            */

pts = MAKEPOINTS(lParam);   /* mouse-cursor coordinates */

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.

Parameter	Description

nHittest	Value of wParam. Specifies the hit-test code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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. For a full description of this structure, see Structures

Returns

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 carries out the appropriate action. If appropriate, DefWindowProc sends the WM_SYSCOMMAND message to the window.

Comments

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, WM_NCHITTEST, WM_NCLBUTTONDBLCLK, WM_NCLBUTTONDOWN, WM_SYSCOMMAND, MAKEPOINTS


WM_NCMBUTTONDBLCLK message
WM_NCMBUTTONDBLCLK (Win32)

WM_NCMBUTTONDBLCLK

nHittest = (INT) wParam;    /* hit-test code            */

pts = MAKEPOINTS(lParam);   /* position of cursor       */

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.

Parameter	Description

nHittest	Value of wParam. Specifies the hit-test code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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. For a full description of this structure, see Structures

Returns

If an application processes this message, it should return zero.

Comments

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, WM_NCHITTEST, WM_NCMBUTTONDOWN, WM_NCMBUTTONUP, WM_SYSCOMMAND, MAKEPOINTS


WM_NCMBUTTONDOWN message
WM_NCMBUTTONDOWN (Win32)

WM_NCMBUTTONDOWN

nHittest = (INT) wParam;    /* hit-test code            */

pts = MAKEPOINTS(lParam);   /* position of cursor       */

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.

Parameter	Description

nHittest	Value of wParam. Specifies the hit-test code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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. For a full description of this structure, see Structures

Returns

If an application processes this message, it should return zero.

Comments

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, WM_NCHITTEST, WM_NCMBUTTONDBLCLK, WM_NCMBUTTONUP, WM_SYSCOMMAND, MAKEPOINTS


WM_NCMBUTTONUP message
WM_NCMBUTTONUP (Win32)

WM_NCMBUTTONUP

nHittest = (INT) wParam;    /* hit-test code            */

pts = MAKEPOINTS(lParam);   /* position of cursor       */

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.

Parameter	Description

nHittest	Value of wParam. Specifies the hit-test code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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. For a full description of this structure, see Structures

Returns

If an application processes this message, it should return zero.

Comments

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, WM_NCHITTEST, WM_NCMBUTTONDBLCLK, WM_NCMBUTTONDOWN, WM_SYSCOMMAND, MAKEPOINTS


WM_NCMOUSEMOVE message
WM_NCMOUSEMOVE (Win32)

WM_NCMOUSEMOVE

nHittest = (INT) wParam;    /* hit-test code            */

pts = MAKEPOINTS(lParam);   /* position of cursor       */

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.

Parameter	Description

nHittest	Value of wParam. Specifies the hit-test code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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. For a full description of this structure, see Structures

Returns

If an application processes this message, it should return zero.

Comments

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

The MAKEPOINTS macro can be used to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, WM_NCHITTEST, MAKEPOINTS


WM_NCPAINT message
WM_NCPAINT (Win32)

WM_NCPAINT

hrgn = (HRGN) wParam;   /* update-region handle */

An application sends the WM_NCPAINT message to a window when its frame must be painted.

Parameter	Description

hrgn	Value of wParam. Identifies the update region of the window. The update region is clipped to the window frame.

Returns

An application should return zero if it processes this message.

Comments

The DefWindowProc function paints the window frame.

Comments

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 message
WM_NCRBUTTONDBLCLK (Win32)

WM_NCRBUTTONDBLCLK

nHittest = (INT) wParam;    /* hit-test code            */

pts = MAKEPOINTS(lParam);   /* position of cursor       */

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.

Parameter	Description

nHittest	Value of wParam. Specifies the hit-test code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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. For a full description of this structure, see Structures

Returns

If an application processes this message, it should return zero.

Comments

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, WM_NCHITTEST, WM_NCRBUTTONDOWN, WM_NCRBUTTONUP, WM_SYSCOMMAND, MAKEPOINTS


WM_NCRBUTTONDOWN message
WM_NCRBUTTONDOWN (Win32)

WM_NCRBUTTONDOWN

nHittest = (INT) wParam;    /* hit-test code            */

pts = MAKEPOINTS(lParam);   /* position of cursor       */

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.

Parameter	Description

nHittest	Value of wParam. Specifies the hit-test code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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. For a full description of this structure, see Structures

Returns

If an application processes this message, it should return zero.

Comments

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, WM_NCHITTEST, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONUP, WM_SYSCOMMAND, MAKEPOINTS


WM_NCRBUTTONUP message
WM_NCRBUTTONUP (Win32)

WM_NCRBUTTONUP

nHittest = (INT) wParam;    /* hit-test code            */

pts = MAKEPOINTS(lParam);   /* position of cursor       */

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.

Parameter	Description

nHittest	Value of wParam. Specifies the hit-test code returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For more information, see the description of the WM_NCHITTEST message.

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. For a full description of this structure, see Structures

Returns

If an application processes this message, it should return zero.

Comments

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, WM_NCHITTEST, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONDOWN, WM_SYSCOMMAND, MAKEPOINTS


WM_NEXTDLGCTL message
WM_NEXTDLGCTL (Win32)

WM_NEXTDLGCTL

wCtlFocus = wParam;              /* identifies control for focus */

fHandle = (BOOL) LOWORD(lParam); /* wParam handle flag           */

The WM_NEXTDLGCTL message is sent to a dialog box procedure to set the keyboard focus to a different control in the dialog box.

Parameter	Description

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.

Returns

An application should return zero if it processes this message.

Comments

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_PAINT message
WM_PAINT (Win32)

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.

Parameters

This message has no parameters.

Returns

An application should return zero if it processes this message.

Comments

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 the GetMessage or PeekMessage function 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.

See Also

BeginPaint, DispatchMessage, EndPaint, GetMessage, PeekMessage, RedrawWindow, UpdateWindow, WM_ERASEBKGND, WM_NCPAINT


WM_PAINTCLIPBOARD message
WM_PAINTCLIPBOARD (Win32)

WM_PAINTCLIPBOARD

hwndViewer = (HWND) wParam;     /* handle of clipboard viewer   */

hglbPs = (HGLOBAL) lParam;      /* handle of PAINTSTRUCT object */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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 the PAINTSTRUCT structure 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, WM_SIZECLIPBOARD, PAINTSTRUCT


WM_PAINTICON message
WM_PAINTICON (Win32)

WM_PAINTICON

The WM_PAINTICON message is sent to a minimized window when the icon is to be painted. A window receives this message only if a class icon is defined for the window. Otherwise, WM_PAINT is sent instead.

Parameters

This message has no parameters.

Returns

An application should return zero if it processes this message.

Comments

The DefWindowProc function draws the class icon.

For compatibility with Windows 3.x, the wParam parameter is TRUE. However, this value has no significance.

See Also

DefWindowProc, WM_ICONERASEBKGND, WM_PAINT


WM_PALETTECHANGED message
WM_PALETTECHANGED (Win32)

WM_PALETTECHANGED

hwndPalChg = (HWND) wParam; /* handle of window that changed palette */

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 without the keyboard focus that uses a color palette to realize its logical palette and update its client area.

Parameter	Description

hwndPalChg	Value of wParam. Identifies the window that caused the system palette to change.

Comments

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 message
WM_PALETTEISCHANGING (Win32)

WM_PALETTEISCHANGING

hwndRealize = (HWND) wParam; /* window to realize palette */

The WM_PALETTEISCHANGING message informs applications that an application is going to realize its logical palette.

Parameter	Description

hwndRealize	Value of wParam. Identifies the window that is going to realize its logical palette.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_PARENTNOTIFY (Win32)

WM_PARENTNOTIFY

fwEvent = LOWORD(wParam);  /* event flags                      */

idChild = HIWORD(wParam);  /* identifier of child window       */

lValue = lParam;        /* child handle, or cursor coordinates */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_PASTE (Win32)

WM_PASTE

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends a WM_PASTE message to an edit control or combo box to copy the current contents 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.

Parameters

This message has no parameters.

Returns

This message does not return a value.

Comments

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 message
WM_POWER (Win32)

WM_POWER

fwPowerEvt = wParam;    /* power-event notification message */

The WM_POWER message is sent when the system, typically a battery-powered personal computer, is about to enter the suspended mode.

Parameter	Description

fwPowerEvt	Value of wParam. Specifies a power-event notification message. This parameter can be one of the following values:

Value	Meaning

PWR_SUSPENDREQUEST	Indicates that the system is about to enter the suspended mode.

PWR_SUSPENDRESUME	Indicates that the system is resuming operation after having entered the 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.

PWR_CRITICALRESUME	Indicates that the system is resuming operation after entering the suspended mode without first sending a PWR_SUSPENDREQUEST notification message to the application. An application should perform any necessary recovery actions.

Returns

The value an application should return 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.

Comments

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_QUERYDRAGICON message
WM_QUERYDRAGICON (Win32)

WM_QUERYDRAGICON

The WM_QUERYDRAGICON message is sent to a minimized (iconic) window which is about to be dragged by the user but which 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.

Parameters

This message has no parameters.

Returns

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.

Comments

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 file and to retrieve this handle.

See Also

DefWindowProc, LoadCursor, LoadIcon


WM_QUERYENDSESSION message
WM_QUERYENDSESSION (Win32)

WM_QUERYENDSESSION

nSource = (UINT) wParam;    /* source of end-session request */

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.

Parameter	Description

nSource	Value of wParam. Specifies the source of the request to end the Windows session. This parameter is zero if the request occurred because the user clicked the Logoff or Shutdown button in the Windows NT Security dialog box. This parameter is nonzero if the user clicked the End Task button in the Task List dialog box.

Returns

If an application can terminate conveniently, it should return TRUE; otherwise, it should return FALSE.

Default Action

The DefWindowProc function returns TRUE.

See Also

DefWindowProc, ExitWindows, WM_ENDSESSION


WM_QUERYNEWPALETTE message
WM_QUERYNEWPALETTE (Win32)

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.

Parameters

This message has no parameters.

Returns

If the window realizes its logical palette, it must return TRUE; otherwise, it must return FALSE.

See Also

WM_PALETTECHANGED, WM_PALETTEISCHANGING


WM_QUERYOPEN message
WM_QUERYOPEN (Win32)

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.

Parameters

This message has no parameters.

Returns

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.

Comments

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 message
WM_QUEUESYNC (Win32)

WM_QUEUESYNC

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

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.

Parameters

This message has no parameters.

Returns

A CBT application should return zero if it processes this message.

Comments

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 message
WM_QUIT (Win32)

WM_QUIT

nExitCode = (int) wParam;   /* exit code */

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.

Parameter	Description

nExitCode	Value of wParam. Specifies the exit code given in the PostQuitMessage function.

Returns

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_RBUTTONDBLCLK message
WM_RBUTTONDBLCLK (Win32)

WM_RBUTTONDBLCLK

fwKeys = wParam;        /* key flags                     */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

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, SetCapture, SetDoubleClickTime, WM_RBUTTONDOWN, WM_RBUTTONUP, MAKEPOINTS


WM_RBUTTONDOWN message
WM_RBUTTONDOWN (Win32)

WM_RBUTTONDOWN

fwKeys = wParam;        /* key flags                     */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, SetCapture, WM_RBUTTONDBLCLK, WM_RBUTTONUP, MAKEPOINTS


WM_RBUTTONUP message
WM_RBUTTONUP (Win32)

WM_RBUTTONUP

fwKeys = wParam;        /* key flags                     */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

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.

Parameter	Description

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.

Returns

If an application processes this message, it should return zero.

Comments

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, SetCapture, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN, MAKEPOINTS


WM_RENDERALLFORMATS message
WM_RENDERALLFORMATS (Win32)

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

Parameters

This message has no parameters.

Returns

If an application processes this message, it should return zero.

Comments

When responding to a WM_RENDERFORMAT or WM_RENDERALLFORMATS message, the clipboard owner must not open the clipboard 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 the SetClipboardData function.

See Also

SetClipboardData, WM_RENDERFORMAT


WM_RENDERFORMAT message
WM_RENDERFORMAT (Win32)

WM_RENDERFORMAT

uFormat = (UINT) wParam;    /* clipboard format */

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.

Parameter	Description

uFormat	Specifies the clipboard format to be rendered.

Returns

If an application processes this message, it should return zero.

Comments

When responding to a WM_RENDERFORMAT or WM_RENDERALLFORMATS message, the clipboard owner must not open the clipboard before calling SetClipboardData.

See Also

SetClipboardData, WM_RENDERALLFORMATS


WM_SETCURSOR message
WM_SETCURSOR (Win32)

WM_SETCURSOR

hwnd = (HWND) wParam;       /* handle of window with cursor */

nHittest = LOWORD(lParam);  /* hit-test code                */

wMouseMsg = HIWORD(lParam); /* mouse-message identifier     */

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.

Parameter	Description

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.

Comments

The high-order word of lParam is zero when the window enters menu mode.

See Also

DefWindowProc, MessageBeep


WM_SETFOCUS message
WM_SETFOCUS (Win32)

WM_SETFOCUS

hwndLoseFocus = (HWND) wParam; /* handle of window losing focus */

The WM_SETFOCUS message is sent to a window after it has gained the keyboard focus.

Parameter	Description

hwndLoseFocus	Value of wParam. Identifies the window that has lost the keyboard focus (may be NULL).

Returns

An application should return zero if it processes this message.

Comments

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 message
WM_SETFONT (Win32)

WM_SETFONT

wParam = (WPARAM) hfont;            /* handle of font */

lParam = MAKELPARAM(fRedraw, 0);    /* redraw flag    */

An application sends a WM_SETFONT message to specify the font that a control is to use when drawing text.

Parameter	Description

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.

Returns

This message does not return a value.

Comments

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 message
WM_SETHOTKEY (Win32)

WM_SETHOTKEY

wParam = (WPARAM) vkey;     /* virtual-key code of hot key */

lParam = 0;                 /* not used, must be zero      */

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.

Parameter	Description

vkey	Value of wParam. Specifies the virtual-key code of the hot key to associate with the window. Setting this parameter to NULL removes the hot key associated with a window.

Returns

The return value is one of the following:

Value	Meaning

2	The function is successful, but another window already has the same hot key.

1	The function is successful and no other window has the same hot key.

0	The function is unsuccessful--the window is invalid.

-1	The function is unsuccessful--the hot key is invalid.

Comments

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_SETREDRAW message
WM_SETREDRAW (Win32)

WM_SETREDRAW

wParam = (WPARAM) fRedraw;  /* state of redraw flag   */

lParam = 0;                 /* not used, must be zero */

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.

Parameter	Description

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.

Returns

An application should return zero if it processes this message.

Comments

This message sets or clears the redraw flag. If the redraw flag is cleared, the contents 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 message
WM_SETTEXT (Win32)

WM_SETTEXT

wParam = 0;                     /* not used, must be zero        */

lParam = (LPARAM)(LPCTSTR)lpsz; /* address of window-text string */

An application sends a WM_SETTEXT message to set the text of a window.

Parameter	Description

lpsz	Value of wParam. Points to a null-terminated string that is the window text.

Returns

The return value is TRUE if the text is set. It is 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.

Comments

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_SHOWWINDOW message
WM_SHOWWINDOW (Win32)

WM_SHOWWINDOW

fShow = (BOOL) wParam;      /* show/hide flag */

fnStatus = (int) lParam;    /* status flag    */

The WM_SHOWWINDOW message is sent to a window when the window is about to be hidden or shown.

Parameter	Description

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_PARENTCLOSING	Window's owner window is being minimized.

SW_PARENTOPENING	Window's owner window is being restored.

Returns

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.

Comments

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 message
WM_SIZE (Win32)

WM_SIZE

fwSizeType = wParam;      /* resizing flag                     */

nWidth = LOWORD(lParam);  /* width of client area              */

nHeight = HIWORD(lParam); /* height of client area             */

The WM_SIZE message is sent to a window after its size has changed.

Parameter	Description

fwSizeType	Value of wParam. Specifies the type of resizing requested. This parameter can be one of the following values:

Value	Meaning

SIZE_MAXIMIZED	Window has been maximized.

SIZE_MINIMIZED	Window has been minimized.

SIZE_RESTORED	Window has been resized, but neither the SIZE_MINIMIZED nor SIZE_MAXIMIZED value applies.

SIZE_MAXHIDE	Message is sent to all pop-up windows when some other window is maximized.

SIZE_MAXSHOW	Message is sent to all pop-up windows when some other window has been restored to its former size.

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.

Returns

If an application processes this message, it should return zero.

Comments

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.

Note that the nWidth and nHeight parameters are limited to one word. Although a window can be created with a dword height or width that is a doubleword, the WM_SIZE message cannot use values of that size.

See Also

MoveWindow, SetScrollPos


WM_SIZECLIPBOARD message
WM_SIZECLIPBOARD (Win32)

WM_SIZECLIPBOARD

hwndViewer = (HWND) wParam;  /* handle of clipboard viewer */

hglbRc = (HGLOBAL) lParam;   /* handle of RECT object      */

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.

Parameter	Description

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.

For a full description of this structure, see Structures.Comments

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 the RECT structure. Before returning, the clipboard owner must unlock the object by using the GlobalUnlock function.

See Also

GlobalLock, GlobalUnlock, RECT


WM_SPOOLERSTATUS message
WM_SPOOLERSTATUS (Win32)

WM_SPOOLERSTATUS

fwJobStatus = wParam;       /* job-status flag          */

cJobsLeft = LOWORD(lParam); /* number of jobs remaining */

The WM_SPOOLERSTATUS message is sent from Windows Print Manager whenever a job is added to or removed from the Print Manager queue.

Parameter	Description

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.

Returns

An application should return zero if it processes this message.

Comments

This message is for informational purposes only.


WM_SYSCHAR message
WM_SYSCHAR (Win32)

WM_SYSCHAR

chCharCode = (TCHAR) wParam;   /* character code */

lKeyData = lParam;             /* key data       */

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.

Parameter	Description

chCharCode	Value of wParam. Specifies the character code of the System-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 a function key or a key on the numeric keypad. The value is 1 if it 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 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.

Returns

An application should return zero if it processes this message.

Comments

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 message
WM_SYSCOLORCHANGE (Win32)

WM_SYSCOLORCHANGE

The WM_SYSCOLORCHANGE message is sent to all top-level windows when a change is made to a system color setting.

Parameters

This message has no parameters.

Comments

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.

See Also

WM_PAINT


WM_SYSCOMMAND message
WM_SYSCOMMAND (Win32)

WM_SYSCOMMAND

uCmdType = wParam;      /* command value                 */

xPos = LOWORD(lParam);  /* horizontal position of cursor */

yPos = HIWORD(lParam);  /* vertical position of cursor   */

The WM_SYSCOMMAND message is sent when the user chooses a command from the System menu (also known as Control menu) or when the user chooses the Maximize button or Minimize button.

Parameter	Description

uCmdType	Value of wParam. Specifies the type of system command requested. This parameter can be one of the following values:

Value	Meaning

SC_CLOSE	Closes the window.

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 a menu through a keystroke.

SC_MAXIMIZE (or SC_ZOOM)	Maximizes the window.

SC_MINIMIZE (or SC_ICON)	Minimizes the window.

SC_MOUSEMENU	Retrieves a menu through 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	Value of the low-order word of lParam. Specifies the x-coordinate of the cursor, in screen coordinates, if a System menu command is chosen with the mouse. Otherwise, this parameter is not used.

yPos	Value of the high-order word of lParam. Specifies the y-coordinate of the cursor, in screen coordinates, if a System menu command is chosen with the mouse. Otherwise, this parameter is not used.

Returns

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function carries out the System menu request for the predefined actions specified in the preceding table.

Comments

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 System menu can be modified by using the GetSystemMenu, AppendMenu, InsertMenu, and ModifyMenu functions. Applications that modify the System menu must process WM_SYSCOMMAND messages.

An application can carry out any system command at any time by passing a WM_SYSCOMMAND message to the DefWindowProc function. 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 System 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 message
WM_SYSDEADCHAR (Win32)

WM_SYSDEADCHAR

chCharCode = (TCHAR) wParam;    /* character code */

lKeyData = lParam;              /* key data       */

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.

Parameter	Description

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 a function key or a key on the numeric keypad. The value is 1 if it 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 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.

Returns

An application should return zero if it processes this message.

See Also

TranslateMessage, WM_DEADCHAR, WM_SYSKEYDOWN


WM_SYSKEYDOWN message
WM_SYSKEYDOWN (Win32)

WM_SYSKEYDOWN

nVirtKey = (int) wParam;    /* virtual-key code */

lKeyData = lParam;          /* key data         */

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.

Parameter	Description

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 a function key or a key on the numeric keypad. The value is 1 if it 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 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.

Returns

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.

Comments

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 message
WM_SYSKEYUP (Win32)

WM_SYSKEYUP

nVirtKey = (int) wParam;    /* virtual-key code */

lKeyData = lParam;          /* key data         */

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.

Parameter	Description

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 a function key or a key on the numeric keypad. The value is 1 if it 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 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.

Returns

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.

Comments

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-USA enhanced 102-key keyboards, the right ALT key is handled as a CTRL+ALT key. The following shows the sequence of messages that result when the user presses and releases this key:

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_TIMECHANGE message
WM_TIMECHANGE (Win32)

WM_TIMECHANGE

wParam = 0; /* not used, must be zero */

lParam = 0; /* not used, must be zero */

An application sends the WM_TIMECHANGE message to all top-level windows after changing the system time.

Parameters

This message has no parameters.

Returns

An application should return zero if it processes this message.

Comments

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 message
WM_TIMER (Win32)

WM_TIMER

wTimerID = wParam;            /* timer identifier          */

tmprc = (TIMERPROC *) lParam; /* address of timer callback */

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.

Parameter	Description

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.

Returns

An application should return zero if it processes this message.

Comments

The DispatchMessage function forwards this message when no other messages are in the thread's message queue.

See Also

DispatchMessage, SetTimer, TimerProc


WM_UNDO message
WM_UNDO (Win32)

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.

Parameters

This message has no parameters.

Returns

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 message
WM_USER (Win32)

WM_USER

The WM_USER constant is used by applications to help define private messages.

Comments

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 in different Windows sessions.

Message numbers in the fifth range (greater than 0xFFFF) are reserved for future use by Windows.

See Also

RegisterWindowMessage


WM_VKEYTOITEM message
WM_VKEYTOITEM (Win32)

WM_VKEYTOITEM

vkey = LOWORD(wParam);      /* virtual-key code   */

nCaretPos = HIWORD(wParam); /* caret position     */

hwndLB = lParam;            /* handle of list box */

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.

Parameter	Description

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.

Returns

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 message
WM_VSCROLL (Win32)

WM_VSCROLL

nScrollCode = (int) LOWORD(wParam); /* scroll bar value     */

nPos = (short int) HIWORD(wParam);        /* scroll box position  */

hwndScrollBar = (HWND) lParam;      /* handle of scroll bar */

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.

Parameter	Description

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

Returns

If an application processes this message, it should return zero.

Comments

The SB_THUMBTRACK notification code is typically used by applications that provide feedback as the user drags the scroll box.

If an application scrolls the contents 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 65535.

However, since SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange support 32-bit scrollbar position data, there is a way to circumvent the WM_*SCROLL messages' 16 bits barrier. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, SetScrollPos, WM_HSCROLL


WM_VSCROLLCLIPBOARD message
WM_VSCROLLCLIPBOARD (Win32)

WM_VSCROLLCLIPBOARD

hwndViewer = (HWND) wParam;         /* handle of clipboard viewer */

nScrollCode = (int) LOWORD(lParam); /* scroll bar code            */

nPos = (int) HIWORD(lParam);        /* scroll box position        */

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.

Parameter	Description

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 nScrlCode parameter is SB_THUMBPOSITION; otherwise, the nPos parameter is not used.

Returns

If an application processes this message, it should return zero.

Comments

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 message
WM_WINDOWPOSCHANGED (Win32)

WM_WINDOWPOSCHANGED

lpwp = (LPWINDOWPOS) lParam; /* points to size and position data */

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 SetWindowPos or another window-management function.

Parameter	Description

lpwp	Value of lParam. Points to a WINDOWPOS structure that contains information about the window's new size and position.

Returns

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.

Comments

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 message
WM_WINDOWPOSCHANGING (Win32)

WM_WINDOWPOSCHANGING

lpwp = (LPWINDOWPOS) lParam; /* points to size and position data */

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 SetWindowPos or another window-management function.

Parameter	Description

lpwp	Value of lParam. Points to a WINDOWPOS structure that contains information about the window's new size and position.

Returns

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_BYTEALIGN client styles. An application can override this by not passing the WM_WINDOWPOSCHANGING message to the DefWindowProc function.

Comments

While this message is being processed, modifying any of the values in the WINDOWPOS structure 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 the WINDOWPOS structure.

See Also

DefWindowProc, EndDeferWindowPos, SetWindowPos, WINDOWPOS, WM_GETMINMAXINFO, WM_MOVE, WM_SIZE, WM_WINDOWPOSCHANGED


WM_WININICHANGE message
WM_WININICHANGE (Win32)

WM_WININICHANGE

wParam = 0;                          /* not used, must be zero */

lParam = (LPARAM) (LPCTSTR) pszSection; /* section-name string */

An application sends the WM_WININICHANGE message to all top-level windows after making a change to the WIN.INI file. The SystemParametersInfo function sends the WM_WININICHANGE message after an application uses the function to change a setting in WIN.INI.

Parameter	Description

pszSection	Value of lParam. Points to a string containing the name of the section that has changed. The string does not include the square brackets that enclose the section name.

Returns

An application should return zero if it processes this message.

Comments

To send the WM_WININICHANGE message to all top-level windows, an application can use the SendMessage function with the hwnd parameter set to HWND_BROADCAST.

Some applications send this message with lParam set to NULL. If an application receives this message with an lParam value of NULL, it should check all sections in WIN.INI that affect the application.

Calls to functions that change WIN.INI 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\Microsoft\

        Windows NT\CurrentVersion\IniFileMapping

The change in the storage location has no effect on the behavior of this message.

See Also

SendMessage, SystemParametersInfo, WM_DEVMODECHANGE


WOM_CLOSE message
WOM_CLOSE (Win32)

This message is sent to a waveform output callback function when a waveform output device is closed. The device handle is no longer valid once this message has been sent.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

MM_WOM_CLOSE


WOM_DONE message
WOM_DONE (Win32)

This message is sent to a waveform output callback function when the specified 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 waveOutReset.

Parameter	Description

DWORD dwParam1	Points to a WAVEHDR structure identifying the buffer.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

MM_WOM_DONE


WOM_OPEN message
WOM_OPEN (Win32)

This message is sent to a waveform output callback function when a waveform output device is opened.

Parameter	Description

DWORD dwParam1	Currently unused.

DWORD dwParam2	Currently unused.

Returns

None.

See Also

MM_WOM_OPEN


Messages (all)

BM_GETCHECK	Retrieves the button check state

BM_GETSTATE	Determines the state of a button or check box

BM_SETCHECK	Places or removes a button check mark

BM_SETSTATE	Sets the highlighting state of a button

BM_SETSTYLE	Sets the style of a button

BN_CLICKED	Indicates the user clicked a button

BN_DISABLE	Indicates a button is disabled

BN_DOUBLECLICKED	Indicates the user double-clicked a button

BN_HILITE	Indicates the user highlighted a button

BN_PAINT	Indicates the button should be painted

BN_UNHILITE	Indicates the highlight should be removed

CB_ADDSTRING	Adds a string to the list box of a combo box

CB_DELETESTRING	Deletes list-box string in a combo box

CB_DIR	Adds file names to the list box of a combo box

CB_FINDSTRING	Finds a string in the list box of a combo box

CB_FINDSTRINGEXACT	Finds prefix string in the list box of a combo box

CB_GETCOUNT	Gets the number of list-box items in a combo box

CB_GETCURSEL	Gets index of selected list-box item in combo box

CB_GETDROPPEDCONTROLRECT	Gets rectangle of combo-box drop-down list box

CB_GETDROPPEDSTATE	Determines if a combo box's list box is visible

CB_GETEDITSEL	Gets position of selection in edit control

CB_GETEXTENDEDUI	Determines if combo box has the extended interface

CB_GETITEMDATA	Retrieves an application supplied value

CB_GETITEMHEIGHT	Retrieves the height of items in a combo box

CB_GETLBTEXT	Gets a string from the list box of a combo box

CB_GETLBTEXTLEN	Gets length of a list-box string in a combo box

CB_GETLOCALE	Get current combo box locale

CB_INSERTSTRING	Inserts a string into the list box of a combo box

CB_LIMITTEXT	Limits amount of edit-control text in a combo box

CB_RESETCONTENT	Removes all items from the list box of a combo box

CB_SELECTSTRING	Selects a string in the list box of a combo box

CB_SETCURSEL	Selects a string in the list box of a combo box

CB_SETEDITSEL	Sets the edit-control selection of a combo box

CB_SETEXTENDEDUI	Sets the default or extended user interface

CB_SETITEMDATA	Sets an application-defined value

CB_SETITEMHEIGHT	Sets the height of items in a combo box

CB_SETLOCALE	Set current combo box locale

CB_SHOWDROPDOWN	Shows or hides the list box of a combo box

CBN_CLOSEUP	Indicates the list box of a combo box has closed

CBN_DBLCLK	Indicates the user double-clicked a string

CBN_DROPDOWN	Indicates the list box of a combo box is dropping down

CBN_EDITCHANGE	Indicates the user has changed text in the edit control

CBN_EDITUPDATE	Indicates altered text is about to be displayed

CBN_ERRSPACE	Indicates the combo box is out of memory

CBN_KILLFOCUS	Indicates the combo box is losing the input focus

CBN_SELCHANGE	Indicates a new combo box list item is selected

CBN_SELENDCANCEL	Indicates the user's selection should be cancelled

CBN_SELENDOK	Indicates the user's selection is valid

CBN_SETFOCUS	Indicates the combo box is receiving the input focus

CPL_DBLCLK	Indicates a Control Panel applet was selected

CPL_EXIT	Indicates an applet DLL is being freed

CPL_GETCOUNT	Requests number of applications serviced

CPL_INIT	Initiates Control Panel DLL initialization

CPL_INQUIRE	Requests information about an application

CPL_NEWINQUIRE	Requests information about an application

CPL_SELECT	Indicates the user selected an application

CPL_STOP	Indicates Control Panel is exiting

DM_GETDEFID	Gets the identifier of the default push button control

DM_SETDEFID	Sets the default push button of a dialog box

EM_CANUNDO	Determines if edit-control operation can be undone

EM_EMPTYUNDOBUFFER	Resets (clears) the edit-control undo flag

EM_FMTLINES	Sets soft line break characters on or off

EM_GETFIRSTVISIBLELINE	Gets index of top line in an edit control

EM_GETHANDLE	Gets the handle of the memory for an MLE

EM_GETLINE	Retrieves a line from an MLE

EM_GETLINECOUNT	Retrieves number of lines in an MLE

EM_GETMODIFY	Checks whether edit-control contents have changed

EM_GETPASSWORDCHAR	Retrieves edit-control password character

EM_GETRECT	Gets the coordinates of an edit-control rectangle

EM_GETSEL	Gets position of current edit-contol selection

EM_GETWORDBREAKPROC	Retrieves the edit-control wordwrap function

EM_LIMITTEXT	Limits amount of text in an edit control

EM_LINEFROMCHAR	Retrieves a line number from a character index

EM_LINEINDEX	Retrieves the character index of an MLE line

EM_LINELENGTH	Retrieves the length of a line in an MLE

EM_LINESCROLL	Scrolls text in an MLE

EM_REPLACESEL	Replaces current selection in an edit control

EM_SCROLL	Vertically scrolls an MLE

EM_SCROLLCARET	Scrolls the caret into view

EM_SETHANDLE	Sets the memory handle for an MLE

EM_SETMODIFY	Sets or clears edit-control modification flag

EM_SETPASSWORDCHAR	Sets or removes edit-control password character

EM_SETREADONLY	Sets the read-only style of an edit control

EM_SETRECT	Sets the formatting rectangle of an MLE

EM_SETRECTNP	Sets the formatting rectangle of an MLE

EM_SETSEL	Selects text within an edit control

EM_SETTABSTOPS	Sets the tab stops in an MLE

EM_SETWORDBREAK	Obsolete

EM_SETWORDBREAKPROC	Provides custom word breaks in an edit control

EM_UNDO	Undoes the last operation in an edit control

EN_CHANGE	Indicates the display is updated after text changes

EN_ERRSPACE	Indicates the edit control is out of memory

EN_HSCROLL	Indicates the user clicked the scroll bar

EN_KILLFOCUS	Indicates the edit control is losing the input focus

EN_MAXTEXT	Indicates the insertion is truncated

EN_SETFOCUS	Indicates the edit-control is receiving the input focus

EN_UPDATE	Indicates edit-control is about to display altered text

EN_VSCROLL	Indicates the user clicked the vertical scroll bar

FM_GETDRIVEINFO	Retrieves drive data from active window

FM_GETFILESEL	Retrieves data about a selected file

FM_GETFILESELLFN	Retrieves data about a selected file

FM_GETFOCUS	Retrieves the type of the File Manager focus window

FM_GETSELCOUNT	Retrieves the count of selected files

FM_GETSELCOUNTLFN	Retrieves the count of selected files

FM_REFRESH_WINDOWS	Repaints File Manager's windows

FM_RELOAD_EXTENSIONS	Reloads File Manager extension DLLs

FMEVENT_HELPMENUITEM	Indicates File Manager wants WinHelp called for command item

FMEVENT_HELPSTRING	Indicates File Manager wants help string for command item

FMEVENT_INITMENU	Initializes File Manager menu extension

FMEVENT_LOAD	Indicates File Manager is loading extension

FMEVENT_SELCHANGE	Indicates user selected a filename

FMEVENT_TOOLBARLOAD	Indicates File Manager is loading its toolbar

FMEVENT_UNLOAD	Indicates an extension DLL is being unloaded

FMEVENT_USER_REFRESH	Indicates user invoked Refresh command

LB_ADDFILE	Adds a file to a directory listing in a list box

LB_ADDSTRING	Adds a string to a list box

LB_DELETESTRING	Deletes a string in a list box

LB_DIR	Adds file names to a list box

LB_FINDSTRING	Finds a string in a list box

LB_FINDSTRINGEXACT	Finds prefix string in a list box

LB_GETANCHORINDEX	Gets the list box anchor item

LB_GETCARETINDEX	Gets index of list-box item with focus rectangle

LB_GETCOUNT	Gets the number of items in a list box

LB_GETCURSEL	Gets index of selected item in a list box

LB_GETHORIZONTALEXTENT	Gets the horizontal extent of a list box

LB_GETITEMDATA	Retrieves value associated with a list-box item

LB_GETITEMHEIGHT	Retrieves the height of items in a list box

LB_GETITEMRECT	Retrieves the bounding rectangle for an item

LB_GETLOCALE	Get current list box locale

LB_GETSEL	Retrieves the selection state of an item

LB_GETSELCOUNT	Retrieves a count of selected list-box items

LB_GETSELITEMS	Lists item numbers of selected list-box items

LB_GETTEXT	Retrieves a string from a list box

LB_GETTEXTLEN	Gets the length of a string in a list box

LB_GETTOPINDEX	Retrieves index of first visible list-box item

LB_INSERTSTRING	Inserts a string into a list box

LB_RESETCONTENT	Removes all items from a list box

LB_SELECTSTRING	Selects a string in a list box

LB_SELITEMRANGE	Selects consecutive items in a list box

LB_SELITEMRANGEEX	Selects consecutive items in a list box

LB_SETANCHORINDEX	Sets anchor item in a list-box

LB_SETCARETINDEX	Sets the focus rectangle in a list box

LB_SETCOLUMNWIDTH	Sets the width of columns in a list box

LB_SETCOUNT	Sets the count of items in a no-data list box

LB_SETCURSEL	Selects a string in a list box

LB_SETHORIZONTALEXTENT	Sets the horizontal extent of a list box

LB_SETITEMDATA	Associates a value with a list-box item

LB_SETITEMHEIGHT	Sets the height of items in a list box

LB_SETLOCALE	Set current list box locale

LB_SETSEL	Selects a string in a multi-selection list box

LB_SETTABSTOPS	Sets tab stops in a list box

LB_SETTOPINDEX	Ensures that a list-box item is visible

LBN_DBLCLK	Indicates that the user double-clicked a string

LBN_ERRSPACE	Indicates the list box is out of memory

LBN_KILLFOCUS	Indicates the list box is losing the input focus

LBN_SELCANCEL	Indicates the selection is cancelled

LBN_SELCHANGE	Indicates the selection is about to change

LBN_SETFOCUS	Indicates the list box is receiving the input focus

MCI_BREAK	Set MCI break key

MCI_CLOSE	Release device or device element access

MCI_COPY	Copy data to the clipboard

MCI_CUE	Cue a device for playback or record

MCI_CUT	Remove element data and copy to the clipboard

MCI_DELETE	Remove element data

MCI_FREEZE	Freeze motion on display

MCI_GETDEVCAPS	Obtain static device information

MCI_INFO	Obtain string information from device

MCI_LOAD	Load a file

MCI_OPEN	Initialize device or device element

MCI_PASTE	Paste clipboard data into device element

MCI_PAUSE	Pause current action

MCI_PLAY	Start transmitting output data

MCI_PUT	Set source, destination and frame rectangles

MCI_RECORD	Start recording

MCI_RESUME	Resume paused device

MCI_SAVE	Save current file

MCI_SEEK	Change current media position

MCI_SET	Set device information

MCI_SOUND	Play system sounds

MCI_STATUS	Obtain device information

MCI_STEP	Step player by frames

MCI_STOP	Stop all play and record sequences

MCI_SYSINFO	Return device information

MCI_UNFREEZE	Restores frozen video buffer

MCI_WHERE	Obtain video clipping rectangle

MCI_WINDOW	Specify graphic window characteristics

MIM_CLOSE	Close input device

MIM_DATA	Input device data callback

MIM_ERROR	Input device error callback

MIM_LONGDATA	Input buffer callback

MIM_LONGERROR	Invalid system-exclusive message callback

MIM_OPEN	Input device open callback

MM_JOY1BUTTONDOWN	Joystick one button pressed

MM_JOY1BUTTONUP	Joystick one button released

MM_JOY1MOVE	Joystick one position change

MM_JOY1ZMOVE	Joystick one z axis position change

MM_JOY2BUTTONDOWN	Joystick two button press

MM_JOY2BUTTONUP	Joystick two button released

MM_JOY2MOVE	Joystick two position change

MM_JOY2ZMOVE	Joystick two z axis position change

MM_MCINOTIFY	Device operation completed

MM_MIM_CLOSE	Input device is closed

MM_MIM_DATA	Input message is received

MM_MIM_ERROR	Invalud message is received

MM_MIM_LONGDATA	System-exclusive data input buffer is ready

MM_MIM_LONGERROR	Invalid MIDI system-exclusive message received

MM_MIM_OPEN	Input device is open

MM_MOM_CLOSE	Input device is closed

MM_MOM_DONE	System exclusive buffer has been played

MM_MOM_OPEN	Output device is open

MM_WIM_CLOSE	Waveform input device is closed

MM_WIM_DATA	Waveform input data is ready

MM_WIM_OPEN	Waveform input device is open

MM_WOM_CLOSE	Waveform output device is closed

MM_WOM_DONE	Waveform output buffer is reset or played

MM_WOM_OPEN	Waveform output device is open

MMIOM_CLOSE	Close file request

MMIOM_OPEN	Open or delete file request

MMIOM_READ	Read file request

MMIOM_SEEK	Move file position request

MMIOM_WRITE	Write file request

MMIOM_WRITEFLUSH	Write file data and flush buffers to disk

MOM_CLOSE	MIDI output device is closed

MOM_DONE	MIDI buffer has been played

MOM_OPEN	MIDI output device is open

SBM_ENABLE_ARROWS	Enables or disables scroll-bar arrows

SBM_GETPOS	Retrieves the position of a scroll box

SBM_GETRANGE	Retrieves scroll range of scroll bar control

SBM_SETPOS	Sets the position of a scroll box

SBM_SETRANGE	Sets the scroll range of a scroll bar control

SBM_SETRANGEREDRAW	Sets scroll range and redraws scroll bar control

STM_GETICON	Gets icon handle associated with an icon control

STM_SETICON	Associates an icon handle with an icon control

WIM_CLOSE	Waveform input device is closed

WIM_DATA	Waveform inout data is ready

WIM_OPEN	Waveform input device is open

WM_ACTIVATE	Indicates a change in activation state

WM_ACTIVATEAPP	Notifies applications when a new task activates

WM_ASKCBFORMATNAME	Retrieves the name of the clipboard format

WM_CANCELJOURNAL	User has cancelled journalling mode

WM_CANCELMODE	Notifies a window to cancel internal modes

WM_CHANGECBCHAIN	Notifies clipboard viewer of removal from chain

WM_CHAR	Indicates the user pressed a character key

WM_CHARTOITEM	Provides list-box keystrokes to owner window

WM_CHILDACTIVATE	Notifies a child window of activation

WM_CHOOSEFONT_GETLOGFONT	Retrieves LOGFONT structure for Font dialog box

WM_CLEAR	Clears an edit control

WM_CLOSE	System Close menu command was chosen

WM_COMMAND	Specifies a command message

WM_COMPACTING	Indicates a low memory condition

WM_COMPAREITEM	Determines position of combo- or list-box item

WM_COPY	Copies a selection to the Clipboard

WM_COPYDATA	Passes data to another application

WM_CPL_LAUNCH	Starts a Control Panel application

WM_CPL_LAUNCHED	Indicates a Control Panel application has ended

WM_CREATE	Indicates a window is being created

WM_CTLCOLORBTN	Button is about to be drawn

WM_CTLCOLORDLG	Dialog box is about to be drawn

WM_CTLCOLOREDIT	Control is about to be drawn

WM_CTLCOLORLISTBOX	List box is about to be drawn

WM_CTLCOLORMSGBOX	Message box is about to be drawn

WM_CTLCOLORSCROLLBAR	Indicates scroll bar is about to be drawn

WM_CTLCOLORSTATIC	Control is about to be drawn

WM_CUT	Deletes a selection and copies it to the Clipboard

WM_DDE_ACK	Acknowledges a DDE message

WM_DDE_ADVISE	Requests a DDE data-change update

WM_DDE_DATA	Sends data to a DDE client

WM_DDE_EXECUTE	Sends a string to a DDE server

WM_DDE_INITIATE	Initiates a DDE conversation

WM_DDE_POKE	Send unsolicited data to a server

WM_DDE_REQUEST	Requests data from a DDE server

WM_DDE_TERMINATE	Ends a DDE conversation

WM_DDE_UNADVISE	Stops a DDE link

WM_DEADCHAR	Indicates the user pressed a dead key

WM_DELETEITEM	Indicates owner-draw item or control was altered

WM_DESTROY	Indicates window is about to be destroyed

WM_DESTROYCLIPBOARD	Notifies owner that the clipboard was emptied

WM_DEVMODECHANGE	Indicates the device-mode settings have changed

WM_DRAWCLIPBOARD	Indicates the clipboard's contents have changed

WM_DRAWITEM	Indicates owner-draw control/menu needs redrawing

WM_DROPFILES	Indicates that a file has been dropped

WM_ENABLE	Indicates a window's enable state is changing

WM_ENDSESSION	Indicates whether the Windows session is ending

WM_ENTERIDLE	Indicates a modal dialog box or menu is idle

WM_ENTERMENULOOP	A menu modal loop has been entered

WM_EXITMENULOOP	A menu modal loop has been exited

WM_ERASEBKGND	Indicates a window's background needs erasing

WM_FONTCHANGE	Indicates a change in the font-resource pool

WM_GETDLGCODE	Allows dialog procedure to process control input

WM_GETFONT	Retrieves the font that a control is using

WM_GETHOTKEY	Gets the virtual-key code of a window's hot key

WM_GETMINMAXINFO	Gets minimum and maximum sizing information

WM_GETTEXT	Gets the text that corresponds to a window

WM_GETTEXTLENGTH	Gets length of text associated with a window

WM_HOTKEY	Hot key has been detected

WM_HSCROLL	Indicates a click in a horizontal scroll bar

WM_HSCROLLCLIPBOARD	Prompts owner to scroll clipboard contents

WM_ICONERASEBKGND	Notifies minimized window to fill icon background

WM_INITDIALOG	Initializes a dialog box

WM_INITMENU	Indicates a menu is about to become active

WM_INITMENUPOPUP	Indicates a pop-up menu is being created

WM_KEYDOWN	Indicates a nonsystem key was pressed

WM_KEYUP	Indicates a nonsystem key was released

WM_KILLFOCUS	Indicates the window is losing keyboard focus

WM_LBUTTONDBLCLK	Indicates double-click of left button

WM_LBUTTONDOWN	Indicates when left mouse button is pressed

WM_LBUTTONUP	Indicates when left mouse button is released

WM_MBUTTONDBLCLK	Indicates double-click of middle mouse button

WM_MBUTTONDOWN	Indicates when middle mouse button is pressed

WM_MBUTTONUP	Indicates when middle mouse button is released

WM_MDIACTIVATE	Activates an MDI child window

WM_MDICASCADE	Arranges MDI child windows in cascade format

WM_MDICREATE	Prompts MDI client to create a child window

WM_MDIDESTROY	Closes an MDI child window

WM_MDIGETACTIVE	Retrieves data about the active MDI child window

WM_MDIICONARRANGE	Arranges minimized MDI child windows

WM_MDIMAXIMIZE	Maximizes an MDI child window

WM_MDINEXT	Activates the next MDI child window

WM_MDIREFRESHMENU	Refreshes an MDI frame window's menu

WM_MDIRESTORE	Prompts MDI client to restore a child window

WM_MDISETMENU	Replaces an MDI frame window's menu

WM_MDITILE	Arranges MDI child windows in tiled format

WM_MEASUREITEM	Requests dimensions of owner-draw control or item

WM_MENUCHAR	Indicates an unknown menu mnemonic was pressed

WM_MENUSELECT	Indicates that the user selected a menu item

WM_MOUSEACTIVATE	Indicates a mouse click in an inactive window

WM_MOUSEMOVE	Indicates mouse-cursor movement

WM_MOVE	Indicates a window's position has changed

WM_NCACTIVATE	Changes the active state of nonclient area

WM_NCCALCSIZE	Calculates the size of a window's client area

WM_NCCREATE	Indicates a window's nonclient area being created

WM_NCDESTROY	Indicates window's nonclient area being destroyed

WM_NCHITTEST	Indicates mouse-cursor movement

WM_NCLBUTTONDBLCLK	Indicates nonclient left button double-click

WM_NCLBUTTONDOWN	Indicates left button pressed in nonclient area

WM_NCLBUTTONUP	Indicates left button released in nonclient area

WM_NCMBUTTONDBLCLK	Indicates nonclient middle button double-click

WM_NCMBUTTONDOWN	Indicates middle button pressed in nonclient area

WM_NCMBUTTONUP	Indicates middle button released in nonclient area

WM_NCMOUSEMOVE	Indicates mouse-cursor movement in nonclient area

WM_NCPAINT	Indicates a window's frame needs painting

WM_NCRBUTTONDBLCLK	Indicates nonclient right button double-click

WM_NCRBUTTONDOWN	Indicates right button pressed in nonclient area

WM_NCRBUTTONUP	Indicates right button released in nonclient area

WM_NEXTDLGCTL	Sets focus to different dialog box control

WM_PAINT	Indicates a window's client area need painting

WM_PAINTCLIPBOARD	Prompts owner to display clipboard contents

WM_PAINTICON	Icon is about to be painted

WM_PALETTECHANGED	Indicates the focus-window realized its palette

WM_PALETTEISCHANGING	Informs windows that palette is changing

WM_PARENTNOTIFY	Notifies parent of child-window activity

WM_PASTE	Inserts Clipboard data into an edit control

WM_POWER	Indicates the system is entering suspended mode

WM_QUERYDRAGICON	Requests a cursor handle for a minimized window

WM_QUERYENDSESSION	Requests that the Windows session be ended

WM_QUERYNEWPALETTE	Allows a window to realize its logical palette

WM_QUERYOPEN	Requests that a minimized window be restored

WM_QUEUESYNC	Delimits CBT messages

WM_QUIT	Requests that an application be terminated

WM_RBUTTONDBLCLK	Indicates double-click of right mouse button

WM_RBUTTONDOWN	Indicates when right mouse button is pressed

WM_RBUTTONUP	Indicates when right mouse button is released

WM_RENDERALLFORMATS	Notifies owner to render all clipboard formats

WM_RENDERFORMAT	Notifies owner to render clipboard data

WM_SETCURSOR	Prompts a window to set the cursor shape

WM_SETFOCUS	Indicates the window gained the keyboard focus

WM_SETFONT	Sets the font for a control

WM_SETHOTKEY	Associates a hot key with a window

WM_SETREDRAW	Allows or prevents redrawing in a window

WM_SETTEXT	Sets the text of a window

WM_SHOWWINDOW	Indicates a window is about to be hidden or shown

WM_SIZE	Indicates a change in a window's size

WM_SIZECLIPBOARD	Indicates a change in the chipboard's size

WM_SPOOLERSTATUS	Indicates a print job was added or removed

WM_SYSCHAR	Indicates a System-menu key was pressed

WM_SYSCOLORCHANGE	Indicates a system color value was changed

WM_SYSCOMMAND	Indicates a system command was requested

WM_SYSDEADCHAR	Indicates a system dead key was pressed

WM_SYSKEYDOWN	Indicates that ALT plus another key was pressed

WM_SYSKEYUP	Indicates that ALT plus another key was released

WM_TIMECHANGE	Indicates the system time has been set

WM_TIMER	Indicates timeout interval for a timer has elapsed

WM_UNDO	Undoes the last operation in an edit control

WM_USER	Indicates a range of message values

WM_VKEYTOITEM	Provides list-box keystrokes to owner window

WM_VSCROLL	Indicates a click in a vertical scroll bar

WM_VSCROLLCLIPBOARD	Prompts owner to scroll clipboard contents

WM_WINDOWPOSCHANGED	Notifies window of size or position change

WM_WINDOWPOSCHANGING	Notifies window of new size or position

WM_WININICHANGE	Notifies applications that WIN.INI has changed

WOM_CLOSE	Waveform output device is closed

WOM_DONE	Waveform output buffer has been played or reset

WOM_OPEN	Waveform output device is open


NDdeGetErrorString function
NDdeGetErrorString (Win32)

UINT NDdeGetErrorString (uErrorCode, lpszErrorString, cBufSize)

UINT uErrorCode;	/* Error code to get string for	*/
LPTSTR lpszErrorString;	/* buffer to hold error string	*/
DWORD cBufSize;	/* sizeof buffer	*/

The NDdeGetErrorString function is called to convert an error code returned by the NetDDE DSDM interface API into an error string explaining the reason for the returned error.

Parameter	Description

uErrorCode	Error code to be converted.

lpszErrorString	Address of a buffer to accept the tranlated error string. Must not be NULL. If the buffer is not large enough to store the complete error string, the string will be truncated.

cBufSize	Defines the size of the buffer allocated to receive the error string.

Returns

If the function succeeds, it returns the value 0.

If the function fails, it returns a non-zero error code. If the lpszErrorString buffer is not large enought to accept the complete error string, and the string is truncated, the function returns the value NDDE_BUF_TOO_SMALL.


NDdeGetShareSecurity function
NDdeGetShareSecurity (Win32)

UINT NDdeGetShareSecurity(lpszServer, lpszShareName, si, pSD, cbSD, lpcbsdRequired)

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

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

Parameter	Description

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 retrieved from the DSDM. This parameter should 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 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 descritptor. 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. Must not be NULL.

Returns

If the function succeeds, it returns NDDE_NO_ERROR. Otherwise, it returns 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.


NDdeGetTrustedShare function
NDdeGetTrustedShare (Win32)

UINT NDdeGetTrustedShare (lpszServer, lpszShareName, lpdwTrustOptions, lpdwShareModId0, lpdwShareModId1)

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 mod id	*/
LPDWORD lpdwShareModId1;	/* second word of share mod id	*/

The NDdeGetTrustedShare function is called to retrieve the options associated with a currently 'trusted' DDE share.

Parameter	Description

lpszServer	Address of the server name on which the DSDM will be modified.

lpszShareName	Address of the share name whose trusted status is being queried. This parameter should not be NULL.

lpdwTrustOptions	Address of a variable into which the TRUST_SHARE_OPTIONS will be stored. Must not be NULL.

lpdwShareModId0	Address of a variable into which the first word of the trusted share modify id will be stored. Must not be NULL.

lpdwShareModId1	Address of a variable into which the second word of the trusted share modify id will be stored. Must not be NULL.

Returns

If the function succeeds, it returns NDDE_NO_ERROR. Otherwise, it returns an error code which can be translated into a text error message by calling NDdeGetErrorString.

Comments

The trusted share modify id reflects the version of the DDE share in the NetDDE DSDM at the time the DDE share was initially promoted to trust status. The trusted share modify id is primarily used to purge obsolete trusted shares. However, the user does not need to purge obsolete trusted shares proactively. The NetDDE Agent purges obsolete shares on the user's behalf.


NDdeIsValidAppTopicList function
NDdeIsValidAppTopicList (Win32)

BOOL NDdeIsValidAppTopicList (lpszTopic)

LPTSTR lpszTopic ;	/* points to app and topic string	*/

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

Parameter	Description

lpszTopic	Address of the application and topic string  to validate. Must not be NULL.

Returns

If lpszTopic has valid syntax the function returns TRUE; otherwise, FALSE.


NDdeIsValidShareName function
NDdeIsValidShareName (Win32)

BOOL NDdeIsValidShareName (lpszShare)

LPTSTR lpszShare;	/* points to share name to validate	*/

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

Parameter	Description

lpszShare	Address of a share name to validate. Must not be NULL.

Returns

If the share name has valid syntax, the function returns TRUE; otherwise, FALSE.


NDdeSetShareSecurity function
NDdeSetShareSecurity (Win32)

UINT NDdeSetShareSecurity(lpszServer, lpszShareName, si, pSD)

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

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.

Parameter	Description

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

Returns

If the function succeeds, it returns NDDE_NO_ERROR. Otherwise, it returns an error code which can be translated into a text error message by calling NDdeGetErrorString.

Comments

To modify the SECURITY_DESCRIPTOR associated with  a DDE share in the DSDM, the user must have appropriate priviledges, e.g., the share creator has such rights.


NDdeSetTrustedShare function
NDdeSetTrustedShare (Win32)

UINT NDdeSetTrustedShare (lpszServer, lpszShareName, dwTrustOptions)

LPTSTR lpszServer;	/* server to execute on	*/
LPTSTR lpszShareName;	/* name of share to delete	*/
DWORD dwTrustOptions;	/* trust options to apply	*/

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

Parameter	Description

lpszServer	Address of the server name on which the DSDM will be modified.

lpszShareName	Address of the share name being promoted to trusted status. This parameter should 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.

Returns

If the function succeeds, it returns NDDE_NO_ERROR. Otherwise, it returns an error code which can be translated into a text error message by calling NDdeGetErrorString.

Comments

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


NDdeShareAdd function
NDdeShareAdd (Win32)

UINT NDdeShareAdd (lpszServer, nLevel, pSD, lpBuffer, cBufSize)

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;	/* sizeof supplied buffer	*/

The NDdeShareAdd function is called to create and add a new DDE share to the NetDDE DSDM.

Parameter	Description

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. It must not be 0.

Returns

If the function succeeds, it returns NDDE_NO_ERROR. Otherwise, it returns an error code which can be translated into a text error message by calling NDdeGetErrorString.


NDdeShareDel function
NDdeShareDel (Win32)

UINT NDdeShareDel (lpszServer, lpszShareName, wReserved)

LPTSTR lpszServer;	/* server to execute on	*/
LPTSTR lpszShareName;	/* name of share to delete	*/
UINT wReserved;	/* must be 0	*/

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

Parameter	Description

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 should not be NULL.

wReserved	Must be 0.

Returns

If the function succeeds, it returns NDDE_NO_ERROR. Otherwise, it returns an error code which can be translated into a text error message by calling NDdeGetErrorString.

Comments

To delete a DDE share from the DSDM the user must have appropriate privileges. The share creator has delete rights.


NDdeShareEnum function
NDdeShareEnum (Win32)

UINT NDdeShareEnum (lpszServer, nLevel, lpBuffer, cBufSize, lpnEntriesRead, lpcbTotalAvailable)

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

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

Parameter	Description

lpszServer	Address of the server name on which the DSDM will be modified.

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.

Returns

If the function succeeds, it returns NDDE_NO_ERROR. Otherwise, it returns 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 function
NDdeShareGetInfo (Win32)

UINT NDdeShareGetInfo ( lpszServer, lpszShareName, nLevel, lpBuffer, cBufSize, lpnTotalAvailable, lpnItems)

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;	/* sizeof buffer	*/
LPDWORD lpnTotalAvailable;	/* number of bytes available	*/
LPWORD lpnItems;	/* item mask for partial getinfo	*/

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

Parameter	Description

lpszServer	Address of the server name on which the DSDM will be modified.

lpszShareName	Address of the share name whose information is to be retrieved from the DSDM. This parameter should 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. 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.

Returns

If the function succeeds, it returns NDDE_NO_ERROR. Otherwise, it returns 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.


NDdeShareSetInfo function
NDdeShareSetInfo (Win32)

UINT NDdeShareSetInfo (lpszServer, lpszShareName, nLevel, lpBuffer, cBufSize, sParmNum)

LPTSTR lpszServer;	/* server to execute on	*/
LPTSTR lpszShareName;	/* name of share	*/
UINT nLevel;	/* info level must be 2	*/
LPBYTE lpBuffer;	/* address of NDDESHAREINFO	*/
DWORD cBufSize;	/* sizeof buffer	*/
WORD sParmNum;	/* Parameter index	*/

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

Parameter	Description

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 should 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, i.e., no partial edits. Must not be NULL.

cBufSize	Size of the DDE share information addressed by lpBuffer.

sParmNum	Parameter index being modified. Current implementation does not support partial modification and, hence, it must be 0.

Returns

If the function succeeds, it returns NDDE_NO_ERROR. Otherwise, it returns an error code which can be translated into a text error message by calling NDdeGetErrorString.


NDdeTrustedShareEnum function
NDdeTrustedShareEnum (Win32)

UINT NDdeTrustedShareEnum (lpszServer, nLevel, lpBuffer, cBufSize, lpnEntriesRead, lpcbTotalAvailable)

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

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

Parameter	Description

lpszServer	Address of the server name on which the DSDM will be modified.

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 stored 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. Must be 0 if lpBuffer is NULL.

lpnEntriesRead	Address of a variable to receive the total number of trusted 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 trusted DDE shares. Must not be NULL.

Returns

If the function succeeds, it returns NDDE_NO_ERROR. Otherwise, it returns 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.


Network DDE

NDdeGetErrorString	Converts net DDE error code to error string

NDdeGetShareSecurity	Obtain net DDE share's security descriptor

NDdeGetTrustedShare	Retrieve net DDE trusted share options

NDdeIsValidAppTopicList	Validates net DDE app and topic string syntax

NDdeIsValidShareName	Validates net DDE share name syntax

NDdeSetShareSecurity	Set a net DDE share's security information

NDdeSetTrustedShare	Applies trust options to a net DDE share

NDdeShareAdd	Adds a net DDE share

NDdeShareDel	Deletes a net DDE share

NDdeShareEnum	Lists net DDE shares

NDdeShareGetInfo	Obtains information about a net DDE sharer

NDdeShareSetInfo	Modifies an existing net DDE share's info

NDdeTrustedShareEnum	Lists trusted shares in calling process' context


CompareStringW function
CompareStringW (Win32)

int CompareStringW(lcid, fdwStyle, lpString1, cch1, lpString2, cch2)

LCID lcid;	/* locale identifier	*/
DWORD fdwStyle;	/* comparison-style options	*/
LPCWSTR lpString1;	/* address of first string	*/
int cch1;	/* number of characters in first string	*/
LPCWSTR lpString2;	/* address of second string	*/
int cch2;	/* number of characters in second string	*/

The CompareStringW function compares two wide-character strings of the same locale (according to the supplied locale identifier).

Parameter	Description

lcid	Specifies the locale used for the comparison. An application can use the MAKELCID macro to create a locale identifier.

fdwStyle	Specifies flags indicating the character properties to use when comparing the two strings. These flags are not set by defaults. This parameter can be any combination of the following values:

Value	Meaning

NORM_IGNORECASE	Ignore case.

NORM_IGNORENONSPACE	Ignore nonspacing characters.

NORM_IGNORESYMBOLS	Ignore symbols.

SORT_STRINGSORT	Treat punctuation the same as symbols.

lpString1	Points to the first string to be compared.

cch1	Specifies the number of characters in the string pointed to by the lpString1 parameter. This count does not include the null-terminating character, if any. If this value 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.

cch2	Specifies the number of characters in the string pointed to by the lpString2 parameter. This count does not include the null-terminating character, if any. If this value is -1, the string is assumed to be null terminated and the length is calculated automatically.

Returns

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, use the GetLastError function.

Comments

Note that if the return value is 2, the two strings are "equal" in the collation sense, though not necessarily identical.

To maintain the C runtime convention of comparing strings, the value 2 can be subtracted from a non-zero return value. The meaning of 0, ==0 and 0 is then consistent with the C runtimes.

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

Normally, strings are compared using what is called a "word sort" technique. In a word sort, all punctuation marks and other non-alphanumeric characters, except for the hyphen and the apostrophe, come before any alphanumeric character. The hyphen and the apostrophe are treated differently than the other non-alphanumeric 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 non-alphanumeric 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	can't	 	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 CompareStringW and LCMapStringW functions default to using a word sort, but use a string sort if their caller sets the SORT_STRINGSORT flag.

See Also

FoldStringW, GetSystemDefaultLCID, GetUserDefaultLCID, LCMapStringW, lstrcmp, lstrcmpi, MAKELCID


FoldStringW function
FoldStringW (Win32)

int FoldStringW(fdwMap, lpSrcStr, cchSrc, lpDestStr, cchDest)

DWORD fdwMap;	/* mapping-type options	*/
LPCWSTR lpSrcStr;	/* address of source string	*/
int cchSrc;	/* number of characters in source string	*/
LPWSTR lpDestStr;	/* address of destination buffer	*/
int cchDest;	/* size of destination buffer	*/

The FoldStringW function maps one wide-character string to another, performing the specified translation.

Parameter	Description

fdwMap	Specifies flags indicating the type of transformation to be used during mapping. This value can be a combination of the following values:

Option	Meaning

MAP_FOLDCZONE	Fold compatibility zone characters into standard Unicode™ equivalents. For information about compatibility zone characters, see the following Comments section.

MAP_FOLDDIGITS	Map all digits to Unicode ASCII 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 number of characters in the string pointed to by the lpSrcStr parameter. If this value 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 number of characters that can be contained by the buffer pointed to by the lpDestStr parameter. If this value is zero, the function returns the number of characters required to hold the mapped string. (The buffer pointed to by the lpDestStr parameter is not used in this case.)

Returns

If the function succeeds, the return value is the number of characters written to the destination buffer; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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

LCMapStringW, CompareStringW


GetACP function
GetACP (Win32)

UINT GetACP(VOID)

The GetACP function retrieves the identifier of the ANSI system code page.

Returns

If the function succeeds, the return value is the ANSI code-page identifier, or it is the default identifier if no identifier is found in the registry.

Comments

Following are the ANSI code-page identifiers:

Identifier	Meaning

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

See Also

GetCPInfo, GetOEMCP


GetCPInfo function
GetCPInfo (Win32)

BOOL GetCPInfo(uCodePage, lpCPInfo)

UINT uCodePage;	/* code page	*/
LPCPINFO lpCPInfo;	/* address of structure for information	*/

The GetCPInfo function retrieves information about any valid installed or available code page.

Parameter	Description

uCodePage	Specifies the code page about which information is to be retrieved. You can use any valid installed or available code page value. The following predefined values are among those that may be used:

Value	Meaning

CP_ACP	ANSI code page

CP_OEMCP	OEM code page

lpCPInfo	Points to a CPINFO structure that receives information about the code page.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetACP, GetOEMCP, CPINFO


GetDateFormatW function
GetDateFormatW (Win32)

int GetDateFormatW(Locale, dwFlags, lpDate, lpFormat, lpDateStr, cchDate)

LCID Locale;	/* locale of interest	*/
DWORD dwFlags;	/* flags specifying function options	*/
CONST SYSTEMTIME * lpDate;	/* date to be formatted	*/
LPCWSTR lpFormat;	/* format string	*/
LPWSTR lpDateStr;	/* buffer for storing formatted string	*/
int cchDate;	/* size of buffer	*/

The GetDateFormatW function obtains a date string that is formatted properly for a given locale. The function uses a specified date or the local system date.

Parameter	Description

Locale	A locale identifier that specifies the locale the date string will be formatted for.

dwFlags	A set of bit flags that specify various function options. The following flag constants are defined:

Flag	Meaning

LOCALE_NOUSEROVERRIDE	If set, do not use user overrides.

DATE_SHORTDATE	If set, use the short date format. This is the default.

DATE_LONGDATE	If set, use the long date format

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 to use to form the date string. If this pointer is NULL, then the format picture for the given locale will be used. Note that the format picture string is a Unicode (wide character) string.

lpDateStr	Pointer to a memory buffer that receives the formatted date string. Note that this will be a Unicode (wide character) string.

cchDate	Specifies the wide character count of the memory buffer pointed to by lpDateStr. If cchDate is 0, the function returns the number of wide characters required to hold the formatted date string. lpDateStr is not referenced in this case.

Returns

If the function succeeds, the return value is the number of wide characters written to the buffer pointed to by lpDateStr.

If the function fails, the return value is 0. Call GetLastError for further information. The function sets the following last-error values:

ERROR_INVALID_PARAMETER

ERROR_INSUFFICIENT_BUFFER

Comments

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.

If the lpFormat parameter is not NULL, the dwFlags parameter must be zero. None of the flags make sense when the format string is specified.

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 quotes in the date format picture.

See Also

GetTimeFormatW, SYSTEMTIME


GetLocaleInfoW function
GetLocaleInfoW (Win32)

int GetLocaleInfoW(lcid, LCType, lpLCData, cchData)

LCID lcid;	/* locale identifier	*/
LCTYPE LCType;	/* type of information	*/
LPWSTR lpLCData;	/* address of buffer for information	*/
int cchData;	/* size of buffer	*/

The GetLocaleInfoW function retrieves information about a locale by querying the registry. The function also indicates how much memory is necessary to contain the requested information.

Parameter	Description

lcid	Specifies the identifier for a locale. An application can use the MAKELCID macro to create this identifier.

LCType	Specifies 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.

For a list of LCTYPE constants, see Locale Identifiers

lpLCData	Points to a buffer to receive the requested data.

cchData	Specifies the number of characters that can be contained in the buffer pointed to by the lpLCData parameter. If this value is zero, the return value is the number of characters required to hold the information. (In this case, the buffer pointed to by lpLCData is not used.)

Returns

If the function succeeds, the return value is the number of characters written to the buffer or, if the cchData parameter is zero, the number of characters required to hold the locale information. Otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

The information retrieved is always a null-terminated Unicode™ string. No integers are retrieved by this function, and any numeric values are retrieved as Unicode text.

See Also

GetStringTypeW, GetSystemDefaultLCID, GetUserDefaultLCID, MAKELCID


GetOEMCP function
GetOEMCP (Win32)

UINT GetOEMCP(VOID)

The GetOEMCP function retrieves the OEM code-page identifier for the system. (OEM stands for original equipment manufacturer.)

Returns

If the function succeeds, the return value is the OEM code-page identifier, or it is the default identifier if the registry value is not readable.

Comments

Following are the OEM code-page identifiers:

Identifier	Meaning

437	MS-DOS United States

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

863	MS-DOS Canadian-French

865	MS-DOS Nordic

866	MS-DOS Russian (former USSR)

869	IBM Modern Greek

See Also

GetACP


GetStringTypeW function
GetStringTypeW (Win32)

BOOL GetStringTypeW(fdwInfoType, lpSrcStr, cchSrc, lpCharType)

DWORD fdwInfoType;	/* information-type options	*/
LPCWSTR lpSrcStr;	/* address of string	*/
int cchSrc;	/* number of characters in string	*/
LPWORD lpCharType;	/* address of buffer for output	*/

The GetStringTypeW function returns character-type information about a Unicode string.

Parameter	Description

fdwInfoType	Specifies the type of character information the user wants to retrieve. The various types are divided into different levels (see the Comments section for a list of the information included in each type). This parameter can be one of the following values:

CT_CTYPE1

CT_CTYPE2

CT_CTYPE3

lpSrcStr	Points to the string for which character types are requested.

cchSrc	Specifies the number of characters in the string pointed to by the lpSrcStr parameter and in the buffer specified by lpCharType. If this value is -1, the string is assumed to be null terminated and the length is calculated automatically.

lpCharType	Points to an array whose length is specified in the cchSrc parameter. When the function returns, this array contains one word corresponding to each Unicode character in the source string.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 limited to 16 bits of representation per character can 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 fdwInfoType 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 letter

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

Printable	Graphic characters and blank

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 Microsoft® Windows NT™. A combination of these values is returned when fdwInfoType 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

Not applicable:

C3_NOTAPPLICABLE	0x0	Not applicable

See Also

GetLocaleInfoW


GetSystemDefaultLangID function
GetSystemDefaultLangID (Win32)

LANGID GetSystemDefaultLangID(void)

The GetSystemDefaultLangID function retrieves the system default language identifier.

Returns

If the function succeeds, the return value is the system default language identifier.

Comments

For more information about language identifiers, see Locale Identifiers

See Also

GetUserDefaultLangID, MAKELANGID


GetSystemDefaultLCID function
GetSystemDefaultLCID (Win32)

LCID GetSystemDefaultLCID(void)

The GetSystemDefaultLCID function retrieves the system default locale identifier.

Returns

If the function succeeds, the return value is the system default locale identifier.

Comments

For more information about locale identifiers, see Locale Identifiers

See Also

GetLocaleInfoW, GetUserDefaultLCID, MAKELCID


GetThreadLocale function
GetThreadLocale (Win32)

LCID GetThreadLocale(VOID)

The GetThreadLocale function returns the calling thread's current locale.

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

Returns

The function returns the calling thread's 32-bit LCID locale identifier.

Comments

For more information about locale identifiers, see Locale Identifiers

See Also

SetThreadLocale, GetSystemDefaultLCID, GetUserDefaultLCID, LCID


GetTimeFormatW function
GetTimeFormatW (Win32)

int GetTimeFormatW(Locale, dwFlags, lpTime, lpTimeStr, cchTime)

LCID Locale;	/* locale of interest	*/
DWORD dwFlags;	/* flags specifying function options	*/
CONST SYSTEMTIME * lpTime;	/* time to be formatted	*/
LPCWSTR lpFormat;	/* format string	*/
LPWSTR lpTimeStr;	/* buffer for storing formatted string	*/
int cchTime;	/* size of buffer	*/

The GetTimeFormatW function obtains a time string that is formatted properly for a given locale. The function uses a specified time or the local system time.

Parameter	Description

Locale	A locale identifier that specifies the locale the time string will be formatted for.

dwFlags	A set of bit flags that specify various function options. The following flag constants are defined:

Flag	Meaning

LOCALE_NOUSEROVERRIDE	If set, do not use user overrides.

TIME_NOMINUTESORSECONDS	If set, do not use minutes or seconds.

TIME_NOSECONDS	If set, do not use seconds.

TIME_NOTIMEMARKER	If set, do not use time marker.

TIME_FORCE24HOURFORMAT	If set, 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 this pointer is NULL, then the format picture for the given locale will be used. Note that the format picture string is a Unicode (wide character) string.

lpTimeStr	Pointer to a memory buffer that receives the formatted time string. Note that this will be a Unicode (wide character) string.

cchTime	Specifies the wide character count of the memory buffer pointed to by lpTimeStr. If cchTime is 0, the function returns the number of wide characters required to hold the formatted time string. lpTimeStr is not referenced in this case.

Returns

If the function succeeds, the return value is the number of wide characters written to the buffer pointed to by lpTimeStr.

If the function fails, the return value is 0. Call GetLastError for further information. The function sets the following last-error values:

ERROR_INVALID_PARAMETER

ERROR_INSUFFICIENT_BUFFER

Comments

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, "de." and "du." for Mexican Spanish.

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

GetDateFormatW, SYSTEMTIME


GetUserDefaultLangID function
GetUserDefaultLangID (Win32)

LANGID GetUserDefaultLangID(void)

The GetUserDefaultLangID function retrieves the user default language identifier.

Returns

If the function succeeds, the return value is the user default language identifier.

Comments

For more information about language identifiers, see Locale Identifiers

See Also

GetSystemDefaultLangID, MAKELANGID


GetUserDefaultLCID function
GetUserDefaultLCID (Win32)

LCID GetUserDefaultLCID(void)

The GetUserDefaultLCID function retrieves the user default locale identifier.

Returns

If the function succeeds, the return value is the user default locale identifier.

Comments

For more information about locale identifiers, see Locale Identifiers

See Also

GetLocaleInfoW, GetSystemDefaultLCID, MAKELCID


IsDBCSLeadByte function
IsDBCSLeadByte (Win32)

BOOL IsDBCSLeadByte(bTestChar)

BYTE bTestChar;	/* character to test	*/

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

Parameter	Description

bTestChar	Specifies the character to be tested.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


IsValidCodePage function
IsValidCodePage (Win32)

BOOL IsValidCodePage(CodePage)

UINT CodePage;	/* specifies code page to check	*/

The IsValidCodePage determines whether a specified code page is valid.

Parameter	Description

CodePage	Specifies the code page to check. Each code page is identified by a unique number.

Returns

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. Call GetLastError for extended error information.

Comments

A code page is considered valid only if it is installed in the system.

See Also

GetACP, GetCPInfo, GetOEMCP


LCMapStringW function
LCMapStringW (Win32)

int LCMapStringW(lcid, fdwMap, lpSrcStr, cchSrc, lpDestStr, cchDest)

LCID lcid;	/* locale identifier	*/
DWORD fdwMap;	/* mapping type	*/
LPCWSTR lpSrcStr;	/* address of source string	*/
int cchSrc;	/* number of characters in source string	*/
LPWSTR lpDestStr;	/* address of destination buffer	*/
int cchDest;	/* size of destination buffer	*/

The LCMapStringW function maps one wide character string to another, performing the specified locale-dependent translation.

Parameter	Description

lcid	Specifies a locale identifier. An application can use the MAKELCID macro to create a locale identifier. For more information about locale identifiers, see Locale Identifiers

fdwMap	Specifies flags indicating the type of transformation to be used during mapping. This parameter can be one or more of the following values:

Option	Meaning

LCMAP_BYTEREV	Use byte reversal.

LCMAP_LOWERCASE	Use lowercase. This option cannot be used with LCMAP_UPPERCASE.

LCMAP_SORTKEY	Use wide-character sort key (normalize).

LCMAP_UPPERCASE	Use uppercase. This option cannot be used with LCMAP_LOWERCASE.

NORM_IGNORECASE	Ignore case. This bit is not set by default. This option can only be used with LCMAP_SORTKEY.

NORM_IGNORENONSPACE	Ignore nonspacing. This bit is not set by default. This option cannot be used with LCMAP_LOWERCASE or LCMAP_UPPERCASE.

NORM_IGNORESYMBOLS	Ignore symbols. This bit is not set by default. This option cannot be used with LCMAP_LOWERCASE or LCMAP_UPPERCASE.

SORT_STRINGSORT	Treat punctuation the same as symbols. This option can only be used with LCMAP_SORTKEY.

lpSrcStr	Points to the string to be mapped.

cchSrc	Specifies the number of characters in the string pointed to by the lpSrcStr parameter. If this value is -1, the string 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 number of characters in the buffer pointed to by the lpDestStr parameter.

However, if LCMAP_SORTKEY is specified in the fdwMap parameter, cchDest specifies the number of bytes in the buffer pointed to by lpDestStr.

If this value 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. In this case, the buffer pointed to by lpDestStr is not used.

Returns

If the function succeeds, and the value of cchDest is non-zero, the return value is the number of characters, or bytes if LCMAP_SORTKEY is specified, written to the buffer.

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.

If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

Comments

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 output string is not strictly in WCHAR format because some of the mapping options, such as LCMAP_SORTKEY, return values instead of wide characters.

See Also

CompareStringW, FoldStringW, MAKELCID


MultiByteToWideChar function
MultiByteToWideChar (Win32)

int MultiByteToWideChar(uCodePage, dwFlags, lpMultiByteStr, cchMultiByte, lpWideCharStr, cchWideChar)

UINT uCodePage;	/* 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	*/

The MultiByteToWideChar function maps a character string to a wide-character string. The character string mapped by this function is not necessarily from a multibyte character set.

Parameter	Description

uCodePage	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 two values have special meanings:

Value	Meaning

CP_ACP	ANSI code page

CP_OEMCP	OEM code page

dwFlags	Specifies flags that indicate whether to translate to precomposed or composite wide characters (if a composite form exists), or to indicate whether to use glyph characters or control codes. The parameter can be one of the following values:

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.

MB_COMPOSITE	Always use composite characters--that is, characters in which a base character and a nonspacing character have different values.

MB_USEGLYPHCHARS	Use glyph characters instead of control characters.

A base character is a character followed by a nonspacing character. For example, in an accented e, the e is the base character and the accent mark is the nonspacing character.

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 number of wide characters required for the buffer, and makes no use of the lpWideCharStr buffer.

Returns

If the function succeeds, and cchWideChar is non-zero, 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 FALSE. Call GetLastError for extended error information.

Comments

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.

See Also

WideCharToMultiByte


SetThreadLocale function
SetThreadLocale (Win32)

BOOL SetThreadLocale (locale)

LCID Locale;	/* locale identifier	*/

The SetThreadLocale function sets the calling thread's current locale.

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

Parameter	Description

Locale	A 32-bit LCID value that will become the new locale for the calling thread.

For more information about locale identifiers, see Locale Identifiers

Returns

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE/NULL. Call GetLastError for extended error information.

See Also

GetThreadLocale, GetSystemDefaultLCID, GetUserDefaultLCID, LCID


WideCharToMultiByte function
WideCharToMultiByte (Win32)

int WideCharToMultiByte(uCodePage, dwFlags, lpWideCharStr, cchWideChar, lpMultiByteStr, cchMultiByte, lpDefaultChar, lpfUsedDefaultChar)

UINT uCodePage;	/* 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 lpfUsedDefaultChar;	/* address of flag set when default char. used	*/

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.

Parameter	Description

uCodePage	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 two values have special meanings:

Value	Meaning

CP_ACP	ANSI code page

CP_OEMCP	OEM code page

dwFlags	Specifies a flag affecting the handling of unmapped characters. The function performs more quickly when this flag is not set.

This parameter can be WC_COMPOSITECHECK. When WC_COMPOSITECHECK is specified, the function converts composite characters to precomposed characters. In composite characters, the base character and the corresponding nonspacing character have different character values. In precomposed characters, the base character and the corresponding nonspacing character have a single character value. (A base character is a character followed by a nonspacing character. For example, in an accented e, the e is the base character and the accent mark is the nonspacing character.)

When an application specifies WC_COMPOSITECHECK, it can use the following flags 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 the wide-character string.

Value	Meaning

WC_DISCARDNS	Discard nonspacing characters.

WC_SEPCHARS	Generate separate characters. This is the default behavior.

WC_DEFAULTCHAR	Replace exceptions with the default character.

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 bytes 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 lpfUsedDefaultChar are NULL.

lpfUsedDefaultChar	Points to a flag that indicates whether a default character was used. This flag is set to TRUE if one or more wide characters in the source string cannot be represented in the specified code page. Otherwise, it is set to FALSE. This parameter may be NULL. The function is faster when both lpDefaultChar and lpfUsedDefaultChar are NULL.

Returns

If the function succeeds, and cchMultiByte is non-zero, 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 FALSE. Call GetLastError for extended error information.

Comments

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.

The function is faster when both lpDefaultChar and lpfUsedDefaultChar are NULL.

See Also

MultiByteToWideChar


National Language Support

CompareStringW	Compare two wide character strings

FoldStringW	Translate one wide character string to another

GetACP	Get ANSI system code page

GetCPInfo	Get code page information

GetDateFormatW	Obtains a locale-formatted date string

GetLocaleInfoW	Get locale information from registry

GetOEMCP	Get OEM system code page

GetStringTypeW	Get Unicode string type

GetSystemDefaultLangID	Get system default language ID

GetSystemDefaultLCID	Get system default locale ID

GetThreadLocale	Get locale information for a thread

GetTimeFormatW	Obtains a locale-formatted time string

GetUserDefaultLangID	Get user default language ID

GetUserDefaultLCID	Get user default locale ID

IsDBCSLeadByte	Is character a DBCS lead byte

IsValidCodePage	Determines code page validity

LCMapStringW	Map character string by locale

MultiByteToWideChar	Map string to wide-character string

SetThreadLocale	Set locale information for a thread

WideCharToMultiByte	Map wide-character string


Object Linking and Embedding
Object Linking and Embedding (OLE)

Introduction to OLE

Considerations for OLE Applications

OLE User Interface

Implementing OLE into Server Applications

Implementing OLE into Client Applications

Implementing Object Handlers

Callback Functions and Data Structures

The OLE Server DLL

The OLE Client DLL

Using the Registry

Testing OLE Applications

Providing User Documentation

Win32 Portability Summary

Error Codes

OLE File Formats

OLE Function Groups

OLE Functions (all)

OLE Structures


OLE Function Groups

Server Functions	Used by the OLE server.

Document Management Functions	Used to obtain information about documents containing OLE objects.

Object Creation and Deletion Functions	Used to add or delete an OLE object from a document.

Object Management Functions	Used to open, close, or draw OLE objects.

Object Information Functions	Used to obtain specific information about the an OLE object.

Object Updating Functions	Used to update and to notify the client application of changes made to an OLE object.

Miscellaneous Functions	Used to perform tasks on OLE objects as the need may arise; for example, locking and unlocking OLE server applications in memory.


OLE functions
OLE functions (all)

OleActivate	Executes an object's verb which could start the object's server application.

OleBlockServer	Causes requests to the server application to be queued until the server calls the OleUnblockServer function.

OleClone	Creates an exact copy of another object.

OleClose	Breaks the connection between an object and a server application.

OleCopyFromLink	Creates an embedded object copy of a linked object.

OleCopyToClipboard	Places a copy of an object on the clipboard.

OleCreate	Creates an embedded object of a specified class.

OleCreateFromClip	Creates an embedded object from data on the clipboard.

OleCreateFromFile	Creates an embedded object using the contents of a file.

OleCreateFromTemplate	Creates an embedded object using a file as a template.

OleCreateInvisible	Creates an embedded object with no data or display.

OleCreateLinkFromClip	Creates a linked object from data on the clipboard.

OleCreateLinkFromFile	Creates a linked object with a link to a specified file.

OleDelete	Permanently deletes an object from a document.

OleDraw	Draws an object onto any device context.

OleEnumFormats	Enumerates available data formats for an object.

OleEnumObjects	Enumerates the objects in a document.

OleEqual	Compares two objects for equality.

OleExecute	Sends DDE Execute messages to an object's server application.

OleGetData	Retrieves an object's data in a specified format.

OleGetLinkUpdateOptions	Determines if a linked object is automatic or manual.

OleIsDcMeta	Identifies a metafile device context.

OleLoadFromStream	Loads an object from a document being loaded.

OleLockServer	Keeps a server in memory for updating multiple objects.

OleObjectConvert	Creates a static object from an existing object.

OleQueryBounds	Retrieves the bounding rectangle for an object.

OleQueryClientVersion	Retrieves the version number of the client DLL.

OleQueryCreateFromClip	Determines if OleCreateFromClip will succeed.

OleQueryLinkFromClip	Determines if OleCreateLinkFromClip will succeed.

OleQueryName	Retrieves the name of an object stored in the client DLL.

OleQueryOpen	Determines if a server is currently editing an object.

OleQueryOutOfDate	Determines whether an object is out-of-date.

OleQueryProtocol	Determines if an object supports a protocol.

OleQueryReleaseError	Determines if an error caused an object's release.

OleQueryReleaseMethod	Determines which operation released an object.

OleQueryReleaseStatus	Determines if an object is released or busy.

OleQueryServerVersion	Retrieves the version number of the server DLL.

OleQuerySize	Retrieves the size of an object in bytes.

OleQueryType	Determines if object is linked, embedded, or static.

OleReconnect	Reconnects a linked object to a server after OleClose.

OleRegisterClientDoc	Registers a client document.

OleRegisterServer	Registers the specified server, class , and instance with the server DLL.

OleRegisterServerDoc	Registers a document with the server DLL.

OleRelease	Frees an object from memory.

OleRename	Informs the client DLL that an object name changed.

OleRenameClientDoc	Informs the client DLL that a registered document was renamed.

OleRenameServerDoc	Informs the server DLL that a document has been renamed.

OleRequestData	Retrieves data from a server in a specified format.

OleRevertClientDoc	This function is provided in the client DLL and header file (OLE.H) for compatibility reasons.

OleRevertServerDoc	This function is provided in the library (OLESVR32.DLL) and header file (OLE.H) for compatibility reasons.

OleRevokeClientDoc	Informs the client DLL that a registered document was closed.

OleRevokeObject	Revokes access to an object. A server application typically calls this function when the user deletes an object.

OleRevokeServer	Called by a server application to revoke any registered documents and to revoke the server application registered with OleRegisterServer.

OleRevokeServerDoc	Revokes the specified document.

OleSavedClientDoc	Informs the client DLL that a registered document was saved.

OleSavedServerDoc	Informs the server DLL that a document has been saved.

OleSaveToStream	Saves an object to a file or other storage.

OleSetBounds	Informs the client DLL of the new object rectangle.

OleSetColorScheme	Recommends colors for documents and objects.

OleSetData	Changes the object's data for a specified format.

OleSetHostNames	Provides the client DLL with the object and document names.

OleSetLinkUpdateOptions	Changes a linked object between automatic and manual.

OleSetTargetDevice	Provides the client DLL with information about the output device.

OleUnblockServer	Processes a request from a queue created by calling the OleBlockServer function.

OleUnlockServer	Releases a server locked with OleLockServer.

OleUpdate	Updates an object's data and display.


OLE Structures
OLE Structures (all)

OLECLIENT	Contains client-function pointers

OLECLIENTVTBL	Points to client's callback function

OLEOBJECT	Contains object-function pointers

OLEOBJECTVTBL	Points to functions for object manipulation

OLESERVER	Contains server-function pointers

OLESERVERDOC	Contains document-function pointers

OLESERVERDOCVTBL	Points to functions for document manipulation

OLESERVERVTBL	Points to functions for server manipulation

OLESTREAM	Contains stream-function pointers

OLESTREAMVTBL	Points to functions for stream operations


Copyright

Microsoft Object Linking and Embedding (OLE) Reference

Information in this on-line help system is subject to change without

notice and does not represent a commitment on the part of Microsoft

Corporation. The software and/or files described in this on-line help

system are furnished under a license agreement or nondisclosure

agreement. The software and/or files may be used or copied only in

accordance with the terms of the agreement. The purchaser may make one

copy of the software for backup purposes. No part of this on-line help

system may be reproduced or transmitted in any form or by any means,

electronic or mechanical, including photocopying, recording, or

information and retrieval systems, for any purpose other than the

purchaser's personal use, without the written permission of Microsoft

Corporation.

(C)  Copyright Microsoft Corporation, 1992. All rights reserved.

     Simultaneously published in the U.S. and Canada.

     Help Database Build Date: 13 October 1992


Introduction to OLE

This topic provides a brief overview of object linking and embedding (OLE). The following chapters explain elements of this topic in greater detail; it is recommended that this topic be read before any other chapters.

The contents of this topic are split into two parts. The first part explains OLE from the point of view of the user; the second part gives a brief technical overview of how OLE works.

The first part of this topic starts out with a discussion of what OLE is and the benefits it provides to a user, followed by a detailed comparison and explanation of linking and embedding, from the user's point of view. Then client and server applications are introduced, including the operations that a server can perform on an object in a document of a client application. The second part describes how client and server applications communicate, along with a brief explanation of the special functions and structures that the developer must use. Finally there is a brief discussion of the registry, which is used by OLE to determine which objects are related to a particular OLE server application.

For more information, see the following topics:

What is OLE?

How Does OLE Work?


What is OLE?

OLE is a set of extensible application protocols that enables one application to use the services of another application in a nearly-seamless manner. Applications that follow the OLE protocols will be able to create documents that contain linked or embedded information from documents created by other applications; such a document is refer red to as a container document . A container document has objects that are still connected to the original application that created them. For example, a user can link or embed a spreadsheet in a word-processing application, and keep the connection to the spreadsheet open. Unlike normal cutting and pasting, the data in an OLE object can be:

linked (where the data resides in another, separate document), or

embedded (where the data resides in the container document).

In either case, the object can be edited only by the application that created it, not the application whose document it currently resides in.

Objects can include text, charts, spreadsheets, bitmap pictures, vector drawings, sounds, video clips, and anything else that can be displayed or controlled by an application.

Benefits of OLE

When incorporated into applications, OLE offers the following benefits:

Users can concentrate on the task they are performing, instead of the different applications required to complete the task. If a user prefers using one application, they need never leave that application. OLE brings other applications to the user in the context that the user prefers.

Applications can specialize in performing one job. A drawing application that implements OLE, for example, would not necessarily need any text editing capability. Users could put text into the drawing and edit that text using any text editor that supported OLE.

Files can be more compact because linking to objects allows a file to use an object without having to store that object's data. Linked objects in a file can be updated dynamically and shared among several files.

Embedded objects can be transferred easily to other users who can then edit the object without needing to know where the original data resides.

Embedded and Linked Objects

Embedding and linking allows the user to insert objects, created by some other application, directly into a document-- without having to leave the application being used to create the document.

Embedding an object is simple: the user selects from a list of objects (for example, a picture, a range of spreadsheet cells, or a sound recording). Then the application that can create the object starts automatically, giving the user the opportunity to create or modify the object for ins ertion. When the user quits the application that created the object, the modified object automatically appears in the document of the current application.

Linking objects means the user inserts a link to the file that contains the source of the object. Then, any time the source object changes, the linked object in the user's document is updated to reflect the change at the source.

Embedded Objects

To illustrate the concept of embedded objects in more detail, consider a situation where an author needs to write a technical article and, in order to enhance it, needs to add objects created using one or more other applications. To accomplish this, the author begins work with a word processor, using it to lay out the pages and enter the majority of the text, to achieve an appearance similar to that shown in Figure 1.

Figure 1. An embedded object in a container document

To enhance the article with a logo of the company, the author places the insertion point where the logo is to appear and chooses the type of object to insert, using the Insert Object command. (For example, Figure 1 in the book you are now reading is an embedded object in the document used to prepare the camera-ready copy.)

Choosing the object type automatically starts the appropriate graphics application from within the word processor. Once in the graphics program, the author draws the logo (or imports it from a previously saved graphics file), then quits to return to the word processor. Quitting the graphics program causes the drawn logo to be automatically displayed in the document. In the sample document shown in Figure 1 , the company logo, created with an OLE graphics program, is inserted as an embedded object.

Note:	While the following example focuses on a word processor document and a graphic objects, it can apply to any type of OLE application, document, and object.

As an embedded object, all data associated with the logo is included with the word processor document and will be saved as part of the document file. Figure 2 shows that the saved document file contains not only the object data in a form needed by the word processor to display the object, but also in the form that is native to the application that created it. The native data allows the object to be passed back to the creating application for possible changes. The embedded object also contains data that associates it directly to the creating application so that it is known which application provided the object and with what presentation data format it was created.

Figure 2. Data storage format for embedded objects

If, at some later time , the embedded object (the logo, in this case) needs to be modified, the author simply opens the word processor document, and double-clicks on the embedded object. This action starts the associated graphics program and displays the object using the embedded data previously stored in the word processor document. When the author finishes with the object and quits the graphics application, the object displayed in the word processor document is automatically updated to reflect the changes.

Prior to OLE, it was certainly possible to integrate text and graphics into a word processor document-- the standard way was to use the cut, copy, and paste mechanism supported by the clipboard. However, if the copying and pasting had to be done back and forth many times, the process grew tedious and the room for human error increased. Now with OLE, the graphics can be pasted in once, and edited as many times as necessary with a simple double-click of the mouse.

Linked Objects

Linked objects, although they may look the same to a casual user, differ greatly from embedded objects. The main difference between an embedded object and a linked object is in:

how it is inserted into the document

how it is later changed or updated

where the native data for the object is stored.

While embedded objects can be copied and pasted with the clipboard to insert them into a document, linked objects must be copied and pasted through the clipboard. Embedded objects are usually opened for edited by double-clicking the object to start the creating application; the changes are made and the creating application closes. This method can also apply to a linked object; however, linked objects are updated whenever the original file that the object is linked to is changed.

Figure 3 depicts the data storage format for a linked object. Unlike an embedded object that saves the native data to an object, linked objects store only the presentation data for the object along with the pathname of the source file that contains the original, native data.

Figure 3. Data storage format for linked objects

To illustrate object linking, suppose a word processor document needs to include data that is normally maintained in a spreadsheet. A range of spreadsheet cells in the original spreadsheet is pasted into the word processor document as a linked object. The word processor document then contains the data from the original spreadsheet file. A single cell or an entire spreadsheet can be linked. Each time the original spreadsheet is changed, the linked object in the word processing file can be updated, either automatically or manually, by the user's choice.

Figure 4 shows how the spreadsheet cells are linked to the word processor document. While the document contains the data necessary to display the contents of the cells, just as it would if they were an embedded object, it does not contain native data for the object. Native data is not necessary since any changes to the spreadsheet will be made by the spreadsheet program directly to its own file--the file to which the word processor document is linked.

To modify a linked object, such as the contents of the spreadsheet cells in the preceding example, the spreadsheet cells in the word processor document are double-clicked. This action starts the associated spreadsheet program and causes the spreadsheet application to open the linked file for editing.

Figure 4. A linked object in a container document

After the linked object is edited, saved, and the spreadsheet application is closed, the spreadsheet cells in the word processing document are updated immediately if the user has set the link up as an automatic link; or if the link will be updated later at the user's choice, the link is a manual link. Any other documents containing links to the changed object will have their copies of the object updated whenever those documents are opened and the command is given to update the linked object.

OLE and Audio-Visual Objects

So far, we've discussed OLE and how it enables the user to insert and edit objects, specifically graphics and spreadsheet data embedded in or linked to word processor documents. However, the use of OLE is not limited to inserting graphics and tabular data. With OLE, the user can also insert audio and visual types of objects. For example, the user could embed an audio object such as a digitally-record ed spoken message so that when the reader clicks the objects, the message plays through a speaker. For a document that provides "how to" instructions, OLE objects that play animation or video could be included.

Server and Client Applications

Throughout most OLE-related documentation, an application is specified as either a client application or a server application , even though an application may function as either at different times. The word processor mentioned in the examples of Figures 1 and 4 operates as a client application that obtains service from two different server applications; a graphics program and a spreadsheet program. As a client application, the word processor creates a container document , referred to as such because it contains the embedded and linked objects as well as the text data that it creates itself.

The menus of the client application are modified to include an Object command on the Insert menu that opens an Insert Object dialog box. This dialog box, shown in Figure 5, allows the user to choose the type (descriptive class name) of object to be embedded into the container document from a list of object types. The client application creates this list of object types dynamically by polling the registry; the registry is used by all server applications to register the object (class) it will serve, the types of objects it supports (descriptive class names), and the types of operations it can perform on objects (verbs). For more information on registering applications, see the section titled "The Registry," later in this topic.

The example shown in Figure 5 lists Microsoft Drawing (the descriptive class name for Microsoft Draw ) as one of the object types available for embedding. Microsoft Draw can operate as a server application that provides objects to client applications. The objects it provides are metafile-type drawings created with lines, circles, text, and so on.

Figure 5. The Insert Object dialog box lets users choose objects

When the user chooses a particular object type, the corresponding server application starts, which allows the user to create the object, or open a file that contains the object. After editing the object, the user quits the server application and the client application's container document is automatically updated with the embedded object at the current insertion point. Later, to make changes to the object, the user simply double-clicks on the object to start the server application again; a special editing window opens in which the object is placed for revisions.

Actions that Servers Can Perform on Objects

Double-clicking on an object is the normal way to invoke the server application associated with an object. The particular operation that the server performs is called a verb. Double-clicking invokes the primary verb supported by the server for the object's class. The primary verb is considered to be the most important, useful, or frequently-used verb. For most classes of objects, the primary verb (and often the only verb) is Edit.

Figure 6. Client application's Edit menu when selecting an audio object

Some object classes have multiple verbs. For example, a sound or animation server might support Play and Rewind verbs in addition to an Edit verb. Any operation a user might want to perform on an object can be provided by the server application as a verb. The client application provides user-access to the different verbs by means of its Edit menu. When the user selects an object that supports multiple verbs and chooses the <Descriptive-Class-Name > Object command on the Edit menu (for example, the Sounder Audio Object command on the Edit menu), the client application reconfigures its Edit menu, using information retrieved from the registry. The Edit menu can then reflect the verbs available for that object. A sample Edit menu with a <Descriptive-Class-Name> Object command appears in Figure 6. The three verbs associated with the object named Sounder Audio are Play, Record, and Rewind.


How Does OLE Work?

Object linking and embedding is a set of extensible protocols that enable client and server applications to communicate to each other through a set of dynamic-linked libraries (DLLs).

How Client and Server Applications Communicate

OLE uses DDE(Dynamic Data Exchange) as the underlying transport mechanism for communicating between client and server applications. A set of dynamic-linked libraries manage the DDE conversations for an OLE application. These DLLs make it is possible to implement OLE with little DDE knowledge and without the need to write DDE code. There are two DLLs that allows client/server communication, one that interfaces to the client application (OLECLI32.DLL) and one to the server application (OLESVR32.DLL).

Server applications are written using the server API included in the server DLL. Likewise, client applications are written using the client API included in the client DLL. In addition to managing the DDE conversation between client and server applications, the OLE DLLs can render objects for the client and launch and shut down server applications . While the client and server DLLs do most of the OLE work, the client and server applications must maintain specific data structures that correspond to OLE objects.

Server applications provide a set of services that the libraries will access when fulfilling requests made by the client application. Client applications must manage all user interface features and can call client DLL functions to do such things as open a server document file, show a specific object, instruct the server application to perform a specified verb on an object (for example, edit), or instruct the server application to save an open document.

The illustration shown in Figure 7 details the basic communication paths that are established between the client and server applications via the OLE client and server DLLs. The applications communicate with their respective DLLs by using OLE-specific function calls and callbacks.

Figure 7: OLE's library-based architecture and the use of function calls

The illustration in Figure 7 also indicates the general sequence of communication events that take place when a user chooses to insert an object from within an application that supports OLE. In this situation, the client application must first recognize that the user is requesting service by a different application (such as when the user double-clicks an object) and then make the appropriate function call to the client DLL.

The following steps correspond to the numbered events in Figure 7:

1	When the user makes an OLE request from within the client application, such as choosing to insert an object, the client application passes the request via specific function calls to the client DLL.

2	The client DLL determines which server application is needed to fulfill the request and generates the appropriate message (using DDE-messaging) for passage to the server application, via the server DLL.

3	The server DLL makes the appropriate callback to the server application, such as create-a-new-object. (Callbacks are described in the next section.)

4	After the user has finished creating the object, the server application passes the object data to the server DLL with a function call.

5	The server DLL generates the appropriate message (using DDE-messaging) for passage to the client application, via the client DLL.

6	The client DLL makes the callback to the client application, passing the object data, which the application places into the container document.

Note:	The use of DDE for communication between client and server DLLs may not be supported in future versions of OLE. Client and server applications will continue to communicate through OLE DLLs, but the transport mechanism cannot be guaranteed.

OLE Functions and Structures

OLE applications make use of callback functions. Callbacks are functions that must be written in a client or server application by the developer. The callback functions are then called directly by the OLE DLLs. Implementing OLE client or server support requires adding callbacks to the application code so that the OLE DLLs can provide data to the application and cause the application to perform specific operations.

To implement callbacks , OLE client and server applications use a mechanism called a VTBL. A VTBL is a data structure that contains pointers to functions (also known as "methods" or "member functions"). The term VTBL comes from the object-oriented concept of a Virtual Table in which methods are associated with instances of an object; each method is a member function of the VTBL associated with the data that forms that particular object. In OLE, VTBLs are the name of the specific data structures used to associate callback functions with the data forming a specific object.

Note:	For more information on VTBLs and callbacks, see Callback Functions and Data Structures.

Clipboard Formats

To support the clipboard-based cut and paste operations that embed and link objects, there are three new clipboard formats that client and server applications must support:

Format	Description

Native	Contains the binary representation data for an object.

ObjectLink	Identifies the type of linked object and the corresponding server application to which it is linked. Also contains the document path name that identifies the object.

OwnerLink	Provides the class and object information for embedded objects.

When a user chooses the Paste Link command, the client application looks for the ObjectLink format on the clipboard and ignores the Native and OwnerLink formats. If the application finds the ObjectLink format and a useful presentation format, it uses them to make an OLE link to the source document for the object.

Note:	For more information on clipboard issues, see Considerations for OLE Applications.

The Registry

OLE server applications must register themselves and the services they provide in the registry. The registry allows server applications to make information about the objects they create available to OLE client applications. It also allows the OLE DLLs to find the server application when the user double clicks an object previously embedded or linked in a container document. For example, a graphical drawing program can register itself in the registry (as a unique object class) as a server application that creates drawing objects. When the user of a word processor application wants to insert a graphical drawing object, the drawing application can be automatically started for creation of the object.

Registering a server application is typically done during installation, or possibly when the application is started for the first time. Each time a server application starts up, it checks the database to ensure that its registration is still valid. If registration is ever lost, the server application must reregister itself, otherwise its services will not be known by other applications, and it cannot be used by the OLE DLLs.

Note:	For more information on registering OLE server applications, see Using the Registry.


Considerations for OLE Applications

This topic contains general information that relates to the implementation of OLE in both server and client applications. Where the information concerns only a server or a client application, it is so noted. Since this topic contains information that may affect how you write your code, we suggest you read through it before doing any coding.

For more information, see the following topics:

Considerations for Objects and the Clipboard

Considerations for Mapping Modes

Considerations for Version Numbers

Considerations for DDE

Considerations for Data

Considerations for Functions

Server Application Issues

Client Application Issues


Considerations for Objects and the Clipboard

An object's appearance depends on the presentation format used to display the object. When a server application places an object on the clipboard, it supplies one or more graphical representations of the object. These representations may be in metafile format (CF_METAFILEPICT, referred to in the clipboard as Picture format), enhanced metafile format (CF_ENHMETAFILE), device-dependent bitmap format (CF_BITMAP, referred to as Bitmap), or device-independent bitmap format (CF_DIB, referred to as DIB).

When pasting an object into a container document, the OLE DLLs use one of these presentation formats to display the object. Since bitmaps and metafiles commonly differ in appearance when they are resized, the appearance of objects may vary depending on the presentation format used to display the object.

Clipboard Presentation Formats for OLE

There are three new clipboard formats for OLE client and server applications to support: Native, ObjectLink, and OwnerLink. While the Metafile, Enhanced Metafile, Bitmap, and DIB formats are used for the presentation of objects, the Native, ObjectLink, and OwnerLink formats provide additional object information that is needed by client applications.

Native Presentation Format

Native format consists of the native data that the server application used to define an object; this is data that the server application would normally save to a file. A client application does not need to interpret native data; however, it does need to store it in the container document as an embedded object. Storing the native data enables a client application to pass the object back to the server application (via the OLE libraries), when the user wants to edit the object.

ObjectLink Presentation Format

The ObjectLink format is used to link objects in the container document. This format consists of the following three null-terminated strings, with the last string double null-terminated:

String	Purpose

Object class	Identifies the different types of OLE objects. Each server application has a unique class that identifies it as being able to edit or play an particular kind of object.

Document name	Identifies the pathname of the document from which the object was copied to the container document.

Item name	Specifies the object in the context of the server document in which the object was created, such as in the case of a spreadsheet application where the item name field is used to specify a range of cells.

The ObjectLink data is placed on the clipboard as shown in the following example; where Worksheet is the class, c:\dir\filename is the document name, and R1C1:R5C3 is the item name.

Worksheet\0c:\dir\filename\0R1C1:R5C3\0\0

Note:	It is possible for the item name to be NULL; in this case, the entire source document is the object.

OwnerLink Presentation Format

The OwnerLink format is used with embedded objects. This format also consists of the null-terminated class, document name, and item name strings (see preceding section). However, unlike linked objects, client applications that embed objects do not use the document name and item name strings.

Placing Data on the Clipboard

The particular data formats and the order in which they are put on the clipboard determine how an OLE object is treated by the clipboard. When the user wants to paste an OLE object from the clipboard, the available data formats and their order determines whether the object can be treated as linked, embedded, or both linked and embedded. For more information on cutting and copying data to the clipboard, see Chapter 4, "Implementing OLE into Server Applications."

Clipboard Contents and Available Object Types

The following table lists several possible clipboard states, with varying types and orders of data.

Order of Clipboard Formats	Embedded Object Available?	Linked Object Available?
1. Native 2. OwnerLink 3. CF_METAFILEPICT	Yes - Native and OwnerLink formats define the object and presentationformat is CF_METAFILEPICT.	No - ObjectLink format is missing and Native format precedes OwnerLink.
1. Native 2. OwnerLink 3. CF_METAFILEPICT 4. ObjectLink	Yes - Native and OwnerLink formats define the object and presentationformat is CF_METAFILEPICT.	Yes - ObjectLink format defines the link and presentation format is CF_METAFILEPICT.
1. OwnerLink 2. Native	No - OwnerLink comes before Native.	Yes - OwnerLink format defines the link and Native format can be used torender the object's presentation.
1. Native 2. OwnerLink 3. CF_BITMAP 4. CF_DIB 5. CF_METAFILEPICT 6. ObjectLink	Yes - Native and OwnerLink formats define the object and presentationformat is CF_BITMAP because it was first on the clipboard.	Yes - ObjectLink format defines the link and presentation format is CF_BITMAP.
1. OwnerLink 2. Native 3. CF_METAFILEPICT	No - OwnerLink comes before Native.	Yes - OwnerLink format defines the link and presentation format is CF_METAFILEPICT.
1. Native 2. CF_METAFILEPICT	No - OwnerLink format is missing.	No - ObjectLink format is missing.
Note:	In the table above, the CF_ENHMETAFILE format will have the same effect as CF_METAFILEPICT. In Win32, either format will be converted to the other automatically by GetClipboardData.

Rules for Inserting Embedded Objects

In order for a client application to embed an object, the server application must put the correct presentation formats on the clipboard. Typically, a server application places Native data, OwnerLink, and at least one presentation data format on the clipboard to support embedding.

Rules for Inserting Linked Objects

In order for a client application to create a link to an object, the server application must put the correct presentation formats on the clipboard. Typically, a server application places ObjectLink and a presentation data format on the clipboard to enable client applications to create links to objects.

Order of Clipboard Data Formats

The most common order for clipboard formats is:

1	Preferred server application data formats (for example, BIFF, SYLK, RTF)

2	Native data

3	OwnerLink data

4	Presentation formats (CF_METAFILEPICT, CF_BITMAP, or CF_DIB)

5	ObjectLink data

These formats are in addition to the server application data formats normally placed on the clipboard to support Copy and Paste operations. This is a Microsoft Windows clipboard management convention, and is not specific to OLE. These formats should be provided by the server application in case the container document understands the server's data.

Before placing an object on the clipboard, a server application must put descriptions of the data format on the clipboard. These data formats are listed in order of their fidelity of object description, from most descriptive to least. When a user chooses the Paste command, the client application mus t query the clipboard for its current formats and use the first format that is compatible with the container document for the object.

Because server applications put data onto the clipboard in order of the ir fidelity of description, the first acceptable format found by a client application is the best format for it to use for an embedded object. If the client application finds an acceptable format prior to the Native format, it incorporates the data directly into the container document without making it an embedded object. For example, a Microsoft Word document would not embed an object from clipboard data that was in RTF format, it would simply include the text as part of its own document. However, if the client application cannot accept any of the data formats placed on the clipboard prior to Native and OwnerLink, it must use those formats to insert an embedded object and then display the object by using one of the presentation data formats.

Note:	If a container's preferred format is on the clipboard, it is recommended that the client application choose that format instead of pasting the data as an OLE object. For example, when copying a range of cells to some other portion of a worksheet document, it makes sense to paste the clipboard data as an OLE object since inserting an OLE object would add unnecessary size and complexity to the document.

When a user chooses the Paste Link command, the client application must check to see if the ObjectLink format is on the clipboard, using one of the OLE query functions, and ignore the Native and OwnerLink formats. If the application finds the ObjectLink format and a useful presentation format, i t uses them to make an OLE link to the source document for the object.

Order of Presentation Data Formats

The order of the presentation formats also determines which of the standard presentation formats the OLE libraries use. For example, if CF_BITMAP is provided before CF_METAFILEPICT or CF_ENHMETAFILE, then the OLE library will use the bitmap representation to render the object. This is important, since the OLE libraries only provide simple scaling of objects. Metafiles provide better scaling than bitmaps, so it is preferable for server applications to provide CF_ENHMETAFILE before any other graphic representations (such as CF_DIB, CF_BITMAP, or even CF_METAFILEPICT). Currently, the OLE libraries only support the CF_METAFILEPICT, CF_ENHMETAFILE, CF_ DIB, and CF_BITMAP presentation formats.

Note:	Server applications must support CF_METAFILEPICT or CF_ENHMETAFILE format. The server application can provide any of the presentation formats when placing an object on the clipboard, but when the OLE libraries request data directly from the server, the server must provide the object in CF_METAFILEPICT or CF_ENHMETAFILE format.


Considerations for Mapping Modes

When working with the visual presentation of OLE data, you must be aware of the mapping mode that the OLE libraries use and how that can affect the mapping modes of your OLE applications.

Mapping Mode Conversions

The OLE libraries express rectangles and other dimensional quantities in HIMETRIC units (MM_HIMETRIC). This mapping mode includes any rectangles provided in the SetDocDimensions callback function or OleGetBounds function or in any metafile that the server application copies to the clipboard.

If your application uses another mapping mode, you must create conversion functions to and from the mapping mode you normally use. For example, if your application normally would use the MM_TWIPS mapping mode, you would need to convert from TWIP S to HIMETRIC when transferring data to OLE, and convert back from HIMETRIC to TWIPS when receiving OLE data.

Note:	Neither the width nor height of an OLE object should exceed 32,767 HIMETRIC units.

Sample Code for Converting Mapping Modes

The following code example shows how to convert to and from HIMETRIC units:

#define HIMETRIC_PER_INCH 2540

/* DeviceToHiMetric

 * Converts a point from device units to HiMetric units. */

void DeviceToHiMetric(HWND hwnd, LPPOINT lppt)

{

    lppt->x = MulDiv (lppt->x, HIMETRIC_PER_INCH, giXppli);

    lppt->y = MulDiv (lppt->y, HIMETRIC_PER_INCH, giYppli);

}

/* HiMetricToDevice

 * Converts a point from HiMetric units to device units. */

void HiMetricToDevice(HWND hwnd, LPPOINT lppt)

{

    lppt->x=MulDiv(giXppli, lppt->x, HIMETRIC_PER_INCH);

    lppt->y=MulDiv(giYppli, lppt->y, HIMETRIC_PER_INCH);

}

Using Mapping Modes to Determine Logical Size for Objects

In Microsoft Windows, there are four mapping modes that define how numbers relating to object sizes are to be passed and interpreted. These modes include ENGLISH, METRIC, TWIPS, and PIXELS(with ISOTROPIC and ANISOTROPIC being PIXEL modes). These mapping modes communicate physical sizes. For example, if an application using MM_HIMETRIC mode is to display a line ten centimeters long, the number of units would be 10,000. The resulting line drawn by the application on the screen will be ten centimeters long, regardless of the size of the video display area. In this case, the printed output will also be a line ten centimeters long.

Since people read display screens from a greater distance than they do printed copy, most applications written for Microsoft 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 log ical size. Using the logical size approach, a column of text that is physically six inches wide could appear 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 using physical sizes and pasting objects into container documents. The effect of the problem is to lose the correct size ratio between the pasted object and the text owned and displayed by the client application. That is, the text is scaled up for readability, but the pasted object may not be. Consequently, applications should take care to preserve the relative size and position of text and objects, which means that if it uses logical resolution for text, it should scale objects accordingly.

In the examples shown in Figure 8 , a chart object has been pasted from a source application that uses physical size into container documents of two different client applications that use logical resolution for display of the text. The application displaying the container document on the right 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 r esolution for display. Both documents will print with the correct object-to-text-size ratio.

Figure 8. Chart object sized according to logical resolution and to physical size

In OLE, the units for specifying the size of drawn objects is HIMETRIC, which means object sizes are in physical units. However, client applications need not use the MM_HIMETRIC mapping mode to draw pasted objects to the display, but should rather map objects to the screen in the same manner as text. That is, if the client application displays text to the screen using a mapping mode that enlarges it, then 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 Figure 8. Since most Windows applications use logical resolution for this type of display mapping, it is suggested that OLE client applications 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.

Note:	If your client application displays text in physical units, where point sizes are accurately maintained on the display (not scaled up for viewing), it can use MM_HIMETRIC mode for the display of pasted objects.


Considerations for Version Numbers

If you create and distribute a new version of an OLE application, you must make sure that objects can be handled properly by the new version.

Including Server Version Numbers in Files

Server applications should include version numbers in any native data structures as well as in files. Newer versions of server applications that are intended to replace older versions should be capable of dealing with native data created by older versions. A version number in the structures allows:

A newer server application to convert the old data to a new structure

An older server application to notify the user that a newer version of the application is necessary to edit that data.

The following code example shows a data structure for storing the version number and related information.

typedef int VERSION;

typedef struct {

    VERSION version;

    int idmColor;

    int nwidth;

    int nHeight;

    int nX;

    int nY;

    int nHiMetricWidth;

    int nHiMetricHeight;

    char szName[10];

} NATIVE, FAR *LPNATIVE;

With OLE, a client application can embed an object created with one version of a server application and later request a newer version of that application to edit that same data.

Newer Versions and the Registry

If a new version of a server application allows the user to keep the old version available, a new object class and descriptive class name should be placed in the registry for the newer server application. One way to do this is to append a version number to the descriptive class name, allowing the end-user to differentiate between the two versions when necessary. For example, you could have two versions of a drawing program with descriptive class names "Draw1" and "Draw2."

The end-user should be able to discard the older server application and remap the class in the registry, typically by means of the server application setup program. To remap the class , the old and new objects types are given the same value for the descriptive class name that describes the object class (although the two classes remain distinct). The client application must make sure there are no duplicate descriptive class names when it enumerates the registry to produce the list displayed in the Insert Object dialog box of the client application.

For client applications, mark the files or object data structure with version information that reflects the version of OLE under which the files are saved. This will insure that if the user has a version of OLE different from the version the files were saved under, you can provide whatever conversions are necessary between the old and new versions of your application.


Considerations for DDE

If your application currently supports DDE Execute commands and your OLE server application supports the StdExecute protocol, the application will receive DDE Execute strings not only through DDE messages but also through the Execute callback functions (in the OLESERVER and OLESERVERDOC VTBLs) when those commands are passed through OLESVR32.DLL. If your application has existing code that parses an Execute string, isolate it so that it is callable from your WM_DDE_EXECUTE case or from either Execute callback. The application may also have code to execute the commands after parsing, which you can also isolate to be callable from these separate locations.


Considerations for Data

There are several considerations relating to data in OLE applications. They are discussed in the following sections.

Isolating Global and Static Data

To simplify OLE implementation, you can reorganize existing global and static data with the objective of isolating non-OLE data from the OLE-specific data. Because OLE is a protocol, it is not something that is fully integrated into the application. Since it is possible to upgrade the OLE DLLs independently of Microsoft Windows , you'll be better prepared to make a revision to the application's OLE code, if isolated, without making changes to the remainder of the application.

In addition, you might want to add a global variable to a server application to indicate if it was started by the OLE protocol or by a user as a st and-alone application. For example, in handling a command like File Save, the application will need to distinguish between the two methods of starting to perform slightly different operations.

Use of Window-Specific Data

OLE follows the object-oriented model in that server applications contain documents, and in turn, documents contain objects. Isolating object, document, and server data is easier if you structure your application to have a window that contains document w indows, and document windows that contain object windows. Each kind of window should maintains a private data structure visible only to that window. Not only does this simplify data management, but it also reduces the need of global variables to track the number of objects or open fi les, and possibly variable-length arrays of data structures.

For each server application, each document, and each object window, register the window class with sizeof(HANDLE) in the cbWndExtra field of WNDCLASS and define a single data structure to contain the data specific to that class. Allocate memory for this structure when the window receives a WM_CREATE message and free that memory on WM_DESTROY . Store the handle to this memory in the window's extra bytes. Then, whenever the window procedure is entered, it can simply retrieve this handle with GetWindowWord and have access to the entire data structure.

Isolating Document- and Object-Specific Data

Information that is global between documents or document windows can also be isolated into a data structure, or it can be attached to each document window. Data isolated into a structure is easily folded into an OLESERVERDOC data structure that holds the OLE-specific data for each document. Also, by isolating this data and always referencing it with a pointer, changing where the structure resides is a simple matter of changing the name of the pointer from which you reference the variable.

In the same manner used to isolate document-specific data, you can also isolate object-specific data that can be folded into your application-defined OLEOBJECT structure.


Considerations for Functions

To simplify implementing OLE into your application, consider reorganizing functions and code in your application to make them callable from OLE functions. The following sections provide some guidelines on how to reorganize your application's existing fun ctions.

Initialization Procedures

During application initialization, the application will need to perform additional steps necessary for OLE, such as registering new clipboard formats and calling OleRegisterClientDoc . Isolate your application initialization code to prepare a place for these additional steps. Since some of the OLE initialization steps have corresponding shutdown steps to perform when an application closes, you can isolate your cleanup code as well.

The Change Flag

All applications that load, modify, and save files track some sort of flag that indicates whether the user has made a modification to the file but has not saved the file since the changes were made. Above what your application currently does to set or clear this flag, various OLE operations, such as creating or changing an object, will also make the file dirty. Isolate set-change-flag code so that you can control the flag from any other function, such as the OLECLIENTVTBL CallBack function.

Exit Procedures

Applications generally include code to clean up items such as allocations and GDI objects that were created in the application initialization code. In the same fashion that you separated initialization code, you can isolate the exit procedure to create a place for OLE-specific cleanup.


Server Application Issues

There are several issues that relate to developing OLE server applications; the following sections discuss these issues.

Initialization

During installation, an OLE server application should verify that it is registered in the registry and if not, register itself. Registration only needs to occur for the first instance of an application. By isolating your existing installation code, you can create a place to insert the code that has to deal with the registry. If all initialization code resides in one function call made from WinMain, then that function can simply return FALSE indicating there was an error so that WinMain can terminate the application.

One of the complexities of initialization is parsing the command-line to detect an /Embedding option. To make this task easier, consider writing a function to parse the command line into separate parameters. For more information on parsing the command line, see Chapter 4, "Implementing OLE into Server Applications."

When the /Embedding switch is present, the nCmdShow parameter passed to WinMain will have to change; you will need to include some method in your initialization function to return the modified nCmdShow. This can be done by passing a pointer to nCmdShow to the initialization function so that it can modify nCmdShow or leave it alone. WinMain then does not have to change, since nCmdShow was changed behind the scenes.

Background Processing Schedulers

Some applications that perform background processing modify the message loop in WinMain to see if there are more messages to process (by using PeekMessage ). If there are no messages, the application can perform one or more steps of some background process while waiting for more messages.

OLE requires a server application to enter a separate message loop when certain operations require it to wait until an object, a document, or the server is released. (The message loop is necessary to process DDE messages bet ween the OLE DLLs while synchronizing a sequence of calls in the server.) Like any other message loop, there may be idle time during which your server application can perform some background task. By isolating the code needed to perform a step of this background task, it can be called from any message loop anywhere in the application with the same results.

Drawing to an Arbitrary Device Context

OLESVR32.DLL may request that a server application produce an image on the screen, to a metafile, or to a bitmap (for providing an image to a client application or even to a printer). You can simplify this requirement by modifying whatever drawing code your application uses for its objects to work with an arbitrary device context (DC)--whether it be a screen DC, a metafile DC, a memory DC containing a bitmap, or a printer DC.

Clipboard Format Builders

OLESVR32.DLL requests an OLE server (through the GetData callback in the OLEOBJECT structure) to provide a handle to data in any single clipboard format, including Native, OwnerLink, CF_METAFILEPICT, CF_ENHMETAFILE, and CF_BITMAP. To simplify your GetData callback, create functions that return handles for formats that existed prior to implementing OLE and that are readily usable for clipboard I/O or in handling the GetData callback function.

Manipulating Change Flags

Invariably there will be several operations that can cause some change to occur in the server document that the user is editing. Your application may currently set some global flag in all of these cases. Isolate code to change that flag into a separate function that you can then call from each change case.

When you add OLE linking support, you must notify the client application that the data has changed. By creating a function to call every ti me your application changes the dirty flag, you create a single place to add the client notification call and prevent yourself from having to find and modify (which means possibly miss) all the cases where you change the dirty flag.

File I/O

Since implementing OLE affects most File menu commands and may require loading or saving a file outside the context of those commands, you can isolate the functions that read and write the data structures to a file. The OLESERVER callback function CreateFromTemplate , for example, requires that you open and read the contents of a file as the initial contents of a new document in the server application. The server application may already include functions that create a new document from a file, but CreateFromTemplate also requires that the file be used for initial data and that the file not be kept open.

Also, you can create a single function from which you prompt the user to save changes in a document before creating a new document, opening a new file, or exiting the application. Normally, this function displays a message box and, depending on whether the user chooses Yes, No, or Cancel, it either saves the file, continues with the operation (New/Open/Exit), or cancels the opera tion.

When starting a server application to edit an embedded object, the text in this message box will change; centralizing this code now simplifies the necessary changes for OLE implementation. For more information on OLE user interface guidelines, see The OLE User Interface.

Changing Window Title on File Open/Save As

Most applications that load files display the loaded filename in the title bar of the application along with the application name. When a user opens a file or renames the file with the Save As command, the name of the file in the title bar should change to reflect the new filename. However, the user interface for server applications requires a different title if the server is editing an embedded object. You can isolate the code for manipulating the title bar by creating a function that takes the main window handle, a pointer to a string containing the document name (or filename), and a pointer to a string containing an object name. In stand-alone (or OLE linking) operation, it can simply pass a NULL as the object name and have this function create the string:

<Application Name> - <Filename>

If the function receives a non-NULL object name, use the object name to indicate that the server is editing an embedded object and change the title bar to the appropriate string:

<Application Name> - <Descriptive-Class-Name> in <Filename>

The server DLL provides the Descriptive-Class-Name and Filename for an embedded object through the SetHostNames callback function.


Client Application Issues

There are several issues that affect the implementation of OLE into client applications; the following sections discuss these issues.

Referencing Objects in Files (Client Applications)

OLE gives your client application complete control over where you store objects. The most convenient method is to simply store objects directly into existing document files; however, they can also be stored in their own files, in a database, and so on. In any case, modify your existing application's file format to reference an object with a persistent name that your OLESTREAMVTBL functions can use to locate and load an object. (For more information on OLESTREAMVTBL, see Callback Functions and Data Structures.)

Since OLE affects your file format, you can isolate the file read and write functions so that adding an OLE call is trivial. When writing a document file, store a small data structure for every object in the document to identify that object and its location. When a document file is loaded and one of these structures is encountered, the name and location of that object is available allowing it to be reloaded.

Clipboard Operations

In client applications, you can isolate code to handle each clipboard operation such as Cut, Copy, and Paste. Where the client application normally cuts and copies data, it will need to determine if an object is selected and then call OleCopyToClipboard. During a paste operation, it will need to determine whether or not it is to paste an OLE object instead of other available data. Implementing OLE also adds the Paste Link and/or Paste Special commands that can make use of your existing Paste functionality.

Painting and Printing Code for Objects

Painting or printing an object requires at least one call to OleDraw . If your application currently draws objects, isolate this code to display or print these existing objects. Later, you can add a quick check for an OLE object in this procedure and call OleDraw as necessary. Isolating the code now will save you from tracking down every case where the application draws or prints an object.

Menu Enabling/Disabling Functions

Implementing OLE in your client application affects the Edit menu. Besides adding new menu items, OLE adds an extra step in handling standard commands such as Cut, Copy, and Paste. This extra step is needed to determine whether or not to disable these c ommands. First, isolate the code that handles the WM_INITMENU or WM_INITMENUPOPUP message in your main window procedure to enable or disable menu items. Second, centralize any other code that enables or disables the standard menu items.

Background Processing

A client application may use a modified message loop in which it detects idle time (no messages to process) and performs a step of background processing before checking for new messages. As described in Implementing OLE into Client Applications, the OLE DLLs require a client application to enter a separate message loop during an asynchronous operation and wait until an object (or all objects) is released. This message loop is necessary to process DDE messages between OLESVR32.DLL and OLECLI32.DLL.

Like any other message loop, there may be idle time during this OLE wait loop during which the application can perform some background task. By isolating the code needed to execute a step of this task, you can call it from any message loop in the application with the same results.


OLE User Interface

This topic describes the recommended user interface changes that will need to be made to a client or server application's user interface to support object linking and embedding.

For more information, see the following topics:

OLE User Interface

Inserting Objects

Viewing Objects

Activating Objects

Editing Objects

Links and Link Dialogs

Link Command Buttons

Dialog Control Buttons

Link Status Entries

Other Dialogs for Link Updating

Status Line Message Recommendations


OLE User Interface

The OLE interface provides easy methods for inserting, editing, viewing, and activating linked and embedded objects, and modifying the properties of such objects.

Client and Server Applications

The OLE process requires a dialog between the client and server application. In addition to the changes in functionality, there are several key differences in the interface of client and server applications:

Client applications add four commands to the Edit menu below the Paste command: Paste Special (and/or Paste Link), Links, Object, and Insert Object.

If there is an Insert menu, the Insert Object command may be placed there as Object instead. The Paste Link command is optional if your application already has the preferred Paste Special... command, as discussed in Selectively Inserting Objects with the Paste Special Command.

There are two types of servers: full servers and mini servers. The title bar for both server types should read as follows and in Figure 9:

<Server> <Descriptive Class-Name> in <Container-Document>

An object class name must always be presented to the user (in window titles, list panes, dialogs, and so on) in the human readable format provided by the registry. The client application must supply an appropriate <Container-Document> string to the server application. Because link servers open the source document, their title bars display the standard information:

<Server> <Source-Document>

Mini Servers

A mini server application uses a dialog box to communicate with the user and requires three command buttons: OK, Cancel, and Help. (The example mini server in Figure 9 includes an optional Apply button.)

Figure 9. Mini server interface

Full Servers

A full server is a stand-alone application with a full set of menus. In a full server application (or in a server window in an MDI application), the File menu should be modified as follows and as shown in Figure 10. (The client application must supply the appropriate <Container-Document> string to the server application.)

The Save command should be replaced by Update <Container-Document>.

The Close command (MDI applications) should be replaced by Close & Return to <Container-Document>.

The Save As command should be changed to Save Copy As.

The Exit command should be replaced by Exit & Return to <Container-Document>.

Figure 10. Full server application interface changes

If the user attempts to launch a server (for example, a mini server) that cannot be run as a stand-alone application, the server application should display the error message shown in Figure 11.

Figure 11. Stand-alone warning message

Note:	SDI (Single Document Interface) applications should not implement File New and File Open when running as servers. It is recommended that these commands be replaced by the Import command, which allows the loading of an existing file without severing the connection with the client application. (See the section, Updating Objects from SDI Server Applications.)


Inserting Objects

The basic user interface for inserting linked and embedded objects relies on the familiar Cut, Copy, and Paste commands on the Edit menu, plus one additional command, Paste Special... (and/or Paste Link), for inserting linked objects and for providing additional control over data formats. To accelerate object embedding, client applications should implement the Insert Object command.

Note:	Paste Special... and Insert Object... are optional but recommended. You should have a good reason to omit them. Paste Links is optional if the preferred Paste Special... is used.

The use of Copy and Paste is not limited to selected document fragments. Entire files may be linked or embedded into documents and displayed as double-clickable icons (that is, packages) with Copy/Paste or by using the drag and drop feature of the File Manager application for Microsoft Windows, version 3.1.

Inserting Embedded Objects with the Insert Object Command

To accelerate the procedure for embedding new objects, client applications should implement an Insert Object command. In applications that include an Insert menu, the command should appear on the Insert menu and should be called O bject. In applications that do not include an Insert menu, the command should appear on the Edit menu and should be called Insert Object. The command leads to the dialog box shown in Figure 12.

The Object Type list box in the Insert Object dialog box contains the descriptive object class names drawn from the registry. The client application must sort and display the list in alphabetical order. To embed an object, the user selects its name from the list and chooses OK. This results in the following:

A rectangle (default size is determined by the client application) immediately appears at the insertion point as an interim place holder until the new object image is available. The rectangle is masked (see Figure 18) to indicate that its server is currently open.

The server application is launched for the selected object type. The server application displays a blank or default window in which the user can create or edit the object.

Figure 12: Insert Object dialog box

If the client application fails to locate the requested server when the user selects the entry from the Insert Object dialog box or double-clicks on an object, the client application should display the error message shown in Figure 13.

Figure 13. Warning message for server application not found

While editing, the user may select the Update<Container-Document> command from the server's File menu at any time to place the current rendition of the embedded object in the client application document at the current cursor location. (This will replace the place holder if it is the first update.) After editing is complete, the user selects the Ex it & Return to <Container-Document > command from the File menu of the server. This command closes the server and returns focus to the container document. If the user does not choose the Update command for a modified embedded object before exiting, the server application displays the prompt shown in Figure 14.

Figure 14. Warning message for an embedded object

Inserting Embedded Objects with Cut, Copy, and Paste Commands

Although the Insert Object command for embedding objects is preferred, most users are familiar with the Cut, Copy, and Paste commands and will want to use these commands. The basic procedure for inserting embedded objects with Cut, Copy, and Paste is simple. For example, inserting a drawing into a text document requires the following steps:

In the drawing server application, select all or part of the drawing and choose the Copy (or Cut) command from the Edit menu.

Switch to the text client application.

In the text client application, position the cursor as desired and choose the Paste command from the Edit menu.

This procedure inserts the drawing at the current cursor location in the text document.

In general, for client applications that support OLE, the Paste command will embed the object that is on the clipboard. Under some circumstances, however, the application may choose not to embed the object. In particular, if the object is represented on the clipboard not only by the embedded object format but also by an alternate format that completely represents the original data and that the application knows how to edit, the application should insert this editable data rather than embedding the object. Most applications, however, will not be able to provide full editing capabilities for alternate formats, so they will simply embed the object and allow the source application to later function as a server.

Thus, in most client applications that support OLE, the Paste command will embed the object in the current document when the clipboard contains an object from another application. Note that in applications that do not support OLE, the Paste command simply inserts a static copy of the data without providing easy access to the tools required to edit the data.

Inserting Linked Objects with Copy and Paste Link Commands

Inserting linked objects is as easy as inserting embedded objects. To continue the example discussed in the previous section, suppose that instead of embedding the drawing, the user wanted to insert a link to the drawing. The following steps would be re quired:

In the drawing server application, select all or part of the drawing and choose the Copy command from the Edit menu. (Do not use Cut because it eliminates the source.)

Switch to the text client application.

In the text client application, position the cursor as desired and choose the Paste Link (or Paste Special) command from the Edit menu.

Note that the only difference between linking and embedding an object is the selection of Paste Link instead of Paste in the final step.

This procedure inserts a linked object to the drawing at the current cursor location in the text document. The drawing is displayed in the text document but stored in the original drawing file. The link is an "automatic" link; in other words, whenever the drawing file changes, the linked drawing in the text file is updated automatically. Automatic and manual links are described more fully in the section, Links and Link Dialogs.

Selectively Inserting Objects with the Paste Special Command

Some client applications will need only the simple methods discussed in the preceding sections for inserting linked and embedded objects. Most applications, however, may want to provide additional control with the Paste Special command.

Applications can interpret and edit data in a variety of formats. Possible formats include: rich text format (RTF), ASCII text, bitmaps, and object-oriented picture formats. These applications may provide a Paste Special command on the Edit menu to provide greater control over the format to be pasted.

By default, the standard Paste and Paste Link commands look on the clipboard for a format that completely represents the original data and that the client application can edit with its own tools. If such a format is found, the original data is translated into that format and inserted into the client. If a preferred format is not found, an image representing the original data is usually inserted. In some cases, however, the user may want to override the default format. For example, special tools or editing operations (for example, rotation, translation, applying format) might be available only for a non-default format (for example, copying the format, but not the contents, of a paragraph to another paragraph). Alternatively, the user might want to force the data to be inserted as an embedded object so that the tools of the original creator application can easily be invoked to edit the object. Client applications should support these format choices with the Paste Special dialog box shown in Figure 15.

Note:	Although not shown, a Help button may be included in the Paste Special dialog box if elaboration on data types or paste behavior is useful.

Figure 15. Paste Special dialog box

The Data Type list in the Paste Special dialog box shows the formats available on the clipboard that the client can process. The names of these formats should clearly suggest the resulting capability of the pasted information. The list also includes one additional entry, <Descriptive-Class-Name> Object (for example, Microsoft Excel Worksheet Object ). When the dialog opens, the format that would have been used if the Paste command had been selected from the Edit menu is highlighted. The dialog box contains two command buttons, Paste and Paste Link, which client applications process as follows:

The Paste button translates the data into the selected format and inserts it into the document without establishing a link to the original source of the data. (If the user does not change the default format that is originally selected in the list, pressing Paste in this dialog is equivalent to choosing Paste from the Edit menu.) If the user selects <Descriptive Class-Name > Object instead of a data format, the data is not translated into a native format, but is instead inserted as an embedded object.

Like Paste, the Paste Link button translates the data into the selected format and inserts it into the document. (If a particular data type cannot support a link, the Paste Link button is dimmed.) Unlike Paste, however, Paste Link establishes an automa tic link to the original source of the data. Because the Paste Special dialog provides a superset of the functionality provided by the Paste Link command, applications that include Paste Special need not include Paste Link. The Paste Link button should be dimmed only when the clipboard does not contain an object link format. Paste linking <Descriptive-Class-Name> Object behaves like any other link, that is, it inserts a facade into the container document along with a reference to the source file.

Copying Linked Objects

When a linked object exists in one client document, it can be insert ed in other documents with Copy and Paste (but not Paste Link). For example, suppose that CLIENT1.DOC (see Figure 16 ) contains Link1, which refers to a bitmap in a graphics file. If Link1 is selected, the Copy command copies Link1, not the bitmap that is the source object. The Paste command then inserts a copy of Link1 (CopyOfLink1) at the current cursor location (CL IENT3.DOC). Like Link1, CopyOfLink1 refers to the original bitmap. If Paste Link is used instead of Paste, a link to (not a cop y of) Link1 is inserted (CLIENT2.DOC). This new link (LinkToLink1) refers to Link1, which in turn refers to the original bitmap. Link1, CopyOfLink1, and LinkToLink1 all yield exactly the same visual presentation (a representation of the original bitmap) in their client documents, but Link1 and CopyOfLink1 refer directly to the bitmap, whereas LinkToLink1 refers to the bitmap only indirectly, through Link1.

Figure 16. Transferring links: Paste vs. Paste Link.index Transferring Links\\:Paste vs. Paste Link

Just as linked objects can be copied from one location to another with Copy and Paste, they can also be moved with Cut and Paste. In this respect, linked objects behave like all other objects that can be manipulated from the clipboard.


Viewing Objects

Compound documents may contain several OLE objects interspersed with objects that are native to the document. Because OLE objects support operations diffe rent from those supported by the native objects, it is convenient to be able to visually distinguish the two. For this purpose, client applications should provide visual indications of OLE object boundaries. The boundaries for a particular object should appear whenever the object is selected. In addition, client applications should provide a way for all object boundaries to be turned on or off at once, to facilitate easy viewing of all OLE objects in a document. For example, applications can reveal ob ject boundaries and other normally hidden information with a Hidden Structure command on the View menu or a Show All check box in an Options dialog.

Figure 17 shows recommended boundaries for linked and embedded objects.

Figure 17. Recommended boundaries for linked and embedded objects

In addition, when an embedded or packaged object is open in the server application, its appearance should be masked in the container document. The masking applies to objects whose representation is an icon (like sound). There is no masking for open linked objects.

Figure 18 shows recommended visuals for the inactive, selected, and open (embedded or packaged objects only) states of an object.

Figure 18. Visual appearance recommendations


Activating Objects

When OLE objects are inserted into a document, the standard user interface provides two methods for editing the objects: by double-clicking and through the Edit menu <Descriptive-Class-Name> Object command.

Double-Clicking

Double-clicking on the object boundary invokes the server application associated with the object. If the object is unitary (that is, if only the whole object can be selected in the container document) the user can double-click anywhere on the object to invoke the server application. The double-click starts the server application and invokes the primary verb for that object.

Note:	Instead of double-clicking, the client application may implement a method of selecting an object and pressing ENTER to activate an object. However, Selection + ENTER should not be implemented in a single- or multiple-edit line because, by default, this should replace the selection with a carriage return and line feed. You can also activate the object by selecting it and using the <Class> Object command. Sometimes the primary verb is not Edit. Instead, it is an activate-type verb such as Run (for a script), Play (for a voice note), and so on. The distinction between primary and secondary verbs in described later in the section, "The < Descriptive-Class-Name> Object Command."

If the server is an SDI server, OLE starts a new instance of the server, even if one is already running. This tight connection between the new instance and the current object helps promote the impression that the object is an integral part of the document in which it is displayed.

There are three exceptions to the rule that OLE should start a new instance of the server application to edit an object. No new instance is necessary in the following cases:

1	The object is already open in an existing instance of the server. In this case, OLE instructs the existing instance to surface.

2	The server application is an MDI application and is the same as the client application (that is, the editor for the object is the client itself). The appropriate behavior depends on whether the link is external or internal.

External links: For example, suppose that a Microsoft Word document contains a link to another Word document. In this case, double clicking on the linked object should not start a new instance of Word. Instead, if a document window for the source document is already open within the current instance (case 1 above), that document window should be surfaced. Otherwise, a new document window should be opened for it within the current instance of Word.

Internal links: If the link refers to another part of the same document, double clicking on the linked object should scroll to show the source of the link.

3	If the server is an MDI application that does not use memory efficiently when multiple instances are running, it should make an intelligent decision about what to do. For example, the application can check available memory to see whether running one more instance is likely to cause problems. If so, the application can issue a warning and/or offer the user a choice between starting a new instance or loading the file into an existing instance.

The <Descriptive-Class-Name> Object Command

If an object supports only one verb, it appears as <Verb-0> <Descriptive-Class-Name > Object on the Edit menu. If an object supports multiple verbs, they appear within a cascading menu; selecting <Descriptive-Class-Name> Object from the Edit menu displays a submenu for <Verb-0>, <Verb-1 >, and so on. Scripts, videos, and voice notes are examples of objects that may support multiple verbs such as play, edit, and rewind. When such an object plays, if possible, it should provide a way for the user to interrupt playing and start editing. For example, a voice note could display a control panel with buttons for stop and rewind.

Client applications should change the commands dynamically in the menus to reflect object class-specific verb names retrieved from the registry. The menus must access the verbs from the database; no fixed commands should be used. These verbs should be registered as mixed-case strings and follow the general style of menu commands described in The Windows Interface: An Application Design Guide which is part of the Microsoft Windows Software Development Kit for Microsoft Windows, version 3.1. Client applications sh ould assign each registered verb an accelerator key (underlined letter) for keyboard access. Also note that each verb should be a single word to ensure that the status bar messages and menus in the client application (described later) will read correctly .

If a selection contains multiple objects of the same class or of different classes, the object verbs should not be available to the user. The object verbs should appear only when there is exactly one object in the current selection; no attempt should be made to join verbs of multiple objects in a selection.

Note:	Verbs are not displayed even if the selection contains objects of the same class, because applying a verb concurrently to the whole set would have ambiguous results.

The most frequent operation for an object should be registered as its primary verb (<Verb-0 >). Mouse users can invoke the primary verb through double-clicking; keyboard users can invoke the primary verb by selecting the object and pressing ENTER. Selection+ENTER need not b e implemented in a single- or multiple-edit line because, by default, this should replace the selection with a carriage return and a line feed. In this case, a user can activate the object by using the <Class> Object command.

Figure 19 shows an example of a <Descriptive-Class-Name> Object submenu that leads to dynamic, object-specific menu items. The primary verb is accessed by the first (topmost) item, followed by subsequent verbs in order.

Figure 19. <Descriptive-Class-Name> Object command with object-specific verbs

For packages (which are always embedded, never linked), the primary verb is the primary verb of the object inside the package; the primary menu item name is Activate Contents. This means that the mouse user can invoke the primary verb of the object inside the package by double-clicking on the package icon.

The secondary verb for a package is Edit Package. Selecting this verb invokes the Packager. Some objects (for example, text objects) have no secondary verb. For such objects, the < Descriptive-Class-Name> Object command does not lead to a cascading menu; the command simply executes the primary verb. The verb is prepended to the menu item: <Verb> <Descriptive-Class-Name > Object. For example, if the object is a Word document, the menu item is Edit Word Document Object.

Busy and Unavailable Server Applications

A server application may be busy or unavailable for several reasons. For example, it may be busy printing, it may be waiting for user input to a modeless error message, or it may have been accidentally deleted from the workstation. If the server is not available, the client application should display the warning message shown in Figure 20. The recommended time between the first request and displaying the dialog box is two to three seconds.

Figure 20. Server application busy warning message

Three different cases can cause the warning message in Figure 20 to be displayed: Busy, Blocked, and OLE_BUSY. The following table describes the behavior of the buttons in each case.

Server State	Caused By	If Switch To... Button Pushed	If Cancel Button Pushed
Busy	Client receives OLE_QUERY_RETRY callback notification	Invokes Task Manager	The OLE operation is discontinued. The dialog is dismissed.
Blocked	Client timed out before getting OLE_RELEASE	Invokes Task Manager	The OLE operation will continue. The dialog is dismissed.
OLE_BUSY	OLE libraries returned OLE_BUSY from an API call	Invokes Task Manager	The previous OLE operation will continue. The dialog is dismissed.


Editing Objects

When the server window opens, the object is loaded into the window. For embedded objects, the window is initially sized to show only the portion of the object that was displayed in the client application. The user can resize the window to display additional portions of the embedded object.

Note:	Some embedded objects (such as spreadsheets) may include portions that are not displayed. These hidden portions are included only if the displayed portion draws data from them.

In the case of linked objects, the entire linked file is loaded, and the linked portion is selected. If possible, the server display should not come up maximized and should obscure as little of the object in the container document as possible.

The user can modify the object with the editing tools provided by the server application. The process for updating the object in the container file varies depending on whether the server supports the single document interface (SDI) or the multiple document interface (MDI).

Updating Objects from SDI Server Applications

Use the following guidelines for updating objects from SDI server applications.

The Update Command

When an SDI application functions as a server for an embedded object, the Save command on the File menu changes to Update, as previously shown in Figure 10. (This change occurs only for embedded objects, not for linked objects.) The Update command updates the object in the container document, but (like Save) does not close the server; the server is left open to allow the user to make further changes after seeing the effects (for example, repagination) of the update in the client. If the user tries to exit the server without updating the object, the server displays the warning message shown in Figure 13.

The Save Copy As, File New, and Open Commands

When editing an embedded object, the user can choose the Save Copy As command from the File menu to save a copy of the embedded object in a separate file. Save Copy As does not sever the connection with the client application. The inclusion of the New o r Open commands in the File menu is not recommended for SDI applications. These commands should be replaced by the Import command, which allows the user to load an existing file (object) into the server application without severing the connection between the server and the client application.

If an SDI application breaks the connection to the client by implementing the File New and File Open commands, the server should display the warning shown in Figure 21.

Figure 21. Warning message when terminating OLE connection with modified object

Closing a Server or a Client Application

When the server application closes, the focus returns to the client application. If the user closes a client application while server applications for that client are still open, the usual client application save confirmation appears. (The container document is considered modified as soon as any object is opened.) If the user chooses to save the container document, all objects are updated without prompting before the file is actually saved. Declining to save the file will likewise discard a ny modifications made to the objects.

Updating Objects from MDI Server Applications

The procedure for editing and updating objects from MDI server applications is similar to the procedure for SDI server applications, with the following exceptions:

If the focus changes from the embedded object window to a "normal" document window (that is, a window containing an existing file or a new document), the File menu reflects that of a client (see Figure 10 ). If the embedded object window regains focus, File menu reflects that of a server again.

When the user chooses the File New or File Open command, the window containing the embedded object remains open. Therefore, it is not necessary to display any warning messages about updating the object.

When the user chooses the File Save As command, the server application informs the client application (via the OLE DLLs) and the link follows the newly saved file.

Operations in Clients with Open OLE Objects

Use the following operations for client applications containing OLE objects that are currently open.

Save Command

When the user saves the container document with the Save command on the File menu, the client application updates all open objects in the container document before saving the document. The server application remains open.

Delete Command

Deleting a selection destroys objects (whether or not they are open) just as it destroys native data. OLE requests server applications of deleted objects to close silently. The client application should request an update from the server before deletion so that the user can get the latest updates in the case of an undo operation.

Close (Exit) Command

The case of closing a client application that contains an open object was discussed earlier in the section "Closing a Server or a Client Application."

Cut and Copy Commands

When the user chooses the Cut or Copy command, OLE silently updates open objects and the updated versions will be carried to the clipboard. Copying open objects leaves their server applications open and connected to the original object; cutting open objects closes their servers.

Paste Command

Pasting over objects (whether or not they are open) replaces them just as it replaces native data. Pasting over open objects also closes their servers. Before closing the server, the client should request an update to prevent data loss in the case that the user wants to undo the paste operation.


Links and Link Dialogs

Links are displayed references to data stored in external documents (or sometimes to data stored within the same document). Because linking relies on a dialog with source documents, an interface for maintaining and updating such links is necessary in client applications. Figure 22 shows the Links dialog box, which allows users to change the type of link updating (automatic or manual), update linked objects, cancel links, and repair broken links.

When the Links dialog first opens, the Links list shows each link contained in the document. Links contained in the current selection in the document are initially selected in the list. (Embedded objects are not shown in the list.) The list is an extended-selection list; the user can select one or several links by using SHIFT+click for range selection and CTRL+click for disjoint sele ction, as described in The Windows Interface: An Application Design Guide which is part of the Microsoft Windows Software Development Kit for Microsoft Windows, version 3.1.

Figure 22. Links dialog box

Update Option Buttons

The Links dialog box contains two Update option buttons: Automatic and Manual. When the dialog opens, these buttons reflect whether the currently selected links are automatically updated whenever the linked file changes, or whether they must be manually updated. If the selected links have different update r ules, neither button is selected. In this case, choosing one of the buttons changes all of the selected links to have the corresponding update behavior.


Link Command Buttons

At the bottom of the Links dialog box, three push buttons allow the user to update, cancel, and change the selected links.

Update Now updates all links selected in the Links list. In other words, the presentations of the linked objects in the client application are updated to reflect the current data in the linked files. Suppose that the selected links are all associated with a file called SOURCE.DOC. It is possible that the client contains other, currently unselected links associated with the same file. In this case, after the selected links are updated, the client application displays the message dialog shown in Figure 23. If the links selected originally are associated with several files and if the document contains other unselected links to those files, the message dialog is displayed once for each file.

Figure 23. Message for updating additional links to the same file

Cancel Link permanently breaks the link between the client and the server. The linked object in the container document is changed to a picture that can no longer be updated or edited with the standard OLE techniques. The picture can still be edited wit h the older Cut, Copy, and Paste techniques, but it is unlikely that the picture will retain all the data present in the original linked object. When the user presses the Cancel Link button,   the entry for the link disappears from the Links list in the Links dialog. Offering the option of changing an embedded object into a picture should be part of an application's controls (for example, using a menu or a button).

The Change Link button is   dimmed if the selection in the Links list includes multiple links that are not all linked to the same file. Otherwise, the button is active and leads to a dialog exactly like the File Open dialog, except that the title is Change Link (see Figure 24). The standard File Open dialog is described in The Windows Interface: An Application Design Guide which is part of the Microsoft Windows Software Development Kit for Microsoft Windows Version 3.1.

The Change Link dialog box allows the user to change the file to which a link refers. For example, if a linked file is renamed or moved to a new location, this dialog lets the user reconnect the link in the container document, using the new name or the new location of the linked file.

Figure 24. Change Link dialog box

When the user chooses a file and presses OK in the Change Link dialog, the client application disconnects the links that were selected in the Links list from their previous file and connected to the newly chosen file. It is possible that the previous file was also associated with other, currently unselected links in the container document. In this case, after the client application changes the selected links, the client application displays the message dialog shown in Figure 25 (this message is analogous to the one shown in Figure 23).

Figure 25. Message for changing additional links to the same file


Dialog Control Buttons

Every dialog box should have an OK button and a Cancel button:

The OK button confirms the changes that the user made in the dialog and closes the dialog.

The Cancel button discards all the changes that the user made and closes the dialog.


Link Status Entries

The link status entries in the Links list box consist of four parts: the human-readable form of the class name, the source file for the link, the item name for the link, and the status of the link.

The human readable form of the class name is the string that is registered in the registry for that object class.

The source file for the link contains the full pathname for the link. If the full path is too long to be displayed, the entry should be truncated.

The item name contains the server specific item name for the object.

The status of the link can be Automatic, Manual, or Unavailable:

An automatic link is updated automatically when it is changed in the server or when the linked object is loaded and the server is open with that object. It is also updated when the linked object is loaded and the user responds "Yes" to the Link Update Message Dialog shown in Figure 26.

A manual link is a link that the user must explicitly update through the Links dialog. The update takes place when the link is selected and the user presses the Update Link button in the Links dialog.

The link receives an unavailable status when an attempt to update the link (upon loading the file or requesting OleUpdate) fails.


Other Dialogs for Link Updating

When the user opens a file containing manual or automatic links, the client application displays a message dialog to ask the user whether to update the links (see Figure 26). If the user presses the Yes button, the client application updates all of the links. Automatic links are not updated unless the server application is open and the source of the link is loaded.

Figure 26. Link Update message dialog box

The progress indicator shown in Figure 27 may be displayed while the links are being updated. The Cancel button interrupts the update process and cancels all updating that has already been carried out.

Figure 27. Progress indicator for updating links

If some of the linked files are unavailable, the client application displays the warning dialog shown in Figure 28 . This dialog contains two buttons, OK and Links. The OK button closes the dialog without updating the links. The Links button displays the Links dialog (see Figure 22 ) with all the links listed. Unavailable linked files are marked with the word "Unavailable" in the fourth column of the list. The user can attempt to locate the unavailable files by using the Change Link dialog (see Figure 24), which is available from the Change Link command button in the Links dialog.

Figure 28. Warning message for unavailable links


Status Line Message Recommendations

If a client application uses the status line to elaborate on menu commands, the messages below can be used for OLE commands.

Menu	Command	Status Line Message
File Menu	Update	Update changes in <Container-Document>
	Save Copy As	Save a copy of <Descriptive-Class-Name> in a separate file
	Exit & Return to <Container-Document>	Exit <Server > and return to <Container-Document>
Edit Menu	Paste	Inserts clipboard contents as <Default-Data-Type>
	Paste Special	Inserts clipboard contents as a linked object, embedded object, or other format
	Paste Link	Inserts a link to <Descriptive-Class-Name> Object from < Source-Document>
	Insert Object	Inserts a new embedded object
	<Verb> <Descriptive-Class-Name> Object	None
	<Descriptive-Class-Name> Object	Apply the following commands to < Descriptive-Class-Name> Object
	<Descriptive-Class-Name> Object <Verb>	None
	Links	Allows links to be viewed, updated, opened, or canceled
Options (Preferences) Menu	Show Objects	Displays the borders around objects (toggle)
Mouse Interface	When an object is selected	Double-click to <Primary-Verb> <Descriptive-Class-Name> Object


Implementing OLE into Server Applications

This topic provides guidelines to help you add OLE server capabilities to a new or existing application. Adding OLE server capabilities is a relatively simple task, because OLE affects only a few specific parts of your application. You can write the rest of your application first and add OLE-specific functionality at any time.

To implement OLE server capabilities in an application, you must add the following parts to your application:

OLE-specific data structures and callback functions

OLE-specific instance initialization code to start up an application

OLE-specific code to exchange data between client and server applications

OLE-specific code to close a server application

This topic begins with a discussion of various kinds of OLE servers, continues with the steps needed to create an OLE server, and ends with information on how to temporarily block OLE requests when you don't want to interrupt a specific non-OLE operation.

For more information, see the following topics:

What is an OLE Server?

OLE Data Structures

Callback Functions

Starting a Server Application

Exchanging Data Between Client and Server Applications

Changing Window Titles and Menus

Saving and Updating Data

Closing a Server Application

Blocking Server Requests (optional)


What is an OLE Server?

An OLE server is any application that can perform action (typically, edit or play) on an object when the OLE libraries inform it that a user has activated an object associated with that server. When the user activates an object--typically, by double-clicking on the object--the server application starts, and the user edits or plays the object inside a window of the server application.

Some applications can be both clients and servers for linked and embedded objects--for example, Microsoft Word for Windows can act as a client or as a server for OLE objects.

Mini Servers vs. Full Servers

When creating a server application, you can choose whether to make your application a mini server or a full server.

Mini Server Applications

Mini servers are server applications that cannot run stand-alone; they can only be called from client applications. Mini-server applications have the following limitations:

They cannot open and save files independently.

They only support embedded objects.

They have a simplified user interface.

Microsoft Draw (included with Word for Windows 2.0) is a good example of a mini server. You should consider making your application a mini server when you want to provide limited functionality or you want to create a server that will work with specific kinds of client applications. Small visual object servers--such as Microsoft Draw or Microsoft WordArt--don't need to save files independently and are designed to be used in conjunction with large client applications.

Full Server Applications

Full servers are stand-alone applications that can create and edit files, independently of other applications. Full OLE servers have some or all of the following capabilities:

They can create, open, and save files.

They can link or embed objects.

They can have additional OLE specific user-interface elements.

They can be an OLE client themselves.

Microsoft Excel is a good example of such an application and has all the capabilities of a full server. Full servers usually have additional user-interface elements that change during the editing process. For example, when a full server starts editing an embedded object, menu commands may be different from the normal non-server application menu commands; see Chapter 3, "Ole User Interface.".

Choosing between a Mini Server or Full Server

If you have an existing application that can read and write files, your application should probably be a full server. If you have a large application that already exists as a stand-alone application and you want to add linking and embedding, a full server makes the most sense.

If you are creating a small application that exists primarily to provide added functionality to other applications, you may want to make it a mini server. Small utility applications make good mini servers.

SDI Servers vs. MDI Servers

A server application can be either a single-document interface (SDI) or multiple-document interface (MDI). MDI server applications optimize the workspace for a set of documents in an application.

When the server library, OLESVR32.DLL, initiates the editing of an object, it starts another instance of an SDI server application, but tells an MDI server application to simply create a new window in which to edit that object.

Registering SDI servers

An SDI OLE server application should never register itself as a single-instance server since doing so prevents the application from starting other instances of itself to edit objects. Instead, an SDI server application should register itself as a multi-instance server by specifying OLE_SERVER_MULTI when calling the OleRegisterServer function.

Registering MDI servers

An MDI server application can be either a single-instance or a multi-instance OLE server. However, an MDI server application registered as a single-instance server tends to have improved performance over MDI applications registered as multi-instance servers.


OLE Data Structures

The header file, OLE.H, contains six data structures that are of interest to an OLE server application . Three of the data structures contain single far pointers that reference corresponding VTBL structures. Each VTBL structure contains pointers to various callback functions. The following chart identifies the single-pointer structure names, the single- pointer data types, and the corresponding VTBL names:

Single-pointer name	Single-pointer data type	VTBL

OLESERVER	LPOLESERVERVTBL	OLESERVERVTBL

OLESERVERDOC	LPOLESERVERDOCVTBL	OLESERVERDOCVTBL

OLEOBJECT	LPOLEOBJECTVTBL	OLEOBJECTVTBL

The following type declarations are for the single-pointer structures (from the OLE.H include file):

typedef struct _OLESERVER {

    LPOLESERVERVTBL  lpvtbl;

} OLESERVER;

typedef struct _OLESERVERDOC {

    LPOLESERVERDOCVTBL  lpvtbl;

} OLESERVERDOC;

typedef struct _OLEOBJECT {

    LPOLEOBJECTVTBL  lpvtbl;

} OLEOBJECT;

Creating Application-Specific Data Structures

You will need to write your own application-specific wrapper data structures, keeping the OLESERVER, OLESERVERDOC, or OLEOBJECT structure as the first member, and adding any additional data required by your application. A wrapper is a structure that has another structure as one of its members.

The OLE DLLs are unaffected by the additional data, since they only handle the predefined OLESERVER, OLESERVERDOC, or OLEOBJECT data at the beginning of these structures. The OLE libraries pass these structures back to the server application as parameters to the server's callback functions; any additional data appended to the data structure can be easily accessed by the server application by casting the pointer to the application-specific wrapper structure. You can name these wrapper structures anything you like.

The following code example shows a wrapper structure that includes the OLESERVERDOC structure as its first member (as defined for the sample program SRVRDEMO.EXE in SRVRDEMO.H):

typedef struct {

    OLESERVERDOC oledoc;      // This must be the first field so that an

                              //   LPOLESERVERDOC can be cast to an DOC*.

    LHSERVERDOC  lhdoc;       // Registration handle

    DOCTYPE      doctype;     // Document type

    ATOM         aName;       // Document name

    HPALETTE     hpal;        // Handle to a logical color palette

    BYTE         rgfObjNums[cfObjNums+1];  // What object numbers have            // been used

} DOC, *DOCPTR ;

For more information about the OLE data structures, see Chapter 7, "Callback Functions and Data Structures."


Callback Functions

As mentioned in the preceding section, the first member of the OLESERVER, OLESERVERDOC, and OLEOBJECT wrapper structures must be an OLESERVER, OLESERVERDOC, or OLEOBJECT structure that points to a corresponding VTBL containing pointers to callback functions for manipulating and handling the server, server document, or object.

You will need to code each of these callbacks so that the server DLL can make mean-ingful calls into your application. Once you have code in place for the server, docu- ment, and object callback functions, you can see how OLE works by double-clicking an embedded object in a client application to start an instance of your server application, set data in an object, instruct the server application to show itself, and so on.

Callback functions are divided into three kinds of OLE manipulation. When creating your server application, you must put callback functions in the appropriate VTBL. The following table shows the server VTBLs and the callback function types for each one:

VTBL	Type of Callback Functions

OLESERVERVTBL	Fundamental server tasks (opening files, creating objects, and terminating after an editing session)

OLESERVERDOCVTBL	Document handling (saving or closing documents, setting document dimensions and color palettes)

OLEOBJECTVTBL	Manipulating objects (actions taken upon opening, showing objects, retrieving data in specified formats)

OLESERVERVTBL

The following table summarizes the set of callback functions needed to perform fundamental server tasks such as opening files, creating objects, and terminating after an editing session. The pointers to these callbacks must be defined in an OLESERVERVTBL structure.

Server Callback	Description

Create	Makes a new object that will be embedded by the client application.

CreateFromTemplate	Creates a new document that is initialized with the data in a specified file.

Edit	Creates a document to be edited (data is sent from the client application).

Execute	Specifies DDE execute strings in support of the StdExecute protocol (optional use for an OLE server).

Exit	Instructs the server application to terminate if no documents are registered.

Open	Opens an existing file and prepares to edit the contents.

Release	Notifies a server application that all connections to it have closed and that it is safe to terminate.

For more information about the OLESERVERVTBL structure and its associated callback functions, see Callback Functions and Data Structures.

The following code example defines the OLESERVER Create callback, as used by the sample SRVRDEMO source file SERVER.C:

/* SrvrCreate                SERVER "Create" METHOD

 * ----------

 *

 * Create a document, allocate and initialize the OLESERVERDOC structure,

 * and associate the library's handle with it.

 * In this demo server, we also create an object for the user to edit.

 *

 * LPOLESERVER lpolesrvr          - The server structure registered by

 *                                  the application

 * LHSERVERDOC lhdoc              - The library's handle

 * LPSTR lpszClassName            - The class of document to create

 * LPSTR lpszDoc                  - The name of the document

 * LPOLESERVERDOC FAR *lplpoledoc - Indicates the server doc structure to

 *                                  be created

 *

 * RETURNS:        OLE_OK if the named document was created.

 *                 OLE_ERROR_NEW if the document could not be created.

 *

 * CUSTOMIZATION: Your application might not call CreateNewObj.

 *

 */

OLESTATUS APIENTRY SrvrCreate(LPOLESERVER lpolesrvr,

    LHSERVERDOC lhdoc, LPSTR lpszClassName,

    LPSTR lpszDoc, LPOLESERVERDOC FAR *lplpoledoc)

{

    if (!CreateNewDoc(lhdoc, lpszDoc, doctypeEmbedded))

        return OLE_ERROR_NEW;

    // Although the document has not actually been changed, the client

    // has not received any data from the server yet, so the client will

    // need to be updated.

    // Therefore, CreateNewObj sets fDocChanged to TRUE.

    CreateNewObj(TRUE);

    *lplpoledoc = (LPOLESERVERDOC) &docMain;

    EmbeddingModeOn();

    return OLE_OK;

}

OLESERVERDOCVTBL

The following table summarizes the callback functions needed to manipulate documents in OLE server applications. The pointers to these callbacks must be defined in an OLESERVERDOCVTBL structure.

Document Callback	Description

Close	Requests the server application to unconditionally close the document.

Execute	Specifies DDE execute strings.

GetObject	Requests the server application to create an OLEOBJECT structure.

Release	Notifies the server application when a revoked document has terminated conversations and must be destroyed.

Save	Instructs the server application to save the document.

SetColorScheme	Specifies the color palette preferred by the client application.

SetDocDimensions	Gives the server application the rectangle on the target device for which the object should be formatted.

SetHostNames	Sets the names that should be used for window titles.

For more information about the OLESERVERDOCVTBL structure and its associated callback functions, see Callback Functions and Data Structures.

The following code example defines the OLESERVERDOC SetHostNames callback function, as used by the sample SRVRDEMO source file DOC.C:

/* DocSetHostNames        DOCUMENT "SetHostNames" METHOD

 * ---------------

 *

 * The library uses this method to set the name of the document

 * window. All this function does is change the title bar text, although

 * it could do more if necesary.

 * This function is only called for embedded objects; linked objects

 * use their filenames for the title bar text.

 *

 * LPOLESERVERDOC lpoledoc    - The server document

 * LPSTR lpszClient           - The name of the client

 * LPSTR lpszDoc              - The client's name for the document

 *

 * RETURNS:        OLE_OK

 *

 * CUSTOMIZATION: None

 *

 */

OLESTATUS APIENTRY DocSetHostNames(LPOLESERVERDOC lpoledoc,

    LPSTR lpszClient, LPSTR lpszDoc)

{

    SetTitle (lpszDoc, TRUE);

    lstrcpy ((LPSTR) szClient, lpszClient);

    lstrcpy ((LPSTR) szClientDoc, Abbrev(lpszDoc));

    UpdateFileMenu (IDM_UPDATE);

    return OLE_OK;

}

OLEOBJECTVTBL

The following table summarizes the set of callback functions needed to manipulate objects in server applications. The pointers to these callbacks must be defined in an OLEOBJECTVTBL structure.

Object Callback	Description

DoVerb	Specifies what kind of action the server application should take when a user opens an object.

EnumFormats	Enumerates the data formats that the server is capable of providing to describe an object.

GetData	Retrieves data from the server to the client describing an object in a specified format.

QueryProtocol	Provided for compatibility only.

Release	Causes the server application to free the resources associated with the specified OLEOBJECT structure.

SetBounds	Provided for compatibility only.

SetColorScheme	Specifies the color palette to be used when the server application edits the specified object.

SetData	Stores data in an object in a specified format.

SetTargetDevice	Communicates information about the client application's target device for the object.

Show	Causes the server application to show an object.

Other optional callback functions are available; see Callback Functions and Data Structures.

The following code example defines the OLEOBJECTDoVerb callback function, as used by the sample SRVRDEMO source file OBJ.C:

/* ObjDoVerb                OBJECT "DoVerb" METHOD

 * ---------

 *

 * This method is called by the client, through the library, to either

 * PLAY, or EDIT the object.  PLAY is implemented as a beep, and

 * EDIT will bring up the server and show the object for editing.

 *

 * LPOLEOBJECT lpoleobject - The OLE object

 * WORD wVerb              - The verb acting on the object: PLAY or EDIT

 * BOOL fShow              - Should the object be shown?

 * BOOL fTakeFocus         - Should the object window get the focus?

 *

 * RETURNS:        OLE_OK

 *

 * CUSTOMIZATION: Add any more verbs your application supports.

 *                Implement verbPlay if your application supports it.

 *

 */

OLESTATUS  APIENTRY ObjDoVerb(LPOLEOBJECT lpoleobject, UINT wVerb,

    BOOL fShow, BOOL fTakeFocus)

{

    switch (wVerb) {

        case verbPlay:

            {  // The application can do whatever is appropriate

               // for the object.

                INT i;

                for (i=0; i<25;i++)

                    MessageBeep(0);

                return OLE_OK;

            }

        case verbEdit:

            if (fShow)

                return objvtbl.Show(lpoleobject, fTakeFocus);

            else

                return OLE_OK;

        default:

            // Unknown verb.

            return OLE_ERROR_DOVERB;

    }

}


Starting a Server Application

An OLE server application must do certain things every time an instance of the server application is initialized. Instance initialization takes place before the application has displayed its main window and entered the message processing loop.

Every time an instance of the server application is initialized, the server must do the following:

Register clipboard formats for Native, OwnerLink, and ObjectLink types.

Initialize VTBLs, creating instance thunks for the server, document, and object callback functions.

Initialize and register the OLESERVER structure.

Register the server application with the server DLL by calling OleRegisterServer.

Parse the command line to see if the server application is starting for a linked or embedded object.

Allocate and initialize the initial OLESERVERDOC structure (optional, only done if a filename is specified when the server application is started).

Register the initial document with OleRegisterServerDoc (optional, only if a filename is specified when the server application is started).

Note:	Before the first instance of your application can be initialized, your server application must be registered in the registry.

The registry provides a system-wide source of information about those server applications that support the OLE protocol. The database lists the names of the executable files for the OLE applications, the verbs available for the classes of objects, and whether an object-handler library exists for a given class of object. For more information about registering a server application, see Using The Registry.

Registering Clipboard Formats

Regardless of whether or not the server application actually does clipboard I/O, it must register clipboard formats for Native, OwnerLink, and ObjectLink. Register these formats with RegisterClipboardFormat and store the registered formats in globally visible variables since the application uses them for clipboard I/O and when making callback functions inside OLEOBJECT. (The GetData, SetData, and EnumFormats callback functions use these formats outside the clipboard context to exchange data with the server DLL.) For an example, see the SRVRDEMO declaration in SRVRDEMO.H:

extern OLECLIPFORMAT    cfObjectLink;

extern OLECLIPFORMAT    cfOwnerLink;

extern OLECLIPFORMAT    cfNative;

And the registration of the formats in the SRVRDEMO source file SRVRDEMO.C:

cfObjectLink = RegisterClipboardFormat("ObjectLink")

cfOwnerLink  = RegisterClipboardFormat("OwnerLink")

cfNative     = RegisterclipboardFormat("Native")

Initializing VTBL Structures and Functions

Before calling any function in the server DLL, the server application must initialize the function callback tables with the MakeProcInstance call, giving each VTBL field an instance thunk. Every field in the OLESERVERVTBL, OLESERVERDOCVTBL, and OLEOBJECTVTBL structures must be initialized.

The server application creates the callback function pointers in these structures by using the MakeProcInstance function.

Note:	If MakeProcInstance call for any VTBL fails, then the initialization fails and the application terminates; an OLE server cannot execute properly without the ability for the OLE libraries to call these callback functions.

In the following code example, from the SRVRDEMO source file SERVER.C, the InitVTbls function creates procedure instances for all of the OLE callback functions:

/* InitVTbls

* ---------

*

* Create procedure instances for all the OLE methods.

*

*

* CUSTOMIZATION: Your application might not use global variables for

*                srvrvtbl, docvtbl, and objvtbl.

*/

VOID InitVTbls (VOID)

{

    typedef LPVOID ( APIENTRY *LPVOIDPROC) (LPOLEOBJECT, LPSTR);

    // Server method table

    srvrvtbl.Create          = SrvrCreate;

    srvrvtbl.CreateFromTemplate = SrvrCreateFromTemplate;

    srvrvtbl.Edit            = SrvrEdit;

    srvrvtbl.Execute         = SrvrExecute;

    srvrvtbl.Exit            = SrvrExit;

    srvrvtbl.Open            = SrvrOpen;

    srvrvtbl.Release         = SrvrRelease;

    // Document method table

    docvtbl.Close            = DocClose;

    docvtbl.GetObject        = DocGetObject;

    docvtbl.Execute          = DocExecute;

    docvtbl.Release          = DocRelease;

    docvtbl.Save             = DocSave;

    docvtbl.SetColorScheme   = DocSetColorScheme;

    docvtbl.SetDocDimensions = DocSetDocDimensions;

    docvtbl.SetHostNames     = DocSetHostNames;

    // Object method table

    objvtbl.DoVerb           = ObjDoVerb;

    objvtbl.EnumFormats      = ObjEnumFormats;

    objvtbl.GetData          = ObjGetData;

    objvtbl.QueryProtocol    = ObjQueryProtocol;

    objvtbl.Release          = ObjRelease;

    objvtbl.SetBounds        = ObjSetBounds;

    objvtbl.SetColorScheme   = ObjSetColorScheme;

    objvtbl.SetData          = ObjSetData;

    objvtbl.SetTargetDevice  = ObjSetTargetDevice;

    objvtbl.Show             = ObjShow;

}

Initializing the OLESERVER Structure

Once your application has initialized the OLESERVERVTBL structure, it needs to initialize the OLESERVER structure, setting the LPOLESERVERVTBL to point to the OLESERVERVTBL previously initialized.

OLE server applications must unconditionally register themselves with the server DLL by calling the OleRegisterServer function. The class passed in OleRegisterServer must match the class set in the registry for the object class.

Note:	An SDI server application should never register itself as a single-instance server; doing so will prevent the application from starting other instances of itself to edit objects. Instead, an SDI server application should register itself as a multi-instance server by specifying OLE_SERVER_MULTI

for the OleRegisterServer function.

An MDI server application can be either a single-instance or a multi-instance server. MDI server applications registered as a single-instance server tend to have improved performance over MDI applications registered as multi-instance servers.

The following code example. from the SRVRDEMO source file SERVER.C, registers the SRVRDEMO.EXE program with OleRegisterServer:

/* InitServer

* ----------

*

* Initialize the server by allocating memory for it, and calling

* the OleRegisterServer method.  Requires that the server method table

* has been properly initialized.

*

* HWND hwnd      - Handle to the main window

* LPSTR lpszLine - The Windows command line

*

* RETURNS: TRUE if the memory could be allocated, and the server

*          was properly registered.

*          FALSE otherwise

*

* CUSTOMIZATION: Your application might not use a global variable

*                for srvrMain.

*

*/

BOOL InitServer (HWND hwnd, HANDLE hInst)

{

    RegServer();

    srvrMain.olesrvr.lpvtbl = &srvrvtbl;

    if (OLE_OK != OleRegisterServer(szClassName,

            (LPOLESERVER) &srvrMain, &srvrMain.lhsrvr, hInst,

            OLE_SERVER_MULTI))

        return FALSE;

    else

        return TRUE;

}

Note:	If an OLE server application is also a DDE server, the class passed to OleRegisterServer cannot be the same as the application's module (executable) name. This is because the server DLL communicates with the server application through DDE and attempts to initiate a DDE conversation with the server using the name given in OleRegisterServer. If the application uses the same name as that used for DDE, then OLE and non-OLE conversations will overlap and the libraries will not know which application initiated the DDE conversation. Typically, the OLE application name changes since other applications and users depend on the original DDE service name.

If OleRegisterServer returns OLE_OK, then the third parameter contains a pointer to a handle that gets passed to future OLESVR32.DLL calls, such as OleRegisterServerDoc. This handle needs to be stored where it will be globally accessible and at the same time associated with the OLESERVER structure. Storing it directly in the application's OLESERVER structure meets both needs.

If OleRegisterServer returns anything other than OLE_OK, the server application should fail initialization and terminate.

An error registering the application with OleRegisterServer often indicates a data problem in the registry; in this case the server application can:

Prompt the user to see if the application is properly registered in the database and/or to reinstall the application.

Use the correct API functions to reregister itself in the registry, then register with OleRegisterServer (this happens without the user's knowledge).

Parsing the Command Line

When activating a linked or embedded object for editing--for example, a user double-clicking on an object-- the client DLL starts the server application using the /Embedding command-line option.

The server application uses this option to determine whether the object has been opened directly by a user or as part of an editing session for linked and embedded objects. Server applications should check for both /Embedding and -Embedding whenever they check for the command-line options.

The /Embedding command line option determines how the server application should initialize itself when starting:

If neither /Embedding nor /Embedding filename is present, the server application should register itself by calling the OleRegisterServer function. The absence of the /Embedding flag indicates that the server was not started by a client application. If the server application normally opens an untitled document when it starts, it should call the OleRegisterServerDoc function, specifying an untitled document to register.

If the /Embedding option is present, the server application should not register the document or display a window. The absence of filename after the /Embedding flag indicates that the object is embedded, but not linked. The application should register itself with the OleRegisterServer function and then enter a message dispatch loop, waiting for callbacks from the server DLL. When the server DLL requires the server application to be visible, it will call the Show or DoVerb callback function in   the OLEOBJECTVTBL structure.

If the /Embedding filename option is present, it indicates that the object to be processed is a linked object and   filename references the linked file. In this case, the server application should register itself with OleRegisterServer, process the filename string and call the OleRegisterServerDoc function to register the document. The server application should   not create a new document or display a window. After registering the document, the application should enter a message dispatch loop, waiting for callbacks from the server DLL. When the DLL requires the server application to be visible, it will call the Show or DoVerb callback function in the OLEOBJECTVTBL structure.

For example, in the SRVRDEMO source file SRVRDEMO.C, the ProcessCmdLine function parses the command line to determine how the application was started, setting a flag to indicate whether it was opened directly by a user (the fEmbedding flag will be FALSE), or whether it is part of an editing session for linked and embedded objects. Linked objects have a filename following the /Embedded command-line option, embedded objects do not.

/* ProcessCmdLine

 * --------------

 *

 * Parses the Windows command line which was passed to WinMain.

 *

 * Case One: SrvrDemo.exe

 *   fEmbedding = FALSE

 *   Create an untitled document.

 *

 * Case two: SrvrDemo.exe filename

 *   fEmbedding = FALSE

 *   Create a new document from the file.

 *

 * Case three: SrvrDemo.exe -Embedding

 *   fEmbedding = TRUE

 *   Do not create or register a document.

 *   Do not show window until client requests it.

 *

 * Case four: SrvrDemo.exe -Embedding filename

 *   fEmbedding = TRUE

 *   Load file.

 *   Call OleRegisterServerDoc.

 *   Do not show window until client requests it.

 *

 *

 * LPSTR lpszLine - The Windows command line

 * int nCmdShow   - Parameter to WinMain

 * HWND hwndMain  - The application's main window

 *

 * RETURNS: TRUE  if the command line was processed correctly.

 *          FALSE if a filename was specified which did not

 *                contain a proper document.

 *

 * CUSTOMIZATION: None.

 *

 */

static BOOL ProcessCmdLine (LPSTR lpszLine, HWND hwndMain)

{

    CHAR     szBuf[cchFilenameMax];

    BOOL     fEmbedding = FALSE;  // Is "-Embedding" on the command line?

    INT      i=0;

    OFSTRUCT of;

    if (!*lpszLine) { // No filename or options, so start a fresh document.

        return CreateUntitledDoc(SW_SHOWNORMAL);

    }

    SkipBlanks(&lpszLine);

    // Check for "-Embedding" or "/Embedding" and set fEmbedding.

    if(*lpszLine == '-' || *lpszLine == '/') {

        lpszLine++;

        GetWord (&lpszLine, szBuf);

        fEmbedding = !lstrcmp(szBuf, szEmbeddingFlag);

    }

    SkipBlanks (&lpszLine);

    if (*lpszLine) {    // if there is a filename

        // Put filename into szBuf.

        GetWord (&lpszLine, szBuf);

        if (-1 == OpenFile(szBuf, &of, OF_READ | OF_EXIST)) {

            // File not found

            if (fEmbedding)

                return FALSE;

            else {

                CHAR sz[100];

                wsprintf (sz, "File %s not found.", (LPSTR) szBuf);

                ErrorBox (sz);

                return CreateUntitledDoc(SW_SHOWNORMAL);

            }

        }

        if (!CreateDocFromFile (szBuf, NULL, doctypeFromFile)) {

            // File not in proper format.

            if (fEmbedding)

                return FALSE;

            else {

                CHAR sz[100];

                wsprintf (sz, "File %s not in proper format.",

                    (LPSTR) szBuf);

                ErrorBox (sz);

                return CreateUntitledDoc(SW_SHOWNORMAL);

            }

        }

    }

    if (fEmbedding) {

        // Do not show window until told to do so by client.

        ShowWindow(hwndMain, SW_HIDE);

    }

    else {

        ShowWindow(hwndMain, SW_SHOWNORMAL);

        UpdateWindow(hwndMain);

    }

    return TRUE;

}

Initializing the OLESERVERDOC Structure (optional)

The server application needs to allocate and initialize an OLESERVERDOC structure for each document it creates. This only needs to be done only when the /Embedding filename option is specified when starting the server (see preceding example). The OLESERVERDOC structure referenced by OLESERVERDOC points to functions that save and close documents, create new objects, and modify document characteristics like dimensions and color scheme.

Registering an Initial Document (optional)

For all cases other than where /Embedding(or -Embedding) only was on the command line, the server application needs to call OleRegisterServerDoc to inform the server DLL that this instance of the server has an open document. A server application should never call OleRegisterServerDoc when it starts to edit an embedded object because the server DLL has already registered the document.

If the command line contains a filename with or without /Embedding, then there is a document name to pass to OleRegisterServerDoc; otherwise, use a string like "(Untitled)" to register a new, unnamed document. If OleRegisterServerDoc returns OLE_OK, then continue initialization. Otherwise, the server should call OleRevokeServer and fail the initialization because it cannot implement OLE without a document. (OleRevokeServer will always return OLE_OK here because there has not yet been any conversations initiated.)

In SRVRDEMO.EXE, if ProcessCmdLine determines that a new document needs to be created and registered, it calls CreateUntitledDoc, which creates and registers a new document and object by calling CreateNewDoc and CreateNewObj, respectively.

The following code examples, from the SRVRDEMO source files SRVRDEMO.C, DOC.C, and OBJ.C, show the sequence of creating and registering a new OLE document, once CreateUntitledDoc is called from ProcessCmdLine:

/* CreateUntitledDoc

 * -----------------

 *

 * Create a fresh document with one object.

 *

 * RETURNS: TRUE if successful

 *          FALSE otherwise

 *

 * CUSTOMIZATION: Re-implement

 *

 */

static BOOL CreateUntitledDoc (INT nCmdShow)

{

    if (!CreateNewDoc (NULL, "(Untitled)", doctypeNew))

        return FALSE;

    CreateNewObj (FALSE);

    ShowWindow(hwndMain, nCmdShow);

    UpdateWindow(hwndMain);

    return TRUE;

}

/* CreateNewDoc

 * ------------

 *

 * If lhdoc == NULL then we must register the new document by calling

 * OleRegisterServerDoc, which will return a new handle which will be

 * stored in docMain.lhdoc.

 * Also if lhdoc==NULL then this document is being created at the request

 * of the user, not of the client library.

 *

 * LONG lhdoc      - Document handle

 * LPSTR lpszDoc   - Title of the new document

 * DOCTYPE doctype - What type of document is being created

 *

 * RETURNS: TRUE if successful, FALSE otherwise.

 *

 * CUSTOMIZATION: Re-implement

 *

 */

BOOL CreateNewDoc(LONG lhdoc, LPSTR lpszDoc, DOCTYPE doctype)

{

    INT i;

    // Fill in the fields of the document structure.

    if (lhdoc == NULL) {

        if (OLE_OK != OleRegisterServerDoc(srvrMain.lhsrvr, lpszDoc,

            (LPOLESERVERDOC) &docMain,

            (LHSERVERDOC FAR *) &docMain.lhdoc))

        return FALSE;

    }

    else

        docMain.lhdoc = lhdoc;

    docMain.doctype      = doctype;

    docMain.oledoc.lpvtbl= &docvtbl;

    // Reset all the flags because no object numbers have been used.

    for (i=1; i <= cfObjNums; i++)

        docMain.rgfObjNums[i] = FALSE;

    fDocChanged = FALSE;

    SetTitle (lpszDoc, doctype == doctypeEmbedded);

    return TRUE;

}

/* CreateNewObj

 * ------------

 *

 * BOOL fDoc_Changed - The new value for the global variable fDocChanged.

 *                     When initializing a new document, we need to

 *                     create a new object without the creation counting

 *                     as a change to the document.

 *

 * RETURNS: A pointer to the new object

 *

 *

 * CUSTOMIZATION: Re-implement

 *                Some applications (like Server Demo) have a finite

 *                number of fixed, distinct, non-overlapping objects.

 *                Other applications allow the user to create an object

 *                from any section of the document.  For example, the

 *                user might select a portion of a bitmap from a paint

 *                program, or a few lines of text from a word processor.

 *                This latter type of application probably will not have

 *                a function like CreateNewObj.

 *

 */

LPOBJ CreateNewObj (BOOL fDoc_Changed)

{

    HANDLE hObj = NULL;

    LPOBJ  lpobj = NULL;

    // index into an array of flags indicating if that object number is

    // used.

    INT    ifObj = 0;

    if ((hObj = LocalAlloc (LMEM_MOVEABLE|LMEM_ZEROINIT, sizeof (OBJ)))

            == NULL)

        return NULL;

    if ((lpobj = (LPOBJ) LocalLock (hObj)) == NULL) {

        LocalFree (hObj);

        return NULL;

    }

    // Fill the fields in the object structure.

    // Find an unused number.

    for (ifObj = 1; ifObj <= cfObjNums; ifObj++) {

        if (docMain.rgfObjNums[ifObj] == FALSE) {

            docMain.rgfObjNums[ifObj]=TRUE;

            break;

        }

    }

    if (ifObj == cfObjNums + 1) {

    // Cannot create any more objects.

        MessageBeep(0);

        return NULL;

    }

    wsprintf (lpobj->native.szName, "Object %d", ifObj);

    lpobj->aName            = GlobalAddAtom (lpobj->native.szName);

    lpobj->hObj             = hObj;

    lpobj->oleobject.lpvtbl = &objvtbl;

    lpobj->native.idmColor  = IDM_RED;    // Default color

    lpobj->native.version   = version;

    lpobj->native.nWidth    = OBJECT_WIDTH;          // Default size

    lpobj->native.nHeight   = OBJECT_HEIGHT;

    SetHiMetricFields (lpobj);

    // Place object in a location corresponding to its number,

    // for aesthetics.

    lpobj->native.nX = (ifObj - 1) * 20;

    lpobj->native.nY = (ifObj - 1) * 20;

    if (!CreateWindow("ObjClass", "Obj",

            WS_BORDER | WS_THICKFRAME | WS_CHILD |

            WS_CLIPSIBLINGS | WS_VISIBLE,

            lpobj->native.nX,

            lpobj->native.nY,

            lpobj->native.nWidth,

            lpobj->native.nHeight,

            hwndMain,

            NULL,

            hInst,

            (LPSTR) lpobj ))

        return FALSE;

    fDocChanged = fDoc_Changed;

    return lpobj;

}


Exchanging Data Between Client and Server Applications

OLE server applications can initially pass data to the client application by using the clipboard. Unlike client applications, which implement many changes to the user interface to support OLE, the user interface does not change significantly for server applications.

OLE server applications typically implement changes to the following commands in the Edit menu:

Command	Description

Cut	Transfers data from the server application to the clipboard, deleting the data from the source document. A client application can use this data to create an embedded object.

Copy	Transfers a copy of the data from the server application to the clipboard. A client application can use this data to create an embedded object and may be able to establish a link to the source document.

Cutting and Copying Data to the Clipboard

To cut or copy data to the clipboard so that a client application can then use the data to create an embedded or linked object, the server application should:

Open the clipboard by calling the OpenClipboard  function.

Empty the clipboard of any existing data by calling the EmptyClipboard function.

Get a handle for each of the data formats and then call SetClipboardData to put the data formats on the clipboard.

Close the clipboard by calling the CloseClipboard function.

If the server application cuts data to the clipboard, it typically does not offer the ObjectLink format because the source for the data has been removed from the document. (If the server application copies data to the clipboard from an untitled document, it does not offer the ObjectLink format.)

The order in which various data formats are put on the clipboard depends on the type of data being copied to the clipboard and the capabilities of the server application. For more information on the clipboard data formats to be used and their order of placement, see Considerations for OLE Applications.

Typically, a server application puts server-specific formats, Native format, OwnerLink format, and presentation formats on the clipboard. If it can support links, the server application also puts the ObjectLink format on the clipboard. The server application must provide a presentation format (CF_METAFILEPICT, CF_ENHMETAFILE, CF_BITMAP, or CF_DIB) if it does not have an object handler (CF_ENHMETAFILE is typically used). Native data can be used as a presentation format only if the server application has an object handler that can use the Native data (for more information about object handlers, see Implementing Object Handlers).

If a server application uses a metafile as the presentation format for an object, the mapping mode for that metafile must be MM_ANISOTROPIC; otherwise, the metafile will not scale properly in the clipboard viewer and in OLE client applications. If a server application uses fonts in these metafiles, it can improve performance by using TrueType fonts. Metafiles scale better when they use TrueType fonts. In addition, TrueType fonts are device-independent, relieving your application from dealing with device-specific fonts depending on the printer in use. To use TrueType fonts exclusively, the server application should set bit 2 (04h) of the lpPitchandFamily member of the LOGFONT structure.

The following case block and code example shows how the SRVRDEMO source file OBJ.C copies and cuts data to the clipboard:

    case IDM_COPY:

    CutOrCopyObj (TRUE);

    break;

/* CutOrCopyObj

 * ------------

 *

 * Put data onto clipboard in all the formats supported.  If the

 * fOpIsCopy is TRUE, the operation is COPY, otherwise it is CUT.

 * This is important, because we cannot put the Object Link format

 * onto the clipboard if the object was cut from the document (there is

 * no longer anything to link to).

 *

 * BOOL fOpIsCopy - TRUE if the operation is COPY; FALSE if CUT

 *

 * CUSTOMIZATION: None

 *

 *

 */

VOID CutOrCopyObj (BOOL fOpIsCopy)

{

    LPOBJ       lpobj;

    HANDLE     hData;

    if (OpenClipboard (hwndMain)) {

        EmptyClipboard ();

        lpobj = SelectedObject();

        if ((hData = GetNative (lpobj)) != NULL)

            SetClipboardData(cfNative, hData);

        if ((hData = GetLink(lpobj)) != NULL)

            SetClipboardData(cfOwnerLink, hData);

        if (fOpIsCopy && docMain.doctype == doctypeFromFile) {

            // Can create a link if object exists in a file.

            if ((hData = GetLink(lpobj)) != NULL)

                SetClipboardData(cfObjectLink, hData);

        }

        if ((hData = GetEnhMetafile(lpobj)) != NULL) {

            SetClipboardData(CF_ENHMETAFILE, hData);

        }

        if ((hData = GetBitmap(lpobj)) != NULL) {

            SetClipboardData(CF_BITMAP, hData);

        }

        CloseClipboard ();

    }

}

To cut an object to the clipboard, SRVRDEMO.EXE calls CutOrCopyObj before calling RevokeObj to revoke the object. After revoking the object, the child window is destroyed (SRVRDEMO gives each object it creates its own window), and then the menus are updated with UpdateObjMenus, as detailed in the following two case statements and code examples from the OBJ.C and SRVRDEMO.C source files:

    case IDM_CUT:

        CutOrCopyObj (FALSE);

    // Fall through.

    case IDM_DELETE:

        RevokeObj(SelectedObject());

        DestroyWindow(SelectedObjectWindow());

        UpdateObjMenus();

        break;

/* RevokeObj

 * ---------

 *

 * Call OleRevokeObject because the user has destroyed the object.

 *

 * LPOBJ lpobj - The object which has been destroyed

 *

 *

 * CUSTOMIZATION: You will only need to call OleRevokeObject once if

 *                there is only one LPOLECLIENT in your OBJ structure,

 *                which there should be.

 *

 */

VOID RevokeObj (LPOBJ lpobj)

{

    INT i;

    for (i = 0; i< clpoleclient; i++) {

        if (lpobj->lpoleclient[i])

            OleRevokeObject (lpobj->lpoleclient[i]);

        else

            /*

             * if lpobj->lpoleclient[i]==NULL then there are no more

             * non-NULLs in the array.

             */

            break;

    }

}

/* UpdateObjMenus

 * ---------------

 *

 * Grey or Ungrey menu items depending on the existence of at least one

 * object in the document.

 *

 * CUSTOMIZATION: Server Demo specific

 *

 */

static VOID UpdateObjMenus (VOID)

{

    static BOOL fObjMenusEnabled = TRUE;

    BOOL        fOneObjExists; // Does at least one object exist?

    WORD        wEnable;

    HMENU       hMenu;

    fOneObjExists = (SelectedObjectWindow() != NULL);

    if (fOneObjExists == fObjMenusEnabled) {

        // Nothing has changed.

        return;

    }

    wEnable = (WORD)(fOneObjExists ? MF_ENABLED : MF_GRAYED);

    hMenu = GetMenu(hwndMain);

    EnableMenuItem(hMenu, menuposColor, MF_BYPOSITION | wEnable);

    hMenu = GetSubMenu(GetMenu(hwndMain), menuposFile);

    EnableMenuItem(hMenu, IDM_SAVE,   MF_BYCOMMAND | wEnable);

    EnableMenuItem(hMenu, IDM_SAVEAS, MF_BYCOMMAND | wEnable);

    hMenu = GetSubMenu(GetMenu(hwndMain), menuposEdit);

    EnableMenuItem(hMenu, IDM_CUT,     MF_BYCOMMAND | wEnable);

    EnableMenuItem(hMenu, IDM_COPY,    MF_BYCOMMAND | wEnable);

    EnableMenuItem(hMenu, IDM_DELETE,  MF_BYCOMMAND | wEnable);

    hMenu = GetSubMenu(GetMenu(hwndMain), menuposObject);

    EnableMenuItem(hMenu, IDM_NEXTOBJ, MF_BYCOMMAND | wEnable);

    DrawMenuBar (hwndMain);

    fObjMenusEnabled = fOneObjExists;

}


Changing Window Titles and Menus

User interface standards for a server application only affect the window's title bar and one or two of its menus and a message box. For more information about UI standards for OLE, see OLE User Interface.

All UI changes affect a server application started for embedding; when a server application is opened for linking it appears just as if it were started as a stand-alone application. In the linking mode, the application needs to implement OLE calls when it saves and changes documents, and when it informs the client application of these actions.

Changing the Window Title

Most full server applications that are able to open files display the name of the file somewhere in their title bar. For example, the Windows 3.1 Paintbrush application displays the filename of the currently loaded bitmap; otherwise, it uses the filename"(Untitled)."

The standard for filenames in the title bar of any application is:

<Application Name> - <Filename>

as shown in the following example for Paintbrush, if a bitmap with the filename CHESS.BMP were loaded:

Paintbrush - CHESS.BMP.

When a server is started for embedding, and only for embedding, the title bar should appear as:

<Application Name> - <Object Type> in <Client Document>

Embedded objects do not have filenames. The following title bar shows Paintbrush is editing an embedded object:

Paintbrush - Paintbrush Picture in CLIENT.DOC

The SRVRDEMO source file DOC.C uses the OLESERVERDOC SetHostNames callback function to set the window title bar, using SetTitle (SERVER.C) and UpdateFileMenu (SRVRDEMO.C):

/* DocSetHostNames        DOCUMENT "SetHostNames" METHOD

 * ---------------

 *

 * The library uses this method to set the name of the document

 * window.

 * All this function does is change the title bar text, although it could

 * do more if necesary.

 * This function is only called for embedded objects; linked objects

 * use their filenames for the title bar text.

 *

 * LPOLESERVERDOC lpoledoc    - The server document

 * LPSTR lpszClient           - The name of the client

 * LPSTR lpszDoc              - The client's name for the document

 *

 * RETURNS:        OLE_OK

 *

 * CUSTOMIZATION: None

 *

 */

OLESTATUS  APIENTRY DocSetHostNames(LPOLESERVERDOC lpoledoc,

    LPSTR lpszClient, LPSTR lpszDoc)

{

    SetTitle (lpszDoc, TRUE);

    lstrcpy ((LPSTR) szClient, lpszClient);

    lstrcpy ((LPSTR) szClientDoc, Abbrev(lpszDoc));

    UpdateFileMenu (IDM_UPDATE);

    return OLE_OK;

}

/* SetTitle

 * --------

 *

 * Sets the main window's title bar. The format of the title bar is as

 * follows:

 *

 * If embedded

 *        <Server App name> - <object type> in <client doc name>

 *

 *      Example:  "Server Demo - SrvrDemo Shape in OLECLI.DOC"

 *                where OLECLI.DOC is a Winword document

 *

 * otherwise

 *        <Server App name> - <server document name>

 *

 *      Example:  "Server Demo - OLESVR.SD"

 *                where OLESVR.SD is a Server demo document

 *

 * LPSTR lpszDoc    - document name

 * BOOL  fEmbedded  - If TRUE embedded document, else normal document

 *

 * RETURNS: OLE_OK

 *

 *

 * CUSTOMIZATION: Your application may store the document's name

 *                somewhere other than docMain.aName.  Other than that,

 *                you may find this a useful utility function as is.

 *

 */

VOID SetTitle (LPSTR lpszDoc, BOOL fEmbedded)

{

    CHAR szBuf[cchFilenameMax];

    if (lpszDoc && lpszDoc[0]) {

        // Change document name.

        if (docMain.aName)

            GlobalDeleteAtom (docMain.aName);

        docMain.aName = GlobalAddAtom (lpszDoc);

    }

    if (fEmbedded) {

        if (lpszDoc && lpszDoc[0]) {

            wsprintf (szBuf, "%s - SrvrDemo Shape in %s",

                (LPSTR) szAppName, Abbrev (lpszDoc));

        }

        else {

            // Use name from docMain

            CHAR szDoc [cchFilenameMax];

            GlobalGetAtomName (docMain.aName, szDoc, cchFilenameMax);

            wsprintf (szBuf, "%s - SrvrDemo Shape in %s",

                (LPSTR) szAppName, Abbrev (szDoc));

        }

        SetWindowText (hwndMain, (LPSTR)szBuf);

    }

    else if (lpszDoc && lpszDoc[0]) {

        wsprintf (szBuf, "%s - %s", (LPSTR) szAppName, Abbrev(lpszDoc));

        SetWindowText (hwndMain, szBuf);

    }

}

/* UpdateFileMenu

 * --------------

 *

 * Updates the "Update <Client doc>" and "Exit & Return to <Client doc>"

 * with the currently set client document name

 *

 * CUSTOMIZATION: Re-implement

 *

 */

VOID UpdateFileMenu (INT iSaveUpdateId)

{

    CHAR    str[cchFilenameMax];

    HMENU   hMenu = GetMenu(hwndMain);

    /*

     * Change File menu so it contains "Update" instead of "Save".

     */

    lstrcpy (str, "&Update ");

    lstrcat (str, szClientDoc);

    ModifyMenu(hMenu, iSaveUpdateId, MF_BYCOMMAND|MF_STRING,

        IDM_UPDATE, str);

    /*

     * Change File menu so it contains "Exit & Return to <client doc>"

     * instead of just "Exit"

     */

    lstrcpy (str, "E&xit && Return to ");

    lstrcat (str, szClientDoc);

    ModifyMenu(hMenu, IDM_EXIT, MF_BYCOMMAND|MF_STRING, IDM_EXIT, str);

}

Changing the File Menu for Embedded Objects

Like the changes to the window title bar, changes to the File menu are quite easy to implement; the File menu need only change in three places (using the ModifyMenu API) when the server application starts editing an embedded object.

Change the "Save" command to "Update <Client Document>." The "<Client Document>" string is the name given in the OLESERVERDOC SetHostNames callback function.

Change the "Save As..." command to "Save Copy As..."

Change the "Exit" command to "Exit & Return to <Client Document>."

When the focus in an MDI server application changes from a window that had activated an embedded object to a window that is editing a document that does not contain an embedded object, the File menu's "Update" command should change back to "Save" and the "Save Copy As..." command should change back to "Save As..." For an MDI server application, the changes to the File menu should only be made when the active document is editing an embedded object.

SRVRDEMO.EXE makes these menu changes using the UpdateFileMenu function shown in the preceding code example.


Saving and Updating Data

When a server application carries out the File New, File Open, File Save As, and File Save/Update commands, it must inform the server DLL about what is happening to its documents.

In an MDI server application, the New or Open command s do not affect the window containing an embedded object as they simply create a new window. This eliminates the need to prompt the user to update the object. The user can continue to work with the server application after choosing one of these commands ; however, when the user closes the server application, the focus does not necessarily return to the client application.

In an SDI server application, the File New and File Open commands break the link between the client application and the document in the server application. In this case, the server application should display a message asking the user whether to update the object in the container document. If the user chooses the Save As command, the server should call the OleRenameServerDoc function. If the user responds to the message by choosing to save changes to the object before renaming the document, the server should call OleSavedServerDoc before calling OleRenameServerDoc.

For embedded objects, choosing the Save As command causes the connection with the client application to be broken, because this command reassociates a document in memory with the specified new file. For linked objects, calling OleRenameServerDoc when the user chooses the Save As command allows the client application to associate the link with the new file.

Tracking Document Changes

Most server applications maintain a flag that records whether changes have been made to each open document of a particular instance. The following table shows the rules that apply to this flag when a server application edits an embedded object.

Flag	Condition

TRUE	DLL calls the Create function in OLESERVERVTBL.

TRUE	DLL calls the CreateFromTemplate function in OLESERVERVTBL.

TRUE	Document is changed in the server application.

FALSE	DLL calls the Edit function in OLESERVERVTBL.

FALSE	DLL calls the GetData function in OLEOBJECTVTBL with the Native data format. (The flag should not change for any other formats.)

By following these rules, a server application can ensure that this flag is TRUE when the document it is editing matches the embedded object in the client application and that, otherwise, this flag is FALSE.

A server application following these rules displays a message asking whether to update the object whenever it destroys a document that contains an embedded object and the dirty flag is TRUE.

The File menu commands are generally those that need to watch this flag in order to prompt the user to save changes.

Notifying Users of Changes

OLE User Interface defines standard message boxes for informing a user that an embedded object has changed. For a linked object, the application should use the message box it already has for informing users of similar kinds of changes.

As previously noted, some of the File menu commands break the connection between the client application and server application editing an embedded object. Before carrying out any operation that may break the connection, your server application should display a different message box in lieu of the message box given for closing.

Notifying the Client Application

A server application can call the OleSavedServerDoc function whenever an object needs to be updated in the client application's document, including when the server application closes the document. If the server application closes the document and the object should be updated, it should send an OLE_CLOSED notification to the client application's CallBack function. Client applications receive the OLE_CLOSED notification for embedded objects but not for linked objects.

File New(for an SDI server application) and File Close/Exit may require the server application to notify the client application if the client application doesn't accept updates of changes through OleSavedServerDoc. Calls like OleSavedServerDoc generally handle these client notifications automatically. The cases where the server application must directly send a notification code to CallBack are:

Notification Code	Condition

OLE_CHANGED	Any operation that changes the object, making it "dirty." Not necessary for embedded objects.

OLE_CLOSED When	the user closes a document with embedded objects that require updating (that is, changed objects), before calling OleRevokeServerDoc.

The OLE_CHANGED notification allows the client application to dynamically update the object as the user changes it in the server application.

File New and File Open

File New and File Open follow the same sequence of steps, since File Open is really File New with the extra step of loading the contents of a file. The steps are:

Allocate, initialize, and register a new document with OleRegisterServerDoc.

For File Open, load the file as necessary.

An SDI server application that was performing embedding when the user chooses File New must reconfigure itself to appear as a stand-alone server application by changing the title bar and menu back to the stand-alone interface. The new filename should appear in the title bar and the File menu should contain the standard "Save," "Exit," and "Save As..." commands in place of "Update <Client Document>," "Save Copy As...," and "Exit & Return to <Client Document>."

At this point, the server application operates as a stand-alone application, in which case you'll want it to reset any global flags that track whether or not it was started through OLE and whether it is linking or embedding.

Implementing the File New command

The following case block (from SRVRDEMO.C) and code examples show how SRVRDEMO.EXE performs the File New command by using SaveChangesOption (from DOC.C), SendDocMsg (from DOC.C), SelectedObjectWindow (from SRVRDEMO.C), SendObjMsg (OBJ.C), RevokeDoc (from DOC.C), CreateNewDoc (from DOC.C), SetTitle (from SERVER.C), CreateNewObj (from OBJ.C), and EmbeddingModeOff (from SRVRDEMO.C):

    case IDM_NEW:

        {

            BOOL fUpdateLater;

            OLESTATUS olestatus;

            if (SaveChangesOption (&fUpdateLater) == IDCANCEL)

                break;

            else if (fUpdateLater)

                SendDocMsg (OLE_CLOSED);

            // We want to revoke the doc but not the server, so if

            // SrvrRelease is called, do not revoke server.

            fRevokeSrvrOnSrvrRelease = FALSE;

            if ((olestatus = RevokeDoc()) > OLE_WAIT_FOR_RELEASE) {

                ErrorBox ("Serious Error: Cannot revoke document.");

                break;

            }

            else if (olestatus == OLE_WAIT_FOR_RELEASE)

                Wait (&fWaitingForDocRelease);

            fRevokeSrvrOnSrvrRelease = TRUE;

            if (!CreateNewDoc (NULL, "(Untitled)", doctypeNew)) {

                ErrorBox ("Serious Error: Cannot create new document.");

                break;

            }

            // Your application need not create a default object.

            CreateNewObj (FALSE);

            EmbeddingModeOff();

            break;

        }

/* SaveChangesOption

 * -----------------

 *

 * Give the user the opportunity to save changes to the current document

 * before continuing.

 *

 * BOOL *pfUpdateLater - Will be set to TRUE if the client does not

 *                       accept the update and needs to be updated when

 *                       the document is closed. In that case,

 *                       OLE_CLOSED will be sent.

 *

 * RETURNS: IDYES, IDNO, or IDCANCEL

 *

 * CUSTOMIZATION: None

 *

 */

INT SaveChangesOption (BOOL *pfUpdateLater)

{

    INT  nReply;

    CHAR szBuf[cchFilenameMax];

    *pfUpdateLater = FALSE;

    if (fDocChanged) {

        CHAR szTmp[cchFilenameMax];

        if (docMain.aName)

            GlobalGetAtomName (docMain.aName, szTmp, cchFilenameMax);

        else

            szTmp[0] = NULL;

        if (docMain.doctype == doctypeEmbedded)

            wsprintf (szBuf, "The object has been changed.\\n\\nUpdate

            %s before closing the object?", Abbrev (szTmp));

        else

            lstrcpy (szBuf, (LPSTR) "Save changes?");

        nReply = MessageBox (hwndMain, szBuf, szAppName,

            MB_ICONEXCLAMATION | MB_YESNOCANCEL);

        switch (nReply) {

            case IDYES:

                if (docMain.doctype != doctypeEmbedded)

                    SaveDoc();

                else

                    switch (OleSavedServerDoc (docMain.lhdoc)) {

                        case OLE_ERROR_CANT_UPDATE_CLIENT:

                            *pfUpdateLater = TRUE;

                            break;

                        case OLE_OK:

                            break;

                        default:

                            ErrorBox ("Fatal Error: Cannot update.");

                    }

                return IDYES;

            case IDNO:

                return IDNO;

            case IDCANCEL:

                return IDCANCEL;

        }

    }

    return TRUE;

}

/* SendDocMsg

 * ----------

 *

 * This function sends messages to all the objects in a document when

 * the document has changed.

 *

 * WORD wMessage - The message to send

 *

 * CUSTOMIZATION: The means of enumerating all the objects in a document

 *                is application specific.

 */

VOID SendDocMsg (WORD wMessage)

{

    HWND    hwnd;

    // Get handle to first object window.

    hwnd = SelectedObjectWindow();

    // Send message to all object windows.

    while (hwnd) {

        SendObjMsg (HwndToLpobj(hwnd), wMessage);

        hwnd = GetWindow (hwnd, GW_HWNDNEXT);

    }

}

/* SelectedObjectWindow

 * --------------------

 *

 * Return a handle to the window for the currently selected object.

 * The GetWindow calls returns a handle to the main window's first child,

 * which is the selected object's window.

 *

 * CUSTOMIZATION: Server Demo specific

 *

 */

HWND SelectedObjectWindow (VOID)

{

    return GetWindow (hwndMain, GW_CHILD);

}

/* SendObjMsg

 * ----------

 *

 * This function sends a message to a specific object.

 *

 * LPOBJ lpobj   - The object

 * WORD wMessage - The message to send

 *

 * CUSTOMIZATION: You will only need to call CallBack once if there

 *                is only one LPOLECLIENT in your OBJ structure, which

 *                there should be.

 *

 */

VOID SendObjMsg (LPOBJ lpobj, WORD wMessage)

{

    INT i;

    for (i = 0; i < clpoleclient; i++) {

        if (lpobj->lpoleclient[i]) {

            // Call the object's Callback function.

            lpobj->lpoleclient[i]->lpvtbl->CallBack

                (lpobj->lpoleclient[i], wMessage, (LPOLEOBJECT) lpobj);

        }

        else

            break;

    }

}

/* RevokeDoc

 * ---------

 *

 * Call OleRevokeServerDoc.

 * If the return value is OLE_WAIT_FOR_BUSY, then set

 * fWaitingForDocRelease and enter a message-dispatch loop until

 * fWaitingForDocRelease is reset. As long as fWaitingForDocRelease is

 * set, the user interface will be disabled so that the user will not be

 * able to manipulate the document. When the DocRelease method is called,

 * it will reset fWaitingForDocRelease, allowing RevokeDoc to free the

 * document's memory and return. This is essentially a way to make an

 * asynchronous operation synchronous.

 *

 * We need to wait until the old document is revoked before we can delete

 * its data and create a new one.

 *

 * Note that we cannot call RevokeDoc from a method because it is illegal

 * to enter a message-dispatch loop within a method.

 *

 * RETURNS: The return value of OleRevokeServerDoc.

 *

 * CUSTOMIZATION: lhdoc may need to be passed in as a parameter if your

 *                application does not have a global variable

 *                corresponding to docMain.

 *

 */

OLESTATUS RevokeDoc (VOID)

{

    OLESTATUS olestatus;

    if ((olestatus = OleRevokeServerDoc(docMain.lhdoc)) >

            OLE_WAIT_FOR_RELEASE)

        DestroyDoc();

    docMain.lhdoc = NULL; // A NULL handle indicates that the document

    // has been revoked or is being revoked.

    return olestatus;

}

/* CreateNewDoc

 * ------------

 *

 * If lhdoc == NULL then we must register the new document by calling

 * OleRegisterServerDoc, which will return a new handle which will be

 * stored in docMain.lhdoc.

 * Also if lhdoc==NULL then this document is being created at the request

 * of the user, not of the client library.

 *

 * LONG lhdoc      - Document handle

 * LPSTR lpszDoc   - Title of the new document

 * DOCTYPE doctype - What type of document is being created

 *

 * RETURNS: TRUE if successful, FALSE otherwise.

 *

 * CUSTOMIZATION: Re-implement

 *

 */

BOOL CreateNewDoc (LONG lhdoc, LPSTR lpszDoc, DOCTYPE doctype)

{

    INT i;

    // Fill in the fields of the document structure.

    if (lhdoc == NULL) {

    if (OLE_OK != OleRegisterServerDoc(srvrMain.lhsrvr,

            lpszDoc,

            (LPOLESERVERDOC) &docMain,

            (LHSERVERDOC FAR *) &docMain.lhdoc))

        return FALSE;

    }

    else

        docMain.lhdoc = lhdoc;

    docMain.doctype      = doctype;

    docMain.oledoc.lpvtbl= &docvtbl;

    // Reset all the flags because no object numbers have been used.

    for (i=1; i <= cfObjNums; i++)

        docMain.rgfObjNums[i] = FALSE;

    fDocChanged = FALSE;

    SetTitle (lpszDoc, doctype == doctypeEmbedded);

    return TRUE;

}

/* SetTitle

 * --------

 *

 * Sets the main window's title bar. The format of the title bar is as

 * follows:

 *

 * If embedded

 *        <Server App name> - <object type> in <client doc name>

 *

 *      Example:  "Server Demo - SrvrDemo Shape in OLECLI.DOC"

 *                where OLECLI.DOC is a Winword document

 *

 * otherwise

 *        <Server App name> - <server document name>

 *

 *      Example:  "Server Demo - OLESVR.SD"

 *                where OLESVR.SD is a Server demo document

 *

 * LPSTR lpszDoc    - document name

 * BOOL  fEmbedded  - If TRUE embedded document, else normal document

 *

 * RETURNS: OLE_OK

 *

 *

 * CUSTOMIZATION: Your application may store the document's name

 *                somewhere other than docMain.aName.  Other than that,

 *                you may find this a useful utility function as is.

 *

 */

VOID SetTitle (LPSTR lpszDoc, BOOL fEmbedded)

{

    CHAR szBuf[cchFilenameMax];

    if (lpszDoc && lpszDoc[0]) {

        // Change document name.

        if (docMain.aName)

            GlobalDeleteAtom (docMain.aName);

        docMain.aName = GlobalAddAtom (lpszDoc);

    }

    if (fEmbedded) {

        if (lpszDoc && lpszDoc[0]) {

            wsprintf (szBuf, "%s - SrvrDemo Shape in %s",

                (LPSTR) szAppName, Abbrev (lpszDoc));

        }

        else {

            // Use name from docMain

            CHAR szDoc [cchFilenameMax];

            GlobalGetAtomName (docMain.aName, szDoc, cchFilenameMax);

            wsprintf (szBuf, "%s - SrvrDemo Shape in %s",

                (LPSTR) szAppName, Abbrev (szDoc));

        }

        SetWindowText (hwndMain, (LPSTR)szBuf);

    }

    else if (lpszDoc && lpszDoc[0]) {

        wsprintf (szBuf, "%s - %s", (LPSTR) szAppName, Abbrev(lpszDoc));

        SetWindowText (hwndMain, szBuf);

    }

}

/* CreateNewObj

 * ------------

 *

 * BOOL fDoc_Changed - The new value for the global variable fDocChanged.

 *                     When initializing a new document, we need to

 *                     create a new object without the creation counting

 *                     as a change to the document.

 *

 * RETURNS: A pointer to the new object

 *

 *

 * CUSTOMIZATION: Re-implement

 *                Some applications (like Server Demo) have a finite

 *                number of fixed, distinct, non-overlapping objects.

 *                Other applications allow the user to create an object

 *                from any section of the document.  For example, the

 *                user might select a portion of a bitmap from a paint

 *                program, or a few lines of text from a word processor.

 *                This latter type of application probably will not have

 *                a function like CreateNewObj.

 *

 */

LPOBJ CreateNewObj (BOOL fDoc_Changed)

{

    HANDLE hObj = NULL;

    LPOBJ  lpobj = NULL;

    // index into an array of flags indicating if that object

    // number is used.

    INT    ifObj = 0;

    if ((hObj = LocalAlloc(LMEM_MOVEABLE|LMEM_ZEROINIT,

            sizeof(OBJ))) == NULL)

        return NULL;

    if ((lpobj = (LPOBJ) LocalLock (hObj)) == NULL) {

        LocalFree (hObj);

        return NULL;

    }

    // Fill the fields in the object structure.

    // Find an unused number.

    for (ifObj = 1; ifObj <= cfObjNums; ifObj++) {

        if (docMain.rgfObjNums[ifObj] == FALSE) {

            docMain.rgfObjNums[ifObj]=TRUE;

            break;

        }

    }

    if (ifObj == cfObjNums + 1) {

        // Cannot create any more objects.

        MessageBeep(0);

        return NULL;

    }

    wsprintf (lpobj->native.szName, "Object %d", ifObj);

    lpobj->aName            = GlobalAddAtom (lpobj->native.szName);

    lpobj->hObj             = hObj;

    lpobj->oleobject.lpvtbl = &objvtbl;

    lpobj->native.idmColor  = IDM_RED;    // Default color

    lpobj->native.version   = version;

    lpobj->native.nWidth    = OBJECT_WIDTH;          // Default size

    lpobj->native.nHeight   = OBJECT_HEIGHT;

    SetHiMetricFields (lpobj);

    // Place object in a location corresponding to its number,

    // for aesthetics.

    lpobj->native.nX = (ifObj - 1) * 20;

    lpobj->native.nY = (ifObj - 1) * 20;

    if (!CreateWindow("ObjClass", "Obj",

            WS_BORDER | WS_THICKFRAME | WS_CHILD | WS_CLIPSIBLINGS |

            WS_VISIBLE,

            lpobj->native.nX,

            lpobj->native.nY,

            lpobj->native.nWidth,

            lpobj->native.nHeight,

            hwndMain,

            NULL,

            hInst,

            (LPSTR) lpobj ))

        return FALSE;

    fDocChanged = fDoc_Changed;

    return lpobj;

}

/* EmbeddingModeOff

 * ----------------

 *

 * Do whatever is necessary for the application to end "embedding mode."

 *

 * CUSTOMIZATION: Re-implement

 *

 */

VOID EmbeddingModeOff (VOID)

{

    HMENU hMenu = GetMenu(hwndMain);

    /* Change File menu so it contains "Save" instead of "Update". */

    ModifyMenu(hMenu, IDM_UPDATE, MF_BYCOMMAND | MF_STRING, IDM_SAVE,

        "&Save");

    /*

     * Change File menu so it contains "Exit & Return to <client doc>"

     * instead of just "Exit"

     */

    ModifyMenu(hMenu, IDM_EXIT, MF_BYCOMMAND | MF_STRING, IDM_EXIT,

        "E&xit");

    /*

     * Change File menu so it contains "Save As..." instead of "Save Copy

     * As..."

     */

    ModifyMenu(hMenu, IDM_SAVEAS, MF_BYCOMMAND|MF_STRING, IDM_SAVEAS,

        "Save As..");

    /* In non-embedded mode, the user can create new objects. */

    EnableMenuItem(hMenu, menuposObject, MF_BYPOSITION | MF_ENABLED);

    lstrcpy (szClientDoc, "Client Document");

    DrawMenuBar (hwndMain);

}

Implementing the File Open command

The following case block (from SRVRDEMO.C) and code examples show how SRVRDEMO.EXE performs the File Open command by using OpenDoc (from FILE.C) and UpdateObjMenus (from SRVRDEMO.C):

case IDM_OPEN:

OpenDoc();

UpdateObjMenus();

break;

/* OpenDoc

* -------

*

* Prompt the user for which document he wants to open

*

* RETURNS: TRUE if successful, FALSE otherwise.

*

* CUSTOMIZATION: None, except your application may or may not call

*                CreateNewObj to create a default object.

*

*/

BOOL OpenDoc (VOID)

{

    CHAR        szDoc[cchFilenameMax];

    BOOL        fUpdateLater;

    OLESTATUS   olestatus;

    if (SaveChangesOption (&fUpdateLater) == IDCANCEL)

        return FALSE;

    if (!GetFileOpenFilename (szDoc)) {

        if (fUpdateLater) {

            // The user chose the "Yes, Update" button but the

            // File Open dialog box failed for some reason

            // (perhaps the user chose Cancel).

            // Even though the user chose "Yes, Update", there is no way

            // to update a client that does not accept updates

            // except when the document is closed.

        }

        return FALSE;

    }

    if (fUpdateLater) {

        // The non-standard OLE client did not accept the update when

        // we requested it, so we are sending the client OLE_CLOSED now

        // that we are closing the document.

        SendDocMsg (OLE_CLOSED);

    }

    fRevokeSrvrOnSrvrRelease = FALSE;

    if ((olestatus = RevokeDoc()) > OLE_WAIT_FOR_RELEASE)

        return FALSE;

    else if (olestatus == OLE_WAIT_FOR_RELEASE)

        Wait(&fWaitingForDocRelease);

    fRevokeSrvrOnSrvrRelease = TRUE;

    EmbeddingModeOff();

    if (!CreateDocFromFile (szDoc, NULL, doctypeFromFile)) {

        MessageBox (hwndMain,

            "Reading from file failed.\\r\\nFile may not be in

            proper file format.",

            szAppName,

            MB_ICONEXCLAMATION | MB_OK);

        // We already revoked the document, so give the user

        // a new one to edit.

        CreateNewDoc (NULL, "(Untitled)", doctypeNew);

        CreateNewObj (FALSE);

        return FALSE;

    }

    fDocChanged = FALSE;

    return TRUE;

}

/* UpdateObjMenus

 * ---------------

 *

 * Grey or Ungrey menu items depending on the existence of at least one

 * object in the document.

 *

 * CUSTOMIZATION: Server Demo specific

 *

 */

static VOID UpdateObjMenus (VOID)

{

    static BOOL fObjMenusEnabled = TRUE;

    BOOL        fOneObjExists; // Does at least one object exist?

    WORD        wEnable;

    HMENU       hMenu;

    fOneObjExists = (SelectedObjectWindow() != NULL);

    if (fOneObjExists == fObjMenusEnabled) {

        // Nothing has changed.

        return;

    }

    wEnable = (WORD)(fOneObjExists ? MF_ENABLED : MF_GRAYED);

    hMenu = GetMenu(hwndMain);

    EnableMenuItem(hMenu, menuposColor, MF_BYPOSITION | wEnable);

    hMenu = GetSubMenu(GetMenu(hwndMain), menuposFile);

    EnableMenuItem(hMenu, IDM_SAVE,   MF_BYCOMMAND | wEnable);

    EnableMenuItem(hMenu, IDM_SAVEAS, MF_BYCOMMAND | wEnable);

    hMenu = GetSubMenu(GetMenu(hwndMain), menuposEdit);

    EnableMenuItem(hMenu, IDM_CUT,     MF_BYCOMMAND | wEnable);

    EnableMenuItem(hMenu, IDM_COPY,    MF_BYCOMMAND | wEnable);

    EnableMenuItem(hMenu, IDM_DELETE,  MF_BYCOMMAND | wEnable);

    hMenu = GetSubMenu(GetMenu(hwndMain), menuposObject);

    EnableMenuItem(hMenu, IDM_NEXTOBJ, MF_BYCOMMAND | wEnable);

    DrawMenuBar (hwndMain);

    fObjMenusEnabled = fOneObjExists;

}

File Save As

The File Save As command saves an untitled or existing file under a new name and operates differently for embedding and linking.

If the document contains an embedded object, the server application should prompt the user to update the objects before breaking the connection.

Retrieve the new filename.

Create and write the file.

Call OleSavedServerDoc , informing the server DLL that the document has been saved.

Call OleRenameServerDoc, informing the server DLL that the document has a new name.

Change the window title bar to reflect the new filename. If the object was embedded, reconfigure the user interface for a stand-alone server application.

The following code block (from SRVRDEMO.C) and code examples shows how SRVRDEMO.EXE implements the File Save As command using SaveDocAs (from FILE.C):

    case IDM_SAVEAS:

        if (!SaveDocAs ())

            break;

        if (docMain.doctype != doctypeEmbedded)

            EmbeddingModeOff();

        break;

/* SaveDocAs

 * ---------

 *

 * Prompt the user for a filename, and save the document

 * under that filename.

 *

 * RETURNS: TRUE if successful or user chose CANCEL

 *          FALSE if SaveDocIntoFile fails

 *

 * CUSTOMIZATION: None

 *

 */

BOOL SaveDocAs (VOID)

{

    CHAR szDoc[cchFilenameMax];

    CHAR szDocOld[cchFilenameMax];

    BOOL fUpdateLater = FALSE;

    // If document is embedded, give user a chance to update.

    // Save old document name in case the save fails.

    if (!GlobalGetAtomName (docMain.aName, szDocOld, cchFilenameMax))

        ErrorBox ("Fatal Error: Document name is invalid.");

    if (GetFileSaveFilename (szDoc)) {

        if (docMain.doctype == doctypeEmbedded)

            return SaveDocIntoFile(szDoc);

        if (fUpdateLater) {

            // The non-standard OLE client did not accept the update when

            // we requested it, so we are sending the client OLE_CLOSED now

            // that we are closing the document.

            SendDocMsg (OLE_CLOSED);

        }

        // Set the window title bar.

        SetTitle (szDoc, FALSE);

        OleRenameServerDoc(docMain.lhdoc, szDoc);

        if (SaveDocIntoFile(szDoc))

            return TRUE;

        else {  // Restore old name

            SetTitle (szDocOld, FALSE);

            OleRenameServerDoc(docMain.lhdoc, szDocOld);

            return FALSE;

        }

    }

    else  // user chose Cancel

        return FALSE;

    // The user chose the "Yes, Update" button but the

    // File Open dialog box failed for some reason

    // (perhaps the user chose Cancel).

    // Even though the user chose "Yes, Update", there is no way

    // to update a non-standard OLE client that does not accept

    // updates except when the document is closed.

}

File Update

Handling the File Update command is done as follows:

Call OleSavedServerDoc.

Set the 'dirty' flag to FALSE.

If the server application is running stand-alone and saves a file, it should call OleSavedServerDoc . If the client application does not accept the update of changes through the call to OleSavedServerDoc, the server application receives OLE_ERROR_UPDATE_CLIENT as an error value (for this error value, the server application should display a message box telling the user that the client application cannot update the changes until the server application terminates).

The following code shows the call to OleSavedServerDoc when the user chooses the File Update command:

    case IDM_UPDATE:

        switch (OleSavedServerDoc (docMain.lhdoc)) {

            case OLE_ERROR_CANT_UPDATE_CLIENT:

                if (!FailedUpdate(hwnd))

                    ExitApplication(TRUE);

                break;

            case OLE_OK:

                break;

            default:

                ErrorBox("Serious Error: Cannot update.");

        }

        break;


Closing a Server Application

The server DLL calls the Exit function in the OLESERVERVTBL structure when the server must quit. The DLL calls the OLESERVERVTBL Release function to inform the server application that it is safe to quit; the server does not necessarily stop when the Release function is called.

Note:	The server must exit when it is invisible and the server DLL calls Release. The only exception is when a n application supports multiple servers; in this case, an invisible server is sometimes not revocable when the DLL calls Release. If the server application has no open documents and it was started with the /Embedding  option (indicating that it was started by a client application) the server should exit when the server DLL calls the Release function. If the user explicitly loads a document into a single-instance (MDI) server, however, the server should not exit when the DLL calls Release.

The following code examples shows the OLESERVERVTBL Release callback function, which supports the closing of an invisible server application:

/* SrvrRelease                SERVER "Release" METHOD

* -----------

*

* This library calls the SrvrRelease method when it is safe to quit the

* application.  Note that the server application is not required to

* quit.

*

* srvrMain.lhsrvr != NULL indicates that SrvrRelease has been called

* because the client is no longer connected, not because the server

* called OleRevokeServer.

* Therefore, only start the revoking process if the document is of type

* doctypeEmbedded or if the server was opened for an invisible update.

*

* srvrmain.lhsrvr == NULL indicates that OleRevokeServer has already

* been called (by the server application), and srvrMain is a lame duck.

* It is safe to quit now because SrvrRelease has just been called.

*

* Note that this method may be called twice: when OleRevokeServer is

* called in StartRevokingServer, SrvrRelease is called again.

* Therefore we need to be reentrant.

*

* LPOLESERVER lpolesrvr - The server structure to release

*

* RETURNS: OLE_OK

*

* CUSTOMIZATION: None

*

*/

OLESTATUS  APIENTRY SrvrRelease (LPOLESERVER lpolesrvr)

{

    if (srvrMain.lhsrvr) {

        if (fRevokeSrvrOnSrvrRelease &&

                (docMain.doctype == doctypeEmbedded ||

                !IsWindowVisible(hwndMain)))

            StartRevokingServer();

    }

    else {

        fWaitingForSrvrRelease = FALSE;

        /*

         * Here you should free any memory that had been allocated for

         * the server.

         */

        PostQuitMessage (0);

    }

    return OLE_OK;

}

When a user closes a server application containing an embedded object without updating changes to the client application, the server should display a message box asking whether to save the changes. If the user chooses to save the changes, the server should send the OLE_CLOSED notification and call the OleRevokeServerDoc function. (Because sending OLE_CLOSED prompts the server library to send data to the client library, it is not necessary to send OLE_CHANGED or OLE_SAVED.) If the user chooses not to save the changes, the server should simply call the OleRevokeServerDoc function (without sending OLE_CLOSED).

A server can use the OleRevokeObject function to revoke a client's access to an object--for example, if the user destroys the object. Similarly, the OleRevokeServerDoc function revokes a client's access to a document. (Because OleRevokeServerDoc revokes a client's access to all objects in a document, an application that uses OleRevokeServerDoc does not need to call the OleRevokeObject function for objects in that document.) To terminate all conversations with client applications, the server application can call the OleRevokeServer function. These functions inform the server DLL that the specified items are no longer available.

A server application can receive OLE_WAIT_FOR_RELEASE--for example, the OleRevokeServerDoc function can return this value. Although a server application can enter a message-dispatch loop and wait for the server DLL to call the server's Release function, server applications should never enter message-dispatch loops inside any of the server callback functions that are called by the server DLL.

Note:	The client application will not instruct the server application to close the document or exit when the server is editing a linked object (unless the server application is updating the link without displaying the object to the user). Because a linked object exists independently of the client application, the user controls saving and closing the document by using the server application.

If a server application owns the clipboard when it terminates, it should make sure that the data on the clipboard is complete and in the correct order. For example, any Native data should also be accompanied by OwnerLink format.

SRVRDEMO.EXE handles application shutdown by generating a WM_SYSCOMMAND (in the IDM_EXIT block of SRVRDEMO.C) that is handled by DefWindowProc. DefWindowProc processes the message, translating the SC_CLOSE message into a WM_CLOSE command, which then uses SaveChangesOption (DOC.C), ExitApplication (SRVRDOC.C), and StartRevokingServer (from SERVER.C), as shown in the following two case blocks (from SRVRDEMO.C) and three code examples:

    case IDM_EXIT:

        SendMessage(hwnd, WM_SYSCOMMAND, SC_CLOSE, 0L);

        break;

    case WM_CLOSE:

        {

            BOOL fUpdateLater;

            if (SaveChangesOption(&fUpdateLater) != IDCANCEL)

                ExitApplication(fUpdateLater);

            break;

        }

/* SaveChangesOption

 * -----------------

 *

 * Give the user the opportunity to save changes to the current document

 * before continuing.

 *

 * BOOL *pfUpdateLater - Will be set to TRUE if the client does not

 *                       accept the update and needs to be updated when

 *                       the document is closed.  In that case,

 *                       OLE_CLOSED will be sent.

 *

 * RETURNS: IDYES, IDNO, or IDCANCEL

 *

 * CUSTOMIZATION: None

 *

 */

INT SaveChangesOption (BOOL *pfUpdateLater)

{

    INT  nReply;

    CHAR szBuf[cchFilenameMax];

    *pfUpdateLater = FALSE;

    if (fDocChanged) {

        CHAR szTmp[cchFilenameMax];

        if (docMain.aName)

            GlobalGetAtomName (docMain.aName, szTmp, cchFilenameMax);

        else

            szTmp[0] = NULL;

        if (docMain.doctype == doctypeEmbedded)

            wsprintf (szBuf, "The object has been changed.\\n\\nUpdate

            %s before closing the object?", Abbrev (szTmp));

        else

            lstrcpy (szBuf, (LPSTR) "Save changes?");

        nReply = MessageBox (hwndMain, szBuf, szAppName,

            MB_ICONEXCLAMATION | MB_YESNOCANCEL);

        switch (nReply) {

            case IDYES:

                if (docMain.doctype != doctypeEmbedded)

                    SaveDoc();

                else

                    switch (OleSavedServerDoc (docMain.lhdoc)) {

                        case OLE_ERROR_CANT_UPDATE_CLIENT:

                            *pfUpdateLater = TRUE;

                            break;

                        case OLE_OK:

                            break;

                        default:

                            ErrorBox ("Fatal Error: Cannot update.");

                    }

                    return IDYES;

            case IDNO:

                return IDNO;

            case IDCANCEL:

                return IDCANCEL;

        }

    }

    return TRUE;

}

/* ExitApplication

 * ---------------

 *

 * Handles the WM_CLOSE and WM_COMMAND/IDM_EXIT messages.

 *

 * RETURNS: TRUE if application should really terminate

 *          FALSE if not

 *

 *

 * CUSTOMIZATION: None

 *

 */

static BOOL ExitApplication (BOOL fUpdateLater)

{

    if (fUpdateLater) {

        // The non-standard OLE client did not accept the update

        // when we requested it, so we are sending the client

        // OLE_CLOSED now that we are closing the document.

        SendDocMsg (OLE_CLOSED);

    }

    if (StartRevokingServer() == OLE_WAIT_FOR_RELEASE)

        Wait (&fWaitingForSrvrRelease);

    /*

     * SrvrRelease will not necessarily post a WM_QUIT message. If the

     * document is not embedded, SrvrRelease by itself does not cause the

     * application to terminate. But now we want it to.

     */

    if (docMain.doctype != doctypeEmbedded)

        PostQuitMessage(0);

    SaveDimensions();

    return TRUE;

}

/* StartRevokingServer

 * -------------------

 *

 * Hide the window, and start to revoke the server.

 * Revoking the server will let the library close any registered

 * documents. OleRevokeServer may return OLE_WAIT_FOR_RELEASE.

 * Calling StartRevokingServer starts a chain of events that will

 * eventually lead to the application being terminated.

 *

 * RETURNS: The return value from OleRevokeServer

 *

 * CUSTOMIZATION: None

 *

 */

OLESTATUS StartRevokingServer (VOID)

{

    OLESTATUS olestatus;

    if (srvrMain.lhsrvr) {

        LHSERVER lhserver;

        // Hide the window so user can do nothing while we are waiting.

        ShowWindow (hwndMain, SW_HIDE);

        lhserver = srvrMain.lhsrvr;

        // Set lhsrvr to NULL to indicate that

        // srvrMain is a lame duck and

        // that if SrvrRelease is called,

        // then it is ok to quit the application.

        srvrMain.lhsrvr = NULL;

        olestatus = OleRevokeServer (lhserver);

    }

    else

        // The programmer should ensure that this never happens.

        ErrorBox ("Fatal Error: StartRevokingServer

        called on NULL server.");

    return olestatus;

}


Blocking Server Requests
Blocking Server Requests (optional)

Blocking Server Requests (optional)

If the server application needs to carry out a long operation and you do not want it to be interrupted by an OLE request, have the application call the OleBlockServer function, which instructs the server DLL to queue any OLE messages destined for the application. Then, when the application is ready to process these requests, call OleUnblockServer prior to GetMessage in your main message loop and in any message loop used to wait for a Release. OleUnblockServer causes all queued requests to be processed before GetMessage can retrieve the next message.

Implementing a blocking mechanism first requires that you r application maintain a global flag indicating that it is ready to unblock. When the server application wants to block, it calls OleBlockServer. When it is ready to unblock, it sets its block flag to TRUE.

In the message loops, have the application call OleUnblockServer  when the global flag is TRUE, and repeat until there are no more blocked requests, at which time the flag is set back to FALSE.

A typical case where a server would use OleBlockServer is when a modal dialog box appears. A modal dialog box has its own message-processing loop inside Windows, so any DDE messages going between the OLE libraries will cause calls to your server's callback functions. This may cause unwanted actions while a dialog box is displayed. To avoid this problem, block the server immediately before putting up a modal dialog box, thereby not allowing the server DLL to make any requests to the application until OleUnblockServer is called.

A server application can alternatively return OLE_BUSY from any function when it does not want to handle OLE requests. Unlike OleBlockServer , returning OLE_BUSY allows the server application to choose which requests to process and allows the user at the client application to decide whether to discontinue or retry the request.


Implementing OLE into Client Applications

This topic provides guidelines to help you add OLE client capabilities to a new or existing application. Because OLE client capabilities affect only a few specific parts of your application, you can write the rest of your application first and add OLE- specific functionality at any time.

To implement OLE client capabilities in an application, you must add the following OLE-specific parts to your application:

Data structures and callback functions

Initialization code to start up a client application

Code for managing documents

Code for working with objects

Code for implementing the Edit menu commands

Code for closing a client application

This topic begins with a discussion of what a client application is and how client and server applications work together, and then continues with the steps needed to create an OLE client application.

For more information, see the following topics:

What is an OLE Client?

How Client and Server Applications Communicate

OLECLI32.DLL and OLECLI32.LIB

Client Data Structures

Starting a Client Application

Managing Documents

Working with Objects

Implementing Edit commands

Closing a Client Application


What is an OLE Client?

An OLE client is an application that can display and store objects created by OLE server applications. The objects themselves can contain any kind of data.

A client application provides storage for embedded objects (including the na tive data defining the object) and a means for the user to activate the object and the server application associated with that object. Client applications also provide ways of putting embedded and linked objects into and out of a document.

Client applications must provide permanent storage for objects that are linked and embedded in a file. How the objects are stored depends on whether the object is a linked object or an embedded object. The following table summarizes the data and presentation formats that get stored along with each type of OLE object:

Linked Object Storage Embedded Object Storage

Presentation data Native data

ObjectLink format Presentation data

Ownerlink data

Client applications accommodate asynchronous operations by defining a CallBack function to which the client DLL, OLECLI32.DLL, sends notifications about current operations. As long as the client application continues to dispatch messages, it can react to the notifications being sent to the CallBack function and to input from the user. For more information about asynchronous operations, see Handling Asynchronous Operations.


How Client and Server Applications Communicate

As shown in Figure 29 , communication between a client application, a server application, an optional object handler, and the two OLE libraries, OLECLI32.DLL and OLESVR32.DLL, takes place on several different levels:

The client application calls API functions in OLECLI32.DLL.

OLECLI32.DLL sends notifications to the client through the CallBack function.

If an object handler exists, the client DLL may call the object handler's exported functions to perform various operations for an object, eliminating the need to start the server application. See Implementing Object Handlers.

Figure 29. OLE communication paths

OLECLI32.DLL and OLESVR32.DLL communicate through DDE messages.

OLESVR32.DLL calls the server application's exported callback functions to request various actions in the server application or to make changes in the document or object.

The server application calls API functions in OLESVR32.DLL.

An OLE client application in this model makes API function calls to OLECLI32.DLL and the DLL calls the CallBack function in the client application to notify it of changes. For example, when the server application changes a linked object it sends an OLE_CHANGED notification that eventually ends up in the client's CallBack function. In response to this notification, the client application repaints the object by calling the OleDraw function in OLECLI32.DLL.

Note:	Although OLECLI32.DLL uses DDE messages to communicate with OLESVR32.DLL, a client application should not depend on this fact. Future versions of the OLE libraries may not necessarily use the DDE mechanism. The OLE libraries hide the underlying mechanism beneath a set of function calls and allow the mechanism to change and improve without requiring changes to the application.

Handling Asynchronous Operations

When a client application calls a function that invokes a server application, actions taken by the client and server application can be asynchronous. For example, the actions of updating a document and closing a server application are asynchronous.

Whenever an asynchronous operation begins, the client DLL returns OLE_WAIT_FOR_RELEASE. When a client application receives this notification, it must wait for the OLE_RELEASE notification before it quits. If the client application cannot take further action until the asynchronous operation finishes, it should enter a message-dispatch loop and wait for OLE_RELEASE . Otherwise, it should allow the main message loop to continue dispatching messages so that processing can continue.

An application can run only one asynchronous operation at a time for an object; each asynchronous operation must end with the OLE_RELEASE notification before the next one begins. (The client application's CallBack function must receive OLE_RELEASE for all pending asynchronous operations before calling the OleRevokeClientDoc function.)

If an application calls a function for an object before receiving OLE_RELEASE for that object, the function may return OLE_BUSY . The server application also returns OLE_BUSY when processing a new request would interfere with the processing of a current request from a client application or user. When a function returns OLE_BUSY , the client application can display a message box reporting the busy condition at this point or it can enter a loop to wait for the function to return OLE_OK. (The OLE_QUERY_RETRY notification is also sent to the client application's CallBack function when the server application is busy; when the callback function returns FALSE, the transaction with the server application is ended.) Note that if the server application uses the OleBlockServer function to postpone OLE activities, the OLE_QUERY_RETRY notification is not sent to the client application. (For a discussion of using OleBlockServer, see Implementing OLE into Server Applications.)

The following code fragment shows a message-dispatch loop that allows a client application to transact messages while waiting for the OLE_RELEASE notification:

while ((olestat = OleQueryReleaseStatus(lpObject)) == OLE_BUSY)

{

  if (GetMessage(&msg, NULL, NULL, NULL))

  {

    TranslateMessage(&msg);

    GetMessage(&msg);

  }

}

if (olestat == OLE_ERROR_OBJECT)

{

  .

  .                         // The lpObject parameter is invalid.

  .

}

else

{                           // if olestat == OLE_OK

  .

  .                        // The object is released or the server

  .                        // has terminated.

}

A server application could end unexpectedly while a client application is waiting for OLE_RELEASE. In this case, the client DLL will recover properly only if the client application uses the OleQueryReleaseStatus function, as shown in the preceding example.

In the preceding example, the program entered a standard message dispatch loop while waiting for the asynchronous function call to complete. It is important to realize that while in the dispatch loop, the user could initiate another asynchronous operation. When this occurs, the program is recursively reentered, which has ramifications that cannot be ignored. Therefore, in the preceding approach it is necessary to program in a manner that will permit recursive reentrance.

An alternative approach is to block all user input while an asynchronous operation is in process. The following code example shows how to do this:

   while ((olestat = OleQueryReleaseStatus(lpObject)) == OLE_BUSY) {

        if (GetMessage(&msg, NULL, NULL, NULL)) {

            FilterMessage ();

        }

    }

    if (olestat == OLE_ERROR_OBJECT) {

        .

        .  /* The lpObject parameter is invalid.  */

        .

    }

    else { /* if olestat == OLE_OK */

        .

        .  /* The object is released or the server has terminated.  */

        .

    }

/*

 * FilterMessage()

 *

 * This function will put the app in a sleep state if the fIgnoreInput

 * flag is set to TRUE.  It will allow Quit, DDE,and any other non-

 * input messages to be dispatched but will prohibit the user from

 * interacting with the app.  The user can Alt-(sh)Tab, Alt-(sh)Esc,

 * and Ctrl-Esc away from the app as well use any Windows hot keys to

 * activate other apps

 */

void FilterMessage()

{

  MSG  msg;

  if (PeekMessage (&msg, 0, 0, 0, PM_REMOVE))

  {

    if ((msg.message >= WM_NCMOUSEMOVE && msg.message <=

        WM_NCMBUTTONDBLCLK)|| (msg.message >= WM_KEYFIRST &&

        msg.message <= WM_KEYLAST) || (msg.message >= WM_MOUSEFIRST &&

        msg.message <= WM_MOUSELAST))

    {

      if (!(msg.message == WM_SYSKEYDOWN && (msg.wParam == VK_TAB ||

         msg.wParam == VK_ESCAPE)) )

        return ;

    }

    TranslateMessage ((LPMSG) &msg);

    DispatchMessage ((LPMSG) &msg);

  }

}

As shown in the function FilterMessage, the approach is simple and straightforward: the client application disregards all UI messages until OleQueryReleaseStatus is not equal to OLE_BUSY. While in the message loop and calling FilterMessage, only non-UI messages are dispatched; DDE messages still get dispatched, thereby allowing the asynchronous call to complete.

While the application is processing the loop, the user will not be able to resize, minimize, maximize, or close the window because all non-client area messages are discarded. In this case, the client application should display a message to the user indicating it's busy waiting for the asynchronous function call to complete.

Note:	During an asynchronous operation, WM_CLOSE and WM_QUERYENDSESSION messages can get dispatched. Therefore, make sure that the application does not close while an asynchronous operation is in progress.

The following OLE functions can return the OLE_WAIT_FOR_RELEASE value, the OLE_BUSY value, or both to a client application:

Function	OLE_BUSY	OLE_WAIT_FOR_RELEASE

OleActivate	Yes	Yes

OleClose	Yes	Yes

OleCopyFromLink	Yes	Yes

OleCreate	No	Yes

OleCreateFromClip	No	Yes

OleCreateFromFile	No	Yes

OleCreateFromTemplate	No	Yes

OleCreateLinkFromClip	No	Yes

OleCreateLinkFromFile	No	Yes

OleDelete	Yes	Yes

OleExecute	Yes	Yes

OleLoadFromStream	No	Yes

OleObjectConvert	Yes	No

OleReconnect	Yes	Yes

OleRelease	Yes	Yes

OleRequestData	Yes	Yes

OleSetBounds	Yes	Yes

OleSetColorScheme	Yes	Yes

OleSetData	Yes	Yes

OleSetHostNames	Yes	Yes

OleSetLinkUpdateOptions	Yes	Yes

OleSetTargetDevice	Yes	Yes

OleUnlockServer	No	Yes

OleUpdate	Yes	Yes


OLECLI32.DLL and OLECLI32.LIB

OLECLI32.DLL provides services to simplify client applications. There is bi-directional communication between client applications and the DLL. A client application calls functions in OLECLI32.DLL when it needs to perform OLE tasks. Object creation, rendering, loading, and saving are some of the services that OLECLI32.DLL provides to the application.

The client DLL sends status information back to the client application by calling an application-defined callback function: CallBack. The DLL passes notification codes to the CallBack function to tell it when an object is changed, renamed, saved, or closed by a server application.

To use the client DLL, a client application must:

Include OLE.H in any source files that reference OLE API functions or data structures.

Link the source file(s) with OLECLI32.LIB.

In all, the client DLL exports 55 functions for use by client applications. These functions are summarized in the following sections; for more detailed information on these functions, see The OLE Client DLL.

Document Management Functions

The following functions manipulate documents in an OLE client application:

Function	Description

OleRegisterClientDoc	Registers a client document.

OleRevokeClientDoc	Informs the client DLL that a registered document was closed.

Object Creation and Destruction Functions

The following functions support adding/removing objects within a container document:

Function	Description

OleClone	Creates an exact copy of another object.

OleCopyFromLink	Creates an embedded object copy of a linked object.

OleCreate	Creates an embedded object of a specified class.

OleCreateFromClip	Creates an embedded object from data on the clipboard.

OleCreateFromFile	Creates an embedded object using the contents of a file.

OleCreateFromTemplate	Creates an embedded object using a file as a template.

OleCreateInvisible	Creates an embedded object without displaying server application.

OleCreateLinkFromClip	Creates a linked object from data on the clipboard.

OleCreateLinkFromFile	Creates a linked object with a link to a specified file.

OleDelete	Permanently deletes an object from a document.

OleLoadFromStream	Loads an object from a document being loaded.

OleObjectConvert	Creates a static object from an existing object.

OleRelease	Frees an object from memory.

Object Management Functions

The following functions support opening, closing, and drawing objects:

Function	Description

OleActivate	Executes an object's verb which could start the object's server application.

OleClose	Breaks the connection between an object and a server application.

OleCopyToClipboard	Places a copy of an object on the clipboard.

OleDraw	Draws an object onto any device context.

OleEnumObjects	Enumerates the objects in a document.

OleEqual	Compares two objects for equality.

OleExecute	Sends DDE Execute messages to an object's server application.

OleReconnect	Reconnects a linked object to a server after OleClose.

OleRename	Informs the client DLL that an object name changed.

OleSaveToStream	Saves an object to a file or other storage.

OleUpdate	Updates an object's data and display.

Object Information Retrieval Functions

The following functions are used to obtain relevant information about an object:

Function	Description

OleEnumFormats	Enumerates available data formats for an object.

OleGetData	Retrieves an object's data in a specified format.

OleGetLinkUpdateOptions	Determines if a linked object is automatic or manual.

OleQueryBounds	Retrieves the bounding rectangle for an object.

OleQueryCreateFromClip	Determines if OleCreateFromClip will succeed.

OleQueryLinkFromClip	Determines if OleCreateLinkFromClip will succeed.

OleQueryName	Retrieves the name of an object stored in the client DLL.

OleQueryOpen	Determines if a server is currently editing an object.

OleQueryOutOfDate	Determines whether an object is out-of-date.

OleQueryProtocol	Determines if an object supports a protocol.

OleQueryReleaseError	Determines if an error caused an object's release.

OleQueryReleaseMethod	Determines which operation released an object.

OleQueryReleaseStatus	Determines if an object is released or busy.

OleQuerySize	Retrieves the size of an object in bytes.

OleQueryType	Determines if object is linked, embedded, or static.

OleRequestData	Retrieves data from a server in a specified format.

Object Information Updating Functions

The following functions inform the client DLL of changes made to an object in the client document:

Function	Description

OleSetBounds	Informs the client DLL of the new object rectangle.

OleSetData	Changes the object's data for a specified format.

OleSetHostNames	Provides the client DLL with the object and document names.

OleSetLinkUpdateOptions	Changes a linked object between automatic and manual.

OleSetTargetDevice	Provides the client DLL with information about the output device.

Miscellaneous Functions

The following functions can be used as noted:

Function	Description

OleIsDcMeta	Identifies a metafile device context.

OleLockServer	Keeps a server in memory for updating multiple objects.

OleQueryClientVersion	Retrieves the version number of the client DLL.

OleSetColorScheme	Recommends colors for documents and objects.

OleUnlockServer	Releases a server locked with OleLockServer.


Client Data Structures

There are four data structures defined in OLE.H that are of interest to an OLE client application. Two of the data structures contain single pointers that reference corresponding VTBL structures. Each VTBL structure contains pointers to various callback functions. The following chart identifies the single pointer structure names, the single pointer data types, and the corresponding VTBL names.

Single-pointer name	Single-pointer data type	Corresponding VTBL

OLECLIENT	LPOLECLIENTVTBL	OLECLIENTVTBL

OLESTREAM	LPOLESTREAMVTBL	OLESTREAMVTBL

The following table shows the contents of each data structure, as defined in OLE.H:

Data Structure	Contents, as defined in OLE.H

OLECLIENT	A long pointer to the OLECLIENTVTBL structure.

OLECLIENTVTBL	A single far pointer to the client's notification function: CallBack.

OLESTREAM	A pointer to the OLESTREAMVTBL structure.

OLESTREAMVTBL	Far pointers to the storage stream functions, Get and Put.

OLECLIENT and OLECLIENTVTBL Structures

Shown below are the OLECLIENT and OLECLIENTVTBL data structures as defined in OLE.H. The OLECLIENT structure only contains a pointer to the OLECLIENTVTBL structure, which contains a pointer to the client application's CallBack function:

typedef struct _OLECLIENT

{

  LPOLECLIENTVTBL   lpvtbl;

} OLECLIENT;

typedef struct  _OLECLIENTVTBL

{

  int (CALLBACK *CallBack) (LPOLECLIENT, OLE_NOTIFICATION, LPOLEOBJECT)

} OLECLIENTVTBL;

typedef OLECLIENTVTBL FAR* LPOLECLIENTVTBL;

The OLECLIENT structure is allocated and initialized by the client application, and then passed to the client DLL. You will need to create your own application-specific OLECLIENT wrapper data structure, keeping the OLECLIENT data structure as the first member, and adding any additional data needed by your client application. You can name this structure anything you like.

The client DLL uses the OLECLIENTVTBL structure to locate and call the client application's CallBack function(Figure 30). The client DLL calls the CallBack function to alert the client application about important events such as when an object is closed, saved, or modified.

Figure 30. Relationship between OLECLIENT, OLECLIENTVTBL, and the client CallBack function

You can create the OLECLIENT wrapper data structure so that it can also point to data that describes the state of an object. This data, when present, is supplied and used only by the client application. Because one argument to the CallBack function is a pointer to the OLECLIENT structure, this is an efficient method of retrieving the object's state information when the CallBack function is called. As an example, consider the following code example from CLIDEMO.EXE, which defines a structure called APPITEM:

typedef struct _APPITEM *APPITEMPTR;

typedef struct _APPITEM {             // Application item

  OLECLIENT         oleclient;        // OLECLIENT pointer

  HWND              hwnd;

  LPOLEOBJECT       lpObject;         // OLE object pointers

  LPOLEOBJECT       lpObjectUndo;     // undo object

  LONG              otObject;         // OLE object type

  LONG              otObjectUndo;

  OLEOPT_UPDATE     uoObject;         // OLE object update option

  OLEOPT_UPDATE     uoObjectUndo;     // link name atom

  ATOM              aLinkName;        // Save the link's document name

  ATOM              aLinkUndo;        // Save the link's document

                                      // name

  LPSTR             lpLinkData;       // pointer to link data

  BOOL              fVisible;         // TRUE: item is to be displayed

  BOOL              fOpen;            // server open? --for undo

                                      // objects

  BOOL              fRetry;           // retry flag for busy servers

  BOOL              fNew;

  BOOL              fServerChangedBounds;

  RECT              rect;             // bounding rectangle

  LHCLIENTDOC       lhcDoc;           // client document handle

  ATOM              aServer;

} APPITEM;

Client CallBack Function

As mentioned earlier, the client DLL communicates with the client application by invoking the client application's CallBack function. The CallBack function--pointed to in the OLECLIENTVTBL structure--is responsible for handling the following notification codes passed to it in response to actions taken by the server application on an object:

Notification	Meaning	Typical Response
OLE_CLOSED	Object was closed in the server application.	If there is no presentation or native data available, delete the object.
OLE_SAVED	Object was saved in the server application. Typically received when anembedded object is updated through the Update command in the server application.	Display the object's updated presentation.
OLE_CHANGED	Object was modified in the server application. Received by linked objectwhenever a link is opened for editing and a change occurs in the server. May be received by embedded objects, when the embedded object is closed in the server and the user saves changes.	Display the object's updated presentation.
OLE_RELEASE	Object was released because an asynchronous operation completed.	Keep track of the number of objects waiting for release, decrementing the count when this notification is received.
OLE_RENAMED	Object was renamed in the server application. (This notification is only forlinked objects.)	None. The library automatically updates the link information.
OLE_QUERY_PAINT	The client DLL needs to know whether to continue a lengthy paintingoperation.	Return TRUE to continue painting. Return FALSE to interrupt painting.
OLE_QUERY_RETRY	The client DLL needs to know whether to retry connecting to a busy server.	Returns TRUE to have the library re-attempt a conversation with the server. Return FALSE to stop attempting to connect.
The return value for the CallBack is ignored except for the OLE_QUERY_RETRY and OLE_QUERY_PAINT notifications.

The following code shows the CallBack function for CLIDEMO.EXE:

/*

 * CallBack()

 *

 * This routine will be called whenever an object has been changed,

 * saved, renamed, is being painted, or an asynchronous operation has

 * completed.  This routine is called by the OLE client DLL in the

 * above situations.  A pointer to this function is kept in the

 * client vtbl.  It is our obligation as a client application to

 * insure that a pointer to this procedure is in the vtbl.

 *

 * IMPORTANT: Note that we are posting messages here rather that

 * doing the work right away.  This is to avoid any possibility of

 * getting into another dispatch message loop.

 *

 * Returns int - see below

 *

 * The return value is generally ignored, except for OLE_QUERY_PAINT

 * and  OLE_QUERY_RETRY.  For these, returning TRUE means continue

 * the current operation(e.g., painting or retry).  Returning FALSE

 * means stop the current operation.  This is useful for interrupting

 * a repaint of an object in order to perform other operations.

 */

int FAR PASCAL CallBack               // ENTRY:

  (LPOLECLIENT lpClient,              // client application pointer

  OLE_NOTIFICATION flags,             // notification code being sent

  LPOLEOBJECT    lpObject)            // OLE object pointer

{                                     // LOCAL:

   APPITEMPTR pItem;                  // application item pointer

  pItem = (APPITEMPTR)LOWORD(lpClient);

  switch (flags)

  {

    case OLE_CLOSED:                  // server has closed

      if (!pItem->fVisible)

      {

        PostMessage(hwndFrame, WM_DELETE,(WORD)pItem,0L);

        Dirty(DOC_UNDIRTY);

      }

      SetFocus( hwndFrame );

      break;

    case OLE_SAVED:                    // server has saved object

    case OLE_CHANGED:                  // object has changed

      cOleWait++;

      pItem->fServerChangedBounds = pItem->fVisible = TRUE;

      PostMessage(pItem->hwnd, WM_CHANGE, NULL, 0L);

      break;

    case OLE_RELEASE:           // notification that an asynchronous

      if (hRetry)               // operation has completed

        PostMessage(hRetry,WM_COMMAND,IDCANCEL,0L);

      if (cOleWait)

      {

        pItem->fRetry = TRUE;

        if (!--cOleWait)

          Hourglass(FALSE);

        Release(pItem);

      }

      break;

    case OLE_QUERY_RETRY:              // Continue retrying.

      ToggleBlockTimer(FALSE);         // toggle timer off

      if (!hRetry && pItem->fRetry)

         PostMessage(hwndFrame,WM_RETRY,(WORD)pItem,0L);

      return (pItem->fRetry);

    case OLE_QUERY_PAINT:              // continue repainting

      return TRUE;                     // a false return terminates

                                       // either

    default:

      break;

  }

  return 0;                            // return value is ignored in

                                       // most cases, see header

}

OLESTREAM and OLESTREAMVTBL

The OLESTREAM structure points to an OLESTREAMVTBL structure, which in turn points to the client-supplied Get and Put functions for stream input and output. These structures are defined in OLE.H as follows:

typedef struct _OLESTREAM

{

  LPOLESTREAMVTBL   lpstbl;

} OLESTREAM;

typedef struct _OLESTREAMVTBL

{

  DWORD (CALLBACK *Get) (LPOLESTREAM, void FAR *, DWORD);

  DWORD (CALLBACK * Put) (LPOLESTREAM, void FAR *, DWORD);

} OLESTREAMVTBL;

typedef OLESTREAMVTBL FAR* LPOLESTREAMVTBL;

Figure 31 shows the relationship between OLESTREAM and OLESTREAMVTBL structures:

Figure 31. Relationship between OLESTREAM, OLESTREAMVTBL, and Get and Put callback functions

You will need to create your own OLESTREAM wrapper data structure, keeping the OLESTREAM structure as the first member and adding any additional information needed by your client application. You can name the structure anything you like.

As shown in the following code example, CLIDEMO.EXE defines a structure called APPSTREAM, which includes the OLESTREAM structure as its first member:

typedef struct _APPSTREAM FAR *LPAPPSTREAM;

typedef struct _APPSTREAM{

OLESTREAM olestream;

int fh;

} APPSTREAM;

Stream Get and Put Functions

The client DLL uses the ReadStream and WriteStream (Get and Put) functions when loading and saving objects. When a client application calls the client DLL to save an object to a stream with the OleSaveToStream function, the client DLL calls the WriteStream (Put) function pointed to in OLESTREAMVTBL. When loading an object from a stream, the client DLL calls OleLoadFromStream, which in turn calls the ReadStream (Get) function pointed to in OLESTREAMVTBL.

A client application can customize stream functions for particular situations, and a client can make such changes as varying the permanent storage for an object--for example, a client could store an object in a database, instead of in a file with the rest of the document.

The following examples shows how to use ReadStream and WriteStream:

/************************************************************************

 *  ReadStream() - OLE Callback Function (Get)

 *  This function is pointed to from the OLESTREAM vtbl; it is Get.

 *  returns DWORD  - number of bytes actually read

 ***********************************************************************/

DWORD  APIENTRY ReadStream(            //* ENTRY:

   LPAPPSTREAM    lpStream,            //* application stream pointer

   LPSTR          lpstr,               //* string pointer

   DWORD          cb                   //* byte count

){

   return _lread(lpStream->fh, lpstr, cb);

}

/************************************************************************

 *  WriteStream() - OLE Callback function (Put)

 *  This function is pointed to from the OLESTREAM vtbl; it is Put.

 *  Returns DWORD  - number of bytes actually written

 ***********************************************************************/

DWORD  APIENTRY WriteStream(           //* ENTRY:

   LPAPPSTREAM    lpStream,            //* application stream pointer

   LPSTR          lpstr,               //* string pointer

   DWORD          cb                   //* number of bytes to write

){

   return _lwrite(lpStream->fh, lpstr, cb);

}


Starting a Client Application

When a client application starts, it should do the following tasks as part of its start-up initialization:

Register the clipboard formats that it requires, using the OleRegisterClipboardFormat function.

Allocate and initialize the OLECLIENT data structure.

Allocate and initialize the OLESTREAM data structure.

Registering Clipboard Formats

A client application registers the clipboard formats it needs by calling the RegisterClipboardFormat function for each format, specifying such formats as Native, OwnerLink, ObjectLink, and any other formats it requires. These registered formats should be stored as global variables visible to all objects, since they are needed to handle object data. For more information on the clipboard formats and their use with OLE, see Considerations for OLE Applications.

// Global Variables

OLECLIPFORMAT   vcfLink;                //Supports linked objects

OLECLIPFORMAT   vcfNative;              //Supports Native format

OLECLIPFORMAT   vcfOwnerLink;           //Supports embedded objects

    .

    .

    .

vcfLink       = RegisterClipboardFormat ("ObjectLink");

vcfNative     = RegisterClipboardFormat ("Native";

vcfOwnerLink  = RegisterClipboardFormat("OwnerLink");

Allocating and Initializing the OLECLIENT and OLESTREAM Structures

The OLECLIENT data structure is allocated and initialized by the client application, and then passed to the client DLL.

Before calling any function in the client DLL, the client application needs to allocate and initialize the OLECLIENTVTBL and OLESTREAMVTBL structures with the MakeProcInstance call, setting each field in these structures. Memory must be allocated for these structures since the OLECLIENT and OLESTREAM structures only contain pointers to the VTBLs.

If a MakeProcInstance call fails, then the application should fail initialization and terminate--a client application cannot function without the ability for the client DLL to call these callback functions.

To illustrate, consider the following code examples from CLIDEMO.EXE, which are used to allocate and initialize the OLECLIENT and OLESTREAM wrapper structures:

/*

 * InitAsOleClient()

 *

 * Initiates the creation of stream and client vtbls.  These vtbls

 * are very important for the proper operation of this application.

 * The  stream vtbl lets the OLE libraries know where the location of

 * the stream I/O routines reside.  The stream routines are used by

 * OleLoadFromStream and the like.  The client vtbl is used to hold

 * the pointer to the CallBack function.

 *

 * IMPORTANT: both the client and the stream structures have pointers

 * to vtbls which have the pointers to the functions.  Therefore, it

 * is necessary to allocate space for the vtbl and the client

 * structure that has the pointer to the vtbl.

 */

static BOOL InitAsOleClient(           // ENTRY:

  HANDLE         hInstance,            // application instance handle

  HWND           hwnd,                 // main window handle

  PSTR           pFileName,            // document file name

  LHCLIENTDOC    *lhcDoc,              // pointer to document Handle

  LPOLECLIENT    *lpClient,            // pointer to client pointer

  LPAPPSTREAM    *lpStream)            // pointer to APPSTREAM pointer

{

                                       // initiate client vtbl creation

  if (!(*lpClient = InitClient(hInstance)))

  {

    SendMessage(hwnd, WM_SYSCOMMAND, SC_CLOSE, 0L);

    return FALSE;                      // ERROR return

  }

                                     // initiate stream vtbl creation

  if (!(*lpStream = InitStream(hInstance)))

  {

    SendMessage(hwnd, WM_SYSCOMMAND, SC_CLOSE, 0L);

    return FALSE;                      // ERROR return

  }

  if (*pFileName && RegDoc(pFileName,lhcDoc)

     && LoadFile(pFileName,*lhcDoc,*lpClient,*lpStream))

  {

    SetTitle(pFileName);

    return TRUE;                        // SUCCESS return

  }

  NewFile(pFileName, lhcDoc, *lpStream);

  return TRUE;                          // SUCCESS return

}                                       // SUCCESS return

/*

 * InitClient()

 * Initialize the OLE client structure, create and fill the

 * OLECLIENTVTBL structure.

 *

 * Returns LPOLECLIENT - if successful a pointer to a client

 * structure otherwise NULL.

 */

static LPOLECLIENT InitClient           // ENTRY:

   (HANDLE hInstance)                   // application instance handle

{                                       // LOCAL:

  LPOLECLIENT lpClient=NULL;            // pointer to client struct

                                        // Allocate vtbls

  if (!(lpClient = (LPOLECLIENT)GlobalLock(

     GlobalAlloc(GMEM_FIXED | GMEM_ZEROINIT, sizeof(OLECLIENT)))))

     goto Error;                        // ERROR jump

  if (!(lpClient->lpvtbl = (LPOLECLIENTVTBL)GlobalLock(

     GlobalAlloc(GMEM_FIXED | GMEM_ZEROINIT,sizeof(OLECLIENTVTBL)))))

     goto Error;                        // ERROR jump

                                        // set the CALLBACK function

                                        // pointer

  lpClient->lpvtbl->CallBack  = MakeProcInstance(CallBack, hInst);

  return lpClient;                      // SUCCESS return

Error:                                  // ERROR Tag

  ErrorMessage(E_FAILED_TO_ALLOC);

  EndClient(lpClient);                  // free any allocated space

  return NULL;                          // ERROR return

}

/*

 *  InitStream()

 *

 * Create and fill the STREAMVTBL.  Create a stream structure and

 * initialize pointer to stream vtbl.

 *

 * Returns LPAPPSTREAM - if successful a pointer to a stream

 *                      structure otherwise NULL .

static LPAPPSTREAM InitStream         // ENTRY:

   (HANDLE hInstance)               // handle to application instance

{                                     // LOCAL:

  LPAPPSTREAM lpStream = NULL;        // pointer to stream structure

  if (!(lpStream = (LPAPPSTREAM)GlobalLock(

     GlobalAlloc(GMEM_FIXED | GMEM_ZEROINIT, sizeof(APPSTREAM)))))

     goto Error;                      // ERROR jump

  if (!(lpStream->olestream.lpstbl = (LPOLESTREAMVTBL)GlobalLock(

     GlobalAlloc(GMEM_FIXED | GMEM_ZEROINIT,sizeof(OLESTREAMVTBL)))))

    goto Error;                       // ERROR jump

                                      // set stream func.  pointers

  lpStream->olestream.lpstbl->Get = (DWORD (FAR PASCAL *)(LPOLESTREAM,

     LPSTR, DWORD)) MakeProcInstance((FARPROC)ReadStream, hInst);

  lpStream->olestream.lpstbl->Put = (DWORD (FAR PASCAL *)(LPOLESTREAM,

    LPSTR, DWORD)) MakeProcInstance((FARPROC)WriteStream, hInst);

  return lpStream;                     // SUCCESS return

Error:                                 // ERROR Tag

  ErrorMessage(E_FAILED_TO_ALLOC);

  EndStream(lpStream);

  return NULL;                         // ERROR return

}


Managing Documents

A client application should notify the client DLL when it opens, closes, saves, or renames a document, or reverts a document to a previously saved state. A client application can use the following functions to accomplish these tasks:

Function	Description

OleRegisterClientDoc	Registers an opened document with the client DLL.

OleRenameClientDoc	Informs the client DLL that a document has been renamed.

OleRevertClientDoc	Informs the client DLL that a document has reverted to a previously saved state.

OleRevokeClientDoc	Informs the client DLL that a document should be closed or no longer exists.

OleSavedClientDoc	Informs the client DLL that a document has been saved.

Note:	When saving an object, the client application must store a persistent name for that object in its document file; this name uniquely identifies the object. The application must retain the name until the object is explicitly renamed with the OleRename

function or until the object is deleted with the OleDelete function. Since this name is used to locate the object, it should be stored separate from the object itself.

Opening a Compound Document

To open a compound document, a client application should:

Register the client application document with the client DLL using the OleRegisterClientDoc function.

Load the application specific document data from a file.

Load each object in the document.

Automatically update any automatic links. List any objects with manual links so that the user can update them.

Registering an OLE Document

Each time a client application creates or opens a document, it should regis ter the document with the client DLL. A client application should register all documents it opens or creates, including untitled documents. Untitled documents can be registered initially using a default name, and then renamed when the document is saved under a new name by the user.

The OleRegisterClientDoc function is used to register a document with the client DLL. (This registration is not the same as the registry used by servers to register objects.) OleRegisterClientDoc returns a handle to the document, which is then used to notify the client DLL of changes to the document such as renaming, saving, and closing.

When a document is saved under a new name, the client application should call the OleRenameClientDoc and OleSavedClientDoc functions, specifying the handle obtained from OleRegisterClientDoc.

Loading Objects

A client application calls the OleLoadFromStream function for each object in the document that will be shown on the screen or otherwise activated. It is not necessary to load every object in a document immediately when the document is opened; often only the objects that must be drawn or activated are loaded when the document is opened. Parameters for OleLoadFromStream include a pointer to the OLECLIENT structure, which is used to locate the client's CallBack function, and a pointer to the OLESTREAM structure , which is used to locate the Get function (pointed to in OLESTREAMVTBL) to load the object.

As the following code examples show, CLIDEMO.EXE initiates the loading of a document by calling ReadFromFile. ReadFromFile in turn calls ObjRead to read the individual objects. ObjRead then calls OleLoadFromStream to locate and call the Get callback function.

As part of loading the document, ReadFromFile calls the UpdateLinks function, which prompts the user to update any links to the objects in the document.

/*

 *  ReadFromFile()

 *

 *  This function reads OLE objects from a file.  If the document

 *  contains manual links, the user will be prompted to update those

 *  links.

 *

 *  Returns BOOL  - TRUE if the read(s) were successful

 */

BOOL FAR ReadFromFile                  // ENTRY:

  (LPAPPSTREAM    lpStream,            // application stream pointer

  LHCLIENTDOC    lhcDoc,               // document handle

  LPOLECLIENT    lpClient)             // pointer to OLE client

                                       // structure

{                                      // LOCAL:

  BOOL           bReturn = FALSE;      // return value

  unsigned int   cFileObjects;         // number of file objects

  Hourglass(TRUE);

  fLoadFile = TRUE;

  _llseek(lpStream->fh, 0L, 0);        // Read the number of objects

                                       // in the file

  if (_lread(lpStream->fh, (LPSTR)&cFileObjects,

     sizeof(int)) < sizeof(int))

     goto Error;

  for (; cFileObjects; --cFileObjects)

  {

    if (!ObjRead(lpStream,lhcDoc,lpClient))

    {

      ErrorMessage(E_FAILED_TO_READ_OBJECT);

      goto Error;

    }

  }

  ShowDoc(lhcDoc,1);

  UpdateLinks(lhcDoc);

  bReturn = TRUE;                     // SUCCESS

Error:                                // ERROR Tag

  Hourglass(FALSE);

  fLoadFile = FALSE;

  return bReturn;                    // return

}

/*

 *  ObjRead()

 *

 *  Read an object from the specified file.  The file pointer will

 *  be advanced past the object.

 *

 *  HANDLE fh     - DOS file handle of file to be read from

 *

 *  returns HWND  - window handle to item window containing the OLE

 *  object

 */

BOOL FAR ObjRead                       // ENTRY:

  (LPAPPSTREAM    lpStream,            // application stream pointer

  LHCLIENTDOC    lhcDoc,               // document handle

  LPOLECLIENT    lpClient)             // pointer to OLE client

                                       // structure

{                                      // LOCAL:

  APPITEMPTR     pItem;                // application item pointer

  LPOLEOBJECT    lpObject;             // pointer OLE object

  long           otObject;             // type of object

  RECT           rcObject;             // object rect

  char           szTmp[CBOBJNAMEMAX];  // temporary string buffer

                                       // protocol string

  char           szProto[PROTOCOL_STRLEN+1];

  int            i;                    // index

  if (_lread(lpStream->fh, szTmp, CBOBJNAMEMAX) < CBOBJNAMEMAX )

    return FALSE;

  if (_lread(lpStream->fh, szProto,PROTOCOL_STRLEN) < PROTOCOL_STRLEN)

    return FALSE;

  for (i=0; szProto[i] != ' '; i++);

    szProto[i] = NULL;

  ValidateName( szTmp );

  if (!(pItem = PreItemCreate(lpClient, TRUE, lhcDoc)))

    return FALSE;

  if (Error(OleLoadFromStream((LPOLESTREAM)&(lpStream->olestream),

      szProto,(LPOLECLIENT)&(pItem->oleclient), lhcDoc, szTmp,

      &lpObject)))

     goto Error;

  if (_lread(lpStream->fh, (LPSTR)&rcObject,

    sizeof(RECT)) < sizeof(RECT))

  goto Error;

  if (_lread(lpStream->fh, (LPSTR)&otObject,

    sizeof(long)) < sizeof(long))

  goto Error;

  if (PostItemCreate(lpObject, otObject, &rcObject, pItem))

  {

    pItem->fNew = TRUE;

    ObjSetBounds(pItem);

    return TRUE;                             // SUCCESS return

  }

  else

    return FALSE;

Error:                                       // ERROR Tag

  FreeAppItem(pItem);

  return FALSE;

}

/*

 * UpdateLinks()

 *

 * Get the most up to date rendering information and show it.

 */

static void UpdateLinks                 // ENTRY

  (LHCLIENTDOC    lhcDoc)               // client document handle

{                                       // LOCAL:

  int            i=0;                   // index

  APPITEMPTR     pItem;                 // temporary item pointer

  char           szUpdate[CBMESSAGEMAX];// update message?

  for (pItem = GetTopItem(); pItem; pItem = GetNextItem(pItem))

  {

   if (pItem->lhcDoc == lhcDoc && pItem->otObject == OT_LINK)

   {

     if (!i)

     {

       LoadString(hInst, IDS_UPDATELINKS, szUpdate, CBMESSAGEMAX);

       if (MessageBox(hwndFrame, szUpdate, szAppName, MB_YESNO |

          MB_ICONEXCLAMATION) != IDYES)

          break;

       i++;

     }

     Error(OleUpdate(pItem->lpObject));

   }

  }

  WaitForAllObjects();

}

Saving a Document

To save a document, a client application should do the following:

Save the data for the document in the document's file.

For each object in the document, call the OleSaveToStream function (which in turn, calls the client application's Put callback function).

After all objects have been saved, call the OleSavedClientDoc function to inform the client DLL that all objects have been saved.

A client application can call the OleQuerySize function to determine the size of the buffer required to store an object before calling OleSaveToStream.

Note:	When saving objects in a container document, be careful not to save any presentation formats other than those needed to recreate the object--file size can grow dramatically saving needless formats. When saving embedded objects, only the Native data and the presentation data need to be stored in the container document. For linked objects, only the OwnerLink and presentation formats need to be stored.

CLIDEMO.EXE initiates the saving of a document by calling the SaveFile function. SaveFile displays a dialog box asking the user to save changes. If the user chooses to save the document, then SaveFile calls the WriteToFile function, which in turn calls ObjWrite. ObjWrite  makes the necessary call to OleSaveToStream. After the data has been saved, SaveFile calls OleSavedClientDoc  to notify the client DLL of the status.

/*

 *  SaveFile()

 *

 * Save a compound document file.  If the file is untitled, ask the

 * user for a name and save the document to that file.

 */

static BOOL SaveFile                    // ENTRY:

  (PSTR           pFileName,            // file to save document to

  LHCLIENTDOC    lhcDoc,                // OLE document handle

  LPAPPSTREAM    lpStream)              // pointer to app.  stream

                                        // struct

{                                       // LOCAL:

  char           szNewFile[CBPATHMAX];  // New file name strings

  char           szOemFileName[2*CBPATHMAX];

  static char    szUntitled[CBMESSAGEMAX] = "";

  HANDLE         fh;                    // file handle

  *szNewFile = NULL;

  if (!(*szUntitled))

    LoadString(hInst, IDS_UNTITLED, (LPSTR)szUntitled,CBMESSAGEMAX);

  if (!lstrcmp(szUntitled, pFileName))  // get filename for the

                                        // untitled case

  {

    if (!OfnGetName(hwndFrame, szNewFile, IDM_SAVEAS))

      return FALSE;                     // CANCEL return

    lstrcpy(pFileName,szNewFile);

    SetTitle(pFileName);

  }

  AnsiToOem(pFileName, szOemFileName);

  if ((fh =_lcreat((LPSTR)szOemFileName, 0)) <= 0)

  {

    ErrorMessage(E_INVALID_FILENAME);

    return FALSE;                    // ERROR return

  }

  lpStream->fh = fh;

                                       // save file on disk

  if (!WriteToFile(lpStream))

  {

    _lclose(fh);

    ErrorMessage(E_FAILED_TO_SAVE_FILE);

    return FALSE;                      // ERROR return

  }

  _lclose(fh);

  if (Error(OleSavedClientDoc(lhcDoc)))

  {

    ErrorMessage(W_FAILED_TO_NOTIFY);

    return FALSE;                    // ERROR return

  }

  Dirty(DOC_CLEAN);

  return TRUE;                        // SUCCESS return

}

/*

 *  WriteToFile()

 *

 *  Write current document to a file.

 *

 *  returns BOOL - TRUE if file successfully written

 */

BOOL FAR WriteToFile                    // ENTRY:

   (LPAPPSTREAM    lpStream)            // application stream pointer

{                                       // LOCAL:

   int            iObjectsWritten=0;    // counter of objects written

                                        // to file

  APPITEMPTR     pItem;                 // application Item pointer

  UpdateFromOpenServers();

  _llseek(lpStream->fh, 0L, 0);

  Hourglass(TRUE);

  if (_lwrite(lpStream->fh, (LPSTR)&iObjects,

    sizeof(int)) < sizeof(int))

  goto Error;

  for (pItem = GetTopItem(); pItem; pItem = GetNextItem(pItem))

  {

   if (!ObjWrite(lpStream, pItem))

     goto Error;

   iObjectsWritten++;

  }

  if (iObjectsWritten != iObjects)

    goto Error;

  Dirty(DOC_CLEAN);

  Hourglass(FALSE);

  return(TRUE);                              // SUCCESS return

Error:                                       // ERROR Tag

  Hourglass(FALSE);

  return(FALSE);                             // ERROR return

}

/*

 *  ObjWrite()

 *

 *  This function writes an object to the specified

 *  file.  The file pointer will be advanced past the end of

 *  the written object.

 *  Returns BOOL - TRUE if object written successfully

 */

BOOL FAR ObjWrite                        // ENTRY:

  (LPAPPSTREAM    lpStream,              // application stream pointer

  APPITEMPTR     pItem)                  // application item pointer

{                                        // LOCAL:

  POINT           pt;                    // center of rec point

  RECT            rc;                    // bounding rectangle

  int             cbTmp;

  char            szTmp[PROTOCOL_STRLEN];// protocol string

  cbTmp = CBOBJNAMEMAX;

  OleQueryName(pItem->lpObject, szTmp, &cbTmp);

  if (_lwrite(lpStream->fh, szTmp, CBOBJNAMEMAX) < CBOBJNAMEMAX )

     return FALSE;

  if (pItem->otObject == OT_STATIC)

     wsprintf(szTmp, "%-15s", STATICP);

  else

     wsprintf(szTmp, "%-15s", STDFILEEDITING);

  if (_lwrite(lpStream->fh, szTmp,PROTOCOL_STRLEN) < PROTOCOL_STRLEN )

     return FALSE;

  if (Error(OleSaveToStream(pItem->lpObject,

      (LPOLESTREAM)&(lpStream->olestream))))

     return FALSE;

  GetClientRect(pItem->hwnd, (LPRECT)&rc);

  pt = *(LPPOINT)&rc;

  ClientToScreen(pItem->hwnd, (LPPOINT)&pt);

  ScreenToClient(hwndFrame, (LPPOINT)&pt);

  OffsetRect(&rc, pt.x - rc.left - GetSystemMetrics(SM_CXFRAME),

     pt.y - rc.top  - GetSystemMetrics(SM_CYFRAME));

  if (_lwrite(lpStream->fh, (LPSTR)&rc, sizeof(RECT)) < sizeof(RECT)

      || _lwrite(lpStream->fh, (LPSTR)&(pItem->otObject),

      sizeof(long)) < sizeof(long))

     return FALSE;

  return TRUE;                                  // SUCCESS return

}

Closing a Document

To close a document, a client application should do the following:

Prompt the user to save changes to the document; if the user chooses to save the document, call the OleSavedClientDoc function.

For each object in the document, call the OleRelease function.

When the client DLL confirms that all objects have been closed, call the OleRevokeClientDoc function.

In the CLIDEMO.EXE program, if the user chooses to close the document, CLIDEMO.EXE first calls SaveAsNeeded, which checks to see if the document has been changed. If the document has been changed, SaveFile(see preceding code example) is called to initiate the saving of the document. After saving, DeregDoc unregisters the document with the client DLL by calling OleRevokeClientDoc.

case WM_CLOSE:

  ANY_OBJECT_BUSY;

  if (!SaveAsNeeded(szFileName, lhcDoc, lpStream))

    break;

  DeregDoc(lhcDoc);

  DestroyWindow(hwnd);

  break;/*

 *  SaveAsNeeded()

 *

 *  This function will have the file saved if and only

 *  if the document has been modified.  If the fDirty flag has

 *  been set to TRUE, then the document needs to be saved.

 *

 *  Returns: BOOL -  TRUE if document doesn't need saving or if the

 *                   document has been saved successfully.

 */

static BOOL SaveAsNeeded(              // ENTRY:

  PSTR           pFileName,            // file to save

  LHCLIENTDOC    lhcDoc,               // OLE doc handle

  LPAPPSTREAM    lpStream)             // pointer to OLE stream vtbl

{                                      // LOCAL:

  char           sz[CBMESSAGEMAX];     // work strings

  char           sz2[CBMESSAGEMAX + CBPATHMAX];

  if (Dirty(DOC_QUERY))                // if doc is clean don't bother

  {

    LoadString(hInst, IDS_MAYBESAVE, sz, CBMESSAGEMAX);

    wsprintf(sz2, sz, (LPSTR)pFileName );

    switch (MessageBox(hwndFrame, sz2, szAppName, MB_YESNOCANCEL |

            MB_ICONQUESTION))

    {

      case IDCANCEL:

        return FALSE;                  // CANCEL return

      case IDYES:

       return (SaveFile(pFileName,lhcDoc,lpStream));

      default:

        break;

    }

  }

  return TRUE;                         // SUCCESS return

}

/*

 *  DeregDoc()

 *

 *  This function initiates the removal of all OLE objects from the

 *  current document and unregisters the document with the OLE

 *  library.

 */

static void DeregDoc                   // ENTRY:

  (LHCLIENTDOC    lhcDoc)              // client document handle

{

  if (lhcDoc)

  {                                    // release all OLE objects and

    ClearAll(lhcDoc,RELEASE);          // remove them from the screen

    WaitForAllObjects();

    if (Error(OleRevokeClientDoc(lhcDoc)))

      ErrorMessage(W_FAILED_TO_NOTIFY);

  }

}                                      // SUCCESS return


Working with Objects

Client applications must be able to create, display, activate, and delete objects. In addition, they must be able to cut and copy objects to the clipboard. The following sections explain how to implement these tasks into client applications.

Creating Objects

A client application can put linked and embedded objects in a document by pasting them from the clipboard, creating them from a file, copying them from other objects, or by starting a server application to create them from a file, copying them from other objects, or by starting a server application to create them directly.

Object-Creation Functions

Each of the following functions creates an embedded or linked object in a specified document:

Function	Description

OleClone	Creates an exact copy of an object.

OleCopyFromLink	Creates an embedded object that is a copy of a linked object.

OleCreate	Creates an embedded object of a specified class.

OleCreateFromClip	Creates an object from the clipboard. This function typically creates an embedded object.

OleCreateFromFile	Creates an object by using the contents of a file. This function typically creates an embedded object.

OleCreateFromTemplate	Creates an embedded object by using another object as a template.

OleCreateInvisible	Creates an object without displaying the server application to the user.

OleCreateLinkFromClip	Creates an object by using information on the clipboard. This function typically creates a linked object.

OleCreateLinkFromFile	Creates an object by using the contents of a file. This function typical ly creates a linked object.

OleObjectConvert	Creates an object that supports a specified protocol by converting an existing object.

Each of these functions takes a parameter that points to an LPOLEOBJECT structure when the function returns.

Before the client DLL gives the client application a pointer to this structure, the DLL includes with the structure some internal information corresponding to the OwnerLink or ObjectLink data. This internal information allows the client DLL to identify the correct server when an OLE function such as OleActivate passes it a pointer to an OLEOBJECT structure.

Note:	Each object must have a name that is unique to the client document. Although meaningful object names can be helpful, some applications assign unique object names simply by incrementing a counter for each new object. Remember too, that OLE object name s are persistent; that is, when a document is saved, closed, and then reopened, the objects are loaded with the same names they had when they were saved.

If a client application implements the Insert Object menu command, it should use the registry to find out which OLE server applications are available and then list those applications for the user. When the user selects one of the server applications and chooses the OK button, the client application can use the OleCreate function to create an object at the current position.

The OleCopyFromLink, OleCreate, and OleCreateFromTemplate functions always create an embedded object. The other object-creation functions can create either an embedded object or a linked object, depending on the order and type of available data.

If a client application's CallBack function receives the OLE_RELEASE notification after the client calls the OleCreate or OleCreateFromFile function, the client application should respond by calling the OleQueryReleaseError function. If OleQueryReleaseError shows that there was an error when the object was created, the client application should delete the object.

Whenever an object-creation function returns OLE_WAIT_FOR_RELEASE, the calling application should either wait for the OLE_RELEASE notification, or notify the user that the object cannot be created. For more information, see Handling Asynchronous Operations.

Paste and Paste Link Commands

A client application should do the following to create an embedded or linked object by pasting from the clipboard:

Call the OleQueryCreateFromClip function   to determine whether to enable the Paste command. If this function fails when StdFileEditing is specified for the lpszProtocol parameter, call it again, specifying Static.

Call the OleQueryLinkFromClip function   to determine whether to enable the Paste Link command.

If the user chooses the Paste command, open the clipboard and call the OleCreat eFromClip function.

If the user chooses Paste Link, open the clipboard and call the OleCreateLinkFromClip function.

Close the clipboard.

Call the OleQueryType function   to determine the kind of object created by the creation function. (Depending on the order of clipboard data, OleCreateFromClip can sometimes create a linked object and OleCreateLinkFromClip can sometimes create an embedded object.)

The client application should put the pasted data or object into the document at the current position. The client should select the object so that the user can work with it immediately. If both the OleQueryCreateFromClip and OleQueryLinkFromClip functions fail but there is data on the clipboard that the client can interpret, the client should enable the Paste command.

If the information on the clipboard is incomplete--for example, if Native data is not accompanied by OwnerLink format--the Paste command should insert a static object into the document.

Note Static objects consist of only the presentation data for an object. Attempts to open static objects fail.

If the client application implements the Paste Special command, it should use the EnumClipboardFormats function to produce a list of data formats on the clipboard. The client application should also check the registry to find the full name of the server application. The Paste Link button in the Pas te Special dialog box works in exactly the same way as the Paste Link command on the Edit menu.

If the DDE Link format is available on the clipboard instead of ObjectLink format, the client application should perform the same link operation as it supported prior to the implementation of OLE.

The following code example demonstrates pasting an object from within CLIDEMO.EXE:

From CLIDEMO.C:

.

.

case IDM_PASTE

case IDM_PASTELINK:

        ANY_OBJECT_BUSY;

        ObjPaste(wParam == IDM_PASTE, lhcDoc, lpClient);

        break;

From Object.C:

.

.

/*

 *  ObjPaste()

 *

 *  This function obtains an object from the clipboard.

 *  Handles both embedded and linked objects.  An item window is

 *  created for each new object.

 *

 *  Returns BOOL  - TRUE if object was pasted successfully.

 */

void FAR ObjPaste                      // ENTRY:

  (BOOL           fPaste,              // Paste/PasteLink flag

  LHCLIENTDOC    lhcDoc,               // client document handle

  LPOLECLIENT    lpClient)             // pointer to client

{                                      // LOCAL:

  LPOLEOBJECT    lpObject;             // object pointer

  long           otObject;             // object type

  APPITEMPTR     pItem;                // application item pointer

  char           szTmp[CBOBJNAMEMAX];  // temporary object name string

  if (!(pItem = PreItemCreate(lpClient, TRUE, lhcDoc)))

    return;                            // ERROR return

  if (!OpenClipboard(hwndFrame))

    goto Error;                      // ERROR jump

  if (fPaste)                        // PASTE the object.

  {                                  // Try "StdFileEditing" protocol

    if (Error(OleCreateFromClip(STDFILEEDITING,(LPOLECLIENT)&

       (pItem->oleclient),lhcDoc, CreateNewUniqueName(szTmp),&lpObject,

        olerender_draw,0)))

    {

                                        // next try "Static" protocol

      if (Error(OleCreateFromClip(STATICP, (LPOLECLIENT)&

         (pItem->oleclient), lhcDoc, CreateNewUniqueName(szTmp),

         &lpObject, olerender_draw, 0)))

        goto Error;                     // ERROR jump

    }

  }

  else

  {                                    // LINK therefore must be

                                       // "STdFileEditing" protocol

    if (Error(OleCreateLinkFromClip(STDFILEEDITING,(LPOLECLIENT)&

       (pItem->oleclient), lhcDoc, CreateNewUniqueName(szTmp),

       &lpObject, olerender_draw, 0)))

      goto Error;                      // ERROR jump

  }

  OleQueryType(lpObject, &otObject);

  CloseClipboard();

  if (!PostItemCreate(lpObject, otObject, NULL, pItem))

     return;                           // ERROR return

  ShowNewWindow(pItem);

  return;                              // SUCCESS return

Error:                                  // TAG Error

  ErrorMessage(E_GET_FROM_CLIPBOARD_FAILED);

  CloseClipboard();

  FreeAppItem(pItem);

  return;                              // ERROR return

}

/*

 * PostItemCreate()

 *

 * This function creates a child window which will contain the newly

 * created OLE object.  A pointer to our item information is stored in

 * the extra bytes of this window.  This is where we internally keep

 * track of information related to the object as well as the

 * pointer to the object for subsequent OLE API calls.  This routine is

 * called after an OLE object has been created by the client library.

 *

 * Returns BOOL - TRUE if application item has been created.

 *

 */

BOOL FAR PostItemCreate                 // ENTRY:

  (LPOLEOBJECT    lpObject,             // OLE object pointer

  long           otObject,              // OLE object type

  LPRECT         lprcObject,            // object bounding rect

  APPITEMPTR     pItem)                 // application item pointer

{                                       // LOCAL:

  int            i;                     // index

  RECT           rc;                    // bounding rectangle

  char           pData[OBJECT_LINK_MAX];// copy of link data

  if (lprcObject)                       // if the size of the objects

    rc = *lprcObject;                   // bounding rectangle is not

  else if (OleQueryBounds(lpObject, &rc) == OLE_OK)

    ConvertToClient(&rc);

  else

    SetRect(&rc, 0, 0, 0, 0);

                                        // Create the child window

  if (!(pItem->hwnd = CreateWindow( szItemClass, "",

      WS_BORDER | WS_CHILD | WS_CLIPSIBLINGS | WS_THICKFRAME,

      rc.left,rc.top, rc.right - rc.left + 2 *

      GetSystemMetrics(SM_CXFRAME), rc.bottom - rc.top + 2 *

      GetSystemMetrics(SM_CYFRAME), hwndFrame, NULL, hInst, NULL)))

    goto Error;

                                        // in windows extra bytes

  SetWindowWord(pItem->hwnd, 0, (WORD)pItem);

  pItem->otObject = otObject;

  pItem->lpObject = lpObject;

  pItem->fRetry  = TRUE;

  if( pItem->otObject == OT_EMBEDDED ) // if object is embedded tell

                                       // library the container name

  {                                    // and object name.

    int cb = CBOBJNAMEMAX;        // Name will be server window title

    char sz[CBOBJNAMEMAX];             // when the object is edited.

    OleQueryName(lpObject, (LPSTR)sz, &cb );

    WaitForObject(pItem);

    Error(OleSetHostNames(lpObject, (LPSTR)szAppName, (LPSTR)sz ));

    WaitForObject(pItem);

  }

  else if (pItem->otObject == OT_LINK) // if the object is linked

  {                                    // retrieve update options

    WaitForObject(pItem);

    if(Error(OleGetLinkUpdateOptions(pItem->lpObject,

       &pItem->uoObject)))

      goto Error;

    if (ObjGetData(pItem,pData))

    {

      for (i=0; pData[i];i++);        // Skip past the server name

        pItem->aLinkName = AddAtom(&pData[++i]);

    }

    else

      pItem->aLinkName = AddAtom("");

  }

  iObjects++;

  Dirty(DOC_DIRTY);

                                // a user interface recommendations.

   return TRUE;                 // SUCCESS return

Error:                          // ERROR Tag

  ErrorMessage(E_FAILED_TO_CREATE_CHILD_WINDOW);

  FreeAppItem(pItem);

  return FALSE;                         // ERROR return

}

/*

 * ConvertToClient()

 *

 * This function will convert to client from himetric.

 */

void FAR ConvertToClient                // ENTRY:

  (LPRECT         lprc)                 // pointer to bounding

                                        // rectangle

{                                       // LOCAL

  // If we have an empty rectangle then set the default size

  if (!(lprc->left || lprc->top || lprc->right || lprc->bottom))

     SetRect(lprc, 0, 0, CXDEFAULT, CYDEFAULT);

  else

  {

    // We got the himetric units, convert them to pixels now.

    lprc->right   = MulDiv (giXppli, (lprc->right - lprc->left),

                    HIMETRIC_PER_INCH);

    lprc->bottom  = MulDiv (giYppli, (lprc->top - lprc->bottom),

                    HIMETRIC_PER_INCH);

    lprc->left    = 0;

    lprc->top     = 0;

  }

}

Displaying and Printing Objects

When an object has been loaded and, if necessary, brought up-to-date, the object can be displayed or printed with the container document . To display an object, the client application should set up the device context and bounding rectangle (ensuring that they use the same mapping mode) and then call the OleDraw function. The client application can use the OleQueryBounds function to retrieve the size of the bounding rectangle on the target device.

Note An object handler can be used to draw an object. If an object-handler exists for an object, the call to the OleDraw function is received and processed by the object handler. If there is no object handler, the client DLL uses the object's presentation data to display or print it. For more information on object handlers, see Implementing Object Handlers.

If the presentation data for an object is a metafile, the library periodically sends an OLE_QUERY_PAINT notification to the client application's callback function while drawing the object. If the callback function returns FALSE, the OleDraw function returns immediately and the drawing is ended. A client application could also use the OLE_QUERY_PAINT notification to take some actions within the callback function and then return TRUE to indicate that drawing should continue. Any actions the client application takes at this time should not interfere with the drawing operation; for example, the client application should not scroll the window.

If the target device for an object changes (for example, when the user changes printers), the client application should call the OleSetTargetDevice function. The client application should also call OleSetTargetDevice whenever an object is created or loaded.

If the size of the presentation rectangle for the object changes--for example, through action by the user--the client application should call the OleSetBounds function. After calling OleSetBounds, the client application should call the OleUpdate function to update the object and then OleDraw to redisplay it.

Activating Objects

When the user double-clicks on an object to activate it, the client application should check whether the object is busy by calling the OleQueryReleaseStatus function. If the object is busy, the client application should either refuse the request to open the object or enter a message-dispatch loop, waiting for the OLE_RELEASE notification (see Handling Asynchronous Operations).

If the object to be activated is not busy, the client application should call the OleActivate function. The client DLL notifies the client application when the server application is open or when an error occurs.

CLIDEMO.EXE activates objects as follows:

.

.

.

  case WM_LBUTTONDBLCLK:           // execute a verb

    ANY_OBJECT_BUSY;

    ExecuteVerb(OLEVERB_PRIMARY,(APPITEMPTR)GetWindowWord(hwnd,0));

    break;

/*

 * ANY_OBJECT_BUSY

 * checks to see if any object in the document is busy.  This prevents

 * a new document from being saved to file if there are objects in

 * asynchronous states.

 */

#define ANY_OBJECT_BUSY  {\

  if (ObjectsBusy()) \

    break; \

}

 /*

 *  ObjectsBusy()

 *

 *  This function enumerates the OLE objects in the current document

 *  and displays a message box stating whether an object is busy.

 *  This function calls  the DisplayBusyMessage() function which

 *  performs most of the work.  This function is only used by the macro

 *  ANY_OBJECT_BUSY, defined in clidemo.h.

 *

 *  fSelectionOnly  BOOL -NOT USED?

 *

 *  BOOL - TRUE if one or more objects found to be busy

 *             FALSE otherwise

 *

 */

BOOL FAR ObjectsBusy ()

{

  APPITEMPTR pItem;

  if (iTimerID)

  {

    RetryMessage(NULL,RD_CANCEL);

    return TRUE;

  }

  for (pItem = GetTopItem(); pItem; pItem = GetNextItem(pItem))

    if (DisplayBusyMessage(pItem))

      return TRUE;

  return FALSE;

}

/*

 *  DisplayBusyMessage()

 *

 *  This function determines if an object is busy and displays

 *  a message box stating this status.

 *

 *  Returns BOOL - TRUE if object is busy

 */

BOOL FAR DisplayBusyMessage            // ENTRY:

   (APPITEMPTR     paItem)             // application item pointer

{                                      // LOCAL:

  if (OleQueryReleaseStatus(paItem->lpObject) == OLE_BUSY)

  {

    RetryMessage(paItem,RD_CANCEL);

    return TRUE;

  }

  return FALSE;

}

/*

 *  ExecuteVerb()

 *

 *  Execute the verb for the given object.

 */

void FAR ExecuteVerb                   // ENTRY:

   (int iVerb,                         // verb

   APPITEMPTR pItem)                   // application item pointer

{                                      // LOCAL

  RECT        rc;                      // holds client area

                                       // bounding rect

  if (pItem->otObject == OT_STATIC)    // if the object is static beep

  {

    ErrorMessage(W_STATIC_OBJECT);

    return;                            // return

  }

                                       // get client area rectangle

  GetClientRect(hwndFrame, (LPRECT)&rc);

                                       // execute OLE verb

  if (Error(OleActivate(pItem->lpObject, iVerb, TRUE, TRUE,

      hwndFrame, &rc)))

     return;

  WaitForObject(pItem);               // wait for async. operation

}                                      // SUCCESS return

The OleActivate function allows the client application to display the activated object in a window of the server application. (A client application might hide the server window if an object is updated automatically.)

The first time a client application activates a particular embedded object, it should call the OleSetHostNames function, specifying the string the server application window should display in its title bar. This string should be the name of the client document containing the object. The client application does not need to call OleSetHostNames every time an embedded object is activated, because the client DLL maintains a record of the specified names.

A client application can use the OleQueryOpen function to determine whether a specified object is currently open. The OleClose function allows the client application to close an open object. Closing an object terminates the connection with the server application. To reestablish a terminated connection between a linked object and an open server application, the client application can use the OleReconnect function. To close an open object and release it from memory, a client application can call the OleRelease function.

Cutting and Copying Objects to the Clipboard

A client application can copy or cut an object to the clipboard by opening the clip-board, calling the OleCopyToClipboard function, and closing the clipboard. To illustrate this sequence of steps, consider the following code from CLIDEMO.EXE:

From CLIDEMO.C:

.

.

.

case IDM_COPY:

case IDM_CUT:

  ANY_OBJECT_BUSY;

  if (!ObjCopy(pItem)

  {

    ErrorMessage((wParam==IDM_CUT) ? E_CLIPBOARD_CUT_FAILED

    : E_CLIPBOARD_COPY_FAILED);

    break;

  }

  if (wParam ==IDM_COPY)

    break;

From Object.C:

.

.

.

/*

 * ObjCopy()

 *

 * This function places an OLE object on the clipboard via the \

 * OleCopyToClipboard() function.

 *

 * Returns BOOL - TRUE if object successfully placed on clipboard

 */

BOOL FAR ObjCopy                       // ENTRY:

   (APPITEMPTR     pItem)              // pointer to app item

{                                      // LOCAL:

  BOOL           fReturn = TRUE;       // return value

  if (!OpenClipboard(hwndFrame))

    return FALSE;                    // ERROR return

  EmptyClipboard();

  if (Error(OleCopyToClipboard(pItem->lpObject)))

    fReturn = FALSE;                   // prepare for ERROR out

   CloseClipboard();

   return fReturn;                     // ERROR or SUCCESS

}

If the client application supports delayed rendering, however, it should:

Open and empty the clipboard.

Put the preferred data formats on the clipboard.

Call the OleEnumFormats function to retrieve the formats for the object.

Call the SetClipboardData function to put the formats on the clipboard, specifying NULL for the handle to the data.

If the call to the OleEnumFormats function retrieves the ObjectLink format, the client application should call SetClipboardData with OwnerLink instead of ObjectLink format. (See the description of the OleCopyToClipboard function.)

Put any additional presentation data formats on the clipboard.

Close the clipboard.

To support the Cut command on the Edit menu, a client application can call OleCopyToClipboard and then delete the object by using the OleDelete  function. The client application can put only one of the selected objects on the clipboard, even when the user has selected and cut or copied multiple objects. In this case, the client application typically puts the first object in the selection onto the clipboard.

When an application, acting as both a client and server application, copies a selection to the clipboard containing one or more objects, it should first allocate enough memory for the selection. To determine the amount of memory required for each object, the application can call the OleQuerySize function. When memory has been allocated, the application should call the OleRegisterClientDoc function, specifying Clipboard for the document name. In this case, the handle returned by the call to OleRegisterClientDoc identifies a document that is used only during the copy operation.

To save each object to memory, the application calls the OleClone function, calls OleSaveToStream for the cloned object, and then calls OleRelease to free the memory for the cloned object. When the selection has been saved to the stream, the application can call the SetClipboardData function. If SetClipboardData is successful, the application should call the OleSavedClientDoc function. The application then calls the OleRevokeClientDoc function, specifying the handle retrieved by the call to OleRegisterClientDoc.

Deleting Objects

To permanently delete an object from a document, the client application should call the OleDelete function. OleDelete closes the specified object, if necessary, before deleting it.

The following code example shows how CLIDEMO.EXE deletes an object:

From ClIDEMO.C:

.

.

.

case WM_DELETE:                       // delete object

  pItem = (APPITEMPTR) wParam;

  WaitForObject(pItem);               // wait for async operation to

                                      // finish

  ObjDelete(pItem,DELETE);

  if (lParam)

     cOleWait--;

  break;

/*

 *  ObjDelete()

 *

 * Delete an OLE object.  For this application, all OLE objects

 * are associated with a child window; therefore the window must be

 * destroyed.

 *

 * NOTE: There is one case when we call OleRelease and the other when

 * we call OleDelete.  We call OleRelease when we unregister

 * a document and OleDelete when removing an object from a document.

 */

void FAR ObjDelete                     // ENTRY:

  (APPITEMPTR     pItem,               // pointer to application item

   BOOL           fDelete)             // delete or release flag

{                                      // LOCAL:

  if (pItem->lpObjectUndo)

  {

    Error(OleDelete(pItem->lpObjectUndo));

                                        // wait for asynchronous

                                        // operation

    WaitForObject(pItem);

  }

  if (fDelete ? Error(OleDelete(pItem->lpObject))

      : Error(OleRelease(pItem->lpObject)))

  {

    ErrorMessage(E_FAILED_TO_DELETE_OBJECT);

    return;                          //* ERROR return

  }

  if (pItem->fVisible)

  {

    ShowWindow(pItem->hwnd, SW_HIDE);

    pItem->fVisible = FALSE;

  }

                                        // the operation has to

                                        // complete before the

  WaitForObject(pItem);                 // application structure

  FreeAppItem(pItem);

  iObjects--;

}


Implementing Edit commands

Client applications can make it easy for users to work with linked and embedded objects by adding commands to the Edit menu. The Undo command allows you to give the user the chance to go back and undo an edit. The Links command allows the user to select the kind of linking desired (automatic or manual), to update or destroy links, and even to attempt to repair a broken link. The Object... command allows the user to edit or play a selected object (depending on the object's primary verb).

Implementing an Undo Command

A client application can use the OleClone function to support the Edit menu's Undo command. A cloned object is identical to the original except for connections to the server application; the cloned object is not automatically connected to the server application. When the server application is closed and the object is updated, the saved copy gives the user the opportunity to undo all of the changes made in the server. Support for the Undo command is provided by the client application, because the server application cannot maintain a record of the prior states of objects.

The Undo command restores an object to its condition prior to the last update from the server. To support this behavior, the client application must clone the object when it is first activated and then clone the updated object when an update occurs; the client must retain two clones of the object. The clone of the original object must be retained so that an updated object can be restored if the user chooses the Undo command. The clone of the updated object must also be retained to support the Undo command if the updated object is updated again.

Because the client application cannot distinguish between different types of object activation, the client application must clone an object for verbs that do not edit the object, even though no updates can occur in those cases.

Implementing a Links Command

When a user chooses the Links command from the Edit menu, the client application needs to display a Links dialog box listing every linked object in the document. The selected links are highlighted in the dialog box. The dialog box allows the user to select whether link updating should be automatic or manual, update a link immediately, cancel a link, and repair broken links. For more information about this dialog box, see OLE User Interface.

A client application can use the OleGetLinkUpdateOptions and OleSetLinkUpdateOptions functions to support the link-update radio buttons in the Links dialog box.

There are three possible update options for linked objects:

Option	Description

oleupdate_always	Update the linked object whenever possible. This option supports the Automatic link-update radio button in the Links dialog box.

oleupdate_onsave	Update the linked object when the source document is saved by the server application.

oleupdate_oncall	Update the linked object only on request from the client application. This option supports the Manual link-update radio button in the Links dialog box.

These update options control when updates occur to the presentation of an object. The contents of the source document are used to update the presentation whenever the link is activated.

To support the Update Now button in the Links dialog box, a client application can call the OleUpdate function. When a user chooses Update Now, the client application should update the links the user selected.

The Cancel Link button in the Links dialog box changes an object into a picture that an application cannot edit by using standard OLE techniques. An application can implement the Cancel Link button by using the OleObjectConvert function.

A client application should activate the Change Link button in the Links dialog box only if all the selected links are to the same source document. When the client has the correct information, it can repair the link by using the OleGetData and OleSetData functions.

To retrieve the link information for an object, a client application can call the OleGetData function, specifying the ObjectLink format. The call to OleGetData fails if ObjectLink is specified and the object is not a link. A client application can retrieve class information by using OleGetData and specifying either the OwnerLink format for embedded objects or the ObjectLink format for linked objects. The client application could allow the user to edit the link information and store it into the object by using the OleSetData function, specifying the ObjectLink format.

Implementing the Object Command

The Object command usually appears on the Edit menu. When an end user selects an object and pulls down the Edit menu, the Descriptive-Class-Name of the object can appear, followed by the word "Object", indicating that the object can be edited (or played). For example, if you selected an object whose Descriptive-Class-Name is MS WordArt, the command will be "MS WordArt Object."

When no object is selected, the command changes to "Object ..." and is dimmed (gray text indicating that the user cannot choose this command). If the object is activated, and the menu command is chosen, the object will be edited, played, or whatever action is desired, based on the choice of the primary verb. For most graphical objects, the verb is edit and, for sound, play.

A client application can implement the Descriptive-Class-Name Object command by using the OleActivate function. The second parameter of OleActivate allows the client to specify the verb chosen by the user. The parameter, a UINT, specifies which operation to perform (0 = the primary verb, 1 = the secondary verb, and so on).


Closing a Client Application

Before a client application closes a document and terminates itself, it should:

Call OleQueryOpen to   see if any of the document's objects are open in the server application.

Call OleUpdate once   for each opened object. OleUpdate obtains the current presentation format for the opened object.

Call OleRelease once   for each object. OleRelease closes the object if it is open, and tells the library to release any memory associated with the object. Closing an object terminates all DDE conversations with the object's server. OleRelease must be called for all objects, since it tells the library to release memory. Conveniently, OleRelease will also close an object if it is currently open in the server application.

Call OleRevokeClientDoc to   notify the client and server DLLs that the document is closed and no longer available. OleRevokeClientDoc takes as its parameter the handle to the document provided by a call to OleRegisterClientDoc.

A client application should call the OleRelease function for each object in the document to remove all objects from memory when it shuts down. If the client DLL returns OLE_WAIT_FOR_RELEASE instead of OLE_OK, the client application should not quit. While waiting for the OLE_RELEASE notification, the client can perform many cleanup tasks--for example, it can close files, free memory, and hide windows.

The OLE_RELEASE notification to the client application's callback function indicates that an operation has finished in a server application, but it does not identify the operation or indicate whether the operation was successful. A client application can call the OleQueryReleaseStatus function to determine whether an operation has been completed for a specified object. The OleQueryRelease function indicates the nature of the operation that has finished for a specified object. To discover the error value for the operation, the client application can call the OleQueryReleaseError function.

If a client application owns the clipboard when it quits, it should make sure that the data on the clipboard is complete and in the correct order.


Implementing Object Handlers

This topic contains information about OLE object handlers, which are DLLs that can replace all or part of a server application. After a brief overview, the operation of object handlers is explained, followed by an outline of the structure of a typical object handler, with examples and exceptions.

For more information, see the following topics:

Handler Overview

Sharing Tasks Between Handlers and Servers

Object Handler Operation

Creating an Object Handler


Handler Overview

Object handlers are DLLs that can be written to handle tasks that normally are done by a server. While there can be many reasons why you would wan t to intercept function calls to a server, the main reason is to avoid asynchronous communication between client and server DLLs. Object handlers also can be used to optimize output to a particular device, screen, or printer. Another use of handlers is to reduce object memory and file size by using only the native data for rendering and avoiding clipboard formats.

As shown in Figure 32, when a client application calls a function in the OLE client DLL (OLECLI32.DLL), the call goes through an API layer and into the matching function. For example, if a client application calls OleExecute , the OLECLI32.DLL takes the function call, checks certain parameters, and transfers the call to a function pointed to by OLEOBJECTVTBL inside OLECLI32.DLL (named Execute ). Asynchronous messages are sent to the server application via the OLE DLLs.

Figure 32. Normal OLE function calling

However, if an object handler is invoked, the handler has a copy of the OLEOBJECTVTBL and allows redirection of the OleExecute call. This redirection enables the incoming OleExecute call to go to the handler (or, if no redirection is indicated, to OLECLI32.DLL).

For a list of asynchronous functions, see the section "Handling Asynchronous Operations," in Implementing OLE into Client Applications.

In Figure 33, the OLEOBJECTVTBL has been copied to the handler. OLEOBJECT is a structure that normally points to the OLEOBJECTVTBL in the OLECLI32.DLL, but OLEOBJECT has been modified to point to the new OLEOBJECTVTBL in the handler. When OleExecute is called, the call is redirected to a new DllExecute function in HANDLER.DLL. Asynchronous communication between the OLE DLLs is avoided.

Figure 33. Object handler function calling

Note The implementation of the protocols and APIs used in support of object handlers are release-specific and may not be available in future versions of OLE.


Sharing Tasks Between Handlers and Servers

You can save the function pointer to the original copy of OLEOBJECTVTBL and call the original OLECLI32.DLL functions. For example, you may want to create your own DllDraw function, but you may still want to call the original Activate function. On the other hand, you might want to call the original GetData function from inside a new DllGetData function. For each function you can modify, you have the choice to substitute a new function, add functionality to the old function, or use the original function.

Figure 34 shows three options for a single object handler:

The DllDraw function completely takes over from the original Draw function.

The DllGetData function does some task and then lets the original GetData perform its tasks.

The Activate function is done by the original function in OLECLI32.DLL.

When you save the pointer to the VTBL, the VTBL pointers point to the original OLECLI32.DLL functions; any function pointer you do not change to point to your new functions will point back to the functions in OLECLI32.DLL.

Figure 34. Object handler function options


Object Handler Operation

Object handler operation requires the following three steps:

The handler must be registered with the registry.

The handler is loaded and initialized when the client application makes an object creation function call.

The handler's functions are called by specific object manipulation functions from the client application.

The following sections outline the steps necessary to create and use object handlers.

Registering Object Handlers

When an object handler is installed, the handler must register itself in the registry. The registration process is the same as for registering server applications, but the keyword handler32 must be used. For more information on registering object handlers, see Using the Registry.

For example, to register StdFileEditing protocol for a handler for a specific Class and Dllname, use the following format:

HKEY_CLASSES_ROOT\Class\protocol\StdFileEditing\handler32 = Dllname

Whenever a client application calls one of the object-creation functions, the client DLL uses the class specified for the object and the handler32 keyword to search the registry. If an object handler is found for the specific class, it is loaded and initialized.

Since handlers usually are designed to work with particular servers, the registry should be added to the related server entries.

Loading and Initializing Object Handlers

Normally, an object is manipulated by a server application through the client and server DLLs. However, if an object handler has been registered in the registry, the handler can take the place of the server.

Once registered, the handler is invoked when the client application calls one of the following eight object-creation functions:

OleCreate	OleCreateLinkFromClip

OleCreateFromClip	OleCreateLinkFromFile

OleCreateFromFile	OleCreateInvisible

OleCreateFromTemplate	OleLoadFromStream

As described later in this topic, all eight of these object-creation functions will have corresponding functions in the object handler.

For more information on object-creation functions, see Callback Functions and Data Structures, and The OLE Client DLL.

Object Manipulation Functions That Can Be Modified

Once the object handler has been invoked by one of the object-creation functions, a copy of the OLEOBJECTVTBL is created that includes pointers to the object-manipulation functions that can be modified. The following is a list of the object-manipulation functions.

Delete

SetHostNames

SaveToStream

Clone

CopyFromLink

Equal

CopyToClipboard

Draw

Activate

Execute

Close

Update

Reconnect

ObjectConvert

GetLinkUpdateOptions

SetLinkUpdateOptions

Rename

QueryName

QueryType

QueryBounds

QuerySize

QueryOpen

QueryOutOfDate

QueryReleaseStatus

QueryReleaseError

QueryReleaseMethod

RequestData

ObjectLong

Note:	All of the preceding functions correspond to OleFunctionName APIs, except for ObjectLong , which is provided for handlers and allows handler-specific data to be pointed to in the VTBL. For example, OleDraw is part of the OLECLI32.DLL API, and calls a function named Draw inside OLECLI32.DLL.

OLEOBJECTVTBL Example

The OLEOBJECTVTBL structure normally points to callback functions that the server application uses. If only a server application is being created, the constant SERVERONLY is defined with #DEFINE and the second half of OLEOBJECTVTBL (as define d in the header file, OLE.H) is not created.

To use the object manipulation functions (beginning with Delete), the handler must have a copy of OLEOBJECTVTBL and initialize it when the handler is invoked by one of the object-creation function calls from the client application. When creating a handler, do not define SERVERONLY by the #DEFINE preprocessor directive, or the object-creation half of the table will not be created.

Also, do not use the /DSERVERONLY command-line option when compiling an object handler.

The following sample code shows the OLEOBJECTVTBL structure, as defined in OLE.H:

typedef struct _OLEOBJECTVTBL

{

    void FAR* (CALLBACK* QueryProtocol)        (LPOLEOBJECT, LPSTR);

    OLESTATUS (CALLBACK* Release)              (LPOLEOBJECT);

    OLESTATUS (CALLBACK* Show)                 (LPOLEOBJECT, BOOL);

    OLESTATUS (CALLBACK* DoVerb)               (LPOLEOBJECT, UINT,

                                                     BOOL, BOOL);

    OLESTATUS (CALLBACK* GetData)              (LPOLEOBJECT,

                                                OLECLIPFORMAT,

                                                HANDLE FAR*);

    OLESTATUS (CALLBACK* SetData)              (LPOLEOBJECT,

                                                OLECLIPFORMAT, HANDLE);

    OLESTATUS (CALLBACK* SetTargetDevice)      (LPOLEOBJECT, HGLOBAL);

    OLESTATUS (CALLBACK* SetBounds)            (LPOLEOBJECT,

                                                OLE_CONST RECT FAR*);

    OLECLIPFORMAT  (CALLBACK* EnumFormats)     (LPOLEOBJECT,

                                                OLECLIPFORMAT);

    OLESTATUS (CALLBACK* SetColorScheme)       (LPOLEOBJECT, OLE_CONST

                                                LOGPALETTE FAR*);

    /* Server has to implement only the above methods. */

#ifndef SERVERONLY

    /* Extra methods required for client. */

    OLESTATUS (CALLBACK* Delete)           (LPOLEOBJECT);

    OLESTATUS (CALLBACK* SetHostNames)     (LPOLEOBJECT, LPSTR, LPSTR);

    OLESTATUS (CALLBACK* SaveToStream)     (LPOLEOBJECT, LPOLESTREAM);

    OLESTATUS (CALLBACK* Clone)            (LPOLEOBJECT, LPOLECLIENT,

                                            LHCLIENTDOC, LPSTR,

                                            LPOLEOBJECT FAR*);

    OLESTATUS (CALLBACK* CopyFromLink)     (LPOLEOBJECT, LPOLECLIENT,

                                            LHCLIENTDOC, LPSTR,

                                            LPOLEOBJECT FAR*);

    OLESTATUS (CALLBACK* Equal)            (LPOLEOBJECT, LPOLEOBJECT);

    OLESTATUS (CALLBACK* CopyToClipboard)  (LPOLEOBJECT);

    OLESTATUS (CALLBACK* Draw)             (LPOLEOBJECT, HDC,

                                            OLE_CONST RECT FAR*,

                                            OLE_CONST RECT FAR*, HDC);

    OLESTATUS (CALLBACK* Activate)         (LPOLEOBJECT, UINT, BOOL,

                                            BOOL, HWND,

                                            OLE_CONST RECT FAR*);

    OLESTATUS (CALLBACK* Execute)          (LPOLEOBJECT, HGLOBAL, UINT);

    OLESTATUS (CALLBACK* Close)            (LPOLEOBJECT);

    OLESTATUS (CALLBACK* Update)           (LPOLEOBJECT);

    OLESTATUS (CALLBACK* Reconnect)        (LPOLEOBJECT);

    OLESTATUS (CALLBACK* ObjectConvert)    (LPOLEOBJECT, LPSTR,

                                            LPOLECLIENT, LHCLIENTDOC,

                                            LPSTR, LPOLEOBJECT FAR*);

    OLESTATUS (CALLBACK* GetLinkUpdateOptions) (LPOLEOBJECT,

                                                OLEOPT_UPDATE FAR*);

    OLESTATUS (CALLBACK* SetLinkUpdateOptions) (LPOLEOBJECT,

                                                OLEOPT_UPDATE);

    OLESTATUS (CALLBACK* Rename)           (LPOLEOBJECT, LPSTR);

    OLESTATUS (CALLBACK* QueryName)        (LPOLEOBJECT, LPSTR,

                                            UINT FAR*);

    OLESTATUS (CALLBACK* QueryType)        (LPOLEOBJECT, LONG FAR*);

    OLESTATUS (CALLBACK* QueryBounds)      (LPOLEOBJECT, RECT FAR*);

    OLESTATUS (CALLBACK* QuerySize)        (LPOLEOBJECT, DWORD FAR*);

    OLESTATUS (CALLBACK* QueryOpen)        (LPOLEOBJECT);

    OLESTATUS (CALLBACK* QueryOutOfDate)   (LPOLEOBJECT);

    OLESTATUS (CALLBACK* QueryReleaseStatus) (LPOLEOBJECT);

    OLESTATUS (CALLBACK* QueryReleaseError)  (LPOLEOBJECT);

    OLE_RELEASE_METHOD (CALLBACK* QueryReleaseMethod)(LPOLEOBJECT);

    OLESTATUS (CALLBACK* RequestData)      (LPOLEOBJECT, OLECLIPFORMAT);

    OLESTATUS (CALLBACK* ObjectLong)       (LPOLEOBJECT, UINT,

                                            LONG FAR*);

/* This method is internal only */

    OLESTATUS (CALLBACK* ChangeData)       (LPOLEOBJECT, HANDLE,

                                            LPOLECLIENT, BOOL);

#endif  /* !SERVERONLY */

} OLEOBJECTVTBL;


Creating an Object Handler

An object handler DLL must have the normal structure of a dynamic-link library. In addition, it must have the following sections:

Object creation callback functions (DllCreate, DllCreateFromClip, and so on)

Function to copy OLEOBJECTVTBL

Object manipulation callback functions

Any other functions that are used inside the DLL

The following sections provide details on the special functions that must be in the object handler DLL.

Object-Creation Functions in the Handler

All eight of the object-creation functions must be included in the handler, since a client could call any object-creation function. All of the object-creation functions must be put into the object handler as functions with the Dll prefix. Once a handler has been registered, any calls to the original object-creation functions (prefixed with Ole) will be redirected to the new object-creati on functions in the handler (prefixed with Dll).

The following table lists the object-creation function names when used with object handlers:

Original Function Name	Handler Object-Creation Function Name

OleCreate	DllCreate

OleCreateFromClip	DllCreateFromClip

OleCreateFromFile	DllCreateFromFile

OleCreateFromTemplate	DllCreateFromTemplate

OleCreateLinkFromClip	DllCreateLinkFromClip

OleCreateLinkFromFile	DllCreateLinkFromFile

OleCreateInvisible	DllCreateInvisible

OleLoadFromStream	DllLoadFromStream

Object-Creation Aliases

The original object-creation functions in OLECLI32.DLL must also be called in the handler object-creation function code. Since object-creation functions with the Ole prefix are redirected to the handler, the calls to the original functions use the Def prefix, which is set up by OLECLI32.DLL as an alias. Each object creation-function code block in the handler must include at the very beginning a function call to the alias of the original object-creation function using the prefix Def.

The following table lists the object-creation alias names:

Original Function Name	Object-Creation Alias Function Name

OleCreate	DefCreate

OleCreateFromClip	DefCreateFromClip

OleCreateFromFile	DefCreateFromFile

OleCreateFromTemplate	DefCreateFromTemplate

OleCreateLinkFromClip	DefCreateLinkFromClip

OleCreateLinkFromFile	DefCreateLinkFromFile

OleCreateInvisible	DefCreateInvisible

OleLoadFromStream	DefLoadFromStream

Object-Creation Code Structure

The following pseudocode shows the structure that each object-creation function in the handler must follow. There must be a call to the OLECLI32.DLL object-creation function alias (using the Def prefix) and there must also be a call to a function to copy the OLEOBJECTVTBL. Additional code can also be used to provide extra functionality to any of the object-creation functions.

DllCreateFunctionName(parameters)

{

        DefCreateFunctionName(parameters);

        CopyVTBLFunction;

        AdditionalCode;

}

Note The object handler must contain Dll calls to all eight of the object-creation functions. OLECLI32.DLL checks to see if all eight object-creation functions are in the handler with the Dll prefix. If they are not, the handler is unloaded and ignored.

Copying the OLEOBJECTVTBL

The object handler must contain a function that copies the OLEOBJECTVTBL from the OLECLI32.DLL to the object handler. Do not attempt to modify the original OLEOBJECTVTBL in the OLECLI32.DLL as other objects may be using it while your handler is in operation. The CopyVTBL function (or your renamed variation) is called from every object-creation function in the handler.

The CopyVTBL function must do the following:

Make a working copy of OLEOBJECTVBL

Save the pointer to the original OLEOBJECTVTBL

Change the pointers in the working copy to point to your new object creation functions

The following pseudocode shows the structure of the CopyVTBL function. When the handler is created, a pointer to OLEOBJECT is passed to the handler (lpobj).

CopyVTBL (lpobj)

{

        lpvtblDef = lpobj->lpvtbl;      /* Original OLEOBJECTVTBL     */

        vtblDLL = *lpobj->lpvtbl;       /* Make copy of OLEOBJECTVTBL */

        vtblDLL.Draw = DllDraw;         /* change individual pointer  */

        vtblDLL.GetData = DllGetData;   /* change another pointer     */

}

Note Only the pointers for the individual object-manipulation functions that will appear in the object handler must be changed. The new object-manipulation functions do not need to have the Dll prefix; since OLEOBJECTVTBL will point to the modified function when called by the OLE APIs in OLECLI32.DLL.

Object-Manipulation Functions in Handler

The handler object-manipulation functions take the place of the original object-manipulation functions in the OLECLI32DLL.

The following pseudocode shows a typical handler object-manipulation function that calls one of the original OLECLI32.DLL object-manipulation functions.

DllDraw(parameters)

{

        lpvtblDef->GetData(cfNative, &hNative);      /* Get native data */

        UseNativeDataToDraw;                         /* Draw with it    */

        Return OLE_OK;

}

To write a function that calls the original function from the OLECLI32.DLL but allows the ability to modify the function, use the following pseudocode.

DllGetData(parameters)

{

        lpvtblDef->GetData(parameters);   /* Use the pointer from */

                                            the backup copy of

                                            OLEOBJECTVTBL        */

        AdditionalCoding;                /* After you get call

                                            original function,

                                         ...manipulate   */

        Return OLE_OK;

}

Note Any pointers to functions not modified in the handler VTBL will point to the original functions in OLECLI32.DLL. You do not need to write a function that just calls the original function.

Adding Protocols with Object Handlers

A handler may implement additional protocols and override the QueryProtocol function to give client applications access to new protocols. If the client requests a protocol that the handler has defined, the handler must allocate a data structure and set the first entry to be a pointer to a VTBL structure, which contains pointers to functions for the new protocol. The pointer to the allocated structure should be returned as the value of the QueryProtocol function. The handler must ensure that the data structure is freed when the object is released. The handler may use the ObjectLong function to associate additional data with the original OLEOBJECT structure.

Special Exceptions

Most of the object-creation functions in the client DLL work in the same way when they are renamed and used by object-handler DLLs. However, as described in the following sections, the DefCreateFromClip (renamed from OleCreateFromClip ) and DefLoadFromStream (renamed from OleLoadFromStream) functions work differently.

DefCreateFromClip and DllCreateFromClip

When the client DLL calls the DllCreateFromClip function, it includes the objtype parameter that is not specified in the original call to the OleCreateFromClip function. This parameter specifies whether the object being created is an embedded object or a link to an object; its value can be either OT_LINK or OT_EMBEDDED.

The following syntax block shows the objtype parameter when an object handler uses the DefCreateFromClip function. The DllCreateFromClip function has exactly the same syntax as DefCreateFromClip.

For a full description of all the parameters, see the OleCreateFromClip function.

OLESTATUS DefCreateFromClip(lpszProtocol, lpclient,

                            lhclientdoc, pszObjname,

                            lplpobject, renderopt, cfFormat,

                            objtype);

LPSTR lpszProtocol;           // pointer to string for

                              // protocol name

LPOLECLIENT lpclient;         // pointer to client structure

LHCLIENTDOC lhclientdoc;      // long handle to client

                              // document

LPSTR lpszObjname;            // string for object name

LPOLEOBJECT FAR * lplpObject; // pointer to pointer to

                              // object

OLEOPT_RENDER renderopt;      // rendering options

OLECLIPFORMAT cfFormat;       // clipboard format

LONG objtype;                 // OT_LINKED or OT_EMBEDDED

If DllCreateFromClip calls DefCreateFromClip, DllCreateFromClip should pass it the objtype parameter along with the other parameters from the version of DefCreateFromClip that was exported by the client DLL.

DllCreateFromClip can modify some of these parameters before passing them back to DefCreateFromClip. For example, the object handler could specify a different value for the renderopt parameter when it calls DefCreateFromClip. If the client calls DefCreateFromClip with olerender_draw for renderopt and the handler performs the drawing with Native data, the handler could change olerender_draw to olerender_none if the handler performs the drawing with native data.

If the client DLL calls DefCreateFromClip with olerender_draw for renderopt (and the handler calls the GetData function and performs the drawing based on a class-specific format), the handler could change olerender_draw to olerender_format . If the handler needed a different rendering format than that specified by the client application, the object handler could also change the value of the cfFormat parameter in the call to DefCreateFromClip.

If an object handler uses native data to render an embedded object, the handler can call the client DLL and specify olerender_none . If a handler uses native data to render a linked object, it can use olerender_format and specify native data. When the handler's Draw function is called, the handler calls the GetData function, specifying native data, to do the rendering. If a handler uses a private data format, the procedure is the same--except that the private format is specified with the olerender_format option and with the GetData function.

DefLoadFromStream and DllLoadFromStream

When the client DLL calls the DllLoadFromStream function, it includes three parameters that are not specified in the original call to the OleLoadFromStream function. One of the additional parameters is objtype, as previously described for DefCreateFromClip and DllCreateFromClip. The other two are aClass, which is an atom containing the class for the object, and cfFormat, which specifies a private clipboard format that the object handler can use for rendering the object.

The following syntax block shows the objtype, aClass, and cfFormat parameters when an object handler uses the DefLoadFromStream function. The DllLoadFromStream function has exactly the same syntax as DefLoadFromStream.

For a full description of all the parameters, see the OleLoadFromStream function.

OLESTATUS DefLoadFromStream(lpstream, lpszProtocol,

                            lpclient, lhclientdoc,

                            pszObjname, lplpobject, objtype,

                            aClass, cfFormat);

LPOLESTREAM lpstream;        // pointer to stream for object

LPSTR lpszProtocol;          // pointer to string for

                             // protocol name

LPOLECLIENT lpclient;        // pointer to client structure

LHCLIENTDOC lhclientdoc;     // long handle to client

                             // document

LPSTR lpszObjname;           // string for object name

LPOLEOBJECT FAR * lplpobject;// pointer to pointer to object

LONG objtype;                // OT_LINKED or OT_EMBEDDED

ATOM aClass;                 // atom containing object's

                             // class name

OLECLIPFORMAT cfFormat;      // private data format for

                             // rendering

If DllLoadFromStream calls DefLoadFromStream, DllLoadFromStream should pass it the three additional parameters along with the other parameters from the version of DefLoadFromStream that was exported by the client DLL. DllLoadFromStream can modify some of these parameters before passing them back to DefLoadFromStream.

For example, the object handler could modify the value of the cfFormat parameter to specify a private data format it would use to render the object.

When the client application calls the object handler with DefLoadFromStream, the handler uses the Get function from the OLESTREAMVTBL structure to obtain the data for the object.


Callback Functions and Data Structures

This topic describes the OLE data structures and callback functions that are used to communicate with the client and server applications.

OLE uses data structures that are Virtual Tables (VTBLs) to store pointers to OLE functions and OLE application callback functions. The first part of this topic outlines the various data structures that OLE uses, and is divided into structures that are used by server applications and VTBLs that are used by client applications.

Server data structures include:

OLESERVER	OLESERVERVTBL

OLESERVERDOC	OLESERVERDOCVTBL

OLEOBJECT	OLEOBJECTVTBL

Client data structures include:

OLESTREAM	OLESTREAMVTBL

OLECLIENT	OLECLIENTVTBL

Note:	The OLE data structures work in pairs; the first structure contains a pointer to the second ( for example, OLESERVER points to OLESERVERVTBL). The second structure (StructureNameVTBL) contains pointers to member functions.

The second part of this topic is a listing of all the OLE callback functions and situations that cause a callback function to be called. The sequence of callback functions is given, since callbacks take place in a definite order that you must understand to code OLE applications efficiently.

For more information, see the following topics:

Data Structures Set Up by the Server Application

Data Structures for Client Applications

Actions that Invoke Server Callbacks Functions


Data Structures Set Up by the Server Application

Communication from the OLE server DLL to server applications is done through callback functions. Callback functions, a standard Windows programming mechanism, are called directly from the server DLLs. You will need to add callbacks to your code so that the OLE DLLs can provide data to your application as well as let your application perform specific operations with that data.

When a server application is invoked, it provides the OLESVR32.DLL with a data structure called a virtual table(VTBL). This VTBL contains a table of pointers to the application's callback functions. The server DLL uses these pointers to locate the application's callback functions.

For example, a server application fills a specific data structure (OLESERVERDOCVTBL ) with pointers to a set of callback functions that provide object level support. These callbacks include Save, Close, SetHostNames, SetDocDimensions, GetObject, Release, SetColorScheme, and Execute , all of which are described later in this topic.

Once the application passes the initialized VTBL to the server DLL, the DLL can call any of the functions pointed to in the table. The VTBLs allow the DLLs to call a defined set of callback functions that all OLE applications support, but which differ in operation depending on the specific needs of the application and the class of object being linked or embedded.

For a discussion of actions that affect the calling of these functions, see Actions that Invoke Server Callbacks Functions

The server application must set up the following data structures, the prototypes of which are defined in OLE.H:

Structure Name	Contents, as defined in OLE.H

OLESERVER	A single pointer (LPOLESERVERVTBL) to the OLESERVERVTBL structure.

OLESERVERVTBL	Far pointers to the server callback functions.

OLESERVERDOC	A single pointer (LPOLESERVERDOCVTBL) to the document functions VTBL.

OLESERVERDOCVTBL	Far pointers to the document callback functions.

OLEOBJECT	A single pointer (LPOLEOBJECTVTBL) to the object functions VTBL.

OLEOBJECTVTBL	Far pointers to the object callback functions.

VTBLS and Functions for Server Applications

The members of the three VTBLs created by the server application-- OLESERVERVTBL, OLESERVERDOCVTBL, and OLEOBJECTVTBL-- contain the far pointers to callback functions for the server, server documents, and objects. You will need to code these functions so that OLESVR32.DLL can make meaningful calls into your application.

The folllowing table lists each of the VTBLs and the callback functions pointed to by them:

OLESERVERVTBL

Function	Purpose

Open	Opens an existing file and prepares to edit the contents.

Create	Makes a new object that will be embedded in the client application.

CreateFromTemplate	Creates a new document that is initialized with the data in a specified file.

Edit	Creates a document.

Exit	Instructs the server application to close documents and terminate.

Release	Notifies a server application that all connections to it have closed and that it is safe to terminate.

Execute	Specifies DDE execute strings.

OLESERVERDOCVTBL

Function	Purpose

Save	Instructs the server application to save the document.

Close	Instructs the server application to unconditionally close the document.

SetHostNames	Sets the names that should be used for window titles.

SetDocDimensions	Gives the serve r application the rectangle on the target device for which the object should be formatted.

GetObject	Requests the server application to create an OLEOBJECT structure.

Release	Notifies the server application when a revoked document has terminated. (Conversations may be destroyed.)

SetColorScheme	Specifies the color selection preferred by the client application.

Execute	Specifies DDE execute strings.

OLEOBJECTVTBL

Function	Purpose

QueryProtocol	Indicate which protocols the server application supports.

Release	Frees the resources associated with the specified OLEOBJECT structure.

Show	Causes the server application to show an object.

DoVerb	Specifies what kind of action the server application should take when a user opens an object.

GetData	Retrieves data from an object in a specified format.

SetData	Stores data in an object in a specified format.

SetTargetDevice	Communicates information about the client application's target device for the object.

SetBounds	Provided for compatibility only.

EnumFormats	Enumerates the data formats that the object can render.

SetColorScheme	Specifies the palette to be used when the server application edits the specified object.

Object Data Structures

As shown in Figure 35, an object consists of the following three distinct data structures:

An OLEOBJECTVTBL structure that contains only pointers to the object callback functions.

An OLEOBJECT structure, which contains only a pointer to OLEOBJECTVTBL.

A wrapper structure that you define (OBJ) to contain the OLEOBJECT structure, and other members to hold any application specific data you want associated with the object.

Figure 35. An OLEOBJECTVTBL, OLEOBJECT structure, and wrapper structure (OBJ)

The following code example, taken from the OLE.H header file, shows the definition of the OLEOBJECTVTBL structure for a single function (GetData).

typedef struct _OLEOBJECTVTBL

{

    .

    .

    .

 OLESTATUS (CALLBACK* GetData) (LPOLEOBJECT, OLECLIPFORMAT,

                                HANDLE FAR*);

    .

    .

    .

} OLEOBJECTVTBL;

In OLEOBJECTVTBL, GetData is a callback function that OLESVR32.DLL will call when the server application needs to retrieve data from an object.

The following code example, also shown for illustration and included in the header file OLE.H, defines the OLEOBJECT data structure that points to OLEOBJECTVTBL:

typedef  OLEOBJECTVTBL FAR* LPOLEOBJECTVTBL;

  .

  .

  .

typedef struct _OLEOBJECT

{

    LPOLEOBJECTVTBL    lpvtbl;

} OLEOBJECT;

You can define the wrapper structure for the OLEOBJECTVTBL as follows:

typedef struct _OBJ

{

  OLEOBJECT oleobject;  // OLE's part must come first!

    //

    // Your member functions go here.

    //

} OBJ;

The data structures and VTBLs shown in the preceding code examples correspond to an object created by the server application. Additional VTBLs required to be setup by server and client applications include:

Server VTBLs	Purpose

OLESERVERVTBL	Contains pointers to the callback functions used to start and control server applications.

OLESERVERDOCVTBL	Contains pointers to the callback functions used to manipulate objects.

Client VTBLs	Purpose

OLECLIENTVTBL	Contains a pointer to the client application's CallBack function.

OLESTREAMVTBL	Contains pointers to the storage and retrieval callback functions.

These data structures are described later in this topic under their respective headings.

Note  Each VTBL has a corresponding structure that points to it--for example, the OLESERVERVTBL structure has an OLESERVER structure that consists of a single, far pointer, LPOLESERVERVTBL.

Multiple Instances of Objects

Since a server or client application may need to deal with more than one object simultaneously, they need more than one instance of the wrapper data structure-- one instance of the wrapper data structure for each object. When an OLE DLL makes a callback function call, it passes a pointer to the callback function that references the wrapper corresponding to the object.

While it makes sense to have unique instances of the wrappers for each object, document, server, client, and stream, it is not necessary to have multiple instances of the VTBL structure. All instances of a given type of wrapper can refer to the same VTBL structure. For example, all server applications must provide the OLEOBJECTVTBL, similar to that shown in Figure 36. Most server applications will need multiple instances of the wrapper structures, such as the OBJ structure shown wrapping the OLEOBJECT structure.

Figure 36. Unique object wrappers and a shared object VTBL

Each OBJ wrapper can contain the same OLEOBJECT structure, which points to one OLEOBJECTVTBL structure. The server application can have multiple wrapper instances that share the same VTBL structure.

Note:	Client and server applications are responsible for providing memory for the data structures associated with the VTBLs. VTBLs may be kept in the application's data segment, either as global variables or as dynamically allocated blocks on the global heap.


OLESERVER structure

The OLESERVER structure is defined in the header file, OLE.H. lpvtbl in the OLESERVER structure points to a table of function pointers for the server application. This structure is initialized and maintained by the server application for OLESVR32.DLL.

OLE.H defines the OLESERVER data structure as follows:

typedef struct _OLESERVER

{

    LPOLESERVERVTBL lpvtbl;

} OLESERVER;


OLESERVERVTBL structure

The following code example shows the OLESERVERVTBL data structure as defined in OLE.H. This structure points to application-specific callback functions that are used to manipulate a server application. After a server application creates this structure and a corresponding OLESERVER structure (which points to OLESERVERVTBL), the server DLL can make calls to the server application.

typedef struct _OLESERVERVTBL

{

    OLESTATUS (CALLBACK* Open)  (LPOLESERVER, LHSERVERDOC, LPSTR,

                                 LPOLESERVERDOC FAR*);

                        /* long handle to doc(privtate to DLL)  */

                        /* lp to OLESERVER                      */

                        /* document name                        */

                        /* place holder for returning oledoc.   */

    OLESTATUS (CALLBACK* Create)(LPOLESERVER, LHSERVERDOC, LPSTR, LPSTR,

                                 LPOLESERVERDOC FAR*);

                        /* long handle to doc(privtate to DLL)  */

                        /* lp to OLESERVER                      */

                        /* lp class name                        */

                        /* lp doc name                          */

                        /* place holder for returning oledoc.   */

    OLESTATUS (CALLBACK* CreateFromTemplate)(LPOLESERVER,

           LHSERVERDOC, LPSTR, LPSTR, LPSTR, LPOLESERVERDOC FAR*);

                        /* long handle to doc(privtate to DLL)  */

                        /* lp to OLESERVER                      */

                        /* lp class name                        */

                        /* lp doc name                          */

                        /* lp template name                     */

                        /* place holder for returning oledoc.   */

    OLESTATUS (CALLBACK* Edit)  (LPOLESERVER, LHSERVERDOC, LPSTR,

                                 LPSTR, LPOLESERVERDOC FAR*);

                        /* long handle to doc(privtate to DLL)  */

                        /* lp to OLESERVER                      */

                        /* lp class name                        */

                        /* lp doc name                          */

                        /* place holder for returning oledoc.   */

    OLESTATUS (CALLBACK* Exit)  (LPOLESERVER);

                        /* lp OLESERVER                         */

    OLESTATUS (CALLBACK* Release)  (LPOLESERVER);

                        /* lp OLESERVER                         */

    OLESTATUS (CALLBACK* Execute)(LPOLESERVER, HGLOBAL);

                        /* lp OLESERVER                         */

                        /* handle to command strings            */

} OLESERVERVTBL;

OLESERVERVTBL Members

The following table lists the OLESERVERVTBL data structure members; each member points to a specific callback function.

Member	Description

Open	Opens an existing document in preparation for editing.

Create	Opens a new document.

CreateFromTemplate	Creates a new document and initializes it with the data from a specified file.

Edit	Creates a document that is initialized with data retrieved by a subsequent call to the SetData function.

Exit	Instructs the server application to close documents and terminate (simply terminate if no documents are registered).

Release	Notifies a server that all connections to it have closed and that it is safe to terminate.

Execute	Specifies DDE execute strings.

You will need to code these functions to the meet the needs of your application.


OLESERVERVTBL Open callback function

OLESTATUS Open(lpServer, lhDoc, lpszDoc, lplpDoc)

LPOLESERVER lpServer;
LHSERVERDOC lhDoc;
LPSTR lpszDoc;
LPOLESERVERDOC FAR* lplpDoc;

The Open function opens an existing file and prepares to edit the contents. This function typically opens a linked object for a client application.

Parameter	Description

lpServer	Points to an OLESERVER structure identifying the server application.

lhDoc	Identifies the document; the server DLL uses this handle internally.

lpszDoc	Points to a null-terminated string specifying the pathname of the document to be opened. Normally this string is a pathname to a file, but for some applications it might specify other data-- for example, a particular table in a database.

lplpDoc	Points to a variable of type LPOLESERVERDOC in which the server application returns a pointer to the OLESERVERDOC structure it has created in response to this function.

When the server DLL calls this function, the server application opens the specified document, allocates and initializes an OLESERVERDOC structure, associates the handle lhDoc with the document, and returns the address of the structure.

The server application does not show the document or its window.

The return value is OLE_OK if successful; otherwise, it is an error value.


OLESERVERVTBL Create callback function

OLESTATUS Create(lpServer, lhDoc, lpszClass, lpszDoc, lplpDoc)

LPOLESERVER lpServer;
LHSERVERDOC lhDoc;
LPSTR lpszClass;
LPSTR lpszDoc;
LPOLESERVERDOC FAR* lplpDoc;

The Create function creates a new server document.

Parameter	Description

lpServer	Points to an OLESERVER structure identifying the server application.

lhDoc	Identifies the document. The server DLL uses this handle internally.

lpszClass	Points to a null-terminated string specifying the class of document to create.

lpszDoc	Points to a null-terminated string specifying a name for the document to be created. This name can be used to identify the document in window titles.

lplpDoc	Points to an LPOLESERVERDOC where the server application should return a long pointer to the created OLESERVERDOC structure.

When the server DLL calls this function, the server application creates a document of a specified class, allocates and initializes an OLESERVERDOC structure, associates the handle with the document, and returns the address of the structure. This function opens the created document for editing and embeds it in the client application document when it is updated or closed.

The server should perform the following steps:

1	Create a document of a specified class.

2	Allocate and initialize an OLESERVERDOC structure and its associated OLESERVERDOCVTBL.

3	Save the lhDoc parameter for future use.

4	Return a pointer to the OLESERVERDOC via the lplpDoc parameter.

The return value is OLE_OK if successful; otherwise, it could be OLE_ERROR_NEW.


OLESERVERVTBL CreateFromTemplate callback function

OLESTATUS CreateFromTemplate(lpServer, lhDoc, lpszClass, lpszDoc, lpszTemplate, lplpDoc)

LPOLESERVER lpServer;
LHSERVERDOC lhDoc;
LPSTR lpszClass;
LPSTR lpszDoc;
LPSTR lpszTemplate;
LPOLESERVERDOC FAR* lplpDoc;

CreateFromTemplate creates a new object from a template (usually using OleCreateFromTemplate).

Parameter	Description

lpServer	Points to an OLESERVER structure identifying the server application.

lhDoc	Identifies the document. The DLL uses this handle internally.

lpszClass	Points to a null-terminated string specifying the class of document to create.

lpszDoc	Points to a null-terminated string specifying the name for the document to be created. This name can be used in window titles and so on.

lpszTemplate	Points to a null-terminated string specifying the permanent name of the document to use when initializing the new document. Normally this string is a pathname, but for some applications it might be further qualified--for example, the string might specify a particular table in a database.

lplpDoc	Points to an LPOLESERVERDOC where the server application should return a long pointer to the created OLESERVERDOC structure.

In response to this call, the server application creates a new document that is initialized with the data from a specified file. The new document is opened for editing by this function. When the server DLL calls this function, the server application should perform the following steps:

1	Create a document of specified class.

2	Read the contents of the specified file and use it to initialize the document.

3	Allocate and initialize an OLESERVERDOC structure.

4	Save the lhDoc for future use.

5	Return a pointer to the OLESERVERDOC via the lplpDoc parameter.

The return value is OLE_OK if successful; otherwise it could be OLE_ERROR_TEMPLATE.


OLESERVERVTBL Edit callback function

OLESTATUS Edit(lpServer, lhDoc, lpszClass, lpszDoc, lplpDoc)

LPOLESERVER lpServer;
LHSERVERDOC lhDoc;
LPSTR lpszClass;
LPSTR lpszDoc;
LPOLESERVERDOC FAR* lplpDoc;

The Edit function creates a document that is initialized with data retrieved by a subsequent call to the SetData function.

Parameter	Description

lpServer	Points to an OLESERVER structure identifying the server application.

lhDoc	Identifies the document. The DLL uses this handle internally.

lpszClass	Points to a null-terminated string specifying the class of document to create.

lpszDoc	Points to a null-terminated string specifying a name for the document to be created. This name may be used in window titles and so on.

lplpDoc	Points to an LPOLESERVERDOC where the server application should return a long pointer to the created OLESERVERDOC structure.

The server application does not show the document or its window in response to this call. In response to a call to Edit, the server application needs to create a new server document by doing the following steps:

1	Create a document of the specified class.

2	Allocate and initialize an OLESERVERDOC structure.

3	Save the lhDoc for future use.

4	Return a pointer to the OLESERVERDOC via the lplpDoc parameter.

The document created by the Edit function retrieves the initial data from the client application in a subsequent call to the SetData function. The user can edit the document when the data has been retrieved and the DLL uses the Show function in the OLEOBJECTVTBL structure (or the DoVerb function with an "edit" verb) to show the document to the user.

The return value is OLE_OK if successful; otherwise it could be OLE_ERROR_EDIT.


OLESERVERVTBL Exit callback function

OLESTATUS Exit(lpServer)

LPOLESERVER lpServer;

The Exit function instructs the server application to close documents and terminate.

Parameter	Description

lpServer	Points to an OLESERVER structure identifying the server application.

If the server application has no open documents when the Exit function is called, it should call OleRevokeServer.

In response to a call to Exit, the server application should perform the following steps:

1	Call OleRevokeServer, which will eventually cause Release to be called (OLE_WAIT_FOR_RELEASE can be ignored).

2	Do whatever is required to terminate the application such as post a WM_CLOSE message or call a termination routine. It is legal to call DestroyWindow or PostQuitMessage from within Exit.

The return value is OLE_OK if successful; otherwise it could be OLE_ERROR_GENERIC.


OLESERVERVTBL Release callback function

OLESTATUS Release(lpServer)

LPOLESERVER lpServer;

The Release function notifies the server application that all connections to it have closed and that it is safe to terminate.

Parameter	Description

lpServer	Points to an OLESERVER structure identifying the server application.

Generally, the server DLL calls the Release function when it is safe for a server application to terminate. When a server application calls the OleRevokeServer function, it must wait, dispatching messages, for the DLL to call the Release function before terminating.

If the server application has already called OleRevokeServer when Release is called, then it can terminate. If Release is called before the server application has called OleRevokeServer, then rather than terminating, it must call OleRevokeServer before returning from Release.

If the server application has already called OleRevokeServer, it should respond to a subsequent Release call by performing the following steps:

1	Free any resources associated with lpServer, including the OLESERVER structure if it was dynamically allocated.

2	Set a release status flag, if appropriate. (Many applications keep a flag indicating the release status of the server.)

3	Do whatever is necessary to terminate -for example, posting a WM_CLOSE message would be one way to terminate an application.

If the server application has not called OleRevokeServer, the following actions apply:

If the server application is invisible when the DLL calls Release, it must call OleRevokeServer and return. (The only exception is when an application supports multiple server applications; in which case, an invisible server application is sometimes not revocable when the DLL calls Release.)

If the server application has no open documents and was started with the /Embedding option (indicating that it was started by a client application), it should call OleRevokeServer and return when the DLL calls Release.

Note:	If the preceding conditions are not present and the server application has not yet called OleRevokeServer, or conditions are not present and the user has explicitly loaded a document into a single-instance MDI server application, then the server should neither terminate nor call OleRevokeServer.

All registered server structures must be released before a server can terminate.

A server can call the PostQuitMessage function inside the Release function.

The return value is OLE_OK if successful; otherwise it could be OLE_ERROR_GENERIC.


OLESERVERVTBL Execute callback function

OLESTATUS Execute(lpServer, hCommands)

LPOLESERVER lpServer;

The Execute function sends the server application one or more DDE execute commands.

Parameter	Description

lpServer	Points to an OLESERVER structure identifying the server application.

hCommands	Identifies memory containing one or more DDE execute commands.

The server application should never free the handle specified in the hCommands parameter.

The return value is OLE_OK if successful; otherwise, it is an error value.


OLESERVERDOC structure

The OLESERVERDOC structure is defined in the header file, OLE.H. The lpvtbl member in the OLESERVERDOC structure points to a table of function pointers for a document. This structure is initialized and maintained by the server application for OLESVR32.DLL.

OLE.H defines the OLESERVERDOC data structure as follows:

typedef struct _OLESERVERDOC{

    LPOLESERVERDOCVTBL lpvtbl;

} OLESERVERDOC;

See Also

OLESERVERDOCVTBL


OLESERVERDOCVTBL structure

The OLESERVERDOCVTBL structure points to functions that manipulate a document. After a server application creates this structure and a corresponding OLESERVERDOC structure (which points to OLESERVERDOCVTBL), the OLESVR32.DLL can access a document. The OLESERVERDOCVTBL structure is defined in OLE.H as follows:

typedef struct _OLESERVERDOCVTBL

{

    OLESTATUS (CALLBACK* Save)      (LPOLESERVERDOC);

    OLESTATUS (CALLBACK* Close)     (LPOLESERVERDOC);

    OLESTATUS (CALLBACK* SetHostNames)(LPOLESERVERDOC, LPSTR, LPSTR);

    OLESTATUS (CALLBACK* SetDocDimensions)(LPOLESERVERDOC,

                                           OLE_CONST RECT FAR*);

    OLESTATUS (CALLBACK* GetObject) (LPOLESERVERDOC, LPSTR,

                                     LPOLEOBJECT FAR*, LPOLECLIENT);

    OLESTATUS (CALLBACK* Release)   (LPOLESERVERDOC);

    OLESTATUS (CALLBACK* SetColorScheme)(LPOLESERVERDOC,

                                         OLE_CONST LOGPALETTE FAR*);

    OLESTATUS (CALLBACK* Execute)  (LPOLESERVERDOC, HGLOBAL);

} OLESERVERDOCVTBL;

Documents opened or created on request from the server DLL should not be shown to the user for editing until the DLL requests that they be shown.

Every function except Release can return OLE_BUSY.

OLESERVERDOCVTBL Members

The OLESERVERDOCVTBL data structure contains the following members, with each member pointing to an application-specific callback function:

Structure Member	Description

Save	Instructs the server to save the document.

Close	Instructs the server application to unconditionally close the document.

SetHostNames	Sets the names that should be used for window titles.

SetDocDimensions	Gives the server the rectangle on the target device for which the object should be formatted.

GetObject	Requests the server to create an OLEOBJECT structure and associate with an object.

Release	Notifies the server when a revoked document has terminated conversations and object resources can be freed.

SetColorScheme	Specifies the color palette preferred by the client application.

Execute	Specifies DDE execute strings.

You will need to code these functions to meet the needs of your application.


OLESERVERDOCVTBL Save callback function

OLESTATUS Save(lpDoc)

LPOLESERVERDOC lpDoc;

The Save function instructs the server application to save the document.

Parameter	Description

lpDoc	Points to an OLESERVERDOC structure corresponding to the document to save.

This callback is only invoked when a linked object is being edited, so it is assumed that the server application already knows the object's filename. In response, the server application should save the specified document.

The return value is OLE_OK if successful; otherwise, it could be OLE_ERROR_GENERIC.


OLESERVERDOCVTBL Close callback function

OLESTATUS Close(lpDoc)

LPOLESERVERDOC lpDoc;

The Close function instructs the server application to unconditionally close the document.

Parameter	Description

lpDoc	Points to an OLESERVERDOC structure corresponding to the document to close.

The server DLL calls this function when the client application initiates the closure. lpDoc points to an OLESERVERDOC structure corresponding to the document to close.

When the server DLL calls the Close function, the server application should respond by calling OleRevokeServerDoc. The resources for the document are freed when the DLL calls the Release callback function. The server should not wait for the Release function by entering a message-dispatch loop after calling OleRevokeServerDoc. (Message-dispatch loops should never be entered while processing any of these functions.)

The return value is OLE_OK if successful; otherwise, it is an error value.


OLESERVERDOCVTBL SetHostNames callback function

OLESTATUS SetHostNames(lpDoc, lpszClient, lpszDoc)

LPOLESERVERDOC lpDoc;
LPSTR lpszClient;
LPSTR lpszDoc;

The SetHostNames function sets the names that should be used for window titles. This function is relevant only for documents that are embedded objects.

Parameter	Description

lpDoc	Points to an OLESERVERDOC structure corresponding to a document that is the embedded object for which names are specified.

lpszClient	Points to a null-terminated string specifying the name of the client.

lpszDoc	Points to a null-terminated string specifying the client application's name for the object.

The names are used only for embedded objects, because linked objects have their own titles.

The server should perform the following steps:

Change the title bar to reflect the embedded state with appropriate names.

Change the File menu to reflect the name of the client application. (See The OLE User Interface for explicit information on the appearance of menus and title bars.)

Save the client and object names for later use in message boxes.

The return value is OLE_OK if successful; otherwise, it could be OLE_ERROR_GENERIC.


OLESERVERDOCVTBL SetDocDimensions callback function

OLESTATUS SetDocDimensions(lpDoc, lpRect)

LPOLESERVERDOC lpDoc;
OLE_CONST RECT FAR* lpRect;

The SetDocDimensions function gives the server application the rectangle on the target device for which the object should be formatted. This function is relevant only for documents that are embedded objects.

Parameter	Description

lpDoc	Points to the OLESERVERDOC structure corresponding to the document that is the embedded object for which the target size is specified.

lpRect	Points to a RECT structure containing the target size of the object, in MM_HIMETRIC units. (In the MM_HIMETRIC mapping mode, the positive y direction is up.)

The return value is OLE_OK if successful; otherwise, it is an error value.


OLESERVERDOCVTBL GetObject callback function

OLESTATUS GetObject(lpDoc, lpszItem, lplpObject, lpClient)

LPOLESERVERDOC lpDoc;
LPSTR lpszItem;
LPOLEOBJECT FAR* lplpObject;
LPOLECLIENT lpClient;

The GetObject function requests the server application to create an OLEOBJECT structure.

Parameter	Description

lpDoc	Points to an OLESERVERDOC structure corresponding to this document.

lpszItem	Points to a null-terminated string specifying the name of an item in the specified document for which an object structure is requested. If this string is NULL or "" (GetObject should check for either), the entire document is requested.

lplpObject	Points to a variable of type LPOLEOBJECT where the server application should return a long pointer to the allocated OLEOBJECT structure.

lpClient	Points to an OLECLIENT structure allocated by the DLL. The server should associate the OLECLIENT structure with the object and use it to notify the DLL of changes to the object.

GetObject is called when a client application creates an object (usually using functions like OleCreate). It requests that the server associate an OLECLIENT structure with an object. If the object name is NULL (lpszItem == "" or lpszItem == NULL), then the object is the whole document. Otherwise, the object name specifies which object in the document is to be associated with the structure.

GetObject is generally called after ServerCreateFromTemplate, ServerCreate, ServerEdit or ServerOpen is called, although not limited to these cases.

The DLL calls the GetObject function to associate a client application with the part of the document identified by the lpszItemname parameter. When a client has been associated with an object by this function, the server application can send notifications to it.

The server should perform the following steps:

1	Allocate and initialize an OLEOBJECT structure.

2	Save the LPOLECLIENT with the OLEOBJECT for later use in notifying the client's callback.

3	Return a pointer to the OLEOBJECT via the lplpObject parameter.

The return value is OLE_OK if successful; otherwise, it could be

OLE_ERROR_MEMORY

OLE_ERROR_NAME


OLESERVERDOCVTBL Release callback function

OLESTATUS Release(lpDoc)

LPOLESERVERDOC lpDoc;

The Release function notifies the server application when a revoked document has terminated conversations and may be destroyed.

The server application may free any document resources.

Parameter	Description

lpDoc	Points to an OLESERVERDOC structure for which the handle was revoked and which may now be released.

The return value is OLE_OK if successful; otherwise, it is an error value.


OLESERVERDOCVTBL SetColorScheme callback function

OLESTATUS SetColorScheme(lpDoc, lpPal)

LPOLESERVERDOC lpDoc;
OLE_CONST LOGPALETTE FAR* lpPal;

The SetColorScheme function sends the server application the color palette recommended by the client application although server applications are not required to use the palette recommended by the client application.

Parameter	Description

lpDoc	Points to an OLESERVERDOC structure for which the client application recommends a palette.

lpPal	Points to a LOGPALETTE structure specifying the recommended palette.

The server application should:

1	Allocate and fill in its own LOGPALETTE structure that contains the colors passed via lpPal.

2	Create a palette from the application defined LOGPALETTE structure using CreatePalette. 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 client application. The second palette entry specifies the background color. The first half of the remaining palette entries are fill colors and the second half are colors for lines and text.

Client applications typically specify an even number of palette entries. When there is an uneven number of entries, the server should round to the fill colors; that is, if there are five entries, three should be interpreted as fill colors and two as line and text colors.

The return value is OLE_OK if successful; otherwise is could be OLE_ERROR_PALETTE.


OLESERVERDOCVTBL Execute callback function

OLESTATUS Execute(lpDoc, hCommands)

LPOLESERVERDOC lpDoc;
HGLOBAL hCommands;

The Execute function sends the server application one or more DDE execute commands.

Parameter	Description

lpDoc	Points to an OLESERVERDOC structure to which the DDE commands apply.

hCommands	Identifies memory containing one or more DDE execute commands.

The server application should never free the handle specified in the hCommands parameter.

The return value is OLE_OK if successful; otherwise, it is an error value.


OLEOBJECT structure

The OLEOBJECT structure is defined in the header file, OLE.H. The lpvtbl member in the OLEOBJECT structure points to a table of function pointers for an object. This structure is initialized and maintained by the server application for OLESVR32.DLL.

OLE.H defines the OLEOBJECT data structure as follows:

typedef struct _OLEOBJECT{

    LPOLEOBJECTVTBL lpvtbl;

} OLEOBJECT;

See Also

OLEOBJECTVTBL


OLEOBJECTVTBL structure

The OLEOBJECTVTBL structure points to the callback functions that manipulate an object. After a server application creates this structure and an OLEOBJECT structure (which points to OLEOBJECTVTBL), the OLESVR32.DLL can access an object.

The OLEOBJECTVTBL structure is defined in OLE.H as follows:

typedef struct _OLEOBJECTVTBL

{

    void FAR*      (CALLBACK* QueryProtocol)    (LPOLEOBJECT, LPSTR);

    OLESTATUS      (CALLBACK* Release)          (LPOLEOBJECT);

    OLESTATUS      (CALLBACK* Show)             (LPOLEOBJECT, BOOL);

    OLESTATUS      (CALLBACK* DoVerb)           (LPOLEOBJECT, UINT,

                                                 BOOL, BOOL);

    OLESTATUS      (CALLBACK* GetData)          (LPOLEOBJECT,

                                                 OLECLIPFORMAT,

                                                 HANDLE FAR*);

    OLESTATUS      (CALLBACK* SetData)          (LPOLEOBJECT,

                                                 OLECLIPFORMAT, HANDLE);

    OLESTATUS      (CALLBACK* SetTargetDevice)  (LPOLEOBJECT, HGLOBAL);

    OLESTATUS      (CALLBACK* SetBounds)        (LPOLEOBJECT,

                                                 OLE_CONST RECT FAR*);

    OLECLIPFORMAT  (CALLBACK* EnumFormats)      (LPOLEOBJECT,

                                                 OLECLIPFORMAT);

    OLESTATUS      (CALLBACK* SetColorScheme)   (LPOLEOBJECT, OLE_CONST

                                                 LOGPALETTE FAR*);

        .

        .

        .

} OLEOBJECTVTBL;

Note The section of the OLEOBJECTVTBL structure that is designed for client applications is not shown here. See Implementing Object Handlers for more information.

OLEOBJECTVTBL Members

The following table lists the members of the OLEOBJECTVTBL data structure. Each member points to a specific callback function.

Structure Member	Description

QueryProtocol	Determines which protocols the server applications supports.

Release	Frees the resources associated with the specified OLEOBJECT structure.

Show	Shows an object's window by making it visible.

DoVerb	Specifies what kind of action a server should take when an object is opened.

GetData	Returns a handle to the requested data.

SetData	Provides the server with the object's native data.

SetTargetDevice	Gives information about the client' s target device for the object.

SetBounds	Returns OLE_OK. Provided for compatibility only.

EnumFormats	Enumerates the data formats that the object can render.

SetColorScheme	Specifies the palette to be used when the server application edits an object.

You will to code these functions to meet the needs of your application.


OLEOBJECTVTBL QueryProtocol callback function

LPVOID (CALLBACK *QueryProtocol)(lpObject, lpProtocol)

LPOLEOBJECT lpObject;
LPSTR lpProtocol;

The QueryProtocol function is called to determine which protocols the server application supports.

Parameter	Description

lpObject	Points to the object to query.

lpProtocol	Points to a null-terminated string specifying the name of the requested protocol. This value can be "StdFileEditing" or "StdExecute." Object handlers may support other protocols identified by other names.

There are currently two possible protocols: StdFileEditing and StdExecute. StdFileEditing is the current OLE protocol while StdExecute is for applications that support WM_DDE_EXECUTE messages.

OLE server applications must support StdFileEditing but are not required to support StdExecute protocol.

In response to the QueryProtocol function, the server application should perform the following steps:

1	If the protocol specified in lpProtocol is supported, return a pointer to and OLEOBJECT structure that contains a VTBL appropriate for the specified protocol. In most cases, the server can just return the lpObject parameter passed to the callback function.

2	If the server application does not support the specified protocol, return NULL.

The return value is NULL if the object does not support the requested protocol.

Otherwise, the return value is a VOID pointer to a data structure similar to the OLEOBJECT structure, but the entries in the corresponding VTBL structure depend on the requested protocol.

For the standard protocols, StdFileEditing and StdExecute, the return value is an OLEOBJECT pointer with corresponding VTBL entries. If an object handler supports additional protocols, the entries in the VTBL structure may be different. Since the caller knows the string name to request, the caller must know the definition of the corresponding VTBL entries.

The DLL can return OLE_WAIT_FOR_RELEASE when an application calls this function.


OLEOBJECTVTBL Release callback function

OLESTATUS (CALLBACK *Release)(lpObject)

LPOLEOBJECT lpObject;

Parameter	Description

lpObject	Points to the OLEOBJECT structure to be released

The Release function causes the server application to free the resources associated with the specified OLEOBJECT structure. This function is called to inform the server application that an object is no longer connected to any client. This callback can be called when a client application calls OleDelete, or when the server application calls OleRevokeServer, OleRevokeObject, or OleRevokeServerDoc. In response, the server application should free the object's resources.

The server application should not destroy data when the DLL calls Release.

The return value is OLE_OK if successful; otherwise, it is an error value.


OLEOBJECTVTBL Show callback function

OLESTATUS (CALLBACK *Show)(lpObject, fTakeFocus)

LPOLEOBJECT lpObject;
BOOL fTakeFocus;

The Show function causes the server application to show an object, showing its window and scrolling (if necessary) to make it visible. The DLL calls the Show function when the server application should show the document to the user for editing, or to request the server application to scroll the document to bring the object into view.

Parameter	Description

lpObject	Points to the OLEOBJECT structure to show.

fTakeFocus	Specifies whether the server window gets the focus. This value is TRUE to take the focus, otherwise FALSE.

In response to a callback to this function, the server application should perform the following steps:

1	If the server application is not already visible, make it visible.

2	If the object's document window is not already visible, make it visible.

3	If the object is not visible within its document window, make it visible. This may require scrolling the object's document window.

4	Select the object, if possible.

5	If fTakeFocus is TRUE, call SetFocus with the main window handle. Also, if the server application's main window or document window is minimized, it should be restored.

The return value is OLE_OK if successful; otherwise, it is an error value.


OLEOBJECTVTBL DoVerb callback function

OLESTATUS (CALLBACK *DoVerb)(lpObject, iVerb, fShow, fTakeFocus);

LPOLEOBJECT lpObject;
UINT iVerb;
BOOL fShow;
BOOL fTakeFocus;

The DoVerb function specifies what kind of action the server should take when a user opens an object.

Parameter	Description

lpObject	Points to the object to activate.

iVerb	Specifies the action to take. The meaning of this parameter is determined by the server application.

fShow	Specifies whether to show the server window. This value is TRUE to show the window or FALSE otherwise.

fFocus	Specifies whether the server window gets the focus. This parameter is relevant only if the fShow parameter is TRUE.

DoVerb is called when the client application has invoked an object's verb (by calling OleActivate ). The server defines the meaning of the verbs. This callback associates meaning with each verb index. In response to DoVerb, a server application should perform the requested verb.

The return value is OLE_OK if the function is successful; otherwise, it is an error value.


OLEOBJECTVTBL GetData callback function

OLESTATUS (CALLBACK *GetData)(lpObject, cfFormat, lphdata)

LPOLEOBJECT lpObject;
OLECLIPFORMAT cfFormat;
HANDLE FAR* lphdata;

GetData is called when the server DLL requests a specific data format for an object (for example, Native, OwnerLink or CF_ENHMETAFILE.) The server application should return a handle to the requested data to the DLL.

Parameter	Description

lpObject	Points to the OLEOBJECT structure from which data is requested.

cfFormat	Specifies the format in which the data is requested.

lphdata	Points to the handle to allocated memory that the server application returns. The DLL frees the memory when it is no longer needed.

GetData should provide the object data based upon the device specified in the SetTargetDevice callback. The server application must maintain target device information so that it can provide the appropriate data. If SetTargetDevice has not been called, then the server may assume a device, usually the display.

In response to a call to GetData, the server should perform the following steps:

1	Allocate a block of memory big enough to hold the requested data format. Use the GMEM_DDESHARE flag when allocating the memory. (The CF_BITMAP data format is an exception. Allocate memory for a bitmap using the CreateBitmap function.)

2	Lock the memory.

3	Fill the memory with the requested data format (cfFormat) for the object pointed to by lpObject.

4	Unlock the memory.

5	Return a handle to the memory via the lphData parameter.

The return value is OLE_OK if the function is successful; otherwise, it coould be one of the following error values:

OLE_ERROR_BLANK

OLE_ERROR_FORMAT

OLE_ERROR_OBJECT


OLEOBJECTVTBL SetData callback function

OLESTATUS (CALLBACK *SetData)(lpObject, cfFormat, hdata)

LPOLEOBJECT lpObject;
OLECLIPFORMAT cfFormat;
HANDLE hdata;

The SetData function is called by the server DLL to provide the server application with an object's native data (usually when the user opens an embedded object for editing).

Parameter	Description

lpObject	Points to the OLEOBJECT structure where data is stored.

cfFormat	Specifies the format of the data.

hdata	Identifies a place in memory from which the server application should extract the data. The server should delete this handle after it uses the data.

The server DLL obtains the native data for the embedded object from the client application and sends it to the server through this callback. SetData is called before the Show or DoVerb functions. This function is also used if the client application calls OleSetData with some other format.

In response to a call to SetData, the server application should perform the following steps:

1	If the supplied data format (cfFormat) is not appropriate, return OLE_ERROR_FORMAT.

2	Lock the native data (hData) using GlobalLock. If this fails, return OLE_ERROR_MEMORY.

3	Allocate a buffer, lock it, and copy the data from hData into data into the buffer. If this can not be done, return OLE_ERROR_MEMORY.

4	Unlock and free the native data supplied by the server library (hData). If this fails, return OLE_ERROR_MEMORY.

Note Copying the native data to a private buffer is important. When the OLE DLLs send data to your server application, do not modify it. Always copy the data and modify the copy.

The server application is responsible for the memory identified by the hdata parameter. The server must delete this data even if it returns OLE_BUSY or if an error occurs.

The return value is OLE_OK if successful; otherwise, it is an error value.


OLEOBJECTVTBL SetTargetDevice callback function

OLESTATUS (CALLBACK *SetTargetDevice)(lpObject, hdata)

LPOLEOBJECT lpObject;
HGLOBAL hdata;

The SetTargetDevice function communicates information about the client application's target device for the object.

Parameter	Description

lpObject	Points to the OLEOBJECT structure for which the target device is specified.

hdata	Identifies a memory object containing a StdTargetDevice structure. For a description of this structure, see the OleSetTargetDevice function. If the specified target device (hdata ) is NULL, the target device is the video display.

The server application can customize output for the target device, such as a video display or printer. SetTargetDevice is called to identify the type device on which the object will be rendered. The server application can use the information provided by SetTargetDevice to optimize the object presentation it supplies to client applications. For example, a server application could return a 24 bit-per-pixel DIB as the presentation for an object displayed on a high resolution color monitor, and a monochrome metafile picture for the same object when displayed on a monochrome dot matrix printer.

After SetTargetDevice is called, subsequent calls to the GetData callback take the specified target device into consideration. This involves getting a DC for the specified device and providing object information based upon that device.

In response to SetTargetDevice, a server should perform the following steps:

1	Lock hdata using GlobalLock.

2	Allocate a buffer, lock it, and copy the target device information (hdata) into the buffer. If this cannot be done, return OLE_ERROR_MEMORY.

3	Unlock hdata using GlobalUnlock.

4	Free hdata using GlobalFree.

The server application is responsible for the memory identified by the hdata parameter. The server application must delete this data even if it returns OLE_BUSY or if an error occurs.

The DLL passes NULL for the hdata parameter to indicate that the rendering is necessary for the screen.

The return value is OLE_OK if successful; otherwise, it is OLE_ERROR_MEMORY.


OLEOBJECTVTBL SetBounds callback function

The SetBounds function provides compatibility only. It should return OLE_OK.


OLEOBJECTVTBL EnumFormats callback function

OLESTATUS (CALLBACK *EnumFormats)(lpObject, cfFormat)

LPOLEOBJECT lpObject;
OLECLIPFORMAT cfFormat;

The EnumFormats function enumerates the data formats that the object can render.

Parameter	Description

lpObject	Points to the object to be queried.

cfFormat	Specifies the format returned by the last call to the OleEnumFormats function. For the first call to this function, this parameter is NULL.

Passing NULL for cfFormat on the first call returns the first data format. Passing the first format returns the second format, and so on. When no more formats are available, NUL L is returned.

The return value is OLE_OK if successful; otherwise, it is an error value.


OLEOBJECTVTBL SetColorScheme callback function

OLESTATUS SetColorScheme(lpObject, lpPalette);

LPOLEOBJECT lpObject;
LPLOGPALETTE lpPalette;

The SetColorScheme function specifies the palette to be used when the server application edits the specified object.

Parameter	Description

lpObject	Points to an OLEOBJECT structure describing the object for which a palette is recommended.

lpPalette	Points to a LOGPALETTE structure specifying the recommended palette.


Data Structures for Client Applications

The client application uses the following data structures, the prototypes of which are defined in OLE.H:

Structure	Contents, as defined in OLE.H

OLESTREAM	A single pointer (LPOLESTREAMVTBL) to the OLESTREAMVTBL structure that provides stream input and output functions.

OLESTREAMTVTBL	Far pointers to functions OLECLI32.DLL uses for stream operations on objects.

OLECLIENT	A single pointer (LPOLECLIENTVTBL) to the client callback VTBL, OLECLIENTVTBL.

OLECLIENTVTBL	Far pointer to the client CallBack function.


OLESTREAM structure

The OLESTREAM structure is defined in the header file, OLE.H. The lpvtbl member in the OLESTREAM structure points to a table of function pointers for the client application. This structure is initialized and maintained by the client application for OLECLI32.DLL.

OLE.H defines the OLESTREAM data structure as follows:

typedef struct _OLESTREAM{

    LPOLESTREAMVTBL lpvtbl;

} OLESTREAM;

See Also

OLESTREAMVTBL


OLESTREAMVTBL structure

The OLESTREAMVTBL structure, shown below as defined in OLE.H, points to functions the client DLL uses for load and save operations that result from calling OleLoadFromStream and OleSaveToStream. This structure is allocated and initialized by client applications.

typedef struct _OLESTREAMVTBL

{

    DWORD (CALLBACK* Get)(LPOLESTREAM, void FAR*, DWORD);

    DWORD (CALLBACK* Put)(LPOLESTREAM, OLE_CONST void FAR*, DWORD);

} OLESTREAMVTBL;

OLESTREAMVTBL Members

The following table lists the members of the OLESTREAMVTBL data structure. Each member points to a specific function.

Structure Member	Description

Get	Gets data from the stream.

Put	Puts data into the stream.

The return values for the stream functions may indicate that an error has occurred; however they are capable of indicating the cause of the error. The client application is responsible for any required error-recovery operations.

A client application can use these functions t o provide variations on the standard stream procedures; for example, the client could change the permanent storage of some objects so that they were stored in a database instead of the client document.

You will to code these functions to meet the needs of your application.


OLESTREAMVTBL Get callback function

DWORD (CALLBACK *Get)(lpstream, lpszBuf, cbbuf)

LPOLESTREAM lpstream;
void FAR* lpszBuf;
DWORD cbbuf;

The Get function gets data from the specified stream.

Parameter	Description

lpstream	Points to an OLESTREAM structure allocated by the client.

lpszBuf	Points to a buffer to fill with data from the stream.

cbbuf	Specifies the number of bytes to read into the buffer.

The value specified by the cbbuf parameter can be larger than 64K. If the client application uses a stream-reading function that is limited to 64K, i t should call that function repeatedly until it has read the number of bytes specified by cbbuf. Whenever the data size is greater than 64K, the pointer to the data buffer is always at the beginning of the segment.

The return value is the number of bytes actually read into the buffer if the function is successful. If the end of the file is encountered, the return value is zero. If the return value is negative, an error occurred.


OLESTREAMVTBL Put callback function

DWORD (CALLBACK* Put)(lpstream, lpszBuf, cbbuf)

LPOLESTREAM lpstream;
OLE_CONST void FAR* lpszBuf;
DWORD cbbuf;

The Put function puts data into the specified stream.

Parameter	Description

lpstream	Points to an OLESTREAM structure allocated by the client.

lpszBuf	Points to a buffer from which to write data into the stream.

cbbuf	Specifies the number of bytes to write into the stream.

The value specified by the cbbuf parameter can be larger than 64K. If the client application uses a stream-writing function that is limited to 64K, i t should call that function repeatedly until it has written the number of bytes specified by cbbuf. Whenever the data size is greater than 64K, the pointer to the data buffer is always at the beginning of the segment.

The return value is the number of bytes actually written to the stream. If the return value is less than the number specified in the cbbuf parameter, there was insufficient space in the stream or an error occurred.


OLECLIENT structure

The OLECLIENT structure is defined in the header file, OLE.H. The lpvtbl member in the OLECLIENT structure points to a table of function pointers for the client application. This structure is initialized and maintained by the client application for OLECLI32.DLL.

OLE.H defines the OLECLIENT data structure as follows:

typedef struct _OLECLIENT{

    LPOLECLIENTVTBL lpvtbl;

} OLECLIENT;

See Also

OLECLIENTVTBL


OLECLIENTVTBL structure

The OLECLIENTVTBL structure, as defined in OLE.H, contains a pointer to a callback function provided by the client application. CallBack points to the callback function within the client application. You will need to code this function to meet the needs of your application.

OLE.H defines the OLECLIENTVTBL data structure as follows:

typedef struct _OLECLIENTVTBL

{

    int (CALLBACK* CallBack)(LPOLECLIENT, OLE_NOTIFICATION, LPOLEOBJECT);

} OLECLIENTVTBL;


OLECLIENTVTBL CallBack callback function

INT (CALLBACK* CallBack)(lpclient, notification, lpobject)

LPOLECLIENT lpclient;
OLE_NOTIFICATION notification;
LPOLEOBJECT lpobject;

Parameter	Description

lpclient	Points to the client structure associated with the object. The client DLL retrieves this pointer from its object structure when a notification occurs, uses it to locate the callback function, and passes the pointer to the client structure for the client application's use.

notification	Specifies the reason for the notification. This parameter can be one of the following values:

Value	Meaning

OLE_CHANGED	The object has changed within the server application. Received whenever a linked object, opened for editing from the client application, is changed in the server application. May be received when a n embedded object is changed and the server applications is closed with document changes saved. Typical actions to take with this notification are to redraw or save the object.

OLE_CLOSED	The object has been closed in its server application. When the client receives this notification, it should not call any function that causes an asynchronous operation until it regains control of program execution.

OLE_QUERY_PAINT	A lengthy drawing operation is occurring. This notification allows the drawing to be interrupted.

OLE_QUERY_RETRY	The server has responded to a request indicating that it is busy. This notification requests the client to determine whether the DLL should continue to make the request. If the callback function returns FALSE, the transaction with the server is discontinued.

OLE_RELEASE	The object has been released because an asynchronous operation has completed. The client application can call the OleQueryReleaseError function to determine whether the operation succeeded. It can also call the OleQueryReleaseMethod function, if necessary, to verify that the operation has terminated.

OLE_RENAMED	The linked object has been renamed in it s server application. This notification is for information only, because the DLL automatically updates its link information.

OLE_SAVED	The object has been saved in its server application. The client receives this notification when the server calls the OleSavedServerDoc function in response to the user choosing "Update" in the server's File menu. Typical actions to take with this notification are to redraw or save the object.

When the client receives the OLE_CLOSED notification, it typically stores the condition and returns control to the client DLL. the application takes action only when the client DLL returns control of program execution to the client application. If the client application must take action before regaining control, it should not call any functions that could result in an asynchronous operation.

lpobject	Points to the object that caused the notification to be sent. Applications that use the same client structure for more than one object use the lpobject parameter to distinguish between notifications.

The client application should act on these notifications at the next appropriate time; for example, as part of the main event loop or when closing the object. The updating of objects can be deferred until the user requests the update, if the client application provides that functionality. The client application may call the DLL from a notification callback function (the DLL is reentrant).

The client application should not attempt an asynchronous operation while a nother operations is in progress (for example, opening or deleting an object). The client application should also not enter a message-dispatch loop inside the callback function (calling MessageBox will cause this to happen).

When the client application calls a function that would cause an asynchronous operation, the client DLL returns OLE_WAIT_FOR_RELEASE when the function is called, notifies the application when the operation completes by using OLE_RELEASE, and returns OLE_BUSY if the client application attempts to invoke a conflicting operation while the previous one is in progress. The client application can determine if an asynchronous operation is in progress by calling OleQueryReleaseStatus , which returns OLE_BUSY if the operation has not yet completed. For more information on asynchronous operations, see Implementing OLE into Client Applications.

When the notification parameter specifies either OLE_QUERY_PAINT or OLE_QUERY_RETRY, the client should return TRUE if the DLL should c ontinue, or FALSE to terminate the painting operation or discontinue the server transaction. When the notification parameter does not specify either OLE_QUERY_PAINT or OLE_QUERY_RETRY, the return value is ignored.


Actions that Invoke Server Callbacks Functions

Using the appropriate VTBL--either for the object, the document, or the server application-- OLESVR32.DLL calls functions in your server application. To provide a better understanding of the relationship between the callbacks and OLESVR32.DLL actions, the following sections list the callbacks made in response to several specific situations that involve the server application.

Each situation is described and names the OLECLI32.DLL function(s) called by the client application in the order that the callbacks are made. The resultant callbacks are identified by the level of operation: server, document, or object.

In the following example, the callbacks are made in a specific sequence. The server callback (Edit) is made first, then the document callback (Get ) and finally the object callbacks (SetData, the EnumFormats calls, and DoVerb) are made.

Note:	In some situations, (for example, when OleUpdate is called to update an embedded object with the server application not running), the callback sequence can go from server to document to object and then back to document and finally server.

Callbacks Resulting from Actions by the Client Application

Action: OleActivate is called and the server application is not running.

When the client application invokes an appropriate verb for an embedded object, the server application is launched with the /Embedding option, causing it to call OleRegisterServer before yielding and remaining invisible.

OLESVR32.DLL makes these callbacks in the following order:

Server Callback

Edit

Document Callback

GetObject

Object Callbacks

SetData  Sequence of EnumFormats calls  DoVerb

Action: OleActivate is called and the server application is running with no open document.

OLESVR32.DLL makes the following callbacks:

Server Callback	Edit

Document Callback	GetObject

Object Callbacks	SetData Sequence of EnumFormats calls DoVerb

Action: OleActive is called while conversation exist between server and client applications.

OLESVR32.DLL makes the following callback:

Object Callback

DoVerb

Action: OleCreate is called by the client application (user chooses Insert Object).

If the server application not running, it is started using the /Embedding option, causing it to call OleRegisterServer before yielding and remaining invisible.

OLESVR32.DLL makes the following callbacks:

Server Callback

Create

Document Callback

GetObject

Object Callbacks

Sequence of EnumFormats calls Show

Action: Open or activate a link with the server application not running (OleActivate is called).

The server is started with /Embedding <filename> option, causing the server application to call OleRegisterServer and OleRegisterServerDoc (specified by <filename >, if valid), before yielding and remaining invisible.

OLESVR32.DLL makes the following callbacks:

Document Callback

GetObject

Object Callbacks

Sequence of EnumFormats calls GetData DoVerb

Action: Open or activate a link with the server application running, but the server document not open (OleActivate is called).

OLESVR32.DLL makes the following callbacks:

Server Callback

Open

Document Callback

GetObject

Object Callbacks

Sequence of EnumFormats calls GetData DoVerb

Open or activate a link with a server document open but no client application in conversation with the item in the document (OleActivate is called).

This situation is present when the client application is started before the server document is opened.

OLESVR32.DLL makes the following callbacks:

Document Callback

GetObject

Object Callbacks

SetData Sequence of EnumFormats calls DoVerb

Action: Open or activate a link with a server document open but a different client application is in conversation with the item in the document (OleActivate is called).

This situation is present when the client application is started after some other client has established conversation with the open server document.

OLESVR32.DLL makes the following callbacks:

Object Callbacks

Sequence of EnumFormats calls GetData DoVerb

Action: OleActivate is called with the client application in conversation with the item in the server document.

OLESVR32.DLL makes the following callback:

Object Callback

DoVerb

Action: OleUpdate is called to update an embedded object with the server application not running.

This situation is present after certain calls to OLECLI32.DLL, such as OleSetBounds or OleSetTargetDevice. The server application is started with the /Embedding command line option, causing the server to call OleRegisterServer before yielding, and remaining invisible.

OLESVR32.DLL makes the following callbacks:

Server Callback

Edit

Document Callback

GetObject

Object Callbacks

SetData Sequence of EnumFormats calls GetData

Document Callback

Close

Server Callbacks

Edit

Action: OleUpdate is called to update an embedded object with the server application running but the document not open.

This situation is present after certain calls to OLECLI32.DLL, such as OleSetBounds or OleSetTargetDevice.

OLESVR32.DLL makes the following callbacks:

Server Callback

Edit

Document Callback

GetObject

Object Callbacks

SetData Sequence of EnumFormats calls GetData

Document Callback

Close

Action: OleUpdate is called to update an embedded object in a document that is in conversation with the server application.

This situation is present after certain calls to OLECLI32.DLL, such as OleSetBounds or OleSetTargetDevice.

OLESVR32.DLL makes the following callbacks:

Object Callbacks

SetData Sequence of EnumFormats calls GetData

Action: OleUpdate is called to update a link with the server application not running.

The server application is started with the /Embedding <filename> command line option, causing the server to call OleRegisterSever and OleRegisterServerDoc (specified by <filename>, if valid), before yielding, and remaining invisible.

OLESVR32.DLL makes the following callbacks:

Document Callback

GetObject

Object Callbacks

Sequence of EnumFormats calls GetData

Server Callback

Release

Action: OleUpdate is called to update a link with the server application running but the server document not open.

OLESVR32.DLL makes the following callbacks:

Server Callbacks

Open

Document Callbacks

GetObject

Object Callbacks

Sequence of EnumFormats calls GetData

Document Callbacks

Close

Action: OleUpdate is called to update a link with the server document open but no client application in conversation with the item in the document.

OLESVR32.DLL makes the following callbacks:

Document Callbacks

GetObject

Object Callbacks

Sequence of EnumFormats calls GetData

Action: OleUpdate is called to update a link with the server document open and the client application in conversation with the item in the document.

OLESVR32.DLL makes the following callbacks:

Object Callbacks

Sequence of EnumFormats calls GetData

Action: OleClose, OleDelete, or OleRelease is called to destroy an open embedded object in a client document:

OLESVR32.DLL makes the following callback:

Document Callback

Close

Callbacks Resulting from Actions by the Server Application

The server application can do the following actions, resulting in the sequence of callbacks to the server application. Although the callback sequences can vary, those listed are generally valid.

Action: OLE_CHANGED notification is sent for a linked object (client application is in automatic update mode).

OLESVR32.DLL makes the following callback:

Object Callback

GetData

Action: OLE_CLOSED notification is sent for an embedded object

OLESVR32.DLL makes the following callbacks:

Object Callbacks

GetData

Document Callbacks

Close (unless the server application or document is revoked after sending OLE_CLOSED)

Action: OleSavedServerDoc is called for an embedded document (or for a link that is set to the update-on-save mode).

OLESVR32.DLL makes the following callback:

Object Callback

GetData

Note:	When GetData is called for embedded objects, it will usually be called twice, once for native data and once for presentation data. Also, It is possible for a call to GetData to be preceded by a call to SetTargetDevice. This can occur if a client application has requested that the object be rendered for a new target device since the most recent GetData call. This can happen for linked as well as embedded objects.

Calls to the Object Release, Document Release, and Server Release Callbacks

The Release callback functions for objects, servers, and documents can be invoked in response to a server application calling OleRenameServerDoc, OleRevokeObject, OleRevokeServerDoc, and OleRevokeServer. The following callbacks are called in the order described:

Action: Server Application calls OleRenameServerDoc for an embedded document.

OLESVR32.DLL calls (if server application is no longer in communication with any client application after the call to OleRenameServerDoc):

Server Callback

Release

Action: Server Application calls OleRevokeObject.

OLESVR32.DLL calls:

Object Callback

Release

Server Callbacks

Release (if a client application was communicating with the obejct before the call to OleRevokeObject and there are no client applications communicating with the server application after the OleRevokeObject call)

Action: Server Application calls OleRevokeServerDoc.

OLESVR32.DLL calls:

Object Callbacks

Release (for each object in the document

Document Callbacks

Release

Server Callbacks

Release (if the server application is no longer in communication with any client application after the call to OleRevokeServerDoc)

Action: Server Application calls OleRevokeServer.

OLESVR32.DLL calls:

Object Callbacks

Release (for each object in each document open in the server application)

Document Callbacks

Release (for each document in open in the server application)

Server Callbacks

Release


The OLE Server DLL

This topic provides information on OLESVR32.DLL, one of the OLE dynamic-linked libraries (DLL) installed in the system directory of the Microsoft Windows graphical environment.

For more information, see the following topics:

Overview of OLESVR32.DLL

OLESVR32.DLL Functions


Overview of OLESVR32.DLL

OLE is implemented through the use of two DLLs: OLESVR32.DLL and OLECLI32.DLL. OLESVR32.DLL contains functions that are called by the server application during OLE operations. Figure 37 shows that OLESVR32.DLL makes callbacks to the server application to perform operations on objects and documents, and to invoke the server functions such as open a file, edit a file, and so on.

Figure 37. Relationship between applications and OLE DLLs

Note:	All communication between the OLESVR32.DLL and OLECLI32.DLL is handled via DDE, which is transparent to the client and server applications.


OLESVR32.DLL Functions

Depending on the particular function called, OLESVR32.DLL will perform the needed operations to fullfill the requirements of the server application. OLESVR32.DLL passes status and object information through the OLECLI32.DLL back to the client application. OLECLI32.DLL uses the client application's CallBack function to pass notifications regarding the status of the objects back to the client application.

OLESVR32.DLL provides the functions listed in the following table:

Function	Description

OleBlockServer	Causes requests to the server application to be queued until the server calls the OleUnblockServer function.

OleQueryServerVersion	Retrieves the version number of the server DLL.

OleRegisterServer	Registers the specified server, class, and instance with the server DLL.

OleRegisterServerDoc	Registers a document with the server DLL.

OleRenameServerDoc	Informs the server DLL that a document has been renamed.

OleRevertServerDoc	This function is provided in the library (OLESVR32.DLL) and header file (OLE.H) for compatibility reasons.

OleRevokeServerDoc	Revokes the specified document.

OleRevokeObject	Revokes access to an object. A server application typically calls this function when the user deletes an object.

OleRevokeServer	Called by a server application to revoke any registered documents and to revoke the server application registered with OleRegisterServer.

OleSavedServerDoc	Informs the server DLL that a document has been saved.

OleUnblockServer	Processes a request from a queue created by calling the OleBlockServer function.


OleBlockServer function

OLESTATUS OleBlockServer(lhSrvr)

LHSERVER lhSrvr;

The OleBlockServer function causes requests to the server to be queued until the server calls the OleUnblockServer function.

Parameter	Description

lhSrvr	Identifies the server for which requests are to be queued.

The server must call the OleUnblockServer function after calling the OleBlockServer function.

A server application can use the OleBlockServer and OleUnblockServer functions to control when the server DLL processes requests from client applications. Because only messages from the client to the server are blocked, a blocked server can continue to send messages to client applications.

The return value is OLE_OK if successful; otherwise, it could be OLE_ERROR_HANDLE.

See Also

OleRegisterServer, OleUnblockServer


OleQueryServerVersion function

DWORD OleQueryServerVersion(void)

The OleQueryServerVersion function retrieves the version number of the server DLL.

The return value is a double word in which the major version number is in the low byte of the low word and the minor version number is in the high byte of the low word. The high word is reserved.

See Also

OleQueryClientVersion


OleRegisterServerDoc function

OLESTATUS OleRegisterServerDoc(lhsrvr, lpszDocName, lpdoc, lplhdoc)

LHSERVER lhsrvr;
LPSTR lpszDocName;
LPOLESERVERDOC lpdoc;
LHSERVERDOC FAR * lplhdoc;

The OleRegisterServerDoc function registers a document with the server DLL in case other client applications have links to it.

Parameter	Description

lhsrvr	Identifies the server. Server applications obtain this handle by calling the OleRegisterServer function.

lpszDocName	Points to a null-terminated string specifying the permanent name for the document. This parameter should be a fully qualified path.

lpdoc	Points to an OLESERVERDOC structure allocated and initialized by the server application.

lplhdoc	Points to a handle that will identify the document. This parameter points to the handle when the function returns.

A server application uses this function when the server is started with the /Embedding filename option or when it creates or opens a document that is not requested by the DLL.

If the document was created or opened in response to a request from the server DLL, the server should not register the document by using the OleRegisterServerDoc function. Instead, the server should return a pointer to the OLESERVERDOC structure through the parameter to the relevant function.

The return value is OLE_OK, if successful; otherwise, it could be one of the following:

OLE_ERROR_HANDLE

OLE_ERROR_MEMORY

OLE_ERROR_TERMINATE

See Also

OleRegisterServer, OleRevokeServerDoc


OleRegisterServer function

OLESTATUS OleRegisterServer(lpszClass, lpsrvr, lplhserver, hInst, srvruse)

LPSTR lpszClass;
LPOLESERVER lpsrvr;
LHSERVER FAR * lplhserver;
HANDLE hInst;
OLE_SERVER_USE srvruse;

The OleRegisterServer function registers the specified server, class, and instance with the server DLL.

Parameter	Description

lpszClass	Points to a null-terminated string specifying the class being registered.

lpsrvr	Points to an OLESERVER structure allocated and initialized by the server application.

lplhserver	Points to a variable of type LHSERVER in which the DLL stores the handle to the server. This handle is used in such functions as OleRegisterServerDoc and OleRevokeServer.

hInst	Identifies the instance of the server application. This handle is used to ensure that clients connect to the correct instance of a server application.

srvruse	Specifies whether the server uses a single instance or multiple instances to support multiple objects. This value must be either OLE_SERVER_SINGLE or OLE_SERVER_MULTI.

When the server application starts, it creates an OLESERVER structure and calls the OleRegisterServer function. Servers that support several classes can alloc ate a structure for each or reuse the same structure. The class is passed to server-application functions that are called through the DLL, so that servers supporting more than one class can check which class is being requested.

The srvruse parameter is used when the libraries open an object. When OLE_SERVER_MULTI is specified for this parameter, a new instance of the server is started if all current instances are already editing an object. Servers that support the multiple document inter face (MDI) typically specify OLE_SERVER_SINGLE.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_PROTECT_ONLY

OLE_ERROR_CLASS

OLE_ERROR_MEMORY

See Also

OleRegisterServerDoc, OleRevokeServer


OleRenameServerDoc function

OLESTATUS OleRenameServerDoc(lhDoc, lpszDocName)

LHSERVERDOC lhDoc;
LPSTR lpszDocName;

The OleRenameServerDoc function informs the server DLL that a document has been renamed.

Parameter	Description

lhDoc	Identifies the document that has been renamed.

lpszDocName	Points to a null-terminated string specifying the new name of the document. This parameter is typically a fully-qualified path.

The OleRenameServerDoc function has the same effect as sending the OLE_RENAMED notification to the client application's callback function. The server application calls this function when it renames a document and active links to that document need to be reconnected or when the user chooses the Save As command from the File menu while working with an embedded object.

Server applications should register open documents with the server DLL and notify the DLL when a document is renamed, closed, saved, or restored to a changed state.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_HANDLE

OLE_ERROR_MEMORY

See Also

OleRegisterServerDoc, OleRevokeServerDoc, OleSavedServerDoc


OleRevertServerDoc function

OLESTATUS OleRevertServerDoc(lhDoc)

LHSERVERDOC lhDoc;

The OleRevertServerDoc function is provided for compatibility only.


OleRevokeServerDoc function

OLESTATUS OleRevokeServerDoc(lhdoc)

LHSERVERDOC lhdoc;

The OleRevokeServerDoc function revokes the specified document. A server application calls this function when a registered document is being closed or otherwise made unavailable to client applications.

Parameter	Description

lhdoc	Identifies the document to revoke. This handle was returned by a call to the OleRegisterServerDoc function or was associated with a document by using one of the serve r-supplied functions that create documents.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_HANDLE

OLE_WAIT_FOR_RELEASE

If this function returns OLE_WAIT_FOR_RELEASE, the server application should not free the OLESERVERDOC structure or exit until the DLL calls the server's document Release callback function.

See Also

OleRegisterServerDoc, OleRevokeObject, OleRevokeServer


OleRevokeObject function

OLESTATUS OleRevokeObject(lpClient)

LPOLECLIENT lpClient;

The OleRevokeObject function revokes access to an object. A server application typically calls this function when the user deletes an object.

Parameter	Description

lpClient	Points to the OLECLIENT structure associated with the object being revoked.

The return value is OLE_OK if successful; otherwise, it is an error value.

See Also

OleRevokeServerDoc, OleRevokeServer


OleRevokeServer function

OLESTATUS OleRevokeServer(lhServer)

LHSERVER lhServer;

The OleRevokeServer function is called by a server application to close any registered documents.

Parameter	Description

lhServer	Identifies the server to revoke. A server application obtains this handle in a call to the OleRegisterServer function.

The OleRevokeServer function returns OLE_WAIT_FOR_RELEASE if communications between clients and the server are in the process of terminating. In this case, the server application should continue to send and dispatch messages until the DLL calls the server's Release function.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_HANDLE

OLE_WAIT_FOR_RELEASE

See Also

OleRegisterServer, OleRevokeServerDoc, OleRevokeObject


OleSavedServerDoc function

OLESTATUS OleSavedServerDoc(lhDoc)

LHSERVERDOC lhDoc;

The OleSavedServerDoc function informs the server DLL that a document has been saved.

Parameter	Description

lhDoc	Identifies the document that has been saved.

The OleSavedServerDoc function has the same effect as sending the OLE_SAVED notification to the client application's callback function. The server application calls this function when saving a document or when updating an embedded object without closing the document.

When a server application receives the OLE_ERROR_CANT_UPDATE_CLIENT error value, it should display a message box indicating that the user cannot update the document until the server terminates or the server document is closed.

Server applications should register open documents with the server DLL and notify the DLL when a document is renamed, closed, saved, or reverted to a saved state.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_CANT_UPDATE_CLIENT

OLE_ERROR_HANDLE

See Also

OleRegisterServerDoc, OleRevokeServerDoc, OleRenameServerDoc


OleUnblockServer function

OLESTATUS OleUnblockServer(lhSrvr, lpfRequest)

LHSERVER lhSrvr;
BOOL FAR * lpfRequest;

The OleUnblockServer function processes a request from a queue created by calling the OleBlockServer function.

Parameter	Description

lhSrvr	Identifies the server for which requests were queued.

lpfRequest	Points to a flag indicating whether there are further requests in the queue. If there are further requests in the queue, this flag is TRUE when the function returns. Otherwise, it is FALSE when the function returns.

A server application can use the OleBlockServer and OleUnblockServer functions to control when the server DLL processes requests from client applications. The best way to use the OleUnblockServer function is outside the GetMessage function in a message loop, unblocking all blocked messages before getting the next message.

Unblocking message loops should not be run inside server-supplied functions that are called by the DLL.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_HANDLE

OLE_ERROR_MEMORY

See Also

OleBlockServer


The OLE Client DLL

This topic describes OLECLI32.DLL, the dynamic-linked library (DLL) that supports the client implementation of OLE. OLE CLI32.DLL must be installed in the SYSTEM directory of the Microsoft Windows graphical environment.

For more information, see the following topics:

Overview of OLELI32.DLL

Summary of OLECLI32.DLL Functions

Document Management Functions

Object Creation and Deletion Functions

Object Management Functions

Object Information Functions

Object Updating Functions

Miscellaneous Functions


Overview of OLECLI32.DLL

Note:	OLE is implemented mainly through the use of two DLLs, OLESVR32.DLL and OLECLI32.DLL. OLECLI32.DLL contains functions that are called by the client applica tions. These functions do tasks such as managing conversations between client and server applications, rendering objects for the client, and launching server applications to manipulate linked and embedded objects.

Figure 38 shows that the client application calls functions within OLECLI32.DLL during OLE operations--such as when a user double-clicks on an object previously inserted in the client application's document.

Figure 38. Relationship between applications and OLE DLLs

Note:	As shown in Figure 38 , communication between the OLESVR32.DLL and OLECLI32.DLL is handled via DDE. Future versions of OLE may not use DDE for their communication protocol; this will not affect your implementation of OLE because DDE is transparent to client and server applications.


Summary of OLECLI32.DLL Functions

The client application makes function calls to the client DLL, which initiates communication with the server DLL (and ultimately, the server application). All status and object information the server application has for the client application is passed back through OLECLI32.DLL. The client application's CallBack function processes this information; see Chapter 5, "Implementing OLE into Client Applications," for details on how the client handles this task.

OLECLI32.DLL provides 55 functions for use by client applications. The functions are divided into the following categories:

Category	Description

Document Management Functions	Used to obtain information about documents containing OLE objects.

Object Creation and Deletion Functions	Used to add or delete an OLE object from a document.

Object Management Functions	Used to open, close, or draw OLE objects.

Object Information Functions	Used to obtain specific information about the an OLE object.

Object Updating Functions	Used to update and to notify the client application of changes made to an OLE object.

Miscellaneous Functions	Used to perform tasks on OLE objects as the need may arise; for example, locking and unlocking OLE server applications in memory.


Document Management Functions

The following functions affect documents in an OLE client application.

Function	Description

OleRegisterClientDoc	Registers a client document.

OleRenameClientDoc	Informs the client DLL that a registered document was renamed.

OleRevertClientDoc	This function is provided in the client DLL and header file (OLE.H) for compatibility reasons.

OleRevokeClientDoc	Informs the client DLL that a registered document was closed.

OleSavedClientDoc	Informs the client DLL that a registered document was saved.


OleRegisterClientDoc function

OLESTATUS OleRegisterClientDoc(lpszClass, lpszDoc, reserved, lplhDoc)

LPSTR lpszClass;
LPSTR lpszDoc;
LONG reserved;
LHCLIENTDOC FAR * lplhDoc;

The OleRegisterClientDoc function registers an open client document with the client DLL and returns a handle to that document.

Parameter	Description

lpszClass	Points to a null-terminated string specifying the class of the client document.

lpszDoc	Points to a null-terminated string specifying the location of the client document. (This value should be a fully-qualified path name.)

reserved	Reserved. Must be zero.

lplhDoc	Points to a handle to the client document, when the function returns. This handle is used to identify the document in other document-management functions.

The name specified in the lpszDoc parameter must be "Clipboard" when a document being copied to the clipboard exists only because the client application is copying Native data that contains objects.

Client applications should register open documents with the DLL and notify it when a document is renamed, closed, saved, or restored to a changed state.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_NAME

OLE_ERROR_MEMORY

See Also

OleRevokeClientDoc


OleRenameClientDoc function

OLESTATUS OleRenameClientDoc(lhClientDoc, lpszNewDocname)

LHCLIENTDOC lhClientDoc;
LPSTR lpszNewDocname;

The OleRenameClientDoc function informs the client application library that a document has been renamed.

Parameter	Description

lhClientDoc	Identifies the document that has been renamed.

lpszNewDocname	Points to a null-terminated string specifying the new name of the document.

A client application calls this function when a document name has changed--for example, when the user chooses the Save or Save As command.

Client applications should register open documents with the client DLL and notify it when a document is renamed, closed, saved, or reverted to a changed state.

The return value is OLE_OK if successful; otherwise, it could be OLE_ERROR_HANDLE.

See Also

OleRegisterClientDoc, OleRevokeClientDoc, OleRevertClientDoc, OleSavedClientDoc


OleRevertClientDoc function

OLESTATUS OleRevertClientDoc(lhDoc)

LHCLIENTDOC lhDoc;

The OleRevertClientDoc function is provided for compatibility only.


OleRevokeClientDoc function

OLESTATUS OleRevokeClientDoc(lhClientDoc)

LHCLIENTDOC lhClientDoc;

The OleRevokeClientDoc function informs the client DLL that a document is no longer open.

Parameter	Description

lhClientDoc	Identifies the document that is no longer open. This handle is invalid following the call to the OleRevokeClientDoc function.

The client application should release all the objects in a document before calling the OleRevokeClientDoc function.

Client applications should register open documents with the DLL and notify the DLL when a document is renamed, closed, saved, or restored to a changed state.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_HANDLE

OLE_ERROR_NOT_EMPTY

See Also

OleRegisterClientDoc


OleSavedClientDoc function

OLESTATUS OleSavedClientDoc(lhClientDoc)

LHCLIENTDOC lhClientDoc;

The OleSavedClientDoc function informs the client application library that a document has been saved.

Parameter	Description

lhClientDoc	Identifies the document that has been saved.

Client applications should register open documents with the client DLL and notify it when a document is renamed, closed, saved, or reverted to a saved state. The return value is OLE_OK if the function is successful. Otherwise, it is an error value, which can be OLE_ERROR_HANDLE.

See Also

OleRegisterClientDoc, OleRevokeClientDoc, OleRenameClientDoc


Object Creation and Deletion Functions

The following functions support adding or removing an object from a container document.

Function	Description

OleClone	Creates an exact copy of another object.

OleCopyFromLink	Creates an embedded object copy of a linked object.

OleCreate	Creates an embedded object of a specified class.

OleCreateFromClip	Creates an embedded object from data on the clipboard.

OleCreateFromFile	Creates an embedded object using the contents of a file.

OleCreateFromTemplate	Creates an embedded object using a file as a template.

OleCreateInvisible	Creates an embedded object with no data or display.

OleCreateLinkFromClip	Creates a linked object from data on the clipboard.

OleCreateLinkFromFile	Creates a linked object with a link to a specified file.

OleDelete	Permanently deletes an object from a document.

OleLoadFromStream	Loads an object from a document being loaded.

OleObjectConvert	Creates a static object from an existing object.

OleRelease	Frees an object from memory.

The object creation and deletion functions are described in the following sections.


OleClone function

OLESTATUS OleClone(lpObject, lpClient, lhClientDoc, lpszObjname, lplpObject)

LPOLEOBJECT lpObject;
LPOLECLIENT lpClient;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR * lplpObject;

The OleClone function makes a copy of an object. The copy is identical to the source object, but it is not connected to the server.

Parameter	Description

lpObject	Points to the object to copy.

lpClient	Points to an OLECLIENT structure for the new object.

lhClientDoc	Identifies the client document in which the object is to be created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object. This name must be unique with respect to the names of any other objects in the document and cannot contain the forward-slash ("/") character.

lplpObject	Points to a variable where the DLL will store the long pointer to the new object.

A client application often use the OleClone function to support the Undo command.

Client applications can supply a new OLECLIENT structure for the cloned object, if required.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_HANDLE

OLE_ERROR_OBJECT

OLE_ERROR_NAME

See Also

OleEqual


OleCopyFromLink function

OLESTATUS OleCopyFromLink(lpObject, lpszProtocol, lpClient, lhClientDoc, lpszObjname, lplpObject)

LPOLEOBJECT lpObject;
LPSTR lpszProtocol;
LPOLECLIENT lpClient;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR * lplpObject;

The OleCopyFromLink function makes an embedded copy of a linked object.

Parameter	Description

lpObject	Points to the linked object that is to be embedded.

lpszProtocol	Points to a null-terminated string specifying the name of the protocol required for the new embedded object. Currently this value can be "StdFileEditing" (the name of the OLE protocol).

lpClient	Points to an OLECLIENT structure for the new object.

lhClientDoc	Identifies the client document in which the object is to be created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object.

lplpObject	Points to a variable where the client DLL will store the long pointer to the new object.

Making an embedded copy of a linked object may involve starting the server application.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_HANDLE

OLE_ERROR_NAME

OLE_ERROR_OBJECT

OLE_ERROR_PROTOCOL

OLE_WAIT_FOR_RELEASE

See Also

OleObjectConvert


OleCreate function

OLESTATUS OleCreate(lpszProtocol, lpClient, lpszClass, lhClientDoc, lpszObjname, lplpObject, renderopt, cfFormat)

LPSTR lpszProtocol;
LPOLECLIENT lpClient;
LPSTR lpszClass;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR* lplpObject;
OLEOPT_RENDER renderopt;
OLECLIPFORMAT cfFormat;

The OleCreate function creates an embedded object of a specified class. The server is opened to perform the initial editing.

Parameter	Description

lpszProtocol	Points to a null-terminated string specifying the name of the protocol required for the new embedded object. Currently this value can be "StdFileEditing" (the name of the OLE protocol).

lpClient	Points to an OLECLIENT structure for the new object.

lpszClass	Points to a null-terminated string specifying the registered name of the class of the object to be created.

lhClientDoc	Identifies the client document in which the object is to be created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object. This name must be unique with respect to the names of any other objects in the document and cannot contain the forward-slash ("/") character.

lplpObject	Points to a variable where the client DLL will store the long pointer to the new object.

renderopt	Specifies the client's preference for presentation data for the object. This parameter can be one of the following values:

Value	Meaning

olerender_none	The client DLL does not obtain any presentation data and does not draw the object.

olerender_draw	The client calls the OleDraw function, and the DLL obtains and manages presentation data.

olerender_format	The client calls the OleGetData function to retrieve data in a specific format. The client DLL obtains and manages the data in the requested format, as specified by the cfFormat parameter.

cfFormat	Specifies the clipboard format when the renderopt parameter is olerender_format. This clipboard format is used in a subsequent call to the OleGetData function. If this clipboard format is CF_ METAFILEPICT, CF_ENHMETAFILE, CF_DIB, or CF_BITMAP, the DLL manages the data and draws the object. The client DLL does not support drawing for any other formats.

The olerender_none rendering option is typically used to support hyper links. With this option, the client does not call the OleDraw function and calls the OleGetData function only for ObjectLink, OwnerLink, and Native formats.

The olerender_format rendering option allows a client to compute data (instead of painting it), use an unusual data format, or modify a standard data format. With this option the client does not call OleDraw. The client calls OleGetData to retrieve data in the specified format.

The olerender_draw rendering option is the most typical option. It is the easiest rendering option for the client to implement (the client simply calls the OleDraw function) and it allows the most flexibility. An object handler can exploit this flexibility to store no presentation data, a private presentation data format, or several different formats that it can choose among dynamically. Future implementations of OLE may also exploit the flexibility that is inherent in this option.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_HANDLE

OLE_ERROR_NAME

OLE_ERROR_PROTOCOL

OLE_WAIT_FOR_RELEASE

See Also

OleCreateFromClip, OleCreateFromTemplate, OleDraw, OleGetData


OleCreateFromClip function

OLESTATUS OleCreateFromClip(lpszProtocol, lpClient, lhClientDoc, lpszObjname, lplpObject, renderopt, cfFormat)

LPSTR lpszProtocol;
LPOLECLIENT lpClient;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR * lplpObject;
OLEOPT_RENDER renderopt;
OLECLIPFORMAT cfFormat;

The OleCreateFromClip function creates an object from the clipboard.

Parameter	Description

lpszProtocol	Points to a null-terminated string specifying the name of the protocol required for the new embedded object. Currently this value can be "StdFileEditing" (the name of the OLE protocol) or "Static" (for uneditable pictures only).

lpClient	Points to an OLECLIENT structure allocated and initialized by the client application. This pointer is used to locate the callback function and is passed in callback notifications.

lhClientDoc	Identifies the client document in which the object is being created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object. This name must be unique with respect to the names of any other objects in the document and cannot contain the forward- slash ("/") character.

lplpObject	Points to a variable where the client DLL will store the long pointer to the new object.

renderopt	Specifies the client's preference for presentation data for the object. This parameter can be one of the following values:

Value	Meaning

olerender_none	The client DLL does not obtain any presentation data and does not draw the object.

olerender_draw	The client calls the OleDraw function, and the client DLL obtains and manages presentation data.

olerender_format	The client calls the OleGetData function to retrieve data in a specific format. The client DLL obtains and manages the data in the requested format, as specified by the cfFormat parameter.

cfFormat	Specifies the clipboard format when the renderopt parameter is olerender_format. This clipboard format is used in a subsequent call to the OleGetData function. If this clipboard format is CF_METAFILEPICT, CF_ENHMETAFILE, CF_DIB, or CF_BITMAP, the DLL manages the data and draws the object. The client DLL does not support drawing for any other formats.

The client application should open and empty the clipboard, call the OleCreateFromClip function, and close the clipboard.

The olerender_none rendering option is typically used to support hyper links. With this option, the client does not call the OleDraw function and calls the OleGetData function only for ObjectLink, OwnerLink, and Native formats.

The olerender_format rendering option allows a client to compute data (instead of painting it), use an unusual data format, or modify a standard data format. With this option the client does not call OleDraw. The client calls OleGetData to retrieve data in the specified format.

The olerender_draw rendering option is the most typical option. It is the easiest rendering option for the client to implement (the client simply calls the OleDraw function) and it allows the most flexibility. An object handler can exploit this flexibility to store no presentation data, a private presentation data format, or several different formats that it can choose among dynamically. Future implementations of OLE may also exploit the flexibility that is inherent in this option.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_CLIPBOARD

OLE_ERROR_FORMAT

OLE_ERROR_HANDLE

OLE_ERROR_NAME

OLE_ERROR_OPTION

OLE_ERROR_PROTOCOL

OLE_WAIT_FOR_RELEASE

See Also

OleCreate, OleCreateFromTemplate, OleDraw, OleGetData, OleQueryCreateFromClip


OleCreateFromFile function

OLESTATUS OleCreateFromFile(lpszProtocol, lpClient, lpszClass, lpszFile, lhClientDoc, lpszObjname, lplpObject, renderopt, cfFormat)

LPSTR lpszProtocol;
LPOLECLIENT lpClient;
LPSTR lpszClass;
LPSTR lpszFile;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR * lplpObject;
OLEOPT_RENDER renderopt;
OLECLIPFORMAT cfFormat;

The OleCreateFromFile function creates an embedded object from the contents of a named file.

Parameter	Description

lpszProtocol	Points to a null-terminated string specifying the name of the protocol required for the new embedded object. Currently this value can be "StdFileEditing" (the name of the OLE protocol).

lpClient	Points to an OLECLIENT structure allocated and initialized by the client application. This pointer is used to locate the callback function and is passed in callback notifications.

lpszClass	Points to a null-terminated string specifying the name of the class for the new object. If this value is NULL, the client DLL uses the extension of the filename pointed to by the lpszFile parameter to find the class name for the object.

lpszFile	Points to a null-terminated string specifying the name of the file containing the object.

lhClientDoc	Identifies the client document in which the object is being created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object. This name must be unique with respect to the names of any other objects in the document and cannot contain the forward-slash ("/") character.

lplpObject	Points to a variable where the client DLL will store the long pointer to the new object.

renderopt	Specifies the client's preference for presentation data for the object. This parameter can be one of the following values:

Value	Meaning

olerender_none	The client DLL does not obtain any presentation data and does not draw the object.

olerender_draw	The client calls the OleDraw function, and the client DLL obtains and manages presentation data.

olerender_format	The client calls the OleGetData function to retrieve data in a specific format. The client DLL obtains and manages the data in the requested format, as specified by the cfFormat parameter.

cfFormat	Specifies the clipboard format when the renderopt parameter is olerender_format. This clipboard format is used in a subsequent call to the OleGetData function. If this clipboard format is CF_METAFILEPICT, CF_ENHMETAFILE, CF_DIB, or CF_BITMAP, the DLL manages the data and draws the object. The client DLL does not support drawing for any other formats.

When a client application calls the OleCreateFromFile function, the server is started to render the Native and presentation data and then closed. (If the server and document are already open, this function simply retrieves the information, without closing the server.) The server does not show the object to the user for editing.

The olerender_none rendering option is typically used to support hyperlinks. With this option, the client does not call the OleDraw function and calls the OleGetData function only for ObjectLink, OwnerLink, and Native formats.

The olerender_format rendering option allows a client to compute data (instead of painting it), use an unusual data format, or modify a standard data format. With this option the client does not call OleDraw. The client calls OleGetData to retrieve data in the specified format.

The olerender_draw rendering option is the most typical option. It is the easiest rendering option for the client to implement (the client simply calls the OleDraw function) and it allows the most flexibility. An object handler can exploit this flexibility to store no presentation data, a private presentation data format, or several different formats that it can choose among dynamically.

If a client application accepts files dropped from File Manager, it should respond to the WM_DROPFILES message by calling OleCreateFromFile and specifying "Packager" for the lpszClass parameter.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_CLASS

OLE_ERROR_HANDLE

OLE_ERROR_MEMORY

OLE_ERROR_NAME

OLE_ERROR_PROTOCOL

OLE_WAIT_FOR_RELEASE

See Also

OleCreate, OleCreateFromTemplate, OleDraw, OleGetData


OleCreateFromTemplate function

OLESTATUS OleCreateFromTemplate(lpszProtocol, lpClient, lpszTemplate, lhClientDoc, lpszObjname, lplpObject, renderopt, cfFormat)

LPSTR lpszProtocol;
LPOLECLIENT lpClient;
LPSTR lpszTemplate;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR * lplpObject;
OLEOPT_RENDER renderopt;
OLECLIPFORMAT cfFormat;

The OleCreateFromTemplate function creates an object by using another object as a template. The server is opened to perform the initial editing.

Parameter	Description

lpszProtocol	Points to a null-terminated string specifying the name of the protocol required for the new embedded object. Currently this value can be "StdFileEditing" (the name of the OLE protocol).

lpClient	Points to an OLECLIENT structure for the new object.

lpszTemplate	Points to a null-terminated string specifying the path and filename of the file to be used as a template for the new object. The server is opened for editing and loads the initial state of the new object from the named template file.

lhClientDoc	Identifies the client document in which the object is being created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object. This name must be unique with respect to the names of any other objects in the document and cannot contain the forward-slash ("/") character.

lplpObject	Points to a variable where the client DLL will store the long pointer to the new object.

renderopt	Specifies the client's preference for presentation data for the object. This parameter can be one of the following values:

Value	Meaning

olerender_none	The client DLL does not obtain any presentation data and does not draw the object.

olerender_draw	The client calls the OleDraw function, and the client DLL obtains and manages presentation data.

olerender_format	The client calls the OleGetData function to retrieve data in a specific format. The client DLL obtains and manages the data in the requested format, as specified by the cfFormat parameter.

cfFormat	Specifies the clipboard format when the renderopt parameter is olerender_format. This clipboard format is used in a subsequent call to the OleGetData function. If this clipboard format is CF_METAFILEPICT, CF_ENHMETAFILE, CF_DIB, or CF_BITMAP, the DLL manages the data and draws the object. The client DLL does not support drawing for any other formats.

The client DLL uses the filename extension of the file specified in the lpszTemplate parameter to identify the server for the object. The association between the extension and the server is stored in the registry.

The olerender_none rendering option is typically used to support hyperlinks. With this option, the client does not call the OleDraw function and calls the OleGetData function only for ObjectLink, OwnerLink, and Native formats.

The olerender_format rendering option allows a client to compute data (instead of painting it), use an unusual data format, or modify a standard data format. With this option the client does not call OleDraw. The client calls OleGetData to retrieve data in the specified format.

The olerender_draw rendering option is the most typical option. It is the easiest rendering option for the client to implement (the client simply calls the OleDraw function) and it allows the most flexibility. An object handler can exploit this flexibility to store no presentation data, a p rivate presentation data format, or several different formats that it can choose among dynamically. Future implementations of OLE may also exploit the flexibility that is inherent in this option.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_CLASS

OLE_ERROR_GENERIC

OLE_ERROR_HANDLE

OLE_ERROR_MEMORY

OLE_ERROR_NAME

OLE_ERROR_PROTOCOL

OLE_WAIT_FOR_RELEASE

See Also

OleCreate, OleCreateFromClip, OleDraw, OleGetData, OleObjectConvert


OleCreateInvisible function

OLESTATUS OleCreateInvisible(lpszProtocol, lpClient, lpszClass, lhClientDoc, lpszObjname, lplpObject, renderopt, cfFormat)

LPSTR lpszProtocol;
LPOLECLIENT lpClient;
LPSTR lpszClass;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR* lplpObject;
OLEOPT_RENDER renderopt;
OLECLIPFORMAT cfFormat;
BOOL fActivate;

The OleCreateInvisible function creates an object without displaying the server application to the user. The function either starts the server to create the object or creates a blank object of the specified class and format without starting the server.

Parameter	Description

lpszProtocol	Points to a null-terminated string specifying the name of the protocol required for the new embedded object. Currently this value can be "StdFileEditing" (the name of the OLE protocol) or "Static" (for uneditable pictures only).

lpClient	Points to an OLECLIENT structure allocated and initialized by the client application. This pointer is used to locate the client applications CallBack function and is passed in callback notifications.

lpszClass	Points to a null-terminated string specifying the registered name of the class of the object to be created.

lhClientDoc	Identifies the client document in which the object is being created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object. This name must be unique with respect to the names of any other objects in the document and cannot contain the forward-slash ("/") character.

lplpObject	Points to a variable where the client DLL will store the long pointer to the new object.

renderopt	Specifies the client's preference for presentation data for the object. This parameter can be one of the following values:

Value	Meaning

olerender_none	The client DLL does not obtain any presentation data and does not draw the object.

olerender_draw	The client calls the OleDraw function, and the client DLL obtains and manages presentation data.

olerender_format	The client calls the OleGetData function to retrieve data in a specific format. The client DLL obtains and manages the data in the requested format, as specified by the cfFormat parameter.

cfFormat	Specifies the clipboard format when the renderopt parameter is olerender_format. This clipboard format is used in a subsequent call to the OleGetData function. If this clipboard format is CF_METAFILEPICT, CF_ENHMETAFILE, CF_DIB, or CF_BITMAP, the client DLL manages the data and draws the object. The client DLL does not support drawing for any other formats.

fActivate	Specifies whether to start the server for the object. If this parameter is TRUE the server is started (but not shown). If this parameter is FALSE, the server is not started and the function creates a blank object of the specified class and format.

An application can avoid redrawing an object repeatedly by calling the OleCreateInvisible function before using such functions as OleSetBounds, OleSetColorScheme and OleSetTargetDevice to set up the object.

After setting up the object, the application can either call the OleActivate function to display the object, or the OleUpdate and OleClose functions to update the object without displaying it.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_CLASS

OLE_ERROR_HANDLE OLE_ERROR_NAME OLE_ERROR_PROTOCOL

See Also

OleActivate, OleClose, OleSetBounds, OleSetColorScheme, OleSetTargetDevice,  OleUpdate


OleCreateLinkFromClip function

OLESTATUS OleCreateLinkFromClip(lpszProtocol, lpClient, lhClientDoc, lpszObjname, lplpObject, renderopt, cfFormat)

LPSTR lpszProtocol;
LPOLECLIENT lpClient;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR * lplpObject;
OLEOPT_RENDER renderopt;
OLECLIPFORMAT cfFormat;

The OleCreateLinkFromClip function typically creates a link to an object from the clipboard.

Parameter	Description

lpszProtocol	Points to a null-terminated string specifying the name of the required protocol. Currently this value can be "StdFileEditing" (the name of the OLE protocol).

lpClient	Points to an OLECLIENT structure allocated and initialized by the client application. This pointer is used to locate the callback function and is passed in callback notifications.

lhClientDoc	Identifies the client document in which the object is being created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object. This name must be unique with respect to the names of any other objects in the document and cannot contain the forward-slash ("/") character.

lplpObject	Points to a variable where the client DLL will store the long pointer to the new object.

renderopt	Specifies the client's preference for presentation data for the object. This parameter can be one of the following values:

Value	Meaning

olerender_none	The client DLL does not obtain any presentation data and does not draw the object.

olerender_draw	The client calls the OleDraw function, and the client DLL obtains and manages presentation data.

olerender_format	The client calls the OleGetData function to retrieve data in a specific format. The client DLL obtains and manages the data in the requested format, as specified by the cfFormat parameter.

cfFormat	Specifies the clipboard format when the renderopt parameter is olerender_format. This clipboard format is used in a subsequent call to the OleGetData function. If this clipboard format is CF_METAFILEPICT, CF_ENHMETAFILE, CF_DIB, or CF_BITMAP, the DLL manages the data and draws the object. The client DLL does not support drawing for any other formats.

The olerender_none rendering option is typically used to support hyperlinks. With this option, the client does not call the OleDraw function and calls the OleGetData function only for ObjectLink, OwnerLink, and Native formats.

The olerender_format rendering option allows a client to compute data (instead of painting it), use an unusual data format, or modify a standard data format. With this option the client does not call OleDraw. The client calls OleGetData to retrieve data in the specified format.

The olerender_draw rendering option is the most typical option. It is the easiest rendering option for the client to implement (the client simply calls the OleDraw function) and it allows the most flexibility. An object handler can exploit this flexibility to store no presentation data, a private presentation data format, or several different formats that it can choose among dynamically. Future implementations of OLE may also exploit the flexibility that is inherent in this option.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_CLIPBOARD

OLE_ERROR_FORMAT

OLE_ERROR_HANDLE

OLE_ERROR_NAME

OLE_ERROR_OPTION

OLE_ERROR_PROTOCOL

OLE_WAIT_FOR_RELEASE

See Also

OleCreate, OleCreateFromTemplate, OleDraw, OleGetData, OleQueryLinkFromClip


OleCreateLinkFromFile function

OLESTATUS OleCreateLinkFromFile(lpszProtocol, lpClient, lpszClass, lpszFile, lpszItem, lhClientDoc, lpszObjname, lplpObject, renderopt, cfFormat)

LPSTR lpszProtocol;
LPOLECLIENT lpClient;
LPSTR lpszClass;
LPSTR lpszFile;
LPSTR lpszItem;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR *lplpObject;
OLEOPT_RENDER renderopt;
OLECLIPFORMAT cfFormat;

The OleCreateLinkFromFile function creates a linked object from a file that contains an object. If necessary, the client DLL starts the server to render the presentation data, but the object is not shown in the server for editing.

Parameter	Description

lpszProtocol	Points to a null-terminated string specifying the name of the required protocol. Currently this value can be "StdFileEditing" (the name of the OLE protocol).

lpClient	Points to an OLECLIENT structure allocated and initialized by the client application. This pointer is used to locate the callback function and is passed in callback notifications.

lpszClass	Points to a null-terminated string specifying the name of the class for the new object. If this value is NULL, the DLL uses the extension of the filename pointed to by the lpszFile parameter to find the class name for the object.

lpszFile	Points to a null-terminated string specifying the name of the file containing the object.

lpszItem	Points to a null-terminated string identifying the part of the document to link to. If this value is NULL, the link is to the entire document.

lhClientDoc	Identifies the client document in which the object is being created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object. This name must be unique with respect to the names of any other objects in the document and cannot contain the forward-slash ("/") character.

lplpObject	Points to a variable where the client DLL will store the long pointer to the new object.

renderopt	Specifies the client's preference for presentation data for the object. This parameter can be one of the following values:

Value	Meaning

olerender_none	The client DLL does not obtain any presentation data and does not draw the object.

olerender_draw	The client calls the OleDraw function, and the client DLL obtains and manages presentation data.

olerender_format	The client calls the OleGetData function to retrieve data in a specific format. The client DLL obtains and manages the data in the requested format, as specified by the cfFormat parameter.

cfFormat	Specifies the clipboard format when the renderopt parameter is olerender_format. This clipboard format is used in a subsequent call to the OleGetData function. If this clipboard format is CF_METAFILEPICT, CF_ENHMETAFILE, CF_DIB, or CF_BITMAP, the client DLL manages the data and draws the object. The client DLL does not support drawing for any other formats.

The olerender_none rendering option is typically used to support hyperlinks. With this option, the client does not call the OleDraw function and calls the OleGetData function only for ObjectLink, OwnerLink, and Native formats.

The olerender_format rendering option allows a client to compute data (instead of painting it), use an unusual data format, or modify a standard data format. With this option the client does not call OleDraw. The client calls OleGetData to retrieve data in the specified format.

The olerender_draw rendering option is the most typical option. It is the easiest rendering option for the client to implement (the client simply calls the OleDraw function) and it allows the most flexibility. An object handler can exploit this flexibility to store no presentation data, a private presentation data format, or several different formats that it can choose among dynamically. Future implementations of OLE may also exploit the flexibility that is inherent in this option.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_CLASS

OLE_ERROR_HANDLE

OLE_ERROR_MEMORY

OLE_ERROR_NAME

OLE_ERROR_PROTOCOL

OLE_WAIT_FOR_RELEASE

See Also

OleCreate, OleCreateFromFile, OleCreateFromTemplate, OleDraw, OleGetData


OleDelete function

OLESTATUS OleDelete(lpObject)

LPOLEOBJECT lpObject;

The OleDelete function deletes an object and frees memory that was associated with that object. If the object was open, it is closed.

Parameter	Description

lpObject	Points to the object to delete.

An application uses the OleDelete function when the object is no longer part of the client document.

The OleDelete function, unlike OleRelease, indicates that the object has been permanently removed.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_OBJECT

OLE_WAIT_FOR_RELEASE

See Also

OleClose, OleRelease


OleLoadFromStream function

OLESTATUS OleLoadFromStream(lpStream, lpszProtocol, lpClient, lhClientDoc, lpszObjname, lplpObject)

LPOLESTREAM lpStream;
LPSTR lpszProtocol;
LPOLECLIENT lpClient;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR * lplpObject;

The OleLoadFromStream function loads an object from the containing document.

Parameter	Description

lpStream	Points to an OLESTREAM structure that was allocated and initialized by the client application. The client DLL calls the Get function in the OLESTREAMVTBL structure to obtain the data for the object.

lpszProtocol	Points to a null-terminated string specifying the name of the required protocol. Currently this value can be "StdFileEditing" (the name of the OLE protocol) or "Static" (for uneditable pictures only).

lpClient	Points to an OLECLIENT structure allocated and initialized by the client application. This pointer is used to locate the callback function and is passed in callback notifications.

lhClientDoc	Identifies the client document in which the object is being created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object.

lplpObject	Points to a variable in which the client DLL stores a pointer to the loaded object.

To load an object, the client application needs only the location of that object in a file. A client typically loads an object only when the object is needed (for example, when it must be displayed).

If an object cannot be loaded when the lpszProtocol parameter specifies "StdFileEditing," the application can call the OleLoadFromStream function again, specifying "Static."

If the object is linked and the server and document are open, the DLL automatically makes the link between the client and server applications when an application calls OleLoadFromStream.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_HANDLE

OLE_ERROR_NAME

OLE_ERROR_PROTOCOL

OLE_ERROR_STATIC_FROM_OTHER_OS

OLE_ERROR_STREAM

OLE_WAIT_FOR_RELEASE

See Also

OleSaveToStream, OleQuerySize


OleObjectConvert function

OLESTATUS OleObjectConvert(lpObject, lpszProtocol, lpClient, lhClientDoc, lpszObjname, lplpObject)

LPOLEOBJECT lpObject;
LPSTR lpszProtocol;
LPOLECLIENT lpClient;
LHCLIENTDOC lhClientDoc;
LPSTR lpszObjname;
LPOLEOBJECT FAR * lplpObject;

The OleObjectConvert function creates a new object that supports a specified protocol by converting an existing object. This function neither deletes nor replaces the original object.

Parameter	Description

lpObject	Points to the object to convert.

lpszProtocol	Points to a null-terminated string specifying the name of the required protocol. Currently this value can be "Static" (for uneditable pictures only).

lpClient	Points to an OLECLIENT structure for the new object.

lhClientDoc	Identifies the client document in which the object is being created.

lpszObjname	Points to a null-terminated string specifying the client's name for the object. This name must be unique with respect to the names of any other objects in the document and cannot contain the forward-slash ("/") character.

lplpObject	Points to a variable in which the client DLL stores a pointer to the new object.

The only conversion currently supported is changing linked or embedded objects to static objects.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_HANDLE

OLE_ERROR_MEMORY

OLE_ERROR_NAME

OLE_ERROR_OBJECT

OLE_ERROR_PROTOCOL

OLE_ERROR_STATIC

See Also

OleClone


OleRelease function

OLESTATUS OleRelease(lpObject)

LPOLEOBJECT lpObject;

The OleRelease function releases an object from memory and closes it if it was open.

Parameter	Description

lpObject	Points to the object to release.

This function does not indicate that the object has been deleted from the client document.

The OleRelease function should be called for all objects when closing the client document.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_OBJECT

OLE_WAIT_FOR_RELEASE

See Also

OleDelete


Object Management Functions

The following functions support opening, closing, and drawing objects.

Function	Description

OleActivate	Executes an object's verb which could start the object's server application.

OleClose	Breaks the connection between an object and a server application.

OleCopyToClipboard	Places a copy of an object on the clipboard.

OleDraw	Draws an object onto any device context.

OleEnumObjects	Enumerates the objects in a document.

OleEqual	Compares two objects for equality.

OleExecute	Sends DDE Execute messages to an object's server application.

OleReconnect	Reconnects a linked object to a server after OleClose.

OleRename	Informs the client DLL that an object name changed.

OleSaveToStream	Saves an object to a file or other storage.

OleUpdate	Updates an object's data and display.


OleActivate function

OLESTATUS OleActivate(lpObject, iVerb, fShow, fTakeFocus, hwnd, lpBounds)

LPOLEOBJECT lpObject;
UINT iVerb;
BOOL fShow;
BOOL fTakeFocus;
HWND hwnd;
const RECT FAR* lpBounds;

The OleActivate function opens an object for an operation. Typically, the object is edited or played.

Parameter	Description

lpObject	Points to the object to activate.

iVerb	Specifies which operation to perform (0 = the primary verb, 1 = the first secondary verb, 2 = the second secondary verb, and so on).

fShow	Specifies whether the window is to be shown. If the window is to be shown, this value is TRUE; otherwise, it is FALSE.

fTakeFocus	Specifies whether the server should get the focus. If the server should get the focus, this value is TRUE, otherwise, it is FALSE. This parameter is relevant only if the fShow parameter is TRUE.

hwnd	Identifies the window of the document containing the object. This parameter can be NULL.

lpBounds	Points to a RECT structure containing the coordinates of the bounding rectangle in which the destination document displays the object. This parameter can be NULL. The mapping mode of the device context determines the units for these coordinates.

Typically, a server is launched in a separate window; editing then occurs asynchronously. The client is notified of changes to the object through the callback function.

A client application might set the fShow parameter to FALSE if a server needed to remain active without being visible on the display. (In this case, the application would also use the OleSetData function.)

Client applications typically specify the primary verb when the user double-clicks an object. The server can take any action in response to the specified verb. If the server supports only one action, it takes that action no matter which value is passed in the iVerb parameter.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_OBJECT

OLE_WAIT_FOR_RELEASE

See Also

OleQueryOpen, OleSetData


OleClose function

OLESTATUS OleClose(lpObject)

LPOLEOBJECT lpObject;

The OleClose function closes the specified open object.

Parameter	Description

lpObject	Points to the object to close.

Closing an object terminates the connection with the server application.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_OBJECT

OLE_WAIT_FOR_RELEASE

See Also

OleActivate, OleDelete, OleReconnect


OleCopyToClipboard function

OLESTATUS OleCopyToClipboard(lpObject)

LPOLEOBJECT lpObject;

The OleCopyToClipboard function puts the specified object on the clipboard.

Parameter	Description

lpObject	Points to the object to copy to the clipboard.

A client application typically calls the OleCopyToClipboard function when a user chooses the Copy or Cut command from the Edit menu.

The client application should open and empty the clipboard, call the OleCopyToClipboard function, and close the clipboard.

The return value is OLE_OK if successful; otherwise, it could be OLE_ERROR_OBJECT.


OleDraw function

OLESTATUS OleDraw(lpObject, hdc, lprcBounds, lprcWBounds, hdcFormat)

LPOLEOBJECT lpObject;
HDC hdc;
const RECT FAR* lprcBounds;
const RECT FAR* lprcWBounds;
HDC hdcFormat;

The OleDraw function draws a specified object into a bounding rectangle in a device context.

Parameter	Description

lpObject	Points to the object to draw.

hdc	Identifies the device context in which to draw the object.

lprcBounds	Points to a RECT structure defining the bounding rectangle (in logical units for the device context specified by the hdc parameter) in which to draw the object.

lprcWBounds	If the hdc parameter is not a handle to metafile, lprcWBounds (this parameter) should be NULL. If hdc is a metafile, then lprcWBounds points to a special RECT structure defining the bounding rectangle of the window to be drawn.

hdcFormat	Identifies a device context describing the target device for which to format the object.

The client DLL may use an object handler to render the object, and this object handler may need information about the target device. Therefore, the device-context handle specified by the hdcFormat parameter is required. The lprcBounds parameter identifies the rectangle on the device context (relative to its current mapping mode) that the object should be mapped onto. This may involve scaling the picture and can be used by client applications to impose a view scaling between the displayed view and the final printed image.

An object handler should format an object as if it were to be drawn at the size specified by a call to the OleSetBounds function for the device context specified by the hdcFormat parameter. Often this formatting will already have been done by the server application; in this case, the DLL simply renders the presentation data with suitable scaling for the required bounding rectangle. If cropping or banding is required, the device context in which the object is drawn may include a clipping region smaller than the specified bounding rectangle.

When the hdc parameter specifies a metafile device context, the rectangle specified by the lprcWBounds parameter contains the coordinate system that will be used by the metafile. Unlike normal RECT structures, the left and top members of the RECT structure should specify the window origin, and the right and bottom members should specify the window extents. The following sample code illustrates how the lprcWBounds parameter is set and used for metafiles using the MM_ANISOTROPIC mapping mode:

hdc = CreateMetaFile (NULL);

SetWindowOrg (hdc, xOrg, yOrg);

SetWindowExt (hdc, xExt, yExt);

lprcWBounds->left = xOrg;

lprcWBounds->top = yOrg;

lprcWBounds->right = xExt;

lprcWBounds->bottom = yExt;

OleDraw (lpobject, hdc, lprcBounds, lprcWBounds, NULL);

hmf = CloseMetaFile(hdc);

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_ABORT

OLE_ERROR_BLANK

OLE_ERROR_DRAW

OLE_ERROR_HANDLE

OLE_ERROR_MEMORY

OLE_ERROR_OBJECT

This function returns OLE_ERROR_ABORT if the callback function returns FALSE during drawing.

See Also

OleSetBounds


OleEnumObjects function

OLESTATUS OleEnumObjects(lhDoc, lplpObject)

LHCLIENTDOC lhDoc;
LPOLEOBJECT FAR * lplpObject;

The OleEnumObjects function enumerates the objects in a specified document.

Parameter	Description

lhDoc	Identifies the document for which the objects are enumerated.

lplpObject	Points to an object in the document when the function returns. For the first call to this function, this parameter should point to a NULL object.

When an application specifies a NULL object for the lplpObject parameter, the OleEnumObjects function returns the first object in the document. Whenever an application specifies an object that was returned by a previous call to OleEnumObjects , the function returns the next object, in sequence. When there are no more objects in the document, the lplpObject parameter points to a NULL object. The objects that have been deleted are not enumerated by this function.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_HANDLE

OLE_ERROR_OBJECT

See Also

OleDelete, OleRelease


OleEqual function

OLESTATUS OleEqual(lpObject1, lpObject2)

LPOLEOBJECT lpObject1;
LPOLEOBJECT lpObject2;

The OleEqual function compares two objects for equality.

Parameter	Description

lpObject1	Points to the first object to test for equality.

lpObject2	Points to the second object to test for equality.

Embedded objects are equal if their class, item, and native data are identical. Linked objects are equal if their class, document, and item are identical.

The return value is OLE_OK if the specified objects are equal; otherwise, it could be one of the following:

OLE_ERROR_OBJECT

OLE_ERROR_NOT_EQUAL

See Also

OleClone, OleQueryOutOfDate


OleExecute function

OLESTATUS OleExecute(lpObject, hCommands, wReserved)

LPOLEOBJECT lpObject;
HGLOBAL hCommands;
UINT wReserved;

The OleExecute function sends DDE execute commands to the server for the specified object.

Parameter	Description

lpObject	Points to an object identifying the server to which DDE execute commands are sent.

hCommands	Identifies the memory containing one or more DDE execute commands.

wReserved	Reserved; must be zero.

The client application should call the OleQueryProtocol function, specifying "StdExecute", before calling the OleExecute function. The OleQueryProtocol function succeeds if the server for an object supports the Execute callback function.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_COMMAND

OLE_ERROR_MEMORY

OLE_ERROR_NOT_OPEN

OLE_ERROR_OBJECT

OLE_ERROR_PROTOCOL

OLE_ERROR_STATIC

OLE_WAIT_FOR_RELEASE

See Also

OleQueryProtocol


OleReconnect function

OLESTATUS OleReconnect(lpObject)

LPOLEOBJECT lpObject;

The OleReconnect function reestablishes a link to an open linked object. If the specified object is not open, this function does not open it.

Parameter	Description

lpObject	Points to the object to reconnect to.

A client application can use the OleReconnect function to keep the presentation for a linked object up-to-date. The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_OBJECT

OLE_ERROR_NOT_LINK

OLE_WAIT_FOR_RELEASE

See Also

OleActivate, OleClose, OleQueryOpen


OleRename function

OLESTATUS OleRename(lpObject, lpszNewname)

LPOLEOBJECT lpObject;
LPSTR lpszNewname;

The OleRename function renames an object.

Parameter	Description

lpObject	Points to the object that is being renamed.

lpszNewname	Points to a null-terminated string specifying the new name of the object.

Object names need not be seen by the user. They must be unique within the containing document and must be preserved when the document is saved.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_OBJECT

OLE_ERROR_NAME.

See Also

OleQueryName


OleSaveToStream function

OLESTATUS OleSaveToStream(lpObject, lpStream)

LPOLEOBJECT lpObject;
LPOLESTREAM lpStream;

The OleSaveToStream function saves an object to the stream.

Parameter	Description

lpObject	Points to the object to save to the stream.

lpStream	Points to an OLESTREAM structure allocated and initialized by the client application. The client DLL calls the Put function in the OLESTREAM structure to store the data from the object.

An application can use the OleQuerySize function to find the number of bytes to allocate for the object.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_BLANK

OLE_ERROR_MEMORY

OLE_ERROR_OBJECT

OLE_ERROR_STREAM

See Also

OleLoadFromStream, OleQuerySize


OleUpdate function

OLESTATUS OleUpdate(lpObject)

LPOLEOBJECT lpObject;

The OleUpdate function updates the specified object.

Parameter	Description

lpObject	Points to the object to be updated.

This function updates the presentation of the object and ensures that the object is up-to-date with respect to any linked objects it contains.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_GENERIC

OLE_ERROR_OBJECT

OLE_WAIT_FOR_RELEASE

See Also

OleQueryOutOfDate


Object Information Functions

The following functions are used to obtain information about an object.

Function	Description

OleEnumFormats	Enumerates available data formats for an object.

OleGetData	Retrieves an object's data in a specified format.

OleGetLinkUpdateOptions	Determines if a linked object is automatic or manual.

OleQueryBounds	Retrieves the bounding rectangle for an object.

OleQueryCreateFromClip	Determines if OleCreateFromClip will succeed.

OleQueryLinkFromClip	Determines if OleCreateLinkFromClip will succeed.

OleQueryName	Retrieves the name of an object stored in the client DLL.

OleQueryOpen	Determines if a server is currently editing an object.

OleQueryOutOfDate	Determines whether an object is out-of-date.

OleQueryProtocol	Determines if an object supports a protocol.

OleQueryReleaseError	Determines if an error caused an object's release.

OleQueryReleaseMethod	Determines which operation released an object.

OleQueryReleaseStatus	Determines if an object is released or busy.

OleQuerySize	Retrieves the size of an object in bytes.

OleQueryType	Determines if object is linked, embedded, or static.

OleRequestData	Retrieves data from a server in a specified format.


OleEnumFormats function

OLECLIPFORMAT OleEnumFormats(lpObject, cfFormat)

LPOLEOBJECT lpObject;
OLECLIPFORMAT cfFormat;

The OleEnumFormats function enumerates the data formats that describe a specified object.

Parameter	Description

lpObject	Points to the object to be queried.

cfFormat	Specifies the format returned by the last call to the OleEnumFormats function. For the first call to this function, this parameter is zero.

When an application specifies NULL for the cfFormat parameter, the OleEnumFormats function returns the first available format. Whenever an application specifies a format that was returned by a previous call to OleEnumFormats , the function returns the next available format, in sequence. When no more formats are available, the function returns NULL.

The return value is the next available format; otherwise, it is NULL.

See Also

OleGetData


OleGetData function

OLESTATUS OleGetData(lpObject, cfFormat, phData)

LPOLEOBJECT lpObject;
OLECLIPFORMAT cfFormat;
HANDLE FAR * phData;

The OleGetData function retrieves data in the requested format from the specified object and supplies a handle to a memory or graphical device interface (GDI) object containing the data.

Parameter	Description

lpObject	Points to the object from which data is retrieved.

cfFormat	Specifies the format in which data is returned. This parameter can be one of the predefined clipboard formats or the value returned by the RegisterClipboardFormat function.

phData	Points to the handle of a memory object that contains the data when the function returns.

If the OleGetData function returns OLE_WARN_DELETE_DATA, the client application owns the data and should free the memory associated with the data when the client application has finished using it. For other return values the client should not free the memory or modify the data, because the data is controlled by the client DLL. If the application needs the data for long-term use, it should copy the data.

The OleGetData function typically return s OLE_WARN_DELETE_DATA if an object handler generates data for an object that the client DLL cannot interpret. In this case, the client application is responsible for controlling that data.

When the OleGetData function specifies CF_METAFILE or CF_BITMAP, the phData parameter points to a GDI object, not a memory object, when the function returns. OleGetData supplies a handle to a memory object for all other formats.

If the function is successful, the return value is OLE_OK; otherwise, it is an error value, which may be one of the following:

OLE_BUSY

OLE_ERROR_BLANK

OLE_ERROR_FORMAT

OLE_WARN_DELETE_DATA

OLE_WAIT_FOR_RELEASE

See Also

OleEnumFormats, OleSetData, RegisterClipboardFormat


OleGetLinkUpdateOptions function

OLESTATUS OleGetLinkUpdateOptions(lpObject, lpUpdateOpt)

LPOLEOBJECT lpObject;
OLEOPT_UPDATE FAR * lpUpdateOpt;

The OleGetLinkUpdateOptions function retrieves the link-update options for the presentation of a specified object.

Parameter	Description

lpObject	Points to the object to query.

lpUpdateOpt	Points to a variable in which the function stores the current value of the link-update option for the specified object. The link-update option setting may be one of the following:

Option	Description

oleupdate_always	Update the linked object whenever possible. This option supports the Automatic link-update option button in the Links dialog box.

oleupdate_onsave	Update the linked object when the source document is saved by the server.

oleupdate_oncall	Update the linked object only on request from the client application. This option supports the Manual link-update option button in the Links dialog box.

The return value is OLE_OK if successful; otherwise, it is OLE_ERROR_OBJECT.

See Also

OleSetLinkUpdateOptions


OleQueryBounds function

OLESTATUS OleQueryBounds(lpObject, lpBounds)

LPOLEOBJECT lpObject;
RECT FAR* lpBounds;

The OleQueryBounds function retrieves the extents of the bounding rectangle on the target device for the specified object. The coordinates are in MM_HIMETRIC units.

The OLE libraries express the size of every object in MM_HIMETRIC units. Neither the width nor height of an object should exceed 32,767 MM_HIMETRIC units.

Parameter	Description

lpObject	Points to the object to query.

lpBounds	Points to a RECT structure for the extents of the bounding rectangle. The fields of the RECT structure have the following meaning:

Field	Meaning

rect.left	0

rect.top	0

rect.right	x-extent

rect.bottom	y-extent

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_BLANK

OLE_ERROR_GENERIC

OLE_ERROR_MEMORY

OLE_ERROR_OBJECT

See Also

OleSetBounds, SetMapMode


OleQueryCreateFromClip function

OLESTATUS OleQueryCreateFromClip(lpszProtocol, renderopt, cfFormat)

LPSTR lpszProtocol;
OLEOPT_RENDER renderopt;
OLECLIPFORMAT cfFormat;

The OleQueryCreateFromClip function checks whether the object on the clipboard supports the specified protocol and rendering options.

Parameter	Description

lpszProtocol	Points to a null-terminated string specifying the name of the protocol needed by the client. Currently this value can be "StdFileEditing", (the name of the OLE protocol) or "Static" (for uneditable pictures only).

renderopt	Specifies the client's preference for presentation data for the object. This parameter can be one of the following values:

Value	Meaning

olerender_none	The client DLL does not obtain any presentation data and does not draw the object.

olerender_draw	The client application calls the OleDraw function, and the client DLL obtains and manages presentation data.

olerender_format	The client DLL obtains and manages the data in the requested format, as specified by the cfFormat parameter.

cfFormat	Specifies the clipboard format. This parameter is used only when the renderopt parameter is olerender_format. If this clipboard format is CF_METAFILEPICT, CF_ENHMETAFILE, CF_DIB, or CF_BITMAP, the DLL manages the data and draws the object. The client DLL does not support drawing for any other formats.

The OleQueryCreateFromClip function is typically used to check whether to enable a Paste command.

The olerender_none rendering option is typically used to support hyperlinks. With this option, the client does not call the OleDraw function and calls the OleGetData function only for ObjectLink, OwnerLink, and Native formats.

The olerender_format rendering option allows a client to compute data (instead of painting it), use an unusual data format, or modify a standard data format. With this option the client does not call OleDraw. The client calls OleGetData to retrieve data in the specified format.

The olerender_draw rendering option is the most typical option. It is the easiest rendering option for the client to implement (the client simply calls the OleDraw function) and it allows the most flexibility. An object handler can exploit this flexibility to store no presentation data, a private presentation data format, or several different formats that it can choose among dynamically. Future implementations of object linking and embedding may also exploit the flexibility that is inherent in this option.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_FORMAT

OLE_ERROR_PROTOCOL

See Also

OleCreateFromClip, OleDraw, OleGetData


OleQueryLinkFromClip function

OLESTATUS OleQueryLinkFromClip(lpszProtocol, renderopt, cfFormat)

LPSTR lpszProtocol;
OLEOPT_RENDER renderopt;
OLECLIPFORMAT cfFormat;

The OleQueryLinkFromClip function checks whether a client application can use the data on the clipboard to produce a linked object that supports the specified protocol and rendering options.

Parameter	Description

lpszProtocol	Points to a null-terminated string specifying the name of the protocol needed by the client. Currently this value can be "StdFileEditing" (the name of the OLE protocol).

renderopt	Specifies the client's preference for presentation data for the object. This parameter can be one of the following values:

Value	Meaning

olerender_none	The client DLL does not obtain any presentation data and does not draw the object.

olerender_draw	The client calls the OleDraw function, and the DLL obtains and manages presentation data.

olerender_format	The DLL obtains and manages the data in the requested format, as specified by the cfFormat parameter.

cfFormat	Specifies the clipboard format. This parameter is used only when the renderopt parameter is olerender_format. If this clipboard format is CF_METAFILEPICT, CF_ENHMETAFILE, CF_DIB, or CF_BITMAP, the DLL manages the data and draws the object. The DLL does not support drawing for any other formats.

The OleQueryLinkFromClip function is typically used to check whether to enable a Paste Link command.

The olerender_none rendering option is typically used to support hyperlinks. With this option, the client does not call the OleDraw function and calls the OleGetData function only for ObjectLink, OwnerLink, and Native formats.

The olerender_format rendering option allows a client to compute data (instead of painting it), use an unusual data format, or modify a standard data format. With this option the client does not call OleDraw. The client calls OleGetData to retrieve data in the specified format.

The olerender_draw rendering option is the most typical option. It is the easiest rendering option for the client to implement (the client simply calls the OleDraw function) and it allows the most flexibility. An object handler can exploit this flexibility to store no presentation data, a private presentation data format, or several different formats that it can choose among dynamically. Future implementations of object linking and embedding may also exploit the flexibility that is inherent in this option.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_FORMAT

OLE_ERROR_PROTOCOL

See Also

OleCreateLinkFromClip, OleDraw, OleGetData


OleQueryName function

OLESTATUS OleQueryName(lpObject, lpszObject, lpwBuffSize)

LPOLEOBJECT lpObject;
LPSTR lpszObject;
UINT FAR * lpwBuffSize;

Parameter	Description

lpObject	Points to the object whose name is being queried.

lpszObject	Points to a character array that contains a null-terminated string. When the function returns, this string specifies the name of the object.

lpwBuffSize	Points to a variable containing the size (in bytes) of the buffer pointed to by the lpszObject parameter. When the function returns, this value is the number of bytes copied to the buffer.

The return value is OLE_OK if successful; otherwise, it could be

OLE_ERROR_OBJECT

OLE_ERROR_SIZE

See Also

OleRename


OleQueryOpen function

OLESTATUS OleQueryOpen(lpObject)

LPOLEOBJECT lpObject;

The OleQueryOpen function checks whether the specified object is open.

Parameter	Description

lpObject	Points to the object to query.

The return value is OLE_OK if the object is open; otherwise, it could be one of the following:

OLE_ERROR_OBJECT

OLE_ERROR_NOT_OPEN

See Also

OleActivate


OleQueryOutOfDate function

OLESTATUS OleQueryOutOfDate(lpObject)

LPOLEOBJECT lpObject;

The OleQueryOutOfDate function checks whether an object is out-of-date.

Parameter	Description

lpObject	Points to the object to query.

The OleQueryOutOfDate function has not been implemented for the current version of object linking and embedding. For linked objects, OleQueryOutOfDate always returns OLE_OK.

A linked object could be out-of-date if the document that is the source for the link has been updated. An embedded object that contains links to other objects could also be out-of-date.

The return value is OLE_OK if the object is up-to-date; otherwise, it is OLE_ERROR_OBJECT.

See Also

OleEqual, OleUpdate


OleQueryProtocol function

LPVOID OleQueryProtocol(lpobj, lpprotocol)

LPOLEOBJECT lpobj;
LPSTR lpszProtocol;

The OleQueryProtocol function checks whether an object supports a specified protocol.

Parameter	Description

lpobj	Points to the object to query.

lpszProtocol	Points to a null-terminated string specifying the name of the requested protocol. This value can be "StdFileEditing" or "StdExecute." Object handlers may support other protocols identified by other names.

The OleQueryProtocol function queries whether the specified protocol is supported and returns a modified object pointer that allows access to the function table for the protocol. This modified object pointer points to a structure that has the same form as the OLEOBJECT structure; the new structure also points to a table of functions and may contain additional state information. The new pointer does not point to a different object if the object is deleted, secondary pointers become invalid. If a protocol includes delete functions, calling a delete function invalidates all pointers to that object.

A client application typically calls the OleQueryProtocol function, specifying "StdExecute" in the lpszProtocol parameter, before calling the OleExecute function. This allows the client application to check whether the server for an object supports DDE execute commands.

The return value is NULL if the object does not support the requested protocol. Otherwise, the return value is a VOID pointer to a data structure similar to the OLEOBJECT structure, but the entries in the corresponding VTBL structure depend on the requested protocol.

For the standard protocols, StdFileEditing and StdExecute, the return value is an OLEOBJECT pointer with corresponding VTBL entries. If an object handler supports additional protocols, the entries in the VTBL structure may be different. Since the caller knows the string name to request, the caller must know the definition of the corresponding VTBL entries.

The DLL can return OLE_WAIT_FOR_RELEASE when an application calls this function.

See Also

OleExecute


OleQueryReleaseError function

OLESTATUS OleQueryReleaseError(lpobj)

LPOLEOBJECT lpobj;

The OleQueryReleaseError function checks the error value for an asynchronous operation on an object.

Parameter	Description

lpobj	Points to an object for which the error value is queried.

A client application receives the OLE_RELEASE notification when an asynchronous operation has terminated. The client should then call the OleQueryReleaseError function to check whether the operation has terminated successfully or with an error value.

The error value is reset when the client application returns from the callback function. The client application should call this function and store the error value.

The return value is OLE_OK if the asynchronous operation completed successfully; otherwise, it is the error value for that operation. If the pointer passed in the lpobj parameter is invalid, the function returns OLE_ERROR_OBJECT.

See Also

OleQueryReleaseMethod, OleQueryReleaseStatus


OleQueryReleaseMethod function

OLE_RELEASE_METHOD OleQueryReleaseMethod(lpobj)

LPOLEOBJECT lpobj;

The OleQueryReleaseMethod function finds out the operation that finished for the specified object.

Parameter	Description

lpobj	Points to an object for which the operation is queried.

The following return values indicate the server callback that finished.Return Value	Server Operation

OLE_NONE	No operation active

OLE_DELETE	Object Delete

OLE_LNKPASTE	PasteLink (auto reconnect)

OLE_EMBPASTE	Paste and Update

OLE_SHOW	Show

OLE_RUN	Run

OLE_ACTIVATE	Activate

OLE_UPDATE	Update

OLE_CLOSE	Close

OLE_RECONNECT	Reconnect

OLE_SETUPDATEOPTIONS	Setting update options

OLE_SERVERUNLAUNCH	Server is stopping

OLE_LOADFROMSTREAM	LoadFromStream (auto reconnect)

OLE_SETDATA	OleSetData

OLE_REQUESTDATA	OleRequestData

OLE_OTHER	Other miscellaneous asynchronous operations

OLE_CREATE	Create

OLE_CREATEFROMTEMPLATE	CreateFromTemplate

OLE_CREATELINKFROMFILE	CreateLinkFromFile

OLE_COPYFROMLNK	CopyFromLink (auto reconnect)

OLE_CREATEFROMFILE	CreateFromFile

If the pointer passed in the lpobj parameter is invalid, the function

returns OLE_ERROR_OBJECT.

A client application receives the OLE_RELEASE notification when an

asynchronous operation has ended. The client can then call the

OleQueryReleaseMethod function to check which operation caused the DLL to

send the OLE_RELEASE notification. The client calls OleQueryReleaseError

to determine whether the operation terminated successfully.See Also

OleQueryReleaseError, OleQueryReleaseStatus


OleQueryReleaseStatus function

OLESTATUS OleQueryReleaseStatus(lpobj)

LPOLEOBJECT lpobj;

The OleQueryReleaseStatus function determines whether an operation has finished for the specified object.

Parameter	Description

lpobj	Points to an object for which the operation is queried.

The return value is OLE_BUSY if an operation is in progress; otherwise, it is OLE_OK. If the pointer passed in the lpobj parameter is invalid, the function returns OLE_ERROR_OBJECT.

See Also

OleQueryReleaseError, OleQueryReleaseMethod


OleQuerySize function

OLESTATUS OleQuerySize(lpObject, pdwSize)

LPOLEOBJECT lpObject;
DWORD FAR * pdwSize;

The OleQuerySize function retrieves the size of the specified object.

Parameter	Description

lpObject	Points to the object to query.

pdwSize	Points to a variable for the size of the object. This variable contains the size of the object when the function returns.

The return value is OLE_OK if successful; otherwise, it is OLE_ERROR_OBJECT.

See Also

OleLoadFromStream


OleQueryType function

OLESTATUS OleQueryType(lpObject, lpType);

LPOLEOBJECT lpObject;
LONG FAR* lpType;

The OleQueryType function checks whether a specified object is embedded, linked, or static.

Parameter	Description

lpObject	Points to the object for which the type is queried.

lpType	Points to a LONG variable that contains the type of the object when the function returns. This parameter can be one of the following values:

Value	Meaning

OT_EMBEDDED	Object is embedded.

OT_LINK	Object is a link.

OT_STATIC	Object is a static picture.

The return value is OLE_OK if successful; otherwise, it is

OLE_ERROR_OBJECT.See Also

OleEnumFormats


OleRequestData function

OLESTATUS OleRequestData(lpObject, cfFormat)

LPOLEOBJECT lpObject;
OLECLIPFORMAT cfFormat;

The OleRequestData function requests the DLL to retrieve data in a specified format from a server.

Parameter	Description

lpObject	Points to the object that is associated with the server from which data is retrieved.

cfFormat	Specifies the format in which data is returned. This parameter can be one of the predefined clipboard formats or the value returned by the RegisterClipboardFormat function.

The client application should be connected to the server application when the client calls the OleRequestData function. When the client receives the OLE_RELEASE notification, it can retrieve the data from the object by using the OleGetData function or query the data by using such functions as OleQueryBounds and OleQuerySize.

If the requested data format is the same as the presentation data for the object, the DLL manages the data and updates the presentation.

The OleRequestData function returns OLE_WAIT_FOR_RELEASE if the server is busy. In this case, the application should continue to dispatch messages until it receives a callback notification with the OLE_RELEASE argument.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_FORMAT

OLE_ERROR_GENERIC

OLE_ERROR_NOT_OPEN

OLE_ERROR_OBJECT

OLE_WAIT_FOR_RELEASE

See Also

OleEnumFormats, OleGetData, OleSetData, RegisterClipboardFormat


Object Updating Functions

The following functions inform the client DLL of changes made to an object in the client document.

Function	Description

OleSetBounds	Informs the client DLL of the new object rectangle.

OleSetData	Changes the object's data for a specified format.

OleSetHostNames	Provides the client DLL with the object and document names.

OleSetLinkUpdateOptions	Changes a linked object between automatic and manual.

OleSetTargetDevice	Provides the client DLL with information about the output device.


OleSetBounds function

OLESTATUS OleSetBounds(lpObject, lpBounds)

LPOLEOBJECT lpObject;
const RECT FAR* lpBounds;

The OleSetBounds function sets the coordinates of the bounding rectangle for the specified object on the target device.

Parameter	Description

lpObject	Points to the object for which the bounding rectangle is set.

lpBounds	Points to a RECT structure containing the coordinates of the bounding rectangle. The coordinates are specified in MM_HIMETRIC units. Neither the width nor height of an object should exceed 32,767 MM_HIMETRIC units.

The OleSetBounds function is ignored for linked objects, because the size of a linked object is determined by the source document for the link.

A client application uses the OleSetBounds function to change the bounding rectangle. The client does not need to call OleSetBounds every time a server is opened.

The bounding rectangle specified in the OleSetBounds function does not necessarily have the same dimensions as the rectangle specified in the call to the OleDraw function. These dimensions may be different because of the view scaling used by the container application. An application can use OleSetBounds to cause the server to reformat the picture to fit the rectangle more closely.

In the MM_HIMETRIC mapping mode, the positive y-direction is up.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_MEMORY

OLE_ERROR_OBJECT

OLE_WAIT_FOR_RELEASE

The OleSetBounds function returns OLE_ERROR_OBJECT when it is called for a linked object.

See Also

OleDraw, OleQueryBounds, SetMapMode, RECT


OleSetData function

OLESTATUS OleSetData(lpObject, cfFormat, hData)

LPOLEOBJECT lpObject;
OLECLIPFORMAT cfFormat;
HANDLE hData;

The OleSetData function sends data in the specified format to the server associated with a specified object.

Parameter	Description

lpObject	Points to an object specifying the server to which data is sent.

cfFormat	Specifies the format of the data.

hData	Identifies a memory object containing the data in the specified format.

If the function is successful, the return value is OLE_OK; otherwise, it is an error value, which may be one of the following:

OLE_BUSY

OLE_ERROR_BLANK

OLE_ERROR_COMM

OLE_ERROR_MEMORY

OLE_ERROR_NOT_OPEN

OLE_ERROR_OBJECT

OLE_WAIT_FOR_RELEASE

If the specified object cannot accept the data, the function returns an error value. If the server is not open and the requested data format is different from the format of the presentation data, the return value is OLE_ERROR_NOT_OPEN.

See Also

OleGetData, OleRequestData


OleSetHostNames function

OLESTATUS OleSetHostNames(lpObject, lpszClient, lpszClientObj)

LPOLEOBJECT lpObject;
LPSTR lpszClient;
LPSTR lpszClientObj;

The OleSetHostNames function specifies the name of the client application and the client's name for the specified object. This information is used in window titles when the object is being edited in the server application.

Parameter	Description

lpObject	Points to the object for which a name is set.

lpszClient	Points to a null-terminated string specifying the name of the client application.

lpszClientObj	Points to a null-terminated string specifying the client's name for the object.

The OleSetHostNames function returns OLE_ERROR_OBJECT when it is called for a linked object.

When a server application is started to edit an embedded object, it displays the string specified in the lpszClientObj parameter in its title bar. The object name specified in this string should be the name of the client document containing the object.

A client application uses the OleSetHostNames function to set the name of an object the first time that object is active. The client does not need to call OleSetHostNames every time a server is opened.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_MEMORY

OLE_ERROR_OBJECT

OLE_WAIT_FOR_RELEASE


OleSetLinkUpdateOptions function

OLESTATUS OleSetLinkUpdateOptions(lpObject, UpdateOpt)

LPOLEOBJECT lpObject;
OLEOPT_UPDATE UpdateOpt;

The OleSetLinkUpdateOptions function sets the link-update options for the presentation of the specified object.

Parameter	Description

lpObject	Points to the object for which the link-update option is set.

UpdateOpt	Specifies the link-update option for the specified object. This parameter can be one of the following values:

Option	Description

oleupdate_always	Update the linked object whenever possible. This option supports the Automatic link-update radio button in the Links dialog box.

oleupdate_onsave	Update the linked object when the source document is saved by the server.

oleupdate_oncall	Update the linked object only on request from the client application. This option supports the Manual link-update radio button in the Links dialog box.

The return value is OLE_OK; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_OBJECT

OLE_ERROR_OPTION

OLE_ERROR_STATIC

OLE_WAIT_FOR_RELEASE

See Also

OleGetLinkUpdateOptions


OleSetTargetDevice function

OLESTATUS OleSetTargetDevice(lpObject, hTargetDevice)

LPOLEOBJECT lpObject;
HGLOBAL hTargetDevice;

The OleSetTargetDevice function specifies the target output device for an object.

Parameter	Description

lpObject	Points to the object for which a target device is specified.

hTargetDevice	Identifies a StdTargetDevice memory structure that describes the target device for the object. See the following comments for information about this structure.

The OleSetTargetDevice function allows a linked or embedded object to be formatted correctly for a target device, even when the object is rendered on a different device.

A client application should call this function whenever the target device changes, so that servers can be notified to change the rendering of the object, if necessary. The client application should call the OleUpdate function to ensure that the information is sent to the server so that the server can make the necessary changes to the object's presentation. The client application should call the DLL to redraw the object if i t receives a notification from the server that the object has changed.

A client application uses the OleSetTargetDevice function to change the target device. The client does not need to call OleSetTargetDevice every time a server is opened.

The StdTargetDevice structure accepts information about the target device that the client is using. The information is in binary format, interpreted as the following structure. (Offsets are relative to the start of the data array.)

struct {

    UINT deviceNameOffset;

    UINT driverNameOffset;

    UINT portNameOffset;

    UINT extDevModeOffset;

    UINT extDevModeSize;

    UINT environmentOffset;

    UINT environmentSize;

    BYTE data[];

} StdTargetDevice;

The deviceNameOffset, driverNameOffset, and portNameOffset members should be null-terminated.

In Windows 3.1, the ability to connect multiple printers to one port has made the environment obsolete. The environment information retrieved by the GetEnvironment function can occasionally be incorrect. To ensure that the StdTargetDevice structure is initialized correctly, the application should copy information from the DEVMODE structure retrieved by a call to the ExtDeviceMode function to the environment position of the StdTargetDevice structure.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_MEMORY

OLE_ERROR_OBJECT

OLE_WAIT_FOR_RELEASE


Miscellaneous Functions

The following functions can be used as noted.

Function	Description

OleIsDcMeta	Identifies a metafile device context.

OleLockServer	Keeps a server in memory for updating multiple objects.

OleQueryClientVersion	Retrieves the version number of the client DLL.

OleSetColorScheme	Recommends colors for documents and objects.

OleUnlockServer	Releases a server locked with OleLockServer.


OleIsDcMeta function

BOOL OleIsDcMeta(hdc)

HDC hdc;

The OleIsDcMeta function determines whether the specified device context is a metafile device context.

Parameter	Description

hdc	Identifies the device context to query.

If the device context is a metafile device context, the return value is a positive value; otherwise, it is NULL.


OleLockServer function

OLESTATUS OleLockServer(lpObject, lphServer)

LPOLEOBJECT lpObject;
LHSERVER FAR * lphServer;

The OleLockServer function is called by a client application to keep an open server application in memory.

Parameter	Description

lpObject	Points to an object the client DLL uses to identify the open server application to keep in memory.

lphServer	Points to a handle to the server application when the function returns.

Keeping the server application in memory allows the client DLL to use the server application to open objects quickly.

A client calls the OleLockServer function to speed the opening of objects when the same server is used for a number of different objects. Before the client terminates, it must call the OleUnlockServer function to release the server from memory.

When the server has been locked, this object can be deleted. When OleLockServer is called more than once for a given server, even by different client applications, the server's lock count is increased. Each call to the OleUnlockServer function decrements the lock count. The server remains locked until the lock count is zero. If the object identified by the lpObject parameter is deleted before calling the OleUnlockServer function, OleUnlockServer must still be called to decrement the lock count.

A server can terminate even though a client has called the OleLockServer function, if necessary.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_COMM

OLE_ERROR_LAUNCH

OLE_ERROR_OBJECT

OLE_ERROR_MEMORY

OLE_ERROR_STATIC

See Also

OleUnlockServer


OleQueryClientVersion function

DWORD OleQueryClientVersion(void)

The OleQueryClientVersion function retrieves the version number of the client DLL.

The return value is a double word in which the major version number is in the low byte of the low word and the minor version number is in the high byte of the low word. The high word is reserved.

See Also

OleQueryServerVersion


OleSetColorScheme function

OLESTATUS OleSetColorScheme(lpObject, lpPalette);

LPOLEOBJECT lpObject;
const LOGPALETTE FAR* lpPalette;

The OleSetColorScheme function specifies the palette a client application recommends be used when the server application edits the specified object. The server application can ignore the recommended palette.

Parameter	Description

lpObject	Points to an OLEOBJECT structure describing the object for which a palette is recommended.

lpPalette	Points to a LOGPALETTE structure specifying the recommended palette.

The OleSetColorScheme function returns OLE_ERROR_OBJECT when it is called for a linked object.

A client application uses the OleSetColorScheme function to change the color scheme. The client does not need to call OleSetColorScheme every time a server is opened.

The first palette entry in the LOGPALETTE structure specifies the foreground color recommended by the client application. The second palette entry specifies the background color. The first half of the remaining palette entries are fill colors, and the second half are colors for lines and text.

Client applications should specify an even number of palette entries. When there is an uneven number of entries, the server interprets the odd entry as a fill color; that is, if there were five entries, three would be interp reted as fill colors and two as line and text colors.

When server applications render metafiles, they should use the suggested palette.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_BUSY

OLE_ERROR_MEMORY

OLE_ERROR_OBJECT

OLE_ERROR_PALETTE

OLE_WAIT_FOR_RELEASE


OleUnlockServer function

OLESTATUS OleUnlockServer(hServer)

LHSERVER hServer;

The OleUnlockServer function unlocks a server that was locked by calling the OleLockServer function.

Parameter	Description

hServer	Identifies the server to release from memory. This handle was retrieved by a call to the OleLockServer function.

When the OleLockServer function is called more than once for a given server, the server's lock count is incremented. Each call to the OleUnlockServer function decrements the lock count. The server remains locked until the lock count is zero.

If the OleUnlockServer function returns OLE_WAIT_FOR_RELEASE, the application should call the OleQueryReleaseStatus function to find out whether the unlocking process has completed. In the call to OleQueryReleaseStatus, the application can cast the server handle to a long pointer to an OLE object (LPOLEOBJECT):

OleQueryReleaseStatus((LPOLEOBJECT) lhserver);

When OleQueryReleaseStatus no longer returns OLE_BUSY, the server has been unlocked.

The return value is OLE_OK if successful; otherwise, it could be one of the following:

OLE_ERROR_HANDLE

OLE_WAIT_FOR_RELEASE

See Also

OleLockServer, OleQueryReleaseStatus


Using the Registry

Server applications must register the services they provide in the registry. The registry has several purposes, but for OLE, it does the following two things:

It allows server applications to make information available to client applications about the type of objects they create.

It allows the OLE libraries to find the server application when the user double clicks on an object previously embedded or linked in a container document.

As an example, consider an OLE drawing server application. To make itself available to other client applications, it must register itself in the registry with a unique Class that indicates the type of objects it can process (for example, drawings). Whenever an object created by the drawing server application is embedded into or linked to a container document, this unique Class is associated with that object. The client application then uses the Class to query the registry to gather specific information about the server draw application.

For more information, see the following topics:

Modifying the Registry

Maintaining and Using the Registry


Modifying the Registry

Registering the server application should take place during product installation. Each time the server application starts up, it should also query the registry to ensure that its registration is still valid. If registration is ever lost, the server application must re-register itself.

Note:	There can be only one application at a time (on one workstation) registered as a server for a given Class.

To register a server application during product installation, the setup program must make registry-specific API function calls to perform registration.

Client applications can make registry-specific API function calls to get information about a particular object and its server application. For example, a client application that supports the Insert Object command can query the registry to obtain object-class data. It then lists the available descriptive class names of objects in a list box so that the user can make a selection regarding the type of object to insert.

Registering OLE Server Information

A server application registers itself in the registry by placing a key and value that shows which OLE protocols it supports. The entries in the registry are used whenever a client application or DLL needs information about a particular object and its server application.

Database Keys and Values

The registration database stores keys and values as null-terminated strings. The keys are structured in a hierarchical manner with the names of the components of the keys separated by backslash (

As shown in Figure 39, the text to the left of the equals sign (=) is the key and the text to the right is the data.

Figure 39. Registry key and data

Specific Registry Keys

Server applications are registered by including the following information as specific keys in the registry:

Key	Purpose

File Extension/Class	The Class and file types should be registered for every object class the server application supports. (This Class must be the same string that the server uses when it calls the OleRegisterServer function.)

Object Descriptive-Class-Name	The Descriptive-Class-Name data needs to be registered in human-readable form so that client applications can display the object type to the user.

Editing Protocol	The protocols supported by OLE 1.0 are StdFileEditing (current protocol for linked and embedded objects) and StdExecute. StdExecute is used only by applications that support the OleExecute function.

Name of Object Handler DLL	If a class has an object handler library, it should be also be registered using the keyword handler32.

Name of the Server Application	Information in the database also allows the OLE libraries to locate and launch the application when the user wants to edit one of its object from within a compound document.

Valid Verbs	An application should also register all the verbs its class or classes support. An application's verbs must be sequential; for example, if an object supports three verbs, the primary verb is 0 and the other verbs must be 1 and 2.

Note:	All OLE server applications must register at least one verb.


Maintaining and Using the Registry

A server application should register the key/value pairs shown in the following example when it is installed. This example shows the form of key/value pairs as they would be added to the registry using the registry-specific API function calls.

HKEY_CLASSES_ROOT\.ext = class

HKEY_CLASSES_ROOT\class = descriptive-class-name

HKEY_CLASSES_ROOT\class\protocol\StdFileEditing\server = path-and-filename

HKEY_CLASSES_ROOT\class\protocol\StdFileEditing\handler32 = dll-name

HKEY_CLASSES_ROOT\class\protocol\StdFileEditing\verb\0 = primary-verb

HKEY_CLASSES_ROOT\class\protocol\StdFileEditing\verb\1 = secondary-verb

Servers that support the OleExecute function should also add the following line to the database:

HKEY_CLASSES_ROOT\class\protocol\StdExecute\server = path-and-filename

A server application should register the entire path name for its executable file since registering only the name fails if the application is installed in a directory not set in the PATH environment variable.


Testing OLE Applications

This topic describes a series of tests that target the issues affecting OLE objects, documents, and applications.

After discussing the OLE testing issues, the information is organized by test function, with each major section describing tests for both OLE server and client test applications.

For more information, see the following topics:

OLE Testing Issues

Overview of OLE Test Cases

Object Creation Tests

Tests for Client Application Object Actions

Tests for Server Application Object Actions

Tests for File/Document and Object Interactions


OLE Testing Issues

OLE Testing Issues

The testing methodology for OLE applications differs from that of testing non-OLE applications. Non-OLE application testing primarily centers around the interaction between users and the application. However, an OLE application test must also consider the interaction between the test application and other OLE applications, and between the test application and the OLE libraries.

An OLE application tester must know whether the OLE application being tested is a server, a client, or both a client and a server. Typical servers might be PBRUSH.EXE and SOUNDREC.EXE. A typical client might be CARDFILE.EXE. A typical client-server might be Microsoft Word for Windows or Microsoft Excel.

If the application is an OLE server, you must know whether the server allows single or multiple instances of itself. OLE labels a server single-instance if only one instance of the application can be started by OLE. If an application is multi-instance, OLE will start a new instance of it each time the user chooses an object's verb.

You must also know whether the server has a single or multiple document interface. The Windows concept of SDI (single document interface) and MDI (multiple document interface) can apply to either client or server applications. Whether or not an application allows multiple documents to be open affects how it opens, closes, and saves files.

The type of application determines the use of callback functions (methods), which are exported with the application. These callbacks are invoked by the OLE DLLs whenever it is necessary to notify an application of status or to request information from it. You must be aware of all of the possible conditions under which an OLE DLL routine may use these callbacks.

Client Application Issues

The client application tester must understand how objects are created. Each object has presentation data associated with it. This presentation data controls the appearance of the server application's picture in the client application. You should be aware of the types of presentation data required by the application. The client application determines at the time the object was created, how it will draw the object--by using information from the server application-- or by letting the client DLL draw it. The object's location in the client document is also determined when the object is created.

Some objects have a presentation for screen display and a presentation for a specific printer device. If the client application supports printer device display, also known as WYSIWYG, it must supply the server application the appropriate printer information.

Once created, there are many actions that can be done with an object in a client application. These actions can occur asynchronously and you should know how the application handles asynchronous processing.

Editing actions may involve starting one or more additional applications, depending on the variety of objects contained within the document. Therefore, the client application needs to alert the user whenever an action may affect the state of the currently opened document. If there is an OLE error, the client application should display a message box describing the error and/or a way to recover.

The client application, in interacting with other applications, may need to open, close, read, and save files-- both with and without OLE objects. Many applications are able to read files created by other applications, however, not all applications can work properly with files containing OLE objects.

Server Application Issues

Server applications are responsible for naming objects, therefore you must be knowledgeable about the naming convention used. Verbs are important and you should know which verb or verbs are provided by the application and their order of importance. The registry contains an entry for each OLE-compliant server application with the class of each object and the supported verbs. A server application may support one or more classes.

There are two conditions that affect communication between server and client applications. A server can block all OLE messages from the client, in which case they will be queued and processed when the server is freed. The client is unaware that the server is blocked and it must wait for an operation to be started or completed. Servers typically alert client applications of busy conditions, thus freeing the client to either retry its communication or go on to another task.

Error reporting and recovery is also important to server applications.

Server applications may incorporate both DDE and O LE protocols. This requires that you understand the methods used to distinguish between OLE and DDE conversations and the techniques for handling OLE operations.


Overview of OLE Test Cases

The following sections describe how to generate test cases to test an OLE client or server application. The test cases are divided into five categories, the last two of which are optional:

Test Category	Description

Precondition	Conditions that must exist in order to run the tests.

Procedure	Step(s) that must be taken to perform the test.

Postcondition	Conditions that exist when the procedure has finished.

Similar	Cases Variations on the Postcondition test.

Special	Cases Test cases that have been previously used to find easy-to-miss problems.


Object Creation Tests

Object Creation Tests

There are five types of OLE objects:

Embedded

Linked

Static

Packaged

Handler

These object types can be created in client and server applications using the clipboard, the Insert Object command, and the drag and drop feature of Windows.

There are tests for the clipboard and the Insert Object command. In the case of drag and drop, objects can be created with client applications and with server applications that can save data to a file; this application must have a standard extension defined in the registry. Documents can be dragged into the client application to create a packaged object.

The server application can put different formats on the clipboard. These formats determine what kinds of objects can be inserted into the client application document. This method can be used to create all five types of objects.

The following table lists the client application commands that apply when creating an OLE object from the clipboard. Keep in mind that Native data without OwnerLink format is not useful. Also, the presentation data must be on the clipboard before the OLE DLLs can create an object with the desired presentation.

Command	OLE Format Present On Clipboard	Type of Object On Clipboard Created

Paste	none	Static

Paste	Native + OwnerLink	Embedded

Paste	OwnerLink	Link

Paste	ObjectLink	Static

Paste Link	none	Invalid

Paste Link	Native + OwnerLink	Link

Paste Link	OwnerLink	Link

Paste Link	ObjectLink	Link

Clipboard Creation - Client Application Tests

From the user's perspective, the Edit Copy command should put an object on the clipboard with the object type preserve d. For example, if an embedded object is copied to the clipboard, then a paste operation in the client application can only create an embedded object. Similarly, if a linked object is copied to the clipboard, the client application would paste a linked object.

To paste an object, the client application calls OleCreateFromClip to create the object. The client application should then call OleQueryType to find out the object's type. The Paste command is enabled only if there is data on the clipboard.

The Paste Link command creates either a new linked, packaged, or handled object from clipboard data. The object type is dependent upon the information available on the clipboard.

If the Paste Link command is active (as opposed to being dimmed), the application is aware that link information is available on the clipboard. The client application will call OleCreateLinkFromClip to create the object. It should also call OleQueryType to get the object type. The object type will be embedded for packaged objects.

Copying and Pasting Static Data into a Client Application Document

Precondition

The Native, Ownerlink, and ObjectLink OLE data formats are not on the clipboard.

The presentation data on the clipboard is compatible with the client application.

Procedure

In the client application, choose Edit Paste to paste the data into the client application document.

Postcondition

Object data should appear in the client application document.

The created object will be static.

Copying and Paste Linking a Server Object into a Client Application Document

Precondition

ObjectLink format is present on the clipboard from any server application.

The data on the clipboard has been saved in a file.

The presentation data is compatible with the client application.

Procedure

In the client application, choose Edit Paste Link to paste a link to the object from the clipboard into the client application document.

Postcondition

The object should appear in the client application document. Its presentation data will depend on the characteristics of the client application.

The object should establish an automatic link if the server application document is open.

The presentation size of the object, as it appears in the client application document, is determined by the server application.

Similar Cases

Try to create a link when the server application is not running, or when it is running but the linked document is not open.

The server application is running and has an open linked document, but it is blocked. The object is not completely created before the server application is unblocked. Try manipulating the object. The application may prevent operations on the object. Verify that this condition is handled properly.

The server application is running and has an open linked document, but it is busy.  The client application may refuse to create the object or it may display a busy dialog box.

Create a handler link and compare the results.

Use any server to put the filename format on the clipboard and create a packaged object using Paste Link.

Copying and Paste Linking Unsuccessful

Precondition

The client application supports compound documents.

ObjectLink data is not on the clipboard.

Postcondition

The client application's Edit Paste Link command is disabled.

Otherwise, if ObjectLink is available or OwnerLink is available without Native data, the link should be created.

Clipboard Creation - Server Application Tests

From the user's perspective, an area in the server application is selected prior to the user choosing the Edit Copy command to transfer the selected data to the clipboard. If the object belongs to a server application document, the server application should put ObjectLink information on the clipboard.

From the developer's perspective, the server application has to create the proper picture data and OLE data formats in order to create OLE objects. If the copied object does not have a document (file) associated with it, the server application should copy Picture, Native, and OwnerLink information. The client application will create an embedded object. However, if the server application object (or item) has an associated document, the server application should also copy ObjectLink information so that a client application can create a link to the object.

Copying Embedded Object Information to the Clipboard from the Server

Precondition

The server application supports embedding of its objects using the clipboard.

Procedure

1	Select an object to copy to the clipboard.

2	Use Edit Copy to copy the object to the clipboard.

3. Open the clipboard to examine its contents.

Postcondition

Under the Display menu in the clipboard, Native and OwnerLink formats should appear.

ObjectLink format should not appear on the clipboard.

Copying Link Information to the Clipboard from a Server Application

Precondition

The server application supports linking of its saved objects.

Procedure

1	Start the server application.

2	Create a file or open an existing file containing an object.

3	Select an object in the file to copy to the clipboard.

4	Choose Edit Copy to copy the object to the clipboard.

5	Open the clipboard to examine its contents.

Postcondition

Under the Display menu in the clipboard, Native, OwnerLink, and ObjectLink formats should appear, but be disabled.

Copying an Embedded Object to the Clipboard from a Client Application

Precondition

The client application document contains an OLE object.

Procedure

1	Use Edit Copy to copy an object to the clipboard. Do not copy a compound object (that is, an object that contains an object).

2	Open the clipboard and examine its contents. Native and OwnerLink formats should appear (disabled) under the clipboard's display menu if the object copied was the embedded object. If the link is copied to the clipboard, only the OwnerLink format should appear.

3	Use Edit Paste to paste the copied link into any client application.

Postcondition

The embedded object should appear in the client application document.

The object should behave as if it was created in the appropriate server application.

Clipboard Creation - Client-Server Application Tests

If the application is a capable of being both a client and a server application, the object may include other server application objects. The client-server application will have to copy the presentation data (and other data formats for the selected object) to the clipboard. If the object is then copied to another client application, the presentation data should include the server application object. When a user tries to edit the object, the client-server application should recreate it so that the original server application object can be edited by the user.

Copying and Pasting an Object Containing an Embedded Object from a Client-Server

Precondition

The client-server application contains an OLE object from another server application.

Procedure

1	In the client application, select the OLE object and copy it to the clipboard using Edit Copy.

2	Use Edit Paste to paste the object into any client application.

3	Select the object for editing by double clicking on it.

4	this point the client server application should be started and the original object should be properly embedded and available for editing.

5	Start the server application for the embedded object in the client server application.

6	Make changes to the object in the server application, update the client application, and close the server application.

7	Close the client server application document.

Postcondition

The client-server application should update the presentation in the client application with the latest changes from both the server and client-server application.

Special Case

Paste the object (see the preceding procedure) back into the client-server application; it should behave as before it was edited.

Copying and Paste Linking an Object Containing a Linked Object from a Client-Server

Precondition

The client-server application contains a link from another server application.

Procedure

1	Select an area in the client server application document that includes a linked object, and copy it to the clipboard using Edit Copy.

2	Choose Edit Paste Link to paste the object into any client application.

3	Attempt to edit the object.

The client server application should open the appropriate document for editing the linked object.

4	From the client server application, start the server application for a linked object.

This will establish an automatic link between the client application, the client server application, and the server application.

5	Make changes to the object in the server application.

Postcondition

The client-server application should update the presentation data with the latest changes from the server application and the c lient-server application. These changes should appear in the client-server application, and in the client application.

Special Cases

Paste Link the object to another document (other than the document from where it was copied) in the client server application and check the behavior.

Paste Link the object to the same document in the client server application. Many applications will disallow this operation because it may cause an infinite loop.

Clipboard Creation - File Manager Test

The user can also use the File Manager's File Copy command to copy a special OLE format FileName to the clipboard. The FileName format can be used to create a package in the client application.

Copying a File to the Clipboard from the File Manager

Precondition

The test application creates a file. The application can be either a client or server application.

Procedure

1	Open the File Manager, select the created file name, and choose File Copy to copy the file to the clipboard.

2	Open the clipboard and examine its contents.

The File Manager should have copied the FileName format to the clipboard.

3	Use Edit Paste to paste the copied file into a client application.

Insert Object Command - Client Application Tests

From the user's perspective, the server application should be selected and started with a new document. The user is able to edit and close the document. At closure, the server application prompts the user to update the object. If the user chooses to update, the updated object is inserted in the client application. If the user decides not to update the object, the client application should resume as though there were no new object.

From the developer's perspective, the client application should call registry-specific API functions to query the registry for what types of objects are available on the workstation. The application gets the human-readable string (descriptive class name) from the registry for each registered object type (class) and displays a list box containing the objects. The client application examines the user selection and calls OleCreate with that class to launch the server application.

Testing the Insert Object Command

Precondition

The client application has implemented an Insert Object command.

Procedure

1	Choose the Insert Object command.

An Insert Object modal dialog box comes up containing a list box that allows the selection of the type of object to insert.

2	Select a type of object to insert.

The appropriate server application is started and loaded with a blank object.

3	In the server application, make changes to a blank object.

4	Choose File Update in the server application.

Postcondition

An object is embedded into the client application document.

The object's presentation depends on characteristics of the client application. In most cases, it will be Picture format. A client application can select different formats.

The size of the object depends on the size of the presentation created by the server application.

Similar Cases

Try the test when the server application is already running. Depending on whether the server application is multi instance or single-instance, a new instance may or may not be started.

If the server is single instance application that supports blocking, block (or make busy) the application and observe how the client application behaves when trying to manipulate the object or document.

Inserting an Embedded Object in a Client Application from a File

Precondition

A client application allows creating an OLE object from the Insert Object command.

A server application has file extensions defined in the registry.

Procedure

1	Use the Insert Object command to display the list box showing the list of server application editable files or the edit box to insert the file name.

2	appropriate server application should be invoked and the server application should open the file for editing.

3	Edit the file in the server application and then close it.

Results

The edited object with all the changes should be inserted into the client application document.

Activating the object should start the server application with the object present. Note that this object now has no link to its parent file; changing the file does not change the embedded object.

Similar Test case

Try different files in different directories. Try cases where server application files and the server application are in different directories.

Special Case

Try this test with a server application that allows blocking. Block the application and check the status of an uncreated object.

Insert Object Command - Server Application Tests

From the user's perspective, if the server application is a single-instance application and an instance is already running, the server application will become the top window and open a new document for editing. If the server is a multi-instance application, a new instance will be started and the server application will rise to the top with the new document. At closing, the user should be prompted to update the client application. If the user chooses to update, a new object should be created in the client application using the picture data from the server application .

From the developer's perspective, the server application method, SrvrCreate, should be called. The server application should start a new document and allow the user to edit it. At closing, the server application should prompt the user to update the object.

Inserting an Embedded Object in a Client Application

Precondition

The server application has registered its object type.

Procedure

1	Use the Insert Object command in a client application to display a list box showing the server applications installed in the system. Choose a server application to test.

The server application should be started and it should open an empty document for editing.

2	Edit the document in the server application and then quit the server application.

Post Conditions

The edited object with all of the changes should be inserted into the client application document.

Activating the object should invoke the server application with the object present.

Similar Cases

The client application calls OleCreate to create an embedded object in this test.

If the presentation format is not specified as a parameter, the client DLL assumes that Picture is the presentation format. However, if a format is specified, the client DLL determines if the server application supports it.

Different formats should be passed to the client to determine if the server supports all formats. Also, check if the server application is able to create the object.

If the client application has started the server application using OleCreateInvisible rather than OleCreate, the application is hidden. In this test, the client application will send information to the server application, causing the server to display the picture for editing.

Special Case

Choose the Insert Object command with an older client application such as Powerpoint Version 2.x. There is a special test for server applications that have a single .E XE file but two or more classes. If such servers use the OLE DLL, they will not be started.

Inserting an Embedded Object in a Client Application from a File

Precondition

The server application supports files with file extensions defined in the registry. The client application has an Insert Object option.

Procedure

1	Use the Insert Object command to display a list box showing the server application editable files. Choose a file that corresponds to the server application.

The server application should be started and the selected file should be opened for editing.

2	Edit the file and then quit the server application.

Results

The edited object with all the changes should be inserted into the client application document.

Activating the object should start the server application with the object present. Note that this object has no link to its parent file; changing the file does not change the embedded object.

Similar Test cases

Try different files in different directories. Try cases where the server application is in one directory and its files are in another directories.

Also try cases where there are several different objects in a server application document.


Tests for Client Application Object Actions

There are four types of actions that can be performed on client application objects:

A user can double click (activa te) an object, causing the server application to be started.

An object can be deleted from the document or cut to the clipboard.

Edit operations can be canceled through the use of the Undo command.

The user can change the presentation size of the object.

Starting a Server - Client Application Tests

From the user's perspective, it should be possible to access a verb by selecting the object and choosing from the Edit menu. Multiple verbs supported by the server application should be listed as submenu items of the Edit Object menu item.

Invoking Verbs for an OLE Object

Precondition

The client application contains an embedded object.

Procedure

1	Select the object in the client application and choose Edit <Object Name>.

2. Choose different verbs supported by the server application.

Postcondition

If the server application is an MDI application, the client DLL s hould start it and pass the data for the embedded object. The server application will behave depending on the particular verb invoked.

If the editor for the object is already open, double clicking the object in the client application should invoke the verb again and not start another instance of the server application. (Step 2 in the preceding procedure should not start another instance).

Similar Test Cases

Try all the verbs and verify that the behavior matches the behavior of the server application.

Choosing either Play or Edit will cause the server application to appear on the top of the window stack.

If the client application allows the selection of multiple objects, try to invoke more than one embedded object in this manner from the client application.

If the test application sends Printer Target Device, check the results.

Invoking Edit to Open a Linked Object in the Server Application

Precondition

A client application with an open document containing more than one linked object.

Procedure

1	Invoke edit on the linked object.

2. Invoke edit on the linked object whose editor is already open.

Postcondition

If the server application is an SDI (Single Document Interface) application, it should start the server application with the document name. The window title in the server application should display the document name.

Any changes made to the document in the server application should be immediately visible in the client application, unless the client application created the linked object with OnCall Update. In this case, the change is not immediately visible.

Similar Test Cases

If the test application allows the selection of multiple objects, try to invoke more than one linked object this way from the client application.

Use a server application that is an SDI application and block or make busy the server application. Try to invoke edit in the client application.

Special Cases

After creating a link to a document, rename or delete the document and try to edit the object. The client application should indicate a failure and allow for a change in the link.

If the client application has a link to the document on the network, the document will be open ed and the link will be established. If there is no network connection, the OLE DLL will attempt to establish a connection to the network server and, if successful, open the document. A dialog box listing available drives may facilitate the selection of the appropriate drive.

Starting a Server - Server Application Tests

From the user's perspective, if the server application document is already open, the Edit verb will bring it to the top of the window stack. When the server application is a multi-in stance application, a new instance will be started and the appropriate document opened. If the server is a single-instance application and is running, a new document will be opened in the current instance.

The server application interprets each verb. Every server application should support the Edit verb. Invoking this verb from a client application should cause either the server application to be started if it was not already running. If the server is running, it should be brought to the top of the window stack before opening the appropriate document.

Invoking Edit to Open an Embedded Object in the Server Application

Precondition

The client application contains an embedded object that belongs to the server application.

Procedure

1	Invoke the Edit verb on the object in the client application.

2. Invoke the Edit verb again on the object in the client application.

Postcondition

If the server application is multi instance, it should start the server application with the embedded object. The window title in the server application should display the name of the object provided by client application.

If the editor for the object is already open, double clicking on the object in the client application should bring its editor to top. (The preceding Step 2 should not start another instance of the server application.)

o   If the server application is MDI application with several open documents, invoking Edit in the client application should bring the corresponding document to top.

The server application should not have the File Save option available, but instead should provide File Update, Choosing File Update should update the object in the client application. In the File menu, Save As should be changed to Save A Copy As... and Exit should be changed to Exit and Update.

Similar Test Cases

If your application accepts ColorPalette, use it to make sure that the server application gives a proper picture with different palettes (sometimes color combinations can make a picture invisible).

If your server application uses Printer Target Device, check that it gives proper picture information for different targets, and the screen picture if no target device is specified.

Invoking Edit to Open a Linked Object in the Server Application

Precondition

A client application is running and has an open document with more than one linked object belonging to your server application.

Procedure

1	Invoke Edit on the linked object.

2	Invoke Edit again on the linked object whose editor is already open.

Postcondition

If the server application is multi instance, it should start the server application with the document name. The window title in the server application should display the document name. If the server application is single-instance, a new document will b e opened and no new instance will be started.

Any changes made to the document in the server application should be immediately visible in the client application, except when the client application created the linked object with OnCall Update. In this case, the change is not immediately visible.

Similar Test Case

If the server application is an SDI application, block or make busy the server application and try to invoke edit in the client application.

Special Cases

If the server application runs macros or displays a dialog box at start up time, check to see if the link is established. This check is required because if the server application is started from the client application, it should establish the link with the client application before yielding control.

Use an older client application such as Microsoft Excel 3.0x. It starts using the /Embedding command line option instead of the -Embedding option.

Deleting and Cutting Objects to the Clipboard from the Client Application

Precondition

A client application document containing embedded or linked objects.

Procedure

1	Select an object to copy to the clipboard.

2	Choose Edit Cut to delete the object from the client application document and copy it to the clipboard.

3	Open the clipboard to examine its contents.

Postcondition

Under the Display menu in the clipboard, Native and OwnerLink formats should appear if the object is embedded; ObjectLink format if the object is linked.

The copied object should be deleted from the client application document instance.

Any conversation with the server application should be broken. (The effect will be noticeable if the server application was open for editing an embedded object.)

Special Case

Try this test when the conversation is open and the server application is blocked.

Cut the object in the client application; since the object is not released, check the behavior of the client application. If the object is still visible, try to cut the object again.

Try to close the document.

Save the document and check the contents of the clipboard. In any of these tests, the client application should indicate an error.

Deleting and Cutting Objects to the Clipboard from the Server Application

From the developer's p erspective, an Edit Cut command from inside a server application should destroy the object. The server application should put Native and OwnerLink information on the clipboard. ObjectLink information should not be on the clipboard.

Precondition

The server application supports embedding of its objects.

Procedure

1	Create one or more objects in the server application.

2	Use the Edit Cut command to delete an object from the server application document and copy it to the clipboard.

3	Open the clipboard and examine its contents.

Postcondition

Under the Display menu in the clipboard, Native and OwnerLink formats should appear disabled.

ObjectLink format should not appear under the Display menu of the clipboard. Cutting the object would destroy it and make it unavailable for linking.

If the server application object is deleted while open for editing in the client application, the conversation between the applications should be broken.

Testing the Undo Command with Embedded Objects from a Client Application

The Undo command is used to cancel an action in client applications. From the user's perspective, different applications will implement the Undo differently. Some client applications will allow the user to revert back to the changes made with the latest server application update. Other applications will allow the user to undo the deleted object.

From the developer's perspective, if the client application allows the rolling back of the latest changes, it will have to clone the object before starting the server application for editing. When the user selects Undo, the client application should destroy the original object and show the cloned object instead.

Precondition

An embedded object has been opened for editing.

Changes to the object have been made in the object's server application.

Procedure

1	Close the server application.

2	Return to the client application instance.

The object in the client application should have been updated to reflect the changes made in the editing session.

The Edit Undo command should be enabled in the client application.

3	Choose the Edit Undo command.

Postcondition

The embedded object should rollback to the state that existed before it was opened for editing.

Make sure the object properties have not changed. Check the object's properties; try to save the object, start the server application, and so on.

Special Cases

There is no recommended user interface for the Undo command, but if your application allows you to recreate the OLE object, check that the object name is preserved.

If the client application has an open link and the linked object is cut and then recreated using Undo, check that the client application automatically opens the link.


Tests for Server Application Object Actions

There are just two types of actions that can be performed on server application objects: edit and update. The object can be edited causing the server and client versions of the object to be out of synchronization. If this condition is undesirable, the update operation will integrate the changes made in the server object into the client object.

Editing an Object - Server Application Tests

Editing Embedded Objects in a Server Application Started by a Client Application

Precondition

A client application document contains an embedded object. This test is used to verify that the server application sends the latest presentation data and Native data. This test is described more fully in the section "File Update" in this topic.

Procedure

1	Invoke edit in the client application to start the server application.

2	Change the object data in the server application.

3	Choose File Update.

The client application should have the latest presentation data from the server application.

4	Close the server application document without sending a new update.

5	Start the server application again from the client application.

Postcondition

A new server application document should be open for editing and it should have the changes that were made in the preceding procedure.

Editing Linked Object Data when the Link is Open

Precondition

The client application document containing a linked object is open and a server application is opened with the source document. The link is open to the object and it is an automatic link.

Procedure

1	Change the object in the server application.

The client application should get the latest presentation data from the server application immediately.

2	Save and then close the document in the server application.

3	Start the server application again from the client application.

Postcondition

A new server application document should be open for editing which should have the changes made in Step 1.

Similar Cases

Try this test by starting the server application, opening the document with File Open, and establishing a link (unlike establishing it by starting the document from the client application).

Setting New Color Schemes and Updating Embedded Objects from Client Application

This tests how the server application handles OleSetColorScheme with an embedded object. The test applies to a server application that has implemented the SetColorScheme callback function. For other server applications, check that they return an error from this function.

Use a client application that allows sending a new color scheme.

Precondition

Client application contains an embedded object from the server application.

The document containing the embedded object is open for editing.

Procedure

1	Start the client and use the right mouse button to bring up the popup menu and choose Set Colors.

2. Choose a color scheme in the displayed dialog box. The client will create and fill in the appropriate entries in the LogPalette structure and then call OleSetColorScheme to send the LogPalette structure to the server application.

Postcondition

If the server application handles OleSetColorScheme , the picture may change depending on the color combination chosen in the preceding procedure.

Update the picture from server to client to determine if the server sends a new picture to the client.

Similar Test Cases

Try this case when the embedded object is not open. Choose a color scheme and open the server object.

Updating an Object - Server Application Tests

Changing and Updating an Embedded Object from the Client While the Server Is Running

To begin the test, paste an embedded object in the client application and change the size of the object. When the object is updated, the client will send the native data and new bounds information to the server application. If the server application accepts the bounds it will pass the new picture data (with the boundary information) to the client.#

Precondition

The client application document contains an embedded object from an MDI server application.

The server application is running.

The embedded object is not open for editing.

Procedure

1	In the client, change the size of the object.

2	In the client, choose the Update Now command, if available.

Postcondition

If the server application handles SetBounds , it will return new picture data to the client.

There will not be any new document open. A new document might be opened for update in the server application momentarily, but it will be closed automatically by the client application.

All of the earlier documents opened in the server application are still open.

Similar Test Cases

Try this test with a non MDI server application.

Try it for more than one client application object belonging to the same server application.

Special Cases

If the server application supports multiple classes, try this test for more than one embedded object, each having a different class.

Try to update when the server application is blocked or busy. Check the object behavior as in the earlier cases.

Updating an Out-of-Date Linked Object from a Client Application

Precondition

The client application document contains a linked object.

The server application is running and the document associated with the linked object is open.

The object in the client application is not up to date with the object in the server application.

The latter two conditions indicate that the link is not open between the client application and the server application.

Procedure

In the client, choose the Update Now command if available.

Postcondition

The server application will return new picture data to the client.

All the server application documents are still open.

The connection between the linked object and the server application document is not established. Check it by changing data in the server application.

Similar Test Cases

Try this test with a non MDI server application.

Try it for more than one client application object belonging to the same document.

Try to update when the document is not open and the client application object is older that the server application object. Make sure that no new documents are open.

Special Cases

If the server application supports multiple classes , try this test for more than one linked object and on objects belonging to different classes.

Try this test when the server application is blocked or busy.

Updating an Object - Client-Server Application Test

Updating a Linked Object Containing a Linked Object in a Client Application

This test applies to a client-server application, such as Microsoft Excel or Word for Windows.

A linked object is created in a client-server application and inserted into a client a pplication. The linked object contains not only client-server data, but also an embedded object from a server application.

When File Update is chosen in the client application that contains the linked object created by the client-server and server applications, the client-server application will not only provide new data for its own object, but will also provide new data from the server application that created the embedded object. All new data is sent by the client-server application to the client application.#

Preconditions

A client server application document contains a linked object.

The object in the client server application is different from the object in the server application.

Procedure

1	Select an area in the client server application document that contains the linked object and copy it to the clipboard.

2	Open a client application and Paste Link the linked object.

3	Close the client server application or the document from which the link was obtained.

The client application contains a linked object that has a link to another server application.

4	Update the linked object in the client application.

Postcondition

The client server application will return the latest picture from the server application.

All the client server application documents are still open.

Similar Test Cases

Try this test with an embedded client server application object that includes a link from another server application.

Try this test for more than one client server application object belonging to the same or different document.

Special Cases

It is possible to create a circular linked list this way with a client server application. Check whether your application can detect the update operation with a circular linked object.

If the client server application supports multiple classes, try this test for more the one linked object which belongs to different classes.

Try this test when the client server application is blocked or busy.

Try this test when the server application is blocked or busy.


Tests for File/Document and Object Interactions

The tests in this section are targeted towards actions involving documents containing multiple objects and files. The issue of whether or not the applications are MDI or SDI applications is an important factor in many of the tests.

The areas covered include closing, creating, and opening documents, saving, renaming, and printing a file, starting and quitting an application, and, editing a linked object's properties.

Closing a Document - Client Application Tests

From the user's perspective, the client application must terminate all active conversations related to the objects in the document between client and server applications. The client application should also prompt the user to update any changes to the object when saving the document.

From the developer's perspective, the client application should check for any active conversations for the objects in the document to be closed. The application should prompt the user to update the objects, using data provided by the server application(s ). If an update is required, the client application should call OleUpdate to get the data from the servers and call OleRelease to release all the objects. This will close all of the active conversations.

The client application should also call OleRevokeClientDoc to revoke the document being closed.

Closing a Client Application Document after Starting an Edit Session in the Server Application

Precondition

The client application and multiple server applications contain embedded objects. The server applications are started from the client application by invoking Edit on the associated embedded objects.

Procedure

1	Change an object in one of the server applications.

2	Choose File Close in the client application to close the document.

Postcondition

The client application should prompt to update and save the latest copies of objects. If the document has not been named, the client application will prompt for a valid name.

All of the server application's documents that were invoked by the client application should be closed.

Any server application documents that was opened by a user should not be closed.

Similar Test Case

Try this test with different types of embedded objects.

Closing a Client Application Document Containing Linked Objects

Precondition

A client application is open with linked objects. There is at least one linked server application document with an open link and one linked object that does not have an open link to its document.

Procedure

1	For the object that does not have an open link, open its container document with the server application and modify it.

Save the document. The object in the client application should remain unmodified.

2	Choose File Close to close the document.

Postcondition

The linked objects should not be closed.

The client application should prompt the user to update and save the latest copies of the objects. If the user chooses to update the objects, the client application should update the objects and save them to document.

Similar Test Cases

Try this test and establish the link conversation by double clicking the object and choosing Edit Paste Link while the server application is running.

o   Try closing the client application document when it has a connection to the server application and the server application is blocked or busy.

Closing a Document - Server Application Tests

From the user's perspective, if the server opened the document to be closed in order to edit an object embedded in a client application, the server application should prompt to Update the client application object with the new data (if the object data has changed). If an update is requested, the server application should send the new object data to the client application.

Closing an Embedded Object from the Client Application

Precondition

The client contains an embedded object from an MDI server application.

The embedded object is open for editing in the server application.

Procedure

In the client, choose Close.

Postcondition

The embedded object (document) in the server application will close.

The server application does not display a message box prompting the user to update changes before closing; therefore, all the changes made in server application document are lost.

If there is no other document open in the server application and the server application was started from a client application, the server application will close.

Similar Test Cases

Try this test with a non MDI server application.

Try this test for a linked object, in which case the server application should not close; however, the link should be broken.

Closing a Server Application Document Containing an Embedded Object

Precondition

The server application is running with an embedded object (document).

Procedure

1	Edit the object in the server application document.

2	Choose File Close in the server application. Respond with Yes when prompted whether to update the object.

Postcondition

The object in the client application should be updated to show the changes.

Similar Test Cases

Try the above procedure with a linked document. The server application should not cause any changes to the object in the client application.

Repeat the preceding procedure, but select No when prompted to update the object. That is, the client application should not be updated.

Repeat the preceding procedure, but select Cancel when asked whether to update the object. The conversation between the client application and the server application should not be broken.

Start the server application by choosing Insert Object and repeat the preceding procedure.

Start the server application by choosing Insert Template, if available, and repeat the preceding procedure.

Closing a Single-Instance MDI Server Application Document

Precondition

A server application has multiple documents open. At least one document has an open embedded object.

Procedure

1	Close the document that has the open embedded object. Select Yes when prompted for a decision whether to update.

2	Close the document that does not have open objects.

Postcondition

The client application containing a document with an open object should prompt the user to update the object when the document is closed.

Closing the document without open objects should not break links to the other open objects.

Similar Test Cases

Try this test with a server application where some of the documents were opened by invoking Edit from the client application and where others were opened directly by choosing File Open in the server application.

Try different cases where the server application is started from the client application and when it is started from the Program Manager.

Repeat the preceding procedure, but select No at Step 1. The client application document should not be updated.

Repeat the preceding procedure, but select Cancel at Step 1. The conversation should not be broken.

Make sure that Closed (not Save) notification is sent to the client application when the document is closed.

Creating a New Document -Client Application Test

Creating a New Document from a SDI Client Containing a Changed Embedded Object

Precondition

The client application document contains an embedded object from a server application.

Procedure

1	In the client application, open the embedded object for editing.

2	In the client application, choose File New to open a new document.

Postcondition

The client application should prompt the user to update the open objects. Choosing Yes should cause all of the objects to be updated and saved in the document opened in Step 2.

All of the embedded objects in the client document open for editing should close.

Check if the client application calls OleRevokeClientDoc with the old document name and calls OleRegisterClientDoc with the new name.

Similar Test Cases

Repeat the preceding steps, but Cancel the Update operation. None of the other listed Postconditions should occur.

Again, try File New when one or more of the server application objects are opened from the client application and/or are blocked or busy. The application should not close the document until the operation is completed. With the operation incomplete and in an indeterminate state, try creating new objects and/or manipulating other objects in the document.

Creating a New Document - Server Application Tests

From the user's perspective, if an SDI server application document is opened by a client application and the object data has been changed, the server application will prompt the user to update the changes when the File New command is chosen.

From the developer's perspective, a SDI server application should close the earlier document and register the new server application document using the functions in SHELL.DLL.

Creating a New Document from a SDI Server Application Containing an Embedded Object

Precondition

A client application document contains an embedded object from a SDI server application.

Procedure

1	In the client application, open the embedded object for editing.

2	In the server application, modify the contents of the object and choose File New to open a new document.

The server application should ask for a decision on updating the client application object. If an update is desired, the server application should update the client application object.

3	In the client application, edit the object again.

Postcondition

A new instance of the server application should be launched to edit the object. The original instance of the server application should not be activated.

Similar Test Cases

Repeat the preceding procedure, but select No in Step 3. The object in the client application should not be updated.

Repeat the preceding procedure. Use File New and select Cancel at Step 3. The conversation between the client application and the server application should not be broken.

Repeat the preceding procedure, but choose Insert New at Step 1.

Repeat the preceding procedure, but choose Insert Template at Step 1.

If the server application is an MDI application, make sure that opening a new document does not break already established links with other open documents.

Creating a New Document in a SDI Server Containing a Document with a Linked Object

Precondition

A client application containing a linked object.

Procedure

1	In the client application, open the link for editing.

2	In the server application, choose File New to open a new document.

If the server application document was changed, the server application should ask whether the document should be saved. Save the document to continue the File New operation.

The original conversation should be broken

3	In the client application, open the link again.

Postcondition

A new instance of the server application should be launched to edit the link.

Similar Test Cases

Repeat the preceding procedure, but choose Cancel in the File New operation in Step 2. The conversation between the client application and server application should not be broken.

If the server application is an MDI application, make sure that opening a new document does not break established links with other open documents.

Quitting an Application - Client Application Test

Quitting a Client Application Containing Changed Objects

Precondition

An open client application and document contains several embedded objects opened for editing.

Procedure

1	Choose File Exit in the client application.

2	If a document has changed, the client application should prompt to save the doc ument. If a save is desirable, the client application should ask (for each open embedded object) if the user wants to get an updated object from the server application.

Post Conditions

The server application should quit.

o   All of the objects in the client application document should be updated if the user selected to save the changes in Step 2.

Similar Test Cases

Repeat the preceding procedure, but choose not to save one or more objects. Those objects should not be updated.

Repeat the preceding procedure and select Cancel in Step 2. The conversation between the client application and the server application should not be terminated. Re opening the embedded object in the client application should cause the server application document to be re-opened.

Repeat the preceding procedure, but with an open linked object. The conversation will be terminated and an Update Yes/No? message box will be displayed.

Special Cases

If some objects are blocked in the server application, the File Exit command in the client application will not be completed until all the objects are released. Check the behavior of the client application when the server application is blocked.

Quitting an Application - Server Application Test

From the user's perspective, if the server application document is opened by a client application and object (document) data ha s changed, the server application will prompt the user to update the changes when the File Exit command is chosen.

From the developer's perspective, the application should close and revoke all of the documents, revoke the server application, wait for the server callback to be invoked and then quit the application.

Quitting a Server Application Containing Embedded Objects

Precondition

An open server application contains several embedded objects (documents) opened for editing from the client application.

Procedure

1	In the server application, change the embedded documents.

2	In the server application, choose File Exit.

The server application should ask whether or not to update the embedded object for each of its changed embedded documents.

3	Respond with Yes to the update prompts.

Post Conditions

The server application should quit.

All of the client application objects should be updated.

Similar Test Cases

Repeat the preceding procedure, but select No in Step 3 for one or more of the documents. Those documents should not be updated.

Repeat the preceding procedure and select Cancel at Step 3. The conversation between the client application and the server application should not be broken. Opening the embedded object in the client application should re activate the server application document. In most applications, selecting Cancel would bring the server application to its original state with all of the documents and conversations intact.

If the server application has other documents which were opened using File New or File Open, the server application should prompt to save the documents.

Repeat the preceding procedure, but with documents opened using the Insert Object command.

Repeat the preceding procedure, but choose the Insert Template command, if available, to create a new document.

Special Cases

Some older client applications, such as Microsoft Excel 3.0x and PowerPoint 2.0x, can only be updated by the server application sending an OLE_CLOSED notification. To make sure that the server application is doing this update properly, repeat the preceding procedure using PowerPoint 2.0x or Microsoft Excel 3.0x as the client application.

Opening a Document - Client Application Test

Opening an Existing Document in a SDI Client Application

Precondition

A SDI client application has an open document.

Procedure

1	In the client application, choose File Open to select a document. The client application will try to close the currently opened document. Follow the cases detailed in the Create a Document section.

2	In the open document, select each object and check the Edit menu for a submenu list of the verbs allowed for the object.

3	Invoke each verb on the list.

Postcondition

Check that all of the object properties are preserved; check the size of presentation.

Test that all of the verbs act as expected for the object.

Similar Test Cases

Repeat the preceding procedure for a document that has objects created from different server applications. Verify that double-clicking starts the appropriate editor.

Opening an Existing Document Containing Embedded and Linked Objects from the Same Server

Precondition

The client application has a document with embedded and linked objects from one server application.

Procedure

1	In the client application, choose File Open and open the document.

2	For each linked object, select the object and choose the Edit Links command. The Edit Links dialog box should indicate the appropriate link information.

3	Double click a linked object. This should start the server application with the object's source document. If more than one linked object has a link to the same server application document, no more than one instance of the server application should be opened.

Postcondition

Double-clicking on each embedded object may invoke a separate editor (if Edit is the default verb of the object). Double-clicking on a linked object establishes a link to its document, but not a link to another object.

Similar Test Cases

Repeat the preceding procedure when objects are linked to different documents of the same server application.

Open a client application document that has links to an object in a server application document. If the server application document is open, the link is established. If the object in the server application differs from the client object, the client application will display the latest object (provided by the serve r).

If the server application document is open and linked, but is blocked, the object will not be fully created until it is unblocked. If a document is opened with one or more blocked links, check how the client application responds to File New, File Close, File Open (another file or the same file).

Opening an Existing Document Containing Embedded and Linked Objects from Multiple Documents in Different Server Applications

Precondition

A document containing a variety of embedded and linked objects from a variety of server application documents. This tests how the client application handles saving, reading, and other operations for multiple objects of different kinds.

Procedure

1	In the client application select the File Open command and open the document.

2	Check the Links dialog box. It should indicate the appropriate information for each linked object.

3	Invoke Edit on each embedded object. This should start the appropriate editor for each object.

4	Invoke Edit on a linked object. This should start the corresponding server application and the source document should be opened.

Postcondition

A separate editor is started each time the user chooses to edit an embedded object. Invoking Edit on a linked object establishes a link to its document. Check each open connection and make sure it is appropriate.

Special Cases

Try objects larger than 64K.

Some applications allow all of the changes made to a document to be discarded before rereading the document from disk. In this case, make sure that all of the old links are closed at reading time.

For linked objects, the link will be reestablished if the server application document is open. Check if the client application is calling OleRevertClientDoc ; this function does not return any value now but may return some value to a link manager.

If the client application uses OleSetTargetDevice  to get a different picture, make sure that the picture presentation does not change when the document is read again and the default printer is attached. Also check for proper presentation when the printer setup is changed within the client application. For example, a Microsoft Excel chart is monochrome when a plotter is the default printer, but is colored if a color printer is chosen.

Opening a Document - Server Application Test

From the user's perspective, the document will be opened immediately for an MDI application, and after the current document is closed for a SDI application. The opened document does not establish automatic links to a client application having links to it ems in this document.

From the developer's perspective, a SDI server application must revoke the existing document and register the opened document with the DLLs.

Opening an Existing SDI Server Document with a Changed Embedded Object

Precondition

The client application document contains an embedded object from a SDI server application.

Procedure

1	In the client application, open the embedded object for editing. The server application should be started.

2	In the server application, make changes in the embedded object.

3	In the server application, select File Open.

The server application should ask whether or not to update the embedded object.

4	Respond with Yes to the update embedded object prompt.

The client application should be updated unless the client application is Microsoft Excel or PowerPoint.

5	Open a document in the server application.

6	In the client application, activate the object again.

Postcondition

A new instance of the server application should be started to edit the object. The original instance should not be activated.

Similar Test Cases

Repeat the preceding procedure, but select No in Step 4. The client application should not be updated at this point, nor after Step 5.

Repeat the preceding procedure, but select Cancel, if available, in Step 4. Re activating the embedded object in the client application should cause the original server application instance to be re-activated.

Repeat the preceding procedure, but select Cancel in the File Open dialog box. Re activating the embedded object in the client application should cause the original server application instance to be re-activated.

Repeat the preceding procedure, but choose Insert Object in Step 1.

Repeat the preceding procedure, but choose Insert Template (if available) in Step 1.

Saving a File - Client Application Tests

Saving an Existing File with Multiple Object Types

Precondition

A client application contains embedded and linked objects from different server application and document types.

Procedure

Choose File Save to save the file. If any of the embedded objects' server applications are open, the client application should prompt to update the objects before saving. If an update is desired, the client application should get the latest update from the server application.

Postcondition

If the earlier document did not have a name, the client application should create the file with the most current data. Otherwise, the client application should update the file.

The old links (both embedded and linked objects) should not be broken.

Similar Test Cases

Repeat the test with different combinations of objects in the document such as:

More than one embedded object of the same server application type.

More than one embedded object and more than one linked object of the same server application type.

More than one embedded object and more than one linked object of different server application types.

Special Case

Block or busy some of the server applications and check the behavior of the client application. The update operation will not be completed until the server applications are unblocked or until they are not busy.

Saving an Existing File with Open Links

Precondition

A client application with embedded and linked objects of different server application and document types.

Procedure

Choose File Save to save the file.

Postcondition

All the open links should be intact.

Similar Test Cases

Save when the embedded objects' editors are open.

Save when the linked objects' editors are open.

Save when the server application is blocked/busy.

Saving an Existing File Requiring an Update

Precondition

A client application has an open document that contains both embedded and linked objects. This tests whether the client application prompts the user to update the embedded and linked objects before saving the document, and also if it saves the latest changes.

Procedure

1	Save the document as above the open the document and check that the latest objects are saved.

2	Open the editors for the embedded objects in the document and change the objects. When the document is saved, the client application keeps the updated copy of the object in the document.

Postcondition

Open the same document and check that the changed embedded objects are in the document.

Saving a File - Server Application Tests

From the user's perspective, saving a file will cause the server application to save the document. If the document to be saved is a currently embedded document opened from the client application, the server application will update the object in the client application and break the connection.

From the developer's perspective, if the document to be saved is an embedded document opened from the client application, the server application should send a saved notification message to the client application callback (or use OleSavedServerDoc). If, during the save operation, the document name is changed, the OleRenameServerDoc should be called which will break the connection for the embedded document.

Saving an Existing Server Document when a Linked Client Object Is Open

Precondition

A client application contains a linked object. There is a server application document with an open link to the linked object. This test verifies that the link is preserved by the server application after a File Save operation.

Procedure

Choose File Save in the server application.

Postcondition

The link should remain intact. Changing the object in the server application should update the object in the client application.

Similar Test Cases

Open links in the following ways:

Choose Edit Copy in the server application and Edit Paste Link in the client application. This creates a new linked object.

Start the server application by double clicking the linked object in the client application.

Replacing the File Save Command with the File Update Command

When a server application is acting as an editor for an embedded object, File Save should be replaced by File Update.

Renaming a File - Client Application Test

Renaming a file is accomplished with the Save As command under the File menu.

Renaming a File in a Client Application

Precondition

A client application contains embedded and linked objects and has links to the respective editors and documents.

Procedure

Choose File Save As to change the name of the file.

Postcondition

All the open links are intact and a new file is created.

Similar Test Case

Test with different embedded objects and linked objects (with open links). No server application should be shut down and no connections broken.

Renaming a File - Server Application Tests

Renaming a File in a Server Application Containing an Open Linked Object

Precondition

The client application contains a link to a server application document. The client application to server application conversation is established.

Procedure

1	Choose File Save As in the server application to change the name of the file.

2	In the client application, examine the link information (using the Link Properties dialog box, if available).

The link should be intact. The client application's link should now correspond to the new name of the server application document.

3	Close the server application document.

4	Activate the linked object in the client application.

Postcondition

The newly named file should be opened in the server application.

Similar Test Cases

The server application is started on its own or it is invoked by choosing Edit from the client application.

Renaming a File in a Server Application Containing an Embedded Object

Precondition

A server application document is open for editing an embedded object. The client application document also is open.

Procedure

1	In the server application, choose File Save As. If the object has changed, the server application should prompt to update it.

2	Respond with Yes to the update prompt to have the client application object update the object.

The server application should break the connection to the client application and create the new file.

3	Activate the object in the client application.

4	new instance of the server application containing a new document should be started to edit the object. The original instance should not be activated.

5	In the server application, copy the data from the saved file to the clipboard.

6	Examine the contents of the clipboard.

The ObjectLink format should be available.

7	Start a client application.

8	Choose Paste Link in the client application.

9	Make changes in the server application's saved document.

Post Condition

Changes should be reflected in the client application document.

Similar Test Cases

The embedded object should re activate the original instance of the server application.

Repeat the preceding procedure, but select Cancel at Step 1 if it is available. Re activating the embedded object in the client application should cause the re-activation of the original server application document.

Repeat the preceding procedure, but select Cancel in the File Save As dialog box. Reactivating the embedded object in the client application should cause the original server application document to be re activated.

Updating Objects

Updating an Object when the Server Is Started as an Editor

Precondition

A client application has opened an embedded object by starting its server application. When a server application is acting as the editor for an embedded object, File Save should be replaced by File Update.

Procedure

1	Make changes in the server application's document.

2. Choose File Update in the server application.

Postcondition

The object in the client application should be updated immediately. The conversation should not be broken.

Similar Test Cases

Establish an embedded link by starting the server application with the Insert Object command in the client application.

Establish an embedded link by starting the server application with the Insert Template command.

Special Test Cases

If update is chosen, the client application document should be updated and the server application (document) should close. If Continue Editing is chosen, the update operation should be canceled, in which case the server application should NOT reset its change flag when closing the server document . The server application should prompt before updating the client application object.

If the server application does not display the message box, make sure that the server application sends the appropriate data to the client application when the server application document is closed.

Editing Links

This section includes tests targeted at linked objects and the dialog box that displays information about linked objects.

Whenever possible, each test case should be performed under the following conditions:

The client application document is new.

The client application document has been obtained by opening a previously saved client application document.

The link in the client application document is not synchronized with the server application document object to which it refers.

Automatic Updating has been selected in the client application instance.

Manual Updating has been selected in the client application instance.

The client application, its document, server application, and its document are each in separate directories.

Editing Links when the Client Application Contains No Linked Objects

Precondition

The client application contains no linked objects.

Postcondition

The Edit Links command should appear disabled.

Editing Links when the Client Application Has Linked Objects

Precondition

The client application document contains linked objects.

Procedure

In the client application, open a document containing a linked object or create a new document and Paste Link an object into it.

Postcondition

The Edit Links command should be enabled.

Editing Links When No Server Applications Are Running

Precondition

A client application is open with a document which contains the linked object.

No instance of the server application is running.

The document to which the link refers is available.

Procedure

1	Activate the Edit Link Properties... command.

The Link Properties dialog box is displayed.

2	In the dialog box, select the button used for opening the linked item in its editor (usually labeled Edit).

Postcondition

The Link Properties dialog box should be closed.

The document to which the link refers should be opened in a newly launched instance of the appropriate server application.

The appearance of the object in the client application instance should be synchronized with the server application document object to which it is linked.

Editing Links by Activating a Currently Running Server Application Instance

Precondition

In the client application instance, a document containing a link is open.

The document to which the link refers is open in at least one currently running instance of the server application.

Procedure

1	Choose the Edit Link Properties... command.

2	In the dialog box, select the button used for opening the linked item in its editor (Edit).

Postcondition

The Link Properties dialog box should be closed.

The instance of the server application, that has the document to which the link refers, is open should be activated.

The object in the client application instance should be the same as the server application item to which it is linked.

The Postcondition for link activation should be in effect.

Editing Links Unsuccessfully

Precondition

In the client application instance, a document containing a linked object is open.

One or more of the following two conditions exists. Either the linked object's server application is unavailable or the document to which the link refers is unavailable. It is necessary to test for each case.

Procedure

1	Choose Edit Links ... to display the Link Properties dialog box.

2. In the dialog box, select the button used for opening the linked item in its editor (Edit).

Postcondition

An Attempt to open the link for editing should fail.

The Links dialog box should not disappear. The Links dialog box should allow the user to repair the broken link.

Changing the Properties of Linked Objects

Precondition

In the client application instance, a document containing a link is open.

Procedure

1	Choose the Edit Links command.

2	In the Link Properties dialog box, make one or more changes (such as changing Update from automatic to manual).

3	In the dialog box, select the button used for opening the linked item in its editor.

Postcondition

The changes made in the dialog box should be accepted, just as if the OK button had been pressed.

Validating Information in a Client Application Link Properties Dialog Box

Precondition

A client application contains linked and embedded objects.

Procedure

Choose the Edit Links command.

Postcondition

The client application displays a Link Properties dialog box that lists all of the linked objects in the document, but none of the embedded objects. For information on the Link Properties dialog box, see The OLE User Interface.

Manually Updating a Link When a Server Application Document is Open

Precondition

The server application allows linking of its objects.

The client application creates the linked object for automatic updating. It does not change the update option for the linked object; automatic is the default.

Procedure

1	Open a server application document and select an item to copy to the clipboard.

2	Choose Edit Copy to copy the item.

3	In the client application instance, choose Edit Paste Link to create a linked object.

4	In the client application instance, display the Link Properties dialog box.

5	Select the Manual Option.

6	Select OK to accept changes.

7	In the server application instance, make changes to the item to which the client application document is linked.

Changes made to the item in the server application instance should not change the appearance of the item in the client application document.

8	In the client application instance, choose Edit Links to display the Link Properties dialog box.

9	Choose the button used to force updating (Update Now).

Postcondition

All changes made to the item in the server application instance should be reflected in the appearance of the item in the client application document.

Similar Test Cases

Repeat the procedure, selecting Cancel in step 9. The item in the client application document should revert back to its state from before the Link Properties dialog box was displayed.

The client application, its document, the server application, and its document are all in separate directories.

After each test, save the client application document and reopen it to see if the changes were properly saved and activation of the saved item works correctly.

Disconnecting a Linked Object from its Source

After each test, save the client application document and reopen it to see if the changes were properly saved and activation of the saved object works as expected.

Precondition

A client application document contains a linked object.

Procedure

1	Choose Edit Link Properties to display the Link Properties dialog box.

2	Select the button used to disconnect a link from the item to which it refers (usually labeled Cancel Link).

3	buttons used for opening a link for editing should be disabled.

4	buttons Update Now and Cancel link should be disabled.

5	Choose OK.

Postcondition

The object is converted to a static object and double-clicking the object should not cause an error. The client application should inform the user that it is a static object.

Similar Test Case

Repeat the above procedure; select Cancel if the unlinking can be canceled. The unlinking should be canceled and the object should behave as a normal linked object.

Changing a Link Using the Link Properties Dialog Box

After each test, save the client application document and reopen it to see if the changes were properly saved and that activating the saved item works as expected.

Precondition

A client application document contains a link to an object in a server application document.

Procedure

1	Change the name of the server application document containing the object to which the client application document is linked.

Activating the link should fail.

Opening the link for editing using the Link Properties dialog box should fail.

Updating the link's presentation using the Link Properties dialog box should fail.

2	Choose Edit Link Properties to display the Link Properties dialog box.

3	Select the Change Link button. In the new change link dialog box, select the new file name.

4	Select OK.

Postcondition

The Link Properties dialog box closes.

The link should now be re connected to the newly named server application document, and link activation and updating behave as expected.

Starting a Client Application

There are several ways in which a client application can be started. The client application has to make sure that it can act as an OLE application in that it registers any document opened by the user and provides all of the OLE related features.

Starting the Client Application

Procedure

Start the client application using different methods such as double-clicking the icon, using File Run in the Program Manager, and using File Manager.

Postcondition

The client application registers the appropriate document.

The client application should start properly and it should be possible to create embedded and linked objects in the client application.

Similar Test Case

Start the client application and specify the document name on the command line. If the client application opens the document, verify that all of the objects are read properly and it is possible to edit them as usual.

Printing a File - Client Application Test

Printing a File Containing OLE Objects

Precondition

A client application document containing embedded and/or linked objects has a File Print option.

Procedure

Use File Print to print the document.

Postcondition

Usually, the client application will print the document with all of the embedded objects and the layout preserved.

Similar Test Cases

Try a document where embedded/linked objects may be overlapped.

Try different printer drivers.

Starting an Application - Server Application Test

From the developer's perspective, a server application registers itself using the parameter SINGLE_INSTANCE or MULTI_INSTANCE. If the server application is a single-instance application and the client application asks to edit an object, the server DLL opens a document. However, if the application is a multi-instance application, a new instance of the server application will be started by the DLL.

A server application that can only be started from within a client application will normally look for command line switches. A client application DLL will always start with the -Embedding  flag; if it is missing, the servers may automatically close. These types of servers are only available for OLE-related operations and they are started using the Insert New command.

Saving Clipboard Formats When Closing the Server Application

Precondition

A server application is open.

Procedure

1	Select the object and choose Edit Copy.

2	The object should be in the clipboard. Open the clipboard and check its format.

3	Close the server application

Postcondition

The formats should still be available in the clipboard. If the clipboard does contain formats, they should be in a consistent state with the same order and nature of selection preserved.

Starting a Single-Instance Server Application from the File Manager

Precondition

A single-instance server application can be started by double clicking on its icon.

Procedure

Start the server application using various methods such as double-clicking the icon, using File Run in the Program Manager, and using File Manager.

Postcondition

The server application registers itself and any document that it opens.

It should be possible to create a linked object and link to the appropriate item in the server application document.

If an embedded object is created and activated from the client application, the server application should open a new document for editing in the same instance of the server application.

Similar Test Case

Start the server application and give the document name on the command line. If the server application opens the document, verify that the server application registers the open document. A good way to test the registration is as follows:

1	Open the document's linked object in a client application.

2	Establish a link from the client application by double clicking the object in the client application.

3	the document is not registered, OLE will try to open the document.


Win32 Portability Summary

This appendix summarizes portability issues between OLE 1.0 for Windows 3.1 and OLE 1.0 for Win32. The following sections summarize the issues that are discussed in greater detail elsewhere in this document or in other Win32 documentation.

For more information, see the following topics:

Threading

Enhanced Metafiles

The Registry

The OLE Libraries

Object Handlers

Code Samples


Threading

All OLE calls must be in the same thread, preferably the main thread. Using multiple threads for a single OLE session could cause problems.


Enhanced Metafiles

OLE for Win32 has added the enhanced metafile (CF_ENHMETAFILE) as one of its standard presentation formats. In general, enhanced metafiles are preferrable to earlier-style metafiles (CF_METAFILEPICT).


The Registry

OLE for Win32 uses the Win32 registry instead of the Windows 3.1 system registration database. To add items to the registry, you must use registry-specific API function calls. Consult the Win32 documentation for the specific calls.


The OLE Libraries

The Win32 libraries (OLECLI32.DLL and OLESVR32.DLL) are supplied for Win32 OLE applications. The earlier Windows 3.1 libraries (OLECLI.DLL and OLESVR.DLL) are supplied for 16-bit application compatibility. The two sets of libraries can work together; for example, a 32-bit client can call a 16-bit server.


Object Handlers

For greatest compatibility, if you create a 32-bit handler, you should also create a 16-bit handler. Register the 32-bit handler with the key value handler32 and the 16-bit handler with the key value handler.

Object handlers should use .DEF files to specify the address they will be loaded at.

Object handler dynamic-link libraries (DLLs) should use the .DEF file to specify the new object-creation and new object-manipulation function names that will be exported. These will have the prefix Dll as part of their function name.


Code Samples

The code samples in this document may change slightly before final distribution. Check the actual code samples for the the sample SRVRDEMO.EXE and CLIDEMO.EXE applications. Also consult the final code in OLE.H.


Error Codes
Error Codes (OLE)

This appendix lists the OLE function error codes, the client Callback notification codes, and the OleQueryReleaseMethod function return codes.

For more information, see the following topics:

OLE Function Error Codes -- Numerical List

OLE Function Error Codes -- Alphabetical List

OleQueryReleaseMethod Return Codes

Client CallBack Notification Codes


OLE Function Error Codes -- Numerical List

All OLE functions of the OLESTATUS data type return one of the following enumerated error codes, as defined in OLE.H. If no errors occur, OLE_OK is returned. For information on the error codes returned by OLE functions, see The OLE Server DLL, and The OLE Client DLL.

The return codes listed here are in ascending order, by value.

0   OLE_OK

1   OLE_WAIT_FOR_RELEASE

2   OLE_BUSY

3   OLE_ERROR_PROTECT_ONLY

4   OLE_ERROR_MEMORY

5   OLE_ERROR_STREAM

6   OLE_ERROR_STATIC

7   OLE_ERROR_BLANK

8   OLE_ERROR_DRAW

9   OLE_ERROR_METAFILE

10  OLE_ERROR_ABORT

11  OLE_ERROR_CLIPBOARD

12  OLE_ERROR_FORMAT

13  OLE_ERROR_OBJECT

14  OLE_ERROR_OPTION

15  OLE_ERROR_PROTOCOL

16  OLE_ERROR_ADDRESS

17  OLE_ERROR_NOT_EQUAL

18  OLE_ERROR_HANDLE

19  OLE_ERROR_GENERIC

20  OLE_ERROR_CLASS

21  OLE_ERROR_SYNTAX

22  OLE_ERROR_DATATYPE

23  OLE_ERROR_PALETTE

24  OLE_ERROR_NOT_LINK

25  OLE_ERROR_NOT_EMPTY

26  OLE_ERROR_SIZE

27  OLE_ERROR_DRIVE

28  OLE_ERROR_NETWORK

29  OLE_ERROR_NAME

30  OLE_ERROR_TEMPLATE

31  OLE_ERROR_NEW

32  OLE_ERROR_EDIT

33  OLE_ERROR_OPEN

34  OLE_ERROR_NOT_OPEN

35  OLE_ERROR_LAUNCH

36  OLE_ERROR_COMM

37  OLE_ERROR_TERMINATE

38  OLE_ERROR_COMMAND

39  OLE_ERROR_SHOW

40  OLE_ERROR_DOVERB

41  OLE_ERROR_ADVISE_NATIVE

42  OLE_ERROR_ADVISE_PICT

43  OLE_ERROR_ADVISE_RENAME

44  OLE_ERROR_POKE_NATIVE

45  OLE_ERROR_REQUEST_NATIVE

46  OLE_ERROR_REQUEST_PICT

47  OLE_ERROR_SERVER_BLOCKED

48  OLE_ERROR_REGISTRATION

49  OLE_ERROR_ALREADY_REGISTERED

50  OLE_ERROR_TASK

51  OLE_ERROR_OUTOFDATE

52  OLE_ERROR_CANT_UPDATE_CLIENT

53  OLE_ERROR_UPDATE

54  OLE_ERROR_SETDATA_FORMAT

55  OLE_ERROR_STATIC_FROM_OTHER_OS

1000  OLE_WARN_DELETE_DATA


OLE Function Error Codes -- Alphabetical List

All OLE functions of the OLESTATUS data type return one of the following enumerated error codes, as defined in OLE.H. If no errors occur, OLE_OK is returned. For information on the error codes returned by OLE functions, see The OLE Server DLL, and The OLE Client DLL.

The return codes listed here are in alphabetical order.

Value	Meaning

OLE_BUSY	The client application tried to initiate an asychronous operation while another asynchronous operation was in progress.

OLE_ERROR_ABORT	The client application chose to cancel the metafile drawing.

OLE_ERROR_ADDRESS	An invalid pointer was used.

OLE_ERROR_ADVISE_NATIVE	The server application could not provide the native data for the specified item; this is usually because the item was deleted in the client application.

OLE_ERROR_ADVISE_PICT	A picture item could be missing or the server application doesn't recognize the presentation format of the object.

OLE_ERROR_ADVISE_RENAME	The server application doesn't support renaming of the object.

OLE_ERROR_ALREADY_REGISTERED	The server application is trying to register the same document multiple times.

OLE_ERROR_BLANK	There is critical data missing; this is generally caused by a user terminating the creation of an object. (The application gets an OLE-CLOSED notification and any subsequent calls to OLE APIs on this object will return this message.)

OLE_ERROR_CANT_UPDATE_CLIENT	The client application containing the embedded object doesn't accept updates.

OLE_ERROR_CLASS	An invalid class was specified.

OLE_ERROR_CLIPBOARD	The OLE libraries were unable to obtain the necessary data from the clipboard; this is generally caused by the client application's failure to get or set the clipboard data.

OLE_ERROR_COMM	The client application failed to establish communication with the server application.

OLE_ERROR_COMMAND	An error occurred in executing a DDE Execute command.

OLE_ERROR_DATATYPE	The data format requested is not supported.

OLE_ERROR_DOVERB	An error occurred in executing a verb; this could also indicate an invalid verb.

OLE_ERROR_DRAW	An error occurred while drawing the object.

OLE_ERROR_DRIVE	The document name contains an invalid drive letter.

OLE_ERROR_EDIT	The server application failed to create an embedded instance for the object.

OLE_ERROR_FORMAT	The requested format is not available.

OLE_ERROR_GENERIC	An error of unknown cause occurred.

OLE_ERROR_HANDLE	An invalid handle was encountered.

OLE_ERROR_LAUNCH	OLECLI.DLL failed to start the server application.

OLE_ERROR_MEMORY	Either the OLE DLLs or the server application could not allocate or lock memory.

OLE_ERROR_METAFILE	The metafile specified is invalid.

OLE_ERROR_NAME	An invalid name (for example, a document name or an object name) was passed to the function.

OLE_ERROR_NETWORK	The client application failed to establish a connection with a network share on which the document is located.

OLE_ERROR_NEW	The server application failed to create a new document.

OLE_ERROR_NOT_EMPTY	The client application's document contains objects.

OLE_ERROR_NOT_EQUAL	The objects are not equal.

OLE_ERROR_NOT_LINK	This is not a linked object.

OLE_ERROR_NOT_OPEN	The object is not open for editing.

OLE_ERROR_OBJECT	The object is not valid.

OLE_ERROR_OPEN	The server application failed to open the document; could also indicate an invalid link.

OLE_ERROR_OPTION	An invalid option occurred (link update or rendering of an object).

OLE_ERROR_OUTOFDATE	The object is out of date.

OLE_ERROR_PALETTE	An invalid color palette was specified.

OLE_ERROR_POKE_NATIVE	The OLE DLLs failed to give the native data to the server application.

OLE_ERROR_PROTECT_ONLY	The OLE function was called in real mode, which is not supported.

OLE_ERROR_PROTOCOL	An invalid protocol was specified as part of a parameter to an OLE API.

OLE_ERROR_REGISTRATION	The server application is not registered in the system registration database.

OLE_ERROR_REQUEST_NATIVE	The server application failed to render the native data.

OLE_ERROR_REQUEST_PICT	The server application failed to render the presentation data.

OLE_ERROR_SERVER_BLOCKED	The client application is trying to block a server application that is already blocked, or the client is trying to revoke a blocked server or document.

OLE_ERROR_SETDATA_FORMAT	The server application doesn't understand the format given to its SetData method.

OLE_ERROR_SHOW	An error occurred in showing the object.

OLE_ERROR_SIZE	An incorrect buffer size was passed to a function that places string information in the calling function's buffer.

OLE_ERROR_STATIC	A non static object was expected by the OLE libraries.

OLE_ERROR_STATIC_FROM_OTHER_OS	The client application is trying to load a static object created in another operating system.

OLE_ERROR_STREAM	An OLE stream error occurred; this is generally caused by a failure in the client application's Get or Put callback functions.

OLE_ERROR_SYNTAX	An invalid command syntax was specified.

OLE_ERROR_TASK	Either the server or client application is trying to perform an invalid task.

OLE_ERROR_TEMPLATE	The server application failed to load the specified template.

OLE_ERROR_TERMINATE	An error occurred while terminating the server application.

OLE_ERROR_UPDATE	An error occurred while trying to update the object in the client application.

OLE_OK	The function encountered no errors and completed successfully.

OLE_WAIT_FOR_RELEASE	The client or server application initiated a command, now it must wait for the object to be released. The application should keep dispatching messages until the release callback receives OLE_RELEASE.

OLE_WARN_DELETE_DATA	(A warning; not an error.) The calling application must delete the data when it is done with it.


OleQueryReleaseMethod Return Codes

The following codes are returned in response to an OleQueryReleaseMethod function call on a specific object. The return value indicates which server operation (method) caused the OLE library to send an OLE_RELEASE message to the client during asynchronous operations. For information on the OLEQueryReleaseMethod function, see The OLE Client DLL.

Code	Value	Server Operation

OLE_NONE	0	No operation is active

OLE_DELETE	1	Object delete

OLE_LNKPASTE	2	PasteLink(auto reconnect

OLE_EMBPASTE	3	Paste(and update

OLE_SHOW	4	Show

OLE_RUN	5	Run

OLE_ACTIVATE	6	Activate

OLE_UPDATE	7	Update

OLE_CLOSE	8	Close

OLE_RECONNECT	9	Reconnect

OLE_SETUPDATEOPTIONS	10	Setting update options

OLE_SERVERUNLAUNCH	11	Server is being unlaunched

OLE_LOADFROMSTREAM	12	LoadFromStream(auto reconnect

OLE_SETDATA	13	OleSetData

OLE_REQUESTDATA	14	OleRequestData

OLE_OTHER	15	Other misc async operations

OLE_CREATE	16	Create

OLE_CREATEFROMTEMPLATE	17	CreatefromTemplate

OLE_CREATELINKFROMFILE	18	CreateLinkFromFile

OLE_COPYFROMLNK	19	CopyFromLink(auto reconnect

OLE_CREATEFROMFILE	20	CreateFromFile

OLE_CREATEINVISIBLE	21	CreateInvisible


Client CallBack Notification Codes

The following table lists the notification codes that a client application can receive from the OLE DLL through the client's Callback function. For more information on the client Callback function, see Callback Functions and Data Structures.

Code	Value	Description

OLE_CHANGED	0	The object was modified in the server application

OLE_SAVED	1	The object was saved in the server application

OLE_CLOSED	2	The object was closed in the server application

OLE_RENAMED	3	The linked object was renamed in the server application

OLE_QUERY_PAINT	4	The client DLL needs to know if it should continue a lengthy painting operation.

OLE_RELEASE	5	The object is released because an asynchronous operation completed.

OLE_QUERY_RETRY	6	The client DLL needs to know whether it should continue trying to connect to a busy server application (returned in response to an OLE_BUSY from the server application).


OLE_BUSY
OLE_BUSY  2  ole.h

The client application tried to initiate an asychronous operation while another asynchronous operation was in progress.


FN_OLE_BUSY
OLE_BUSY  2  ole.h


OLE_ERROR_ABORT
OLE_ERROR_ABORT  10  ole.h

The client application chose to cancel the metafile drawing.


FN_OLE_ERROR_ABORT
OLE_ERROR_ABORT  10  ole.h


OLE_ERROR_ADDRESS
OLE_ERROR_ADDRESS  16  ole.h

An invalid pointer was used.


FN_OLE_ERROR_ADDRESS
OLE_ERROR_ADDRESS  16  ole.h


OLE_ERROR_ADVISE_NATIVE
OLE_ERROR_ADVISE_NATIVE  41  ole.h

The server application could not provide the native data for the specified item; this is usually because the item was deleted in the client application.


FN_OLE_ERROR_ADVISE_NATIVE
OLE_ERROR_ADVISE_NATIVE  41  ole.h


OLE_ERROR_ADVISE_PICT
OLE_ERROR_ADVISE_PICT  42  ole.h

A picture item could be missing or the server application doesn't recognize the presentation format of the object.


FN_OLE_ERROR_ADVISE_PICT
OLE_ERROR_ADVISE_PICT  42  ole.h


OLE_ERROR_ADVISE_RENAME
OLE_ERROR_ADVISE_RENAME  43  ole.h

The server application doesn't support renaming of the object.


FN_OLE_ERROR_ADVISE_RENAME
OLE_ERROR_ADVISE_RENAME  43  ole.h


OLE_ERROR_ALREADY_REGISTERED
OLE_ERROR_ALREADY_REGISTERED  49  ole.h

The server application is trying to register the same document multiple times.


FN_OLE_ERROR_ALREADY_REGISTERED
OLE_ERROR_ALREADY_REGISTERED  49  ole.h


OLE_ERROR_BLANK
OLE_ERROR_BLANK  7  ole.h

There is critical data missing; this is generally caused by a user terminating the creation of an object. (The application gets an OLE-CLOSED notification and any subsequent calls to OLE APIs on this object will return this message.)


FN_OLE_ERROR_BLANK
OLE_ERROR_BLANK  7  ole.h


OLE_ERROR_CANT_UPDATE_CLIENT
OLE_ERROR_CANT_UPDATE_CLIENT  52  ole.h

The client application containing the embedded object doesn't accept updates.


FN_OLE_ERROR_CANT_UPDATE_CLIENT
OLE_ERROR_CANT_UPDATE_CLIENT  52  ole.h


OLE_ERROR_CLASS
OLE_ERROR_CLASS  20  ole.h

An invalid class was specified.


FN_OLE_ERROR_CLASS
OLE_ERROR_CLASS  20  ole.h


OLE_ERROR_CLIPBOARD
OLE_ERROR_CLIPBOARD  11  ole.h

The OLE libraries were unable to obtain the necessary data from the clipboard; this is generally caused by the client application's failure to get or set the clipboard data.


FN_OLE_ERROR_CLIPBOARD
OLE_ERROR_CLIPBOARD  11  ole.h


OLE_ERROR_COMM
OLE_ERROR_COMM  36  ole.h

The client application failed to establish communication with the server application.


FN_OLE_ERROR_COMM
OLE_ERROR_COMM  36  ole.h


OLE_ERROR_COMMAND
OLE_ERROR_COMMAND  38  ole.h

An error occurred in executing a DDE Execute command.


FN_OLE_ERROR_COMMAND
OLE_ERROR_COMMAND  38  ole.h


OLE_ERROR_DATATYPE
OLE_ERROR_DATATYPE  22  ole.h

The data format requested is not supported.


FN_OLE_ERROR_DATATYPE
OLE_ERROR_DATATYPE  22  ole.h


OLE_ERROR_DOVERB
OLE_ERROR_DOVERB  40  ole.h

An error occurred in executing a verb; this could also indicate an invalid verb.


FN_OLE_ERROR_DOVERB
OLE_ERROR_DOVERB  40  ole.h


OLE_ERROR_DRAW
OLE_ERROR_DRAW  8  ole.h

An error occurred while drawing the object.


FN_OLE_ERROR_DRAW
OLE_ERROR_DRAW  8  ole.h


OLE_ERROR_DRIVE
OLE_ERROR_DRIVE  27  ole.h

The document name contains an invalid drive letter.


FN_OLE_ERROR_DRIVE
OLE_ERROR_DRIVE  27  ole.h


OLE_ERROR_EDIT
OLE_ERROR_EDIT  32  ole.h

The server application failed to create an embedded instance for the object.


FN_OLE_ERROR_EDIT
OLE_ERROR_EDIT  32  ole.h


OLE_ERROR_FORMAT
OLE_ERROR_FORMAT  12  ole.h

The requested format is not available.


FN_OLE_ERROR_FORMAT
OLE_ERROR_FORMAT  12  ole.h


OLE_ERROR_GENERIC
OLE_ERROR_GENERIC  19  ole.h

An error of unknown cause occurred.


FN_OLE_ERROR_GENERIC
OLE_ERROR_GENERIC  19  ole.h


OLE_ERROR_HANDLE
OLE_ERROR_HANDLE  18  ole.h

An invalid handle was encountered.


FN_OLE_ERROR_HANDLE
OLE_ERROR_HANDLE  18  ole.h


OLE_ERROR_LAUNCH
OLE_ERROR_LAUNCH  35  ole.h

OLECLI.DLL failed to start the server application.


FN_OLE_ERROR_LAUNCH
OLE_ERROR_LAUNCH  35  ole.h


OLE_ERROR_MEMORY
OLE_ERROR_MEMORY  4  ole.h

Either the OLE DLLs or the server application could not allocate or lock memory.


FN_OLE_ERROR_MEMORY
OLE_ERROR_MEMORY  4  ole.h


OLE_ERROR_METAFILE
OLE_ERROR_METAFILE  9  ole.h

The metafile specified is invalid.


FN_OLE_ERROR_METAFILE
OLE_ERROR_METAFILE  9  ole.h


OLE_ERROR_NAME
OLE_ERROR_NAME  29  ole.h

An invalid name (for example, a document name or an object name) was passed to the function.


FN_OLE_ERROR_NAME
OLE_ERROR_NAME  29  ole.h


OLE_ERROR_NETWORK
OLE_ERROR_NETWORK  28  ole.h

The client application failed to establish a connection with a network share on which the document is located.


FN_OLE_ERROR_NETWORK
OLE_ERROR_NETWORK  28  ole.h


OLE_ERROR_NEW
OLE_ERROR_NEW  31  ole.h

The server application failed to create a new document.


FN_OLE_ERROR_NEW
OLE_ERROR_NEW  31  ole.h


OLE_ERROR_NOT_EMPTY
OLE_ERROR_NOT_EMPTY  25  ole.h

The client application's document contains objects.


FN_OLE_ERROR_NOT_EMPTY
OLE_ERROR_NOT_EMPTY  25  ole.h


OLE_ERROR_NOT_EQUAL
OLE_ERROR_NOT_EQUAL  17  ole.h

The objects are not equal.


FN_OLE_ERROR_NOT_EQUAL
OLE_ERROR_NOT_EQUAL  17  ole.h


OLE_ERROR_NOT_LINK
OLE_ERROR_NOT_LINK  24  ole.h

This is not a linked object.


FN_OLE_ERROR_NOT_LINK
OLE_ERROR_NOT_LINK  24  ole.h


OLE_ERROR_NOT_OPEN
OLE_ERROR_NOT_OPEN  34  ole.h

The object is not open for editing.


FN_OLE_ERROR_NOT_OPEN
OLE_ERROR_NOT_OPEN  34  ole.h


OLE_ERROR_OBJECT
OLE_ERROR_OBJECT  13  ole.h

The object is not valid.


FN_OLE_ERROR_OBJECT
OLE_ERROR_OBJECT  13  ole.h


OLE_ERROR_OPEN
OLE_ERROR_OPEN  33  ole.h

The server application failed to open the document; could also indicate an invalid link.


FN_OLE_ERROR_OPEN
OLE_ERROR_OPEN  33  ole.h


OLE_ERROR_OPTION
OLE_ERROR_OPTION  14  ole.h

An invalid option occurred (link update or rendering of an object).


FN_OLE_ERROR_OPTION
OLE_ERROR_OPTION  14  ole.h


OLE_ERROR_OUTOFDATE
OLE_ERROR_OUTOFDATE  51  ole.h

The object is out of date.


FN_OLE_ERROR_OUTOFDATE
OLE_ERROR_OUTOFDATE  51  ole.h


OLE_ERROR_PALETTE
OLE_ERROR_PALETTE  23  ole.h

An invalid color palette was specified.


FN_OLE_ERROR_PALETTE
OLE_ERROR_PALETTE  23  ole.h


OLE_ERROR_POKE_NATIVE
OLE_ERROR_POKE_NATIVE  44  ole.h

The OLE DLLs failed to give the native data to the server application.


FN_OLE_ERROR_POKE_NATIVE
OLE_ERROR_POKE_NATIVE  44  ole.h


OLE_ERROR_PROTECT_ONLY
OLE_ERROR_PROTECT_ONLY  3  ole.h

The OLE function was called in real mode, which is not supported.


FN_OLE_ERROR_PROTECT_ONLY
OLE_ERROR_PROTECT_ONLY  3  ole.h


OLE_ERROR_PROTOCOL
OLE_ERROR_PROTOCOL  15  ole.h

An invalid protocol was specified as part of a parameter to an OLE API.


FN_OLE_ERROR_PROTOCOL
OLE_ERROR_PROTOCOL  15  ole.h


OLE_ERROR_REGISTRATION
OLE_ERROR_REGISTRATION  48  ole.h

The server application is not registered in the system registration database.


FN_OLE_ERROR_REGISTRATION
OLE_ERROR_REGISTRATION  48  ole.h


OLE_ERROR_REQUEST_NATIVE
OLE_ERROR_REQUEST_NATIVE  45  ole.h

The server application failed to render the native data.


FN_OLE_ERROR_REQUEST_NATIVE
OLE_ERROR_REQUEST_NATIVE  45  ole.h


OLE_ERROR_REQUEST_PICT
OLE_ERROR_REQUEST_PICT  46  ole.h

The server application failed to render the presentation data.


FN_OLE_ERROR_REQUEST_PICT
OLE_ERROR_REQUEST_PICT  46  ole.h


OLE_ERROR_SERVER_BLOCKED
OLE_ERROR_SERVER_BLOCKED  47  ole.h

The client application is trying to block a server application that is already blocked, or the client is trying to revoke a blocked server or document.


FN_OLE_ERROR_SERVER_BLOCKED
OLE_ERROR_SERVER_BLOCKED  47  ole.h


OLE_ERROR_SETDATA_FORMAT
OLE_ERROR_SETDATA_FORMAT  54  ole.h

The server application doesn't understand the format given to its SetData method.


FN_OLE_ERROR_SETDATA_FORMAT
OLE_ERROR_SETDATA_FORMAT  54  ole.h


OLE_ERROR_SHOW
OLE_ERROR_SHOW  39  ole.h

An error occurred in showing the object.


FN_OLE_ERROR_SHOW
OLE_ERROR_SHOW  39  ole.h


OLE_ERROR_SIZE
OLE_ERROR_SIZE  26  ole.h

An incorrect buffer size was passed to a function that places string information in the calling function's buffer.


FN_OLE_ERROR_SIZE
OLE_ERROR_SIZE  26  ole.h


OLE_ERROR_STATIC
OLE_ERROR_STATIC  6  ole.h

A non static object was expected by the OLE libraries.


FN_OLE_ERROR_STATIC
OLE_ERROR_STATIC  6  ole.h


OLE_ERROR_STATIC_FROM_OTHER_OS
OLE_ERROR_STATIC_FROM_OTHER_OS  55  ole.h

The client application is trying to load a static object created in another operating system.


FN_OLE_ERROR_STATIC_FROM_OTHER_OS
OLE_ERROR_STATIC_FROM_OTHER_OS  55  ole.h


OLE_ERROR_STREAM
OLE_ERROR_STREAM  5  ole.h

An OLE stream error occurred; this is generally caused by a failure in the client application's Get or Put callback functions.


FN_OLE_ERROR_STREAM
OLE_ERROR_STREAM  5  ole.h


OLE_ERROR_SYNTAX
OLE_ERROR_SYNTAX  21  ole.h

An invalid command syntax was specified.


FN_OLE_ERROR_SYNTAX
OLE_ERROR_SYNTAX  21  ole.h


OLE_ERROR_TASK
OLE_ERROR_TASK  50  ole.h

Either the server or client application is trying to perform an invalid task.


FN_OLE_ERROR_TASK
OLE_ERROR_TASK  50  ole.h


OLE_ERROR_TEMPLATE
OLE_ERROR_TEMPLATE  30  ole.h

The server application failed to load the specified template.


FN_OLE_ERROR_TEMPLATE
OLE_ERROR_TEMPLATE  30  ole.h


OLE_ERROR_TERMINATE
OLE_ERROR_TERMINATE  37  ole.h

An error occurred while terminating the server application.


FN_OLE_ERROR_TERMINATE
OLE_ERROR_TERMINATE  37  ole.h


OLE_ERROR_UPDATE
OLE_ERROR_UPDATE  53  ole.h

An error occurred while trying to update the object in the client application.


FN_OLE_ERROR_UPDATE
OLE_ERROR_UPDATE  53  ole.h


OLE_OK
OLE_OK  0  ole.h

The function encountered no errors and completed successfully.


FN_OLE_OK
OLE_OK  0  ole.h


OLE_WAIT_FOR_RELEASE
OLE_WAIT_FOR_RELEASE  1  ole.h

The client or server application initiated a command, now it must wait for the object to be released. The application should keep dispatching messages until the release callback receives OLE_RELEASE.


FN_OLE_WAIT_FOR_RELEASE
OLE_WAIT_FOR_RELEASE  1  ole.h


OLE_WARN_DELETE_DATA
OLE_WARN_DELETE_DATA  1000  ole.h

(A warning; not an error.) The calling application must delete the data when it is done with it.


FN_OLE_WARN_DELETE_DATA
OLE_WARN_DELETE_DATA  1000  ole.h


OLE File Formats

Note: The following information is for developers who choose to implement OLE into their applications without using the OLE libraries (DLLs), or who want to manipulate the private data format of OLE objects, such as for special buffering. File format information is given for applications that run in the Microsoft Windows graphical environment as well as the on the Macintosh computer.

OLE files on the Macintosh store pictures in PICT format while OLE files under Windows store picture objects as metafiles or in some other Windows format. When the OLE DLLs read a foreign file format, they ignore the foreign presentation data of the object and substitute a standard icon as a place holder.

If the platform reading the file has a server application available that reads the particular class of object, it can recreate the picture. However, if the file containing the OLE picture is used on a platform that does not support the server application 's class, the picture will not be available and cannot be activated or edited. Using the private data format, a client application can translate PICT format to metafile format, or metafile format to PICT format.

The DLLs perform the minimal conversion necessary when reading OLE objects on one platform that were written on the other. Where numbers are written by the libraries, the Macintosh numbers are byte-swapped to mimic the Intel convention. Native data formats are hidden from the libraries, so no conversion is applied to native data. Standard presentation formats (PICT, M etafile, and so on.) will convert, but an application cannot depend on anything more accurate than frame bounds for the picture.

The stream layout of embedded or linked objects contain presentation objects, which can be Standard (Windows: metafile, bitmap, or DIB; Macintosh: PICT), Generic, or NULL objects. The client DLL completely supports the standard presentation objects including the drawing. Neither the client application (nor the object handler, if present) have access to these presentation objects; they exist only for the OLE client DLL.

For more information, see the following topics:

Format Descriptions


Format Descriptions

The following sections describe the file formats used for the Windows operating system and for the Macintosh computer.

String Storage Layout

All strings use this format. A null string is a byte count (length) of zero only. That is, there will be four bytes with a value of zero, not four bytes plus one byte of variable data containing a null.

Embedded Object Storage Layout

The client DLL cannot convert native date. If a server application needs to convert native data, it can call OleGetData (native data), convert it, then call OleSetData . Storing platform ID into native data is a good idea if it will need to be converted.

Linked Object Storage Layout

Standard Presentation Object Storage Layout

For Windows, the class string is METAFILEPICT, ENHMETAFILE, BITMAP, or DIB; the client DLL is able to render these types of presentation data. For the Macintosh, the class string can only be METAFILEPICT.

Generic Presentation Object Storage Layout

The class string is the class name of the server application for that object. In Windows , the clipboard format name will only be included if the clipboard format value is NULL. Otherwise Presentation data size follows the clipboard format value.

On the Macintosh, only a clipboard type is used. It is the responsibility of either the client application or the object handler to save and load (or set) the bounds of the object in HIMETRIC or Pixel units along with the object.

When loading an object from a foreign file system (such as in the case of going from Macintosh to Windows ), TEXT and RTF clipboard formats will be converted by the DLLs and the data will persist. All other generic formats will be skipped and a blank picture will be substituted.

Static Object Storage Layout

A static object can only be a METAFILEPICT, ENHMETAFILE, BITMAP, or DIB object. On the Macintosh it will always be METAFILEPICT. The only difference between a static object and a presentation object is the value of the format ID.


Providing User Documentation

This topic contains suggestions for writing the user documentation that will accompany your OLE client application. Since it is not practical to address the specific documentation requirements for all applications that implement OLE, this topic is limited to general guidelines that can be followed when writing user documentation, some "boilerplate" text and subjectheadings, plus a description of the termin ology that can be used in documentation that supports OLE applications.

By using variations of the sample text given in this topic, you can provide basic instructions needed by your end user when using the OLE features in your application.

Note:	Most user manuals are divided into chapters or major sections. When documenting the OLE features in your application, a separate chapter or section titled "Inserting Objects from Other Programs," is recommended.

For more information, see the following topics:

Background Information on OLE

Linking Information

Embedding Information

General Recommendations


Background Information on OLE

OLE (Object Linking and Embedding) is not a term that the user typically needs to be aware of. The user does, however, need to be aware of the benefits and features provided by OLE in your application. To this end, it is important to introduce the concept of OLE to the users, but in a fashion that appeals to their viewpoint.

The sample paragraphs in the following example make up an introduction to an "Inserting Objects from Other Programs" chapter.

Chapter n. Inserting Objects from Other Programs

As software and software users become more sophisticated, individual applications provide more powerful ways to manipulate specific kinds of information. Applications are now available that help you create graphs, drawings, worksheets, text documents, sl ides, electronic mail, and charts--to name only a few. With the linking and embedding features in <your_application_name> , you can now bring these separate kinds of information, referred to as objects, together into a single document. This document, referred to as a container document, allows you to make changes to the objects without leaving <your_application_name>.

Linking and embedding are based on exchanging information using the Clipboard where you select the object you want to insert into the container document and choose the Copy command to place it on the Clipboard. Then, in the container document, you position the insertion point where you want the object to appear and use the Paste Special command from the Edit menu to link or embed it.

<your_application_name> can automatically update the information with any changes that occur in the original. For instance, if you link sales data from a worksheet to a report written in <your_application_name> , the report can automatically reflect changes to the data in the worksheet. You can also link <your_application_name> documents to other applications or documents so that changes made in the <your_application_name> documents are reflected in the other applications or documents.

Alternatively, you can embed information from another application or document. This means the information contained in the object actually becomes part of your <your_application_name> document; there are no links to other files. For example, you can create a logo in a drawing application and embed it in a <your_application_name> document. If you decide to change the design of the logo, you can just double-click it, and <your_application_name> opens a window of the drawing application. When you ve finished making changes, you save the logo, close the drawing window, and return to <your_application_name>; the changed logo is in your document.

The primary difference between linking and embedding is the location where the actual data for the object is stored. The data for a linked object is stored outside the container document in a source document. Embedded information, however, is stored right in the container document. Keep this difference in mind when deciding whether to link or embed information. If you want to use the information in one document only, its better to embed; in most other cases, its better to link.

Sample text explaining how to insert objects


Linking Information

Since linking and embedding are different features of your application, they can be discussed separately in the user documentation. Additional information on the linking feature can be provided before presenting the step-by-step procedures on how to link objects.

This section of your user manual can have the following topics:

Creating Links

Updating Links

Editing Linked Information

Canceling a Link

Sample text presenting an overview of linking is shown in the following example.

Linking

By creating links in <your_application_name>, you save time and ensure consistency in your documents. You can share information from one document with several others, and you only need to maintain the original; the others are updated automatically. For example, if you store sales Figures in a worksheet, you can use that data i n several different reports created with <your_application_name>. As long as you update the worksheet, <your_application_name> updates the reports.

Creating links is as easy as copying and pasting. You copy a selection from an application or document called the source and paste it where you want to appear in the container document. You can create links between two <your_application_name> documents or between a <your_application_name> document and a file created by another application.

Once you ve established links, you can check for new data and retrieve it with a single keystroke; or you can specify that new data is sent as soon as it is available.

You can link information in a variety of presentation formats--for example, as unformatted or formatted text. You can create links between <your_application_name> and other applications that support linking.

Sample overview of linking objects

Creating Links

Under the subject of "Creating Links," you can insert step-by-step procedures that guide the user through the actual process of linking objects. For example, you might have a procedure titled "Creating a Link from a Source File in Another Application." This procedure would describe how to insert a link to a file that was created using some other application, and would be centered around the Paste Special dialog box in a manner similar to that shown in the following example.

Creating Links

To create links, you use the Paste Special command on the Edit menu.

Paste Special dialog box

Source: The application containing the source of the information on the Clipboard

Data Type: The presentation formats available from the Clipboard. These vary from application to application. Those in the list that have a format ending with the wordobject, as in Paintbrush Picture Object, shown in the preceding illustration, are not used for linking, only to embed objects.

Sample text explaining the Paste Special dialog box

Another linking procedure might describe how to create a link to source information that was created with your application, such as a file other than the current file.

Be sure to caution the user with regard to saving the source file prior to performing any linking operations.

Updating Links

There are several procedures that can be included to describe different link update operations. These procedures may include:

Changing the Update Option of a Link

Locking a Link

Manually Updating a Link

Printing a Document Containing Update Links

Reconnecting a Broken Link

The section on Updating Links could be introduced as shown in the following example.

Updating Links

Links can be updated either automatically or only when you request it. For example, if you link a worksheet to a Word document, you can control whether the information in the Word document changes every time the worksheet changes or only when you want the Word document to change. Use the Links command on the Edit menu to change the update option.

Automatic: Whenever a change is made in the source file, that change is shown immediately in each destination document. You dont have to request updates, and you always have the most recent information.

Manual : You request changes from the source file when you want them. This option gives you more control over your document.

Locked: The information in the link is frozen when you select this check box. Use this option when you ve reached the final version of the linked information and want to stop updating without canceling the link.

Sample text describing links and how to change them

Changing and Canceling Links

If appropriate, users need to be aware of how to make changes to links that appear in their document and also how to delete links. In general, the user should instructed to change the contents or the formatting of linked information at its source. The p rocedure should stress the ease at which the user can move directly from the container document to the source of a link using the Links command.

The procedure for canceling a link should explain that the linked information remains in the container document, but it can no longer be updated.


Embedding Information

This section of your user manual can provide the user with the embedding information and procedures on embedded objects. This section may have some or all of the following topics:

Embedding Existing Objects

Creating Embedded Objects

Editing an Object

Canceling Embedding

Your introduction to embedding could contain the information shown in the following example.

Embedding

By embedding information, you gain fast access to the features of another application without having to go to that application each time you want to make a change. The technique of embedding is simple: You copy a selection from one document and then insert it into another. The information you insert is called an object.

When you embed an object, any instructions ne eded to create the object are inserted along with it. This included the objects file format, the name of the application that created it, and information about how to display it. You don t see this information; it is simply to display and edit the object.

Embedding makes editing and updating objects quick and simple. You can just double-click the object to open it in its source application. Then you make your changes and Exit or choose the Update command from the source application s File menu, and the embedded object is updated automatically. You may also want to use the Object command on the Insert menu to create different types of objects in <your_application_name>.

Sample overview of embedded objects

Embedding Existing Objects

Existing objects are those that have already been created using another application and are ready to be pasted into the destination document. The procedure of embedding existing objects can be centered around the Paste Special dialog box in a manner similar to that shown in the following example.

Embedding Existing Objects

You use the Paste Special command to embed an object that has already been created.

Source: The source application and the name of the file containing the original copy of the object.

Data: Type Lists the presentation formats available for the information on the Clipboard. These vary from application to application. Make sure you select the data type ending with the wordobject, as in PC Paintbrush Picture Object, shown in the preceding illustration.

Page 20

Sample text explaining how to embed objects

Since the user can typically embed objects both into and from the container document, procedures should be provided for both when appropriate.

Creating Embedded Objects

If your application allows the user to embed an object by starting a server application, creating the object, and then updating the container document, an appropriate procedure should be provided. A procedure that describes how to embed an object created with your application into some other application may also be necessary.

Editing and Canceling Embedded Objects

One of the main benefits of OLE is the ability to edit an object in a container document by simply double-clicking on the object. An appropriate procedure should be provided for this function.

If your application allows the user to cancel the embedded state of an object by making it a permanent part of the container document, a procedure and explanation should be provided. The introduction for this procedure could read.

"Because the objects you embed include the information necessary to create them, embedding can increase the size of your files. You can reduce your file size by changing the object to a picture. The object remains in your document, but you can no longer change it by double-clicking it."


General Recommendations

The implementation of OLE into an application introduces new terms to the user. A s a means of providing a standard set of terms to OLE application users, the following recommendations and list of words are provided for use within user documentation.

The following strategies are recommended for writing about OLE:

Whenever possible, indicate the type of object under discussion - for example, "Word text," "CorelDraw drawing," "1-2-3 worksheet," and so on.

When appropriate, indicate whether an object is linked or embedded by using a modifier such as "linked object" or "embedded object."

Distinguish between the link and the source information.

Distinguish between a "document" and a "document's application," using the appropriate term:

source document and source application

container document and container application

Distinguish between a "document" and a "file." Reserve the word "file" for operating system level discussions.

Use "compound document" in general, conceptual discussions of OLE. Use "container document" for procedural descriptions and instructions.

Use "copying" only as a generic term that covers standard copying and pasting as well as linking and embedding.

Note:	See the Glossary of Terms, later in this manual, for a description of OLE-specific terminology as used in this manual.


RasDial function
RasDial (Win32)

DWORD RasDial(reserved, lpszPhonebookPath, lprasdialparams, reserved2, notifier, lphrasconn)

LPTSTR reserved;	/* reserved; must be set to NULL	*/
LPTSTR lpszPhonebookPath;	/* full pathname to phonebook file	*/
LPRASDIALPARAMS lpRasDialParams;	/* points to calling parameters	*/
LPVOID reserved2;	/* reserved; must be set to NULL	*/
RASDIALFUNC notifier;	/* callback function for RasDial events	*/
LPHRASCONN lphRasConn;	/* points to variable to receive connection handle	*/

The RasDial function establishes a remote access (RAS) connection between a RAS client and a RAS server. The connection data includes callback and user authentication information.

Parameter	Description

reserved	This parameter is reserved, and should always be set to NULL.

lpszPhonebookPath	Points to a string that specifies the full path to the phonebook file. This parameter can be NULL, and typically is; in that case, the default phonebook is used.

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.

reserved2	This parameter is reserved, and should always be set to NULL.

notifier	Points to an optional application-supplied callback function of type RASDIALFUNC. For a full description of this type of callback function, see RasDialFunc.

If such a callback function is specified, RasDial calls it for each RasDial event. Additionally, the RasDial call will be asynchronous; that is, given a callback function, RasDial will return immediately, before the connection is established.

If, on the other hand, notifier is NULL, the RasDial call will not return until the connection attempt has either succeeded or failed.

lphRasConn	Points to a variable of type HRASCONN. If the function succeeds, it stores a handle to the connection into that variable; if the function fails, it sets the variable to NULL.

Returns

The immediate return value if the function succeeds is 0. In addition, the function stores a handle to the RAS connection into the variable pointed to by lphRasConn.

The immediate return value if the function fails is a non-zero error code, either from the set listed in the file RASERROR.H or ERROR_NOT_ENOUGH_MEMORY.

Comments

Errors that occur after the immediate return can be detected with the RasGetConnectStatus function. Data is available until an application calls RasHangUp to hang up the connection.

An application must eventually call RasHangUp whenever a valid connection handle (not -1) is returned into the variable pointed to by lphRasConn. This must be done even if the connection fails.

An application can safely call RasHangUp from a RasDial notifier callback function. If this is done, however, the actual hangup does not occur until the routine returns.

A note for applications seeking Win16 compatibility: In Win16, a RasDial caller does not pass a pointer to a callback function, but instead passes an HWND specifying a window that will receive RasDial event messages.

See Also

RasDialFunc, RasGetConnectStatus, RasHangUp, RASCONN, RASDIALPARAMS


RasDialFunc function
RasDialFunc (Win32)

VOID RasDialFunc(unMsg, rasconnstate, dwError)

UINT unMsg;	/* type of event that has occurred	*/
RASCONNSTATE rasconnstate;	/* connection state about to be entered	*/
DWORD dwError;	/* error that may have occurred	*/

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 remote access connection process.

Parameter	Description

unMsg	Specifies the type of event that has occurred. For the first release of Windows NT, this is always WM_RASDIALEVENT.

rasconnstate	A RASCONNSTATE enumerator value that indicates the state that the RasDial remote access connection process is about to enter.

dwError	Indicates the error that has occurred, or 0 if no error has occurred.

RasDial calls RasDialFunc with dwError set to 0 upon entry to each connection state. If an error occurs within a state, RasDialFunc is called again for the state, this time with a non-zero dwError value.

Comments

The connection state machine is suspended during the call to a RasDialFunc callback function. For that reason, a RasDialFunc callback function should generally return as quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices such as modems often have timeout periods measured in seconds rather than milliseconds; a less-than-prompt return from a RasDialFunc function is generally not problematic. The prompt return requirement also does not apply when dwError is a non-zero value, indicating that an error has occurred. It is safe, for example, to put up an error dialog box and wait for user input.

RasDial should not be called from within a RasDialFunc callback function. The other remote access functions APIs (RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp) can be called from within the callback function. For example, it can be useful to call RasGetConnectStatus from within a callback function to determine the name and type of the connecting device.

Note that, for convenience, RasHangUp can be called from within a RasDialFunc callback function. It should be understood, however, that 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

RasDial, RASCONNSTATE


RasEnumConnections function
RasEnumConnections (Win32)

DWORD RasEnumConnections(lprasconn, lpcb, lpcConnections)

LPRASCONN lprasconn;	/* buffer to receive connections data	*/
LPDWORD lpcb;	/* size in bytes of buffer	*/
LPDWORD lpcConnections;	/* number of connections written to buffer	*/

The RasEnumConnections function lists all active remote access connections. It returns each connection's connnection handle and phone book entry name.

Parameter	Description

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.

Returns

If the function succeeds, the return value is 0.

If the function fails, the return value is a non-zero error code. This will be a code from the set listed in RASERROR.H, ERROR_BUFFER_TOO_SMALL, or ERROR_NOT_ENOUGH_MEMORY.

Comments

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

RasEnumEntries, RasGetConnectStatus, RASCONN


RasEnumEntries function
RasEnumEntries (Win32)

DWORD RasEnumEntries (reserved, lpszPhonebookPath, lprasentryname, lpcb, lpcEntries)

LPTSTR reserved;	/* reserved; must be NULL	*/
LPTSTR lpszPhonebookPath;	/* full path to phonebook file	*/
LPRASENTRYNAME lprasentryname;	/* buffer to receive phonebook entries	*/
LPDWORD lpcb;	/* size in bytes of buffer	*/
LPDWORD lpcEntries;	/* number of entries written to buffer	*/

The RasEnumEntries function lists all entry names in a remote access phone book.

Parameter	Description

reserved	Reserved for future use. Must be set to NULL.

lpszPhonebookPath	Points to a string that specifies the full path to the phone book file. This parameter can be NULL, and typically is; in that case, the default phone book is used.

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 it succeeds, sets to the number of phone book entries written to the buffer specified by lprasentryname.

Returns

If the function succeeds, the return value is 0.

If the function fails, the return value is a non-zero error code. This will be a code from the set listed in RASERROR.H, ERROR_BUFFER_TOO_SMALL, or ERROR_NOT_ENOUGH_MEMORY.

See Also

RasEnumConnections, RASENTRYNAME


RasGetConnectStatus function
RasGetConnectStatus (Win32)

DWORD RasGetConnectStatus(hrasconn, lprasconnstatus)

HRASCONN hrasconn;	/* handle to RAS connection of interest	*/
LPRASCONNSTATUS lprasconnstatus;	/* buffer to receive status data	*/

The RasGetConnectStatus function obtains information on the current status of a specified remote access connection. The current status data is returned in a RASCONNSTATUS structure. An application can use this call to determine when an asynchronous RasDial call has completed.

Parameter	Description

hrasconn	A remote access connection handle, obtained from RasDial or RasEnumConnections, that specifies the RAS connection whose status the function will obtain.

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.

Returns

If the function succeeds, the return value is 0.

If the function fails, the return value is a non-zero error code. This will be a code from the set listed in RASERROR.H, ERROR_INVALID_HANDLE, or ERROR_NOT_ENOUGH_MEMORY.

See Also

RasDial, RasEnumConnections, RASCONNSTATUS


RasGetErrorString function
RasGetErrorString (Win32)

DWORD RasGetErrorString (uErrorCode, lpszErrorString, cBufSize)

UINT uErrorCode;	/* error code to get string for	*/
LPTSTR lpszErrorString;	/* buffer to hold error string	*/
DWORD cBufSize;	/* sizeof buffer	*/

The RasGetErrorString function obtains an error message string for a specified RAS remote access error code.

Parameter	Description

uErrorCode	Specifies the error code of interest. These are codes returned by one of the RAS remote access functions: those listed in RASERROR.H between RASBASE and RASBASEEND. Any other code causes the function to fail, returning ERROR_INVALID_PARAMETER.

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.

Returns

If the function succeeds, the return value is 0.

If the function fails, the return value is a non-zero error code. This code is ERROR_INVALID_PARAMETER, or the GetLastError codes 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.

Comments

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 less in size; a buffer size of 256 characters will always be adequate. A buffer of insufficient size causes the RasGetErrorString function to fail, returning the error code ERROR_INSUFFICIENT_BUFFER. Note carefully 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.


RasHangUp function
RasHangUp (Win32)

DWORD RasHangUp(hrasconn)

HRASCONN hrasconn;	/* handle to the RAS connection to hang up	*/

The RasHangUp function terminates a RAS remote access connection. The connection is specified with a RAS connection handle. The function releases all RASAPI32.DLL resources associated with the handle.

Parameter	Description

hrasconn	A handle that specifies the remote access connection to terminate. This is a handle returned from a previous call to RasDial or RasEnumConnections.

Returns

If the function succeeds, the return value is 0.

If the function fails, the return value is a non-zero error code. This will be a code from the set listed in RASERROR.H or ERROR_INVALID_HANDLE.

Comments

The connection is terminated even if the RasDial call has not yet 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

RasDial, RasEnumConnections, RASCONN


Remote Access

RasDial	Establishes a RAS connection

RasDialFunc	Called by RasDial when connection state changes

RasEnumConnections	Lists active RAS connections

RasEnumEntries	Lists entries in a RAS phone book

RasGetConnectStatus	Reports current status of a RAS connection

RasGetErrorString	Converts RAS error code to error string

RasHangUp	Terminates a RAS connection


AccessCheck function
AccessCheck (Win32)

BOOL AccessCheck(pSD, hClientToken, dwDesiredAccess, pgm, pps, cbps, lpdwGrantedAccess, lpfStatus)

PSECURITY_DESCRIPTOR pSD;	/* address of security descriptor	*/
HANDLE hClientToken;	/* handle of client access token	*/
DWORD dwDesiredAccess;	/* access mask to request	*/
PGENERIC_MAPPING pgm;	/* address of generic-mapping structure	*/
PPRIVILEGE_SET pps;	/* address of privilege-set structure	*/
LPDWORD cbps;	/* size of privilege-set structure	*/
LPDWORD lpdwGrantedAccess;	/* address of granted access mask	*/
LPBOOL lpfStatus;	/* address of flag indicating whether access granted	*/

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.

Parameter	Description

pSD	Points to a SECURITY_DESCRIPTOR structure against which access is checked.

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

dwDesiredAccess	Specifies the access mask to be requested. This mask must have been mapped by the MapGenericMask function to contain no generic access rights.

pgm	Points to the GENERIC_MAPPING structure associated with the object for which access is being checked.

pps	Points to a PRIVILEGE_SET structure 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.

cbps	Specifies the size, in bytes, of the buffer pointed to by the pps parameter.

lpdwGrantedAccess	Points 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.

lpfStatus	Points to a flag indicating the success or failure of the access check. If lpfStatus is TRUE, the access token has the requested access to the object. If lpfStatus 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The AccessCheck function compares the specified security descriptor with the specified access token and indicates, in the lpfStatus 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, MapGenericMask, PrivilegeCheck, GENERIC_MAPPING, PRIVILEGE_SET, SECURITY_DESCRIPTOR


AccessCheckAndAuditAlarm function
AccessCheckAndAuditAlarm (Win32)

BOOL AccessCheckAndAuditAlarm(lpszSubsystem, lpvHandleId, lpszObjectType, lpszObject, psd, dwDesiredAccess, pgm, fObjectCreation, lpdwGrantedAccess, lpfAccessStatus, lpfGenerateOnClose)

LPCTSTR lpszSubsystem;	/* address of string for subsystem name	*/
LPVOID lpvHandleId;	/* address of handle identifier	*/
LPTSTR lpszObjectType;	/* address of string for object type	*/
LPTSTR lpszObject;	/* address of string for object name	*/
PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
DWORD dwDesiredAccess;	/* mask for requested access rights	*/
PGENERIC_MAPPING pgm;	/* address of GENERIC_MAPPING	*/
BOOL fObjectCreation;	/* object-creation flag	*/
LPDWORD lpdwGrantedAccess;	/* address of mask for granted rights	*/
LPBOOL lpfAccessStatus;	/* address of flag for results	*/
LPBOOL lpfGenerateOnClose;	/* address of flag for audit generation	*/

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.

Parameter	Description

lpszSubsystem	Points to a null-terminated string specifying the name of the subsystem calling the function--for example, "DEBUG" or "WIN32."

lpvHandleId	Points to a unique 32-bit value representing the client's handle of the object. If the access is denied, this value is ignored and may be reused.

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

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

psd	Points to the SECURITY_DESCRIPTOR structure against which access is checked.

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

pgm	Points to the GENERIC_MAPPING structure associated with the type of object being examined.

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

lpdwGrantedAccess	Points to a buffer that receives an access mask indicating which access rights were granted, if the function succeeds.

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, MapGenericMask, ObjectCloseAuditAlarm, ObjectOpenAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm, GENERIC_MAPPING, SECURITY_DESCRIPTOR


AddAccessAllowedAce function
AddAccessAllowedAce (Win32)

BOOL AddAccessAllowedAce(pAcl, dwAclRevision, dwAccessMask, pSid)

PACL pAcl;	/* address of access-control list	*/
DWORD dwAclRevision;	/* ACL revision level	*/
DWORD dwAccessMask;	/* access mask	*/
PSID pSid;	/* address of security identifier	*/

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. An SID is a security identifier.

Parameter	Description

pAcl	Points 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.

dwAclRevision	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 granted to the specified SID.

pSid	Points to the SID structure representing a process being granted access.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 this function specifies a type and size, but provides no inheritance and no ACE flags.

See Also

AddAccessDeniedAce, AddAce, AddAuditAccessAce, DeleteAce, GetAce, ACCESS_ALLOWED_ACE, ACCESS_MASK, ACE_HEADER, ACL, SID


AddAccessDeniedAce function
AddAccessDeniedAce (Win32)

BOOL AddAccessDeniedAce(pAcl, dwAclRevision, dwAccessMask, pSid)

PACL pAcl;	/* address of access-control list	*/
DWORD dwAclRevision;	/* ACL revision level	*/
DWORD dwAccessMask;	/* access mask	*/
PSID pSid;	/* address of security identifier	*/

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. An SID is a security identifier.

Parameter	Description

pAcl	Points 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.

The ACL structure has the following form:

typedef struct _ACL { /* acl */

    BYTE AclRevision;

    BYTE Sbz1;

    WORD AclSize;

    WORD AceCount;

    WORD Sbz2;

} ACL;

dwAclRevision	Specifies the revision level of the ACL being modified. Currently, this value must be ACL_REVISION.

dwAccessMask	Specifies the mask of access rights being denied to the specified SID.

pSid	Points to the SID structure representing the process being denied access.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The ACE_HEADER structure placed in the ACE by this function specifies a type and size, but provides no ACE flags.

See Also

AddAccessAllowedAce, AddAce, AddAuditAccessAce, DeleteAce, GetAce, ACCESS_DENIED_ACE, ACCESS_MASK, ACE_HEADER, ACL, SID


AddAce function
AddAce (Win32)

BOOL AddAce(pAcl, dwAclRevision, dwStartingAceIndex, lpvAceList, cbAceList)

PACL pAcl;	/* address of access-control list	*/
DWORD dwAclRevision;	/* ACL revision level	*/
DWORD dwStartingAceIndex;	/* index of ACE position in ACL	*/
LPVOID lpvAceList;	/* address of one or more ACEs	*/
DWORD cbAceList;	/* size of buffer for ACEs	*/

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.

Parameter	Description

pAcl	Points to an ACL structure. This function adds an ACE to this ACL.

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

lpvAceList	Points to a list of one or more ACEs to be added to the specified ACL. The ACEs in the list must be stored contiguously.

cbAceList	Specifies the size, in bytes, of the input buffer pointed to by the lpvAceList parameter.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

AddAccessAllowedAce, AddAccessDeniedAce, AddAuditAccessAce, DeleteAce, FindFirstFreeAce, GetAce, GetAclInformation, ACE, ACL, ACL_SIZE_INFORMATION


AddAuditAccessAce function
AddAuditAccessAce (Win32)

BOOL AddAuditAccessAce(pAcl, dwAclRevision, dwAccessMask, pSid, fAuditSuccess, fAuditFailure)

PACL pAcl;	/* address of access-control list	*/
DWORD dwAclRevision;	/* ACL revision level	*/
DWORD dwAccessMask;	/* access mask	*/
PSID pSid;	/* address of security identifier	*/
BOOL fAuditSuccess;	/* flag for auditing successful access	*/
BOOL fAuditFailure;	/* flag for auditing unsuccessful access attempts	*/

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. An SID is a security identifier.

Parameter	Description

pAcl	Points 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.

dwAclRevision	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	Points to the SID structure representing the process whose access is being audited.

fAuditSuccess	Specifies whether successful access attempts are to be audited. Set this flag to TRUE to enable auditing; otherwise, set it to FALSE.

fAuditFailure	Specifies whether unsuccessful access attempts are to be audited. Set this flag to TRUE to enable auditing; otherwise, set it to FALSE.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The ACE_HEADER structure placed in the ACE by this function specifies a type and size, but provides no ACE flags.

See Also

AddAccessAllowedAce, AddAccessDeniedAce, AddAce, DeleteAce, GetAce, ACCESS_MASK, ACE_HEADER, ACL, SID, SYSTEM_AUDIT_ACE


AdjustTokenGroups function
AdjustTokenGroups (Win32)

BOOL AdjustTokenGroups(hToken, fResetToDefault, ptgNew, cbtgPrevious, ptgPrevious, pcbtgPreviousRequired)

HANDLE hToken;	/* handle of token that contains groups	*/
BOOL fResetToDefault;	/* flag for default settings	*/
PTOKEN_GROUPS ptgNew;	/* address of new group information	*/
DWORD cbtgPrevious;	/* size of buffer for previous information	*/
PTOKEN_GROUPS ptgPrevious;	/* address of previous group information	*/
PDWORD pcbtgPreviousRequired;	/* address of required buffer size	*/

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.

Parameter	Description

hToken	Identifies the access token containing the groups to be modified.

fResetToDefault	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 ptgNew parameter is ignored. If this value is FALSE, the groups are set according to the information pointed to by the ptgNew parameter.

ptgNew	Points to a TOKEN_GROUPS structure containing the groups whose states are to be set. If the fResetToDefault 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 fResetToDefault is TRUE, this parameter is ignored.

cbtgPrevious	Specifies the size, in bytes, of the buffer pointed to by the ptgPrevious parameter. If the ptgPrevious parameter is NULL, this parameter can be also.

ptgPrevious	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 pcbtgPreviousRequired parameter to the number of bytes required to hold the complete list of modified groups.

pcbtgPreviousRequired	Points to a variable set by the function that contains the actual number of bytes needed for the buffer pointed to by the ptgPrevious parameter. This parameter can be NULL and is ignored if ptgPrevious is NULL.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. Call GetLastError to obtain extended error information.

Comments

The information retrieved in the ptgPrevious parameter is formatted as a TOKEN_GROUPS structure. This means a pointer to the buffer can be passed as the ptgNew parameter in a subsequent call to the AdjustTokenGroups function, restoring the original state of the groups.

The ptgNew 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, SID_AND_ATTRIBUTES


AdjustTokenPrivileges function
AdjustTokenPrivileges (Win32)

BOOL AdjustTokenPrivileges(hToken, fDisableAll, ptpNew, cbtpPrevious, ptpPrevious, pcbtpPreviousRequired)

HANDLE hToken;	/* handle of token that contains privileges	*/
BOOL fDisableAll;	/* flag for disabling all privileges	*/
PTOKEN_PRIVILEGES ptpNew;	/* address of new privilege information	*/
DWORD cbtpPrevious;	/* size of previous information buffer	*/
PTOKEN_PRIVILEGES ptpPrevious;	/* address of previous information	*/
PDWORD pcbtpPreviousRequired;	/* address of required buffer size	*/

The AdjustTokenPrivileges function adjusts privileges in the specified access token. Enabling or disabling privileges in an access token requires TOKEN_ADJUST_PRIVILEGES access.

Parameter	Description

hToken	Identifies the access token that contains the privileges to be modified.

fDisableAll	Specifies whether the function is to disable all of the token's privileges. If this value is TRUE, the privileges are disabled, and the ptpNew parameter is ignored. If it is FALSE, the function modifies privileges based on the information pointed to by the ptpNew parameter.

ptpNew	Points to a TOKEN_PRIVILEGES structure containing the privileges to be changed. If the fDisableAll parameter is FALSE, the function sets each of the token's privileges to the value of that privilege's SE_PRIVILEGE_ENABLED flag in the TOKEN_PRIVILEGES structure. If fDisableAll is TRUE, this parameter is ignored.

cbtpPrevious	Specifies the size, in bytes, of the buffer pointed to by the ptpPrevious parameter. If the ptpPrevious parameter is NULL, this parameter can be also.

ptpPrevious	Points to a buffer 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 a buffer is specified but does not contain enough space to receive the complete list of modified privileges, no privileges are changed and the function fails. In this case, the function sets the variable pointed to by the pcbtpPreviousRequired parameter to the number of bytes required to hold the complete list of modified privileges.

pcbtpPreviousRequired	Points to a variable receiving the actual number of bytes needed for the buffer pointed to by the ptpPrevious parameter. This parameter can be NULL and is ignored if ptpPrevious is NULL.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. Call GetLastError to obtain extended error information.

Comments

The information retrieved in the ptpPrevious parameter is formatted as a TOKEN_PRIVILEGES structure. This means that a pointer to the buffer can be passed as the ptpNew parameter in a subsequent call to the AdjustTokenPrivileges function, restoring the original state of the privileges.

The ptpNew parameter can list privileges to be changed that are not present in the access token. This does not affect the successful modification of the privileges in the token.

See Also

AdjustTokenGroups, GetTokenInformation, OpenProcessToken, OpenThreadToken, SetTokenInformation, TOKEN_PRIVILEGES


AllocateAndInitializeSid function
AllocateAndInitializeSid (Win32)

BOOL AllocateAndInitializeSid(psia, cSubAuthorities, dwSubAuthority0, dwSubAuthority1, dwSubAuthority2, dwSubAuthority3, dwSubAuthority4, dwSubAuthority5, dwSubAuthority6, dwSubAuthority7, lppsid)

PSID_IDENTIFIER_AUTHORITY psia;	/* address of identifier authority	*/
BYTE cSubAuthorities;	/* 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 *lppsid;	/* address of pointer to SID	*/

The AllocateAndInitializeSid function allocates and initializes a security identifier (SID) with up to eight subauthorities.

Parameter	Description

psia	Points to an SID_IDENTIFIER_AUTHORITY structure, giving the top-level identifier authority value to set in the SID.

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

lppsid	Points to a variable that receives the address of the allocated and initialized SID structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

An SID allocated with this function must be freed by using the FreeSid function.

See Also

FreeSid, GetSidIdentifierAuthority, InitializeSid, SID, SID_AND_ATTRIBUTES, SID_IDENTIFIER_AUTHORITY


AllocateLocallyUniqueId function
AllocateLocallyUniqueId (Win32)

BOOL AllocateLocallyUniqueId(pluid)

PLUID pluid;	/* address of locally unique identifier	*/

The AllocateLocallyUniqueId function allocates a locally unique identifier (LUID).

Parameter	Description

pluid	Points to a buffer that receives the allocated LUID.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, LUID


AreAllAccessesGranted function
AreAllAccessesGranted (Win32)

BOOL AreAllAccessesGranted(dwGrantedAccess, dwDesiredAccess)

DWORD dwGrantedAccess;	/* access mask for granted access rights	*/
DWORD dwDesiredAccess;	/* access mask for requested access rights	*/

The AreAllAccessesGranted function checks whether all the access rights in an access mask to be requested are present in a granted access mask.

Parameter	Description

dwGrantedAccess	Specifies the granted access mask.

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

Returns

If all the requested access rights have been granted, the return value is TRUE; otherwise, it is FALSE.

Comments

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 dwDesiredAccess parameter match the bits set in the dwGrantedAccess parameter, all requested rights have been granted.

See Also

AccessCheck, AreAnyAccessesGranted, MapGenericMask


AreAnyAccessesGranted function
AreAnyAccessesGranted (Win32)

BOOL AreAnyAccessesGranted(dwGrantedAccess, dwDesiredAccess)

DWORD dwGrantedAccess;	/* access mask for granted access rights	*/
DWORD dwDesiredAccess;	/* access mask for access rights requested	*/

The AreAnyAccessesGranted function tests whether any of a requested set of access rights are granted by a granted access mask.

Parameter	Description

dwGrantedAccess	Specifies the granted access mask.

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

Returns

If any of the requested access rights have been granted, the return value is TRUE; otherwise, it is FALSE.

Comments

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 dwDesiredAccess parameter match the bits set in the dwGrantedAccess parameter, at least one of the requested access rights has been granted.

See Also

AccessCheck, AreAllAccessesGranted, MapGenericMask


CopySid function
CopySid (Win32)

BOOL CopySid(cbDestinationSid, psidDestination, psidSource)

DWORD cbDestinationSid;	/* size of buffer for copied SID	*/
PSID psidDestination;	/* address of buffer for copied SID	*/
PSID psidSource;	/* address of source SID	*/

The CopySid function copies a security identifier (SID) to a buffer.

Parameter	Description

cbDestinationSid	Specifies the length, in bytes, of the buffer receiving the copy of the SID.

psidDestination	Points to a buffer recieving a copy of the source SID structure.

psidSource	Points to an SID structure the function copies to the buffer pointed to by the psidDestination parameter.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

An application can use the CopySid function to make a copy of an SID in an access token (in a TOKEN_GROUPS structure, for instance) to use in an access-control entry (ACE).

See Also

AllocateAndInitializeSid, EqualSid, GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, InitializeSid, IsValidSid, SID, SID_AND_ATTRIBUTES, TOKEN_GROUPS


CreatePrivateObjectSecurity function
CreatePrivateObjectSecurity (Win32)

BOOL CreatePrivateObjectSecurity(psdParent, psdCreator, lppsdNew, fContainer, hClientToken, pgm)

PSECURITY_DESCRIPTOR psdParent;	/* address of parent directory SD	*/
PSECURITY_DESCRIPTOR psdCreator;	/* address of creator SD	*/
PSECURITY_DESCRIPTOR * lppsdNew;	/* address of pointer to new SD	*/
BOOL fContainer;	/* container flag for new SD	*/
HANDLE hClientToken;	/* handle of client's access token	*/
PGENERIC_MAPPING pgm;	/* address of access-rights structure	*/

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.

Parameter	Description

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

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

fContainer	Specifies whether the new object is a container. A value of TRUE indicates the object contains other objects, such as a directory.

hClientToken	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 more information about the SecurityIdentification impersonation level, see SECURITY_IMPERSONATION_LEVEL.

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.

pgm	Points to a GENERIC_MAPPING structure that specifies the mapping from each generic right to specific rights for the object.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If a system access-control list, or SACL, is specified in the SECURITY_DESCRIPTOR specified by psdCreator, hClientToken must have SeSecurityPrivilege enabled, and the caller's token must have SeAuditPrivilege enabled. The CreatePrivateObjectSecurity function performs access/privilege checks to ensure this, and may generate audits during the process.

The CreatePrivateObjectSecurity function may send many messages to port objects. This can result in a significant delay before the function returns. Be sure to take this potential delay into account when designing an application that calls CreatePrivateObjectSecurity. An application that uses mutexes to lock structures, for example, usually seeks to avoid such potentially-long lockups.

See Also

DestroyPrivateObjectSecurity, GetPrivateObjectSecurity, GetTokenInformation, OpenProcessToken, SetPrivateObjectSecurity, GENERIC_MAPPING, SECURITY_DESCRIPTOR, SECURITY_IMPERSONATION_LEVEL


DdeImpersonateClient function
DdeImpersonateClient (Win32)

BOOL DdeImpersonateClient(hConv)

HCONV hConv;	/* handle of DDE conversation	*/

The DdeImpersonateClient function impersonates a dynamic data exchange (DDE) client application in a DDE client conversation.

Parameter	Description

hConv	Identifies the DDE client conversation to be impersonated.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


DeleteAce function
DeleteAce (Win32)

BOOL DeleteAce(pAcl, dwAceIndex)

PACL pAcl;	/* address of access-control list	*/
DWORD dwAceIndex;	/* index of ACE position in ACL	*/

The DeleteAce function deletes an ACE from an ACL.

An ACE is an access-control entry. An ACL is an access-control list.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

AddAccessAllowedAce, AddAccessDeniedAce, AddAce, AddAuditAccessAce, GetAce, GetAclInformation, ACE, ACL, ACL_SIZE_INFORMATION


DestroyPrivateObjectSecurity function
DestroyPrivateObjectSecurity (Win32)

BOOL DestroyPrivateObjectSecurity(lppsdObject)

PSECURITY_DESCRIPTOR *lppsdObject;	/* address of pointer to SD	*/

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.

Parameter	Description

lppsdObject	Points to a pointer to the SECURITY_DESCRIPTOR structure to be deleted.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CreatePrivateObjectSecurity, GetPrivateObjectSecurity, SetPrivateObjectSecurity, SECURITY_IMPERSONATION_LEVEL


DuplicateToken function
DuplicateToken (Win32)

BOOL DuplicateToken(hSourceToken, sil, hDuplicateToken)

HANDLE hSourceToken;	/* handle of token to duplicate	*/
SECURITY_IMPERSONATION_LEVEL sil;	/* impersonation level	*/
PHANDLE hDuplicateToken;	/* handle of duplicated token	*/

The DuplicateToken function creates a new access token that duplicates one already in existence.

Parameter	Description

hSourceToken	Identifies an access token opened with TOKEN_DUPLICATE access.

sil	Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that supplies the impersonation level of the new token.

hDuplicateToken	Identifies the duplicate access token when the function returns. This handle has TOKEN_IMPERSONATE and TOKEN_QUERY access to the new token.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Impersonation is the ability of a process to take on the security attributes of another process. Usually, a server process impersonates a client process to complete a task involving objects to which the client normally has no access. If a client does not have an account on the server's domain, for example, the server must impersonate the client to gain access to secured objects.

See Also

DdeImpersonateClient, ImpersonateNamedPipeClient, RevertToSelf, SECURITY_IMPERSONATION_LEVEL


EqualPrefixSid function
EqualPrefixSid (Win32)

BOOL EqualPrefixSid(psid1, psid2)

PSID psid1;	/* address of first SID to compare	*/
PSID psid2;	/* address of second SID to compare	*/

The EqualPrefixSid function tests two security-identifier (SID) prefix values for equality. An SID prefix is the entire SID except for the last subauthority value.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 given 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 an 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, SID_AND_ATTRIBUTES


EqualSid function
EqualSid (Win32)

BOOL EqualSid(psid1, psid2)

PSID psid1;	/* address of first SID to compare	*/
PSID psid2;	/* address of second SID to compare	*/

The EqualSid function tests two security identifier (SID) values for equality. Two SIDs must match exactly to be considered equal.

Parameter	Description

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.

Returns

If the SID structures are equal, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLostError function.

If either SID structure is invalid, the return value is undefined.

See Also

EqualPrefixSid, IsValidSid, SID, SID_AND_ATTRIBUTES


FindFirstFreeAce function
FindFirstFreeAce (Win32)

BOOL FindFirstFreeAce(pAcl, lplpvAce)

PACL pAcl;	/* address of access-control list	*/
LPVOID *lplpvAce;	/* address of pointer to first free byte	*/

The FindFirstFreeAce function retrieves a pointer to the first free byte in an access-control list (ACL).

Parameter	Description

pAcl	Points to an ACL structure.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetAce, GetAclInformation, ACL


FreeSid function
FreeSid (Win32)

PVOID FreeSid(psid)

PSID psid;	/* address of SID to free	*/

The FreeSid function frees a security identifier (SID) previously allocated by using the AllocateAndInitializeSid function.

Parameter	Description

psid	Points to the SID structure to free.

Returns

This function does not return a value.

See Also

AllocateAndInitializeSid, SID, SID_AND_ATTRIBUTES


GetAce function
GetAce (Win32)

BOOL GetAce(pAcl, dwAceIndex, lplpvAce)

PACL pAcl;	/* address of access-control list	*/
DWORD dwAceIndex;	/* index of ACE to retrieve	*/
LPVOID *lplpvAce;	/* address of pointer to ACE	*/

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.

Parameter	Description

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.

lplpvAce	Points to a pointer the function sets to the address of the ACE.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AddAccessAllowedAce, AddAccessDeniedAce, AddAce, AddAuditAccessAce, GetAclInformation, InitializeAcl, ACE, ACL


GetAclInformation function
GetAclInformation (Win32)

BOOL GetAclInformation(pAcl, lpvAclInfo, cbAclInfo, aclic)

PACL pAcl;	/* address of access-control list	*/
LPVOID lpvAclInfo;	/* address of ACL information	*/
DWORD cbAclInfo;	/* size of ACL information	*/
ACL_INFORMATION_CLASS aclic;	/* class of requested information	*/

The GetAclInformation function retrieves information about an access-control list (ACL).

Parameter	Description

pAcl	Points to an ACL structure. The function retrieves information about this ACL.

lpvAclInfo	Points to a buffer receiving the requested information. The structure put into the buffer depends on the information class requested in the aclic parameter.

cbAclInfo	Specifies the size, in bytes, of the buffer pointed to by the lpvAclInfo parameter.

aclic	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 lpvAclInfo parameter with an ACL_REVISION_INFORMATION structure.

If the value is AclSizeInformation, the function fills the buffer pointed to by the lpvAclInfo parameter with an ACL_SIZE_INFORMATION structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetAce, InitializeAcl, IsValidAcl, SetAclInformation, ACL, ACL_INFORMATION_CLASS, ACL_REVISION_INFORMATION, ACL_SIZE_INFORMATION


GetFileSecurity function
GetFileSecurity (Win32)

BOOL GetFileSecurity(lpszFile, si, psd, cbsd, lpcbsdRequired)

LPCTSTR lpszFile;	/* address of string for file name	*/
SECURITY_INFORMATION si;	/* requested information	*/
PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
DWORD cbsd;	/* size of security descriptor buffer	*/
LPDWORD lpcbsdRequired;	/* address of required size of buffer	*/

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.

Parameter	Description

lpszFile	Points to a null-terminated string specifying the file or directory for which security information is retrieved.

si	Specifies a SECURITY_INFORMATION structure that identifies the security information being requested.

psd	Points to a buffer that receives a copy of the security descriptor of the object specified by the lpszFile 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.

cbsd	Specifies the size, in bytes, of the buffer pointed to by the psd parameter.

lpcbsdRequired	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 cbsd parameter when the function returns, none of the security descriptor is copied to the buffer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

In order 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. Additionally, the caller must have the SE_SECURITY_NAME privilege to read the system access-control list.

See Also

GetKernelObjectSecurity, GetPrivateObjectSecurity, GetUserObjectSecurity, SetFileSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION


GetKernelObjectSecurity function
GetKernelObjectSecurity (Win32)

BOOL GetKernelObjectSecurity(hObject, si, psd, cbsd, lpcbsdRequired)

HANDLE hObject;	/* handle of object to query	*/
SECURITY_INFORMATION si;	/* requested information	*/
PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
DWORD cbsd;	/* size of buffer for security descriptor	*/
LPDWORD lpcbsdRequired;	/* address of required size of buffer	*/

The GetKernelObjectSecurity function retrieves a copy of the security descriptor protecting a kernel object.

Parameter	Description

hObject	Identifies a kernel object.

si	Specifies a SECURITY_INFORMATION structure that identifies the security information being requested.

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

cbsd	Specifies the size, in bytes, of the buffer pointed to by the psd parameter.

lpcbsdRequired	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 cbsd parameter when the function returns, none of the security descriptor is copied to the buffer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SetKernelObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION


GetLengthSid function
GetLengthSid (Win32)

DWORD GetLengthSid(psid)

PSID psid;	/* address of SID to query	*/

The GetLengthSid function returns the length, in bytes, of a valid SID structure. An SID is a security identifier.

Parameter	Description

psid	Points to the SID structure whose length is returned. The structure is assumed to be valid.

Returns

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, use the GetLastError function.

See Also

GetSidLengthRequired, GetSidSubAuthorityCount, IsValidSid, SID, SID_AND_ATTRIBUTES


GetPrivateObjectSecurity function
GetPrivateObjectSecurity (Win32)

BOOL GetPrivateObjectSecurity(ObjectDescriptor, SecurityInformation, ResultantDescriptor, DescriptorLength, ReturnLength)

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

The GetPrivateObjectSecurity retrieves information from a protected server object's security descriptor.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

An application must perform appropriate access/privilege checks and audits before calling this function.

See Also

CreatePrivateObjectSecurity, DestroyPrivateObjectSecurity, GetFileSecurity, GetKernelObjectSecurity, GetUserObjectSecurity, SetPrivateObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION


GetProcessWindowStation function
GetProcessWindowStation (Win32)

HWINSTA GetProcessWindowStation(VOID)

The GetProcessWindowStation function returns a handle of the window station associated with the calling process. This handle can be used in calls to the GetUserObjectSecurity and SetUserObjectSecurity functions.

Returns

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. Use the GetLastError function to get extended error information.

See Also

GetThreadDesktop, GetUserObjectSecurity, SetUserObjectSecurity


GetSecurityDescriptorControl function
GetSecurityDescriptorControl (Win32)

BOOL GetSecurityDescriptorControl(psd, psdc, lpdwRevision)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
PSECURITY_DESCRIPTOR_CONTROL psdc;	/* address of control structure	*/
LPDWORD lpdwRevision;	/* address of revision value	*/

The GetSecurityDescriptorControl function retrieves a security descriptor's control and revision information.

Parameter	Description

psd	Points to a SECURITY_DESCRIPTOR structure whose control and revision information the function retrieves.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL


GetSecurityDescriptorDacl function
GetSecurityDescriptorDacl (Win32)

BOOL GetSecurityDescriptorDacl(psd, lpfDaclPresent, lppAcl, lpfDaclDefaulted)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
LPBOOL lpfDaclPresent;	/* address of flag for presence of disc. ACL	*/
PACL *lppAcl;	/* address of pointer to ACL	*/
LPBOOL lpfDaclDefaulted;	/* address of flag for default disc. ACL	*/

The GetSecurityDescriptorDacl function retrieves a pointer to the discretionary access-control list (ACL) in a specified security descriptor.

Parameter	Description

psd	Points to the SECURITY_DESCRIPTOR structure containing the discretionary ACL. The function retrieves a pointer to it.

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

lppAcl	Points to a pointer to an ACL structure. If a discretionary ACL exists, the function sets the pointer pointed to by lppAcl 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 lppAcl, the security descriptor has a NULL discretionary ACL. A NULL discretionary ACL implicitly allows all access to an object.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SetSecurityDescriptorDacl, ACL, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL


GetSecurityDescriptorGroup function
GetSecurityDescriptorGroup (Win32)

BOOL GetSecurityDescriptorGroup(psd, lppsidGroup, lpfGroupDefaulted)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
PSID * lppsidGroup;	/* address of pointer to group SID	*/
LPBOOL lpfGroupDefaulted;	/* address of flag for default	*/

The GetSecurityDescriptorGroup function retrieves the primary group information from a security descriptor.

Parameter	Description

psd	Points to a SECURITY_DESCRIPTOR structure whose primary group information the function retrieves.

lppsidGroup	Points to a pointer to an SID structure identifying the primary group when the function returns. (An SID is a security identifier.) If the security descriptor does not contain a primary group, the function sets the pointer pointed to by lppsidGroup to NULL and ignores the remaining output parameter, lpfGroupDefaulted. If the security descriptor contains a primary group, the function sets the pointer pointed to by lppsidGroup to the address of the security descriptor's group SID structure and provides a valid value for the variable pointed to by lpfGroupDefaulted.

lpfGroupDefaulted	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 lppsidGroup parameter is NULL, no value is set.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SetSecurityDescriptorGroup, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SID


GetSecurityDescriptorLength function
GetSecurityDescriptorLength (Win32)

DWORD GetSecurityDescriptorLength(psd)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/

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.

Parameter	Description

psd	Points to the SECURITY_DESCRIPTOR structure whose length the function returns. The SECURITY_DESCRIPTOR structure is assumed to be valid.

Returns

If the function succeeds, the return value is the length, in bytes, of the SECURITY_DESCRIPTOR structure. If the SECURITY_DESCRIPTOR's structure is invalid, the return value is undefined.

Comments

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 function
GetSecurityDescriptorOwner (Win32)

BOOL GetSecurityDescriptorOwner(psd, lppsidOwner, lpfOwnerDefaulted)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
PSID *lppsidOwner;	/* address of pointer to owner SID	*/
LPBOOL lpfOwnerDefaulted;	/* address of flag for default	*/

The GetSecurityDescriptorOwner function retrieves the owner information from a security descriptor.

Parameter	Description

psd	Points to a SECURITY_DESCRIPTOR structure whose owner information the function retrieves.

lppsidOwner	Points to a pointer to an SID structure identifying the owner when the function returns. (An SID is a security identifier.) If the security descriptor does not contain an owner, the function sets the pointer pointed to by lppsidOwner to NULL and ignores the remaining output parameter, lpfOwnerDefaulted. If the security descriptor contains an owner, the function sets the pointer pointed to by lppsidOwner to the address of the security descriptor's owner SID structure and provides a valid value for the variable pointed to by lpfOwnerDefaulted.

lpfOwnerDefaulted	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 lppsidOwner parameter is NULL, no value is set.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SetSecurityDescriptorOwner, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SID


GetSecurityDescriptorSacl function
GetSecurityDescriptorSacl (Win32)

BOOL GetSecurityDescriptorSacl(psd, lpfSaclPresent, lppAcl, lpfSaclDefaulted)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
LPBOOL lpfSaclPresent;	/* address of flag for presence of system ACL	*/
PACL *lppAcl;	/* address of pointer to ACL	*/
LPBOOL lpfSaclDefaulted;	/* address of flag for default system ACL	*/

The GetSecurityDescriptorSacl function retrieves a pointer to the system access-control list (ACL) in a specified security descriptor.

Parameter	Description

psd	Points to the SECURITY_DESCRIPTOR structure containing the system ACL to which the function retrieves a pointer to.

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

lppAcl	Points to a pointer to an ACL structure. If a system ACL exists, the function sets the pointer pointed to by lppAcl 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 lppAcl, the security descriptor has a NULL system ACL.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SetSecurityDescriptorSacl, SACL, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL


GetSidIdentifierAuthority function
GetSidIdentifierAuthority (Win32)

PSID_IDENTIFIER_AUTHORITY GetSidIdentifierAuthority(psid)

PSID psid;	/* address of SID to query	*/

The GetSidIdentifierAuthority function returns the address of the SID_IDENTIFIER_AUTHORITY structure in a specified security identifier (SID).

Parameter	Description

psid	Points to the SID structure for which the address of the SID_IDENTIFIER_AUTHORITY structure is returned.

Returns

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, use the GetLastError function.

See Also

GetLengthSid, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, IsValidSid, SID, SID_IDENTIFIER_AUTHORITY


GetSidLengthRequired function
GetSidLengthRequired (Win32)

DWORD GetSidLengthRequired(cSubauthorities)

UCHAR cSubauthorities;	/* count of subauthorities	*/

The GetSidLengthRequired function returns the length, in bytes, of the buffer required to store an SID structure with a specified number of subauthorities.

Parameter	Description

cSubauthorities	Specifies the number of subauthorities to be stored in the SID structure.

Returns

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, SID_IDENTIFIER_AUTHORITY


GetSidSubAuthority function
GetSidSubAuthority (Win32)

PDWORD GetSidSubAuthority(psid, dwSubauthority)

PSID psid;	/* address of SID to query	*/
DWORD dwSubauthority;	/* index of subauthority to retrieve	*/

The GetSidSubAuthority function returns the address of a specified subauthority in an SID structure. The subauthority value is a relative identifier (RID). An SID is a security identifier.

Parameter	Description

psid	Points to the SID structure from which the address of a subauthority is to be returned.

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

Returns

If the function succeeds, the return value is the address of the specified SID subauthority. To get extended error information, use the GetLastError function.

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 dwSubauthority parameter is out of bounds.

See Also

GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthorityCount, IsValidSid, SID, SID_IDENTIFIER_AUTHORITY


GetSidSubAuthorityCount function
GetSidSubAuthorityCount (Win32)

PUCHAR GetSidSubAuthorityCount(psid)

PSID psid;	/* address of SID to query	*/

The GetSidSubAuthorityCount function returns the address of the field in an SID structure containing the subauthority count. An SID is a security identifier.

Parameter	Description

psid	Points to the SID structure from which a pointer to the subauthority count is returned.

Returns

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, use the GetLastError function.

See Also

GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, IsValidSid, SID, SID_AND_ATTRIBUTES, SID_IDENTIFIER_AUTHORITY


GetThreadDesktop function
GetThreadDesktop (Win32)

HDESK GetThreadDesktop(idThread)

DWORD idThread;	/* thread identifier	*/

The GetThreadDesktop function returns the handle of the desktop associated with the specified thread. This handle can be used in calls to the GetUserObjectSecurity and SetUserObjectSecurity functions.

Parameter	Description

idThread	Specifies the thread to return the desktop handle for.

Returns

If the function succeeds, the return value is the handle of the desktop associated with the specified thread.

See Also

GetCurrentThreadId, GetProcessWindowStation, GetUserObjectSecurity, SetUserObjectSecurity


GetTokenInformation function
GetTokenInformation (Win32)

BOOL GetTokenInformation(hToken, tic, lpvReturnedInformation, cbReturnedInformation, pcbReturnRequired)

HANDLE hToken;	/* handle of access token	*/
TOKEN_INFORMATION_CLASS tic;	/* type of information to retrieve	*/
LPVOID lpvReturnedInformation;	/* address of retrieved information	*/
DWORD cbReturnedInformation;	/* size of information buffer	*/
PDWORD pcbReturnRequired;	/* address of required buffer size	*/

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.

Parameter	Description

hToken	Identifies an access token from which information is retrieved.

tic	Specifies a variable of the TOKEN_INFORMATION_CLASS enumerated type identifying the type of information the function retrieves.

lpvReturnedInformation	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 tic 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.

cbReturnedInformation	Specifies the size, in bytes, of the buffer pointed to by the lpvReturnedInformation parameter.

pcbReturnRequired	Points to a variable receiving the actual number of bytes needed for the buffer pointed to by the lpvReturnedInformation parameter. If this value is larger than the value specified in the cbReturnedInformation parameter, the function fails and stores no data in the buffer.

If the value of the tic parameter is TokenDefaultDacl and the token has no default access-control list, the function sets the variable pointed to by pcbReturnRequired to zero and stores no data in the buffer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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


GetUserObjectSecurity function
GetUserObjectSecurity (Win32)

BOOL GetUserObjectSecurity(hObject, psi, psd, cbsd, lpcbsdRequired)

HANDLE hObject;	/* handle of user object	*/
PSECURITY_INFORMATION psi;	/* address of requested security information	*/
PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
DWORD cbsd;	/* size of buffer for security descriptor	*/
LPDWORD lpcbsdRequired;	/* address of required size of buffer	*/

The GetUserObjectSecurity function retrieves security information for the specified user object.

Parameter	Description

hObject	Identifies the user object for which to return security information.

psi	Points to a SECURITY_INFORMATION structure specifying the security information being requested.

psd	Points to a SECURITY_DESCRIPTOR structure in self-relative format that contains the requested information when the function returns.

cbsd	Specifies the length, in bytes, of the buffer pointed to by the psd parameter.

lpcbsdRequired	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 cbsd 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CreatePrivateObjectSecurity, GetKernelObjectSecurity, GetPrivateObjectSecurity, SetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION


ImpersonateNamedPipeClient function
ImpersonateNamedPipeClient (Win32)

BOOL ImpersonateNamedPipeClient(hNamedPipe)

HANDLE hNamedPipe;	/* handle of a named pipe	*/

The ImpersonateNamedPipeClient function impersonates a named-pipe client application.

Parameter	Description

hNamedPipe	Identifies a named pipe.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
ImpersonateSelf (Win32)

BOOL ImpersonateSelf(sil)

SECURITY_IMPERSONATION_LEVEL sil;	/* impersonation level	*/

The ImpersonateSelf function obtains an access token that impersonates the security context of the calling process. The token is assigned to the calling thread.

Parameter	Description

sil	Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that supplies the impersonation level of the new token.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


InitializeAcl function
InitializeAcl (Win32)

BOOL InitializeAcl(pAcl, cbAcl, dwAclRevision)

PACL pAcl;	/* address of access-control list	*/
DWORD cbAcl;	/* size of access-control list	*/
DWORD dwAclRevision;	/* revision level of access-control list	*/

The InitializeAcl function creates a new ACL structure. An ACL is an access-control list.

Parameter	Description

pAcl	Points to an ACL structure initialized by this function.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

AddAccessAllowedAce, AddAccessDeniedAce, AddAce, AddAuditAccessAce, DeleteAce, GetAce, GetAclInformation, IsValidAcl, SetAclInformation, ACE, ACL, ACL_INFORMATION_CLASS


InitializeSecurityDescriptor function
InitializeSecurityDescriptor (Win32)

BOOL InitializeSecurityDescriptor(psd, dwRevision)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
DWORD dwRevision;	/* revision level	*/

The InitializeSecurityDescriptor function initializes a new security descriptor.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl, SECURITY_DESCRIPTOR


InitializeSid function
InitializeSid (Win32)

BOOL InitializeSid(psid, psia, cSubauthorities)

PSID psid;	/* address of SID to initialize	*/
PSID_IDENTIFIER_AUTHORITY psia;	/* address of identifier authority	*/
BYTE cSubauthorities;	/* count of subauthorities	*/

The InitializeSid function initializes an SID structure. An SID is a security identifier.

Parameter	Description

psid	Points to an SID structure to be initialized.

psia	Points to an SID_IDENTIFIER_AUTHORITY structure to set in the SID structure.

cSubauthorities	Specifies the number of subauthorities to set in the SID. Values of the subauthority must be set separately, as described in the Comments section.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 an SID and sets its subauthority values.

See Also

GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, IsValidSid, SID, SID_AND_ATTRIBUTES, SID_IDENTIFIER_AUTHORITY


IsValidAcl function
IsValidAcl (Win32)

BOOL IsValidAcl(pAcl)

PACL pAcl;	/* address of access-control list	*/

The IsValidAcl function validates an access-control list (ACL).

Parameter	Description

pAcl	Points to an ACL structure validated by this function. This must be a non-NULL value.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

GetAclInformation, InitializeAcl, ACE, ACL


IsValidSecurityDescriptor function
IsValidSecurityDescriptor (Win32)

BOOL IsValidSecurityDescriptor(psd)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/

The IsValidSecurityDescriptor function validates a SECURITY_DESCRIPTOR structure. Validation is performed by checking the revision level of each component in the security descriptor.

Parameter	Description

psd	Points to a SECURITY_DESCRIPTOR structure that the function validates.

Returns

If the structure of the security descriptor is valid, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, InitializeSecurityDescriptor, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl, SECURITY_DESCRIPTOR


IsValidSid function
IsValidSid (Win32)

BOOL IsValidSid(psid)

PSID psid;	/* address of SID to query	*/

The IsValidSid function validates an SID structure by verifying that the revision number is within a known range and that the number of subauthorities is less than the maximum. An SID is a security identifier.

Parameter	Description

psid	Points to the SID structure to validate. This must be a non-NULL value.

Returns

If the SID structure is valid, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If psid is NULL, the application will fail with an access violation.

See Also

GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, SID, SID_AND_ATTRIBUTES, SID_IDENTIFIER_AUTHORITY


LookupAccountName function
LookupAccountName (Win32)

BOOL LookupAccountName(lpszSystem, lpszAccount, psid, lpcbSid, lpszReferencedDomain, lpcchReferencedDomain, psnu)

LPCTSTR lpszSystem;	/* address of string for system name	*/
LPCTSTR lpszAccount;	/* address of string for account name	*/
PSID psid;	/* address of security identifier	*/
LPDWORD lpcbSid;	/* address of size of security identifier	*/
LPTSTR lpszReferencedDomain;	/* address of string for referenced domain	*/
LPDWORD lpcchReferencedDomain;	/* address of size of domain string	*/
PSID_NAME_USE psnu;	/* address of SID-type indicator	*/

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.

Parameter	Description

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

lpszAccount	Points to a null-terminated string specifying the account name.

psid	Points to a buffer receiving the SID structure that corresponds to the account name pointed to by the lpszAccount parameter.

lpcbSid	Specifies the size of the buffer pointed to by the psid parameter. If the specified size is too small, the function sets this variable to the required buffer size.

lpszReferencedDomain	Points to a buffer receiving the name of the domain where the account name is found.

lpcchReferencedDomain	Specifies the size of the lpszReferencedDomain buffer in characters. If the specified size is too small, the function sets this variable to the required buffer size.

psnu	Points to an SID_NAME_USE enumerated type indicating the type of the account when the function returns.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SID, SID_AND_ATTRIBUTES, SID_NAME_USE


LookupAccountSid function
LookupAccountSid (Win32)

BOOL LookupAccountSid(lpszSystem, psid, lpszAccount, lpcchAccount, lpszReferencedDomain, lpcchReferencedDomain, psnu)

LPCTSTR lpszSystem;	/* address of string for system name	*/
PSID psid;	/* address of security identifier	*/
LPTSTR lpszAccount;	/* address of string for account name	*/
LPDWORD lpcchAccount;	/* address of size account string	*/
LPTSTR lpszReferencedDomain;	/* address of string for referenced domain	*/
LPDWORD lpcchReferencedDomain;	/* address of size domain string	*/
PSID_NAME_USE psnu;	/* address of structure for SID type	*/

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.

Parameter	Description

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

psid	Points to a SID structure for which the account name is looked up.

lpszAccount	Points to a buffer receiving a null-terminated string representing the account name corresponding to the psid parameter.

lpcchAccount	Specifies the size of the buffer pointed to by the lpszAccount parameter. If the specified size is too small, the function sets this variable to the required buffer size.

lpszReferencedDomain	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 Advanced 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 Advanced Server is a domain controller.

Some accounts are predefined by the system. The domain name returned for these accounts is BUILTIN.

lpcchReferencedDomain	Specifies the size of the buffer pointed to by the lpszReferencedDomain parameter. If the specified size is too small, the function sets this variable to the required buffer size.

psnu	Points to an SID_NAME_USE enumerated type indicating the type of the account when the function returns.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SID, SID_AND_ATTRIBUTES, SID_NAME_USE


LookupPrivilegeDisplayName function
LookupPrivilegeDisplayName (Win32)

BOOL LookupPrivilegeDisplayName(lpszSystemName, lpszProgramName, lpszDisplayName, lpcchDisplayName, lpdwLanguageId)

LPCTSTR lpszSystemName;	/* address of string specifying the system	*/
LPCTSTR lpszProgramName;	/* address of string specifying the privilege	*/
LPTSTR lpszDisplayName;	/* address of string receiving the displayable name	*/
LPDWORD lpcchDisplayName;	/* address of size of string for displayable name	*/
LPDWORD lpdwLanguageId;	/* address of language identifier	*/

The LookupPrivilegeDisplayName function retrieves a displayable name representing a specified privilege.

Parameter	Description

lpszSystemName	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 tConvention o find the displayable name on the local system.

lpszProgramName	Points to a null-terminated string specifying the name of the privilege, as defined in the WINNT.H header file. For example, this string could be SE_REMOTE_SHUTDOWN_NAME.

lpszDisplayName	Points to a buffer receiving a null-terminated string giving the privilege's displayable name. For example, if the lpszProgramName parameter is SE_REMOTE_SHUTDOWN_NAME, the displayable name is, "Force shutdown from a remote system".

lpcchDisplayName	Points to a variable specifying the size, in characters, of the lpszDisplayName 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 lpszDisplayName parameter is too small, this variable contains the required size when the function returns.

lpdwLanguageId	Points to a variable receiving the language identifier for the returned displayable name.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

LookupPrivilegeName, LookupPrivilegeValue


LookupPrivilegeName function
LookupPrivilegeName (Win32)

BOOL LookupPrivilegeName(lpszSystemName, pluid, lpszProgramName, lpcchName)

LPCTSTR lpszSystemName;	/* address of string specifying the system	*/
PLUID pluid;	/* address of locally unique identifier	*/
LPTSTR lpszProgramName;	/* address of string specifying the privilege	*/
LPDWORD lpcchName;	/* address of size of string for displayable name	*/

The LookupPrivilegeName function retrieves the name corresponding to the privilege represented on a specific system by a specified locally unique identifier (LUID).

Parameter	Description

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

pluid	Points to the locally unique identifier by which the privilege is known on the target system.

lpszProgramName	Points to a buffer receiving a null-terminated string that represents the privilege's name. For example, this string could be SE_SECURITY_NAME.

lpcchName	Points to a variable specifying the size, in characters, of the lpszProgramName 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 lpszProgramName parameter is too small, this variable contains the required size when the function returns.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
LookupPrivilegeValue (Win32)

BOOL LookupPrivilegeValue(lpszSystemName, lpszPrivilege, pluid)

LPCTSTR lpszSystemName;	/* address of string specifying the system	*/
LPCTSTR lpszPrivilege;	/* address of string specifying the privilege	*/
PLUID pluid;	/* address of locally unique identifier	*/

The LookupPrivilegeValue function retrieves the locally unique identifier (LUID) used on a specified system to locally represent the specified privilege name.

Parameter	Description

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

lpszPrivilege	Points to a null-terminated string specifying the privilege's name. For example, this string could be SE_SECURITY_NAME.

pluid	Points to a variable receiving the locally unique identifier by which the privilege is known on the system specified by the lpszSystemName parameter.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


MakeAbsoluteSD function
MakeAbsoluteSD (Win32)

BOOL MakeAbsoluteSD(psdSelf, psdAbs, lpcbsdAbsolute, paclDiscretionary, lpcbDacl, paclSystem, lpcbSacl, psidOwner, lpcbsidOwner, psidPrimaryGroup, lpcbsidPrimaryGroup)

PSECURITY_DESCRIPTOR psdSelf;	/* address self-relative SD	*/
PSECURITY_DESCRIPTOR psdAbs;	/* address of absolute SD	*/
LPDWORD lpcbsdAbsolute;	/* address of size of absolute SD	*/
PACL paclDiscretionary;	/* address of discretionary ACL	*/
LPDWORD lpcbDacl;	/* address of size of discretionary ACL	*/
PACL paclSystem;	/* address of system ACL	*/
LPDWORD lpcbSacl;	/* address of size of system ACL	*/
PSID psidOwner;	/* address of owner SID	*/
LPDWORD lpcbsidOwner;	/* address of size of owner SID	*/
PSID psidPrimaryGroup;	/* address of primary-group SID	*/
LPDWORD lpcbsidPrimaryGroup;	/* address of size of group SID	*/

The MakeAbsoluteSD function creates a security descriptor in absolute format by using a security descriptor in self-relative format as a template.

Parameter	Description

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

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

lpcbsdAbsolute	Points to a variable specifying the size of the buffer pointed to by the psdAbs parameter. If the buffer is not large enough for the security descriptor, the function fails and sets this variable to the minimum required size.

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

lpcbDacl	Points to a variable specifying the size of the buffer pointed to by the paclDiscretionary parameter. If the buffer is not large enough for the ACL, the function fails and sets this variable to the minimum required size.

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

lpcbSacl	Points to a variable specifying the size of the buffer pointed to by the paclSystem parameter. If the buffer is not large enough for the ACL, the function fails and sets this variable to the minimum required size.

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

lpcbsidOwner	Points to a variable specifying the size of the buffer pointed to by the psidOwner parameter. If the buffer is not large enough for the SID, the function fails and sets this variable to the minimum required size.

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

lpcbsidPrimaryGroup	Points to a variable specifying the size of the buffer pointed to by the psidPrimaryGroup parameter. If the buffer is not large enough for the SID, the function fails and sets this variable to the minimum required size.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, ACL, SECURITY_DESCRIPTOR, SID


MakeSelfRelativeSD function
MakeSelfRelativeSD (Win32)

BOOL MakeSelfRelativeSD(psdAbsolute, psdSelfRelative, lpcbsdSelfRelative)

PSECURITY_DESCRIPTOR psdAbsolute;	/* address of absolute SD	*/
PSECURITY_DESCRIPTOR psdSelfRelative;	/* address self-relative SD	*/
LPDWORD lpcbsdSelfRelative;	/* address of SD size	*/

The MakeSelfRelativeSD function creates a security descriptor in self-relative format by using a security descriptor in absolute format as a template.

Parameter	Description

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

psdSelfRelative	Points to a buffer the function fills with a security descriptor in self-relative format.

lpcbsdSelfRelative	Points to a variable specifying the size of the buffer pointed to by the psdSelfRelative parameter. If the buffer is not large enough for the security descriptor, the function fails and sets this variable to the minimum required size.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


MapGenericMask function
MapGenericMask (Win32)

VOID MapGenericMask(pdwAccessMask, pgm)

PDWORD pdwAccessMask;	/* address of access mask	*/
PGENERIC_MAPPING pgm;	/* address of GENERIC_MAPPING structure	*/

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.

Parameter	Description

pdwAccessMask	Points to an access mask receiving the specific and standard rights mapped from generic access rights.

pgm	Points to a GENERIC_MAPPING structure specifying a mapping of generic access types to specific and standard access types.

Returns

This function does not return a value.

Comments

After calling the MapGenericMask function, the access mask pointed to by the pdwAccessMask 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


ObjectCloseAuditAlarm function
ObjectCloseAuditAlarm (Win32)

BOOL ObjectCloseAuditAlarm(lpszSubsystem, lpvHandleId, fGenerateOnClose)

LPCTSTR lpszSubsystem;	/* address of string for subsystem name	*/
LPVOID lpvHandleId;	/* address of handle identifier	*/
BOOL fGenerateOnClose;	/* flag for audit generation	*/

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.

Parameter	Description

lpszSubsystem	Points to a null-terminated string specifying the name of the subsystem calling the function; for example, "DEBUG" or "WIN32".

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

fGenerateOnClose	Specifies a flag set by a call to the AccessCheckAndAuditAlarm or ObjectOpenAuditAlarm function when the object handle is created.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

The ObjectCloseAuditAlarm function may send many messages to port objects. This can result in a significant delay before the function returns. The design of applications calling ObjectCloseAuditAlarm can take this potential delay into account. For example, this consideration may affect the design of an application that uses mutexes to lock structures.

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, MapGenericMask, ObjectOpenAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm


ObjectOpenAuditAlarm function
ObjectOpenAuditAlarm (Win32)

BOOL ObjectOpenAuditAlarm(lpszSubsystem, lpvHandleId, lpszObjectType, lpszObject, psd, hClientToken, dwDesiredAccess, dwGrantedAccess, pps, fObjectCreation, fAccessGranted, lpfGenerateOnClose)

LPCTSTR lpszSubsystem;	/* address of string for subsystem name	*/
LPVOID lpvHandleId;	/* address of handle identifier	*/
LPTSTR lpszObjectType;	/* address of string for object type	*/
LPTSTR lpszObject;	/* address of string for object name	*/
PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
HANDLE hClientToken;	/* handle of client's access token	*/
DWORD dwDesiredAccess;	/* mask for desired access rights	*/
DWORD dwGrantedAccess;	/* mask for granted access rights	*/
PPRIVILEGE_SET pps;	/* address of privileges	*/
BOOL fObjectCreation;	/* flag for object creation	*/
BOOL fAccessGranted;	/* flag for results	*/
LPBOOL lpfGenerateOnClose;	/* address of flag for audit generation	*/

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.

Parameter	Description

lpszSubsystem	Points to a null-terminated string specifying the subsystem calling this function; for example, "DEBUG" or "WIN32".

lpvHandleId	Points to a unique 32-bit value representing the client's handle of the object. If the access is denied, this parameter is ignored.

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

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

psd	Points to the SECURITY_DESCRIPTOR structure for the object being accessed.

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

dwDesiredAccess	Specifies the desired access mask. This mask must have been previously mapped by the MapGenericMask function to contain no generic access rights.

dwGrantedAccess	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 dwGrantedAccess parameter. Examples of access-checking functions include AccessCheckAndAuditAlarm and AccessCheck.

pps	Points to a PRIVILEGE_SET structure that specifies the set of privileges required for the access attempt. This parameter can be NULL.

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

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

The ObjectOpenAuditAlarm function may send many messages to port objects. This can result in a significant delay before the function returns. The design of applications calling ObjectOpenAuditAlarm 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, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm, PRIVILEGE_SET, SECURITY_DESCRIPTOR


ObjectPrivilegeAuditAlarm function
ObjectPrivilegeAuditAlarm (Win32)

BOOL ObjectPrivilegeAuditAlarm(lpszSubsystem, lpvHandleId, hClientToken, dwDesiredAccess, pps, fAccessGranted)

LPCTSTR lpszSubsystem;	/* address of string for subsystem name	*/
LPVOID lpvHandleId;	/* address of handle identifier	*/
HANDLE hClientToken;	/* handle of client's access token	*/
DWORD dwDesiredAccess;	/* mask for desired access rights	*/
PPRIVILEGE_SET pps;	/* address of privileges	*/
BOOL fAccessGranted;	/* flag for results	*/

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.

Parameter	Description

lpszSubsystem	Points to a null-terminated string specifying the name of the subsystem calling the function; for example, "DEBUG" or "WIN32".

lpvHandleId	Points to a unique 32-bit value representing the client's handle of the object.

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

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

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


OpenProcessToken function
OpenProcessToken (Win32)

BOOL OpenProcessToken(hProcess, dwAccessMask, phToken)

HANDLE hProcess;	/* handle of process	*/
DWORD dwAccessMask;	/* desired access to process	*/
PHANDLE phToken;	/* address of handle of open access token	*/

The OpenProcessToken function opens the access token associated with a process.

Parameter	Description

hProcess	Identifies the process whose access token is opened.

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

phToken	Points to a handle identifying the newly-opened access token when the function returns.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AdjustTokenGroups, AdjustTokenPrivileges, GetTokenInformation, OpenThreadToken, SetTokenInformation, ACL


OpenThreadToken function
OpenThreadToken (Win32)

BOOL OpenThreadToken(hThread, dwAccessMask, fOpenAsSelf, phToken)

HANDLE hThread;	/* handle of thread	*/
DWORD dwAccessMask;	/* access to process	*/
BOOL fOpenAsSelf;	/* flag for process or thread security	*/
PHANDLE phToken;	/* address of handle of open access token	*/

The OpenThreadToken function opens the access token associated with a thread.

Parameter	Description

hThread	Identifies the thread whose access token is opened.

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

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

phToken	Points to a handle identifying the newly-opened access token when the function returns.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The fOpenAsSelf 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, SetTokenInformation, ACL, SECURITY_IMPERSONATION_LEVEL


PrivilegeCheck function
PrivilegeCheck (Win32)

BOOL PrivilegeCheck(hClientToken, pps, lpfResult)

HANDLE hClientToken;	/* handle of client's access token	*/
PPRIVILEGE_SET pps;	/* address of privileges	*/
LPBOOL lpfResult;	/* address of flag for result	*/

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.

Parameter	Description

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

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

lpfResult	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 pps 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, LookupPrivilegeDisplayName, LookupPrivilegeName, LookupPrivilegeValue, ObjectPrivilegeAuditAlarm, PrivilegedServiceAuditAlarm, LUID_AND_ATTRIBUTES, PRIVILEGE_SET


PrivilegedServiceAuditAlarm function
PrivilegedServiceAuditAlarm (Win32)

BOOL PrivilegedServiceAuditAlarm(lpszSubsystem, lpszService, hClientToken, pps, fAccessGranted)

LPCTSTR lpszSubsystem;	/* address of string for subsystem name	*/
LPCTSTR lpszService;	/* address of string for service name	*/
HANDLE hClientToken;	/* handle of access token	*/
PPRIVILEGE_SET pps;	/* address of privileges	*/
BOOL fAccessGranted;	/* flag for granted access rights	*/

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.

Parameter	Description

lpszSubsystem	Points to a null-terminated string specifying the name of the subsystem calling the function; such as, "DEBUG" or "WIN32".

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

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

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

The PrivilegedServiceAuditAlarm function can send many messages to port objects. This can result in a significant delay before the function returns. The design of applications calling PrivilegedServiceAuditAlarm can take this potential delay into account. For example, this consideration may affect the design of an application that uses mutexes to lock structures.

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, MapGenericMask, ObjectCloseAuditAlarm, ObjectOpenAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PRIVILEGE_SET


RevertToSelf function
RevertToSelf (Win32)

BOOL RevertToSelf(VOID)

The RevertToSelf function terminates the impersonation of a client application.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


SetAclInformation function
SetAclInformation (Win32)

BOOL SetAclInformation(pAcl, lpvAclInfo, cbAclInfo, aclic)

PACL pAcl;	/* address of access-control list	*/
LPVOID lpvAclInfo;	/* address of ACL information	*/
DWORD cbAclInfo;	/* size of ACL information	*/
ACL_INFORMATION_CLASS aclic;	/* specifies class of requested info	*/

The SetAclInformation function sets information about an access-control list (ACL).

Parameter	Description

pAcl	Points to an ACL structure. The function sets information in this ACL.

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

cbAclInfo	Specifies the size, in bytes, of the buffer pointed to by the pAclInfo parameter.

aclic	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 lpvAclInfo parameter contains an ACL_REVISION_INFORMATION structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetAclInformation, InitializeAcl, IsValidAcl, ACL, ACL_INFORMATION_CLASS, ACL_REVISION_INFORMATION


SetFileSecurity function
SetFileSecurity (Win32)

BOOL SetFileSecurity(lpszFile, si, psd)

LPCTSTR lpszFile;	/* address of string for filename	*/
SECURITY_INFORMATION si;	/* type of information to set	*/
PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/

The SetFileSecurity function sets the security of a file or directory object.

Parameter	Description

lpszFile	Points to a null-terminated string specifying the file or directory for which security is set.

si	Specifies a SECURITY_INFORMATION structure identifying the contents of the security descriptor pointed to by the psd parameter.

psd	Points to a SECURITY_DESCRIPTOR structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SetKernelObjectSecurity, SetPrivateObjectSecurity, SetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION


SetKernelObjectSecurity function
SetKernelObjectSecurity (Win32)

BOOL SetKernelObjectSecurity(hObject, si, psd)

HANDLE hObject;	/* handle of object	*/
SECURITY_INFORMATION si;	/* type of information to set	*/
PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/

The SetKernelObjectSecurity function sets the security of a kernel object. For example, this can be a process, thread, or event.

Parameter	Description

hObject	Identifies a kernel object for which security information is set.

si	Specifies a SECURITY_INFORMATION structure identifying the contents of the security descriptor pointed to by the psd parameter.

psd	Points to a SECURITY_DESCRIPTOR structure containing the new security information.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SetFileSecurity, SetPrivateObjectSecurity, SetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION


SetPrivateObjectSecurity function
SetPrivateObjectSecurity (Win32)

BOOL SetPrivateObjectSecurity(si, psdSource, lppsdTarget, pgm, hClientToken)

SECURITY_INFORMATION si;	/* type of security information	*/
PSECURITY_DESCRIPTOR psdSource;	/* address of SD to apply to object	*/
PSECURITY_DESCRIPTOR *lppsdTarget;	/* address of object's SD	*/
PGENERIC_MAPPING pgm;	/* address of access-mapping struct	*/
HANDLE hClientToken;	/* handle of client access token	*/

The SetPrivateObjectSecurity function modifies a private object's security descriptor.

Parameter	Description

si	Specifies a SECURITY_INFORMATION structure identifying the contents of the security descriptor pointed to by the psdSource parameter.

psdSource	Points to a SECURITY_DESCRIPTOR structure to be applied to the object.

lppsdTarget	Points to a pointer to a SECURITY_DESCRIPTOR structure to be altered by this function. This security descriptor must be in self-relative form.

pgm	Points to a GENERIC_MAPPING structure specifying the mapping of generic to specific and standard access types for the object.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, GetPrivateObjectSecurity, SetFileSecurity, SetKernelObjectSecurity, SetUserObjectSecurity, GENERIC_MAPPING, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SID


SetSecurityDescriptorDacl function
SetSecurityDescriptorDacl (Win32)

BOOL SetSecurityDescriptorDacl(psd, fDaclPresent, pAcl, fDaclDefaulted)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
BOOL fDaclPresent;	/* flag for presence of discretionary ACL	*/
PACL pAcl;	/* address of discretionary ACL	*/
BOOL fDaclDefaulted;	/* flag for default discretionary ACL	*/

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.

Parameter	Description

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

fDaclPresent	Specifies a flag indicating the presence of a DACL 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 pAcl and fDaclDefaulted parameters. If it is FALSE, the function clears the SE_DACL_PRESENT flag, and pAcl and fDaclDefaulted are ignored.

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 fDaclPresent flag and the pAcl parameter:

When the pACL parameter points to a discretionary ACL and the fDaclPresent flag is TRUE, a discretionary ACL is specified and it must contain access-allowed ACEs to allow access to the object.

When the pACL parameter does not point to a discretionary ACL and the fDaclPresent flag is TRUE, a NULL discretionary ACL is specified. All access is allowed.

When the pACL parameter does not point to a discretionary ACL and the fDaclPresent flag is FALSE, a discretionary ACL can be provided for the object through an inheritance or default mechanism.

See Also

GetSecurityDescriptorDacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl, ACL, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL


SetSecurityDescriptorGroup function
SetSecurityDescriptorGroup (Win32)

BOOL SetSecurityDescriptorGroup(psd, psidGroup, fGroupDefaulted)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
PSID psidGroup;	/* address of SID for group	*/
BOOL fGroupDefaulted;	/* flag for default	*/

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.

Parameter	Description

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

psidGroup	Points to an 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.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetSecurityDescriptorGroup, InitializeSecurityDescriptor, SetSecurityDescriptorDacl, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SID


SetSecurityDescriptorOwner function
SetSecurityDescriptorOwner (Win32)

BOOL SetSecurityDescriptorOwner(psd, psidOwner, fOwnerDefaulted)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
PSID psidOwner;	/* address of SID for owner	*/
BOOL fOwnerDefaulted;	/* flag for default	*/

The SetSecurityDescriptorOwner function sets the owner information of an absolute-format security descriptor. It replaces any owner information already present in the security descriptor.

Parameter	Description

psd	Points to the SECURITY_DESCRIPTOR structure whose owner is set by this function. The function replaces any existing owner with the new owner.

psidOwner	Points to an 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.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetSecurityDescriptorOwner, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorSacl, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SID


SetSecurityDescriptorSacl function
SetSecurityDescriptorSacl (Win32)

BOOL SetSecurityDescriptorSacl(psd, fSaclPresent, pAcl, fSaclDefaulted)

PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/
BOOL fSaclPresent;	/* flag for presence of system ACL	*/
PACL pAcl;	/* address of system ACL	*/
BOOL fSaclDefaulted;	/* flag for default system ACL	*/

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.

Parameter	Description

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

fSaclPresent	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 pAcl and fSaclDefaulted parameters. If it is FALSE, the function does not set the SE_SACL_PRESENT flag, and pAcl and fSaclDefaulted are ignored.

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetSecurityDescriptorSacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, ACL, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL


SetTokenInformation function
SetTokenInformation (Win32)

BOOL SetTokenInformation(hToken, tic, lpvInformation, cbInformation)

HANDLE hToken;	/* handle of access token	*/
TOKEN_INFORMATION_CLASS tic;	/* type of information to set	*/
LPVOID lpvInformation;	/* address of information to set	*/
DWORD cbInformation;	/* size of information buffer	*/

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.

Parameter	Description

hToken	Identifies the access token for which information is to be set.

tic	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 lpvInformation parameter.

lpvInformation	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 tic parameter. The following three values are valid in calls to this function:

Token Information Class	Structure Provided

TokenOwner	TOKEN_OWNER structure. TOKEN_ADJUST_DEFAULT access 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. TOKEN_ADJUST_DEFAULT access is needed to set primary group information.

TokenDefaultDacl	TOKEN_DEFAULT_DACL structure. TOKEN_ADJUST_DEFAULT access 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 lpvInformation parameter is NULL, the current default discretionary ACL is removed and no replacement is established.

cbInformation	Specifies the length, in bytes, of the buffer pointed to by lpvInformation.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, ACL, TOKEN_INFORMATION_CLASS, TOKEN_DEFAULT_DACL, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_STATISTICS


SetUserObjectSecurity function
SetUserObjectSecurity (Win32)

BOOL SetUserObjectSecurity(hObject, psi, psd)

HANDLE hObject;	/* handle of user object	*/
PSECURITY_INFORMATION psi;	/* address of security information	*/
PSECURITY_DESCRIPTOR psd;	/* address of security descriptor	*/

The SetUserObjectSecurity function sets the security of a user object. This can be, for example, a window, menu, or DDE conversation.

Parameter	Description

hObject	Identifies a user object for which security information is set.

psi	Points to a SECURITY_INFORMATION structure describing the security information being set.

psd	Points to a SECURITY_DESCRIPTOR structure containing the new security information.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

GetUserObjectSecurity, SetFileSecurity, SetKernelObjectSecurity, SetPrivateObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION


Security

AccessCheck	Validates a client's access rights

AccessCheckAndAuditAlarm	Validates access, generates audit and alarm

AddAccessAllowedAce	Adds ACCESS_ALLOWED_ACE to ACL

AddAccessDeniedAce	Adds ACCESS_DENIED_ACE to ACL

AddAce	Adds an ACE to an existing ACL

AddAuditAccessAce	Adds SYSTEM_AUDIT_ACE to ACL

AdjustTokenGroups	Enables/disables groups in a token

AdjustTokenPrivileges	Enables/disables token privileges

AllocateAndInitializeSid	Alloc and init SID with subauthorities

AllocateLocallyUniqueId	Allocates an LUID

AreAllAccessesGranted	Checks for all desired access

AreAnyAccessesGranted	Checks for any desired access

CopySid	Copies an SID to a buffer

CreatePrivateObjectSecurity	Allocates and initializes a protected SD

DdeImpersonateClient	DDE server impersonates client

DeleteAce	Deletes an ACE from an existing ACL

DestroyPrivateObjectSecurity	Deletes a protected server object's SD

DuplicateToken	Duplicate an access token

EqualPrefixSid	Test two SID prefixes for equality

EqualSid	Test two SID security IDs for equality

FindFirstFreeAce	Retrieves a pointer to first free ACL byte

FreeSid	Free an allocated SID

GetAce	Retrieve a pointer to an ACE in an ACL

GetAclInformation	Retrieves access-control list information

GetFileSecurity	Get file or directory security information

GetKernelObjectSecurity	Retrieve kernel object SD

GetLengthSid	Returns length of an SID

GetPrivateObjectSecurity	Retrieves protected server object SD

GetProcessWindowStation	Returns process window-station handle

GetSecurityDescriptorControl	Retrieve SD revision and control info

GetSecurityDescriptorDacl	Retrieve SD discretionary ACL

GetSecurityDescriptorGroup	Retrieve SD primary group information

GetSecurityDescriptorLength	Returns SD length

GetSecurityDescriptorOwner	Retrieve SD owner

GetSecurityDescriptorSacl	Retrieve SD system ACL

GetSidIdentifierAuthority	Return ID authority field address

GetSidLengthRequired	Returns required length of SID

GetSidSubAuthority	Returns subauthority array address

GetSidSubAuthorityCount	Return subauthority field address

GetThreadDesktop	Returns thread desktop handle

GetTokenInformation	Retrieves specified token information

GetUserObjectSecurity	Retrieve server object SD information

ImpersonateNamedPipeClient	Pipe server acts as client

ImpersonateSelf	Get impersonation token for calling process

InitializeAcl	Creates a new access-control list

InitializeSecurityDescriptor	Initializes a security descriptor

InitializeSid	Initializes an SID

IsValidAcl	Validates an access-control list

IsValidSecurityDescriptor	Validates security descriptor

IsValidSid	Validates an SID

LookupAccountName	Translates account name to SID

LookupAccountSid	Translates SID to account name

LookupPrivilegeDisplayName	Retrieves a displayable privilege name

LookupPrivilegeName	Retrieves a programmatic privilege name

LookupPrivilegeValue	Retrieves LUID for privilege name

MakeAbsoluteSD	Create absolute SD from self-relative

MakeSelfRelativeSD	Create self-relative SD from absolute

MapGenericMask	Map generic access to specific/standard

ObjectCloseAuditAlarm	Generate audit/alarm when object is deleted

ObjectOpenAuditAlarm	Generate audit/alarm when object is accessed

ObjectPrivilegeAuditAlarm	Generate audit/alarm on privileged operation

OpenProcessToken	Open process token object

OpenThreadToken	Open thread token object

PrivilegeCheck	Test client security context for privileges

PrivilegedServiceAuditAlarm	Audit/alarm on privileged system service

RevertToSelf	Stop impersonation

SetAclInformation	Sets information in an ACL

SetFileSecurity	Sets file or directory security

SetKernelObjectSecurity	Sets kernel object security

SetPrivateObjectSecurity	Modifies existing SD

SetSecurityDescriptorDacl	Sets DACL information

SetSecurityDescriptorGroup	Sets SD primary group information

SetSecurityDescriptorOwner	Sets SD owner

SetSecurityDescriptorSacl	Sets SACL information

SetTokenInformation	Sets various token information

SetUserObjectSecurity	Sets security-descriptor values


ChangeServiceConfig function
ChangeServiceConfig (Win32)

BOOL ChangeServiceConfig(schService, fdwServiceType, fdwStartType, fdwErrorControl, lpszBinaryPathName, lpszLoadOrderGroup, lpszDependencies, lpszServiceStartName, lpszPassword, lpszDisplayName)

SC_HANDLE schService;	/* handle of service	*/
DWORD fdwServiceType;	/* type of service	*/
DWORD fdwStartType;	/* when to start service	*/
DWORD fdwErrorControl;	/* severity if service fails to start	*/
LPCTSTR lpszBinaryPathName;	/* address of service binary file name	*/
LPCTSTR lpszLoadOrderGroup;	/* address of load ordering group name	*/
LPDWORD lpdwTagID;	/* address of variable to get tag identifier	*/
LPCTSTR lpszDependencies;	/* address of array of dependency names	*/
LPCTSTR lpszServiceStartName;	/* address of account name of service	*/
LPCTSTR lpszPassword;	/* address of password for service account	*/
LPCTSTR lpszDisplayName;	/* address of display name	*/

The ChangeServiceConfig function changes the configuration parameters of a service.

Parameter	Description

schService	Identifies the service. This handle is returned by the OpenService or CreateService function and must have SERVICE_CHANGE_CONFIG access.

fdwServiceType	Specifies the type of service. This value can be SERVICE_NO_CHANGE if the existing service type is not modified, or one of the following values can be specified:

Type	Meaning

SERVICE_WIN32_OWN_PROCESS	Specifies a service that runs in its own Win32 process.

SERVICE_WIN32_SHARE_PROCESS	Specifies a service that shares a Win32 process with other services.

SERVICE_KERNEL_DRIVER	Specifies a Windows NT device driver.

SERVICE_FILE_SYSTEM_DRIVER	Specifies a Windows NT file system driver.

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

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

lpszBinaryPathName	Points 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.

lpszLoadOrderGroup	Points 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 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 these 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.

lpdwTagID	Points to a 32-bit variable that receives a unique tag value for this service in the group specified in the lpszLoadOrderGroup 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 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.

lpszDependencies	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, 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.

lpszServiceStartName	Points to a null-terminated string. If NULL is specified, the name is not modified. 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 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.

lpszPassword	Points to a null-terminated string that contains the password to the account name specified by the lpszServiceStartName 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.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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.

Comments

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 lpszDisplayName, the changes do not take effect until the service is stopped.

See Also

CreateService, QueryServiceConfig


CloseServiceHandle function
CloseServiceHandle (Win32)

BOOL CloseServiceHandle(schSCObject)

SC_HANDLE schSCObject;	/* handle of service or service control manager database	*/

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.

Parameter	Description

schSCObject	Identifies the service control manager database or the service object to close.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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.

Comments

The CloseServiceHandle function does not destroy the service control manager object referred to by the handle. An service control manager object cannot be destroyed. A service object can be destroyed by calling the DeleteService function.

See Also

CreateService, DeleteService, OpenSCManager, OpenService


ControlService function
ControlService (Win32)

BOOL ControlService(schService, fdwControl, lpssServiceStatus)

SC_HANDLE schService;	/* handle of service	*/
DWORD fdwControl;	/* control code	*/
LPSERVICE_STATUS lpssServiceStatus;	/* address of service status structure	*/

The ControlService function sends a control code to a Win32 service.

Parameter	Description

schService	Identifies the service. This handle is returned by the OpenService or CreateService function. The access required for this handle depends on the fdwControl code requested.

fdwControl	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 schService handle must have SERVICE_USER_DEFINE_CONTROL access, and the service defines the action associated with the control code.

Value	Meaning

SERVICE_CONTROL_STOP

Requests the service to stop. The schService handle must have SERVICE_STOP access.

SERVICE_CONTROL_PAUSE

Requests the service to pause. The schService handle must have SERVICE_PAUSE_CONTINUE access.

SERVICE_CONTROL_CONTINUE

Requests the paused service to resume. The schService 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 schService handle must have SERVICE_INTERROGATE access.

SERVICE_CONTROL_SHUTDOWN

The ControlService function fails if this control code is specified.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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.

Comments

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


CreateService function
CreateService (Win32)

SC_HANDLE CreateService(schSCManager, lpszServiceName, fdwDesiredAccess, fdwServiceType, fdwStartType, fdwErrorControl, lpszBinaryPathName, lpszLoadOrderGroup, lpdwTagID, lpszDependencies, lpszServiceStartName, lpszPassword)

SC_HANDLE schSCManager;	/* handle of service control manager database	*/
LPCTSTR lpszServiceName;	/* address of name of service to start	*/
LPCTSTR lpszDisplayName;	/* address of display name	*/
DWORD fdwDesiredAccess;	/* type of access to service	*/
DWORD fdwServiceType;	/* type of service	*/
DWORD fdwStartType;	/* when to start service	*/
DWORD fdwErrorControl;	/* severity if service fails to start	*/
LPCTSTR lpszBinaryPathName;	/* address of name of binary file	*/
LPCTSTR lpszLoadOrderGroup;	/* address of name of load ordering group	*/
LPDWORD lpdwTagID;	/* address of variable to get tag identifier	*/
LPCTSTR lpszDependencies;	/* address of array of dependency names	*/
LPCTSTR lpszServiceStartName;	/* address of account name of service	*/
LPCTSTR lpszPassword;	/* address of password for service account	*/

The CreateService function creates a service object and adds it to the specified service control manager database.

Parameter	Description

schSCManager	Identifies the service control manager database. The OpenSCManager function returns this handle which must have SC_MANAGER_CREATE_SERVICE access.

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

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

fdwDesiredAccess	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_DEFINE_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 fdwDesiredAccess 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, 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, SERVICE_INTERROGATE, and SERVICE_USER_DEFINED_CONTROL.

fdwServiceType	Specifies the type of service. One of the following values is specified.

Type	Meaning

SERVICE_WIN32_OWN_PROCESS	Specifies a service that runs in its own Win32 process.

SERVICE_WIN32_SHARE_PROCESS	Specifies a service that shares a Win32 process with other services.

SERVICE_KERNEL_DRIVER	Specifies a Windows NT device driver.

SERVICE_FILE_SYSTEM_DRIVER	Specifies a Windows NT file system driver.

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

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

lpszBinaryPathName	Points to a null-terminated string that contains the fully qualified path to the service binary file.

lpszLoadOrderGroup	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 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 these 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.

lpdwTagID	Points to a 32-bit variable that receives a unique tag value for this service in the group specified in the lpszLoadOrderGroup 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 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.

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

lpszServiceStartName	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, in which case, the lpszPassword 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.

lpszPassword	Points to a null-terminated string that contains the password to the account name specified by the lpszServiceStartName 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.

Returns

If the function succeeds, the return value is a handle to the service; otherwise, it is NULL. To get extended error information, use the GetLastError function.

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 lpszServiceStartName parameter does not exist.

ERROR_SERVICE_EXISTS

The specified service already exist in this database.

Comments

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\<lpszServiceName> where lpszServiceName 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

EnumDependentServices

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

CloseServiceHandle, OpenSCManager, StartService


DeleteService function
DeleteService (Win32)

BOOL DeleteService(schService)

SC_HANDLE schService;	/* handle of service	*/

The DeleteService function marks the specified service for deletion from the service control manager database.

Parameter	Description

schService	Identifies the service. This handle is returned by the OpenService or CreateService function, and it must have DELETE access.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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.

Comments

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

The service control manager deletes the service by deleting the service key and its subkeys from the registry.

See Also

CloseServiceHandle, ControlService, CreateService, OpenService


EnumDependentServices function
EnumDependentServices (Win32)

BOOL EnumDependentServices(schService, fdwServiceState, lpessServices, cbBufSize, lpcbBytesNeeded, lpdwServicesReturned)

SC_HANDLE schService;	/* handle of service	*/
DWORD fdwServiceState;	/* state of services to enumerate	*/
LPENUM_SERVICE_STATUS lpessServices;	/* address of service status buffer	*/
DWORD cbBufSize;	/* size of service status buffer	*/
LPDWORD lpcbBytesNeeded;	/* address of variable for bytes needed	*/
LPDWORD lpdwServicesReturned;	/* address of variable for number returned	*/

The EnumDependentServices function enumerates services that depend on another specified service; that is, the specified service must be running before they can run. The name and status of each dependent service are provided.

Parameter	Description

schService	Identifies the service. This handle is returned by the OpenService or CreateService function, and it must have SERVICE_ENUMERATE_DEPENDENTS access.

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

lpessServices	Points to an array of ENUM_SERVICE_STATUS structures where the name and service status information for each dependent service is returned. The order of the services in this array is the reverse of the start order. In other words, the dependent service that would be started last is listed first.

cbBufSize	Specifies the size, in bytes, of the buffer pointed to by the lpessServices parameter.

lpcbBytesNeeded	Points to a variable that receives the number of bytes needed to return the remaining service entries.

lpdwServicesReturned	Points to a variable that receives the number of service entries returned.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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

There are more service entries than would fit into the lpessServices buffer. The actual number of service entries written to lpessServices is returned in the lpdwServicesReturned parameter. The number of bytes required to get the remaining entries is returned in the lpcbBytesNeeded parameter.

Comments

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 lpessServices buffer to stop the dependent services in the proper order.

See Also

CreateService, EnumServicesStatus, OpenService


EnumServicesStatus function
EnumServicesStatus (Win32)

BOOL EnumServicesStatus(schSCManager, fdwServiceType, fdwServiceState, lpessServices, cbBufSize, lpcbBytesNeeded, lpdwServicesReturned, lpdwResumeHandle)

SC_HANDLE schSCManager;	/* handle of service control manager database	*/
DWORD fdwServiceType;	/* type of services to enumerate	*/
DWORD fdwServiceState;	/* state of services to enumerate	*/
LPENUM_SERVICE_STATUS lpessServices;	/* address of service status buffer	*/
DWORD cbBufSize;	/* size of service status buffer	*/
LPDWORD lpcbBytesNeeded;	/* address of variable for bytes needed	*/
LPDWORD lpdwServicesReturned;	/* address of variable for number returned	*/
LPDWORD lpdwResumeHandle;	/* address of variable for next entry	*/

The EnumServicesStatus function enumerates services in the specified service control manager database. The name and status of each service are provided.

Parameter	Description

schSCManager	Identifies the service control manager database. The OpenSCManager function returns this handle which must have SC_MANAGER_ENUMERATE_SERVICE access.

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

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

lpessServices	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 lpessServices parameter.

lpcbBytesNeeded	Points to a variable that receives the number of bytes needed to return the remaining service entries.

lpdwServicesReturned	Points to a variable that receives the number of service entries returned.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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 lpessServices buffer. The actual number of service entries written to lpessServices is returned in the lpdwServicesReturned parameter. The number of bytes required to get the remaining entries is returned in the lpcbBytesNeeded parameter. The remaining services can be enumerated by additional calls to EnumServicesStatus with the lpdwResumeHandle parameter indicating the next service to read.

See Also

EnumDependentServices, OpenSCManager


GetServiceDisplayName function
GetServiceDisplayName (Win32)

BOOL GetServiceDisplayName(hSCManager, lpServiceName, lpDisplayName, lpcchBuffer)

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

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.

Parameter	Description

hSCManager	Handle to a machine's service control manager database. This parameter is an RPC server handle as returned by OpenSCManager.

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.

Returns

If the functions succeeds, the return value is TRUE; otherwise, it is FALSE. Call GetLastError for further error information.

Comments

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 applet 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 services'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 function
GetServiceKeyName (Win32)

BOOL GetServiceKeyName(hSCManager, lpDisplayName, lpServiceName, lpcchBuffer)

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

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.

Parameter	Description

hSCManager	Handle to a machine's service control manager database. This parameter is an 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 lpServiceName. 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 into it. When the function returns, the DWORD pointed to by lpcchBuffer contains the size in characters of the service name, excluding the NULL terminator.

Returns

If the functions succeeds, the return value is TRUE; otherwise, it is FALSE. Call GetLastError for further error information.

Comments

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 applet 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 services'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


Handler function
Handler (Win32)

VOID Handler(fdwControl)

DWORD fdwControl;	/* requested control code	*/

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.

Parameter	Description

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, if the eventlog service needs to clear a dirty bit in the files that it maintains, or if the server service needs to shutdown so that network connections made when the system is in the shut down 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.

Returns

This function does not return a value.

Comments

When a Win32 service is started, its Service Main 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


LockServiceDatabase function
LockServiceDatabase (Win32)

SC_LOCK LockServiceDatabase(schSCManager)

SC_HANDLE schSCManager;	/* handle of service control manager database	*/

The LockServiceDatabase function locks a specified database.

Parameter	Description

schSCManager	Identifies the service control manager database. The OpenSCManager function returns this handle, which must have SC_MANAGER_LOCK access.

Returns

If the function succeeds, the return value is a lock to the specified service control manager database; otherwise, it is NULL. To get extended error information, use the GetLastError function.

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.

Comments

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


NotifyBootConfigStatus function
NotifyBootConfigStatus (Win32)

BOOL NotifyBootConfigStatus(fBootAcceptable)

BOOL fBootAcceptable;	/* indicates acceptability of boot configuration	*/

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 configuation; an unacceptable configuration triggers a system reboot.

Parameter	Description

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

Returns

If fBootAcceptable is FALSE, the function does not return.

If the last-known-good configuration was successfully saved, the return value is TRUE.

If an error occurs, the return value is FALSE. Call GetLastError to determine the cause of the failure.

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 deal with the configuration registry.

Value	Meaning

ERROR_ACCESS_DENIED	The specified handle was not opened with SC_MANAGER_MODIFY_BOOT_CONFIG access.

Comments

The NotifyBootConfigStatus function is used to save the configuration that a running system was booted from. This is a useful thing to do once the configuration has been checked and found to be acceptable. In this way, the latest acceptable modifications to the configuration are saved away as the last-known-good configuration.

If the boot configuration is found to be unacceptable, this function can be called to instigate a reboot with the existing last-known-good configuration. This function can only be called by a process running in the LocalSystem or the Administrator's security context.


OpenService function
OpenService (Win32)

SC_HANDLE OpenService(schSCManager, lpszServiceName, fdwDesiredAccess)

SC_HANDLE schSCManager;	/* handle of service control manager database	*/
LPCTSTR lpszServiceName;	/* address of name of service to start	*/
DWORD fdwDesiredAccess;	/* type of access to service	*/

The OpenService function opens a handle to an existing service.

Parameter	Description

schSCManager	Identifies the service control manager database. The OpenSCManager function returns this handle.

lpszServiceName	Points to a null-terminated string that names the service to open. 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 forward-slash (/), back-slash (\), comma, and space are invalid service name characters.

fdwDesiredAccess	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_DEFINE_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 fdwDesiredAccess 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, 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, SERVICE_INTERROGATE, and SERVICE_USER_DEFINED_CONTROL.

Returns

If the function succeeds, the return value is a handle to the service; otherwise, it is NULL. To get extended error information, use the GetLastError function.

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

Comments

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


OpenSCManager function
OpenSCManager (Win32)

SC_HANDLE OpenSCManager(lpszMachineName, lpszDatabaseName, fdwDesiredAccess)

LPCTSTR lpszMachineName;	/* address of machine name string	*/
LPCTSTR lpszDatabaseName;	/* address of database name string	*/
DWORD fdwDesiredAccess;	/* type of access	*/

The OpenSCManager function establishes a connection to the service control manager on the specified machine and opens the specified database.

Parameter	Description

lpszMachineName	Points to a null-terminated string that names the target machine. If the pointer is NULL or if it points to an empty string, the function connects to the service control manager on the local machine.

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

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

Returns

If the function succeeds, the return value is a handle to the specified service control manager database; otherwise, it is NULL. To get extended error information, use the GetLastError function.

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

Comments

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 OpenSCManager. It can be closed by calling the CloseServiceHandle function.

See Also

CloseServiceHandle, CreateService, EnumServicesStatus, LockServiceDatabase, OpenService, QueryServiceLockStatus


QueryServiceConfig function
QueryServiceConfig (Win32)

BOOL QueryServiceConfig(schService, lpqscServConfig, cbBufSize, lpcbBytesNeeded)

SC_HANDLE schService;	/* handle of service	*/
LPQUERY_SERVICE_CONFIG lpqscServConfig;	/* address of service config. structure	*/
DWORD cbBufSize;	/* size of service configuration buffer	*/
LPDWORD lpcbBytesNeeded;	/* address of variable for bytes needed	*/

The QueryServiceConfig function retrieves the configuration parameters of the specified service.

Parameter	Description

schService	Identifies the service. This handle is returned by the OpenService or CreateService function, and it must have SERVICE_QUERY_CONFIG access.

lpqscServConfig	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 lpqscServConfig parameter.

lpcbBytesNeeded	Points to a variable that receives the number of bytes needed to return all the configuration information.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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 lpqscServConfig buffer. The number of bytes required to get all the information is returned in the lpcbBytesNeeded parameter. Nothing is written to the lpqscServConfig buffer.

ERROR_INVALID_HANDLE	The specified handle is invalid.

Comments

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 is an exception to this. When the DisplayName is changed, it takes effect immediately regardless of whether the service is running.

The lpqscServConfig 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, QueryServiceObjectSecurity, QueryServiceStatus


QueryServiceLockStatus function
QueryServiceLockStatus (Win32)

BOOL QueryServiceLockStatus(schSCManager, lpqslsLockStat, cbBufSize, lpcbBytesNeeded)

SC_HANDLE schSCManager;	/* handle of svc. ctrl. mgr. database	*/
LPQUERY_SERVICE_LOCK_STATUS lpqslsLockStat;	/* address of lock status structure	*/
DWORD cbBufSize;	/* size of service configuration buffer	*/
LPDWORD lpcbBytesNeeded;	/* address of variable for bytes needed	*/

The QueryServiceLockStatus function retrieves the lock status of the specified service control manager database.

Parameter	Description

schSCManager	Identifies the service control manager database. The OpenSCManager function returns this handle, which must have SC_MANAGER_QUERY_LOCK_STATUS access.

lpqslsLockStat	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 lpqslsLockStat parameter.

lpcbBytesNeeded	Points to a variable that receives the number of bytes needed to return all the lock status information.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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 lpqslsLockStat buffer. The number of bytes required to get all the information is returned in the lpcbBytesNeeded parameter. Nothing is written to the lpqslsLockStat buffer.

ERROR_INVALID_HANDLE

The specified handle is invalid.

Comments

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 lpqslsLockStat 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, UnlockServiceDatabase


QueryServiceObjectSecurity function
QueryServiceObjectSecurity (Win32)

BOOL QueryServiceObjectSecurity(schService, fdwSecurityInfo, psdSecurityDesc, cbBufSize, lpcbBytesNeeded, )

SC_HANDLE schService;	/* handle of service	*/
SECURITY_INFORMATION fdwSecurityInfo;	/* type of security information requested	*/
PSECURITY_DESCRIPTOR psdSecurityDesc;	/* address of security descriptor	*/
DWORD cbBufSize;	/* size of security descriptor buffer	*/
LPDWORD lpcbBytesNeeded;	/* address of variable for bytes needed	*/

The QueryServiceObjectSecurity function retrieves a copy of the security descriptor protecting a service object.

Parameter	Description

schService	Identifies the service. This handle is returned by the OpenService or CreateService function, and it must have READ_CONTROL access.

fdwSecurityInfo	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 SeSecurityPrivilege privilege.

psdSecurityDesc	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 psdSecurityDesc parameter.

lpcbBytesNeeded	Points to a variable that receives the number of bytes needed to return all the requested security descriptor information.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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 psdSecurityDesc buffer. The number of bytes required to get all the information is returned in the lpcbBytesNeeded parameter. Nothing is written to the psdSecurityDesc buffer.

ERROR_INVALID_PARAMETER

The specified security information is invalid.

Comments

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, SetServiceObjectSecurity, SECURITY_DESCRIPTOR, SID


QueryServiceStatus function
QueryServiceStatus (Win32)

BOOL QueryServiceStatus(schService, lpssServiceStatus)

SC_HANDLE schService;	/* handle of service	*/
LPSERVICE_STATUS lpssServiceStatus;	/* address of service status structure	*/

The QueryServiceStatus function retrieves the current status of the specified service.

Parameter	Description

schService	Identifies the service. This handle is returned by the OpenService or the CreateService function, and it must have SERVICE_QUERY_STATUS access.

lpssServiceStatus	Points to a SERVICE_STATUS structure in which the status information is returned.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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.

Comments

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, SetServiceStatus


RegisterServiceCtrlHandler function
RegisterServiceCtrlHandler (Win32)

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandler(lpszServiceName, lpHandlerProc)

LPCTSTR lpszServiceName;	/* address of name of service	*/
LPHANDLER_FUNCTION lpHandlerProc;	/* address of handler function	*/

The RegisterServiceCtrlHandler function registers a function to handle service control requests for a service.

Parameter	Description

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

Returns

If the function succeeds, the return value is a service status handle; otherwise, it is zero. To get extended error information, use the GetLastError function.

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.

Comments

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


ServiceMain function
ServiceMain (Win32)

VOID ServiceMain(dwArgc, lpszArgv)

DWORD dwArgc;	/* number of arguments	*/
LPTSTR *lpszArgv;	/* address of array of argument string pointers	*/

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.

Parameter	Description

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.

Returns

This function does not return a value.

Comments

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, StartServiceCtrlDispatcher


SetServiceStatus function
SetServiceStatus (Win32)

BOOL SetServiceStatus(sshServiceStatus, lpssServiceStatus)

SERVICE_STATUS_HANDLE sshServiceStatus;	/* service status handle	*/
LPSERVICE_STATUS lpssServiceStatus;	/* address of status structure	*/

The SetServiceStatus function updates the service control manager's status information for the calling service.

Parameter	Description

sshServiceStatus	Specifies a handle to the service control manager's status information structure for the current service. This handle is returned by the RegisterServiceCtrlHandler function.

lpssServiceStatus	Points to the SERVICE_STATUS structure the contains the latest status information for the calling service.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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.

Comments

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

RegisterServiceCtrlHandler, SERVICE_STATUS


SetServiceObjectSecurity function
SetServiceObjectSecurity (Win32)

BOOL SetServiceObjectSecurity(schService, fdwSecurityInfo, psdSecurityDesc, )

SC_HANDLE schService;	/* handle of service	*/
SECURITY_INFORMATION fdwSecurityInfo;	/* type of security information requested	*/
PSECURITY_DESCRIPTOR psdSecurityDesc;	/* address of security descriptor	*/

The SetServiceObjectSecurity function sets the security descriptor of a service object.

Parameter	Description

schService	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 fdwSecurityInfo parameter.

fdwSecurityInfo	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 schService 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 schService 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 schService 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 SeSecurityPrivilege privilege.

psdSecurityDesc	Points to a SECURITY_DESCRIPTOR structure containing the new security information.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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.

Comments

The SetServiceObjectSecurity function sets the specified portions of the service object's security descriptor, based on the information specified in the psdSecurityDesc buffer. This function replaces any or all of the security information associated with the service object, according to the flags set in the fdwSecurityInfo 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, SID


StartService function
StartService (Win32)

BOOL StartService(schService, dwNumServiceArgs, *lpszServiceArgs)

SC_HANDLE schService;	/* handle of service	*/
DWORD dwNumServiceArgs;	/* number of arguments	*/
LPCTSTR *lpszServiceArgs;	/* address of array of argument string pointers	*/

The StartService function starts the execution of a service.

Parameter	Description

schService	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 lpszServiceArgs array. If lpszServiceArgs is NULL, this parameter can be zero.

lpszServiceArgs	Points to an array of pointers that point to null-terminated argument strings passed to a Win32 service. Driver services do not receive these arguments. If no arguments are passed to the service being started, this parameter can be NULL. The new 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 lpszServiceArgs array.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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.

Comments

When a driver service is started, the StartService function does not return until the device driver is done initializing.

When a Win32 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.

For a Win32 service, 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.

This function cannot be called from within a service.

See Also

ControlService, CreateService, OpenService, QueryServiceStatus


StartServiceCtrlDispatcher function
StartServiceCtrlDispatcher (Win32)

BOOL StartServiceCtrlDispatcher(lpsteServiceTable)

LPSERVICE_TABLE_ENTRY lpsteServiceTable;	/* address of service table	*/

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.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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_DATA	The specified dispatch table contains entries that are not in the proper format.

Comments

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 lpsteServiceTable 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, RegisterServiceCtrlHandler, ServiceMain


UnlockServiceDatabase function
UnlockServiceDatabase (Win32)

BOOL UnlockServiceDatabase(sclLock)

SC_LOCK sclLock;	/* service control manager database lock to be released	*/

The UnlockServiceDatabase function unlocks a service control manager database by releasing the specified lock.

Parameter	Description

sclLock	Specifies a lock obtained from a previous call to the LockServiceDatabase function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

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


Service Control Manager

ChangeServiceConfig	Changes service configuration parameters

CloseServiceHandle	Close Service Control Manager object

ControlService	Send a control to a service

CreateService	Create a service object

DeleteService	Remove service from SC Manager database

EnumDependentServices	Enumerate services dependent on device

EnumServicesStatus	Enumerate services in SC manager database

GetServiceDisplayName	Obtains a service's display name

GetServiceKeyName	Obtains a service's registry key name

Handler	Control handler function of a service

LockServiceDatabase	Lock specified SC Manager database

NotifyBootConfigStatus	Notifies/responds to acceptability of boot configuration

OpenService	Open an existing service

OpenSCManager	Connect to service control manager

QueryServiceConfig	Get service configuration parameters

QueryServiceLockStatus	Get service database lock status

QueryServiceObjectSecurity	Get service object security descriptor

QueryServiceStatus	Get service status

RegisterServiceCtrlHandler	Register service control request handler

ServiceMain	Main function of a service

SetServiceStatus	Update service status to SC Manager

SetServiceObjectSecurity	Modify service object security descriptor

StartService	Start running a service

StartServiceCtrlDispatcher	Connect thread as dispatch thread

UnlockServiceDatabase	Unlock specified database


DragAcceptFiles function
DragAcceptFiles (Win32)

VOID DragAcceptFiles(hWnd, fAccept)

HWND hWnd;	/* handle of the registering window	*/
BOOL fAccept;	/* acceptance option	*/

The DragAcceptFiles function registers whether a window accepts dropped files.

Parameter	Description

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.

Returns

This function does not return a value.

Comments

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


DragFinish function
DragFinish (Win32)

VOID DragFinish(hDrop)

HDROP hDrop;	/* handle of memory to free	*/

The DragFinish function releases memory that Windows allocated for use in transferring filenames to the application.

Parameter	Description

hDrop	Identifies the structure describing dropped files. This handle is retrieved from the wParam parameter of the WM_DROPFILES message.

Returns

This function does not return a value.

See Also

WM_DROPFILES


DragQueryFile function
DragQueryFile (Win32)

UINT DragQueryFile(hDrop, iFile, lpszFile, cb)

HDROP hDrop;	/* handle of structure for dropped files	*/
UINT iFile;	/* index of file to query	*/
LPTSTR lpszFile;	/* buffer for returned filename	*/
UINT cb;	/* size of buffer for filename	*/

The DragQueryFile function retrieves the filenames of dropped files.

Parameter	Description

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.

cb	Specifies the size, in characters, of the lpszFile buffer.

Returns

When the function copies a filename to the buffer, the return value is a count of the characters copied. If the index value is 0xFFFF, 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 buffer address is NULL, the return value is the required size, in characters, of the buffer.

See Also

DragQueryPoint, WM_DROPFILES


DragQueryPoint function
DragQueryPoint (Win32)

BOOL DragQueryPoint(hDrop, lppt)

HDROP hDrop;	/* handle of structure for dropped file	*/
LPPOINT lppt;	/* address of structure for mouse coordinates	*/

The DragQueryPoint function retrieves the position of the mouse pointer at the time a file was dropped.

Parameter	Description

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.

Returns

If the drop occurred in the client area of the window, the return value is TRUE; otherwise, it is FALSE.

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


ExtractAssociatedIcon function
ExtractAssociatedIcon (Win32)

HICON ExtractAssociatedIcon(hInst, lpIconPath, lpiIcon)

HINSTANCE hInst;	/* application instance handle	*/
LPTSTR lpIconPath;	/* path and filename of file for which icon is wanted	*/
LPWORD lpiIcon;	/* pointer to icon index	*/

The ExtractAssociatedIcon function returns the handle of an indexed icon found in a file or an icon found in an associated executable file.

Parameter	Description

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.

Returns

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.

Comments

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 function
ExtractIcon (Win32)

HICON ExtractIcon(hInst, lpszExeName, nIconIndex)

HINSTANCE hInst;	/* instance handle	*/
LPCTSTR lpszExeName;	/* filename of file with icon	*/
UINT nIconIndex;	/* index of icon to extract	*/

The ExtractIcon function retrieves the handle of an icon from the given executable file, dynamic-link library (DLL), or icon file.

Parameter	Description

hInst	Identifies the instance of the application calling the function.

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

Returns

If the function succeeds, the return value is the handle of 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.


FindExecutable function
FindExecutable (Win32)

HINSTANCE FindExecutable(lpszFile, lpszDir, lpszResult)

LPCTSTR lpszFile;	/* address of string for filename	*/
LPCTSTR lpszDir;	/* address of string for default directory	*/
LPTSTR lpszResult;	/* address of buffer for string for executable file on return	*/

The FindExecutable function retrieves the name and handle of the executable (.EXE) file associated with the given filename.

Parameter	Description

lpszFile	Points to a null-terminated string specifying a filename. This can be a document or executable file.

lpszDir	Points to a null-terminated string specifying the default directory.

lpszResult	Points 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 lpszFile parameter.

Returns

If the function succeeds, the return value is the instance handle of the executable file associated with the specified filename. (This handle could also be the handle of a dynamic data exchange [DDE] server application.) If there is an error, the return value is less than or equal to 32. The possible error values are listed in the following Comments section.

Comments

When FindExecutable returns, the lpszResult parameter may contain the path to the DDE server started if no server responds to a request to initiate a DDE conversation.

The FindExecutable function returns 31 if there is no association for the specified file type. Following are the other possible error values:

Value	Meaning

0	The 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).

See Also

ShellExecute


ShellAbout function
ShellAbout (Win32)

int ShellAbout (hWnd, szApp, szOtherStuff, hIcon)

HWND hWnd;	/* handle of parent window	*/
LPCTSTR szApp;	/* title bar and first line text	*/
LPCTSTR szOtherStuff;	/* other dialog text	*/
HICON hIcon;	/* icon to display	*/

The ShellAbout function displays a Shell About dialog.

Parameter	Description

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 and on the first line of the dialog after the text "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 NT."

szOtherStuff	Points to text that the function displays in the dialog after the version and copyright information.

hIcon	Identifies an icon that the function displays in the dialog. If this parameter is NULL, the function displays the Microsoft Windows NT icon.

Returns

If the function succeeds in displaying the dialog, the return value is TRUE; otherwise the return value is FALSE.

Comments

Please note that the ShellAbout function dialog uses text and a default icon that are specific to Windows NT.

An example of a Shell About dialog can be seen by selecting Program Manager's About Program Manager command.


ShellExecute function
ShellExecute (Win32)

HINSTANCE ShellExecute(hwnd, lpszOp, lpszFile, lpszParams, lpszDir, wShowCmd)

HWND hwnd;	/* handle of parent window	*/
LPCTSTR lpszOp;	/* address of string for operation to perform	*/
LPCTSTR lpszFile;	/* address of string for filename	*/
LPTSTR lpszParams;	/* address of string for executable-file parameters	*/
LPCTSTR lpszDir;	/* address of string for default directory	*/
INT wShowCmd;	/* whether file is shown when opened	*/

The ShellExecute function opens or prints the given file.

Parameter	Description

hwnd	Identifies the parent window. This window receives any message boxes an application produces (for example, for error reporting).

lpszOp	Points to a null-terminated string specifying the operation to perform. This parameter can be "open" or "print". If this parameter is NULL, "open" is the default value.

lpszFile	Points to a null-terminated string specifying the file to open.

lpszParams	Points to a null-terminated string specifying parameters passed to the application when the lpszFile parameter specifies an executable (.EXE) file. If lpszFile specifies a document file, the lpsz Params parameter is NULL.

lpszDir	Points to a null-terminated string specifying the default directory.

wShowCmd	Specifies whether the application is shown when it is opened. If the lpszFile parameter specifies a document file, this parameter is zero.

Returns

If the function succeeds, the return value is the instance handle of the application that was run. (This handle could also be the handle of a dynamic data exchange [DDE] server application.) If there is an error, the return value is less than or equal to 32. The possible error values are listed in the following Comments section.

Comments

The file specified by the lpszFile parameter can be a document file or an executable file. If it is a document file, this function opens or prints it, depending on the value of the lpszOp parameter. If it is an executable file, this function opens it, even if lpszOp specifies PRINT.

The ShellExecute function returns 31 if there is no association for the specified file type or if there is no association for the specified action within the file type. The following error values specific to the ShellExecute function have been defined:

Value	Meaning

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_NOASSOC	There is no application associated with the given filename extension.

SE_ERR_SHARE	A sharing violation occurred.

Following are the other possible error values:

Value	Meaning

0	The 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).

See Also

FindExecutable


Shell Library

DragAcceptFiles	Registers whether a windows accepts dropped files

DragFinish	Releases memory allocated for dropping files

DragQueryFile	Retrieves filename of dropped file

DragQueryPoint	Retrieves mouse position at file drop

ExtractAssociatedIcon	Obtains icon handle from file or associated executable

ExtractIcon	Retrieves handle of icon from executable file

FindExecutable	Retrieves name and handle of program for a file

ShellAbout	Displays a Shell About dialog

ShellExecute	Opens or prints specified file


AbortPrinter function
AbortPrinter (Win32)

BOOL AbortPrinter(hPrinter)

HANDLE hPrinter;	/* handle of printer object	*/

The AbortPrinter function deletes a printer's spool file if the printer is configured for spooling.

Parameter	Description

hPrinter	Identifies the printer from which the spool file is deleted.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If the printer is not configured for spooling, this function has no effect.

The handle hPrinter is returned by the OpenPrinter function.

See Also

OpenPrinter


AddForm function
AddForm (Win32)

BOOL AddForm(hPrinter, cLevel, pForm)

HANDLE hPrinter;	/* handle of printer object	*/
DWORD cLevel;	/* data-structure level	*/
LPBYTE pForm;	/* address of data structure	*/

The AddForm function adds a form to the list of available forms that can be selected for the given printer.

Parameter	Description

hPrinter	Identifies the printer that supports printing with the specified form.

cLevel	Specifies the version of the structure to which pForm points. This value must be 1.

pForm	Points to a FORM_INFO_1 structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The handle hPrinter 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, OpenPrinter


AddJob function
AddJob (Win32)

BOOL AddJob(hPrinter, cLevel, pData, cbBuf, pcbNeeded)

HANDLE hPrinter;	/* handle of printer object	*/
DWORD cLevel;	/* data-structure level	*/
LPBYTE pData;	/* address of data-structure array	*/
DWORD cbBuf;	/* count of bytes in array	*/
LPDWORD pcbNeeded;	/* address of variable that contains count of bytes required	*/

The AddJob function returns a full path and filename of a file that can be used to store a print job.

Parameter	Description

hPrinter	Identifies the printer for which the print job is intended.

cLevel	Specifies the version of the structure to which pData points. This value must be 1.

pData	Points to an ADDJOB_INFO_1 structure.

cbBuf	Specifies the size, in bytes, of the buffer pointed to by pData.

pcbNeeded	Points to a variable that will be updated with the number of bytes copied or the number of bytes required. If cbBuf is less than the required number of bytes, pcbNeeded specifies the number of bytes required; if cbBuf is large enough, pcbNeeded specifies the number of bytes copied.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The filename returned in the ADDJOB_INFO_1 structure can be opened with the CreateFile function. Once the file is opened, data can be written to the file by calling the WriteFile function.

The job identifier returned in the ADDJOB_INFO_1 structure can be passed to the SetJob and ScheduleJob functions in order to control the print job.

See Also

OpenPrinter, ScheduleJob, SetJob


AddMonitor function
AddMonitor (Win32)

BOOL AddMonitor (pName, Level, pMonitors)

LPTSTR pName;	/* address of server name	*/
DWORD Level;	/* monitor info structure level	*/
LPBYTE pMonitors;	/* address of monitor info structure	*/

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.

Parameter	Description

pName	Points 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	Points to a MONITOR_INFO_2 structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Before an application calls this 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 function
AddPort (Win32)

BOOL AddPort(lpszName, hwnd, lpszMonitorName)

LPTSTR lpszName;	/* address of a server name	*/
HWND hwnd;	/* handle of parent window	*/
LPTSTR lpszMonitorName;	/* address of a monitor name	*/

The AddPort function adds the name of a port to the list of supported ports.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server to which the port is connected. If this string is NULL, the port is local.

hwnd	Identifies the parent window of the AddPort dialog box.

lpszMonitorName	Points to a null-terminated string that specifies the monitor associated with the port.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The monitor name specified in lpszMonitorName can be retrieved by calling the EnumMonitors function.

An application can determine which ports are currently supported by calling the EnumPorts function.

See Also

EnumMonitors, EnumPorts


AddPrinter function
AddPrinter (Win32)

HANDLE AddPrinter(lpszName, dwLevel, lpbPrinter)

LPTSTR lpszName;	/* address of server name	*/
DWORD dwLevel;	/* printer info structure level	*/
LPBYTE lpbPrinter;	/* address of structure	*/

The AddPrinter function adds a printer to the list of supported printers for a specified server.

Parameter	Description

lpszName	Points 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.

dwLevel	Specifies the version of the structure to which lpbPrinter points. This value must be 2.

lpbPrinter	Points to a PRINTER_INFO_2 structure. The pPrinterName, pPortName, and pDriverName members of this structure must be set before calling this function.

Returns

If the function succeeds, the return value is the handle of a new printer object; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The following list identifies the members of the PRINTER_INFO_2 structure that can be set before this function is called.

Attributes

DefaultPriority

pComment

pDatatype

pDevMode

pLocation

pParameters

pPrintProcessor

Priority

pSecurityDescriptor

pSepFile

pShareName

StartTime

UntilTime

The following list identifies the members of the PRINTER_INFO_2 structure that are reserved for use by the GetPrinter function; these members must not be set before calling AddPrinter:

Status

cJobs

AveragePPM

If pSecurityDescriptor is NULL, the system assigns a default security decriptor 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).

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.

See Also

DeletePrinter, GetPrinter, PrinterProperties, SetPrinter, PRINTER_INFO_2


AddPrinterConnection function
AddPrinterConnection (Win32)

BOOL AddPrinterConnection (pName)

LPTSTR pName;	/* address of printer name	*/

The AddPrinterConnection function adds a connection to the specified printer for the current user.

Parameter	Description

pName	Points to a null-terminated string that specifies the name of a printer that the current user wishes to establish a connection to.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. Call GetLastError to obtain extended error information.

Comments

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, 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


AddPrinterDriver function
AddPrinterDriver (Win32)

BOOL AddPrinterDriver(lpszName, dwLevel, lpbDriverInfo)

LPTSTR lpszName;	/* address of server name	*/
DWORD dwLevel;	/* printer info structure level	*/
LPBYTE lpbDriverInfo;	/* address of structure	*/

The AddPrinterDriver function installs a local or remote printer driver and links the configuration, data, and driver files.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server on which the driver should be installed. If the driver will be installed locally, this string should be NULL.

dwLevel	Specifies the version of the structure to which lpbDriverInfo points. This value must be 2.

lpbDriverInfo	Points to a DRIVER_INFO_2 structure.

If the pEnvironment member of the DRIVER_INFO_2 structure is NULL,  the current environment of the caller/client (not of the destination/server) is used.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Before an application calls this 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

EnumPrinterDrivers, GetPrinterDriverDirectory


AddPrintProcessor function
AddPrintProcessor (Win32)

BOOL AddPrintProcessor(lpszServer, lpszEnvir, lpszPath, lpszPPName)

LPTSTR lpszServer;	/* address of server name	*/
LPTSTR lpszEnvir;	/* address of environment name	*/
LPTSTR lpszPath;	/* address of path	*/
LPTSTR lpszPPName;	/* address of print-processor name	*/

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.

Parameter	Description

lpszServer	Points to a null-terminated string that specifies the name of the server on which the print processor should be installed. If this pointer is NULL, the print processor is installed locally.

lpszEnvir	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 string is NULL, the current environment of the caller/client (not of the destination/server) is used.

lpszPath	Points 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.

lpszPPName	Points to a null-terminated string that specifies the name of the print processor.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Before calling this 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 function
AddPrintProvidor (Win32)

BOOL AddPrintProvidor (pName, Level, pProvidorInfo)

LPTSTR pName;	/* address of server name	*/
DWORD Level;	/* providor info structure level	*/
LPBYTE pProvidorInfo;	/* address of providor info structure	*/

The AddPrintProvidor function installs a local printer providor and links the configuration, data, and providor files. Future releases of Windows NT may allow remote installation of printer providors.

Parameter	Description

pName	Points to a null-terminated string that specifies the name of the server on which the providor should be installed. For this release of Windows NT,  providors may only be installed locally, so this string should be NULL.

Level	Specifies the version of the structure to which pProvidorInfo points. This value must be 1.

pProvidorInfo	Points to a PROVIDOR_INFO_1 structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Before an application calls this function, all files required by the providor must be copied to the system32 directory.

A providor added by AddPrintProvidor may be removed by calling DeletePrintProvidor.

See Also

DeletePrintProvidor, PROVIDOR_INFO_1


AdvancedDocumentProperties function
AdvancedDocumentProperties (Win32)

LONG AdvancedDocumentProperties(hwnd, hPrinter, lpszDevName, pdmOutput, pdmInput)

HWND hwnd;	/* handle of dialog box's parent window	*/
HANDLE hPrinter;	/* handle of printer object	*/
LPTSTR lpszDevName;	/* address of driver name	*/
PDEVMODE pdmOutput;	/* address of modified device mode structure	*/
PDEVMODE pdmInput;	/* address of original device mode structure	*/

The AdvancedDocumentProperties function displays a printer-configuration dialog box for the given printer, allowing the user to configure that printer.

Parameter	Description

hwnd	Identifies the parent window of the printer-configuration dialog box.

hPrinter	Identifies a printer object.

lpszDevName	Points to a null-terminated string specifying the name of the device for which a printer-configuration dialog box should be displayed.

pdmOutput	Points 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 pdmOutput to NULL.

typedef struct _devicemode {    /* dvmd */

    TCHAR  dmDeviceName[32];

    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;

    TCHAR  dmFormName[32];

    WORD   dmUnusedPadding;

    USHORT dmBitsPerPel;

    DWORD  dmPelsWidth;

    DWORD  dmPelsHeight;

    DWORD  dmDisplayFlags;

    DWORD  dmDisplayFrequency;

} DEVMODE;

For a full description of this structure, see the <Microsoft Win32 Programmer's Reference, Volume 5>.

pdmInput	Points to a DEVMODE structure that contains the configuration data used to initialize the controls of the printer-configuration dialog box.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

An application can obtain the hPrinter parameter by calling the OpenPrinter or AddPrinter function.

An application can obtain the lpszDevName parameter by calling the GetPrinter function and examining the pPrinterName member of the PRINTER_INFO_2 structure.

See Also

GetPrinter


ClosePrinter function
ClosePrinter (Win32)

BOOL ClosePrinter(hPrinter)

HANDLE hPrinter;	/* handle of printer object	*/

The ClosePrinter function closes the given printer object.

Parameter	Description

hPrinter	Identifies the printer object to be closed.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AddPrinter, OpenPrinter


ConfigurePort function
ConfigurePort (Win32)

BOOL ConfigurePort(lpszName, hwnd, lpszPortName)

LPTSTR lpszName;	/* address of server name	*/
HWND hwnd;	/* handle of window that displays dialog box	*/
LPTSTR lpszPortName;	/* address of port name	*/

This function displays the port-configuration dialog box for the given port on the specified server.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server on which the given port exists. If this string is NULL, the port is local.

hwnd	Identifies the parent window of the port-configuration dialog.

lpszPortName	Points to a null-terminated string that specifies the name of the port to be configured.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Before calling this function, an application should call the EnumPorts function to determine valid port names.

See Also

EnumPorts


ConnectToPrinterDlg function
ConnectToPrinterDlg (Win32)

HANDLE ConnectToPrinterDlg (hwnd, Flags)

HWND hwnd;	/* parent window of dialog box	*/
DWORD Flags;	/* reserved for future use; must be zero	*/

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.

Parameter	Description

hwnd	Specifies the parent window of the dialog box.

Flags	This parameter is reserved for future use. Set it to zero.

Returns

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 without selecting a printer, the return value is NULL.

Comments

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

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, PRINTER_INFO_2


DeleteForm function
DeleteForm (Win32)

BOOL DeleteForm(hPrinter, pFormName)

HANDLE hPrinter;	/* handle of printer object	*/
LPTSTR lpszFormName;	/* address of form name	*/

The DeleteForm function removes a form name from the list of supported forms.

Parameter	Description

hPrinter	Indicates the open printer handle that this function is to be performed upon.

lpszFormName	Points to the form name to be removed.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The printer handle is obtained by calling the OpenPrinter function. This function can delete only form names that were added by using the AddForm function.

See Also

AddForm


DeleteMonitor function
DeleteMonitor (Win32)

BOOL DeleteMonitor(pName, pEnvironment, pMonitorName)

LPTSTR pName;	/* server name	*/
LPTSTR pEnvironment;	/* environment string	*/
LPTSTR pMonitorName;	/* monitor name	*/

The DeleteMonitor function removes a printer monitor added by the AddMonitor function.

Parameter	Description

pName	Points to a null-terminated string that specifies the name of the server from which the monitor is to be removed. If this string is NULL, the printer monitor will be 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", or "Windows NT Alpha_AXP"). If this string is NULL, the monitor is removed from the current environment of the caller/client (not of the destination/server).

pMonitorName	Points to a null-terminated string that specifies the name of the monitor to be removed.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AddMonitor


DeletePort function
DeletePort (Win32)

BOOL DeletePort(lpszName, hwnd, lpszPortName)

LPTSTR lpszName;	/* address of server name	*/
HWND hwnd;	/* handle of window that displays dialog box	*/
LPTSTR lpszPortName;	/* address of port name	*/

The DeletePort function displays a dialog box that allows the user to delete a port name.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server for which the port should be deleted. If this string is NULL, a local port is deleted.

hwnd	Identifies the parent window of the port-deletion dialog box.

lpszPortName	Points to a null-terminated string that specifies the name of the port that should be deleted.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

An application can retrieve the names of valid ports by calling the EnumPorts function.

This function returns an error if a printer is currently connected to the specified port.

See Also

AddPort, EnumPorts


DeletePrinter function
DeletePrinter (Win32)

BOOL DeletePrinter(hPrinter)

HANDLE hPrinter;	/* handle of printer object	*/

The DeletePrinter function deletes the given printer object.

Parameter	Description

hPrinter	Identifies a printer object that will be deleted.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 given 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 will fail with an InvalidState error.

See Also

AddPrinter, EnumPrinters,


DeletePrinterConnection function
DeletePrinterConnection (Win32)

BOOL DeletePrinterConnection (lpszName)

LPTSTR pName;	/* address of printer name	*/

The DeletePrinterConnection function deletes a connection to a printer that was established by a call to AddPrinterConnection or ConnectToPrinterDlg.

Parameter	Description

pName	Points to a null-terminated string that specifies the name of the printer connection to delete.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

This 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


DeletePrinterDriver function
DeletePrinterDriver (Win32)

BOOL DeletePrinterDriver(lpszName, lpszEnvironment, lpszDriverName)

LPTSTR lpszName;	/* address of server name	*/
LPTSTR lpszEnvironment;	/* address of environment	*/
LPTSTR lpszDriverName;	/* address of driver name	*/

The DeletePrinterDriver function removes the specified printer-driver name from the list of names of supported drivers for the given server.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server from which the driver is to be deleted. If this string is NULL, the printer-driver name will be removed locally.

lpszEnvironment	Points to a null-terminated string that specifies the environment from which the driver is to be deleted (for example, "Windows NT x86" or "Windows NT R4000"). If this string is NULL, the driver name is deleted from the current environment of the caller/client (not of the destination/server).

lpszDriverName	Points to a null-terminated string that specifies the name of the driver that should be deleted.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

This 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 function
DeletePrintProcessor (Win32)

BOOL DeletePrintProcessor (pName, pEnvironment, pPrintProcessorName)

LPTSTR pName;	/* server name	*/
LPTSTR pEnvironment;	/* environment string	*/
LPTSTR pPrintProcessorName;	/* processor name	*/

The DeletePrintProcessor function removes a printer processor added by the AddPrintProcessor function.

Parameter	Description

pName	Points to a null-terminated string that specifies the name of the server from which the processor is to be removed. If this string is NULL, the printer processor will be 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", or "Windows NT Alpha_AXP"). If this string is NULL, the processor is removed from the current environment of the caller/client (not of the destination/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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AddPrintProcessor


DeletePrintProvidor function
DeletePrintProvidor (Win32)

BOOL DeletePrintProvidor (pName, pEnvironment, pPrintProvidorName)

LPTSTR pName;	/* server name	*/
LPTSTR pEnvironment;	/* environment string	*/
LPTSTR pPrintProvidorName;	/* providor name	*/

The DeletePrintProvidor function removes a printer providor added by the AddPrintProvidor function.

Parameter	Description

pName	Points to a null-terminated string that specifies the name of the server from which the providor is to be removed. If this string is NULL, the printer providor will be removed locally.

pEnvironment	Points to a null-terminated string that specifies the environment from which the providor is to be removed (for example, "Windows NT x86", "Windows NT R4000", or "Windows NT Alpha_AXP"). If this string is NULL, the providor is removed from the current environment of the caller/client (not of the destination/server). NULL is the recommended value, as it provides maximum portability.

pPrintProvidorName	Points to a null-terminated string that specifies the name of the providor to be removed.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AddPrintProvidor


DocumentProperties function
DocumentProperties (Win32)

LONG DocumentProperties(hwnd, hPrinter, lpszDeviceName, pdmOutput, pdmInput, fMode)

HWND hwnd;	/* handle of window that displays dialog box	*/
HANDLE hPrinter;	/* handle of printer object	*/
LPTSTR pDeviceName;	/* address of device name	*/
PDEVMODE pdmOutput;	/* address of modified device mode structure	*/
PDEVMODE pdmInput;	/* address of original device mode structure	*/
DWORD fMode;	/* mode flag	*/

The DocumentProperties function displays a printer-configuration dialog box for the given printer.

Parameter	Description

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.

pdmOutput	Points to a DEVMODE structure that receives the printer configuration data specified by the user.

pdmInput	Points to a DEVMODE structure used to initialize the dialog box controls.

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 pdmInput 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 pdmInput override the printer driver's current print settings.

DM_IN_PROMPT	Input value. The function will present the printer driver's Print Setup dialog box, then change 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 will write the printer driver's current print settings, including private data, to the DEVMODE data structure specified by the pdmOutput parameter. The caller must allocate a buffer sufficiently large to contain the information. If the bit DM_OUT_BUFFER sets is clear, the pdmOutput parameter can be NULL. This value is also defined as DM_COPY.

Returns

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.

The return value is less than zero if the function fails.

Comments

The printer-object handle hPrinter can be obtained by calling the OpenPrinter function.

The string pointed to by pDeviceName can be obtained by calling the GetPrinter function.

In order to make changes to print settings that are local to an application, the application should:

Call the DocumentProperties function, specifying the DM_OUT_BUFFER value

Modify the returned DEVMODE structure

Then pass the modified DEVMODE structure back by calling the DocumentProperties function, specifying both DM_IN_BUFFER and DM_OUT_BUFFER (which are combined using the OR operator).

The DEVMODE structure returned by the second call to the DocumentProperties function can be used as an argument in a call to the CreateDC function.

An application can obtain a DEVMODE structure filled with the printer driver's initialization data by specifying DM_OUT_BUFFER. The application can then pass this structure on to the CreateDC function to set a private environment for the printer device context.

See Also

AdvancedDocumentProperties, CreateDC, GetPrinter, OpenPrinter, DEVMODE


EndDocPrinter function
EndDocPrinter (Win32)

BOOL EndDocPrinter(hPrinter)

HANDLE hPrinter;	/* handle of printer object	*/

The EndDocPrinter function ends a print job for the given printer.

Parameter	Description

hPrinter	Identifies a printer for which the print job should be ended.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

This function returns an error if the print job was not started by calling the StartDocPrinter function.


EndPagePrinter function
EndPagePrinter (Win32)

BOOL EndPagePrinter(hPrinter)

HANDLE hPrinter;	/* handle of printer object	*/

The EndPagePrinter function indicates the end of one page and the beginning of the next page.

Parameter	Description

hPrinter	Identifies the printer for which the page will be concluded.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


EnumForms function
EnumForms (Win32)

BOOL EnumForms(hPrinter, dwLevel, lpbForm, dwBuf, lpdwNeeded, lpdwReturned)

HANDLE hPrinter;	/* handle of printer object	*/
DWORD dwLevel;	/* data-structure level	*/
LPBYTE lpbForm;	/* address of data-structure array	*/
DWORD dwBuf;	/* count of bytes in buffer	*/
LPDWORD lpdwNeeded;	/* address of value for count of bytes required for array	*/
LPDWORD lpdwReturned;	/* address of value for count of bytes returned in array	*/

The EnumForms function enumerates the forms supported by the given printer.

Parameter	Description

hPrinter	Identifies the printer for which the forms should be enumerated.

dwLevel	Specifies the version of the structure to which lpbForm points. This value must be 1.

lpbForm	Points to a FORM_INFO_1 structure.

dwBuf	Specifies the size of the array to which lpbForm points.

lpdwNeeded	Points to a value that specifies the number of bytes copied to or the number of bytes required for the array to which lpbForm points. If dwBuf is too small, this value specifies the number of bytes required; otherwise, this value specifies the number of bytes copied.

lpdwReturned	Points to a value that specifies the number of FORM_INFO_1 structures copied into the array to which lpbForm points.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The printer-object handle hPrinter is normally obtained by calling the OpenPrinter function. The AddPrinter function can also be used.

See Also

AddPrinter, OpenPrinter


EnumJobs function
EnumJobs (Win32)

BOOL EnumJobs(hPrinter, dwFirstJob, dwNoJobs, dwLevel, lpbJob, dwBuf, lpdwNeeded, lpdwReturned)

HANDLE hPrinter;	/* handle of printer object	*/
DWORD dwFirstJob;	/* location of first job in print queue	*/
DWORD dwNoJobs;	/* number of jobs to enumerate	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbJob;	/* address of structure array	*/
DWORD dwBuf;	/* size of array, in bytes	*/
LPDWORD lpdwNeeded;	/* addr. of variable with no. of bytes copied (or required)	*/
LPDWORD lpdwReturned;	/* addr. of variable with no. of job info. structures copied	*/

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 given printer.

Parameter	Description

hPrinter	Identifies a printer object.

dwFirstJob	Specifies the location of the first enumerated job in the print queue. For example, a value of 10 indicates that enumeration should begin at the tenth job.

dwNoJobs	Specifies the total number of print jobs to enumerate.

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

lpbJob	Points to an array of either JOB_INFO_1 or JOB_INFO_2 structures.

dwBuf	Specifies the size, in bytes, of the array lpbJob.

lpdwNeeded	Points to a value that specifies the number of bytes copied if the function succeeds; otherwise, this value specifies the number of bytes required.

lpdwReturned	Points to a value that specifies the number of JOB_INFO_1 or JOB_INFO_2 structures that were initialized.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The handle hPrinter is obtained by calling the OpenPrinter function.

The JOB_INFO_1 structure contains general print-job data; the JOB_INFO_2 structure is much more detailed.

See Also

GetJob, OpenPrinter, SetJob, JOB_INFO_1, JOB_INFO_2


EnumMonitors function
EnumMonitors (Win32)

BOOL EnumMonitors(lpszName, dwLevel, lpbMonitors, cbBuf, lpdwNeeded, lpdwReturned)

LPTSTR lpszName;	/* address of server name	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbMonitors;	/* address of structure array	*/
DWORD cbBuf;	/* size, in bytes, of buffer	*/
LPDWORD lpdwNeeded;	/* addr. of variable with no. of bytes copied (or required)	*/
LPDWORD lpdwReturned;	/* addr. of variable with no. of job info. structures copied	*/

The EnumMonitors function initializes an array of MONITOR_INFO_1 structures with data describing the specified monitors for the given server.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server on which the monitors reside. If this string is NULL, the local monitors are enumerated.

dwLevel	Specifies the version of the structure to which lpbMonitors points. This value must be 1.

lpbMonitors	Points to an array of MONITOR_INFO_1 structures.

cbBuf	Specifies the size, in bytes, of the buffer to which lpbMonitors points.

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

lpdwReturned	Points to a value that specifies the number of MONITOR_INFO_1 structures that were returned in the array to which lpbMonitors points.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.


EnumPorts function
EnumPorts (Win32)

BOOL EnumPorts(lpszName, dwLevel, lpbPorts, cbBuf, lpdwNeeded, lpdwReturned)

LPTSTR lpszName;	/* address of server name	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbPorts;	/* address of structure array	*/
DWORD cbBuf;	/* size, in bytes, of array	*/
LPDWORD lpdwNeeded;	/* addr. of variable with no. of bytes copied (or required)	*/
LPDWORD lpdwReturned;	/* addr. of variable with no. of job info. structures copied	*/

The EnumPorts function enumerates the ports available for printing on a specified server.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server whose ports you wish to enumerate. If this string is NULL, the local ports are enumerated.

dwLevel	Specifies the version of the structure to which lpbPorts points. This value must be 1.

lpbPorts	Points to an array of PORT_INFO_1 structures that will contain data describing the available ports.

cbBuf	Specifies the size, in bytes, of the buffer to which lpbPorts points.

lpdwNeeded	Points to a value that will contain the actual, required buffer size identified by lpbPorts. If cbBuf is too small, GetLastError will indicate ERROR_INSUFFICIENT_BUFFER, and lpdwNeeded will contain the size required. If cbBuf is large enough, lpdwNeeded will contain the number of bytes that were copied.

lpdwReturned	Points to a variable that will contain the number of PORT_INFO_1 structures returned in lpbPorts.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The server doesn't need to have a printer defined for this function to work.

See Also

AddPort, DeletePort


EnumPrinterDrivers function
EnumPrinterDrivers (Win32)

BOOL EnumPrinterDrivers(lpszName, lpszEnvironment, dwLevel, lpbDriverInfo, cbBuf, lpdwNeeded, lpdwReturned)

LPTSTR lpszName;	/* address of server name	*/
LPTSTR lpszEnvironment;	/* address of environment	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbDriverInfo;	/* address of structure array	*/
DWORD cbBuf;	/* size, in bytes, of array	*/
LPDWORD lpdwNeeded;	/* addr. of variable with no. of bytes copied (or required)	*/
LPDWORD lpdwReturned;	/* addr. of variable with no. of job info. structures copied	*/

The EnumPrinterDrivers function enumerates all of the printer drivers installed on the specified printer server.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server on which the drivers should be enumerated. If this string is NULL, the local drivers are enumerated.

lpszEnvironment	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 string is NULL, the current environment of the caller/client (not of the destination/server) is used.

dwLevel	Specifies the version of the structure to which lpbDriverInfo points. This value must be 1 or 2.

lpbDriverInfo	Points to an array of DRIVER_INFO_1 or DRIVER_INFO_2 structures. One structure is created for each available driver.

cbBuf	Specifies the size, in bytes, of the buffer to which lpbDriverInfo points.

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

lpdwReturned	Points to a value that specifies the number of DRIVER_INFO_1 structures that returned in the array to which lpbDriverInfo points.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AddPrinterDriver, GetPrinterDriver


EnumPrinters function
EnumPrinters (Win32)

BOOL EnumPrinters(dwType, lpszName, dwLevel, lpbPrinters, cbBuf, lpdwNeeded, lpdwReturned)

DWORD dwType;	/* printer type or types	*/
LPTSTR lpszName;	/* name of printer object	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbPrinters;	/* printer info array	*/
DWORD cbBuf;	/* address of structure count of bytes in array	*/
LPDWORD lpdwNeeded;	/* addr. of variable with no. of bytes copied (or required)	*/
LPDWORD lpdwReturned;	/* addr. of variable with no. of printer info. structures copied	*/

The EnumPrinters function enumerates available printers, print servers, domains, or print providers.

Parameter	Description

dwType	Specifies the type of print objects that the function should enumerate. This value can be a combination of the following constants:

Value	Meaning

PRINTER_ENUM_CONNECTIONS	Enumerates the list of printers that the user has made previous connections to.

PRINTER_ENUM_LOCAL	Enumerates the locally installed printers.

PRINTER_ENUM_NAME	Enumerates the printer identified by lpszName. This can be a server, a domain, or a print provider. If lpszName is NULL, the function enumerates available print providers.

PRINTER_ENUM_NETWORK	Enumerates network printers known to the local server. This value is valid only if dwLevel is 1.

PRINTER_ENUM_REMOTE	Enumerates network printers. This value is valid only if dwLevel is 1.

PRINTER_ENUM_SHARED	Enumerates printers with the shared attribute.

lpszName	If dwLevel is 1, dwType contains PRINTER_ENUM_NAME, and lpszName is non-NULL, lpszName points to a null-terminated string that specifies the name of the object to enumerate. This can be the name of a server, a domain, or a print provider.

If dwLevel is 1, dwType contains PRINTER_ENUM_NAME, and lpszName is NULL, the function enumerates the available print providers.

If dwLevel is 1, dwType contains PRINTER_ENUM_REMOTE, and lpszName is NULL, the function enumerates the printers in the user's domain.

If dwLevel is 2, lpszName 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 local printers.

dwLevel	Specifies the version of the structure to which lpbPrinters points. This value must be 1 or 2.

lpbPrinters	Points to an array of PRINTER_INFO_1 or PRINTER_INFO_2 structures. If dwLevel is 1, the array contains PRINTER_INFO_1 structures; if dwLevel is 2, the array contains PRINTER_INFO_2 structures.

cbBuf	Specifies the size, in bytes, of the array to which lpbPrinters points.

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

lpdwReturned	Points to a value that specifies the number of PRINTER_INFO_1 or PRINTER_INFO_2 structures that the function returns in the array to which lpbPrinters points.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If EnumPrinters returns a PRINTER_INFO_1 structure in which PRINTER_ENUM_CONTAINER is set, this indicates that there is a hierarchy of printer objects. An application can enumerate the hierarchy by calling EnumPrinters again, setting lpszName 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 lpbPrinters, their pSecurityDescriptor members will be set to NULL.

An application can determine the name of the default printer by calling GetProfileString with the section name string set to "windows" and the key name string set to "device".

See Also

AddPrinter, DeletePrinter, GetPrinter, SetPrinter


EnumPrintProcessors function
EnumPrintProcessors (Win32)

BOOL EnumPrintProcessors(lpszName, lpszEnvir, dwLevel, lpbPPInfo, cbBuf, lpdwNeeded, lpdwReturned)

LPTSTR lpszName;	/* address of server name	*/
LPTSTR lpszEnvir;	/* address of environment name	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbPPInfo;	/* address of structure array	*/
DWORD cbBuf;	/* array length in bytes	*/
LPDWORD lpdwNeeded;	/* addr. of variable with no. of bytes copied (or required)	*/
LPDWORD lpdwReturned;	/* addr. of variable with no. of job info. structures copied	*/

The EnumPrintProcessors function enumerates the print processors installed on the specified server.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server on which the print processors reside. If this string is NULL, the local print processors are enumerated.

lpszEnvir	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 string is NULL, the current environment of the caller/client (not of the destination/server) is used.

dwLevel	Specifies the version of the structure to which lpbPPInfo points. This value must be 1.

lpbPPInfo	Points to an array 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 lpbPPInfo.

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

lpdwReturned	Points to a value that specifies the number of PRINTPROCESSOR_INFO_1 structures that returned in the array which lpbPPInfo points.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AddPrintProcessor


GetForm function
GetForm (Win32)

BOOL GetForm(hPrinter, lpszForm, dwLevel, lpbForm, cbBuf, lpdwNeeded)

HANDLE hPrinter;	/* handle of printer	*/
LPTSTR lpszForm;	/* address of form name	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbForm;	/* address of structure array	*/
DWORD cbBuf;	/* count of bytes in array	*/
LPDWORD lpdwNeeded;	/* addr. of variable with count of bytes retrieved (or required)	*/

The GetForm function initializes a FORM_INFO_1 structure with data describing the specified form for the given printer.

Parameter	Description

hPrinter	Identifies the printer.

lpszForm	Points to a null-terminated string that specifies the name of the form.

dwLevel	Specifies the version of the structure to which lpbForm points. This value must be 1.

lpbForm	Points to an array of bytes that receives the initialized FORM_INFO_1 structure.

cbBuf	Specifies the size, in bytes, of the array.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The handle hPrinter is obtained by calling the OpenPrinter function.

See Also

AddForm, DeleteForm


GetJob function
GetJob (Win32)

BOOL GetJob(hPrinter, dwJobId, dwLevel, lpbJob, cbBuf, lpdwNeeded)

HANDLE hPrinter;	/* handle of printer	*/
DWORD dwJobId;	/* job identifier value	*/
DWORD dwLevel;	/* data-structure level	*/
LPBYTE lpbJob;	/* address of data-structure array	*/
DWORD cbBuf;	/* count of bytes in array	*/
LPDWORD lpdwNeeded;	/* address of value that contains count of bytes retrieved (or required)	*/

The GetJob function retrieves print-job data for the given printer.

Parameter	Description

hPrinter	Identifies the printer for which the print-job data is retrieved.

dwJobId	Identifies the print job for which data should be retrieved.

dwLevel	Specifies the version of the structure to which lpbJob points. This value must be either 1 or 2.

lpbJob	Points to an array that contains either a JOB_INFO_1 or a JOB_INFO_2 structure. If dwLevel is 1, this function stores the data in a JOB_INFO_1 structure; if dwLevel is 2, this function stores the data in a JOB_INFO_2 structure.

cbBuf	Specifies the size, in bytes, of the array.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AddJob, ScheduleJob, SetJob


GetPrinter function
GetPrinter (Win32)

BOOL GetPrinter(hPrinter, dwLevel, lpbPrinter, cbBuf, lpdwNeeded)

HANDLE hPrinter;	/* handle to printer of interest	*/
DWORD dwLevel;	/* version of printer info data structure	*/
LPBYTE lpbPrinter;	/* pointer to array of bytes that receives printer info structure	*/
DWORD cbBuf;	/* size, in bytes, of array of bytes	*/
LPDWORD lpdwNeeded;	/* pointer to variable with count of bytes retrieved (or required)	*/

The GetPrinter function retrieves data for the given printer.

Parameter	Description

hPrinter	Identifies the printer for which data should be retrieved.

dwLevel	Specifies the version of the structure to which lpbPrinter points. This value must be 1, 2, or 3.

lpbPrinter	Points to an array of bytes that receives a PRINTER_INFO_1, a PRINTER_INFO_2, or a PRINTER_INFO_3 structure.

cbBuf	Specifies the size, in bytes, of the array to which lpbPrinter points.

lpdwNeeded	Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf was too small.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If the structure returned in the buffer pointed to by lpbPrinter 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 ACL

ACCESS_SYSTEM_SECURITY	System ACL

See Also

AbortPrinter, AddPrinter, ClosePrinter, DeletePrinter, EnumPrinters, OpenPrinter, SetPrinter


GetPrinterData function
GetPrinterData (Win32)

DWORD GetPrinterData(hPrinter, lpszType, lpdwType, lpbData, nSize, lpdwNeeded)

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;	/* addr. of variable with count of bytes retrieved (or required)	*/

The GetPrinterData function retrieves printer-configuration data for the given printer.

Parameter	Description

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 SetPrinterData. The GetPrinterData function 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 to which pData points.

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The printer handle hPrinter is obtained by calling the OpenPrinter function.

The function retrieves printer-configuration data set by the SetPrinter function.

See Also

OpenPrinter, SetPrinter


GetPrinterDriver function
GetPrinterDriver (Win32)

BOOL GetPrinterDriver(hPrinter, lpszEnv, dwLevel, lpbDrvInfo, cbBuf, lpdwNeeded)

HANDLE hPrinter;	/* printer object	*/
LPTSTR lpszEnv;	/* address of environment	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbDrvInfo;	/* address of structure array	*/
DWORD cbBuf;	/* size, in bytes, of array	*/
LPDWORD lpdwNeeded;	/* addr. of variable with count of bytes retrieved (or required)	*/

The GetPrinterDriver function retrieves driver data for the given printer.

Parameter	Description

hPrinter	Identifies the printer for which the driver data should be retrieved.

lpszEnv	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 string is NULL, the current environment of the caller/client (not of the destination/server) is used.

dwLevel	Specifies the version of the structure to which lpbForm points. This value must be either 1 or 2.

lpbDrvInfo	Points to either a DRIVER_INFO_1 or a DRIVER_INFO_2 structure. If dwLevel is 1, this array receives a DRIVER_INFO_1 structure; if dwLevel is 2, this array receives a DRIVER_INFO_2 structure.

cbBuf	Specifies the size, in bytes, of the array at which lpbDrvInfo points.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The printer handle hPrinter should be retrieved by calling the OpenPrinter function.

The DRIVER_INFO_2 structure contains 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, EnumPrinterDrivers, LoadLibrary, OpenPrinter


GetPrinterDriverDirectory function
GetPrinterDriverDirectory (Win32)

BOOL GetPrinterDriverDirectory(lpszName, lpszEnv, dwLevel, lpbDir, cbBuf, lpdwNeeded)

LPTSTR lpszName;	/* address of server name	*/
LPTSTR lpszEnv;	/* address of environment	*/
DWORD dwLevel;	/* address of structure	*/
LPBYTE lpbDir;	/* address of structure array that receives path	*/
DWORD cbBuf;	/* size, in bytes, of array	*/
LPDWORD lpdwNeeded;	/* addr. of variable with count of bytes retrieved (or required)	*/

The GetPrinterDriverDirectory function retrieves the path of the printer-driver directory.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server on which the printer driver resides. If this string is NULL, the local driver-directory path is retrieved.

lpszEnv	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 string is NULL, the current environment of the caller/client (not of the destination/server) is used.

dwLevel	Specifies the structure level. This value must be 1.

lpbDir	Points to an array of bytes that receives the path.

cbBuf	Specifies the size of the array to which lpbDir points.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AddPrinterDriver


GetPrintProcessorDirectory function
GetPrintProcessorDirectory (Win32)

BOOL GetPrintProcessorDirectory(lpszName, lpszEnv, dwLevel, lpbProcessorDir, cbBuf, lpdwNeeded)

LPTSTR lpszName;	/* address of server name	*/
LPTSTR lpszEnv;	/* address of environment	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbProcessorDir;	/* address of structure array	*/
DWORD cbBuf;	/* size, in bytes, of array	*/
LPDWORD lpdwNeeded;	/* addr. of variable with count of bytes retrieved (or required)	*/

The GetPrintProcessorDirectory function retrieves the path for the print processor on the specified server.

Parameter	Description

lpszName	Points to a null-terminated string that specifies the name of the server. If this string is NULL, a local path is returned.

lpszEnv	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 string is NULL, the current environment of the caller/client (not of the destination/server) is used.

dwLevel	Specifies the structure level. This value must be 1.

lpbProcessorDir	Points to an array of bytes into which the path is copied.

cbBuf	Specifies the size of the buffer to which lpbProcessorDir points.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AddPrintProcessor


OpenPrinter function
OpenPrinter (Win32)

BOOL OpenPrinter(pPrinterName, phPrinter, pDefault)

LPTSTR pPrinterName;	/* address of printer or server name	*/
LPHANDLE phPrinter;	/* address of printer or server handle	*/
LPPRINTER_DEFAULTS pDefault;	/* address of printer defaults structure	*/

The OpenPrinter function retrieves a handle identifying the specified printer or print server.

Parameter	Description

pPrinterName	Points to a null-terminated string that specifies the name of the printer or print server.

phPrinter	Points to a value that receives the handle identifying the opened printer or print server object.

pDefault	Points to a PRINTER_DEFAULTS structure. This value can be NULL.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

An application can determine what permissions a client has on a print server, or obtain a handle to a print server in  order 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 ClosePrinter or WaitForPrinterChange.

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, WaitForPrinterChange, PRINTER_DEFAULTS


PrinterMessageBox function
PrinterMessageBox (Win32)

HPRINTER PrinterMessageBox (hPrinter, dwError, hwndOwner, pText, pCaption, dwType)

HANDLE hPrinter;	/* handle of printer	*/
DWORD dwError;	/* error ID	*/
HWND hwndOwner;	/* handle of owner window	*/
LPTSTR pText;	/* pointer to message box text	*/
LPTSTR pCaption;	/* pointer to message box title	*/
DWORD dwType;	/* style of message box	*/

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.

Parameter	Description

hPrinter	Identifies the printer to which the job was sent.

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

hwndOwner	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

Returns

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.

See MessageBox for a more complete list of message box return values.

See Also

MessageBox


PrinterProperties function
PrinterProperties (Win32)

BOOL PrinterProperties(hwnd, hPrinter)

hwnd hwnd;	/* handle of window in which dialog box appears	*/
HANDLE hPrinter;	/* handle of printer object	*/

The PrinterProperties function displays a printer-properties dialog box for the given printer.

Parameter	Description

hwnd	Identifies the parent window of the dialog box.

hPrinter	Identifies a printer object.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

OpenPrinter


ReadPrinter function
ReadPrinter (Win32)

BOOL ReadPrinter(hPrinter, lpBuf, cbBuf, lpdwBytes)

HANDLE hPrinter;	/* handle of printer object	*/
LPVOID lpBuf;	/* address of array of bytes that receives data	*/
DWORD cbBuf;	/* size, in bytes, of array	*/
LPDWORD lpdwBytes;	/* address of variable with number of bytes retrieved	*/

The ReadPrinter function retrieves data from the given printer.

Parameter	Description

hPrinter	Identifies the printer for which to retrieve data.

lpBuf	Points to an array of bytes that receives the printer data.

cbBuf	Specifies the size, in bytes, of the buffer to which lpBuf points.

lpdwBytes	Points to a variable that receives the number of bytes of data copied into the array to which lpBuf points.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

This function returns an error if the device or the printer is not bidirectional.

See Also

OpenPrinter


ResetPrinter function
ResetPrinter (Win32)

BOOL ResetPrinter (hPrinter, pDefault)

HANDLE hPrinter;	/* printer handle	*/
LPPRINTER_DEFAULTS pDefault;	/* address of printer defaults structure	*/

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.

Parameter	Description

hPrinter	Identifies a printer.

pDefault	Points to a PRINTER_DEFAULTS structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

OpenPrinter, StartDocPrinter


ScheduleJob function
ScheduleJob (Win32)

BOOL ScheduleJob(hPrinter, dwJobID)

HANDLE hPrinter;	/* handle of printer object	*/
DWORD dwJobID;	/* job-identifier value	*/

The ScheduleJob function informs the print spooler that the specified job can be scheduled for printing.

Parameter	Description

hPrinter	Identifies the printer for which the job is scheduled.

dwJobID	Specifies the print job being scheduled.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The printer handle hPrinter is obtained by calling the OpenPrinter function.

This function should be called after an application calls the AddJob function.

See Also

AddJob, OpenPrinter


SetForm function
SetForm (Win32)

BOOL SetForm(hPrinter, lpszForm, dwLevel, lpbForm)

HANDLE hPrinter;	/* handle of printer object	*/
LPTSTR lpszForm;	/* address of form name	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbForm;	/* address of structure array	*/

The SetForm function sets the form information for the given printer.

Parameter	Description

hPrinter	Identifies the printer for which the form information is set.

lpszForm	Points to a null-terminated string specifying the form name for which the form information is set.

dwLevel	Specifies the version of the structure to which lpbForm points. This value must be 1.

lpbForm	Points to a FORM_INFO_1 structure.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The printer handle hPrinter is obtained by calling the OpenPrinter function.

See Also

OpenPrinter


SetJob function
SetJob (Win32)

BOOL SetJob(hPrinter, dwJob, dwLevel, lpbJob, dwCommand)

HANDLE hPrinter;	/* handle of printer object	*/
DWORD dwJob;	/* job-identification value	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbJob;	/* address of job info structures	*/
DWORD dwCommand;	/* job-command value	*/

The SetJob function pauses, resumes, cancels, or restarts the specified print job on the given printer. The function can also be used to set print job parameters such as the job priority, the document name, and so forth.

Parameter	Description

hPrinter	Identifies the printer.

dwJob	Specifies the print job.

dwLevel	Specifies the version of the structure to which lpbJob points. This value must be 0, 1, or 2.

lpbJob	Points to either a JOB_INFO_1 or JOB_INFO_2 structure. If dwLevel is 0, this pointer must be NULL; if dwLevel is 1, the array contains a JOB_INFO_1 structure and if dwLevel is 2, the array contains a JOB_INFO_2 structure.

dwCommand	Specifies the operation which should be performed. It can be one of the following values:

Value	Meaning

JOB_CONTROL_CANCEL	Deletes a print job.

JOB_CONTROL_PAUSE	Pauses a print job.

JOB_CONTROL_RESTART	Restarts a print job. A job can only be restarted if it was printing.

JOB_CONTROL_RESUME	Resumes a paused print job.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The SetJob function can be used to set various job parameters by supplying a pointer to a JOB_INFO_1 or JOB_INFO_2 structure that contains the necessary data.

To remove or delete all the print jobs for a particular printer, call the SetPrinter function and set the PRINTER_CONTROL_PURGE value.

The following fields of a JOB_INFO_1 or JOB_INFO_2 structure will be ignored on a call to SetJob:

JobId, pPrinterName, pMachineName, pDrivername, Size, Submitted, and Time.

A client must have PRINTER_ACCESS_ADMINISTER access permission to a printer in order to change the order of jobs on the printer.

If an application does not wish to set the job position, it should set the Position field to JOB_POSITION_UNSPECIFIED (0).

See Also

OpenPrinter, SetJob, SetPrinter


SetPrinter function
SetPrinter (Win32)

BOOL SetPrinter(hPrinter, dwLevel, lpbPrinter, dwCommand)

HANDLE hPrinter;	/* handle of printer object	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbPrinter;	/* address of array containing printer data	*/
DWORD dwCommand;	/* printer-state command	*/

The SetPrinter function sets the specified printer by pausing printing, resuming printing, or clearing all print jobs. It can also be used to set printer data.

Parameter	Description

hPrinter	Identifies the printer.

dwLevel	Specifies the version of the structure to which lpbPrinter points. This value must be 0, 2, or 3.

lpbPrinter	Points to an array of bytes that may contain printer data. If dwLevel is 0, this pointer must be NULL; if dwLevel is 2, the array contains a PRINTER_INFO_2 structure; and if dwLevel is 3, the array contains a PRINTER_INFO_3 structure.

dwCommand	Specifies the new printer state. 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 lpbPrinter 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The handle hPrinter is obtained 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 following fields of a PRINTER_INFO_2 structure will be ignored on a call to the SetPrinter function:

pServerName, pPrinterName, 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	Security Descriptor Components Modifiable

WRITE_OWNER	Owner, Primary Group

WRITE_DAC	Discretionary ACL

ACCESS_SYSTEM_SECURITY	System ACL

If the caller lacks a required permission, the SetPrinter function will fail. Those components of a security descriptor that an application does not wish to modify should be set to NULL or not present, as appropriate. If an application does not wish to modify the security descriptor, the pSecurityDescriptor member of the printer data structure should be set to NULL.

See Also

AddPrinter, GetPrinter, OpenPrinter


SetPrinterData function
SetPrinterData (Win32)

DWORD SetPrinterData(hPrinter, lpszType, dwType, lpbData, cbData)

HANDLE hPrinter;	/* handle of printer object	*/
LPTSTR lpszType;	/* address of data type	*/
DWORD dwType;	/* flag for value type	*/
LPBYTE lpbData;	/* address of array that specifies printer data	*/
DWORD cbData;	/* size, in bytes, of array	*/

The SetPrinterData function sets the configuration data for a printer.

Parameter	Description

hPrinter	Identifies the printer for which the configuration data should be set.

lpszType	Points to a null-terminated string that specifies the type of data to be set.

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 word. This is the most common format for computers running Windows NT.

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

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.

lpbData	Points to an array of bytes that contains the printer configuration data.

cbData	Specifies the size, in bytes, of the array.

Returns

If the function succeeds, the return value is ERROR_SUCCESS; otherwise it is an error value.

Comments

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, OpenPrinter


StartDocPrinter function
StartDocPrinter (Win32)

DWORD StartDocPrinter(hPrinter, dwLevel, lpbDocInfo)

HANDLE hPrinter;	/* handle of printer object	*/
DWORD dwLevel;	/* structure level	*/
LPBYTE lpbDocInfo;	/* address of structure	*/

The StartDocPrinter function informs the print spooler that a document is to be spooled for printing.

Parameter	Description

hPrinter	Identifies the printer.

dwLevel	Specifies the version of the structure to which lpbDocInfo points. This value must be 1.

lpbDocInfo	Points to a DOC_INFO_1 structure.

Returns

If the function succeeds, the return value identifies the print job; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

The printer handle hPrinter is obtained by calling the OpenPrinter function.

The return value will never be greater than ((2^ 31) - 1).

See Also

OpenPrinter


StartPagePrinter function
StartPagePrinter (Win32)

BOOL StartPagePrinter(hPrinter)

HANDLE hPrinter;	/* handle of printer object	*/

The StartPagePrinter function informs the spooler that a page is about to be printed on the given printer.

Parameter	Description

hPrinter	Identifies a printer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The printer handle hPrinter 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


WaitForPrinterChange function
WaitForPrinterChange (Win32)

DWORD WaitForPrinterChange(hPrinter, Flags)

HANDLE hPrinter;	/* handle of printer object	*/
DWORD Flags;	/* bit mask specifying changes to wait for	*/

The WaitForPrinterChange function returns when one or more requested changes occur on a printer or print server, or if the function times out.

Parameter	Description

hPrinter	Identifies the printer object to wait on.

Flags	A bit mask that specifies the changes that the application wishes to be notified of. The following values have meaning, as do the values listed in the Returns section:

Value	Meaning

PRINTER_CHANGE_PRINTER	Notify the application of any changes to a printer.

PRINTER_CHANGE_JOB	Notify the application of any changes to a job.

PRINTER_CHANGE_FORM	Notify the application of any changes to a form.

PRINTER_CHANGE_PORT	Notify the application of any changes to a port.

PRINTER_CHANGE_PRINT_PROCESSOR	Notify the application of any changes to a print processor.

PRINTER_CHANGE_PRINTER_DRIVER	Notify the application of any changes to a printer driver.

Returns

If the function succeeds, the return value is a bit mask that indicates the waited-on changes that have occurred. The following values have meaning; note that they can also be used with the function's Flags parameter:

Value	Meaning

PRINTER_CHANGE_ADD_PRINTER	A printer was added to the server.

PRINTER_CHANGE_SET_PRINTER	A printer was set.

PRINTER_CHANGE_DELETE_PRINTER	A printer was deleted.

PRINTER_CHANGE_ADD_JOB	A job was sent to a printer.

PRINTER_CHANGE_SET_JOB	A job was set.

PRINTER_CHANGE_DELETE_JOB	A job was deleted.

PRINTER_CHANGE_WRITE_JOB	Job data was written.

PRINTER_CHANGE_ADD_FORM	A form was added to the server.

PRINTER_CHANGE_SET_FORM	A form was set on the server.

PRINTER_CHANGE_DELETE_FORM	A form was deleted from the server.

PRINTER_CHANGE_ADD_PORT	A port or monitor was added to the server.

PRINTER_CHANGE_CONFIGURE_PORT	A port was configured on the server.

PRINTER_CHANGE_DELETE_PORT	A port or monitor was deleted from the server.

PRINTER_CHANGE_ADD_PRINT_PROCESSOR	A print processor was added to the server.

PRINTER_CHANGE_DELETE_PRINT_PROCESSOR	A print processor was deleted from the server.

PRINTER_CHANGE_ADD_PRINTER_DRIVER	A printer driver was added to the server.

PRINTER_CHANGE_DELETE_PRINTER_DRIVER	A printer driver was deleted from the server.

PRINTER_CHANGE_TIMEOUT	A timeout occurred.

If the function times out, the flags passed in are returned unchanged, with the PRINTER_CHANGE_TIMEOUT flag set.

If the function fails, or the printer is closed by another thread, the return value is 0. If the printer was closed, GetLastError returns ERROR_INVALID_HANDLE.

Comments

If the function is called with a handle to a printer, it will return when a change occurs on that printer. If the function is called with a handle to a server, it will return when a change occurs on that server or on a printer on the server.

To obtain detailed information about the change, an application should call the appropriate function: GetPrinter or EnumPrinters, for example. An application can also request notification of specific changes by using the smaller-grain PRINTER_CHANGE_* constants listed in this reference page's Returns section to set the Flags parameter. For example, the PRINTER_CHANGE_ADD_PRINTER bit flag constant tests for a printer being added to a print server.

Since the WaitForPrinterChange function usually does not return immediately, it should not be called on the main thread of an application. However, on a busy print server where changes are occurring continually, this function may return immediately. To guard against possible looping and excessive network traffic, applications should ensure that there is a reasonable interval between calls to the function.

See Also

OpenPrinter, ClosePrinter, GetPrinter, EnumPrinters, EnumJobs, EnumForms, EnumMonitors, EnumPrintProcessors, EnumPrinterDrivers, Sleep


WritePrinter function
WritePrinter (Win32)

BOOL WritePrinter(hPrinter, pBuf, cbBuf, lpdwWritten)

HANDLE hPrinter;	/* handle of printer object	*/
LPVOID pBuf;	/* address of array that contains printer data	*/
DWORD cbBuf;	/* size, in bytes, of array	*/
LPDWORD lpdwWritten;	/* addr. of variable with count of bytes written	*/

The WritePrinter function informs the print spooler that the specified data should be written to the given printer.

Parameter	Description

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.

lpdwWritten	Points to a value that specifies the number of bytes of data that were written to the printer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

OpenPrinter


Print Spooler

AbortPrinter	Delete printer spool file

AddForm	Add a printer form

AddJob	Start a printer job

AddMonitor	Adds a printer monitor

AddPort	Add a printer port

AddPrinter	Creates a printer on a printer server

AddPrinterConnection	Adds connection to printer for current user

AddPrinterDriver	Copies a printer driver to a print server

AddPrintProcessor	Copies a print processor to a server

AddPrintProvidor	Adds a printer providor

AdvancedDocumentProperties	Configure printer advanced settings

ClosePrinter	Close an open printer

ConfigurePort	Configure printer port

ConnectToPrinterDlg	Displays dialog for browsing and connecting to network printers

DeleteForm	Remove printer form

DeleteMonitor	Remove printer monitor

DeletePort	Deletes a printer port

DeletePrinter	Deletes a printer on a printer server

DeletePrinterConnection	Adds a connection to a printer

DeletePrinterDriver	Remove printer driver

DeletePrintProcessor	Remove printer processor

DeletePrintProvidor	Remove printer providor

DocumentProperties	Configure printer settings

EndDocPrinter	End a print job

EndPagePrinter	End a printer page

EnumForms	Enumerate supported printer forms

EnumJobs	Get printer job information

EnumMonitors	Enumerate available monitors

EnumPorts	Enumerates available printer ports

EnumPrinterDrivers	Enumerate installed printer drivers

EnumPrinters	Enumerate available printing objects

EnumPrintProcessors	Enumerate installed print processors

GetForm	Get printer form information

GetJob	Get print-job information

GetPrinter	Get printer information

GetPrinterData	Gets printer configuration information

GetPrinterDriver	Get printer driver information

GetPrinterDriverDirectory	Get path for printer driver

GetPrintProcessorDirectory	Get path for print processor

OpenPrinter	Get handle for specified printer

PrinterMessageBox	Displays printing job error message

PrinterProperties	Modify printer properties

ReadPrinter	Read printer data

ResetPrinter	Set printer data type and device mode values

ScheduleJob	Schedule added job

SetForm	Set form information

SetJob	Set print job information

SetPrinter	Set printer information

SetPrinterData	Set printer configuration information

StartDocPrinter	Start print job

StartPagePrinter	Start a printer page

WaitForPrinterChange	Enumerate available printers

WritePrinter	Write data to printer


ABC structure
ABC (Win32)

typedef struct _ABC { /* abc */

    int     abcA;

    UINT    abcB;

    int     abcC;

} ABC;

The ABC structure contains the width of a character in a TrueType® font.

Member	Description

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.

Comments

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 structure
ABCFLOAT (Win32)

typedef struct _ABCFLOAT { /* abcf */

    FLOAT   abcfA;

    FLOAT   abcfB;

    FLOAT   abcfC;

} ABCFLOAT;

The ABCFLOAT structure contains the A, B, and C widths of a font character.

Member	Description

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.

Comments

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 structure
ACCEL (Win32)

typedef struct tagACCEL { /* accl */

    BYTE   fVirt;

    WORD   key;

    WORD   cmd;

} ACCEL;

The ACCEL structure defines an accelerator key used in an accelerator table.

Member	Description

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


ACCESS_ALLOWED_ACE structure
ACCESS_ALLOWED_ACE (Win32)

typedef struct _ACCESS_ALLOWED_ACE { /* aaace */

    ACE_HEADER Header;

    ACCESS_MASK Mask;

    DWORD SidStart;

} 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).

Member	Description

Header	Specifies an ACE_HEADER structure.

Mask	Specifies an ACCESS_MASK structure that specifies the access rights granted by this ACE.

SidStart	Specifies an SID. The access rights specified by the Mask member are granted to any subject possessing an enabled SID matching this field.

Comments

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 structure
ACCESS_DENIED_ACE (Win32)

typedef struct _ACCESS_DENIED_ACE { /* adace */

    ACE_HEADER  Header;

    ACCESS_MASK Mask;

    DWORD       SidStart;

} 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).

Member	Description

Header	Specifies an ACE_HEADER structure.

Mask	Specifies an ACCESS_MASK structure specifying the access rights explicitly denied by this ACE.

SidStart	Specifies an SID. The access rights specified by the Mask member are denied to any subject possessing an enabled SID matching this field.

Comments

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 structure
ACCESS_MASK (Win32)

typedef DWORD 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.

The bits in this value are allocated as follows:

Bits	Meaning

0 through 15	Specific rights. Contain 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:

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


ACE structure
ACE (Win32)

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.

Comments

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 structure
ACE_HEADER (Win32)

typedef struct _ACE_HEADER { /* acehdr */

    BYTE AceType;

    BYTE AceFlags;

    WORD AceSize;

} ACE_HEADER;

The ACE_HEADER structure describes the type and size of an access-control entry (ACE).

Member	Description

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.

Comments

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 structure
ACL (Win32)

typedef struct _ACL { /* acl */

    BYTE AclRevision;

    BYTE Sbz1;

    WORD AclSize;

    WORD AceCount;

    WORD Sbz2;

} 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).

Member	Description

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.

Comments

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_INFORMATION_CLASS structure
ACL_INFORMATION_CLASS (Win32)

typedef enum tagACL_INFORMATION_CLASS { /* aclic */

    AclRevisionInformation = 1,

    AclSizeInformation

} ACL_INFORMATION_CLASS;

The ACL_INFORMATION_CLASS enumerated type indicates the type of information being assigned to or retrieved from an access-control list (ACL).

See Also

GetAclInformation, SetAclInformation, ACL, ACL_REVISION_INFORMATION, ACL_SIZE_INFORMATION


ACL_REVISION_INFORMATION structure
ACL_REVISION_INFORMATION (Win32)

typedef struct _ACL_REVISION_INFORMATION {

    DWORD   AclRevision;

} ACL_REVISION_INFORMATION;

The ACL_REVISION_INFORMATION structure contains revision information about an ACL structure.

Member	Description

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 structure
ACL_SIZE_INFORMATION (Win32)

typedef struct _ACL_SIZE_INFORMATION {

    DWORD   AceCount;

    DWORD   AclBytesInUse;

    DWORD   AclBytesFree;

} ACL_SIZE_INFORMATION;

The ACL_SIZE_INFORMATION structure contains information about the size of an ACL structure.

Member	Description

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 structure
ACTION_HEADER (Win32)

typedef struct _ACTION_HEADER {

    ULONG   transport_id;

    USHORT  action_code;

    USHORT  reserved;

} ACTION_HEADER;

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

Member	Description

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, etc.

action_code	Specifies the action.

reserved	Reserved.

Comments

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 LANadapter.	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 structure
ADAPTER_STATUS (Win32)

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;

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 are required to describe the network adapters on the system.

Member	Description

adapter_address	Specifies the adapter's encoded address.

rev_major	Specifies the major software-release level. This value is 3 for IBM NetBIOS 3.x.

reserved0	Reserved. This value is always 0.

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

ti_timeouts	Specifies the number of times the DLC T1 timer expired.

reserved1	Reserved. This value is always 0.

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 structure
ADDJOB_INFO_1 (Win32)

typedef struct _ADDJOB_INFO_1 { /* aji1 */

    LPTSTR  Path;

    DWORD   JobId;

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

Member	Description

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


AUXCAPS structure
AUXCAPS (Win32)

typedef struct auxcaps_tag {

    WORD  wMid;

    WORD  wPid;

    MMVERSION  vDriverVersion;

    TCHAR  szPname[MAXPNAMELEN];

    WORD  wTechnology;

    DWORD  dwSupport;

} AUXCAPS;

The AUXCAPS structure describes the capabilities of an auxiliary output device.

Member	Description

wMid	Specifies a manufacturer identifier for the device driver for the auxiliary audio device.

wPid	Specifies a product identifier for the auxiliary audio device.

vDriverVersion	Specifies the 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	Specifies the product name in a null-terminated string.

wTechnology	Specifies the type of the auxiliary audio output. This member can be one of the following values:

Value	Meaning

AUXCAPS_AUXIN	Audio output from auxiliary input jacks

AUXCAPS_CDAUDIO	Audio output from an internal CD-ROM drive

dwSupport	Specifies optional functionality supported by the auxiliary audio device. This member can be one or both of the following values:

Value	Meaning

AUXCAPS_LRVOLUME	Supports separate left and right volume control.

AUXCAPS_VOLUME	Supports volume control.

Comments

If a device supports volume changes, the AUXCAPS_VOLUME flag is set for the dwSupport member. If a device supports separate volume changes on the left and right channels, both the AUXCAPS_VOLUME and the AUXCAPS_LRVOLUME flags are set for this member.

See Also

auxGetDevCaps


BITMAP structure
BITMAP (Win32)

typedef struct tagBITMAP {  /* bm */

   LONG   bmType;

   LONG   bmWidth;

   LONG   bmHeight;

   LONG   bmWidthBytes;

   WORD   bmPlanes;

   WORD   bmBitsPixel;

   LPVOID bmBits;

} BITMAP;

The BITMAP structure defines the type, width, height, color format, and bit values of a bitmap.

Member	Description

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.

Comments

The currently used bitmap formats 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 the GetDeviceCaps function.

Each device has a unique color format. In order to transfer a bitmap from one device to another, use the GetDIBits and SetDIBits functions.

See Also

CreateBitmapIndirect, GetDeviceCaps, GetDIBits, GetObject, SetDIBits


BITMAPCOREHEADER structure
BITMAPCOREHEADER (Win32)

typedef struct tagBITMAPCOREHEADER { /* bmch */

        DWORD   bcSize;

        WORD    bcWidth;

        WORD    bcHeight;

        WORD    bcPlanes;

        WORD    bcBitCount;

} BITMAPCOREHEADER;

The BITMAPCOREHEADER structure contains information about the dimensions and color format of a device-independent bitmap (DIB).

Member	Description

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.

Comments

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 the description of the 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))

See Also

BITMAPCOREINFO


BITMAPCOREINFO structure
BITMAPCOREINFO (Win32)

typedef struct _BITMAPCOREINFO {    /* bmci */

        BITMAPCOREHEADER  bmciHeader;

        RGBTRIPLE         bmciColors[1];

} BITMAPCOREINFO;

The BITMAPCOREINFO structure defines the dimensions and color information for a device-independent bitmap (DIB).

Member	Description

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.

Comments

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 3-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, RGBTRIPLE


BITMAPFILEHEADER structure
BITMAPFILEHEADER (Win32)

typedef struct tagBITMAPFILEHEADER { /* bmfh */

        WORD    bfType;

        DWORD   bfSize;

        WORD    bfReserved1;

        WORD    bfReserved2;

        DWORD   bfOffBits;

} BITMAPFILEHEADER;

The BITMAPFILEHEADER data structure contains information about the type, size, and layout of a file that contains a device-independent bitmap (DIB).

Member	Description

bfType	Specifies the file type. It must be BM.

bfSize	Specifies the size of the file, in a doubleword value. This value can be obtained by dividing the length of the file, in bytes, by 4.

bfReserved1	Reserved; must be zero.

bfReserved2	Reserved; must be zero.

bfOffBits	Specifies the offset, in bytes, from the BITMAPFILEHEADER to the bitmap bits.

Comments

A BITMAPINFO or BITMAPCOREINFO structure immediately follows the BITMAPFILEHEADER structure in the DIB file.

See Also

BITMAPCOREINFO, BITMAPINFO


BITMAPINFO structure
BITMAPINFO (Win32)

typedef struct tagBITMAPINFO { /* bmi */

   BITMAPINFOHEADER bmiHeader;

   RGBQUAD          bmiColors[1];

} BITMAPINFO;

The BITMAPINFO structure defines the dimensions and color information for a Windows device-independent bitmap (DIB).

Member	Description

bmiHeader	Specifies a BITMAPINFOHEADER structure that contains information about the dimensions and color format of a device-independent bitmap.

bmiColors	Specifies an array of RGBQUAD or DWORD data types that define the colors in the bitmap.

Comments

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 boundary. If height is positive the origin of the bitmap is the lower-left corner. If the height is negative then the 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. The biCompression member of the BITMAPINFOHEADER must be BI_BITFIELDS. The bmiColors member contains 3 DWORD color masks which specify the red, green, and blue components, respectively, of each pixel. Bits set in the 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. Each WORD in the array represents a single pixel.

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, of a pixel.

32	The bitmap has a maximum of 2^32 colors. The biCompression member of the BITMAPINFOHEADER must be BI_BITFIELDS. The bmiColors member contains 3 DWORD color masks which specify the red, green, and blue components, respectively, of each pixel. Bits set in the 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. Each DWORD in the array represents a single pixel.

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 (that is, 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 DWORD 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, RGBQUAD


BITMAPINFOHEADER structure
BITMAPINFOHEADER (Win32)

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;

The BITMAPINFOHEADER structure contains information about the dimensions and color format of a device-independent bitmap (DIB).

Member	Description

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 negative then the origin of the bitmap is the upper-left hand corner and the height is the absolute value of biHeight.

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 bitmap. It can be one of the following values:

Value	Description

BI_RGB	An uncompressed format.

BI_RLE8	A run-length encoded format for bitmaps with 8 bits per pixel. The compression format is a 2-byte format consisting of a count byte followed by a byte containing a color index. For more information, see the following Comments section.

BI_RLE4	A run-length encoded format for bitmaps with 4 bits per pixel. The compression format is a 2-byte format consisting of a count byte followed by two word-length color indices. For more information, see the following Comments section.

BI_BITFIELDS	Specifies the bitmap is not compressed and the color table consists of 3 DWORD color masks which 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. For biBitCount equal to 16 or 32 the optimal color palette starts immediately following the 3 DWORD masks.

If the bitmap is a packed bitmap (that is, 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 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.

Comments

The BITMAPINFO data structure combines the BITMAPINFOHEADER structure and a color table to provide a complete definition of the dimensions and colors of a Windows DIB. For more information about Windows 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 8 bits per pixel and with 4 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. Following are the meanings of the second byte of the escape.

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 nibble (that is, its high-order four bits) and one in its low-order nibble. The first of the pixels is drawn using the color specified by the high-order nibble, the second is drawn using the color in the low-order nibble, the third is drawn using the color in the high-order nibble, 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 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

See Also

BITMAPINFO


BY_HANDLE_FILE_INFORMATION structure
BY_HANDLE_FILE_INFORMATION (Win32)

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;

The BY_HANDLE_FILE_INFORMATION structure contains information retrieved by the GetFileInformationByHandle function.

Member	Description

dwFileAttributes	Specifies the file's attributes. This member can be one or more of the following:

Value	Meaning

FILE_ATTRIBUTE_ARCHIVE

The file is an archive file. Applications use this flag to mark files for backup or removal.

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 attribute is valid only if used alone.

FILE_ATTRIBUTE_READONLY

The file is a read-only file. 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 a temporary file. Applications can 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.

FILE_ATTRIBUTE_ATOMIC_WRITE

Reserved for future use. Do not specify.

FILE_ATTRIBUTE_XACTION_WRITE

Reserved for future use. Do not specify.

ftCreationTime	Specifies the time the file was created. If the underlying file system does not support this time field, ftCreationTime is zero. The file allocation table (FAT) file system does not record file creation time, but the high-performance (HPFS) and New Technology (NTFS) file systems do.

ftLastAccessTime	Specifies the time the file was last accessed. If the underlying file system does not support this time field, ftLastAccessTime is zero. The FAT file system does not record last access time, but HPFS and NTFS do.

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 FAT and HPFS file systems, this member is always 1. For NTFS, it may be more than one.

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


CBT_CREATEWND structure
CBT_CREATEWND (Win32)

typedef struct tagCBT_CREATEWND { /* cbtcw */

    LPCREATESTRUCT lpcs;

    HWND           hwndInsertAfter;

} CBT_CREATEWND;

The CBT_CREATEWND structure contains information passed to a WH_CBT hook procedure before a window is created.

Member	Description

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, SetWindowsHookEx


CBTACTIVATESTRUCT structure
CBTACTIVATESTRUCT (Win32)

typedef struct tagCBTACTIVATESTRUCT { /* cas */

    BOOL fMouse;

    HWND hWndActive;

} CBTACTIVATESTRUCT;

The CBTACTIVATESTRUCT structure contains information passed to a WH_CBT hook procedure before a window is activated.

Member	Description

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 structure
CHAR_INFO (Win32)

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;

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.

Member	Description

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.

See Also

ReadConsoleOutput, ScrollConsoleScreenBuffer, WriteConsoleOutput


CHARSET structure
CHARSET (Win32)

typedef struct tagCHARSET { /* chst */

    DWORD aflBlock[3];

    DWORD flLang;

} CHARSET;

The CHARSET structure specifies the Unicode™ blocks and the character sets supported by a given font.

Member	Description

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.


CHOOSECOLOR structure
CHOOSECOLOR (Win32)

typedef struct {   /* cc */

    DWORD        lStructSize;

    HWND         hwndOwner;

    HWND         hInstance;

    DWORD        rgbResult;

    LPDWORD      lpCustColors;

    DWORD        Flags;

    DWORD        lCustData;

    LPCCHOOKPROC lpfnHook;

    LPCSTR       lpTemplateName;

} CHOOSECOLOR;

The CHOOSECOLOR structure contains information the operating system uses to initialize the system-defined Color dialog box. After the user closes the dialog box, the system returns information about the user's selection in this structure.

Member	Description

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 NULL if the dialog box has no owner.

hInstance	Identifies a data block that contains the dialog box template specified by the lpTemplateName member. This member is used only if the Flags member specifies the CC_ENABLETEMPLATE flag; otherwise, this member is ignored.

rgbResult	Specifies the color initially selected when the dialog box is created, and contains the user's color selection when the dialog box is closed. When the dialog box is created, if the CC_RGBINIT flag is set in the Flags member and the value of this member is not among the colors available, the system selects the nearest solid color available. If this member is NULL, the color initially selected is black.

lpCustColors	Points to an array of 16 DWORDs that contain 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. An application should save these values for future calls to the ChooseColor function.

Flags	Specifies the dialog box initialization flags. This member may be a combination of the following values:

Value	Meaning

CC_ENABLEHOOK	Enables the hook function specified in the lpfnHook member.

CC_ENABLETEMPLATE	Causes the system to create the dialog box by using the dialog box template identified by the hInstance and lpTemplateName members.

CC_ENABLETEMPLATEHANDLE	Indicates that the hInstance member identifies a data block that contains a pre-loaded dialog box template. The system ignores the lpTemplateName member if this flag is specified.

CC_FULLOPEN	Causes the entire dialog box to appear when the dialog box is created, including the portion that allows the user to create custom colors. If this flag is not specified, the user must choose the Define Custom Color button to see this portion of the dialog box.

CC_PREVENTFULLOPEN	Disables the Define Custom Colors button, preventing the user from creating custom colors.

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 show the Help button. The hwndOwner member must not be NULL if this option is specified.

lCustData	Specifies application-defined data the system passes to the hook function identified by the lpfnHook member. The system passes the data in the lParam parameter of the WM_INITDIALOG message.

lpfnHook	Points to a hook function that processes messages intended for the dialog box. An application must specify the CC_ENABLEHOOK flag in the Flags member to enable the function; otherwise, the system ignores this structure member. The hook function must return FALSE to pass a message to the standard color dialog box procedure, or TRUE to discard the message.

lpstrTemplateName	Points to a null-terminated string that names the dialog box template resource to be substituted for the standard dialog box template. An application can use the MAKEINTRESOURCE macro for numbered dialog box resources. This member is used only if the Flags member specifies the CC_ENABLETEMPLATE flag; otherwise, this member is ignored.

See Also

ChooseColor,, WM_INITDIALOG, MAKEINTRESOURCE, RGB


CHOOSEFONT structure
CHOOSEFONT (Win32)

typedef struct {    /* cf */

    DWORD        lStructSize;

    HWND         hwndOwner;

    HDC          hDC;

    LPLOGFONT    lpLogFont;

    INT          iPointSize;

    DWORD        Flags;

    DWORD        rgbColors;

    DWORD        lCustData;

    LPCFHOOKPROC lpfnHook;

    LPCTSTR      lpTemplateName;

    HANDLE       hInstance;

    LPTSTR       lpszStyle;

    WORD         nFontType;

    WORD         ___MISSING_ALIGNMENT__;

    INT          nSizeMin;

    INT          nSizeMax;

} CHOOSEFONT;

The CHOOSEFONT structure contains information the operating system uses to initialize the system-defined Font dialog box. After the user closes the dialog box, the system returns information about the user's selection in this structure.

Member	Description

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 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 flag; otherwise, this member is ignored.

lpLogFont	Points to a LOGFONT structure. If an application initializes the members of this structure before calling ChooseFont and also sets the CF_INITTOLOGFONTSTRUCT flag, the ChooseFont function initializes the dialog with a font that is the closest possible match. After the user closes the dialog box, ChooseFont sets the members of the LOGFONT structure based on the user's final selection.

iPointSize	Specifies the size of the selected font in units of 1/10 of a point. ChooseFont sets this value after the user closes the dialog box.

Flags	Specifies the dialog box initialization flags. This member may be a combination of the following values:

Value	Meaning

CF_APPLY	Specifies that ChooseFont should enable the Apply button.

CF_ANSIONLY	Specifies that ChooseFont should allow only the selection of fonts using the Windows character set. (If this flag is set, the user will not be able to select a font that contains only symbols.)

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.

CF_TTONLY	Specifies that ChooseFont should enumerate only and allow the selection of TrueType fonts.

CF_EFFECTS	Specifies that ChooseFont should enable strikeout, underline, and color effects. If this flag is set, the lfStrikOut, lfUnderline, and rgbColors members can be set before calling ChooseFont, and ChooseFont can set these members after the user closes the dialog box.

CF_ENABLEHOOK	Enables the hook function specified in the lpfnHook member of this structure.

CF_ENABLETEMPLATE	Indicates that hInstance member identifies a data block that contains a dialog box template identified by lpTemplateName.

CF_ENABLETEMPLATEHANDLE	Indicates that 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 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 lpLogFont 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	See the CF_NOVECTORFONTS description.

CF_NOFACESEL	Specifies that ChooseFont should not allow font selections.

CF_NOSTYLESEL	Specifies that ChooseFont should not allow style selections.

CF_NOSIZESEL	Specifies that ChooseFontw should not allow size selections.

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_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 algorithms or technologies.)

CF_SCREENFONTS	Causes the dialog box to list only the screen fonts supported by the system.

CF_SHOWHELP	Causes the dialog box to show the Help button. The hwndOwner member must not be NULL if this option is specified.

CF_USESTYLE	Specifies that lpszStyle member points to a buffer that contains style data that ChooseFont should use to initialize the Font Style selection. 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 set, the CF_BOTH and CF_SCALABLEONLY flags should also be set.

rgbColors	If the CF_EFFECTS flag is set, this member contains an RGB value that ChooseFont should use to set the text color. After the user closes the dialog box, this member contains the RGB value of the color the user selected.

lCustData	Specifies application-defined data the application passes to the hook function.

lpfnHook	Points to a hook function that processes messages intended for the dialog box. An application must specify the CF_ENABLEHOOK flag in the Flags member to enable the function; otherwise, the system ignores this member. The hook function must return FALSE to pass a message to the standard dialog box procedure, or TRUE to discard the message.

lpTemplateName	Points to a null-terminated string that names the dialog box template resource to be substituted for the standard dialog box template. An application can use the MAKEINTRESOURCE macro for numbered dialog box resources. This member is used only if the Flags member specifies the CF_ENABLETEMPLATE flag; otherwise, this member is ignored.

hInstance	Identifies a data block that contains the dialog box template specified by the lpstrTemplateName member. This member is used only if the Flags member specifies the CF_ENABLETEMPLATE flag; otherwise, this member is ignored.

lpszStyle	Points to a buffer that contains style data. If the CF_USESTYLE flag is set, that ChooseFont uses the data in this buffer to initialize the style control. When the user closes the dialog box, that ChooseFont copies the string in the style control into this buffer.

nFontType	Specifies the type of the selected font. This member may contain one of the values in the following list:

Value	Meaning

SIMULATED_FONTTYPE	The font is simulated by graphics device interface (GDI).

PRINTER_FONTTYPE	The font is a printer font.

SCREEN_FONTTYPE	The font is a screen font.

nSizeMin	Specifies the minimum point size a user can select. ChooseFont recognizes this member only if the CF_LIMITSIZE flag is set.

nSizeMax	Specifies the maximum point size a user can select. ChooseFont recognizes this member only if the CF_LIMITSIZE flag is set.

See Also

ChooseFont, WM_CHOOSEFONT_GETLOGFONT, CHOOSEFONT, LOGFONT, MAKEINTRESOURCE


COLORADJUSTMENT structure
COLORADJUSTMENT (Win32)

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;

The COLORADJUSTMENT structure defines the color adjustment values used by the StretchBlt and StretchDIBits functions when the stretchblt mode is HALFTONE.

Member	Description

caSize	Specifies the size of the structure in bytes.

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 luminance of the light source under which the image object is viewed. This member may be set to one of the following values:

ILLUMINANT_EQUAL_ENERGY

ILLUMINANT_A

ILLUMINANT_B

ILLUMINANT_C

ILLUMINANT_D50

ILLUMINANT_D55

ILLUMINANT_D65

ILLUMINANT_D75

ILLUMINANT_F2

ILLUMINANT_TURNGSTEN

ILLUMINANT_DAYLIGHT

ILLUMINANT_FLUORESCENT

ILLUMINANT_NTSC

caRedGamma	Specifies the n-th power gamma-correction value for the red primary of the source colors. The value must be in the range from 2,500 to 65,000. A value of 10,000 means no gamma-correction.

caGreenGamma	Specifies the n-th power gamma-correction value for the green primary of the source colors. The value must be in the range from 2,500 to 65,000. A value of 10,000 means no gamma-correction.

caBlueGamma	Specifies the n-th power gamma-correction value for the blue primary of the source colors. The value must be in the range from 2,500 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 4,000.

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 6,000 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 would adjust towards red and negative numbers adjust towards green. A 0 means no tint adjustment.

See Also

SetStretchBltMode, StretchBlt, StretchDIBits


CLIENTCREATESTRUCT structure
CLIENTCREATESTRUCT (Win32)

typedef struct tagCLIENTCREATESTRUCT { /* ccs */

    HANDLE hWindowMenu;

    UINT   idFirstChild;

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

Member	Description

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


COLORREF structure
COLORREF (Win32)

The COLORREF value is a 32-bit value used to specify an RGB color.

Comments

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


COMMPROP structure
COMMPROP (Win32)

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;

The COMMPROP structure is used in the GetCommProperties function to return information about a given communications driver.

Member	Description

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 bit is always set for communications 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_128K	128K bps

BAUD_USER	Programmable baud rates available

dwProvSubType	Specifies the specific communications provider type.

Value	Meaning

PST_UNSPECIFIED	Unspecified

PST_RS232	RS-232 serial port

PST_PARALLELPORT	Parallel port

PST_RS422	RS-422 port

PST_RS423	RS-423 port

PST_RS449	RS-449 port

PST_FAX	Fax device

PST_SCANNER	Scanner device

PST_NETWORK_BRIDGE	Unspecified network bridge

PST_LAT	LAT protocol

PST_TCPIP_TELNET	TCP/IP Telnet protocol

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:

Flag	Meaning

PCF_DTRDSR	DTR (data-terminal-ready)/DSR (data-set-ready) supported

PCF_RTSCTS	RTS (request-to-send)/CTS (clear-to-send) supported

PCF_RLSD	RLSD (receive-line-signal-detect supported)

PCF_PARITY_CHECK	Parity checking supported

PCF_XONXOFF	XON/XOFF flow control supported

PCF_SETXCHAR	Settable XON/XOFF supported

PCF_TOTALTIMEOUTS	Total (elapsed) timeouts supported

PCF_INTTIMEOUTS	Interval timeouts supported

PCF_SPECIALCHARS	Special character support provided

PCF_16BITMODE	Special 16-bit mode supported

dwSettableParams	Specifies a bitmask indicating the communications parameter that can be changed. This member can be one of the following values:

Flag	Meaning

SP_PARITY	Parity

SP_BAUD	Baud rate

SP_DATABITS	Data bits

SP_STOPBITS	Stop bits

SP_HANDSHAKING	Handshaking (flow control)

SP_PARITY_CHECK	Parity checking

SP_RLSD	RLSD (receive-line-signal-detect)

dwSettableBaud	Specifies a bitmask indicating the baud rates that can be set. 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:

Flag	Meaning

DATABITS_5	5 data bits

DATABITS_6	6 data bits

DATABITS_7	7 data bits

DATABITS_8	8 data bits

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

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

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.

See Also

GetCommProperties


COMMTIMEOUTS structure
COMMTIMEOUTS (Win32)

typedef struct _COMMTIMEOUTS { /* ctmo */

    DWORD ReadIntervalTimeout;

    DWORD ReadTotalTimeoutMultiplier;

    DWORD ReadTotalTimeoutConstant;

    DWORD WriteTotalTimeoutMultiplier;

    DWORD WriteTotalTimeoutConstant;

} COMMTIMEOUTS,*LPCOMMTIMEOUTS;

The COMMTIMEOUTS structure is used in the SetCommTimeouts and GetCommTimeouts functions to set and query the timeout parameters for a communications device. The parameters determine the behavior of ReadFile, WriteFile, ReadFileEx, and WriteFileEx operations on the device.

Member	Description

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 timeouts 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 timeout period for read operations. For each read operation, this value is multiplied by the requested number of bytes to read.

ReadTotalTimeoutConstant	Specifies the constant, in milliseconds, used to calculate the total timeout 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 timeouts are not used for read operations.

WriteTotalTimeoutMultiplier	Specifies the multiplier, in milliseconds, used to calculate the total timeout 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 timeout 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 timeouts are not used for write operations.

See Also

GetCommTimeouts, SetCommTimeouts


COMPAREITEMSTRUCT structure
COMPAREITEMSTRUCT (Win32)

typedef struct tagCOMPAREITEMSTRUCT { /* cis */

    UINT  CtlType;

    UINT  CtlID;

    HWND  hwndItem;

    UINT  itemID1;

    DWORD itemData1;

    UINT  itemID2;

    DWORD itemData2;

} COMPAREITEMSTRUCT;

The COMPAREITEMSTRUCT structure supplies the identifiers and application-supplied data for two items in a sorted owner-draw 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.

Member	Description

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


COMSTAT structure
COMSTAT (Win32)

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;

The COMSTAT structure contains information about a communications device. This structure is filled in by the ClearCommError function.

Member	Description

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 EOF character has been received. If this member is TRUE, the EOF character has been received.

fTxim	Specifies whether a character is waiting to be transmitted. If this member is TRUE, a character is waiting to be transmitted.

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 0 when doing a non-overlapped write.

See Also

ClearCommError


CONSOLE_CURSOR_INFO structure
CONSOLE_CURSOR_INFO (Win32)

typedef struct _CONSOLE_CURSOR_INFO { /* cci */

    DWORD  dwSize;

    BOOL   bVisible;

} CONSOLE_CURSOR_INFO, *PCONSOLE_CURSOR_INFO;

The CONSOLE_CURSOR_INFO structure contains information about the console cursor.

Member	Description

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 structure
CONSOLE_SCREEN_BUFFER_INFO (Win32)

typedef struct _CONSOLE_SCREEN_BUFFER_INFO { /* csbi */

    COORD      dwSize;

    COORD      dwCursorPosition;

    WORD       wAttributes;

    SMALL_RECT srWindow;

    COORD      dwMaximumWindowSize;

} CONSOLE_SCREEN_BUFFER_INFO ;

The CONSOLE_SCREEN_BUFFER_INFO structure contains information about a console screen buffer.

Member	Description

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


CONTEXT structure
CONTEXT (Win32)

The CONTEXT structure contains processor-specific register data. Currently, there is a CONTEXT structure for Intel® processors and one for MIPS® processors. This structure is defined in the header file.


CONVCONTEXT structure
CONVCONTEXT (Win32)

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;

The CONVCONTEXT structure contains information supplied by a dynamic data exchange (DDE) client application. The information is useful for specialized or cross-language DDE conversations.

Member	Description

cb	Specifies the size, in bytes, of the structure.

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 structure
CONVINFO (Win32)

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;

The CONVINFO structure contains information about a dynamic data exchange (DDE) conversation.

Member	Description

cb	Specifies the length, in bytes, of the structure.

hUser	Identifies application-defined data.

hConvPartner	Identifies the partner application in the DDE conversation. This member is set to 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 send updated data to the client during an advise loop. This transaction results when the server calls the DdePostAdvise function.

XTYP_ADVSTART	Requests a server begin an advise loop with a client.

XTYP_ADVSTOP	Notifies a server an advise loop is stopping.

XTYP_CONNECT	Requests a server establish a conversation with a client.

XTYP_CONNECT_CONFIRM	Notifies a server a conversation with a client has been established.

XTYP_DISCONNECT	Notifies a server a conversation has terminated.

XTYP_EXECUTE	Requests a server 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 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 send data to a client.

XTYP_UNREGISTER	Notifies other DDEML applications that a server has unregistered a service name.

XTYP_WILDCONNECT	Requests a server 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, DdeQueryConvInfo


COORD structure
COORD (Win32)

typedef struct _COORD { /* coord. */

    SHORT X;      /* horizontal coordinate    */

    SHORT Y;      /* vertical coordinate      */

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

Member	Description

X	Horizontal or column value.

Y	Vertical or row value.


COPYDATASTRUCT structure
COPYDATASTRUCT (Win32)

typedef struct tagCOPYDATASTRUCT {  /* cds */

    DWORD dwData;

    DWORD cbData;

    PVOID lpData;

} COPYDATASTRUCT;

The COPYDATASTRUCT structure contains data to be passed to another application by the WM_COPYDATA message.

Member	Description

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 structure
CPINFO (Win32)

struct tagCPINFO {

    UINT MaxCharSize;

    BYTE DefaultChar[MAX_DEFAULTCHAR];

    BYTE LeadByte[MAX_LEADBYTES];

} CPINFO;

The CPINFO structure contains information about a code page.

Member	Description

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 as determined by the translation options specified in the WideCharToMultiByte function.

LeadByte	Specifies lead-byte ranges in a variable-length array. If there are no lead bytes in this code page, every element of the array is NULL. If there are lead bytes, a starting value and an ending value are given for each range. Ranges are inclusive.

Comments

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 maximum number of lead-byte ranges for any code page is 5. Each range requires 2 bytes to describe, plus a double-byte terminating null character. Therefore, a value of 12 for the LeadByte member designates 5 lead-byte ranges.

See Also

GetCPInfo, WideCharToMultiByte


CPLINFO structure
CPLINFO (Win32)

typedef struct tagCPLINFO { /* cpli */

    int  idIcon;

    int  idName;

    int  idInfo;

    LONG lData;

} CPLINFO;

The CPLINFO structure contains resource information and a user-defined value for a Control Panel application.

Member	Description

idIcon	Specifies an icon resource identifier for the application icon. This icon is displayed in the Control Panel window.

idName	Specifies a string resource identifier for the application name. The name is the short string displayed below the application icon in the Control Panel window. The name is also displayed in the Settings menu of Control Panel.

idInfo	Specifies a string resource identifier for the application description. The description is the descriptive string displayed at the bottom of the Control Panel window when the application icon is selected.

lData	Specifies user-defined data for the application.

See Also

CPL_INQUIRE, NEWCPLINFO


CREATE_PROCESS_DEBUG_INFO structure
CREATE_PROCESS_DEBUG_INFO (Win32)

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;

The CREATE_PROCESS_DEBUG_INFO structure contains process creation information that can be used by a debugger.

Member	Description

hFile	Identifies an open handle of the process's image file. If hFile is NULL, the handle is not valid. Otherwise, the debugger can use hFile to read from and write to the image file.

hProcess	Identifies an open handle of the process. If hProcess is NULL, the handle is not valid. Otherwise, the debugger can use hProcess 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. This allows the debugger to read from and write to the registers of the thread and 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	Specifies the base address of a per-thread data block. At offset 0x2C within this block there exists an array of LPVOIDs. There is one LPVOID for each DLL/EXE loaded at process initialization, and that LPVOID points to thread local storage. This gives a debugger access to per-thread data in its debuggee's threads 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	Provides an optional pointer to the file name associated with the hFile parameter. The lpImageName parameter may be NULL, or may contain the address of a string pointer in the debuggee's address space. That address may in turn either be NULL, or point to the actual file name. If fUnicode is a non-zero value, the name string is Unicode; otherwise it is ANSI.

This parameter is strictly optional. Debuggers must be prepared to handle the case where lpImageName is NULL, OR *lpImageName (in the debuggee's address space) is NULL. Specifically, this release of Windows NT will never provide an image name for a create process event, and 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 debug events that originate from a call to the DebugActiveProcess function.

fUnicode	Indicates whether a file name specified by lpImageName is Unicode or ANSI. A non-zero value indicates Unicode; zero indicates ANSI.

See Also

CREATE_THREAD_DEBUG_INFO, DEBUG_EVENT, LOAD_DLL_DEBUG_INFO


CREATE_THREAD_DEBUG_INFO structure
CREATE_THREAD_DEBUG_INFO (Win32)

typedef struct _CREATE_THREAD_DEBUG_INFO { /* ctdi */

    HANDLE hThread;

    LPVOID lpThreadLocalBase;

    LPTHREAD_START_ROUTINE lpStartAddress;

} CREATE_THREAD_DEBUG_INFO;

The CREATE_THREAD_DEBUG_INFO structure contains thread-creation information that can be used by a debugger.

Member	Description

hThread	Identifies a handle of the thread whose creation caused the debugging event. 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. This allows the debugger to read from and write to the registers of the thread and control execution of the thread.

lpThreadLocalBase	Specifies the base address of a per-thread data block. At offset 0x2C within this block there exists an array of LPVOIDs. There is one LPVOID for each DLL/EXE loaded at process initialization, and that LPVOID points to thread local storage. This gives a debugger access to per-thread data in its debuggee's threads 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


CREATESTRUCT structure
CREATESTRUCT (Win32)

typedef struct tagCREATESTRUCT { /* cs */

    LPVOID lpCreateParams;

    HANDLE hInstance;

    HMENU  hMenu;

    HWND   hwndParent;

    int    cy;

    int    cx;

    int    y;

    int    x;

    LONG   style;

    LPCSTR lpszName;

    LPCSTR lpszClass;

    DWORD  dwExStyle;

} CREATESTRUCT;

The CREATESTRUCT structure defines the initialization parameters passed to the window procedure of an application.

Member	Description

lpCreateParams	Points to data to be used for creating the window.

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.

See Also

CreateWindow, CreateWindowEx


CWPSTRUCT structure
CWPSTRUCT (Win32)

typedef struct tagCWPSTRUCT { /* cwps */

    LPARAM lParam;

    WPARAM wParam;

    DWORD  message;

    HWND   hwnd;

} CWPSTRUCT;

The CWPSTRUCT structure defines the message parameters passed to a WH_CALLWNDPROC hook procedure.

Member	Description

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

SetWindowsHook, SetWindowsHookEx


DCB structure
DCB (Win32)

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

} DCB;

The DCB structure defines the control setting for a serial communications device.

Member	Description

DCBlength	Specifies the length, in bytes, of the DCB structure.

BaudRate	Specifies the baud rate at which the communications device operates.

fBinary	Specifies whether binary mode is enabled. Windows NT does not support non-binary mode transfers, so this member should be set TRUE. Trying to set it to FALSE, under Windows NT, will not work.

Under Windows 3.1, if this member is FALSE, non-binary 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, when 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, when 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	Description

DTR_CONTROL_DISABLE

Disables the DTR line on device open and leaves it disabled.

DTR_CONTROL_ENABLE

Enables the DTR line on device open 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 flag 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. To calculate the maximum number of bytes allowed, this value is subtracted 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.

Comments

When a DCB structure is used to configure the 8250, the following restrictions apply to the values specified for the 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, GetCommState, SetCommState


DDEACK structure
DDEACK (Win32)

typedef struct { /* ddeack */

    unsigned short bAppReturnCode:8,

    reserved:6,

    fBusy:1,

    fAck:1;

} DDEACK;

The DDEACK structure contains status flags that a dynamic data exchange (DDE) application passes to its partner as part of the WM_DDE_ACK message. The flags provide details about the application's response to a WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_EXECUTE, WM_DDE_REQUEST, WM_DDE_POKE, or WM_DDE_UNADVISE message.

Member	Description

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, DDEDATA, DDEPOKE


DDEADVISE structure
DDEADVISE (Win32)

typedef struct { /* ddeadv */

    unsigned short reserved:14,

        fDeferUpd:1,

        fAckReq:1;

    short cfFormat;

} DDEADVISE;

The DDEADVISE structure contains flags that specify how a dynamic data exchange (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.

Member	Description

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, DDEACK, DDEDATA, DDEPOKE


DDEDATA structure
DDEDATA (Win32)

typedef struct { /* ddedat */

    unsigned short unused:12,

        fResponse:1,

        fRelease:1,

        reserved:1,

        fAckReq:1;

    short cfFormat;

    BYTE  Value[1];

} DDEDATA;

The DDEDATA structure contains the data, and information about the data, sent as part of a WM_DDE_DATA message.

Member	Description

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

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

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[1]	Contains the data. The length and the type of data depends on the cfFormat member.

See Also

WM_DDE_ACK, WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_POKE, WM_DDE_REQUEST


DDELN structure
DDELN (Win32)

typedef struct { /* ddeln */

    unsigned short unused:13,

        fRelease:1,

        fDeferUpd:1,

        fAckReq:1;

    short cfFormat;

} DDELN;

The DDELN structure is obsolete. Win32 applications should use the DDEADVISE structure.

See Also

DDEADVISE, WM_DDE_ADVISE, WM_DDE_UNADVISE


DDEML_MSG_HOOK_DATA structure
DDEML_MSG_HOOK_DATA (Win32)

typedef struct tagDDEML_MSG_HOOK_DATA { /* dmhd */

    UINT  uiLo;

    UINT  uiHi;

    DWORD cbData;

    DWORD Data[8];

} DDEML_MSG_HOOK_DATA;

The DDEML_MSG_HOOK_DATA structure contains information about a dynamic data exchange (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.

Member	Description

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 structure
DDEPOKE (Win32)

typedef struct { /* ddepok */

    unsigned short unused:13,

        fRelease:1,

        fReserved:2;

    short cfFormat;

    BYTE  Value[1];

} DDEPOKE;

The DDEPOKE structure contains the data, and information about the data, sent as part of a WM_DDE_POKE message.

Member	Description

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 depends on the value of the cfFormat member.

See Also

WM_DDE_POKE


DDEUP structure
DDEUP (Win32)

typedef struct { /* ddeup */

    unsigned short unused:12,

        fAck:1,

        fRelease:1,

        fReserved:1,

        fAckReq:1;

    short cfFormat;

    BYTE rgb[1];

} DDEUP;

The DDEUP structure is obsolete. Win32 applications should use the DDEDATA and DDEPOKE structures.

See Also

DDEDATA, DDEPOKE, WM_DDE_DATA, WM_DDE_POKE


DEBUG_EVENT structure
DEBUG_EVENT (Win32)

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;

The DEBUG_EVENT structure describes a debugging event.

Member	Description

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

Comments

If the WaitForDebugEvent function succeeds, it fills in the members of a DEBUG_EVENT structure.

See Also

WaitForDebugEvent


DEBUGHOOKINFO structure
DEBUGHOOKINFO (Win32)

typedef struct tagDEBUGHOOKINFO { /* dh */

    DWORD  idThread;

    LPARAM reserved;

    LPARAM lParam;

    WPARAM wParam;

    int    code;

} DEBUGHOOKINFO;

The DEBUGHOOKINFO structure contains debugging information.

Member	Description

idThread	Identifies the thread containing the filter function.

reserved	Not used.

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


DELETEITEMSTRUCT structure
DELETEITEMSTRUCT (Win32)

typedef struct tagDELETEITEMSTRUCT { /* ditms */

    UINT CtlType;

    UINT CtlID;

    UINT itemID;

    HWND hwndItem;

    UINT itemData;

} DELETEITEMSTRUCT;

The DELETEITEMSTRUCT structure describes a deleted owner-drawn list-box or combo-box item. When an item is removed from the list box or combo box or when the list box or combo box is destroyed, Windows sends the WM_DELETEITEM message to the owner for each deleted item. The lParam parameter of the message contains a pointer to this structure.

Member	Description

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.

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


DEVMODE structure
DEVMODE (Win32)

typedef struct _devicemode {    /* dvmd */

    TCHAR  dmDeviceName[32];

    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;

    TCHAR  dmFormName[32];

    WORD   dmUnusedPadding;

    USHORT dmBitsPerPel;

    DWORD  dmPelsWidth;

    DWORD  dmPelsHeight;

    DWORD  dmDisplayFlags;

    DWORD  dmDisplayFrequency;

} DEVMODE;

The DEVMODE data structure contains information about the device initialization and environment of a printer.

Member	Description

dmDeviceName	Specifies the name of the device the driver supports; for example, "PCL/HP LaserJet" in the case of PCL/HP LaserJet®. This string is unique among device drivers.

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 except the dmDriverData (device-specific) member. If an application manipulates only the driver-independent portion of the data, it can use this member to determine the length of the structure without having to account for different versions.

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	Specifies which of the remaining members in the DEVMODE structure have been initialized. Bit 0 (defined as DM_ORIENTATION) corresponds to dmOrientation; bit 1 (defined as DM_PAPERSIZE) specifies dmPaperSize, and so on. A printer driver supports only those members that are appropriate for the printer technology.

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 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_FALSE provides faster, more efficient output, since the data is sent to a page printer just once, no matter how many copies are required. The printer is told to simply print the page again.

dmFormName	Specifies the name of the form to use; for example, "Letter" or "Legal". A complete set of names can be retrieved through the EnumForms function.

dmBitsPerPel	Specifies in bits per pixel the color resolution of the display device. For example: 4 bits for 16 colors, 8 bits for 256 colors, or 16 bits for 65536 colors.

dmPelsWidth	Specifies the width, in pixels, of the visible device surface.

dmPelsHeight	Specifies the height, in pixels, of the visible device surface.

dmDisplayFlags	Specifies the device's display mode. The following are valid flags:

Value	Meaning

DM_GRAYSCALE	Specifies that the display is a NON-color 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, NON-interlaced is assumed.

dmDisplayFrequency	Specifies the frequency, in hertz (cycles per second), of the display device in a particular mode.

Comments

A device driver's private data will follow the dmDisplayMode member. The number of bytes of private data is specified by the dmDriverExtra member.

See Also

AdvancedDocumentProperties, CreateDC, CreateIC, DeviceCapabilities, DocumentProperties, OpenPrinter


DEVNAMES structure
DEVNAMES (Win32)

typedef struct tagDEVNAMES { /* dvnm */

    WORD wDriverOffset;

    WORD wDeviceOffset;

    WORD wOutputOffset;

    WORD wDefault;

    /* driver, device, and port-name strings follow wDefault */

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

Member	Description

wDriverOffset	(Input/Output) Specifies the offset to a null-terminated string that contains the MS-DOS 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 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 to the null-terminated string that contains the MS-DOS 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. On input, if the DN_DEFAULTPRN flag is set, the other values in the DEVNAMES structure are checked against the current default printer. 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 set if the default printer was selected. If a specific printer is selected, the flag is not set. All other bits in this member are reserved for internal use by the Print Dialog box procedure.

See Also

PrintDlg, DEVMODE


DISK_GEOMETRY structure
DISK_GEOMETRY (Win32)

typedef struct _DISK_GEOMETRY {

   MEDIA_TYPE  MediaType;

   LARGE_INTEGER  Cylinders;

   DWORD  TracksPerCylinder;

   DWORD  SectorsPerTrack;

   DWORD  BytesPerSector;

} DISK_GEOMETRY ;

The DISK_GEOMETRY structure describes the geometry of disk devices and media.

Member	Description

MediaType	The type of media. See MEDIA_TYPE.

Cylinders	The number of cylinders.

TracksPerCylinder	The number of tracks per cylinder.

SectorsPerTrack	The number of sectors per track.

BytesPerSector	The number of bytes per sector

Comments

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, IOCTL_DISK_GET_DRIVE_GEOMETRY, IOCTL_DISK_GET_MEDIA_TYPES, MEDIA_TYPE


DISK_PERFORMANCE structure
DISK_PERFORMANCE (Win32)

typedef struct _DISK_PERFORMANCE {

        LARGE_INTEGER BytesRead;

        LARGE_INTEGER BytesWritten;

        LARGE_INTEGER ReadTime;

        LARGE_INTEGER WriteTime;

        DWORD ReadCount;

        DWORD WriteCount;

        DWORD QueueDepth;

} DISK_PERFORMANCE ;

The DISK_PERFORMANCE structure provides disk performance information.

Member	Description

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

Comments

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 structure
DLGITEMTEMPLATE (Win32)

typedef struct { /* dlit */

    DWORD style;

    DWORD dwExtendedStyle;

    WORD  x;

    WORD  y;

    WORD  cx;

    WORD  cy;

    WORD  id;

} 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 dialog box template.

Member	Description

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 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 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 units, of the control.

cy	Specifies the height, in dialog units, of the control.

id	Specifies the control identifier.

Comments

In a dialog box template, 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.

The class array follows the DLGITEMTEMPLATE structure. When the first element of this array is 0xFFFF, the array has one additional element that specifies an atom value identifying a registered window class. When the first element has any other value, Windows assumes the array is a null-terminated Unicode string that specifies the name of a registered window class. Following are the class atom values for predefined controls:

Value	Meaning

0x0080	Button

0x0081	Edit

0x0082	Static

0x0083	List box

0x0084	Scroll bar

0x0085	Combo box

The title array follows the class array. When the first element is 0xFFFF, the array has one additional element that specifies the identifier of a resource, such as an icon, in an executable file. Resource identifiers are usually given for controls, such as static icon controls, that load and display an icon or other resources rather than text. When the first element is any other value, Windows assumes the array is a null-terminated Unicode string that specifies the initial text for the control.

The creation data array follows the text array. This array can contain any number of elements; the control's window procedure must understand the content and format of the data. Windows passes this data to the control when it calls the CreateWindowEx function.

The x, y, cx, and cy members specify values in dialog units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, CreateWindowEx, DialogBoxIndirect, DialogBoxIndirectParam, MapDialogRect, DLGTEMPLATE


DLGTEMPLATE structure
DLGTEMPLATE (Win32)

typedef struct { /* dltt */

    DWORD style;

    DWORD dwExtendedStyle;

    WORD  cdit;

    WORD  x;

    WORD  y;

    WORD  cx;

    WORD  cy;

} DLGTEMPLATE;

The DLGTEMPLATE structure defines the dimensions and style of a dialog box. This structure, always the first in a dialog box template, also specifies the number of controls in the dialog box and therefore specifies the number of subsequent DLGITEMTEMPLATE structures in the template.

Member	Description

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_ABSALIGN	Specifies that the dialog box position is relative to the upper-left corner of the screen. If this style is not given, the position is relative to the upper-left corner of the owner window's client area.

DS_MODALFRAME	Specifies a dialog box with a modal dialog box border.

DS_NOIDLEMSG	Prevents Windows from sending the WM_ENTERIDLE messages to the owner window when no messages are in the application queue. This value applies to modal dialog boxes only.

DS_SETFONT	Specifies that a font other than the system font is used to draw text in the dialog box and its controls. When this value is given, the dialog box template must specify a point size and typeface name as described in the "Comments" section.

DS_SETFOREGROUND	Specifies that the application creating the dialog box is to be made the foreground task. Windows calls the SetForegroundWindow function to set the foreground task.

The DS_LOCALEDIT and DS_SYSMODAL styles are not fully supported in Windows NT. DS_LOCALEDIT applies only to applications written for Windows 3.x. DS_SYSMODAL creates a dialog box having the WS_EX_TOPMOST style but does not cause the system to disable all other windows.

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 units, of the upper left corner of the dialog box.

y	Specifies the y-coordinate, in dialog units, of the upper left corner of the dialog box

cx	Specifies the width, in dialog units, of the dialog box.

cy	Specifies the height, in dialog units, of the dialog box.

Comments

In a dialog box template, the DLGTTEMPLATE 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 array follows the DLGTEMPLATE structure. When the first element of this array is 0x0000, the dialog box has no menu and the array has no other elements. When the first element is 0xFFFF, the array has one additional element that specifies the resource identifier for a menu resource in an executable file. If the first element has any other value, Windows assumes the array is a null-terminated Unicode string that specifies the name of the menu resource in an executable file.

The class array follows the menu array. When the first element of the array is 0x0000, Windows uses the predefined dialog box class for the dialog box. When the first element is 0xFFFF, the array has one additional element that specifies the atom value identifying a registered window class. When the first element has any other value, Windows assumes the array is a null-terminated Unicode string that specifies the name of a registered window class.

The title array follows the class array. When the first element of the array is 0x0000, the dialog box has no title. When the first element has any other value, Windows assumes the array is a null-terminated Unicode string that specifies the title.

The 16-bit point size value and the typeface array follow the title array, but only if the style member gives the DS_SETFONT style. The point size value specifies the size in points 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.

Every dialog box template also contains the number of DLGITEMTEMPLATE structures as given by the cdit member. These structures define the dimensions and style of the controls in the dialog box.

The x, y, cx, and cy members specify values in dialog units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, DialogBoxIndirect, DialogBoxIndirectParam, MapDialogRect, DLGITEMTEMPLATE, WM_SETFONT


DOCINFO structure
DOCINFO (Win32)

typedef struct {    /* di */

    int    cbSize;

    LPTSTR lpszDocName;

    LPTSTR lpszOutput;

} DOCINFO;

The DOCINFO structure contains the input and output filenames used by the StartDoc function.

Member	Description

cbSize	Specifies the size, in bytes, of the structure.

lpszDocName	Points to a null-terminated string that specifies the name of the document.

pszOutput	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 DC handle which was passed to the StartDoc function.

See Also

StartDoc


DOC_INFO_1 structure
DOC_INFO_1 (Win32)

typedef struct _DOC_INFO_1 { /* dci1 */

    LPTSTR pDocName;

    LPTSTR pOutputFile;

    LPTSTR pDatatype;

} DOC_INFO_1;

The DOC_INFO_1 structure describes a document that will be printed.

Member	Description

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


DRAWITEMSTRUCT structure
DRAWITEMSTRUCT (Win32)

typedef struct tagDRAWITEMSTRUCT {  /* dis */

    UINT  CtlType;

    UINT  CtlID;

    UINT  itemID;

    UINT  itemAction;

    UINT  itemState;

    HWND  hwndItem;

    HDC   hDC;

    RECT  rcItem;

    DWORD itemData;

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

Member	Description

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_MENU	Owner-drawn menu item

CtlID	Specifies the identifier of the combo box, list box, or button. 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_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, and buttons. For menus, this member identifies the menu containing the item.

hDC	Identifies a device context (DC); this DC 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 DC specified by the hDC member. Windows automatically clips anything the owner window draws in the DC 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


DRIVE_LAYOUT_INFORMATION structure
DRIVE_LAYOUT_INFORMATION (Win32)

typedef struct _DRIVE_LAYOUT_INFORMATION {

   DWORD  PartitionCount;

   DWORD  Signature;

   PARTITION_INFORMATION  PartitionEntry[1];

} DRIVE_LAYOUT_INFORMATION;

The DRIVE_LAYOUT_INFORMATION structure provides information about a drive's partitions.

Member	Description

PartitionCount	The number of partitions on the drive.

Signature	A drive signature value.

PartitionEntry[1]	A variable-sized array of PARTITION_INFORMATION structures, one structure for each partition on the drive.

Comments

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 structure
DRIVER_INFO_1 (Win32)

typedef struct _DRIVER_INFO_1 { /* dri1 */

    LPTSTR pName;

} DRIVER_INFO_1;

The DRIVER_INFO_1 structure identifies a printer driver.

Member	Description

pName	Points to a null-terminated string that specifies the name of a printer driver.

See Also

EnumPrinterDrivers


DRIVER_INFO_2 structure
DRIVER_INFO_2 (Win32)

typedef struct _DRIVER_INFO_2 { /* dri2 */

    DWORD  cVersion;

    LPTSTR pName;

    LPTSTR pEnvironment;

    LPTSTR pDriverPath;

    LPTSTR pDataFile;

    LPTSTR pConfigFile;

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

Member	Description

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


EMRFORMAT structure
EMRFORMAT (Win32)

typedef struct tagEMRFORMAT   {

    DWORD   dSignature;

    DWORD   nVersion;

    DWORD   cbData;

    DWORD   offData;

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

Member	Description

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.

Comments

The reference page for GdiComment discusses enhanced metafile public comments in general, and the GDICOMMENT_MULTIFORMATS public comment in particular.

See Also

GdiComment


ENHMETAHEADER structure
ENHMETAHEADER (Win32)

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;

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

Member	Description

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. For the first release of Windows NT, the 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.

See Also

ENHMETARECORD


ENHMETARECORD structure
ENHMETARECORD (Win32)

typedef struct tagENHMETARECORD { /* enmr */

    DWORD iType;

    DWORD nSize;

    DWORD dParm[1];

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

Member	Description

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


ENUMLOGFONT structure
ENUMLOGFONT (32-bit)

typedef struct tagENUMLOGFONT { /* elf */

    LOGFONT elfLogFont;

    BYTE    elfFullName[LF_FULLFACESIZE];

    BYTE    elfStyle[LF_FACESIZE];

} ENUMLOGFONT;

The ENUMLOGFONT structure defines the attributes of a font, the complete name of a font, and the style of a font.

Member	Description

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


ENUM_SERVICE_STATUS structure
ENUM_SERVICE_STATUS

typedef struct _ENUM_SERVICE_STATUS { /* ess */

    LPTSTR lpServiceName;

    LPTSTR lpDisplayName;

    SERVICE_STATUS ServiceStatus;

} ENUM_SERVICE_STATUS, *LPENUM_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.

Member	Description

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 forward-slash (/), back-slash (\), 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


EVENTLOGRECORD structure
EVENTLOGRECORD (Win32)

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:

    //

    // WCHAR SourceName[]

    // WCHAR Computername[]

    // SID   UserSid

    // WCHAR Strings[]

    // BYTE  Data[]

    // CHAR  Pad[]

    // DWORD Length;

    //

} EVENTLOGRECORD;

The EVENTLOGRECORD structure contains information about an event record.

Member	Description

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 structure
EVENTMSG (Win32)

typedef struct tagEVENTMSG {    /* em */

    UINT  message;

    UINT  paramL;

    UINT  paramH;

    DWORD time;

    HWND  hwnd;

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

Member	Description

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, MSG


EXCEPTION_DEBUG_INFO structure
EXCEPTION_DEBUG_INFO (Win32)

typedef struct _EXCEPTION_DEBUG_INFO { /* exdi */

    EXCEPTION_RECORD ExceptionRecord;

    DWORD dwFirstChance;

} EXCEPTION_DEBUG_INFO;

The EXCEPTION_DEBUG_INFO structure contains exception information that could be used by a debugger.

Member	Description

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 ExceptionRecord. If dwFirstChance 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 dwFirstChance 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_POINTERS structure
EXCEPTION_POINTERS (Win32)

typedef struct _EXCEPTION_POINTERS { /* exp */

    PEXCEPTION_RECORD ExceptionRecord;

    PCONTEXT ContextRecord;

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

Member	Description

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 structure
EXCEPTION_RECORD (Win32)

typedef struct _EXCEPTION_RECORD { /* exr */

    DWORD ExceptionCode;

    DWORD ExceptionFlags;

    struct _EXCEPTION_RECORD *ExceptionRecord;

    PVOID ExceptionAddress;

    DWORD NumberParameters;

    DWORD ExceptionInformation[EXCEPTION_MAXIMUM_PARAMETERS];

} EXCEPTION_RECORD;

The EXCEPTION_RECORD structure describes an exception.

Member	Description

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_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_SINGLE_STEP

A trace trap or other single-instruction mechanism signaled that one instruction has been executed.

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_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_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_PRIV_INSTRUCTION

The thread tried to execute an instruction whose operation is not allowed in the current machine mode.

STATUS_NONCONTINUABLE_EXCEPTION

The thread tried to continue execution after a noncontinuable exception occurred.

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 STATUS_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

GetExceptionInformation, UnhandledExceptionFilter, EXCEPTION_DEBUG_INFO, EXCEPTION_POINTERS


EXIT_PROCESS_DEBUG_INFO structure
EXIT_PROCESS_DEBUG_INFO (Win32)

typedef struct _EXIT_PROCESS_DEBUG_INFO { /* epdi */

    DWORD dwExitCode;

} EXIT_PROCESS_DEBUG_INFO;

The EXIT_PROCESS_DEBUG_INFO structure contains an exiting process's exit code.

Member	Description

dwExitCode	Specifies the exit code for the process.

See Also

DEBUG_EVENT


EXIT_THREAD_DEBUG_INFO structure
EXIT_THREAD_DEBUG_INFO (Win32)

typedef struct _EXIT_THREAD_DEBUG_INFO { /* etdi */

    DWORD dwExitCode;

} EXIT_THREAD_DEBUG_INFO;

The EXIT_THREAD_DEBUG_INFO structure contains an exiting thread's exit code.

Member	Description

dwExitCode	Specifies the exit code for the thread.

See Also

DEBUG_EVENT


EXTLOGFONT structure
EXTLOGFONT (Win32)

typedef struct tagEXTLOGFONT {

    LOGFONT elfLogFont;

    BYTE    elfFullName[LF_FULLFACESIZE];

    BYTE    elfStyle[LF_FACESIZE];

    DWORD   elfVersion;

    DWORD   elfStyleSize;

    DWORD   elfMatch;

    DWORD   elfReserved;

    BYTE    elfVendorId[ELF_VENDOR_SIZE];

    DWORD   elfCulture;

    PANOSE  elfPanose;

} EXTLOGFONT;

The EXTLOGFONT structure defines the attributes of a font.

Member	Description

elfLogFont	Specifies some of the attributes of the given 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).

elfVersion	Reserved. Must be zero for the first release of Windows NT.

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 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	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 structure
EXTLOGPEN (Win32)

typedef struct tagEXTLOGPEN { /* exlp */

    UINT     elpPenStyle;

    UINT     elpWidth;

    UINT     elpBrushStyle;

    COLORREF elpColor;

    LONG     elpHatch;

    DWORD    elpNumEntries;

    DWORD    elpStyleEntry[1];

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

Member	Description

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

ExtCreatePen, GetObject, SetBkColor, SetBkMode, LOGBRUSH, LOGPEN


EXT_BUTTON structure
EXT_BUTTON (Win32)

typedef struct tagEXT_BUTTON { /* extbtn */

    WORD idCommand;

    WORD idsHelp;

    WORD fsStyle;

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

Member	Description

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


FILETIME structure
FILETIME (Win32)

typedef struct _FILETIME { /* ft */

    DWORD dwLowDateTime;

    DWORD dwHighDateTime;

} FILETIME;

The FILETIME structure is a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601.

Member	Description

dwLowDateTime	Specifies the low-order 32 bits of the file time.

dwHighDateTime	Specifies the high-order 32 bits of the file time.

See Also

CompareFileTime, DosDateTimeToFileTime, FileTimeToDosDateTime, FileTimeToLocalFileTime, FileTimeToSystemTime, GetFileTime, LocalFileTimeToFileTime, SetFileTime, SystemTimeToFileTime, SYSTEMTIME


FIND_NAME_BUFFER structure
FIND_NAME_BUFFER (Win32)

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;

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 NCBFINDNAME in the ncb_command member of the NCB structure.

Member	Description

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[6]	Specifies the destination address of the remote node where the name was found.

source_addr[6]	Specifies the source address for the remote node where the name was found.

routing_info[18]	Specifies additional routing information.

See Also

FILE_NAME_HEADER, NCB


FIND_NAME_HEADER structure
FIND_NAME_HEADER (Win32)

typedef struct _FIND_NAME_HEADER { /* fnh */

    WORD  node_count;

    UCHAR reserved;

    UCHAR unique_group;

} FIND_NAME_HEADER;

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

Member	Description

node_count	Specifies the number of nodes on which the specified name was found. The FIND_NAME_HEADER 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.

Comments

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 structure
FINDREPLACE (Win32)

typedef struct {    /* fr */

    DWORD        lStructSize;

    HWND         hwndOwner;

    HINSTANCE    hInstance;

    DWORD        Flags;

    LPSTR        lpstrFindWhat;

    LPSTR        lpstrReplaceWith;

    WORD         wFindWhatLen;

    WORD         wReplaceWithLen;

    DWORD        lCustData;

    LPFRHOOKPROC lpfnHook;

    LPCSTR       lpTemplateName;

} FINDREPLACE;

The FINDREPLACE structure contains information the operating system uses to initialize the system-defined Find and Replace dialog boxes. After the user closes the dialog box, the system returns information about the user-defined find or replace parameters in this structure.

Member	Description

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, but it must not be NULL.

hInstance	Identifies a data block that contains a dialog box template specified by the lpstrTemplateName member. This member is used only if the Flags member specifies the FR_ENABLETEMPLATE flag; otherwise, this member is ignored.

Flags	Specifies the dialog box initialization flags. This member may be a combination of the following values:

Value	Meaning

FR_DIALOGTERM

Indicates that the dialog box is closing. The window handle returned by the FindText or ReplaceText function is not valid if this flag is set.

FR_DOWN

Determines the direction of searches through a document. If this flag is set, the search direction is down; if the flag is clear, the search direction is up. Initially, this flag specifies the state of the Up and Down controls; after the user closes the dialog box, this flag specifies the user's selection.

FR_ENABLEHOOK

Enables the hook function specified in the lpfnHook member of this structure. This flag is used only to initialize the dialog box.

FR_ENABLETEMPLATE

Causes the system to create the dialog box by using the dialog box template identified by the hInstance and lpTemplateName members. 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

Indicates that the application should search for the next occurrence of the string specified by the lpstrFindWhat member.

FR_HIDEUPDOWN

Causes the system to hide the Direction check box and the Up and Down controls.

FR_HIDEMATCHCASE

Causes the system to hide the Match Case check box.

FR_HIDEWHOLEWORD

Causes the system to hide the Match Whole Word Only check box.

FR_MATCHCASE

Set for case-sensitive searches.

FR_NOMATCHCASE

Disables the Match Case check box. This flag is used only to initialize the dialog box.

FR_NOUPDOWN

Disables the direction radio buttons. This flag is used only to initialize the dialog box.

FR_NOWHOLEWORD

Disables the Whole Word check box. This flag is used only to initialize the dialog box.

FR_REPLACE

Indicates that the application should replace the current occurrence of the string specified in the lpstrFindWhat member with the string specified in the lpstrReplaceWith member.

FR_REPLACEALL

Indicates that the application should replace all occurrences of the string specified in the lpstrFindWhat member with the string specified in the lpstrReplaceWith member.

FR_SHOWHELP

Causes the dialog box to show the Help button. The hwndOwner member must not be NULL if this option is specified.

FR_WHOLEWORD

Checks the Whole Word check box. Only whole words matching the search string will be considered.

lpstrFindWhat	Specifies the string to search for. If there is a string specified when the dialog box starts, the dialog box initializes the Find What: text control with this string. If the FR_FINDNEXT flag is set when the dialog box is opened, the application should search for an occurrence of this string by using the FR_DOWN, FR_WHOLEWORD, and FR_MATCHCASE flags to further define the direction and type of search. The application must allocate a buffer for the string. This buffer should be at least 80 characters long.

lpstrReplaceWith	Specifies the replacement string for replace operations. The FindText function ignores this member.

wFindWhatLen	Specifies the length, in bytes, of the buffer pointed to by the lpstrFindWhat member points.

wReplaceWithLen	Specifies the length, in bytes, of the buffer pointed to by the lpstrReplaceWith member.

lCustData	Specifies application-defined data the system passes to the hook function identified by the lpfnHook member. The system passes the data in the lParam parameter of the WM_INITDIALOG message.

lpfnHook	Points to a hook function that processes messages intended for the dialog box. An application must specify the FR_ENABLEHOOK flag in the Flags member to enable the function; otherwise, the system ignores this structure member. The hook function should return FALSE to pass a message on to the standard dialog procedure, or TRUE to discard the message.

If the hook function returns FALSE in response to the WM_INITDIALOG message, it is responsible for displaying the dialog. This is done by calling the ShowWindow and UpdateWindow functions (note: remember to put these calls after any other paint operations). The following code snippet provides an example:

    /* we've returned FALSE in response to WM_INITDIALOG */

    /* we've performed any other paint operations */

    /* now we display the dialog */

    ShowWindow(hDlg, SW_SHOWNORMAL);

    UpdateWindow(hDlg);

If the hook function returns FALSE in response to the WM_INITDIALOG message, but fails to display the dialog, the dialog will not be shown.

lpstrTemplateName	Points to a null-terminated string that names the dialog box template resource to be substituted for the standard dialog box template. An application can use the MAKEINTRESOURCE macro for numbered dialog resources. This member is used only if the Flags member specifies the FR_ENABLETEMPLATE flag; otherwise, this member is ignored.

See Also

FindText, ReplaceText, WM_INITDIALOG, MAKEINTRESOURCE


FIXED structure
FIXED (Win32)

typedef struct _FIXED { /* fix */

    WORD  fract;

    short value;

} FIXED;

The FIXED structure contains the integral and fractional parts of a fixed-point real number.

Member	Description

fract	Specifies the fractional part of the number.

value	Specifies the integer part of the number.

Comments

The FIXED structure is used to describe the elements of the MAT2 structure.

See Also

MAT2


FMS_GETDRIVEINFO structure
FMS_GETDRIVEINFO (Win32)

typedef struct _FMS_GETDRIVEINFO { /* fmsgdi */

    DWORD dwTotalSpace;

    DWORD dwFreeSpace;

    CHAR  szPath[260];

    CHAR  szVolume[14];

    CHAR  szShare[128];

} 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).

Member	Description

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 structure
FMS_GETFILESEL (Win32)

typedef struct _FMS_GETFILESEL { /* fmsgfs */

    FILETIME ftTime;

    DWORD    dwSize;

    BYTE     bAttr;

    CHAR     szName[260];

} 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).

Member	Description

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, FM_GETFILESEL


FMS_HELPSTRING structure
FMS_HELPSTRING (Win32)

typedef struct tagFMS_HELPSTRING { /* fmshs */

    INT          idCommand ;

    HMENU        hMenu ;

    CHAR         szHelp[128] ;

} FMS_HELPSTRING;

The FMS_HELPSTRING structure contains information about ????.

Member	Description

idCommand	Specifies ?????????.

hMenu	Specifies ????????.

szHelp	Specifies ?????.

See Also

FMEVENT_HELPSTRING, FMEVENT_HELPMENUITEM


FMS_LOAD structure
FMS_LOAD (Win32)

typedef struct _FMS_LOAD { /* fmsld */

    DWORD dwSize;

    CHAR  szMenuName[MENU_TEXT_LEN];

    HMENU hMenu;

    UINT  wMenuDelta;

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

Member	Description

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 structure
FMS_TOOLBARLOAD (Win32)

typedef struct tagFMS_TOOLBARLOAD { /* fmstbl */

    DWORD        dwSize;

    LPEXT_BUTTON lpButtons;

    WORD         cButtons;

    WORD         cBitmaps;

    WORD         idBitmap;

    HBITMAP      hBitmap;

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

Member	Description

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 structure
FOCUS_EVENT_RECORD (Win32)

typedef struct _FOCUS_EVENT_RECORD { /* fer */

    BOOL bSetFocus;

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

Member	Description

bSetFocus	Used internally.

See Also

INPUT_RECORD


FORM_INFO_1 structure
FORM_INFO_1 (Win32)

typedef struct _FORM_INFO_1 { /* fi1 */

    LPTSTR pName;

    SIZEL  Size;

    RECTL  ImageableArea;

} FORM_INFO_1;

The FORM_INFO_1 structure identifies a form, specifies its dimensions, and specifies the dimensions of its printable area.

Member	Description

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 structure
FORMAT_PARAMETERS (Win32)

typedef struct _FORMAT_PARAMETERS{

   MEDIA_TYPE MediaType;

   DWORD StartCylinderNumber;

   DWORD EndCylinderNumber;

   DWORD StartHeadNumber;

   DWORD EndHeadNumber;

} FORMAT_PARAMETERS ;

The FORMAT_PARAMETERS structure provides information used in formatting a contiguous set of disk tracks.

Member	Description

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.

Comments

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


GENERIC_MAPPING structure
GENERIC_MAPPING (Win32)

typedef struct _GENERIC_MAPPING { /* gm */

    ACCESS_MASK GenericRead;

    ACCESS_MASK GenericWrite;

    ACCESS_MASK GenericExecute;

    ACCESS_MASK GenericAll;

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

Member	Description

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 structure
GLYPHMETRICS (Win32)

typedef struct _GLYPHMETRICS { /* glmt */

    UINT  gmBlackBoxX;

    UINT  gmBlackBoxY;

    POINT gmptGlyphOrigin;

    short gmCellIncX;

    short gmCellIncY;

} GLYPHMETRICS;

The GLYPHMETRICS structure contains information about the placement and orientation of a glyph in a character cell.

Member	Description

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.

Comments

Values in the GLYPHMETRICS structure are specified in logical units.

See Also

GetGlyphOutline, POINT


HANDLETABLE structure
HANDLETABLE (Win32)

typedef struct tagHANDLETABLE { /* ht */

    HGDIOBJ objectHandle[1];

} HANDLETABLE;

The HANDLETABLE structure is an array of handles, each of which identifies a graphics device interface (GDI) object.

Member	Description

objectHandle[1]	Contains an array of handles.


HELPWININFO structure
HELPWININFO (Win32)

typedef struct {    /* hi */

    int   wStructSize;

    int   x;

    int   y;

    int   dx;

    int   dy;

    int   wMax;

    TCHAR rgchMember[2];

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

Member	Description

wStructSize	Specifies the size of the HELPWININFO structure.

x	Specifies the x-coordinate of the upper left corner of the window.

y	Specifies the y-coordinate of the upper left corner of the window.

dx	Specifies the width of the window.

dy	Specifies the height of the window.

wMax	Specifies how the window is to be shown. This member must be one of the following values:

Value	Action

SW_HIDE	Hides the window and passes activation to another window.

SW_SHOWNORMAL	Activates and displays the window. Whether the window is minimized or maximized, Windows restores it to its original size and position.

SW_SHOWMINIMIZED	Activates the window and displays it as an icon.

SW_SHOWMAXIMIZED	Activates the window and displays it as a maximized window.

SW_SHOWNOACTIVATE	Displays a window in its most recent size and position. The window that is currently active remains active.

SW_SHOW	Activates a window and displays it in its current size and position.

SW_MINIMIZE	Minimizes the specified window and activates the top-level window in the Z order.

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_RESTORE	Same as SW_SHOWNORMAL.

rgchMember	Specifies the name of the window.

Comments

Microsoft 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


HSZPAIR structure
HSZPAIR (Win32)

typedef struct tagHSZPAIR {   /* hp */

    HSZ hszSvc;

    HSZ hszTopic;

} HSZPAIR;

The HSZPAIR structure contains a dynamic data exchange (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.

Member	Description

hszSvc	Identifies a service name.

hszTopic	Identifies a topic name.

See Also

XTYP_WILDCONNECT


ICONINFO structure
ICONINFO (Win32)

typedef struct _ICONINFO { /* ii */

   BOOL    fIcon;

   DWORD   xHotspot;

   DWORD   yHotspot;

   HBITMAP hbmMask;

   HBITMAP hbmColor;

} ICONINFO;

The ICONINFO structure contains information about an icon or a cursor.

Member	Description

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 defines the AND bitmask of the icon ONLY.

hbmColor	Identifies the icon color bitmap. This member can be optional if this structure defines a black and white icon. After the AND bitmask of hbmMask is applied with SRCAND to the destination, the color bitmap is applied (using XOR) to the destination by using SRCINVERT.

See Also

CreateIconIndirect, GetIconInfo


INPUT_RECORD structure
INPUT_RECORD (Win32)

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;

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.

Member	Description

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 input 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 a user action to change the console window size.

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

PeekConsoleInput, ReadConsoleInput, WriteConsoleInput


JOB_INFO_1 structure
JOB_INFO_1 (Win32)

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;

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.

Member	Description

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.

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.

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 structure
JOB_INFO_2 (Win32)

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;

The JOB_INFO_2 structure describes a full set of values associated with a job.

Member	Description

JobId	Specifies a job ID 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.

pSecurityDescriptor	This value 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.

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) elapsed since the job began printing.

PagesPrinted	Specifies the number of pages that have printed.

See Also

EnumJobs, GetJob, SetJob


JOYCAPS structure
JOYCAPS (Win32)

typedef struct joyinfo_tag {

    WORD  wMid;

    WORD  wPid;

    TCHAR  szPname[MAXPNAMELEN];

    UINT  wXmin;

    UINT  wXmax;

    UINT  wYmin;

    UINT  wYmax;

    UINT  wZmin;

    UINT  wZmax;

    UINT  wNumButtons;

    UINT  wPeriodMin;

    UINT  wPeriodMax;

} JOYCAPS;

The JOYCAPS structure stores joystick-capability information.

Member	Description

wMid	Specifies the manufacturer identifier of the joystick.

wPid	Specifies the product identifier of the joystick.

szPname	Specifies the product name of the joystick, stored as a null-terminated string.

wXmin	Specifies the minimum x-position of the joystick.

wXmax	Specifies the maximum x-position of the joystick.

wYmin	Specifies the minimum y-position of the joystick.

wYmax	Specifies the maximum y-position of the joystick.

wZmin	Specifies the minimum z-position of the joystick.

wZmax	Specifies the maximum z-position of the joystick.

wNumButtons	Specifies the number of buttons on the joystick.

wPeriodMin	Specifies the smallest polling interval supported when captured by the joySetCapture function.

wPeriodMax	Specifies the largest polling interval supported when captured by joySetCapture.

See Also

joyGetDevCaps


JOYINFO structure
JOYINFO (Win32)

typedef struct joyinfo_tag {

    UINT  wXpos;

    UINT  wYpos;

    UINT  wZpos;

    UINT  wButtons;

} JOYINFO;

The JOYINFO structure stores joystick-position and button-state information.

Member	Description

wXpos	Specifies the current x-position of the joystick.

wYpos	Specifies the current y-position of the joystick.

wZpos	Specifies the current z-position of the joystick.

wButtons	Specifies the current state of the joystick buttons. This member can be any combination of the following bit flags:

Value	Meaning

JOY_BUTTON1	Set if button 1 is pressed

JOY_BUTTON2	Set if button 2 is pressed

JOY_BUTTON3	Set if button 3 is pressed

JOY_BUTTON4	Set if button 4 is pressed

See Also

joyGetPos


KERNINGPAIR structure
KERNINGPAIR (Win32) (32-bit)

typedef struct tagKERNINGPAIR { /* kp */

    WORD wFirst;

    WORD wSecond;

    int  iKernAmount;

} KERNINGPAIR;

The KERNINGPAIR structure defines a kerning pair.

Member	Description

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 structure
KEY_EVENT_RECORD (Win32)

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;

The KEY_EVENT_RECORD structure is used to report keyboard input events in a console INPUT_RECORD structure.

Member	Description

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

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.

SHIFT_PRESSED	The SHIFT key is pressed.

NUMLOCK_ON	The NUM LOCK light is on.

SCROLLLOCK_ON	The SCROLL LOCK light is on.

CAPSLOCK_ON	The CAPS LOCK light is on.

ENHANCED_KEY	The key is enhanced.

Comments

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 structure
LANA_ENUM (Win32)

typedef struct _LANA_ENUM { /* le */

    UCHAR length;

    UCHAR lana[MAX_LANA];

} LANA_ENUM;

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

Member	Description

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

lana	Specifies an array of LAN adapter numbers.

Comments

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 structure
LARGE_INTEGER (Win32)

typedef struct _LARGE_INTEGER { /* li */

    DWORD LowPart;

    LONG  HighPart;

} LARGE_INTEGER;

The LARGE_INTEGER structure is used to represent a 64-bit signed integer value.

Member	Description

LowPart	Specifies the low-order 32 bits.

HighPart	Specifies the high-order 32 bits.

See Also

LUID, ULARGE_INTEGER


LDT_ENTRY structure
LDT_ENTRY (Win32)

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;

The LDT_ENTRY structure describes an entry in the descriptor table. This structure is valid only on x86-based systems.

Member	Description

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 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	The privilege level of the descriptor. This member is an integer value in the range 0 (most privileged) through 3 (least privileged).

Pres	The present flag. This member is 1 if the segment is present in physical memory; 0 if 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 64K, 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.

Comments

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 BaseLow, BaseMid, and BaseHi.

The limit of a segment is the address of the last byte that can be addressed in the segment. To calculate this value, combine LimitLow and LimitHi.

See Also

GetThreadSelectorEntry


LIST_ENTRY structure
LIST_ENTRY (Win32)

typedef struct _LIST_ENTRY { /* le */

    struct _LIST_ENTRY *Flink;

    struct _LIST_ENTRY *Blink;

} LIST_ENTRY;

The LIST_ENTRY structure is available for any entry in a double-linked list.

Member	Description

Flink	Points to the preceding entry in a double-linked list.

Blink	Points to the next entry in a double-linked list.

Comments

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 structure
LOAD_DLL_DEBUG_INFO (Win32)

typedef struct _LOAD_DLL_DEBUG_INFO { /* lddi */

    HANDLE hFile;

    LPVOID lpBaseOfDll;

    DWORD  dwDebugInfoFileOffset;

    DWORD  nDebugInfoSize;

    LPVOID lpImageName;

    WORD fUnicode;

} LOAD_DLL_DEBUG_INFO;

The LOAD_DLL_DEBUG_INFO structure contains information about a dynamic-link library (DLL) that has just been loaded.

Member	Description

hFile	Identifies a handle of the DLL. If hFile is NULL, the handle is not valid. Otherwise, hFile 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	Provides an optional pointer to the file name associated with the hFile parameter. The lpImageName parameter may be NULL, or may contain the address of a string pointer in the debuggee's address space. That address may in turn either be NULL, or point to the actual file name. If fUnicode is a non-zero value, the name string is Unicode; otherwise it is ANSI.

This parameter is strictly optional. Debuggers must be prepared to handle the case where lpImageName is NULL, OR *lpImageName (in the debuggee's address space) is NULL. Specifically, this release of Windows NT will never provide an image name for a create process event, and 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 debug events that originate from a call to the DebugActiveProcess function.

fUnicode	Indicates whether a file name specified by lpImageName is Unicode or ANSI. A non-zero value indicates Unicode; zero indicates ANSI.

See Also

CREATE_PROCESS_DEBUG_INFO, CREATE_THREAD_DEBUG_INFO, DEBUG_EVENT


LOGBRUSH structure
LOGBRUSH (Win32)

typedef struct tagLOGBRUSH { /* lb */

   UINT     lbStyle;

   COLORREF lbColor;

   LONG     lbHatch;

} LOGBRUSH;

The LOGBRUSH structure defines the style, color, and pattern of a physical brush. It is used by the CreateBrushIndirect and ExtCreatePen functions.

Member	Description

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.

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

If lbStyle is BS_SOLID or BS_HOLLOW, lbHatch is ignored.

Comments

Although lbColor controls the foreground color of a hatch brush, the SetBkMode and SetBkColor functions control the background color.

See Also

CreateBrushIndirect, ExtCreatePen, SetBkColor, SetBkMode, BITMAPINFO


LOGFONT structure
LOGFONT (Win32)

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;

   CHAR lfFaceName[LF_FACESIZE];

} LOGFONT;

The LOGFONT structure defines the attributes of a font.

Member	Description

lfHeight	Specifies the height, in logical units, of the font. The font height can be specified in one of three ways. If lfHeight is greater than zero, it is transformed into device units and matched against the cell height of the available fonts. If it is zero, a reasonable default size is used. If it is less than zero, it is transformed into device units and the absolute value is matched 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; if there is no such font, it looks for the smallest font available. This mapping occurs when the font is actually used for the first time.

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, of each line of text written in the font (relative to the bottom of the page).

lfOrientation	Specifies the angle, in tenths of degrees, of each character's base line (relative to the bottom of the page).

lfWeight	Specifies the weight of the font, in the range 0 through 1000 (for example, 400 is normal and 700 is bold). If lfWeight is zero, a default weight is used.

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

    OEM_CHARSET

    SYMBOL_CHARSET

    UNICODE_CHARSET

The OEM character set is system dependent.

Fonts with other character sets may exist in the system. If an application uses a font with an unknown character set, it should not attempt to translate or interpret strings that are to be rendered with that font.

lfOutPrecision	Specifies the output precision. The output precision defines how closely the output must match the requested font's height, width, character orientation, escapement, and pitch. It can be one of the following values:

    OUT_CHARACTER_PRECIS

    OUT_DEFAULT_PRECIS

    OUT_STRING_PRECIS

    OUT_STROKE_PRECIS

lfClipPrecision	Specifies the clipping precision. The clipping precision defines how to clip characters that are partially outside the clipping region. It can be one of the following values:

    CLIP_CHARACTER_PRECIS

    CLIP_DEFAULT_PRECIS

    CLIP_STROKE_PRECIS

lfQuality	Specifies the output quality. The output quality defines how carefully 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 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 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 (fixed-pitch), with or without serifs. Fixed-pitch fonts are usually modern. Pica, Elite, and CourierNew® are examples.

FF_ROMAN	Fonts with variable stroke width (proportionally spaced) 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 (proportionally spaced) and without serifs. MS® Sans Serif is an example.

lfFaceName	Points to a null-terminated string that specifies the typeface name of the font. The length of this string must not exceed 32 characters. The EnumFonts function can be used to enumerate the typeface names of all currently available fonts. If lfFaceName is NULL, GDI uses a default typeface.

See Also

CreateFontIndirect


LOGPALETTE structure
LOGPALETTE (Win32)

typedef struct tagLOGPALETTE { /* lgpl */

    WORD         palVersion;

    WORD         palNumEntries;

    PALETTEENTRY palPalEntry[1];

} LOGPALETTE;

The LOGPALETTE structure defines a logical color palette.

Member	Description

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.

Comments

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.

CreatePalette

See Also

PALETTEENTRY


LOGPEN structure
LOGPEN (Win32)

typedef struct tagLOGPEN { /* lgpn */

    UINT     lopnStyle;

    POINT    lopnWidth;

    COLORREF lopnColor;

} LOGPEN;

The LOGPEN structure defines the style, width, and color of a pen, a drawing object used to draw lines and borders. The CreatePenIndirect function uses the LOGPEN structure.

Member	Description

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.

Comments

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, RGB, POINT


LUID structure
LUID (Win32)

typedef LARGE_INTEGER 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.

See Also

AllocateLocallyUniqueId, LookupPrivilegeName, LookupPrivilegeValue, PrivilegeCheck, LUID_AND_ATTRIBUTES, PRIVILEGE_SET


LUID_AND_ATTRIBUTES structure
LUID_AND_ATTRIBUTES (Win32)

typedef struct _LUID_AND_ATTRIBUTES { /* luaa */

    LUID  Luid;

    DWORD Attributes;

} LUID_AND_ATTRIBUTES;

The LUID_AND_ATTRIBUTES structure represents a locally unique identifier (LUID) and its attributes.

Member	Description

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.

Comments

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


MAT2 structure
MAT2 (Win32)

typedef struct _MAT2 { /* mt2 */

    FIXED eM11;

    FIXED eM12;

    FIXED eM21;

    FIXED eM22;

} MAT2;

The MAT2 structure contains the values for a transformation matrix used by the GetGlyphOutline function.

Member	Description

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.

Comments

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, FIXED, GLYPHDATAINFO


MCI_ANIM_OPEN_PARMS structure
MCI_ANIM_OPEN_PARMS (Win32)

typedef struct {

    DWORD   dwCallback;

    MCIDEVICEID wDeviceID;

    LPCTSTR   lpstrDeviceType;

    LPCTSTR   lpstrElementName;

    LPCSTR   lpstrAlias;

    DWORD   dwStyle;

    HWND    hWndParent;

} MCI_ANIM_OPEN_PARMS;

The MCI_ANIM_OPEN_PARMS structure contains information for the MCI_OPEN command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

wDeviceID	Specifies the device identifier returned to the user.

lpstrDeviceType	Points to the name or constant identifier of the device type.

lpstrElementName	Points to the device-element name (usually a path).

lpstrAlias	Points to an optional device alias.

dwStyle	Specifies the window style.

hWndParent	Identifies the window to use as the parent window.

Comments

You can use the MCI_OPEN_PARMS structure in place of MCI_ANIM_OPEN_PARMS if you are not using the extended data members.

See Also

MCI_OPEN


MCI_ANIM_PLAY_PARMS structure
MCI_ANIM_PLAY_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwFrom;

    DWORD  dwTo;

    DWORD  dwSpeed;

} MCI_ANIM_PLAY_PARMS;

The MCI_ANIM_PLAY_PARMS structure contains parameters for the MCI_PLAY command message for animation devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwFrom	Specifies the position to play from.

dwTo	Specifies the position to play to.

dwSpeed	Specifies the play rate, in frames per second.

Comments

You can use the MCI_PLAY_PARMS structure in place of MCI_ANIM_PLAY_PARMS if you are not using the extended data members.

See Also

MCI_PLAY


MCI_ANIM_RECT_PARMS structure
MCI_ANIM_RECT_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    RECT  rc;

} MCI_ANIM_RECT_PARMS;

The MCI_ANIM_RECT_PARMS structure contains parameters for the MCI_PUT and MCI_WHERE command messages for animation devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

rc	Specifies a rectangle.

See Also

MCI_PUT, MCI_WHERE


MCI_ANIM_STEP_PARMS structure
MCI_ANIM_STEP_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwFrames;

} MCI_ANIM_STEP_PARMS;

The MCI_ANIM_STEP_PARMS structure contains parameters for the MCI_STEP command message for animation devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwFrames	Specifies the number of frames to step.

See Also

MCI_STEP


MCI_ANIM_UPDATE_PARMS structure
MCI_ANIM_UPDATE_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    RECT  rc;

    HDC  hDC;

} MCI_ANIM_UPDATE_PARMS;

The MCI_ANIM_UPDATE_PARMS structure contains parameters for the MCI_UPDATE command message for animation devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

rc	Specifies a window rectangle.

hDC	Identifies the device context.

See Also

MCI_UPDATE


MCI_ANIM_WINDOW_PARMS structure
MCI_ANIM_WINDOW_PARMS (Win32)

typedef struct tagMCI_ANIM_WINDOW_PARMS {

    DWORD  dwCallback;

    DWORD  hWnd;

    UINT  nCmdShow;

    LPCTSTR  lpstrText;

} MCI_ANIM_WINDOW_PARMS;

The MCI_ANIM_WINDOW_PARMS structure contains parameters for the MCI_WINDOW command message for animation devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

hWnd	Identifies the display window.

nCmdShow	Specifies how the window is displayed.

lpstrText	Points to a null-terminated string containing the window caption.

See Also

MCI_WINDOW


MCI_BREAK_PARMS structure
MCI_BREAK_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    int  nVirtKey;

    HWND  hwndBreak;

} MCI_BREAK_PARMS;

The MCI_BREAK_PARMS structure contains parameters for the MCI_BREAK command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

nVirtKey	Specifies the virtual-key code used for the break key.

hwndBreak	Identifies the window that must be the current window for break detection.

See Also

MCI_BREAK


MCI_GENERIC_PARMS structure
MCI_GENERIC_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

} MCI_GENERIC_PARMS;

The MCI_GENERIC_PARMS structure contains information for the Media Control Interface (MCI) command messages that have empty parameter lists. When assigning data to the members in this structure, set the corresponding MCI flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.


MCI_GETDEVCAPS_PARMS structure
MCI_GETDEVCAPS_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwReturn;

    DWORD  dwItem;

} MCI_GETDEVCAPS_PARMS;

The MCI_GETDEVCAPS_PARMS structure contains parameters for the MCI_GETDEVCAPS command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwReturn	Contains the return information on exit.

dwItem	Specifies the capability being queried.

See Also

MCI_GETDEVCAPS


MCI_INFO_PARMS structure
MCI_INFO_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    LPTSTR  lpstrReturn;

    DWORD  dwRetSize;

} MCI_INFO_PARMS;

The MCI_INFO_PARMS structure contains parameters for the MCI_INFO command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

lpstrReturn	Points to a user-defined buffer for the return string.

dwRetSize	Specifies the size, in bytes, of the buffer for the return string.

See Also

MCI_INFO


MCI_LOAD_PARMS structure
MCI_LOAD_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    LPCTSTR  lpfilename;

} MCI_LOAD_PARMS;

The MCI_LOAD_PARMS structure contains information for the MCI_LOAD command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

lpfilename	Points to a null-terminated string containing the filename of the device element to load.

See Also

MCI_LOAD


MCI_OPEN_PARMS structure
MCI_OPEN_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    MCIDEVICEID  wDeviceID;

    LPCTSTR  lpstrDeviceType;

    LPCTSTR  lpstrElementName;

    LPCTSTR  lpstrAlias;

} MCI_OPEN_PARMS;

The MCI_OPEN_PARMS structure contains information for the MCI_OPEN command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

wDeviceID	Contains the device identifier returned to the user.

lpstrDeviceType	Points to the name or constant identifier of the device type.

lpstrElementName	Points to the device-element name (usually a path).

lpstrAlias	Points to an optional device alias.

See Also

MCI_OPEN


MCI_OVLY_LOAD_PARMS structure
MCI_OVLY_LOAD_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    LPCTSTR  lpfilename;

    RECT  rc;

} MCI_OVLY_LOAD_PARMS;

The MCI_OVLY_LOAD_PARMS structure contains parameters for the MCI_LOAD command message for video overlay devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

lpfilename	Points to the buffer containing a null-terminated string.

rc	Specifies a rectangle.

See Also

MCI_LOAD


MCI_OVLY_OPEN_PARMS structure
MCI_OVLY_OPEN_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    MCIDEVICEID  wDeviceID;

    LPCTSTR  lpstrDeviceType;

    LPCTSTR  lpstrElementName;

    LPCTSTR  lpstrAlias;

    DWORD  dwStyle;

    HWND  hWndParent;

} MCI_OVLY_OPEN_PARMS;

The MCI_OVLY_OPEN_PARMS structure contains information for the MCI_OPEN command message for video overlay devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

wDeviceID	Specifies the device identifier returned to the user.

lpstrDeviceType	Points to the name or constant identifier of the device type obtained from the SYSTEM.INI file.

lpstrElementName	Points to the device-element name (usually a path).

lpstrAlias	Points to an optional device alias.

dwStyle	Specifies the window style.

hWndParent	Identifies the window to use as the parent window.

Comments

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_OVLY_RECT_PARMS structure
MCI_OVLY_RECT_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    RECT  rc;

} MCI_OVLY_RECT_PARMS;

The MCI_OVLY_RECT_PARMS structure contains parameters for the MCI_PUT and MCI_WHERE command messages for video overlay devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

rc	Specifies a rectangle.

See Also

MCI_PUT, MCI_WHERE


MCI_OVLY_SAVE_PARMS structure
MCI_OVLY_SAVE_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    LPCTSTR  lpfilename;

    RECT  rc;

} MCI_OVLY_SAVE_PARMS;

The MCI_OVLY_SAVE_PARMS structure contains parameters for the MCI_SAVE command message for video overlay devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

lpfilename	Points to the buffer containing a null-terminated string.

rc	Specifies a rectangle.

See Also

MCI_SAVE


MCI_OVLY_WINDOW_PARMS structure
MCI_OVLY_WINDOW_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    HWND   hWnd;

    UINT   nCmdShow;

    LPCTSTR  lpstrText;

} MCI_OVLY_WINDOW_PARMS;

The MCI_OVLY_WINDOW_PARMS structure contains parameters for the MCI_WINDOW command message for video overlay devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

hWnd	Identifies the display window.

nCmdShow	Specifies how the window is displayed.

lpstrText	Points to a null-terminated buffer containing the window caption.

See Also

MCI_WINDOW


MCI_PLAY_PARMS structure
MCI_PLAY_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwFrom;

    DWORD  dwTo;

} MCI_PLAY_PARMS;

The MCI_PLAY_PARMS structure contains parameters for the MCI_PLAY command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwFrom	Specifies the position to play from.

dwTo	Specifies the position to play to.

See Also

MCI_PLAY


MCI_RECORD_PARMS structure
MCI_RECORD_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwFrom;

    DWORD  dwTo;

} MCI_RECORD_PARMS;

The MCI_RECORD_PARMS structure contains parameters for the MCI_RECORD command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwFrom	Specifies the position to play from.

dwTo	Specifies the position to play to.

See Also

MCI_RECORD


MCI_SAVE_PARMS structure
MCI_SAVE_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    LPCTSTR  lpfilename;

} MCI_SAVE_PARMS;

The MCI_SAVE_PARMS structure contains information for the MCI_SAVE command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

lpfilename	Points to the buffer containing a null-terminated string.

See Also

MCI_SAVE


MCI_SEEK_PARMS structure
MCI_SEEK_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwTo;

} MCI_SEEK_PARMS;

The MCI_SEEK_PARMS structure contains parameters for the MCI_SEEK command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwTo	Specifies the position to seek to.

See Also

MCI_SEEK


MCI_SEQ_SET_PARMS structure
MCI_SEQ_SET_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwTimeFormat;

    DWORD  dwAudio;

    DWORD  dwTempo;

    DWORD  dwPort;

    DWORD  dwSlave;

    DWORD  dwMaster;

    DWORD  dwOffset;

} MCI_SEQ_SET_PARMS;

The MCI_SEQ_SET_PARMS structure contains parameters for the MCI_SET command message for Musical Instrument Digital Interface (MIDI) sequencer devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwTimeFormat	Specifies the time format of the sequencer.

dwAudio	Specifies the audio output channel.

dwTempo	Specifies the tempo.

dwPort	Specifies the output port.

dwSlave	Specifies the type of synchronization used by the sequencer for slave operation.

dwMaster	Specifies the type of synchronization used by the sequencer for master operation.

dwOffset	Specifies the data offset.

See Also

MCI_SET


MCI_SET_PARMS structure
MCI_SET_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwTimeFormat;

    DWORD  dwAudio;

} MCI_SET_PARMS;

The MCI_SET_PARMS structure contains parameters for the MCI_SET command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwTimeFormat	Specifies the time format used by the device.

dwAudio	Specifies the audio output channel.

See Also

MCI_SET


MCI_SOUND_PARMS structure
MCI_SOUND_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    LPCTSTR  lpstrSoundName;

} MCI_SOUND_PARMS;

The MCI_SOUND_PARMS structure contains parameters for the MCI_SOUND command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

lpstrSoundName	Points to a null-terminated string containing the name of the sound or the name of the file containing the sound to be played.

See Also

MCI_SOUND


MCI_STATUS_PARMS structure
MCI_STATUS_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwReturn;

    DWORD  dwItem;

    DWORD  dwTrack;

} MCI_STATUS_PARMS;

The MCI_STATUS_PARMS structure contains parameters for the MCI_STATUS command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwReturn	Contains the return information on exit.

dwItem	Specifies the capability being queried.

dwTrack	Specifies the length or number of tracks.

See Also

MCI_STATUS


MCI_SYSINFO_PARMS structure
MCI_SYSINFO_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    LPTSTR  lpstrReturn;

    DWORD  dwRetSize;

    DWORD  dwNumber;

    UINT  wDeviceType;

} MCI_SYSINFO_PARMS;

The MCI_SYSINFO_PARMS structure contains parameters for the MCI_SYSINFO command message. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

lpstrReturn	Points to a user-defined buffer for the return string. When the MCI_SYSINFO_QUANTITY flag is used,  lpstrReturn is evaluated as a LPDWORD, and a doubleword value is stored.

dwRetSize	Specifies the size, in bytes, of the buffer for the return string.

dwNumber	Specifies a 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	Specifies the type of device.

See Also

MCI_SYSINFO


MCI_VD_ESCAPE_PARMS structure
MCI_VD_ESCAPE_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    LPCTSTR  lpstrCommand;

} MCI_VD_ESCAPE_PARMS;

The MCI_VD_ESCAPE_PARMS structure contains parameters for the MCI_ESCAPE command message for videodisc devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

lpstrCommand	Points to a null-terminated buffer containing the command to send to the device.

See Also

MCI_ESCAPE


MCI_VD_PLAY_PARMS structure
MCI_VD_PLAY_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwFrom;

    DWORD  dwTo;

    DWORD  dwSpeed;

} MCI_VD_PLAY_PARMS;

The MCI_VD_PLAY_PARMS structure contains parameters for the MCI_PLAY command message for videodiscs. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwFrom	Specifies the position to play from.

dwTo	Specifies the position to play to.

dwSpeed	Specifies the playing speed, in frames per second.

Comments

You can use the MCI_PLAY_PARMS structure in place of MCI_VD_PLAY_PARMS if you are not using the extended data members.

See Also

MCI_PLAY


MCI_VD_STEP_PARMS structure
MCI_VD_STEP_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwFrames;

} MCI_VD_STEP_PARMS;

The MCI_VD_STEP_PARMS structure contains parameters for the MCI_STEP command message for videodiscs. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwFrames	Specifies the number of frames to step.

See Also

MCI_STEP


MCI_WAVE_DELETE_PARMS structure
MCI_WAVE_DELETE_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    DWORD  dwFrom;

    DWORD  dwTo;

} MCI_WAVE_DELETE_PARMS;

The MCI_WAVE_DELETE_PARMS structure contains parameters for the MCI_DELETE command message for waveform audio devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwFrom	Specifies the starting position for the delete operation.

dwTo	Specifies the end position for the delete operation.

See Also

MCI_DELETE


MCI_WAVE_OPEN_PARMS structure
MCI_WAVE_OPEN_PARMS (Win32)

typedef struct {

    DWORD  dwCallback;

    MCIDEVICEID  wDeviceID;

    LPCTSTR  lpstrDeviceType;

    LPCTSTR  lpstrElementName;

    LPCTSTR  lpstrAlias;

    DWORD  dwBufferSeconds;

} MCI_WAVE_OPEN_PARMS;

The MCI_WAVE_OPEN_PARMS structure contains information for the MCI_OPEN command message for waveform audio devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

wDeviceID	Specifies the device identifier returned to the user.

lpstrDeviceType	Points to the name or constant identifier of the device type obtained.

lpstrElementName	Points to the device-element name (usually a path).

lpstrAlias	Points to an optional device alias.

dwBufferSeconds	Specifies the buffer length, in seconds.

Comments

You can use the MCI_OPEN_PARMS structure in place of MCI_WAVE_OPEN_PARMS if you are not using the extended data members.

See Also

MCI_OPEN


MCI_WAVE_SET_PARMS structure
MCI_WAVE_SET_PARMS (Win32)

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;

The MCI_WAVE_SET_PARMS structure contains parameters for the MCI_SET command message for waveform audio devices. When assigning data to the members in this structure, set the corresponding Media Control Interface (MCI) flags in the fdwCommand parameter of the mciSendCommand function to validate the members.

Member	Description

dwCallback	Specifies a window handle used for the MCI_NOTIFY flag.

dwTimeFormat	Specifies the time format used by the device.

dwAudio	Specifies the channel used for audio output.

wInput	Specifies the channel used for audio input.

wOutput	Specifies the channel used for output.

wFormatTag	Specifies the interpretation of the waveform data.

wReserved2	Reserved; do not use.

nChannels	Specifies monaural (1) or stereo data (2).

wReserved3	Reserved; do not use.

nSamplesPerSec	Specifies the samples per second used for the waveform.

nAvgBytesPerSec	Specifies the sample rate, in bytes per second.

nBlockAlign	Specifies the block alignment of the data.

wReserved4	Reserved; do not use.

wBitsPerSample	Specifies the number of bits per sample.

wReserved5	Reserved; do not use.

See Also

MCI_SET


MDICREATESTRUCT structure
MDICREATESTRUCT (Win32)

typedef struct tagMDICREATESTRUCT { /* mdic */

    LPCTSTR szClass;

    LPCTSTR szTitle;

    HANDLE  hOwner;

    int     x;

    int     y;

    int     cx;

    int     cy;

    DWORD   style;

    LPARAM  lParam;

} MDICREATESTRUCT;

The MDICREATESTRUCT structure contains information about the class, title, owner, location, and size of a multiple document interface (MDI) child window.

Member	Description

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

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

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

style	Specifies the style of the MDI child window. If the MDI client window was 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	Description

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.

Comments

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


MEASUREITEMSTRUCT structure
MEASUREITEMSTRUCT (Win32)

typedef struct tagMEASUREITEMSTRUCT {   /* mis */

    UINT  CtlType;

    UINT  CtlID;

    UINT  itemID;

    UINT  itemWidth;

    UINT  itemHeight;

    DWORD itemData;

} MEASUREITEMSTRUCT;

The MEASUREITEMSTRUCT structure informs Windows of the dimensions of an owner-drawn control. This allows Windows to process user interaction with the control correctly.

Member	Description

CtlType	Specifies the control type. This member can be one of the following values:

Value	Description

ODT_BUTTON	Owner-drawn button

ODT_COMBOBOX	Owner-drawn combo box

ODT_LISTBOX	Owner-drawn list box

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 menu item identifier for a menu item or the list box item identifier for a variable-height list box or combo box. This member is not used for a fixed-height list box or combo box, or for a button.

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

Comments

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

WM_MEASUREITEM


MEDIA_TYPE structure
MEDIA_TYPE (Win32)

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;

The MEDIA_TYPE enumerated type provides a set of enumerators to describe various forms of device media. The comments above explain the enumerators.

Comments

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, IOCTL_DISK_GET_DRIVE_GEOMETRY, IOCTL_DISK_GET_MEDIA_TYPES, DISK_GEOMETRY


MEMORY_BASIC_INFORMATION structure
MEMORY_BASIC_INFORMATION (Win32)

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;

The MEMORY_BASIC_INFORMATION structure contains information about a range of pages in the process's virtual address space. The VirtualQuery and VirtualQueryEx functions use this structure.

Member	Description

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:

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 execution 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 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/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 value 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	No cacheing of the committed regions of pages is allowed. 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 no cache. This value 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:

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

VirtualQuery, VirtualQueryEx


MEMORYSTATUS structure
MEMORYSTATUS (Win32)

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;

The MEMORYSTATUS structure contains information about current memory availability. The GlobalMemoryStatus function uses this structure.

Member	Description

dwLength	Indicates the size of this structure. The calling process should set this member prior to calling the GlobalMemoryStatus function.

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.


MENU_EVENT_RECORD structure
MENU_EVENT_RECORD (Win32)

typedef struct _MENU_EVENT_RECORD { /* mer */

    UINT dwCommandId;

} MENU_EVENT_RECORD, *PMENU_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.

Member	Description

dwCommandId	Used internally.

See Also

INPUT_RECORD


MENUITEMTEMPLATE structure
MENUITEMTEMPLATE (Win32)

typedef struct {    /* mit */

    WORD mtOption;

    WORD mtID;

    WCHAR mtString[1];

} MENUITEMTEMPLATE;

The MENUITEMTEMPLATE structure defines a menu item in a menu template.

Member	Description

mtOption	Specifies a mask of 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 a pop-up item (a pop-up item invokes a pop-up menu when the user chooses the item).

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 a pop-up menu item does not contain the mtID member.

mtString	Specifies the null-terminated string for the menu item.

See Also

LoadMenuIndirect, MENUITEMTEMPLATEHEADER


MENUITEMTEMPLATEHEADER structure
MENUITEMTEMPLATEHEADER (Win32)

typedef struct {    /* mith */

    WORD versionNumber;

    WORD offset;

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

Member	Description

versionNumber	Specifies the version number. This member should 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.

Comments

One or more MENUITEMTEMPLATE structures are combined to form the menu item list.

See Also

LoadMenuIndirect, MENUITEMTEMPLATE


METAFILEPICT structure
METAFILEPICT (Win32)

typedef struct tagMETAFILEPICT { /* mfp */

    LONG      mm;

    LONG      xExt;

    LONG      yExt;

    HMETAFILE hMF;

} METAFILEPICT;

The METAFILEPICT structure defines the metafile picture format used for exchanging metafile data through the clipboard.

Member	Description

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 structure
METAHEADER (Win32)

typedef struct tagMETAHEADER {  /* mh */

    WORD  mtType;

    WORD  mtHeaderSize;

    WORD  mtVersion;

    DWORD mtSize;

    WORD  mtNoObjects;

    DWORD mtMaxRecord;

    WORD  mtNoParameters;

} METAHEADER;

The METAHEADER structure contains information about a metafile.

Member	Description

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 structure
METARECORD (Win32)

typedef struct tagMETARECORD {  /* mr */

    DWORD rdSize;

    WORD  rdFunction;

    WORD  rdParm[1];

} METARECORD;

The METARECORD structure contains a metafile record.

Member	Description

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


MIDIHDR structure
MIDIHDR (Win32)

typedef struct midihdr_tag {

    LPSTR  lpData;

    DWORD  dwBufferLength;

    DWORD  dwBytesRecorded;

    DWORD  dwUser;

    DWORD  dwFlags;

    struct midihdr_tag *lpNext;

    DWORD  reserved;

} MIDIHDR;

The MIDIHDR structure defines the header used to identify a Musical Instrument Digital Interface (MIDI) system-exclusive data buffer.

Member	Description

lpData	Points to the system-exclusive data buffer.

dwBufferLength	Specifies the length of the data buffer.

dwBytesRecorded	Specifies the amount of data in the buffer, if the header is used in input.

dwUser	Specifies user data.

dwFlags	Specifies flags giving information about the data buffer. This member can be one of the following values:

Value	Meaning

MHDR_DONE	Set by the device driver to indicate that it is finished with the data buffer and is returning it to the application.

MHDR_PREPARED	Set by Windows to indicate that the data buffer has been prepared with midiInPrepareHeader or midiOutPrepareHeader.

lpNext	Reserved; do not use.

reserved	Reserved; do not use.


MIDIINCAPS structure
MIDIINCAPS (Win32)

typedef struct midiincaps_tag {

    WORD  wMid;

    WORD  wPid;

    MMVERSION  vDriverVersion;

    TCHAR  szPname[MAXPNAMELEN];

} MIDIINCAPS;

The MIDIINCAPS structure describes the capabilities of a Musical Instrument Digital Interface (MIDI) input device.

Member	Description

wMid	Specifies a manufacturer identifier for the device driver for the MIDI input device.

wPid	Specifies a product identifier for the MIDI input device.

vDriverVersion	Specifies the 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	Specifies the product name in a null-terminated string.

See Also

midiInGetDevCaps


MIDIOUTCAPS structure
MIDIOUTCAPS (Win32)

typedef struct midioutcaps_tag {

    WORD  wMid;

    WORD  wPid;

    MMVERSION  vDriverVersion;

    TCHAR  szPname[MAXPNAMELEN];

    WORD  wTechnology;

    WORD  wVoices;

    WORD  wNotes;

    WORD  wChannelMask;

    DWORD  dwSupport;

} MIDIOUTCAPS;

The MIDIOUTCAPS structure describes the capabilities of a Musical Instrument Digital Interface (MIDI) output device.

Member	Description

wMid	Specifies a manufacturer identifier for the device driver for the MIDI output device.

wPid	Specifies a product identifier for the MIDI output device.

vDriverVersion	Specifies the 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	Specifies the product name in a null-terminated string.

wTechnology	Specifies the type of the MIDI output device. This member can be one of the following values:

Value	Meaning

MOD_MIDIPORT	MIDI hardware port

MOD_SQSYNTH	Square wave synthesizer

MOD_FMSYNTH	FM synthesizer

MOD_MAPPER	Microsoft MIDI Mapper

wVoices	Specifies the number of voices supported by an internal synthesizer device. If the device is a port, this member is not meaningful and is set to zero.

wNotes	Specifies the maximum number of notes that may be played simultaneously by an internal synthesizer device. If the device is a port, this member is not meaningful and is set to zero.

wChannelMask	Specifies the 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 transmit on all channels; if the device is a port, this member is set to 0xFFFF.

dwSupport	Specifies optional functionality supported by the device. This member can be one or more of the following values:

Value	Meaning

MIDICAPS_VOLUME	Supports volume control.

MIDICAPS_LRVOLUME	Supports separate left and right volume control.

MIDICAPS_CACHE	Supports patch caching.

Comments

If a device supports volume changes, the MIDICAPS_VOLUME flag is 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 are set for this member.

See Also

midiOutGetDevCaps


MINMAXINFO structure
MINMAXINFO (Win32))

typedef struct tagMINMAXINFO {  /* mmi */

    POINT ptReserved;

    POINT ptMaxSize;

    POINT ptMaxPosition;

    POINT ptMinTrackSize;

    POINT ptMaxTrackSize;

} MINMAXINFO;

The MINMAXINFO structure contains information about a window's maximized size and position and its minimum and maximum tracking size.

Member	Description

ptReserved	Reserved for internal 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


MMCKINFO structure
MMCKINFO (Win32)

typedef struct _MMCKINFO {

    FOURCC  ckid;

    DWORD  cksize;

    FOURCC  fccType;

    DWORD  dwDataOffset;

    DWORD  dwFlags;

} MMCKINFO;

The MMCKINFO structure contains information about a chunk in a Resource Interchange File Format (RIFF) file.

Member	Description

ckid	Specifies the identifier of the chunk.

cksize	Specifies the size 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 field.

fccType	Specifies the form type for RIFF chunks or the list type for LIST chunks.

dwDataOffset	Specifies the file offset of the beginning of the chunk's data member, relative to the beginning of the file.

dwFlags	Specifies flags giving additional information about the chunk. This value can be MMIO_DIRTY, which specifies that the length of the chunk may have changed and should be updated by the mmioAscend function. This flag is set when a chunk is created by the mmioCreateChunk function.


MMIOINFO structure
MMIOINFO (Win32)

typedef struct _MMIOINFO {

    DWORD  dwFlags;

    FOURCC  fccIOProc;

    LPMMIOPROC  pIOProc;

    UINT  wErrorRet;

    HANDLE  htask;

    LONG  cchBuffer;

    LPSTR  pchBuffer;

    LPSTR  pchNext;

    LPSTR  pchEndRead;

    LPSTR  pchEndWrite;

    LONG  lBufOffset;

    LONG  lDiskOffset;

    DWORD  adwInfo[3];

    DWORD  dwReserved1;

    DWORD  dwReserved2;

    HMMIO  hmmio;

} MMIOINFO;

This MMIOINFO structure contains the current state of a file opened by using the mmioOpen function.

Member	Description

dwFlags	Specifies flags indicating how a file was opened. This member can be one of the following values:

Value	Meaning

MMIO_READ	The file was opened for reading only.

MMIO_WRITE	The file was opened for writing only.

MMIO_READWRITE	The file was opened for both reading and writing.

MMIO_COMPAT	The file was opened in compatibility mode, allowing any process on a given computer to open the file any number of times.

MMIO_EXCLUSIVE	The file was opened in exclusive mode, denying other processes both read and write access to the file.

MMIO_DENYWRITE	Other processes are denied write access to the file.

MMIO_DENYREAD	Other processes are denied read access to the file.

MMIO_DENYNONE	Other processes are not denied read or write access to the file.

MMIO_CREATE	The mmioOpen function was directed to create the file or truncate it to zero length if it already existed.

MMIO_ALLOCBUF	The file's input and output (I/O) buffer was allocated by the mmioOpen or mmioSetBuffer function.

fccIOProc	Specifies the four-character code identifying the file's I/O procedure. If the I/O procedure is not an installed I/O procedure, fccIOProc is NULL.

pIOProc	Points to the file's I/O procedure.

wErrorRet	Contains the extended error value from the mmioOpen function, if mmioOpen returns NULL. This member does not receive extended error information from any other functions.

htask	Identifies the task.

cchBuffer	Specifies the size of the file's I/O buffer, in characters. If the file does not have an I/O buffer, this member is zero.

pchBuffer	Points to the file's I/O buffer. If the file does not have an I/O buffer, pchBuffer is NULL.

pchNext	Points to the next location to be read from or written to in the I/O buffer. If no more bytes can be read without calling the mmioAdvance or mmioRead function, this member points to pchEndRead. If no more bytes can be written without calling the mmioAdvance or mmioWrite function, this member points to pchEndWrite.

pchEndRead	Points to the location that is one byte past the last location in the buffer that can be read from.

pchEndWrite	Points to the location that is one byte past the last location in the buffer that can be written to.

lBufOffset	Reserved for internal use by multimedia file I/O functions; do not use.

lDiskOffset	Specifies the current file position. The current file position is an offset, in bytes, from the beginning of the file. I/O procedures are responsible for maintaining this member.

adwInfo	Contains state information maintained by the I/O procedure. I/O procedures can also use this member to transfer information from the caller to the I/O procedure when the caller opens a file.

dwReserved1	Reserved for internal use by multimedia file I/O functions; do not use.

dwReserved2	Reserved for internal use by multimedia file I/O functions; do not use.

hmmio	Identifies the open file. File I/O procedures can use this type HMMIO handle when calling other multimedia file I/O functions.

See Also

mmioGetInfo


MMTIME structure
MMTIME (Win32)

typedef struct mmtime_tag {

    WORD  wType;

    union {

        DWORD  ms;

        DWORD  sample;

        DWORD  cb;

        struct {

            BYTE  hour;

            BYTE  min;

            BYTE  sec;

            BYTE  frame;

            BYTE  fps;

            BYTE  dummy;

        } smpte;

        struct {

            DWORD  songptrpos;

        } midi;

    } u;

} MMTIME;

The MMTIME structure is a general-purpose structure for timing information.

Member	Description

wType	Specifies the type of the union. This member can be one of the following values:

Value	Meaning

TIME_MS	Time counted in milliseconds

TIME_SAMPLES	Number of wave samples

TIME_BYTES	Current byte offset

TIME_SMPTE	Society of Motion Picture and Television Engineers (SMPTE) time

TIME_MIDI	Musical Instrument Digital Interface (MIDI) time

u	Specifies the contents of the union. The following members are contained in the u union:

Member	Meaning

ms	Milliseconds. Used when the wType member of the MMTIME structure is TIME_MS.

sample	Samples. Used when wType is TIME_SAMPLES.

cb	Byte count. Used when wType is TIME_BYTES.

smpte	SMPTE time. Used when wType is TIME_SMPTE. The following members are contained in the smpte structure:

Member	Meaning

hour	Hours

min	Minutes

sec	Seconds

frame	Frames

fps	Frames per second (24, 25, 29[30 drop] or 30)

dummy	Dummy byte for alignment

midi	MIDI time. Used when wType is TIME_MIDI. The following member is contained in the midi structure:

Member	Meaning

songptrpos	Song pointer position


MONCBSTRUCT structure
MONCBSTRUCT (Win32)

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;

The MONCBSTRUCT structure contains information about the current dynamic data exchange (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.

Member	Description

cb	Specifies the length, in bytes, of the structure.

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, XTYP_MONITOR


MONCONVSTRUCT structure
MONCONVSTRUCT (Win32)

typedef struct tagMONCONVSTRUCT { /* mcvst */

    UINT   cb;

    BOOL   fConnect;

    DWORD  dwTime;

    HANDLE hTask;

    HSZ    hszSvc;

    HSZ    hszTopic;

    HCONV  hConvClient;

    HCONV  hConvServer;

} MONCONVSTRUCT;

The MONCONVSTRUCT structure contains information about a conversation. A DDE monitoring application can use this structure to obtain information about a conversation that has been established or has terminated.

Member	Description

cb	Specifies the length, in bytes, of the structure.

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

hConvServer	Identifies the server conversation handle.

Comments

In Windows NT, string handles are local to the process; therefore, the hszSvc and hszTopic members are global atoms.

In Windows NT, 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, XTYP_MONITOR


MONERRSTRUCT structure
MONERRSTRUCT (Win32)

typedef struct tagMONERRSTRUCT { /* mest */

    UINT   cb;

    UINT   wLastError;

    DWORD  dwTime;

    HANDLE hTask;

} MONERRSTRUCT;

The MONERRSTRUCT structure contains information about the current dynamic data exchange (DDE) error. A DDE monitoring application can use this structure to monitor errors returned by DDE Management Library functions.

Member	Description

cb	Specifies the length, in bytes, of the structure.

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, XTYP_MONITOR


MONHSZSTRUCT structure
MONHSZSTRUCT (Win32)

typedef struct tagMONHSZSTRUCT { /* mhst */

    UINT   cb;

    BOOL   fsAction;

    DWORD  dwTime;

    HSZ    hsz;

    HANDLE hTask;

    char   str[1];

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

Member	Description

cb	Specifies the length, in bytes, of the structure.

fsAction	Specifies the action being performed on the string handle specified 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 use 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. In Windows NT, string handles are local to the process; therefore, 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, DdeCreateStringHandle, DdeFreeStringHandle, DdeKeepStringHandle, DdeUninitialize


MONITOR_INFO_1 #$ structure
MONITOR_INFO_1

typedef struct _MONITOR_INFO_1 { /* mi1 */

    LPTSTR pName;

} MONITOR_INFO_1;

The MONITOR_INFO_1 structure identifies an installed monitor.

Member	Description

pName	Points to a null-terminated string that identifies an installed monitor.

See Also

EnumMonitors, MONITOR_INFO_2


MONITOR_INFO_2 #$ structure
MONITOR_INFO_2

typedef struct _MONITOR_INFO_2 { /* mi2 */

    LPTSTR pName;

    LPTSTR pEnvironment ;

    LPTSTR pDLLName ;

} MONITOR_INFO_2;

The MONITOR_INFO_2 structure identifies a monitor.

Member	Description

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 this DLL is designed to run in.

pDLLName	Points to a null-terminated string that is the name of the monitor DLL.

See Also

EnumMonitors, MONITOR_INFO_1


MONLINKSTRUCT structure
MONLINKSTRUCT (Win32)

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;

The MONLINKSTRUCT structure contains information about a dynamic data exchange (DDE) advise loop. A DDE monitoring application can use this structure to obtain information about an advise loop that has started or ended.

Member	Description

cb	Specifies the length, in bytes, of the structure.

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. In Windows NT, string handles are local to the process; therefore, this member is a global atom.

hszTopic	Identifies the topic name on which the advise loop is established. In Windows NT, string handles are local to the process; therefore, this member is a global atom.

hszItem	Identifies the item name that is the subject of the advise loop. In Windows NT, string handles are local to the process; therefore, this member is a global atom.

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.

Comments

In Windows NT, string handles are local to the process; therefore, the hszSvc, hszTopic, and hszItem members are actually global atoms.

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, MONMSGSTRUCT, XTYP_MONITOR


MONMSGSTRUCT structure
MONMSGSTRUCT (Win32)

typedef struct tagMONMSGSTRUCT { /* mmst */

    UINT   cb;

    HWND   hwndTo;

    DWORD  dwTime;

    HANDLE hTask;

    UINT   wMsg;

    WPARAM wParam;

    LPARAM lParam;

    DDEML_MSG_HOOK_DATA dmhd;

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

Member	Description

cb	Specifies the length, in bytes, of the structure.

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, XTYP_MONITOR


MOUSE_EVENT_RECORD structure
MOUSE_EVENT_RECORD (Win32)

typedef struct _MOUSE_EVENT_RECORD { /* mer */

    COORD dwMousePosition;

    DWORD dwButtonState;

    DWORD dwControlKeyState;

    DWORD dwEventFlags;

} MOUSE_EVENT_RECORD;

The MOUSE_EVENT_RECORD structure is used in a console INPUT_RECORD structure to report mouse input events.

Member	Description

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.

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.

SHIFT_PRESSED	The SHIFT key is pressed.

NUMLOCK_ON	The NUM LOCK light is on.

SCROLLLOCK_ON	The SCROLL LOCK light is on.

CAPSLOCK_ON	The CAPS LOCK light is on.

ENHANCED_KEY	The key is enhanced.

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

MOUSE_MOVED	A change in mouse position occurred.

DOUBLE_CLICK	The second click (button press) of a double-click occurred. The first click is returned as a regular button-press event.

Comments

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

PeekConsoleInput, ReadConsoleInput, WriteConsoleInput


MOUSEHOOKSTRUCT structure
MOUSEHOOKSTRUCT (Win32)

typedef struct tagMOUSEHOOKSTRUCT { /* ms */

    POINT pt;

    HWND  hwnd;

    UINT  wHitTestCode;

    DWORD dwExtraInfo;

} MOUSEHOOKSTRUCT;

The MOUSEHOOKSTRUCT structure contains information about a mouse event.

Member	Description

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.

wHitTextCode	Specifies the hit-test code. For a list of hit-test codes, see the description of the WM_NCHITTEST message.

dwExtraInfo	Specifies extra information associated with the message.

See Also

GetMessageExtraInfo, SetWindowsHook


MSG structure
MSG (Win32)

typedef struct tagMSG {     /* msg */

    HWND   hwnd;

    UINT   message;

    WPARAM wParam;

    LPARAM lParam;

    DWORD  time;

    POINT  pt;

} MSG;

The MSG structure contains message information from a thread's message queue.

Member	Description

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


MULTIKEYHELP structure
MULTIKEYHELP (Win32)

typedef struct tagMULTIKEYHELP { /* mkh */

    DWORD mkSize;

    BYTE  mkKeylist;

    TCHAR szKeyphrase[1];

} MULTIKEYHELP;

The MULTIKEYHELP structure specifies a keyword table and an associated keyword to be used by the Windows Help application.

Member	Description

mkSize	Specifies the length, in bytes, of the MULTIKEYHELP structure.

mkKeylist	Specifies a single character that identifies the keyword table to be searched.

szKeyphrase[]	Contains a null-terminated text string that specifies the keyword to be located in the keyword table.

See Also

WinHelp


NAME_BUFFER structure
NAME_BUFFER (Win32)

typedef struct _NAME_BUFFER { /* nb */

    UCHAR name[NCBNAMSZ];

    UCHAR name_num;

    UCHAR name_flags;

} 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 NCBASTAT in the ncb_command member of the NCB structure.

Member	Description

name	Specifies the local network name. This is the value in the ncb_name member of the NCB structure.

name_num	Specifies the number for the local network name. This is the value 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 using the NCBADDGRNAME command.

UNIQUE_NAME	The name specified by the name member was created with using the NCBADDNAME command.

See Also

ADAPTER_STATUS, NCB


NCB structure
NCB (Win32)

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;

The NCB structure describes a network-control block. A pointer to this structure is passed to the Netbios function.

Member	Description

ncb_command	Specifies the command code and a flag that indicates whether the NCB 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 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 value 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	Add a group name to the local name table.

NCBADDNAME	Add a unique name to the local name table.

NCBASTAT	Retrieve the status of the adapter. When this value 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	Open a session with another name.

NCBCANCEL	Cancel a previous command.

NCBCHAINSEND	Send the contents of two data buffers to the specified session partner. For Windows NT, this is equivalent to the NCBCHAINSENDNA command.

NCBCHAINSENDNA	Send the contents of two data buffers to the specified session partner and do not wait for acknowledgment. For Windows NT, this is equivalent to the NCBCHAINSEND command.

NCBDELNAME	Delete a name from the local name table.

NCBDGRECV	Receive a datagram from any name.

NCBDGRECVBC	Receive broadcast datagram from any host.

NCBDGSEND	Send datagram to a specified name.

NCBDGSENDBC	Send a broadcast datagram to every host on the local area network (LAN).

NCBENUM	Enumerate LAN adapter (LANA) numbers. When this value is specified, the ncb_buffer member points to a buffer to be filled with a LANA_ENUM structure.

NCBFINDNAME	Determine the location of a name on the network. When this value 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	Close a specified session.

NCBLANSTALERT	Notify the user of LAN failures that last for more than one minute.

NCBLISTEN	Enable a session to be opened with another name.

NCBRECV	Receive data from the specified session partner.

NCBRECVANY	Receive data from any session corresponding to a specified name.

NCBRESET	Reset 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 byte ncb_callname[0] specifies the maximum number of sessions, and the byte ncb_callname[2] specifies the maximum number of names. A non-zero value for the byte ncb_callname[3] requests that the application use NAME_NUMBER_1.

NCBSEND	Send data to the specified session partner. For Windows NT, this is equivalent to the NCBSENDNA command.

NCBSENDNA	Send data to specified session partner and do not wait for an acknowledgment. For Windows NT, this is equivalent to the NCBSEND command.

NCBSSTAT	Retrieve 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	Activate or deactivate NCB tracing. Support for this command in the system is optional and system-specific.

NCBUNLINK	Unlink the adapter.

ncb_retcode	Specifies the return code. This value is set to NRC_PENDING while an asynchronous operation is in progress. The return codes can be one of the following:

Return code	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 SAPs 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. This return code is not returned in the NCB; 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_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 bring the length of the string specified by the NCBNAMSZ command.

ncb_name Specifies the string that contains the local name. Trailing space characters should be supplied to bring the length of the string specified by the NCBNAMSZ command.

ncb_rto	Specifies the receive time-out period, in 500-millisecond units, for the session. A value of 0 implies no timeout. Specified only for NCBRECV commands.

ncb_sto	Specifies the send time-out period, in 500-millisecond units, for the session. A value of 0 implies no timeout. Specified only for 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. This member must be set to 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 non-zero. Otherwise, NRC_ILLCMD is returned.

The event specified by ncb_event is set to the non-signalled state by the system when an asynchronous NetBIOS command is accepted, and is set to the signalled 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

ADAPTER_STATUS, FIND_NAME_BUFFER, FIND_NAME_HEADER, LANA_ENUM, NAME_BUFFER, Netbios, SESSION_HEADER


NCCALCSIZE_PARAMS structure
NCCALCSIZE_PARAMS (Win32)

typedef struct tagNCCALCSIZE_PARAMS { /* nccp */

    RECT       rgrc[3];

    PWINDOWPOS lppos;

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

Member	Description

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 structure
NDDESHAREINFO (Win32)

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;

The NDDESHAREINFO structure is used to get and set DDE share attributes maintained by the NetDDE DSDM. The security descriptor associated with each DDE share is not passed through this structure; it is accessed through specific APIs. The NetDDE DSDM API accepts the NDDESHAREINFO structure in absolute for set functions; for get functions, the NetDDE DSDM returns the NDDESHAREINFO structure packed into the supplied buffer along with the data referenced by lpszShareName, lpszAppTopicList, and lpszItemList.

Member	Description

lRevision	Specifies the revision level of the NDDESHAREINFO structure. For the first release of Windows NT, 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 type options:

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 accessable to remote clients for linking. If this flag is set to FALSE, the DDE share will not allow remote users to communicate through it via 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 go through the process of checking to see if 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, Network DDE will attempt to start the application specified by lpszAppTopicList if it cannot initially start a  DDE conversation with the application.

nCmdShow	When Network DDE starts an application to initiate a DDE conversation with it, this value is sent to the application via the WinMain function's nCmdShow parameter. 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 they promote the share to trusted status. The default for this field 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 via a NDdeSetShareInfo or NDdeSetShareSecurity call, these values are changed.

cNumItems	Specifies the number of items listed in lpszItemList. If cNumItems is 0, 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 that 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.


NETRESOURCE structure
NETRESOURCE (Win32)

typedef struct _NETRESOURCE {  /* nr */

    DWORD  dwScope;

    DWORD  dwType;

    DWORD  dwDisplayType;

    DWORD  dwUsage;

    LPTSTR lpLocalName;

    LPTSTR lpRemoteName;

    LPTSTR lpComment;

    LPTSTR lpProvider;

} NETRESOURCE;

The NETRESOURCE structure is returned during enumeration of resources on the network and during enumeration of currently connected resources.

Member	Description

dwScope	Specifies the scope of the enumeration. Currently, this member can be one of the following values:

Value	Meaning

RESOURCE_CONNECTED	Currently connected resources (dwUsage 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 remembered 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

WNetCloseEnum, WNetEnumResource, WNetOpenEnum


NEWCPLINFO structure
NEWCPLINFO (Win32)

typedef struct tagNEWCPLINFO {  /* ncpli */

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwHelpContext;

    LONG  lData;

    HICON hIcon;

    char  szName[32];

    char  szInfo[64];

    char  szHelpFile[128];

} NEWCPLINFO;

The NEWCPLINFO structure contains resource information and a user-defined value for a Control Panel application.

Member	Description

dwSize	Specifies the length of the structure, in bytes.

dwFlags	Specifies Control Panel flags.

dwHelpContext	Specifies the context number for the topic in the help project (.HPJ) file that displays when the user selects help for the application.

lData	Specifies data defined by the application.

hIcon	Identifies an icon resource for the application icon. This icon is displayed in the Control Panel window.

szName	Specifies a null-terminated string that contains the application name. The name is the short string displayed below the application icon in the Control Panel window. The name is also displayed in the Settings menu of Control Panel.

szInfo	Specifies a null-terminated string containing the application description. The description displayed at the bottom of the Control Panel window when the application icon is selected.

szHelpFile	Specifies a null-terminated string that contains the path of the help file, if any, for the application.

See Also

CPLINFO, CPL_NEWINQUIRE


NEWTEXTMETRIC structure
NEWTEXTMETRIC (Win32)

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;

    BYTE  tmFirstChar;

    BYTE  tmLastChar;

    BYTE  tmDefaultChar;

    BYTE  tmBreakChar;

    BYTE  tmItalic;

    BYTE  tmUnderlined;

    BYTE  tmStruckOut;

    BYTE  tmPitchAndFamily;

    BYTE  tmCharSet;

    DWORD ntmFlags;

    UINT  ntmSizeEM;

    UINT  ntmCellHeight;

    UINT  ntmAvgWidth;

} NEWTEXTMETRIC;

The NEWTEXTMETRIC structure contains data that describes a physical font.

Member	Description

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 GetTextExtentPoint 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. If it is 0, the font is fixed pitch. 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.

Comments

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

EnumFonts, GetTextMetrics, TEXTMETRIC


OFSTRUCT structure
OFSTRUCT (Win32)

typedef struct _OFSTRUCT { /* of */

    BYTE cBytes;

    BYTE fFixedDisk;

    WORD nErrCode;

    WORD Reserved1;

    WORD Reserved2;

    BYTE szPathName[OFS_MAXPATHNAME];

} OFSTRUCT;

The OFSTRUCT structure contains information about a file that the OpenFile function opened or attempted to open.

Member	Description

cBytes	Specifies the length, in bytes, of the OFSTRUCT structure.

fFixedDisk	Specifies whether the file is on a fixed disk. This member is nonzero if the file is on a fixed 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 structure
OPENFILENAME (Win32)

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;

The OPENFILENAME structure contains information the operating system uses to initialize the system-defined Open or Save As dialog box. After the user closes the dialog box, the system returns information about the user's selection in this structure.

Member	Description

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 NULL if the dialog box has no owner.

hInstance	Identifies a data block that contains a dialog box template specified by the lpstrTemplateName member. This member is used only if the Flags member specifies the OFN_ENABLETEMPLATE flag; otherwise, this member is ignored.

lpstrFilter	Points to a buffer containing pairs of null-terminated filter strings. The first string in each pair describes a filter (for example, "Text Files"), the second specifies the filter pattern (for example, "*.TXT"). Multiple filters can be specified for a single item by separating the filter-pattern strings with a semicolon (for example, "*.TXT;*.DOC;*.BAK"). The last string in the buffer must be terminated by two NULL characters. If this parameter is NULL, the dialog box will not display any filters. The filter strings are assumed to be in the proper order--the operating system does not change the order.

lpstrCustomFilter	Points to a buffer containing a pair of user-defined filter strings. The first string describes the filter, and the second specifies the filter pattern (for example "WinWord, *.docnn"). The buffer is terminated by two NULL characters. The operating system copies the strings to the buffer when the user closes the dialog box. The system uses the strings to initialize the user-defined file filter the next time the dialog box is created. If this parameter is NULL, the dialog box lists but does not save user-defined filter strings.

nMaxCustFilter	Specifies the size, in characters, of the buffer identified by the lpstrCustomFilter member. This buffer should be at least 40 characters long. This parameter is ignored if the lpstrCustomFilter member is NULL or points to a NULL string.

nFilterIndex	Specifies an index into the buffer pointed to by the lpstrFilter member. The operating system uses the index value to obtain a pair of strings to use as the initial filter description and filter pattern for the dialog box. The first pair of strings has an index value of 1. When the user closes the dialog box, the system copies the index of the selected filter strings into this location. If the nFilterIndex member is 0, the custom filter is used. If the nFilterIndex member is 0 and the lpstrCustomFilter member is NULL, the system uses the first filter in the buffer identified by the lpstrFilter member. If all three members are 0 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	Points 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, this buffer contains the drive designator, path, filename, and extension of the selected file.

If the buffer is too small, the dialog box procedure copies the required size into this member.

nMaxFile	Specifies the size, in characters, of the buffer pointed to by the lpstrFile member. 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. This member is ignored if the lpstrFile member is NULL.

lpstrFileTitle	Points to a buffer that receives the title of the selected file. For Windows versions 3.0 and 3.1, this buffer receives the filename and extension without path information. This application should use this string to display the file title. If this member is NULL, the function does not copy the file title.

nMaxFileTitle	Specifies the maximum length of the string that can be copied into the lpstrFileTitle buffer. This member is ignored if lpstrFileTitle is NULL.

lpstrInitialDir	Points 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	Points 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	Specifies the dialog box creation flags. This member may be a combination of the following values:

Value	Meaning

OFN_ALLOWMULTISELECT

Specifies that the File Name list box allows multiple selections. (If the dialog box is created by using a private template, the LBS_EXTENDEDSEL constant must appear in the definition of the File Name list box.)

OFN_CREATEPROMPT

Specifies that the dialog box function should ask whether the user wants to create a file that does not currently exist. (This flag automatically sets the OFN_PATHMUSTEXIST and OFN_FILEMUSTEXIST flags.)

OFN_ENABLEHOOK

Enables the hook function specified in the lpfnHook member.

OFN_ENABLETEMPLATE

Causes the operating system to create the dialog box by using the dialog box template identified by the hInstance and lpTemplateName members.

OFN_ENABLETEMPLATEHANDLE

Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The operating system ignores the lpTemplateName member if this flag is specified.

OFN_EXTENSIONDIFFERENT

Specifies that the user typed a filename extension that differs from the extension specified by the lpstrDefExt member. The function does not set 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 set and the user enters an invalid filename in the File Name entry field, the dialog box function displays a warning in a message box. The setting of this flag causes the OFN_PATHMUSTEXIST flag to be set.

OFN_HIDEREADONLY

Hides the Read Only check box.

OFN_NOCHANGEDIR

Causes the dialog box to set the current directory back to what it was when the dialog box was called.

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 set if the application saves the file on a create-nonmodify network share point. When an application sets 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 function that checks the filename by using the FILEOKSTRING registered 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, the nFileOffset and nFileExtension members are set to values generated by parsing the text. No default extension is added to the text, nor is text copied to the lpstrFileTitle buffer.

If the value specified by the nFileOffset member is negative, the filename is invalid. If the value specified by nFileOffset is not negative, the filename is valid, and the nFileOffset and nFileExtension members can be used as if the OFN_NOVALIDATE flag had not been set.

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 path and filenames. If this flag is set 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. 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 given filename. If this flag is not set, the registered message for SHAREVISTRING is sent to the hook function, with a pointer to a null-terminated string for the path and filename in the lParam parameter. The hook function responds with one of the following values:

Value	Meaning

OFN_SHAREFALLTHROUGH	Specifies that the filename is returned by the dialog box.

OFN_SHARENOWARN	Specifies no further action.

OFN_SHAREWARN	Specifies that the user receives the standard warning message for this error, the same result as if there were no hook function.

OFN_SHOWHELP	Causes the dialog box to show the Help button. The hwndOwner member must not be NULL if this option is specified.

nFileOffset	Specifies a zero-based offset from the beginning of the path to the filename in the string to which the lpstrFile member points. For example, if lpstrFile points to the following string, "c:\dir1\dir2\file.ext", this member contains the value 13.

nFileExtension	Specifies a zero-based offset from the beginning of the path to the filename extension in the string pointed to by the lpstrFile member. 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 0.

lpstrDefExt	Points to a buffer that contains the default extension. The GetOpenFileName and GetSaveFileName functions 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 operating system passes to the hook function identified by the lpfnHook member. The system passes the data in the lParam parameter of the WM_INITDIALOG message.

lpfnHook	Points to a hook function that processes messages intended for the dialog box. An application must specify the OFN_ENABLEHOOK flag in the Flags member to enable the function; otherwise, the operating system ignores this structure member. The hook function should return FALSE to pass a message to the standard dialog box procedure, or TRUE to discard the message.

lpstrTemplateName	Points to a null-terminated string that names the dialog box template resource to be substituted for the standard dialog box template. An application can use the MAKEINTRESOURCE macro for numbered dialog box resources. This member is used only if the Flags member specifies the OFN_ENABLETEMPLATE flag; otherwise, this member is ignored.

See Also

GetOpenFileName, GetSaveFileName, MAKEINTRESOURCE


OUTLINETEXTMETRIC structure
OUTLINETEXTMETRIC (Win32)

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;

The OUTLINETEXTMETRIC structure contains metrics describing a TrueType® font.

Member	Description

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 counterclockwise degrees 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.

Comments

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, PANOSE, TEXTMETRIC


OUTPUT_DEBUG_STRING_INFO structure
OUTPUT_DEBUG_STRING_INFO (Win32)

typedef struct _OUTPUT_DEBUG_STRING_INFO { /* odsi */

    LPSTR lpDebugStringData;

    WORD  fUnicode;

    WORD  nDebugStringLength;

} OUTPUT_DEBUG_STRING_INFO;

The OUTPUT_DEBUG_STRING_INFO structure contains the address, format, and length, in bytes, of a debugging string.

Member	Description

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 value 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


OVERLAPPED structure
OVERLAPPED (Win32)

typedef struct _OVERLAPPED { /* o */

    DWORD  Internal;

    DWORD  InternalHigh;

    DWORD  Offset;

    DWORD  OffsetHigh;

    HANDLE hEvent;

} OVERLAPPED;

The OVERLAPPED structure contains information used in asynchronous input and output.

Member	Description

Internal	Reserved for operating system use. This member specifies a system-dependent status. This member 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 specifies the length of the data transferred. This member is valid when the GetOverlappedResult function returns TRUE.

Offset	Specifies a file position 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 the functions read from and write to named pipes and communication devices.

OffsetHigh	Specifies the high word of the byte offset at which to start the transfer. This member is ignored when the functions read from and write to named pipes and communication 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.

See Also

ConnectNamedPipe, CreateFile, GetOverlappedResult, ReadFile, ReadFileEx, WriteFile, WriteFileEx


PAINTSTRUCT structure
PAINTSTRUCT (Win32)

typedef struct tagPAINTSTRUCT { /* ps */

    HDC  hdc;

    BOOL fErase;

    RECT rcPaint;

    BOOL fRestore;

    BOOL fIncUpdate;

    BYTE rgbReserved[32];

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

Member	Description

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 structure
PALETTEENTRY (Win32)

typedef struct tagPALETTEENTRY { /* pe */

    BYTE peRed;

    BYTE peGreen;

    BYTE peBlue;

    BYTE peFlags;

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

Member	Description

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 these 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 prevents other windows from matching colors to the palette entry since the color frequently changes. If an unused system-palette entry is available, this color is placed in that entry. Otherwise, the color is available for animation.

See Also

LOGPALETTE


PANOSE structure
PANOSE (Win32)

typedef struct tagPANOSE { /* pnse */

    DWORD ulCulture;

    BYTE bFamilyType;

    BYTE bSerifStyle;

    BYTE bWeight;

    BYTE bProportion;

    BYTE bContrast;

    BYTE bStrokeVariation;

    BYTE bArmStyle;

    BYTE bLetterform;

    BYTE bMidline;

    BYTE bXHeight;

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

Member	Description

ulCulture	Specifies the culture-specific classification scheme of the PANOSE number. The culture number specifies how to interpret the subsequent ten members for Latin fonts. The culture number can have the following values:

Value	Meaning

PAN_ANY	Any

PAN_CULTURE_LATIN	Latin

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	Non-straight arms/horizontal

PAN_BENT_ARMS_WEDGE	Non-straight arms/wedge

PAN_BENT_ARMS_VERT	Non-straight arms/vertical

PAN_BENT_ARMS_SINGLE_SERIF	Non-straight arms/single-serif

PAN_BENT_ARMS_DOUBLE_SERIF	Non-straight 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

See Also

EXTLOGFONT


PARTITION_INFORMATION structure
PARTITION_INFORMATION (Win32)

typedef struct _PARTITION_INFORMATION {

    BYTE PartitionType;

    BOOLEAN BootIndicator;

    BOOLEAN RecognizedPartition;

    BOOLEAN RewritePartition;

    LARGE_INTEGER StartingOffset;

    LARGE_INTEGER PartitionLength;

    LARGE_INTEGER HiddenSectors;

} PARTITION_INFORMATION ;

The PARTITION_INFORMATION function provides information about a disk partition.

Member	Description

PartitionType	Specifies the type of partition. This member can take on 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.

BootIndicator	The boot sector of the disk.

RecognizedPartition	The partition is recognized.

RewritePartition	The rewrite partition.

StartingOffset	The starting offset.

PartitionLength	The partition length.

HiddenSectors	The number of hidden sectors.

Comments

The DeviceIoControl function receives a PARTITION_INFORMATION structure in response to an IOCTL_DISK_GET_PARTITION_INFO or IOCTL_DISK_GET_DRIVE_LAYOUT device i/o operation. The DeviceIoControl function uses a PARTITION_INFORMATION structure as input to an IOCTL_DISK_SET_DRIVE_LAYOUT device i/o operation.

See Also

IOCTL_DISK_GET_DRIVE_LAYOUT, IOCTL_DISK_GET_PARTITION_INFO, IOCTL_DISK_SET_DRIVE_LAYOUT


PCMWAVEFORMAT structure
PCMWAVEFORMAT (Win32)

typedef struct pcmwaveformat_tag {

    WAVEFORMAT  wf;

    WORD  wBitsPerSample;

} PCMWAVEFORMAT;

The PCMWAVEFORMAT structure describes the data format for pulse code modulated (PCM) waveform data.

Member	Description

wf	Specifies a WAVEFORMAT structure containing general information about the format of the waveform data.

wBitsPerSample	Specifies the number of bits per sample.

See Also

WAVEFORMAT


PERF_COUNTER_BLOCK structure
PERF_COUNTER_BLOCK (Win32)

typedef struct _PERF_COUNTER_BLOCK { /* pcd */

    DWORD ByteLength;

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

Member	Description

ByteLength	Specifies the length, in bytes, of this structure, including the counters that follow.

Comments

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_COUNTER_DEFINITION structure
PERF_COUNTER_DEFINITION (Win32)

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;

The PERF_COUNTER_DEFINITION structure describes a performance counter. The Unicode names in this structure must appear in a message file.

Member	Description

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

Detail level	Meaning

PERF_DETAIL_NOVICE	Data can be understood by the uninformed user.

PERF_DETAIL_ADVANCED	Data designed for the advanced user.

PERF_DETAIL_EXPERT	Data designed for the expert user.

PERF_DETAIL_WIZARD	Data designed for the system designer.

CounterType	Specifies the type of counter. This member is some combination of the following values.

The following 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.

The following 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 the following 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 the following 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 by the current time (units specified by this counter's subtype). Add the product to this counter. To obtain the average queue length, divide the result by the delta time.

PERF_COUNTER_HISTOGRAM	The counter value begins or ends a histogram.

If PERF_TYPE_COUNTER is specified, one of the following values is also specified to indicate the subtype of counter:

Value	Meaning

PERF_TIMER_TICK	Use the frequency of the high-resolution performance counter as the base.

PERF_TIMER_100NS	Use the time base units of the 100-nanosecond timer as the base.

PERF_OBJECT_TIMER	Use the object-timer frequency 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 the following 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.

The following values indicate how to use the counter data in a calculation:

Value	Meaning

PERF_DELTA_COUNTER	Compute the difference between the previous counter value and the current counter value before proceeding.

PERF_DELTA_BASE	Compute the difference between the previous base value and the current base value before proceeding.

PERF_INVERSE_COUNTER	After other calculations, the counter should be inverted before displaying or converting to a percentage.

PERF_MULTI_COUNTER	This is a sum of counters from several sources, the number of which is indicated by the next counter.

The following 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.

Comments

This structure is part of the performance data provided by the RegQueryValueEx function when the HKEY_PERFORMANCE_DATA key is used.


PERF_DATA_BLOCK structure
PERF_DATA_BLOCK (Win32)

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;

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.

Member	Description

Signature	Contains the Unicode string PERF.

LittleEndian	Contains zero if the processor is big endian, one if little endian.

Version	Contains the version of the PERF_ structures. This value is greater than or equal to one.

Revision	Contains the revision of the PERF_ structures. This value is greater than or equal to zero.

TotalByteLength	Contains the total length, in bytes, of 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 value can be -1 to indicate that no data is to be displayed.

SystemTime	Contains the time when the system is monitored. This value is in Universal Time Convention (UTC) format.

PerfTime	Contains the performance-counter value for the system being monitored. This value is in counts.

PerfFreq	Contains the performance-counter frequency for the system being monitored. This value is in counts per second.

PerfTime100nSec	Contains the performance-counter value for the system being monitored. This value is in 100 nanosecond units.

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.


PERF_INSTANCE_DEFINITION structure
PERF_INSTANCE_DEFINITION (Win32)

typedef struct _PERF_INSTANCE_DEFINITION { /* pid */

    DWORD ByteLength;

    DWORD ParentObjectTitleIndex;

    DWORD ParentObjectInstance;

    DWORD UniqueID;

    DWORD NameOffset;

    DWORD NameLength;

} 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_DATA_BLOCK structure.

Member	Description

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; 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 value 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 value is zero if the instance does not have a name.


PERF_OBJECT_TYPE structure
PERF_OBJECT_TYPE (Win32)

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;

The PERF_OBJECT_TYPE structure describes the 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.

Member	Description

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 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 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 value is the offset to the first PERF_COUNTER_DEFINITION structure for this object.

ObjectNameTitleIndex	Contains the index to the object name in the title database.

ObjectNameTitle	Points to the name of the object. This member initially contains NULL, but 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 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 value is typically greater than or equal to zero. However, this value 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 value is zero if the instance strings are in Unicode. Otherwise, this value 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.

Comments

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.


POINT structure
POINT (Win32)

typedef struct tagPOINT { /* pt */

    LONG x;

    LONG y;

} POINT;

The POINT structure defines the x- and y- coordinates of a point.

Member	Description

x	Specifies the x-coordinate of the point.

y	Specifies the y-coordinate of the point.

See Also

ChildWindowFromPoint, GetBrushOrgEx, PtInRect, SetBrushOrgEx, WindowFromPoint


POINTFX structure
POINTFX (Win32)

typedef struct tagPOINTFX { /* ptfx */

    FIXED x;

    FIXED y;

} POINTFX;

The POINTFX structure contains the coordinates of points that describe the outline of a character in a TrueType® font.

Member	Description

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.

Comments

The POINTFX structure is a member of the TTPOLYCURVE and TTPOLYGONHEADER structures.

See Also

FIXED, TTPOLYCURVE, TTPOLYGONHEADER, GetGlyphOutline


POINTL structure
POINTL (Win32)

typedef struct _POINTL { /* ptl */

    LONG x;

    LONG y;

} POINTL;

The POINTL structure contains the coordinates of a point.

Member	Description

x	Specifies the horizontal (x) coordinate of the point.

y	Specifies the vertical (y) coordinate of the point.


POINTS structure
POINTS (Win32)

typedef struct tagPOINTS { /* pts */

    SHORT x;

    SHORT y;

} POINTS;

The POINTS structure defines the coordinates of a point.

Member	Description

x	Specifies the x-coordinate of the point.

y	Specifies the y-coordinate of the point.

See Also

ChildWindowFromPoint, PtInRect, WindowFromPoint, POINT


POLYTEXT structure
POLYTEXT (Win32)

typedef struct _POLYTEXT { /* ptxt */

    int   x;

    int   y;

    UINT  n;

    TCHAR *lpwstr;

    UINT  uiFlags;

    RECT  rcl;

    int   *pdx;

} POLYTEXT;

The POLYTEXT structure describes how the PolyTextOut function should draw a string of text.

Member	Description

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.

ETO_DELTAVECTOR	Each string is accompanied by an array of character widths, as in ExtTextOut.

lpwstr	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. This member is ignored unless the ETO_DELTAVECTOR value is specified for the uiFlags member.

See Also

PolyTextOut


PORT_INFO_1 structure
PORT_INFO_1 (Win32)

typedef struct _PORT_INFO_1 { /* pi1 */

    LPSTR pName;

} PORT_INFO_1;

The PORT_INFO_1 structure identifies a supported printer port.

Member	Description

pName	Points to a null-terminated string that identifies a supported printer port (for example, "LPT1:").

See Also

EnumPorts


PREVENT_MEDIA_REMOVAL structure
PREVENT_MEDIA_REMOVAL (Win32)

typedef struct _PREVENT_MEDIA_REMOVAL{

   BOOLEAN PreventMediaRemoval;

} PREVENT_MEDIA_REMOVAL ;

The PREVENT_MEDIA_REMOVAL structure provides removeable media locking data.

Member	Description

PreventMediaRemoval	Specifies whether the media is to be locked (if TRUE) or not (if FALSE).

Comments

The DeviceIoControl function uses a PREVENT_MEDIA_REMOVAL structure as input to an IOCTL_DISK_MEDIA_REMOVAL device i/o operation.

See Also

DeviceIoControl, IOCTL_DISK_MEDIA_REMOVAL


PRINTDLG structure
PRINTDLG (Win32)

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;

    LPCSTR    lpPrintTemplateName;

    LPCSTR    lpSetupTemplateName;

    HANDLE    hPrintTemplate;

    HANDLE    hSetupTemplate;

} PRINTDLG;

The PRINTDLG structure contains information the operating system uses to initialize the system-defined Print dialog boxes. After the user closes the dialog box, the system returns information about the user-defined print parameters in this structure.

Member	Description

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 NULL if the dialog box has no owner.

hDevMode	Identifies a movable global memory object that contains a DEVMODE structure. Before the 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 the application uses the structure to initialize the dialog box controls, it must allocate space for and create the DEVMODE structure. (The application should allocate a movable block of memory.)

If the application does not use the structure to initialize the dialog box controls, the hDevMode member 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, the hDevMode member 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 an hDevMode value and an hDevNames value, see the Comments 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 the application uses the structure to initialize the dialog box controls, it must allocate space for and create the DEVMODE structure. (The application should allocate a movable block of global memory.)

If the application does not use the structure to initialize the dialog box controls, the hDevNames member 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, if the following string appears in the [devices] section:

PCL / HP LaserJet=HPPCL,LPT1:,LPT2:

The function uses "LPT1:" as the port name.

If both the hDevMode and hDevNames members 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.

Please refer to the Comments section below for a discussion of how the system resolves a possible data collision between an hDevNames value and an hDevMode value.

hDC	Identifies a device context or an information context, depending on whether the Flags member specifies the PD_RETURNDC or the 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	Specifies the dialog box initialization flags. This member may be a combination of the following values:

Value	Meaning

PD_ALLPAGES

Indicates that the All radio button was selected when the user closed the dialog box. (This value is used as a placeholder, to indicate that the PD_PAGENUMS and PD_SELECTION flags are not set. This value can be set on input and on output.)

PD_COLLATE

Causes the Collate check box to be in the checked state when the dialog box is created. When the PrintDlg function returns, this flag indicates the state the Collate check box was left in by the user.

PD_DISABLEPRINTTOFILE

Disables the Print to File check box.

PD_ENABLEPRINTHOOK

Enables the hook function specified in the lpfnPrintHook member of this structure.

PD_ENABLEPRINTTEMPLATE

Causes the operating system to create the dialog box by using the dialog box template identified by the hInstance and lpPrintTemplateName members.

PD_ENABLEPRINTTEMPLATEHANDLE

Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The system ignores the lpPrintTemplateName member if this flag is specified.

PD_ENABLESETUPHOOK

Enables the hook function specified in the lpfnSetupHook member of this structure.

PD_ENABLESETUPTEMPLATE

Causes the operating system to create the dialog box by using the dialog template box identified by the hInstance and lpSetupTemplateName members.

PD_ENABLESETUPTEMPLATEHANDLE

Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The operating system ignores the lpSetupTemplateName member if this flag is specified.

PD_HIDEPRINTTOFILE

Hides and disables the Print to File check box.

PD_NOPAGENUMS

Disables the Pages radio button and the associated edit control.

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 the PrintDlg function 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 in the checked state when the dialog box is created. When the PrintDlg function returns, the pOutput member of the DEVNAMES structure points to the "FILE:" string.

PD_RETURNDC

Causes the PrintDlg function to return a device context matching the selections the user made in the dialog box. The device context is returned in the hDC member.

PD_RETURNDEFAULT

Without displaying a dialog box the PrintDlg function to return DEVMODE and DEVNAME structures that are initialized for the system default printer. It is assumed that both the hDevNames and hDevMode members are NULL; otherwise, the function returns an error. If the system default printer is supported by an old printer driver (earlier than Windows 3.0), only the hDevNames member is returned--the hDevMode member 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, the hDC parameter is undefined on output.

PD_SELECTION

Causes the Selection radio button to be in the selected state when the dialog box is created. When the PrintDlg function returns, this flag is set if the Selection radio button is in the selected state. If neither PD_PAGENUMS nor PD_SELECTION is specified, the All radio button is in the selected state.

PD_SHOWHELP

Causes the dialog box to show the Help button. The hwndOwner member must not be NULL if this option is specified.

PD_USEDEVMODECOPIES

If a printer driver does not support multiple copies, setting this flag disables the Copies edit control; if a driver does support multiple copies, setting this flag indicates the the PrintDlg function should store the requested number of copies in the dmCopies member of the DEVMODE structure and store the value 1 in the nCopies member of the PRINTDLG structure.

If this flag is not set, the PrintDlg structure stores the value 1 in the dmCopies member of the DEVMODE structure and stores the requested number of copies in the nCopies member of the PRINTDLG structure.

nFromPage	Specifies the initial value for the starting page edit control. When the PrintDlg function returns, this member specifies the page to begin printing. 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, this member specifies the last page to print. 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	Before the call to the PrintDlg function, this member contains a value used to initialize the Copies edit control if the hDevMode member is NULL; otherwise, the dmCopies member of the DEVMODE structure contains the value used to initialize this control.

When the PrintDlg function returns, the value specified by this member depends on the printer-driver version. For printer drivers earlier than Windows version 3.0, this member specifies the number of copies requested by the user in the dialog box's Copies edit control. For Windows version 3.0 and later printer drivers, this member specifies the number of copies requested by the user if the PD_USEDEVMODECOPIES flag was not set; otherwise, this member specifies the value 1, and the actual requested copy count appears in the DEVMODE structure.

hInstance	Identifies a data block that contains the preloaded dialog box template specified by the lpstrTemplateName member. This member is used only if the Flags member specifies the PD_ENABLEPRINTTEMPLATE or PD_ENABLESETUPTEMPLATE flag; otherwise, this member is ignored.

lCustData	Specifies application-defined data that the operating system passes to the hook function pointed to by the lpfnHook member. The system passes the data in the lParam parameter of the WM_INITDIALOG message.

lpfnPrintHook	Points to the exported function that hooks dialog messages if the application alters the Print dialog box. This member is ignored unless the PD_ENABLEPRINTHOOK flag is specified in the Flags member.

lpfnSetupHook	Points to the exported function that hooks dialog messages if the application alters the Print Setup dialog box. This member is ignored unless the PD_ENABLESETUPHOOK flag is specified in the Flags member.

lpPrintTemplateName	Points to a hook function that processes messages intended for the dialog box. An application must specify the PD_ENABLEPRINTTEMPLATE or PD_ENABLEPRINTERTEMPLATEHANDLE constant in the Flags member to enable the function; otherwise, the system ignores this structure member. The hook function should return FALSE to pass a message to the standard dialog box procedure, or TRUE to discard the message.

lpSetupTemplateName	Points to a hook function that processes messages intended for the dialog box. An application must specify the PD_ENABLESETUPTEMPLATE or PD_ENABLESETUPTEMPLATEHANDLE constant in the Flags member to enable the function; otherwise, the system ignores this structure member. The hook function should return FALSE to pass a message to the standard dialog box procedure, or TRUE to discard the message.

hPrintTemplate	Identifies the global memory object that contains the preloaded dialog box template to be used instead of the default Print Dialog box.

hSetupTemplate	Identifies the global memory object that contains the preloaded dialog box template to be used instead of the default Setup dialog box.

Comments

There is the possibility of a data collision between an hDevNames value and an hDevMode value. That is because the wDeviceOffset member of the DEVNAMES structure is supposed to be identical to thedmDeviceName of the DEVMODE structure. If it is not, the system resolves the data collision by using the wDeviceOffset value.

See Also

CreateDC, CreateIC, PrintDlg, DEVMODE, DEVNAMES, DEVMODE, DEVNAMES


PRINTER_DEFAULTS structure
PRINTER_DEFAULTS (Win32)

typedef struct _PRINTER_DEFAULTS {  /* pd */

    LPTSTR      pDatatype;

    LPDEVMODE   pDevMode;

    ACCESS_MASK DesiredAccess;

} PRINTER_DEFAULTS;

The PRINTER_DEFAULTS structure specifies the default data type, environment, initialization data, and acces rights for a printer.

Member	Description

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_ADMINISTER, PRINTER_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_ADMINISTER access.

See Also

OpenPrinter, DEVMODE


PRINTER_INFO_1 structure
PRINTER_INFO_1 (Win32)

typedef struct _PRINTER_INFO_1 { /* pri1 */

    DWORD  Flags;

    LPTSTR pDescription;

    LPTSTR pName;

    LPTSTR pComment;

} PRINTER_INFO_1;

The PRINTER_INFO_1 structure specifies general printer information.

Member	Description

Flags	Specifies information about the returned data.

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	Points to a null-terminated string that describes the contents of the structure.

pName	Points to a null-terminated string that names the contents of the structure.

pComment	Points to a null-terminated string that contains additional data describing the structure.

See Also

GetPrinter, EnumPrinters, PRINTER_INFO_2, PRINTER_INFO_3


PRINTER_INFO_2 structure
PRINTER_INFO_2 (Win32)

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;

The PRINTER_INFO_2 structure specifies detailed printer information.

Member	Description

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, and may be NULL.

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

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 specified in minutes elapsed since 12:00 A.M.)

UntilTime	Specifies the latest time at which the printer will print a job. (This value is specified in minutes elapsed since 12:00 A.M.)

Status	Specifies the printer status. This member can be one of the following values:

PRINTER_STATUS_PAUSED

PRINTER_STATUS_PENDING_DELETION

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.

See Also

EnumPrinters, PRINTER_INFO_1


PRINTER_INFO_3 structure
PRINTER_INFO_3 (Win32)

typedef struct _PRINTER_INFO_3 { /* pri3 */

    PSECURITY_DESCRIPTOR pSecurityDescriptor;

} PRINTER_INFO_3;

The PRINTER_INFO_3 structure specifies printer security information.

Member	Description

pSecurityDescriptor	Points to a SECURITY_DESCRIPTOR structure that specifies a printer's security information.

Comments

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, so long as it has the standard rights described in the SetPrinter and GetPrinter reference pages. 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, SECURITY_DESCRIPTOR


PRINTPROCESSOR_INFO_1 structure
PRINTPROCESSOR_INFO_1 (Win32)

typedef struct _PRINTPROCESSOR_INFO_1 { /* ppi1 */

    LPSTR pName;

} PRINTPROCESSOR_INFO_1;

The PRINTPROCESSOR_INFO_1 structure specifies the name of an installed print processor.

Member	Description

pName	Points to a null-terminated string that specifies the name of an installed print processor.

See Also

EnumPrintProcessors


PRIVILEGE_SET structure
PRIVILEGE_SET (Win32)

typedef struct _PRIVILEGE_SET { /* ps */

    DWORD PrivilegeCount;

    DWORD Control;

    LUID_AND_ATTRIBUTES Privilege[ANYSIZE_ARRAY];

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

Member	Description

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.

Comments

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_INFORMATION structure
PROCESS_INFORMATION (Win32)

typedef struct _PROCESS_INFORMATION { /* pi */

    HANDLE hProcess;

    HANDLE hThread;

    DWORD dwProcessId;

    DWORD dwThreadId;

} PROCESS_INFORMATION;

The PROCESS_INFORMATION structure is filled in by the CreateProcess function with information about a newly created process and its primary thread.

Member	Description

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 identifiers 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


PROVIDOR_INFO_1 structure
PROVIDOR_INFO_1 (Win32)

typedef struct _PROVIDOR_INFO_1 { /* pi1 */

    LPTSTR pName;

    LPTSTR pEnvironment ;

    LPTSTR pDLLName ;

} PROVIDOR_INFO_1;

The PROVIDOR_INFO_1 structure identifies a print provider.

Member	Description

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 this 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


QUERY_SERVICE_CONFIG structure
QUERY_SERVICE_CONFIG

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;

The QUERY_SERVICE_CONFIG structure is used by the QueryServiceConfig function to return configuration information about an installed service.

Member	Description

dwServiceType	Indicates the type of service. One of the following values is specified.

Type	Meaning

SERVICE_WIN32_OWN_PROCESS	Specifies a service that runs in its own Win32 process.

SERVICE_WIN32_SHARE_PROCESS	Specifies a service that shares a Win32 process with other services.

SERVICE_KERNEL_DRIVER	Specifies a Windows NT device driver.

SERVICE_FILE_SYSTEM_DRIVER	Specifies a Windows NT file system driver.

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

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

Comments

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


QUERY_SERVICE_LOCK_STATUS structure
QUERY_SERVICE_LOCK_STATUS

typedef struct _QUERY_SERVICE_LOCK_STATUS { /* qsls */

    DWORD fIsLocked;

    LPTSTR lpLockOwner;

    DWORD dwLockDuration;

} QUERY_SERVICE_LOCK_STATUS, * LPQUERY_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.

Member	Description

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


RASCONN structure
RASCONN (Win32)

typedef struct _RASCONN {

    DWORD     dwSize;

    HRASCONN  hrasconn;

    TCHAR     szEntryName[RAS_MaxEntryName + 1];

} RASCONN ;

The RASCONN structure provides information about a remote access connection. The RasConnectEnum function returns an array of RASCONN structures.

Member	Description

dwSize	Specifies the size in bytes of the RASCONN structure.

hrasconn	Specifies a RAS handle for 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.

See Also

RasEnumConnections, RasGetConnectStatus


RASCONNSTATE structure
RASCONNSTATE (Win32)

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_SendCallback,

        RASCS_PrepareForCallback,

        RASCS_WaitForModemReset,

        RASCS_WaitForCallback,

        RASCS_Interactive = RASCS_PAUSED,

        RASCS_RetryLogon,

        RASCS_CallbackSetByCaller,

        RASCS_PasswordExpired,

        RASCS_Connected = RASCS_DONE,

        RASCS_Disconnected

} RASCONNSTATE ;

The RASCONNSTATE enumeration type enumerates all states that may occur when connecting via the RasDial function.

A RASCONNSTATE enumerator value is returned as part of a RASCONNSTATUS data structure; that structure is obtained by calls to the RasGetConnectStatus function.

The enumerator values are listed here in the general order that the connection states occur.

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

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 consists of:

Validating the username/password on the specified domain.

Projecting the client onto the LAN. This means that the Remote Access server does what is necessary to send/receive data on the LAN on behalf of the client. For example, the Remote Access server might need to add a NetBIOS name corresponding to the client's computer name.

Callback processing where client hangs up and the server calls back. (The user needs special permissions on the Remote Access server for this)

Calculation of link speed. This is necessary to correctly set transport timeouts to match the relatively slow speed of the remote link.

RASCS_AuthNotify	An authentication event has occurred. If dwError is 0 this will be immediately followed by one of the more specific authentication states below. If dwError is non-zero, authentication has failed, and the error code indicates why.

RASCS_AuthRetry	The client has requested another validation attempt with a new username/password/domain. This state does not occur in the version 3.1 public interface.

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 the version 3.1 public interface.

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_Interactive	This state corresponds to the Terminal state supported by RASPHONE.EXE. This state does not occur in the version 3.1 public interface.

RASCS_RetryAuthentication	This state corresponds to the Retry Authentication state supported by RASPHONE.EXE. This state does not occur in the version 3.1 public interface.

RASCS_CallbackSetByCaller	This state corresponds to the Callback state supported by RASPHONE.EXE. This state does not occur in the version 3.1 public interface.

RASCS_PasswordExpired	This state corresponds to the Change Password state supported by RASPHONE.EXE. This state does not occur in the version 3.1 public interface.

RASCS_Connected	Successful connection.

RASCS_Disconnected	Disconnection or failed connection.

Comments

The connection process states are divided into 3 classes: running states, paused states, and terminal states.

An application can easily determine the class of a given 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, RASCONNSTATUS


RASCONNSTATUS structure
RASCONNSTATUS (Win32)

typedef struct _RASCONNSTATUS {

    DWORD         dwSize;

    RASCONNSTATE  rasconnstate;

    DWORD         dwError;

    TCHAR         szDeviceType[RAS_MaxDeviceType + 1];

    TCHAR         szDeviceName[RAS_MaxDeviceName + 1];

} RASCONNSTATUS;

A RASCONNSTATUS structure describes the current status of a RAS remote access connection. It is returned by the RasGetConnectStatus API.

Member	Description

dwSize	Specifies the size of the structure in bytes.

rasconnstate	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 completed successfully.

RASCS_Disconnected	Indicates that the connection has failed.

dwError	If non-zero, indicates the reason for failure. The value is one of the error codes from RASERROR.H, 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 remote access service 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


RASDIALPARAMS structure
RASDIALPARAMS (Win32)

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] ;

} RASDIALPARAMS;

The RASDIALPARAMS structure contains parameters used by RasDial to establish a RAS remote access connection.

Member	Description

dwSize	Specifies the size of the structure in bytes.

szEntryName	A string specifying the phone book entry to use to establish the connection. An empty string ("") specifies a simple modem connection on the first available modem port, in which case a non-empty szPhoneNumber must be provided.

szPhoneNumber	A string specifying an overriding phone number. An empty string ("") indicates that the phone book entry's phone number should be used. If szEntryName is "", szPhoneNumber cannot be "".

szCallbackNumber	A string specifying 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.

The special value "*" indicates that the number stored in the phonebook should be used for callback.

szUserName	A string specifying the user's NT or Lan Manager user name. This string is used to authenticate the user's access to the Remote Access server.

szPassword	A string specifying the user's NT or Lan Manager password. This string is used to authenticate the user's access to the Remote Access server.

szDomain	A string specifying the NT 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.

Comments

The szUserName and szPassword strings are only used to authenticate the user's access to the Remote Access server. RAS does not actually log the user onto the network. The user does this in the usual manner, using Ctrl-Alt-Del, after the RAS connection is established.

If both the szUserName and the szPassword members are empty strings (""), RAS uses the username and password of the currently logged-on user for authentication.

See Also

RasDial


RASENTRYNAME structure
RASENTRYNAME (Win32)

typedef struct _RASENTRYNAME {

    DWORD  dwSize;

    TCHAR  szEntryName[RAS_MaxEntryName + 1];

}RASENTRYNAME;

The RASENTRYNAME structure contains an entry name from a remote access phonebook created by RASPHONE.EXE. The RasEntryEnum function returns an array of these structures.

Member	Description

dwSize	Specifies the size in bytes of the RASENTRYNAME structure.

szEntryName	A string that is the entry name as entered in an "Entry name" field in RASPHONE.EXE.

See Also

RasEnumEntries


RASTERIZER_STATUS structure
RASTERIZER_STATUS (Win32)

typedef struct _RASTERIZER_STATUS {    /* rs */

    short nSize;

    short wFlags;

    short nLanguageID;

} RASTERIZER_STATUS;

The RASTERIZER_STATUS structure contains information about whether TrueType® is installed. This structure is filled when an application calls the GetRasterizerCaps function.

Member	Description

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 and/or TT_ENABLED if TrueType is on the system.

nLanguageID	Specifies the language in the system's SETUP.INF file.

See Also

GetRasterizerCaps


REASSIGN_BLOCKS structure
REASSIGN_BLOCKS (Win32)

typedef struct _REASSIGN_BLOCKS {

    WORD   Reserved;

    WORD   Count;

    DWORD BlockNumber[1];

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

Member	Description

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[1]	An array of Count block numbers, one for each block to be reassigned.

Comments

The DeviceIoControl function uses a REASSIGN_BLOCKS structure as input to an IOCTL_DISK_REASSIGN_BLOCKS device i/o operation.

See Also

DeviceIoControl, IOCTL_DISK_REASSIGN_BLOCKS


RECT structure
RECT (Win32)

typedef struct tagRECT {    /* rc */

    LONG left;

    LONG top;

    LONG right;

    LONG bottom;

} RECT;

The RECT structure defines the coordinates of the upper-left and lower-right corners of a rectangle.

Member	Description

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.

Comments

When the RECT structure is passed to the FillRect function, the rectangle is filled up to, but not including, the right column and bottom row of pixels.

See Also

RECTL, SMALL_RECT


RECTL structure
RECTL (Win32)

typedef struct _RECTL { /* rcl */

    LONG left;

    LONG top;

    LONG right;

    LONG bottom;

} RECTL;

The RECTL structure defines the coordinates of the upper-left and lower-right corners of a rectangle.

Member	Description

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.

Comments

When the RECTL structure is passed to the FillRect function, the rectangle is filled up to, but not including, the right column and bottom row of pixels.

See Also

RECT, SMALL_RECT


RGBQUAD structure
RGBQUAD (Win32)

typedef struct tagRGBQUAD { /* rgbq */

    BYTE    rgbBlue;

    BYTE    rgbGreen;

    BYTE    rgbRed;

    BYTE    rgbReserved;

} RGBQUAD;

The RGBQUAD structure describes a color consisting of relative intensities of red, green, and blue.

Member	Description

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.

Comments

The bmiColors member of the BITMAPINFO structure consists of an array of RGBQUAD structures.

See Also

CreateDIBitmap, CreateDIBSection, GetDIBits, SetDIBits, SetDIBitsToDevice, StretchDIBits


RGBTRIPLE structure
RGBTRIPLE (Win32)

typedef struct tagRGBTRIPLE { /* rgbt */

    BYTE rgbtBlue;

    BYTE rgbtGreen;

    BYTE rgbtRed;

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

Member	Description

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.


RGNDATA structure
RGNDATA (Win32)

typedef struct _RGNDATA { /* rgnd */

    RGNDATAHEADER rdh;

    char          Buffer[1];

} RGNDATA;

The RGNDATA structure contains a header and an array of rectangles that compose a region. These rectangles, sorted top to bottom left to right, do not overlap.

Member	Description

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 structure
RGNDATAHEADER (Win32)

typedef struct _RGNDATAHEADER { /* rgndh */

    DWORD dwSize;

    DWORD iType;

    DWORD nCount;

    DWORD nRgnSize;

    RECT  rcBound;

} RGNDATAHEADER;

The RGNDATAHEADER structure describes the data returned by the GetRegionData function.

Member	Description

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

RECT, RGNDATA


RIP_INFO structure
RIP_INFO (Win32)

typedef struct _RIP_INFO { /* ri */

    DWORD  dwError;

    DWORD  dwType;

} RIP_INFO;

The RIP_INFO structure contains the error and address, format, and length, in bytes, of a debugging string.

Member	Description

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


SECURITY_ATTRIBUTES structure
SECURITY_ATTRIBUTES (Win32)

typedef struct _SECURITY_ATTRIBUTES { /* sa */

    DWORD  nLength;

    LPVOID lpSecurityDescriptor;

    BOOL   bInheritHandle;

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

Member	Description

nLength	Specifies the length, in bytes, of this structure. This value is to be set to the size of the SECURITY_ATTRIBUTES structure.

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.

Comments

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 structure
SECURITY_DESCRIPTOR (Win32)

typedef PVOID PSECURITY_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.

Comments

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, ACL, SID


SECURITY_DESCRIPTOR_CONTROL structure
SECURITY_DESCRIPTOR_CONTROL (Win32)

typedef WORD 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.

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, ACL, SECURITY_DESCRIPTOR, SID


SECURITY_IMPERSONATION_LEVEL structure
SECURITY_IMPERSONATION_LEVEL (Win32)

typedef enum tagSECURITY_IMPERSONATION_LEVEL { /* sil */

    SecurityAnonymous,

    SecurityIdentification,

    SecurityImpersonation,

    SecurityDelegation

} SECURITY_IMPERSONATION_LEVEL;

The SECURITY_IMPERSONATION_LEVEL enumerated type specifies impersonation levels. Security impersonation levels govern the degree to which a server process can act on behalf of a client process.

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 use kernel functions. This is useful for servers that export their own objects--for example, tables and views exported by a database product. 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	This impersonation level is not supported in the current version of Windows NT.

Comments

Impersonation is the ability of a process to take on the security attributes of another process.

See Also

CreatePrivateObjectSecurity, DuplicateToken, GetTokenInformation, ImpersonateSelf, OpenThreadToken


SECURITY_INFORMATION structure
SECURITY_INFORMATION (Win32)

typedef DWORD 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

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_DESCRIPTOR


SECURITY_QUALITY_OF_SERVICE structure
SECURITY_QUALITY_OF_SERVICE (Win32)

typedef struct _SECURITY_QUALITY_OF_SERVICE { /* sqos */

    DWORD Length;

    SECURITY_IMPERSONATION_LEVEL ImpersonationLevel;

    SECURITY_CONTEXT_TRACKING_MODE ContextTrackingMode;

    BOOLEAN EffectiveOnly;

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

Member	Description

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 enumerated type value.

ContextTracking Mode	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.

Effective Only	Specifies whether or not the server may enable or disable privileges and groups that the client's security context may include.

See Also

SECURITY_IMPERSONATION_LEVEL


SERVICE_STATUS structure
SERVICE_STATUS

typedef struct _SERVICE_STATUS { /* ss */

    DWORD dwServiceType;

    DWORD dwCurrentState;

    DWORD dwControlsAccepted;

    DWORD dwWin32ExitCode;

    DWORD dwServiceSpecificExitCode;

    DWORD dwCheckPoint;

    DWORD dwWaitHint;

} SERVICE_STATUS, *LPSERVICE_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.

Member	Description

dwServiceType	Indicates the type of service. One of the following values is specified.

Type	Meaning

SERVICE_WIN32_OWN_PROCESS	Specifies a service that runs in its own Win32 process.

SERVICE_WIN32_SHARE_PROCESS	Specifies a service that shares a Win32 process with other services.

SERVICE_KERNEL_DRIVER	Specifies a Windows NT device driver.

SERVICE_FILE_SYSTEM_DRIVER	Specifies a Windows NT file system driver.

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

SERVICE_ACCEPT_PAUSE_CONTINUE

The service can be paused and continued. This enables the SERVICE_CONTROL_PAUSE and SERVICE_CONTROL_CONTINUE commands.

SERVICE_ACCEPT_SHUTDOWN

The service is notified when system shutdown occurs. This enables the system to send a SERVICE_CONTROL_SHUTDOWN command 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 the amount of time, in milliseconds, that the service expects a pending start, stop, or continue operation to take before completion. The user interface program that invoked the operation waits this amount of time before calling QueryServiceStatus to see if the operation has been completed. If the operation has not been completed but dwCheckPoint has been incremented indicating that the service is making progress, the user interface program should wait this amount of time again. When the service does not have a start, stop, or continue operation pending, this value is not valid and should be zero.

See Also

ControlService, EnumDependentServices, EnumServicesStatus, QueryServiceStatus, SetServiceStatus


SERVICE_TABLE_ENTRY structure
SERVICE_TABLE_ENTRY

typedef struct _SERVICE_TABLE_ENTRY { /* ste */

    LPTSTR lpServiceName;

    LPSERVICE_MAIN_FUNCTION lpServiceProc;

} SERVICE_TABLE_ENTRY, *LPSERVICE_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.

Member	Description

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


SESSION_BUFFER structure
SESSION_BUFFER (Win32)

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;

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 NCBSSTAT in the ncb_command member of the NCB structure.

Member	Description

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 structure
SESSION_HEADER (Win32)

typedef struct _SESSION_HEADER { /* sh */

    UCHAR sess_name;

    UCHAR num_sess;

    UCHAR rcv_dg_outstanding;

    UCHAR rcv_any_outstanding;

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

Member	Description

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


SET_PARTITION_INFORMATION structure
SET_PARTITION_INFORMATION (Win32)

typedef struct _SET_PARTITION_INFORMATION {

   BYTE PartitionType;

} SET_PARTITION_INFORMATION ;

The SetPartitionInformation structure provides information used to set a disk partition's type.

Member	Description

PartitionType	Specifies the type of partition. This member can take on 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.

Comments

The DeviceIoControl function  uses a SET_PARTITION_INFORMATION structure as input to an IOCTL_DISK_SET_PARTITION_INFO device i/o operation.

See Also

DeviceIoControl, IOCTL_DISK_SET_PARTITION_INFO, IOCTL_DISK_GET_PARTITION_INFO, PARTITION_INFORMATION


SID structure
SID (Win32)

typedef PVOID PSID;

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.

See Also

AllocateAndInitializeSid, CopySid, EqualSid, FreeSid, GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, InitializeSid, IsValidSid, LookupAccountName, LookupAccountSid, SID_AND_ATTRIBUTES, SID_IDENTIFIER_AUTHORITY, SID_NAME_USE


SID_AND_ATTRIBUTES structure
SID_AND_ATTRIBUTES (Win32)

typedef struct _SID_AND_ATTRIBUTES { /* saa */

    PSID  Sid;

    DWORD Attributes;

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

Member	Description

Sid	Points to an 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.

Comments

A group is represented by an SID. SIDs have attributes that indicate whether they are currently enabled, disabled, or mandatory, and how they are used. An SID_AND_ATTRIBUTES structure can represent an 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 structure
SID_IDENTIFIER_AUTHORITY (Win32)

typedef struct _SID_IDENTIFIER_AUTHORITY { /* sia */

    BYTE Value[6];

} SID_IDENTIFIER_AUTHORITY ;

The SID_IDENTIFIER_AUTHORITY structure represents the top-level authority of a security identifier (SID).

Member	Description

Value	An array of six bytes specifying a SID's top-level authority.

Comments

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

An SID must contain a top-level authority and at least one relative identifier (RID) value.

See Also

AllocateAndInitializeSid, GetSidIdentifierAuthority, InitializeSid, SID


SID_NAME_USE structure
SID_NAME_USE (Win32)

typedef enum tagSID_NAME_USE {

    SidTypeUser = 1,

    SidTypeGroup,

    SidTypeDomain,

    SidTypeAlias,

    SidTypeWellKnownGroup,

    SidTypeDeletedAccount,

    SidTypeInvalid,

    SidTypeUnknown

} SID_NAME_USE;

The SID_NAME_USE enumerated type lists the uses of security identifiers (SIDs). The enumerators indicate what a SID represents.

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, SID


SINGLE_LIST_ENTRY structure
SINGLE_LIST_ENTRY (Win32)

typedef struct _SINGLE_LIST_ENTRY { /* sle */

    struct _SINGLE_LIST_ENTRY *Next;

} SINGLE_LIST_ENTRY;

The SINGLE_LIST_ENTRY structure is available for any entry in a single-linked list.

Member	Description

Next	Points to the next entry in a single-linked list.

Comments

This structure can be used as the beginning of a single-linked list or as any subsequent entry in the list.


SIZE structure
SIZE (Win32)

typedef struct tagSIZE { /* siz */

    LONG cx;

    LONG cy;

} SIZE;

The SIZE structure specifies the width and height of a rectangle.

Member	Description

cx	Specifies the rectangle's width.

cy	Specifies the rectangle's height.

Comments

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, GetTextExtentPoint, GetViewportExtEx, GetWindowExtEx, ScaleViewportExtEx, ScaleWindowExtEx, SetBitmapDimensionEx, SetViewportExtEx, SetWindowExtEx


SMALL_RECT structure
SMALL_RECT (Win32)

typedef struct _SMALL_RECT { /* srct */

    SHORT Left;

    SHORT Top;

    SHORT Right;

    SHORT Bottom;

} SMALL_RECT;

The SMALL_RECT structure defines the coordinates of the upper-left and lower-right corners of a rectangle. 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.

Member	Description

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.

See Also

RECT, RECTL


STARTUPINFO structure
STARTUPINFO (Win32)

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;

The STARTUPINFO structure is used in 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 affects the first window created by the CreateWindow function. For console processes, this 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 it was created.

Member	Description

cb	Specifies the size, in bytes, of the structure.

lpReserved	Reserved. Set this member to NULL before passing the structure to CreateProcess.

lpDesktop	If non-NULL, this parameter refers to the name of a desktop to start the process in. If the desktop exists, the new process is associated with this desktop. If the desktop does not exist, a desktop with default attributes is created by this name for the new 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 CreateWindow is called 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 CreateWindow is called 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, specifies the screen buffer width (dwXCountChars) and height (dwYCountChars), in character columns and rows, if a new console window is created. These values are ignored in GUI processes.

dwFillAttribute	Ignored unless dwFlags specifies STARTF_USEFILLATTRIBUTE. For console processes, specifies the initial text and background colors if a new console window is created. These values are ignored in GUI processes.

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 not specified, the wShowWindow member is ignored.

STARTF_USEPOSITION

If not specified, the dwX and dwY members are ignored.

STARTF_USESIZE

If not specified, the dwXSize and dwYSize members are ignored.

STARTF_USECOUNTCHARS

If not specified, the dwXCountChars and dwYCountChars members are ignored.

STARTF_USEFILLATTRIBUTE

If not specified, the dwFillAttribute member is ignored.

STARTF_FORCEONFEEDBACK

If 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 Comments 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 Comments section.

STARTF_SCREENSAVER

If specified, the system will treat this application as a screen saver. To wit:

The system allows the application to initialize at the foreground priority of the priority class passed to the CreateProcess function.

When the application looks for input via the GetMessage or PeekMessage function for the first time, the system changes it to the idle priority class. That lets background applications get priority over it.

When the user moves the mouse or hits a key, the system gives the application the foreground priority of the priority class originally passed to the CreateProcess function.

Creating a screen saver with NORMAL_PRIORITY_CLASS lets the screen saver initialize and terminate over other normal priority applications.

STARTF_USESTDHANDLES

If specified, sets the process' standard input, standard output, and standard error handles to the handles specified in the hStdInput, hStdOutput, and hStdError fields of the STARTUPINFO structure. The CreateProcess function's fInheritHandles flag must be set to TRUE for this to work properly.

If not specified, any handles specified in the aforementioned standard handle fields of the STARTUPINFO structure are ignored.

wShowWindow	Ignored unless dwFlags specifies STARTF_USESHOWWINDOW. For GUI processes, specifies the default value the first time ShowWindow is called, if the nCmdShow parameter of ShowWindow is SW_SHOWDEFAULT. Can be any of the SW_ constants defined in WINUSER.H.

In previous versions of Windows, the WinMain function had an nCmdShow parameter that applications were encouraged to pass to the CreateWindow or ShowWindow function. The nCmdShow parameter is no longer available through WinMain. Now applications are encouraged to use SW_SHOWDEFAULT as the default ShowWindow command, in which case, ShowWindow uses the wShowWindow member of the process's STARTUPINFO structure.

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 process' standard input handle if STARTF_USESTDHANDLES is specified.

hStdOutput	Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the process' standard output handle if STARTF_USESTDHANDLES is specified.

hStdError	Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the process' standard error handle if STARTF_USESTDHANDLES is specified.

Comments

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


WIN32_STREAM_ID structure
WIN32_STREAM_ID (Win32)

struct WIN32_STREAM_ID {

    DWORD dwStreamId;

    DWORD dwStreamAttributes;

    LARGE_INTEGER Size;

    DWORD dwStreamNameSize;

    WCHAR  cStreamName[ ] ;

}

Member	Description

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


String structure
String (Win32)

String {

    WCHAR  szKey[];

    BYTE   Padding[];

    String Value[];

} String;

The String structure depicts the organization of data in a file-version resource. This structure is not a true C data 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.

Member	Description

szKey	Specifies an arbitrary 7-bit ASCII English string. The szKey member can be one of the following values:

String	Description

Comments	Value contains any additional information that should be displayed for diagnostic purposes. This string is optional and can be of an arbitrary length.

CompanyName	Value identifies the company that produced the file. For example, "Microsoft Corporation" or "Standard Microsystems Corporation, Inc." This string is required.

FileDescription	Value 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". This string is required.

FileVersion	Value identifies the version of this file. For example, Value could be "3.00A" or "5.00.RC2". This string is required.

InternalName	Value 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. This string is required.

LegalCopyright	Value 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. This string is optional. In English, this string should be in the format "Copyright Microsoft Corp. 1990-1992".

LegalTrademarks	Value 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. This string is optional. In English, this string should be in the format "Windows is a trademark of Microsoft Corporation".

OriginalFilename	Value 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. This string is required.

PrivateBuild	Value 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	Value identifies the name of the product with which this file is distributed. For example, this string could be "Microsoft Windows". This string is required.

ProductVersion	Value identifies the version of the product with which this file is distributed. For example, Value could be "3.00A" or "5.00.RC2". This string is required.

SpecialBuild	Value 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 bytes as necessary to align the Value member on a 32-bit boundary.

Value	Specifies a zero-terminated string formatted in the language and code page indicated by the current StringTable structure. See the szKey description for more information.

Comments

For example, a String structure may have an szKey value of "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 04070000, that is, German/ASCII.

See Also

StringTable, VS_VERSION_INFO


StringFileInfo structure
StringFileInfo (Win32)

StringFileInfo {

    WCHAR       szKey[];

    BYTE        Padding[];

    StringTable Children[];

};

The StringFileInfo structure depicts the organization of data in a file-version resource. This structure is not a true C data 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 in a particular language and code page. A code page is an ordered character set.

Member	Description

szKey	Contains "StringFileInfo".

Padding	Contains as many zero bytes as necessary to align the Children member on a 32-bit boundary.

Children	Specifies a list of one or more StringTable structures. Each StringTable structure's szKey member indicates the appropriate language and code-page formatting.

Comments

The Children member of the VS_VERSION_INFO structure may contain zero or more StringFileInfo structures.

See Also

StringTable, VS_VERSION_INFO


StringTable structure
StringTable (Win32)

StringTable {

    WCHAR  szKey[];

    BYTE   Padding[];

    String Children[];

};

The StringTable structure depicts the organization of data in a file-version resource. This structure is not a true C data 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.

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.

Member	Description

szKey	Specifies an 8-digit hexadecimal number stored as a string. The four most significant digits represent the language identifier, and 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. The following language identifiers are valid:

Identifier	Language

0x0401	Arabic

0x0402	Bulgarian

0x0403	Catalan

0x0404	Traditional Chinese

0x0804	Simplified Chinese

0x0405	Czech

0x0406	Danish

0x0407	German

0x0807	Swiss German

0x0408	Greek

0x0409	U.S. English

0x0809	U.K. English

0x040A	Castilian Spanish

0x080A	Mexican Spanish

0x040B	Finnish

0x040C	French

0x080C	Belgian French

0x0C0C	Canadian French

0x100C	Swiss French

0x040D	Hebrew

0x040E	Hungarian

0x040F	Icelandic

0x0410	Italian

0x0810	Swiss Italian

0x0411	Japanese

0x0412	Korean

0x0413	Dutch

0x0813	Belgian Dutch

0x0414	Norwegian--Bokmål

0x0814	Norwegian--Nynorsk

0x0415	Polish

0x0416	Brazilian Portuguese

0x0816	Portuguese

0x0417	Rhaeto-Romanic

0x0418	Romanian

0x0419	Russian

0x041A	Croato-Serbian (Latin)

0x081A	Serbo-Croatian (Cyrillic)

0x041B	Slovak

0x041C	Albanian

0x041D	Swedish

0x041E	Thai

0x041F	Turkish

0x0420	Urdu

0x0421	Bahasa

The code-page value can be one of the following or any IBM-registered code page:

Code page	Description

0	7-bit ASCII

932	Windows, Japan (Shift--JIS X-0208)

949	Windows, Korea (Shift--KSC 5601)

950	Windows, Taiwan (GB5)

1200	Unicode

1250	Windows, Latin-2 (Eastern European)

1251	Windows, Cyrillic

1252	Windows, Multilingual (ANSI)

1253	Windows, Greek

1254	Windows, Turkish

1255	Windows, Hebrew

1256	Windows, Arabic

Files designed for the English version of Windows would normally be marked with a code-page value of 1252.

Padding	Contains as many zero bytes as necessary to align the Children member on a 32-bit boundary.

Children	Specifies a list of zero or more String structures.

Comments

The Children member of the StringFileInfo structure contains at least one StringTable structure with an szKey value of "04090000". This value indicates that the language is U.S. English and the code page is generic 7-bit ASCII.

See Also

String, StringFileInfo, VS_VERSION_INFO


SYSTEM_ALARM_ACE structure
SYSTEM_ALARM_ACE (Win32)

Reserved for future use.


SYSTEM_AUDIT_ACE structure
SYSTEM_AUDIT_ACE (Win32)

typedef struct _SYSTEM_AUDIT_ACE { /* sada */

    ACE_HEADER  Header;

    ACCESS_MASK Mask;

    DWORD       SidStart;

} 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).

Member	Description

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 an 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 an SID for this member, audit messages are generated for the specified access rights for all users and groups.

Comments

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 structure
SYSTEM_INFO (Win32)

typedef struct _SYSTEM_INFO { /* sinf */

    DWORD  dwOemId;

    DWORD  dwPageSize;

    LPVOID lpMinimumApplicationAddress;

    LPVOID lpMaximumApplicationAddress;

    DWORD  dwActiveProcessorMask;

    DWORD  dwNumberOfProcessors;

    DWORD  dwProcessorType;

    DWORD  dwAllocationGranularity;

    DWORD  dwReserved;

} SYSTEM_INFO;

The SYSTEM_INFO structure contains information about the current computer system. This information includes the processor type, page size, original equipment manufacturer (OEM) identifier, and other such information.

Member	Description

dwOemId	Returns a computer identifier that is specific to a particular OEM.

dwPageSize	Returns the page size and specifies the granularity of page protection and commitment.

lpMinimumApplicationAddress	Returns the lowest memory address accessible to applications and dynamic-link libraries (DLLs).

lpMaximumApplicationAddress	Returns the highest memory address accessible to applications and DLLs.

dwActiveProcessorMask	Returns a mask representing the set of processors configured into the system. Bit 0 is processor 0; bit 31 is processor 31.

dwNumberOfProcessors	Returns the number of processors in the system.

dwProcessorType	Returns the type of the current processors in the system. All processors are assumed to be of the same type, have the same stepping, and are configured with the same options.

The following processor type constants are currently defined :

PROCESSOR_INTEL_386

PROCESSOR_INTEL_486

PROCESSOR_INTEL_PENTIUM

PROCESSOR_INTEL_860

PROCESSOR_MIPS_R2000

PROCESSOR_MIPS_R3000

PROCESSOR_MIPS_R4000

PROCESSOR_ALPHA_21064

dwAllocationGranularity	Returns the allocation granularity in which memory will be allocated on. This value was hard-coded as 64k in the past, but other hardware architectures may require different values.

dwReserved	Reserved.

See Also

GetSystemInfo, MapViewOfFile, MapViewOfFileEx


SYSTEMTIME structure
SYSTEMTIME (Win32)

typedef struct _SYSTEMTIME {  /* st */

    WORD wYear;

    WORD wMonth;

    WORD wDayOfWeek;

    WORD wDay;

    WORD wHour;

    WORD wMinute;

    WORD wSecond;

    WORD wMilliseconds;

} SYSTEMTIME;

The SYSTEMTIME structure represents a date and time using individual members for the month, day, year, weekday, hour, minute, second, and millisecond.

Member	Description

wYear	Specifies the current year.

wMonth	Specifies the current month; January = 1.

wDayOfWeek	Specifies the current day of the week; Sunday = 0, Monday = 1, etc.

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.

See Also

GetLocalTime, GetSystemTime, SetLocalTime, SetSystemTime, FILETIME


TAPE_CREATE_PARTITION structure
TAPE_CREATE_PARTITION (Win32)

typedef struct _TAPE_CREATE_PARTITION {  /* tcp */

    ULONG Method;

    ULONG Count;

    ULONG Size;

} TAPE_CREATE_PARTITION;

The TAPE_CREATE_PARTITION structure describes the size and number of tape partitions of a specified type.

Member	Description

Method	Specifies the type of partition. This member must have one of the following values:

Value	Meaning

TAPE_PARTITION_FIXED	Indicates that the partition parameters are fixed by the device.

TAPE_PARTITION_INITIATOR	Indicates that the number of partitions is specified by Count and the partition sizes are specified in the Size array.

TAPE_PARTITION_SELECT	Indicates that the number of partitions is specified by Count and the partition sizes are defined by the device.

Count	Specifies the number of partitions to create and the number of elements in the Size array.

Size	Specifies the size, in megabytes, of each partition. If this value is zero, the partition is the size of the rest of the storage space on the tape.


TAPE_ERASE structure
TAPE_ERASE (Win32)

typedef struct _TAPE_ERASE { /* ter */

    ULONG Type;

} TAPE_ERASE;

The TAPE_ERASE structure describes the partition to be erased.

Member	Description

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 structure
TAPE_GET_DRIVE_PARAMETERS (Win32)

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;

The TAPE_GET_DRIVE_PARAMETERS structure describes the tape drive.

Member	Description

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 have one or more of following bits set:

Value	Meaning

TAPE_DRIVE_COMPRESSION	Device supports hardware data compression.

TAPE_DRIVE_ECC	Device supports hardware error correction.

TAPE_DRIVE_ERASE_BOP_ONLY	Device performs the erase operation from the beginning-of-partition marker only.

TAPE_DRIVE_ERASE_LONG	Device performs a long erase operation.

TAPE_DRIVE_ERASE_IMMEDIATE	Device performs an immediate erase operation-- that is, it returns when the erase operation begins.

TAPE_DRIVE_ERASE_SHORT	Device performs a short erase operation.

TAPE_DRIVE_FIXED	Device creates fixed data partitions.

TAPE_DRIVE_FIXED_BLOCK	Device supports fixed-length block mode.

TAPE_DRIVE_INITIATOR	Device creates initiator-defined partitions.

TAPE_DRIVE_PADDING	Device supports data padding.

TAPE_DRIVE_GET_ABSOLUTE_BLK	Device provides the current device-specific block address.

TAPE_DRIVE_GET_LOGICAL_BLK	Device provides the current logical block address (and logical tape partition).

TAPE_DRIVE_REPORT_SMKS	Device supports setmark reporting.

TAPE_DRIVE_SELECT	Device creates select data partitions.

TAPE_DRIVE_SET_EOT_WT_SIZE	Device supports setting the end-of-medium warning size.

TAPE_DRIVE_TAPE_CAPACITY	Device returns the maximum capacity of the tape.

TAPE_DRIVE_TAPE_REMAINING	Device returns the remaining capacity of the tape.

TAPE_DRIVE_VARIABLE_BLOCK	Device supports variable-length block mode.

TAPE_DRIVE_WRITE_PROTECT	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 have one or more of the following bits set:

Value	Meaning

TAPE_DRIVE_ABS_BLK_IMMED	Device moves the tape to a device-specific block address and returns as soon as the move begins.

TAPE_DRIVE_ABSOLUTE_BLK	Device moves the tape to a device specific block address.

TAPE_DRIVE_END_OF_DATA	Device moves the tape to the end-of-data marker in a partition.

TAPE_DRIVE_FILEMARKS	Device moves the tape forward (or backward) a specified number of filemarks.

TAPE_DRIVE_LOAD_UNLOAD	Device enables and disables the device for further operations.

TAPE_DRIVE_LOAD_UNLOAD_IMMED	Device supports immediate load and unload operations.

TAPE_DRIVE_LOCK_UNLOCK	Device enables and disables the tape ejection mechanism.

TAPE_DRIVE_LOCK_UNLK_IMMED	Device supports immediate lock and unlock operations.

TAPE_DRIVE_LOG_BLK_IMMED	Device moves the tape to a logical block address in a partition and returns as soon as the move begins.

TAPE_DRIVE_LOGICAL_BLK	Device moves the tape to a logical block address in a partition.

TAPE_DRIVE_RELATIVE_BLKS	Device moves the tape forward (or backward) a specified number of blocks.

TAPE_DRIVE_REVERSE_POSITION	Device moves the tape backward over blocks, filemarks, or setmarks.

TAPE_DRIVE_REWIND_IMMEDIATE	Device supports immediate rewind operation.

TAPE_DRIVE_SEQUENTIAL_FMKS	Device moves the tape forward (or backward) to the first occurrence of a specified number of consecutive filemarks.

TAPE_DRIVE_SEQUENTIAL_SMKS	Device moves the tape forward (or backward) to the first occurrence of a specified number of consecutive setmarks.

TAPE_DRIVE_SET_BLOCK_SIZE	Device supports setting the size of a fixed-length logical block or setting the variable-length block mode.

TAPE_DRIVE_SET_COMPRESSION	Device enables and disables hardware data compression.

TAPE_DRIVE_SET_ECC	Device enables and disables hardware error correction.

TAPE_DRIVE_SET_PADDING	Device enables and disables data padding.

TAPE_DRIVE_SET_REPORT_SMKS	Device enables and disables the reporting of setmarks.

TAPE_DRIVE_SETMARKS	Device moves the tape forward (or reverse) a specified number of setmarks.

TAPE_DRIVE_SPACE_IMMEDIATE	Device supports immediate spacing.

TAPE_DRIVE_TENSION	Device supports tape tensioning.

TAPE_DRIVE_TENSION_IMMED	Device supports immediate tape tensioning.

TAPE_DRIVE_WRITE_FILEMARKS	Device writes filemarks.

TAPE_DRIVE_WRITE_LONG_FMKS	Device writes long filemarks.

TAPE_DRIVE_WRITE_MARK_IMMED	Device supports immediate writing of short and long filemarks.

TAPE_DRIVE_WRITE_SETMARKS	Device writes setmarks.

TAPE_DRIVE_WRITE_SHORT_FMKS	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 structure
TAPE_GET_MEDIA_PARAMETERS (Win32)

typedef struct _TAPE_GET_MEDIA_PARAMETERS {  /* tgmp */

    LARGE_INTEGER   Capacity;

    LARGE_INTEGER   Remaining;

    DWORD   BlockSize;

    DWORD   PartitionCount;

    BOOLEAN WriteProtected;

} TAPE_GET_MEDIA_PARAMETERS;

The TAPE_GET_MEDIA_PARAMETERS structure describes the tape in the tape drive.

Member	Description

Capacity	Specifies the total number of bytes on the tape.

Remaining	Specifies the number of bytes between the current position and the end of the tape.

BlockSize	Specifies the number of bytes per block. Block sizes are typically multiples of 512 bytes, in the range 512 bytes through 32 kilobytes.

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.

Comments

The GetTapeParameters function fills the Remaining and Capacity members with estimates of the tape remaining and the total capacity.


TAPE_GET_POSITION structure
TAPE_GET_POSITION (Win32)

typedef struct _TAPE_GET_POSITION { /* tgpos */

    ULONG Type;

    ULONG Partition;

    ULONG OffsetLow;

    ULONG OffsetHigh;

} TAPE_GET_POSITION;

The TAPE_GET_POSITION structure describes the position of the tape.

Member	Description

Type	Specifies the type of position. This member must be one of the following values:

Value	Description

TAPE_ABSOLUTE_POSITION	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	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 parameter should be zero.


TAPE_SET_POSITION structure
TAPE_SET_POSITION (Win32)

typedef struct _TAPE_SET_POSITION { /* tspos */

    ULONG Method;

    ULONG Partition;

    ULONG OffsetLow;

    ULONG OffsetHigh;

} TAPE_SET_POSITION;

The TAPE_SET_POSITION structure describes how and where to position the tape.

Member	Description

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 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 members 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 parameter should be zero.

Comments

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_PREPARE structure
TAPE_PREPARE (Win32)

typedef struct _TAPE_PREPARE { /* tp */

    ULONG Operation;

} TAPE_PREPARE;

The TAPE_PREPARE structure describes how to prepare the tape.

Member	Description

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. This prevents the tape from being 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 this action.

TAPE_UNLOAD	Rewinds and unloads the tape.

TAPE_UNLOCK	Unlocks the tape ejection mechanism.


TAPE_SET_DRIVE_PARAMETERS structure
TAPE_SET_DRIVE_PARAMETERS (Win32)

typedef struct _TAPE_SET_DRIVE_PARAMETERS {  /* tsdp */

    BOOLEAN ECC;

    BOOLEAN Compression;

    BOOLEAN DataPadding;

    BOOLEAN ReportSetmarks;

    ULONG   EOTWarningZoneSize;

} TAPE_SET_DRIVE_PARAMETERS;

The TAPE_SET_DRIVE_PARAMETERS structure describes the tape drive.

Member	Description

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 structure
TAPE_SET_MEDIA_PARAMETERS (Win32)

typedef struct _TAPE_SET_MEDIA_PARAMETERS { /* tsmp */

    ULONG BlockSize;

} TAPE_SET_MEDIA_PARAMETERS;

The TAPE_SET_MEDIA_PARAMETERS structure describes the tape in the tape drive.

Member	Description

BlockSize	Specifies the number of bytes per block. Block sizes should be powers of 2 : values like 256, 512, 1024, and 204k. Maximum and minimum block sizes can be obtained by calling the GetTapeParameters function.

See Also

GetTapeParameters, SetTapeParameters


TAPE_WRITE_MARKS structure
TAPE_WRITE_MARKS (Win32)

typedef struct _TAPE_WRITE_MARKS { /* twm */

    ULONG Type;

    ULONG Count;

} TAPE_WRITE_MARKS;

The TAPE_WRITE_MARKS structure describes the type and number of tapemarks to write.

Member	Description

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.


TEXTMETRIC structure
TEXTMETRIC (Win32)

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;

    BYTE tmFirstChar;

    BYTE tmLastChar;

    BYTE tmDefaultChar;

    BYTE tmBreakChar;

    BYTE tmItalic;

    BYTE tmUnderlined;

    BYTE tmStruckOut;

    BYTE tmPitchAndFamily;

    BYTE tmCharSet;

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

Member	Description

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 GetTextExtentPoint 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 fixed pitch bitmap font has all of these low-order bits clear; a variable pitch 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, LOGFONT


TIME_ZONE_INFORMATION structure
TIME_ZONE_INFORMATION (Win32)

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;

The TIME_ZONE_INFORMATION structure specifies information specific to the time zone.

Member	Description

Bias	Specifies the current bias, in minutes, for local time translation on this computer. The bias is the difference, in minutes, between Universal Time Convention (UTC) time and local time. All translations between UTC time 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 time 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 time 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


TIMECAPS structure
TIMECAPS (Win32)

typedef struct timecaps_tag {

    UINT  wPeriodMin;

    UINT  wPeriodMax;

} TIMECAPS;

The TIMECAPS structure contains information about the resolution of the timer.

Member	Description

wPeriodMin	Minimum period supported by the timer, in milliseconds.

wPeriodMax	Maximum period supported by the timer, in milliseconds.

See Also

timeGetDevCaps


TOKEN_CONTROL structure
TOKEN_CONTROL (Win32)

typedef struct _TOKEN_CONTROL { /* tc */

    LUID TokenId;

    LUID AuthenticationId;

    LUID ModifiedId;

    TOKEN_SOURCE TokenSource;

} TOKEN_CONTROL ;

The TOKEN_CONTROL structure contains information that identifies an access token.

Member	Description

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 structure
TOKEN_DEFAULT_DACL (Win32)

typedef struct _TOKEN_DEFAULT_DACL {  /* tdd */

    PACL DefaultDacl;

} TOKEN_DEFAULT_DACL;

The TOKEN_DEFAULT_DACL structure specifies a discretionary access-control list (ACL).

Member	Description

DefaultDacl	Points to an ACL structure assigned by default to any objects created by the user represented by the access token.

Comments

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

GetTokenInformation, SetTokenInformation, ACL, TOKEN_CONTROL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_GROUPS structure
TOKEN_GROUPS (Win32)

typedef struct _TOKEN_GROUPS { /* tg */

    DWORD GroupCount;

    SID_AND_ATTRIBUTES Groups[ANYSIZE_ARRAY];

} TOKEN_GROUPS;

The TOKEN_GROUPS structure contains information about a set of groups in an access token.

Member	Description

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_INFORMATION_CLASS structure
TOKEN_INFORMATION_CLASS (Win32)

typedef enum tagTOKEN_INFORMATION_CLASS { /* tic */

    TokenUser = 1,

    TokenGroups,

    TokenPrivileges,

    TokenOwner,

    TokenPrimaryGroup,

    TokenDefaultDacl,

    TokenSource,

    TokenType,

    TokenImpersonationLevel,

    TokenStatistics

} TOKEN_INFORMATION_CLASS;

The TOKEN_INFORMATION_CLASS enumerated type is used to indicate the type of information being assigned to or retrieved from an access token.

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_OWNER structure
TOKEN_OWNER (Win32)

typedef struct _TOKEN_OWNER { /* to */

    PSID Owner;

} TOKEN_OWNER;

The TOKEN_OWNER structure contains the default owner SID that will be applied to newly created objects.

Member	Description

Owner	Points to an 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 structure
TOKEN_PRIMARY_GROUP (Win32)

typedef struct _TOKEN_PRIMARY_GROUP { /* tpg */

    PSID PrimaryGroup;

} TOKEN_PRIMARY_GROUP;

The TOKEN_PRIMARY_GROUP structure specifies a group security identifier (SID) for an access token.

Member	Description

PrimaryGroup	Points to an 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 structure
TOKEN_PRIVILEGES (Win32)

typedef struct _TOKEN_PRIVILEGES { /* tp */

    DWORD PrivilegeCount;

    LUID_AND_ATTRIBUTES Privileges[ANYSIZE_ARRAY];

} TOKEN_PRIVILEGES;

The TOKEN_PRIVILEGES structure contains information about the set of privileges for an access token.

Member	Description

PrivilegeCount	Specifies the number of privileges in the token.

Privileges	Specifies an array of LUID_AND_ATTRIBUTES structures describing the token's privileges.

The following attributes can be used with this parameter:

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, PrivilegeCheck, PrivilegedServiceAuditAlarm, SetTokenInformation, LUID_AND_ATTRIBUTES, PRIVILEGE_SET, 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 structure
TOKEN_SOURCE (Win32)

typedef struct _TOKEN_SOURCE { /* ts */

    CHAR SourceName[8];

    LUID SourceIdentifier;

} TOKEN_SOURCE;

The TOKEN_SOURCE structure identifies the source of an access token.

Member	Description

SourceName	Specifies an eight-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 structure
TOKEN_STATISTICS (Win32)

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;

The TOKEN_STATISTICS structure contains information about an access token. An application can retrieve this information by calling the GetTokenInformation function.

Member	Description

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 may 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_TYPE structure
TOKEN_TYPE (Win32)

typedef enum tagTOKEN_TYPE { /* tt */

    TokenPrimary = 1,

    TokenImpersonation

} TOKEN_TYPE;

The TOKEN_TYPE enumerated type differentiates between a primary and impersonation token.

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


TOKEN_USER structure
TOKEN_USER (Win32)

typedef struct _TOKEN_USER { /* tu */

    SID_AND_ATTRIBUTES User;

} TOKEN_USER;

The TOKEN_USER structure identifies the user associated with an access token.

Member	Description

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


TTPOLYCURVE structure
TTPOLYCURVE (Win32)

typedef struct tagTTPOLYCURVE { /* ttpc */

    WORD    wType;

    WORD    cpfx;

    POINTFX apfx[1];

} TTPOLYCURVE;

The TTPOLYCURVE structure contains information about a curve in the outline of a TrueType® character.

Member	Description

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.

Comments

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

POINTFX, TTPOLYGONHEADER, GetGlyphOutline


TTPOLYGONHEADER structure
TTPOLYGONHEADER (Win32)

typedef struct tagTTPOLYGONHEADER { /* ttph */

    DWORD   cb;

    DWORD   dwType;

    POINTFX pfxStart;

} TTPOLYGONHEADER;

The TTPOLYGONHEADER structure specifies the starting position and type of a contour in a TrueType® character outline.

Member	Description

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.

Comments

Each TTPOLYGONHEADER structure is followed by one or more TTPOLYCURVE structures.

See Also

POINTFX, TTPOLYCURVE, GetGlyphOutline


ULARGE_INTEGER structure
ULARGE_INTEGER (Win32)

typedef struct _ULARGE_INTEGER { /* uli */

    DWORD LowPart;

    DWORD HighPart;

} ULARGE_INTEGER;

The ULARGE_INTEGER structure is used to specify a 64-bit unsigned integer value.

Member	Description

LowPart	Specifies the low-order 32 bits.

HighPart	Specifies the high-order 32 bits.

See Also

LARGE_INTEGER


UNLOAD_DLL_DEBUG_INFO structure
UNLOAD_DLL_DEBUG_INFO (Win32)

typedef struct _UNLOAD_DLL_DEBUG_INFO { /* uddi */

    LPVOID lpBaseOfDll;

} UNLOAD_DLL_DEBUG_INFO;

The UNLOAD_DLL_DEBUG_INFO structure contains information about a dynamic-link library (DLL) that has just been unloaded.

Member	Description

lpBaseOfDll	Points to the base address of the DLL in the address space of the process unloading the DLL.

See Also

DEBUG_EVENT


Var structure
Var (Win32)

Var {

    WCHAR szKey[];

    BYTE  Padding[];

    Var   Value[];

};

The Var structure depicts the organization of data in a file-version resource. This structure is not a true C data 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 contains version information not dependent on a particular language and code page.

Member	Description

szKey	Specifies an arbitrary 7-bit ASCII English string. The szKey member can be the following value:

Value	Meaning

Translation	Value contains an array of doubleword values indicating the language and code-page combinations supported by this file. The high-order word of each doubleword contains a Microsoft language identifier and the low-order word contains 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.

Padding	Contains as many zero bytes as necessary to align the Value member on a 32-bit boundary.

Value	Specifies a list of zero or more Var structures.

Comments

The Children member of the VS_VERSION_INFO structure may contain zero or more Var structures.

See Also

VarFileInfo, VS_VERSION_INFO


VarFileInfo structure
VarFileInfo (Win32)

VarFileInfo {

    WCHAR szKey[];

    BYTE  Padding[];

    Var   Children[];

};

The VarFileInfo structure depicts the organization of data in a file-version resource. This structure is not a true C data 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.

Member	Description

szKey	Contains "VarFileInfo".

Padding	Contains as many zero bytes as necessary to align the Children member on a 32-bit boundary.

Children	Specifies a list of zero or more Var structures.

Comments

The Children member of the VS_VERSION_INFO structure may contain zero or more VarFileInfo structures.

See Also

Var, VS_VERSION_INFO


VERIFY_INFORMATION structure
VERIFY_INFORMATION (Win32)

typedef struct _VERIFY_INFORMATION {

   LARGE_INTEGER  StartingOffset;

   DWORD  Length;

} VERIFY_INFORMATION ;

The VERIFY_INFORMATION structure provides information used to logically format a disk extent.

Member	Description

StartingOffset	Specifies the starting offset of the disk extent.

Length	Length, in bytes, of the disk extent.

Comments

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 structure
VS_FIXEDFILEINFO (Win32)

typedef struct tagVS_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;

The VS_FIXEDFILEINFO structure contains version information about a file. This information is language and code-page independent.

Member	Description

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. This value must be greater than 0x00000029.

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_DOS	The file was designed for MS-DOS.

VOS_OS216	The file was designed for 16-bit OS/2.

VOS_OS232	The file was designed for 32-bit OS/2.

VOS_NT	The file was designed for Windows NT.

VOS_WINDOWS16	The file was designed for 16-bit Windows.

VOS_PM16	The file was designed for 16-bit Presentation Manager.

VOS_PM32	The file was designed for 32-bit Presentation Manager.

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_WINDOWS16	The file was designed for 16-bit Windows running on MS-DOS.

VOS_DOS_WINDOWS32	The file was designed for the Win32 API running on MS-DOS.

VOS_OS216_PM16	The file was designed for 16-bit Presentation Manager running on 16-bit OS/2.

VOS_OS232_PM32	The file was designed for 32-bit Presentation Manager running on 32-bit OS/2.

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.

Comments

The Value member of the VS_VERSION_INFO data is a VS_FIXEDFILEINFO structure.

See Also

StringFileInfo, VS_VERSION_INFO


VS_VERSION_INFO structure
VS_VERSION_INFO (Win32)

VS_VERSION_INFO {

    WORD  wLength;

    WORD  wValueLength;

    WORD  bText;

    WCHAR szKey[];

    BYTE  Padding1[];

    VS_FIXEDFILEINFO Value;

    BYTE  Padding2[];

    BYTE  Children[];

};

The VS_VERSION_INFO structure depicts the organization of data in a file-version resource. This structure is not a true C data 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).

Member	Description

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.

bText	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 "VS_VERSION_INFO".

Padding1	Contains as many zero bytes 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 bytes as necessary to align the Children member on a 32-bit boundary. These bytes are not included in wValueLength.

Children	Specifies a list of zero or more StringFileInfo or VarFileInfo structures (or both) that are children of the current version structure.

Comments

The VS_VERSION_INFO structure is the root structure that contains all other file information structures.

See Also

StringFileInfo, VarFileInfo, VS_FIXEDFILEINFO


WAVEFORMAT structure
WAVEFORMAT (Win32)

typedef struct waveformat_tag {

    WORD  wFormatTag;

    WORD  nChannels;

    DWORD  nSamplesPerSec;

    DWORD  nAvgBytesPerSec;

    WORD  nBlockAlign;

} WAVEFORMAT;

The WAVEFORMAT structure describes the format of waveform data. Only format information common to all waveform data formats is included in this structure. For formats that require additional information, this structure is included as a member in another structure, along with the additional information.

Member	Description

wFormatTag	Specifies the format type. The currently defined waveform format type is WAVE_FORMAT_PCM, which specifies that the waveform data is pulse code modulated (PCM).

nChannels	Specifies the number of channels in the waveform data. Monaural data uses one channel and stereo data uses two channels.

nSamplesPerSec	Specifies the sample rate, in samples per second.

nAvgBytesPerSec	Specifies the required average data-transfer rate, in bytes per second.

nBlockAlign	Specifies the block alignment, in bytes. The block alignment is the minimum atomic unit of data.

Comments

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

See Also

PCMWAVEFORMAT


WAVEHDR structure
WAVEHDR (Win32)

typedef struct wavehdr_tag {

    LPSTR  lpData;

    DWORD  dwBufferLength;

    DWORD  dwBytesRecorded;

    DWORD  dwUser;

    DWORD  dwFlags;

    DWORD  dwLoops;

    struct wavehdr_tag *lpNext;

    DWORD  reserved;

} WAVEHDR;

The WAVEHDR structure defines the header used to identify a waveform data buffer.

Member	Description

lpData	Points to the waveform data buffer.

dwBufferLength	Specifies the length of the data buffer.

dwBytesRecorded	Specifies the amount of data in the buffer, if the header is used in input.

dwUser	Specifies 32 bits of user data.

dwFlags	Specifies flags that provide information about the data buffer. This member can be one or more of the following values:

Value	Meaning

WHDR_DONE	Device driver is finished with the data buffer and is returning it to the application. This flag is set by the device driver.

WHDR_BEGINLOOP	Buffer is the first buffer in a loop. This flag is used only with output data buffers.

WHDR_ENDLOOP	Buffer is the last buffer in a loop. This flag is used only with output data buffers.

WHDR_PREPARED	Data buffer has been prepared by using the waveInPrepareHeader or waveOutPrepareHeader function. This flag is set by Windows.

dwLoops	Specifies the number of times to play the loop. This parameter is used only with output data buffers.

lpNext	Reserved; do not use.

reserved	Reserved; do not use.

Comments

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 of the first block in the loop to specify the number of times to play the loop.


WAVEINCAPS structure
WAVEINCAPS (Win32)

typedef struct waveincaps_tag {

    WORD  wMid;

    WORD  wPid;

    VERSION  vDriverVersion;

    TCHAR  szPname[MAXPNAMELEN];

    DWORD  dwFormats;

    WORD  wChannels;

} WAVEINCAPS;

The WAVEINCAPS structure describes the capabilities of a waveform input device.

Member	Description

wMid	Specifies a manufacturer identifier for the device driver for the waveform input device.

wPid	Specifies a product identifier for the waveform input device.

vDriverVersion	Specifies the version number of the device driver for the waveform input device. The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname	Specifies the product name in a null-terminated string.

dwFormats	Specifies the standard formats supported. This member can be a combination of the following values:

Value	Meaning

WAVE_FORMAT_1M08	11.025 kHz, monaural, 8-bit

WAVE_FORMAT_1S08	11.025 kHz, stereo, 8-bit

WAVE_FORMAT_1M16	11.025 kHz, monaural, 16-bit

WAVE_FORMAT_1S16	11.025 kHz, stereo, 16-bit

WAVE_FORMAT_2M08	22.05 kHz, monaural, 8-bit

WAVE_FORMAT_2S08	22.05 kHz, stereo, 8-bit

WAVE_FORMAT_2M16	22.05 kHz, monaural, 16-bit

WAVE_FORMAT_2S16	22.05 kHz, stereo, 16-bit

WAVE_FORMAT_4M08	44.1 kHz, monaural, 8-bit

WAVE_FORMAT_4S08	44.1 kHz, stereo, 8-bit

WAVE_FORMAT_4M16	44.1 kHz, monaural, 16-bit

WAVE_FORMAT_4S16	44.1 kHz, stereo, 16-bit

wChannels	Specifies whether the device supports monaural (1) or stereo (2) input.

See Also

waveInGetDevCaps


WAVEOUTCAPS structure
WAVEOUTCAPS (Win32)

typedef struct waveoutcaps_tag {

    WORD  wMid;

    WORD  wPid;

    MMVERSION  vDriverVersion;

    TCHAR  szPname[MAXPNAMELEN];

    DWORD  dwFormats;

    WORD  wChannels;

    DWORD  dwSupport;

} WAVEOUTCAPS;

The WAVEOUTCAPS structure describes the capabilities of a waveform output device.

Member	Description

wMid	Specifies a manufacturer identifier for the device driver for the waveform output device.

wPid	Specifies a product identifier for the waveform output device.

vDriverVersion	Specifies the version number of the device driver for the waveform output device. The high-order byte is the major version number, and the low-order byte is the minor version number.

szPname	Specifies the product name in a null-terminated string.

dwFormats	Specifies the standard formats supported. This member can be a combination of the following values:

Value	Meaning

WAVE_FORMAT_1M08	11.025 kHz, monaural, 8-bit

WAVE_FORMAT_1S08	11.025 kHz, stereo, 8-bit

WAVE_FORMAT_1M16	11.025 kHz, monaural, 16-bit

WAVE_FORMAT_1S16	11.025 kHz, stereo, 16-bit

WAVE_FORMAT_2M08	22.05 kHz, monaural, 8-bit

WAVE_FORMAT_2S08	22.05 kHz, stereo, 8-bit

WAVE_FORMAT_2M16	22.05 kHz, monaural, 16-bit

WAVE_FORMAT_2S16	22.05 kHz, stereo, 16-bit

WAVE_FORMAT_4M08	44.1 kHz, monaural, 8-bit

WAVE_FORMAT_4S08	44.1 kHz, stereo, 8-bit

WAVE_FORMAT_4M16	44.1 kHz, monaural, 16-bit

WAVE_FORMAT_4S16	44.1 kHz, stereo, 16-bit

wChannels	Specifies whether the device supports monaural (1) or stereo (2) output.

dwSupport	Specifies optional functionality supported by the device. This member can be one or more of the following values:

Value	Meaning

WAVECAPS_PITCH	Supports pitch control.

WAVECAPS_PLAYBACKRATE	Supports playback rate control.

WAVECAPS_VOLUME	Supports volume control.

WAVECAPS_LRVOLUME	Supports separate left and right volume control.

Comments

If a device supports volume changes, the WAVECAPS_VOLUME flag is 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 are set for this member.

See Also

waveOutGetDevCaps


WIN32_FIND_DATA structure
WIN32_FIND_DATA (Win32)

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;

The WIN32_FIND_DATA structure describes a file found by the FindFirstFile or FindNextFile function.

Member	Description

dwFileAttributes	Specifies the file attributes of the file found.

This flag can be one or more of the following values:

Value	Meaning

FILE_ATTRIBUTE_ARCHIVE

The file is an archive file. Applications use this flag to mark files for backup or removal.

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 attribute is valid only if used alone.

FILE_ATTRIBUTE_READONLY

The file is a read-only file. 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 a temporary file. Applications can 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.

FILE_ATTRIBUTE_ATOMIC_WRITE

Reserved for future use. Do not specify.

FILE_ATTRIBUTE_XACTION_WRITE

Reserved for future use. Do not specify.

ftCreationTime	Specifies the time the file was created. A value of 0,0 indicates that the file system containing the file does not support this time field.

ftLastAccessTime	Specifies the time that the file was last accessed. A value of 0,0 indicates that the file system containing the file does not support this time field.

ftLastWriteTime	Specifies the time that the file was last written to. All file systems support this time field.

nFileSizeHigh	Specifies the high-order word of the file size, in bytes.

nFileSizeLow	Specifies the low-order word of the file size, in bytes.

cFileName	Specifies a null-terminated string that is the name of the file.

cAlternateFileName	Specifies a null-terminated string that is an alternative name of the file, in the 8.3 (filename.ext) format.


WINDOW_BUFFER_SIZE_RECORD structure
WINDOW_BUFFER_SIZE_RECORD (Win32)

typedef struct _WINDOW_BUFFER_SIZE_RECORD { /* wbsr */

    COORD dwSize;

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

Member	Description

dwSize	Specifies the new size of the screen buffer, in character cell columns and rows.

Comments

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 structure
WINDOWPLACEMENT (Win32)

typedef struct tagWINDOWPLACEMENT {     /* wndpl */

    UINT  length;

    UINT  flags;

    UINT  showCmd;

    POINT ptMinPosition;

    POINT ptMaxPosition;

    RECT  rcNormalPosition;

} WINDOWPLACEMENT;

The WINDOWPLACEMENT structure contains information about the placement of a window on the screen.

Member	Description

length	Specifies the length, in bytes, of the structure.

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

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.

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 top-left corner when the window is minimized.

ptMaxPosition	Specifies the coordinates of the window's top-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, GetWindowPlacement, SetWindowPlacement


WINDOWPOS structure
WINDOWPOS (Win32)

typedef struct tagWINDOWPOS { /* wp */

    HWND hwnd;

    HWND hwndInsertAfter;

    int  x;

    int  y;

    int  cx;

    int  cy;

    UINT flags;

} WINDOWPOS;

The WINDOWPOS structure contains information about the size and position of a window.

Member	Description

hwnd	Identifies the window.

hwndInsertAfter	Identifies the window behind which this window is placed.

x	Specifies the position of the left edge of the window.

y	Specifies the position of the right 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. The window receives a WM_NCCALCSIZE message.

SWP_HIDEWINDOW	Hides the window.

SWP_NOACTIVATE	Does not activate the window.

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 has been 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_NOSIZE	Retains the current size (ignores the cx and cy parameters).

SWP_NOREDRAW	Does not redraw changes.

SWP_NOREPOSITION	Same as the SWP_NOOWNERZORDER flag.

SWP_NOZORDER	Retains the current Z order (ignores the hwndInsertAfter member).

SWP_SHOWWINDOW	Displays the window.

See Also

EndDeferWindowPos, SetWindowPos, WM_NCCALCSIZE, WM_WINDOWPOSCHANGED, WM_WINDOWPOSCHANGING


WNDCLASS structure
WNDCLASS (Win32)

typedef struct tagWNDCLASS {    /* wc */

    UINT    style;

    WNDPROC lpfnWndProc;

    int     cbClsExtra;

    int     cbWndExtra;

    HANDLE  hInstance;

    HICON   hIcon;

    HCURSOR hCursor;

    HBRUSH  hbrBackground;

    LPCTSTR lpszMenuName;

    LPCTSTR lpszClassName;

} WNDCLASS;

The WNDCLASS structure contains the window class attributes that are registered by the RegisterClass function.

Member	Description

style	Specifies the class style. These 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 (DC) 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 DC 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 registration database 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	Gives the parent window's device context to the child windows. Specifying CS_PARENTDC enhances an application's performance. When an application calls the GetDC function, passing the handle of a window that belongs to a class with the CS_PARENTDC style, the operating system searches for a device context that has been precalculated for the window's parent window. If all child windows of a particular parent window specify this style, the system need not recalculate a device context for any of the child windows.

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 that are displayed briefly and then removed before other screen activity takes place (for example, menus or dialog boxes). 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 the description of the WindowProc callback function.

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 standard system colors listed below, and the value 1 must be added to the chosen color; for example, COLOR_BACKGROUND + 1 specifies the system background 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 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 in the low-order word of lpszClassName; the high-order word must be zero.

The lpszClassName string or atom specifies the window class name.

See Also

GlobalAddAtom, PAINTSTRUCT, WindowProc


XFORM structure
XFORM (Win32)

typedef struct  tagXFORM {  /* xfrm */

    FLOAT eM11;

    FLOAT eM12;

    FLOAT eM21;

    FLOAT eM22;

    FLOAT eDx;

    FLOAT eDy;

} XFORM;

The XFORM structure specifies a world-space to page-space transformation.

Member	Description

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.

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


Structures (all)

ABC	Contains width for character in TrueType font

ABCFLOAT	Contains fractional character widths

ACCEL	Specifies an accelerator key for ACCELTABLE

ACCESS_ALLOWED_ACE	Allows access to an object

ACCESS_DENIED_ACE	Denies access to an object

ACCESS_MASK	Standard, specific and generic access rights

ACE	Specifies security access

ACE_HEADER	Defines ACE type and flags

ACL	List of access-control entries

ACL_INFORMATION_CLASS	Indicates ACL information type

ACL_REVISION_INFORMATION	Contains ACL revision information

ACL_SIZE_INFORMATION	Contains ACL size information

ACTION_HEADER	Contains information about a transport action

ADAPTER_STATUS	Contains network-device information

ADDJOB_INFO_1	Identifies a print job

AUXCAPS	Describes auxiliary device capabilities

BITMAP	Defines characteristics of logical bitmap

BITMAPCOREHEADER	Defines PM-compatible DIB

BITMAPCOREINFO	Defines PM-compatible DIB and colors

BITMAPFILEHEADER	Defines characteristics of a DIB file

BITMAPINFO	Defines characteristics and color of a DIB

BITMAPINFOHEADER	Defines characteristics of a DIB

BY_HANDLE_FILE_INFORMATION	Contains handle-based file information

CBT_CREATEWND	Contains data passed to the WH_CBT hook

CBTACTIVATESTRUCT	Contains data passed to the WH_CBT hook

CHAR_INFO	Screen buffer cell information

CHARSET	Contains font-character information

CHOOSECOLOR	Data for color-select dialog box

CHOOSEFONT	Contains data for font-selection dialog box

COLORADJUSTMENT	Defines bitmap color-adjustment values

CLIENTCREATESTRUCT	Defines window menu and first MDI child

COLORREF	Specifies an RGB color

COMMPROP	Contains communications driver information

COMMTIMEOUTS	Contains communications timeout information

COMPAREITEMSTRUCT	Contains data for sorted owner-drawn control

COMSTAT	Contains data about a communications device

CONSOLE_CURSOR_INFO	Specifies cursor size and visibility

CONSOLE_SCREEN_BUFFER_INFO	Contains console screen-buffer information

CONTEXT	Processor specific register data

CONVCONTEXT	Contains language data for a DDE conversation

CONVINFO	Contains information about a DDE conversation

COORD	Specifies x and y coordinates

COPYDATASTRUCT	Contains data to send to another application

CPINFO	Code page information

CPLINFO	Contains Control Panel app resource data

CREATE_PROCESS_DEBUG_INFO	Contains process-creation debug info

CREATE_THREAD_DEBUG_INFO	Contains process-creation debug info

CREATESTRUCT	Defines window-initialization parameters

CWPSTRUCT	Defines WH_CALLWNDPROC message parameters

DCB	Defines settings for serial comm. device

DDEACK	Status flags sent by a WM_DDE_ACK message

DDEADVISE	Contains flags sent by a WM_DDE_ADVISE message

DDEDATA	Contains data send by a WM_DDE_DATA message

DDELN	Obsolete

DDEML_MSG_HOOK_DATA	Contains DDEML message-monitoring information

DDEPOKE	Contains data send by a WM_DDE_POKE message

DDEUP	Obsolete

DEBUG_EVENT	Contains debug-event details

DEBUGHOOKINFO	Contains data used for debugging

DELETEITEMSTRUCT	Describes an owner-drawn item

DEVMODE	Contains information about printer environment

DEVNAMES	Contains device data for print-text dialog box

DISK_GEOMETRY	Provides disk geometry information

DISK_PERFORMANCE	Provides disk performance information

DLGITEMTEMPLATE	Sets dimensions and style of dialog box controls

DLGTEMPLATE	Defines dimensions and style of a dialog box

DOCINFO	Contains document input and output filenames

DOC_INFO_1	Describes a document to be printed

DRAWITEMSTRUCT	Contains painting data for owner-drawn control

DRIVE_LAYOUT_INFORMATION	Provides drive layout information

DRIVER_INFO_1	Identifies a printer driver

DRIVER_INFO_2	Describes printer driver

EMRFORMAT	Identifies enhanced metafile graphics data information

ENHMETAHEADER	Contains enhanced metafile data

ENHMETARECORD	Information about part of a metafile picture

ENUMLOGFONT	Specifies a logical font for enumeration

ENUM_SERVICE_STATUS	Enumerated service name and status

EVENTLOGRECORD	Describes event log record

EVENTMSG	Contains journaling hook message information

EXCEPTION_DEBUG_INFO	Contains exception debug information

EXCEPTION_POINTERS	Specifies exception and processor context

EXCEPTION_RECORD	Describes an exception

EXIT_PROCESS_DEBUG_INFO	Contains process exit code

EXIT_THREAD_DEBUG_INFO	Contains thread exit code

EXTLOGFONT	Describes font attributes

EXTLOGPEN	Defines extended pen characteristics

EXT_BUTTON	Defines a toolbar button for File Manager

FILETIME	Represents time in 100-nanosecond intervals

FIND_NAME_BUFFER	Contains information about a network name

FIND_NAME_HEADER	Contains information about a network name

FINDREPLACE	Data for find- and replace-text dialog boxes

FIXED	Integral and fractional parts of a number

FMS_GETDRIVEINFO	Contains drive data for File Manager

FMS_GETFILESEL	Contains file data for File Manager

FMS_HELPSTRING	??????

FMS_LOAD	Contains custom menu data for File Manager

FMS_TOOLBARLOAD	Contains custom button information

FOCUS_EVENT_RECORD	Used internally by the console

FORM_INFO_1	Printer form information

FORMAT_PARAMETERS	Provides information for formatting disk tracks

GENERIC_MAPPING	Map standard to generic security

GLYPHMETRICS	Describes placement of glyph in character cell

HANDLETABLE	Contains array of handles to GDI objects

HELPWININFO	Contains journaling hook message information

HSZPAIR	Contains a DDE service-name and topic-name

ICONINFO	contains cursor or icon information

INPUT_RECORD	Contains console input information

JOB_INFO_1	Specifies print-job information

JOB_INFO_2	Full print job information

JOYCAPS	Contains joystick capability information

JOYINFO	Contains joystick position and button state

KERNINGPAIR	Defines a kerning pair

KEY_EVENT_RECORD	Contains key-press information

LANA_ENUM	Contains numbers of LAN adapters

LARGE_INTEGER	64-bit signed integer

LDT_ENTRY	Describes a descriptor table entry

LIST_ENTRY	Double-linked list structure

LOAD_DLL_DEBUG_INFO	Contains loaded DLL information

LOGBRUSH	Defines characteristics of a logical brush

LOGFONT	Specifies a logical font

LOGPALETTE	Defines a logical color palette

LOGPEN	Defines characteristics of a logical pen

LUID	Locally Unique Identifier

LUID_AND_ATTRIBUTES	Represents an LUID and its attributes

MAT2	Contains values for a transformation matrix

MCI_ANIM_OPEN_PARMS	Contains information for MCI_OPEN

MCI_ANIM_PLAY_PARMS	Contains parameters for MCI_PLAY

MCI_ANIM_RECT_PARMS	Contains parameters for MCI_PUT and MCI_WHERE

MCI_ANIM_STEP_PARMS	Contains parameters for MCI_STEP

MCI_ANIM_UPDATE_PARMS	Contains parameters for MCI_UPDATE

MCI_ANIM_WINDOW_PARMS	Contains parameters for MCI_WINDOW

MCI_BREAK_PARMS	Contains parameters for MCI_BREAK

MCI_GENERIC_PARMS	Contains information for generic MCI messages

MCI_GETDEVCAPS_PARMS	Contains parameters for MCI_GETDEVCAPS

MCI_INFO_PARMS	Contains parameters for MCI_INFO

MCI_LOAD_PARMS	Contains parameters for MCI_LOAD

MCI_OPEN_PARMS	Contains parameters for MCI_OPEN

MCI_OVLY_LOAD_PARMS	Contains parameters for video overlay MCI_LOAD

MCI_OVLY_OPEN_PARMS	Contains parameters for video overlay MCI_OPEN

MCI_OVLY_RECT_PARMS	Contains parameters for video overlay MCI_PUT

MCI_OVLY_SAVE_PARMS	Contains parameters for video overlay MCI_SAVE

MCI_OVLY_WINDOW_PARMS	Parameters for video overlay MCI_WINDOW

MCI_PLAY_PARMS	Contains parameters for MCI_PLAY

MCI_RECORD_PARMS	Contains parameters for MCI_RECORD

MCI_SAVE_PARMS	Contains parameters for MCI_SAVE

MCI_SEEK_PARMS	Contains parameters for MCI_SEEK

MCI_SEQ_SET_PARMS	Contains parameters for MIDI sequencer MCI_SET

MCI_SET_PARMS	Contains parameters for MCI_SET

MCI_SOUND_PARMS	Contains parameters for MCI_SOUND

MCI_STATUS_PARMS	Contains parameters for MCI_STATUS

MCI_SYSINFO_PARMS	Contains parameters for MCI_SYSINFO

MCI_VD_ESCAPE_PARMS	Contains parameters for videodisc MCI_ESCAPE

MCI_VD_PLAY_PARMS	Contains parameters for videodisc MCI_PLAY

MCI_VD_STEP_PARMS	Contains parameters for videodisc MCI_STEP

MCI_WAVE_DELETE_PARMS	Contains parameters for waveform MCI_DELETE

MCI_WAVE_OPEN_PARMS	Contains parameters for waveform MCI_OPEN

MCI_WAVE_SET_PARMS	Contains parameters for waveform MCI_SET

MDICREATESTRUCT	Initialization data for MDI child window

MEASUREITEMSTRUCT	Contains dimensions of owner-drawn control

MEDIA_TYPE	Defines a set of device media types

MEMORY_BASIC_INFORMATION	Contains virtual memory information

MEMORYSTATUS	Contains memory availability information

MENU_EVENT_RECORD	Used internally by the console

MENUITEMTEMPLATE	Defines a menu item

MENUITEMTEMPLATEHEADER	Contains header data for a menu template

METAFILEPICT	Defines metafile picture format for clipboard

METAHEADER	Contains information about a metafile

METARECORD	Contains a metafile record

MIDIHDR	Defines MIDI system-exclusive data buffer

MIDIINCAPS	Describes MIDI input device capabilities

MIDIOUTCAPS	Describes MIDI output device capabilities

MINMAXINFO	Contains window size and tracking data

MMCKINFO	Contains RIFF chunk information

MMIOINFO	Contains open file state information

MMTIME	General-purpose timing structure

MONCBSTRUCT	Contains data about current DDE transaction

MONCONVSTRUCT	Contains data about a DDE conversation

MONERRSTRUCT	Contains data about the current DDE error

MONHSZSTRUCT	Contains data about a DDE string handle

MONITOR_INFO_1MONITOR_INFO_1 #MONITOR_INFO_2MONITOR_INFO_2#  Identifies an installed monitor	Identifies an installed monitor

MONLINKSTRUCT	Contains data about an advise loop

MONMSGSTRUCT	Contains data about a DDE message

MOUSE_EVENT_RECORD	Contains mouse event information

MOUSEHOOKSTRUCT	Contains data about a mouse event

MSG	Contains message information

MULTIKEYHELP	Contains key-word data for Windows Help

NAME_BUFFER	Contains local network name information

NCB	Network control block

NCCALCSIZE_PARAMS	Contains data for calculating client area

NDDESHAREINFO	Describes network DDE share attributes

NETRESOURCE	Information about network resource

NEWCPLINFO	Contains Control Panel app resource data

NEWTEXTMETRIC	Contains information about a physical font

OFSTRUCT	Contains data about an open file

OPENFILENAME	Contains data for the open-filename dialog box

OUTLINETEXTMETRIC	Contains TrueType font metrics

OUTPUT_DEBUG_STRING_INFO	Contains debug string information

OVERLAPPED	Contains overlapped I/O offset and event

PAINTSTRUCT	Contains painting data for an client area

PALETTEENTRY	Specifies entry in logical color palette

PANOSE	Contains Panose numbers for a TrueType font

PARTITION_INFORMATION	Provides disk partition information

PCMWAVEFORMAT	Describes PCM waveform data format

PERF_COUNTER_BLOCK	Length of counter data

PERF_COUNTER_DEFINITION	Performance ounter information

PERF_DATA_BLOCK	Performance information

PERF_INSTANCE_DEFINITION	Instance information

PERF_OBJECT_TYPE	Object-specific performance information

POINT	Contains the coordinates of a point

POINTFX	Describes a point in a character outline

POINTL	Point coordinates as LONG values

POINTS	Defines x and y coordinates

POLYTEXT	Identifies strings for PolyTextOut

PORT_INFO_1	List of supported printer ports

PREVENT_MEDIA_REMOVAL	Provides removeable media locking data

PRINTDLG	Contains data for the print-text dialog box

PRINTER_DEFAULTS	Specifies the printer defaults

PRINTER_INFO_1	General printer information

PRINTER_INFO_2	Detailed printer information

PRINTER_INFO_3	Printer security information

PRINTPROCESSOR_INFO_1	Installed print processor names

PRIVILEGE_SET	Specifies a set of privileges

PROCESS_INFORMATION	Contains new process handles and IDs

PROVIDOR_INFO_1	Identifies a print provider

QUERY_SERVICE_CONFIG	Service configuration information

QUERY_SERVICE_LOCK_STATUS	Service lock status and owner name

RASCONN	Contains remote access connection information

RASCONNSTATE	Enumeration type describing states of RAS connection

RASCONNSTATUS	Describes current status of a RAS connection

RASDIALPARAMS	Contains remote access connection dial information

RASENTRYNAME	Contains entry name from a remote access phone book

RASTERIZER_STATUS	Contains data about TrueType installation

REASSIGN_BLOCKS	Provides disk block reassignment data

RECT	Contains the coordinates of a rectangle

RECTL	Contains the coordinates of a rectangle

RGBQUAD	Describes colors for a DIB

RGBTRIPLE	Describes colors for a PM-compatible DIB

RGNDATA	Region rectangle data

RGNDATAHEADER	Region rectangle data description

RIP_INFO	Contains RIP error information

SECURITY_ATTRIBUTES	Contains object security attributes

SECURITY_DESCRIPTOR	Opaque security information

SECURITY_DESCRIPTOR_CONTROL	Qualifies a security descriptor

SECURITY_IMPERSONATION_LEVEL	Contains impersonation level enumerators

SECURITY_INFORMATION	Specifies security information type

SECURITY_QUALITY_OF_SERVICE	Used for server/client impersonation

SERVICE_STATUS	Specifies service status

SERVICE_TABLE_ENTRY	Service start information

SESSION_BUFFER	Contains data for a local network session

SESSION_HEADER	Contains information about a network session

SET_PARTITION_INFORMATION	Information for setting a disk partition's type.

SID	Security identifier

SID_AND_ATTRIBUTES	SID and associated attributes

SID_IDENTIFIER_AUTHORITY	SID top-level authority

SID_NAME_USE	Enumerates type of SID

SINGLE_LIST_ENTRY	Single-linked list structure

SIZE	Contains returned extents

SMALL_RECT	Rectangle coordinates as SHORT values

STARTUPINFO	Process startup information

WIN32_STREAM_ID	Used by backup read/write functions

String	Contains a version string.

StringFileInfo	Language and codepage dependent version info

StringTable	Contains format info and version strings

SYSTEM_ALARM_ACE	Specifies accesses that cause alarms

SYSTEM_AUDIT_ACE	Specifies accesses that cause audits

SYSTEM_INFO	Computer system-specific information

SYSTEMTIME	Contains time in individual values

TAPE_CREATE_PARTITION	Tape partition information

TAPE_ERASE	Tape erasure information

TAPE_GET_DRIVE_PARAMETERS	Tape drive information

TAPE_GET_MEDIA_PARAMETERS	Tape information

TAPE_GET_POSITION	Tape position information

TAPE_SET_POSITION	Tape position information

TAPE_PREPARE	Tape preparation information

TAPE_SET_DRIVE_PARAMETERS	Tape drive information

TAPE_SET_MEDIA_PARAMETERS	Tape information

TAPE_WRITE_MARKS	Tapemark information

TEXTMETRIC	Contains information about a physical font

TIME_ZONE_INFORMATION	Contains time-zone settings

TIMECAPS	Contains timer resolution information

TOKEN_CONTROL	Token control information

TOKEN_DEFAULT_DACL	Token default access control list

TOKEN_GROUPS	Group SIDs and attributes

TOKEN_INFORMATION_CLASS	Token information enumerated type

TOKEN_OWNER	Token owner SID

TOKEN_PRIMARY_GROUP	Token primary group SID

TOKEN_PRIVILEGES	Token LUID and attributes

TOKEN_SOURCE	Identifies token source

TOKEN_STATISTICS	Token information

TOKEN_TYPE	Token primary or impersonated

TOKEN_USER	Token user SID and attributes

TTPOLYCURVE	Describes a curve in a character outline

TTPOLYGONHEADER	Specifies starting point for character outline

ULARGE_INTEGER	64-bit unsigned integer

UNLOAD_DLL_DEBUG_INFO	Unloaded DLL information

Var	Language and codepage independent version info

VarFileInfo	Language and codepage independent version info

VERIFY_INFORMATION	Information for logically formatting a disk extent

VS_FIXEDFILEINFO	Language and codepage independent version info

VS_VERSION_INFO	Contains version information about a file.

WAVEFORMAT	Describes waveform data format

WAVEHDR	defines waveform data header

WAVEINCAPS	Describes waveform input device capabilities

WAVEOUTCAPS	Describes waveform output device capabilities

WIN32_FIND_DATA	File information

WINDOW_BUFFER_SIZE_RECORD	Console screen buffer size

WINDOWPLACEMENT	Contains window-placement information

WINDOWPOS	Contains window size and position data

WNDCLASS	Defines a window class

XFORM	Specifies a transformation matrix


XTYP_ADVDATA transaction
XTYP_ADVDATA (Win32)

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.

Parameter	Description

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.

Returns

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.

Comments

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, DdePostAdvise, XTYP_ADVREQ, XTYP_ADVSTART, XTYP_ADVSTOP


XTYP_ADVREQ transaction
XTYP_ADVREQ (Win32)

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.

Parameter	Description

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.

Returns

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.

Comments

A server cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

DdeCreateDataHandle, DdeInitialize, DdePostAdvise, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_ADVDATA


XTYP_ADVSTOP transaction
XTYP_ADVSTOP (Win32)

XTYP_ADVSTOP

A dynamic data exchange (DDE) server callback function receives the XTYP_ADVSTOP transaction when a client specifies XTYP_ADVSTOP as the uType parameter of the DdeClientTransaction function. A client uses this transaction to end an advise loop with a server.

Parameter	Description

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.

Comments

This transaction is filtered if the server application specified the CBF_FAIL_ADVISES flag in the DdeInitialize function.

See Also

DdeClientTransaction, DdeInitialize, DdePostAdvise, XTYP_ADVREQ, XTYP_ADVSTART


XTYP_ADVSTART transaction
XTYP_ADVSTART (Win32)

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.

Parameter	Description

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.

Returns

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.

Comments

If a client requests an advise loop on a topic, item, and format name set 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_ADVREQ, XTYP_ADVSTOP


XTYP_CONNECT transaction
XTYP_CONNECT (Win32)

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.

Parameter	Description

uFmt	Not used.

hconv	Not used.

hsz1	Identifies the topic name.

hsz2	Identifies the service name.

hdata	Not used.

dwData1	Points to a CONVCONTEXT data 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 the same instance. If the parameter is 0, the client is a different instance.

Returns

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

Comments

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

DdeConnect, DdeInitialize, CONVCONTEXT, XTYP_CONNECT_CONFIRM


XTYP_CONNECT_CONFIRM transaction
XTYP_CONNECT_CONFIRM (Win32)

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.

Parameter	Description

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.

Comments

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_CONNECT, XTYP_WILDCONNECT


XTYP_DISCONNECT transaction
XTYP_DISCONNECT (Win32)

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.

Parameter	Description

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 the parameter is 1, the partners are the same instance. If the parameter is 0, the partners are different instances.

Comments

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, DdeQueryConvInfo


XTYP_ERROR transaction
XTYP_ERROR (Win32)

XTYP_ERROR

A dynamic data exchange (DDE) callback function receives the XTYP_ERROR transaction when a critical error occurs.

Parameter	Description

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.

Comments

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 transaction
XTYP_EXECUTE (Win32)

XTYP_EXECUTE

A dynamic data exchange (DDE) server callback function receives the XTYP_EXECUTE transaction when a client specifies XTYP_EXECUTE as the uType parameter of the DdeClientTransaction function. A client uses this transaction to send a command string to the server.

Parameter	Description

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.

Returns

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.

Comments

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 CBR_BLOCK. 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, DdeInitialize


XTYP_MONITOR transaction
XTYP_MONITOR (Win32)

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.

Parameter	Description

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.

Returns

The callback function should return 0 if it processes this transaction.

See Also

DdeAccessData, DdeInitialize, MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


XTYP_POKE transaction
XTYP_POKE (Win32)

XTYP_POKE

A dynamic data exchange (DDE) server callback function receives the XTYP_POKE transaction when a client specifies XTYP_POKE as the uType parameter of the DdeClientTransaction function. A client uses this transaction to send unsolicited data to the server.

Parameter	Description

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.

Returns

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.

Comments

This transaction is filtered if the server application specified the CBF_FAIL_POKES flag in the DdeInitialize function.

See Also

DdeClientTransaction, DdeInitialize


XTYP_REGISTER transaction
XTYP_REGISTER (Win32)

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.

Parameter	Description

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.

Comments

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_UNREGISTER


XTYP_REQUEST transaction
XTYP_REQUEST (Win32)

XTYP_REQUEST

A dynamic data exchange (DDE) server callback function receives the XTYP_REQUEST transaction when a client specifies XTYP_REQUEST as the uType parameter of the DdeClientTransaction function. A client uses this transaction to request data from a server.

Parameter	Description

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.

Returns

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 acknowledgment flag.

Comments

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 CBR_BLOCK 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 transaction
XTYP_UNREGISTER (Win32)

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.

Parameter	Description

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.

Comments

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_REGISTER


XTYP_WILDCONNECT transaction
XTYP_WILDCONNECT (Win32)

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 DdeWildConnect 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 and topic name.

Parameter	Description

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

Returns

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.

Comments

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

DdeConnect, DdeInitialize, CONVCONTEXT, XTYP_CONNECT_CONFIRM


XTYP_XACT_COMPLETE transaction
XTYP_XACT_COMPLETE (Win32)

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.

Parameter	Description

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 will be TRUE. This parameter will be NULL if the transaction was unsuccessful.

dwData1	Contains the transaction identifier of the completed transaction.

dwData2	Contains any applicable DDE_ status flags in the low word. This 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.

Comments

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


DDE Transactions (all)

XTYP_ADVDATA	Passes advise data to a client

XTYP_ADVREQ	Prompts a server to send advise data to a client

XTYP_ADVSTOP	Ends an advise loop

XTYP_ADVSTART	Requests an advise loop

XTYP_CONNECT	Requests a DDE conversation

XTYP_CONNECT_CONFIRM	Confirms a DDE conversation

XTYP_DISCONNECT	Terminates a DDE conversation

XTYP_ERROR	Notifies a DDEML application of a critical error

XTYP_EXECUTE	Executes a server command

XTYP_MONITOR	Informs a DDE monitor application of a DDE event

XTYP_POKE	Sends unsolicited data to a server

XTYP_REGISTER	Registers a service name

XTYP_REQUEST	Requests data from a server

XTYP_UNREGISTER	Unregisters a service name

XTYP_WILDCONNECT	Requests multiple DDE conversation

XTYP_XACT_COMPLETE	Confirms completion of asynchronous transaction


Data Types

Data types are keywords that 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. Most 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

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)

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

FOURCC	A four-character code used in multimedia input/output operations

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

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

HINSTANCE	Handle of an instance

HKEY	Handle of a registry key

HLOCAL	Handle of a local memory block

HMENU	Handle of a menu

HMETAFILE	Handle of a metafile

HMIDIIN	Handle of a Musical Instrument Digital Interface (MIDI) input file

HMIDIOUT	Handle of a MIDI output file

HMMIO	Handle of a file

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

HWAVEIN	Handle of a waveform input file

HWAVEOUT	Handle of a waveform output file

HWINSTA	Handle of a workstation

HWND	Handle of a window

INT	Signed integer

LANGID	Language identifier

LCID	Locale identifier

LCTYPE	Locale type

LINEDDAPROC	Pointer to a callback function that processes line coordinates

LONG	32-bit signed value

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

LPHWAVEIN	Pointer to a handle to a waveform input file

LPHWAVEOUT	Pointer to a handle to a waveform output file

LPINT	Pointer to a signed integer

LPLONG	Pointer to a signed long (32 bits)

LPMMIOPROC	Pointer to an MMIOPROC application-defined multimedia input/output callback procedure. See MMIOProc for information on procedures of this type.

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

MCIDEVICEID	Media control interface (MCI) device identifier

MFENUMPROC	Pointer to an application-defined callback function that enumerates metafile records

MMIOPROC	An application-defined multimedia input/output callback procedure. See MMIOProc for information on procedures of this type.

MMRESULT	Result of multimedia message processing

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

PLONG	Pointer to a signed long (32 bits)

PLUID	Pointer to a locally unique identifier (LUID)

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

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

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


ATOM
ATOM  WORD    windef.h

Atom (a reference to a character string in an atom table)


FN_ATOM
ATOM  WORD    windef.h


BOOL
BOOL  int    windef.h

Boolean variable (should be TRUE or FALSE)


FN_BOOL
BOOL  int    windef.h


BOOLEAN
BOOLEAN  CCHAR    winnt.h

Boolean variable (should be TRUE or FALSE)


FN_BOOLEAN
BOOLEAN  CCHAR    winnt.h


BYTE
BYTE  unsigned char    windef.h

Byte (8 bits)


FN_BYTE
BYTE  unsigned char    windef.h


CCHAR
CCHAR  char    winnt.h

Windows character


FN_CCHAR
CCHAR  char    winnt.h


CHAR
CHAR  char    winnt.h

Windows character


FN_CHAR
CHAR  char    winnt.h


COLORREF
COLORREF  DWORD    windef.h

Red, green, blue (RGB) color value (32 bits)


FN_COLORREF
COLORREF  DWORD    windef.h


CONST
CONST  const    windef.h

Variable whose value is to remain constant during execution


FN_CONST
CONST  const    windef.h


CRITICAL_SECTION
CRITICAL_SECTION  RTL_CRITICAL_SECTION    winbase.h

Critical-section object


FN_CRITICAL_SECTION
CRITICAL_SECTION  RTL_CRITICAL_SECTION    winbase.h


CTRYID
CTRYID  WORD    winnls.h

Country identifier


FN_CTRYID
CTRYID  WORD    winnls.h


DLGPROC
DLGPROC  STRICT: typedef BOOL (CALLBACK* DLGPROC)(HWND, UINT, WPARAM, LPARAM); else: FARPROC    winuser.h

Pointer to an application-defined dialog box callback procedure.


FN_DLGPROC
DLGPROC  STRICT: typedef BOOL (CALLBACK* DLGPROC)(HWND, UINT, WPARAM, LPARAM); else: FARPROC    winuser.h


DWORD
DWORD  unsigned long    windef.h

Doubleword (32 bits)


FN_DWORD
DWORD  unsigned long    windef.h


EDITWORDBREAKPROC
EDITWORDBREAKPROC  STRICT: typedef int (CALLBACK* EDITWORDBREAKPROC)(LPTSTR lpch, int ichCurrent, int cch, int code); ELSE: typedef FARPROC EDITWORDBREAKPROC  winuser.h

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.


FN_EDITWORDBREAKPROC
EDITWORDBREAKPROC  STRICT: typedef int (CALLBACK* EDITWORDBREAKPROC)(LPTSTR lpch, int ichCurrent, int cch, int code); ELSE: typedef FARPROC EDITWORDBREAKPROC  winuser.h


ENHMFENUMPROC
ENHMFENUMPROC  typedef int (CALLBACK* ENHMFENUMPROC)(HDC, HANDLETABLE FAR*, ENHMETARECORD FAR*, int, LPARAM);  wingdi.h

Pointer to an application-defined callback function that enumerates enhanced-metafile records


FN_ENHMFENUMPROC
ENHMFENUMPROC  typedef int (CALLBACK* ENHMFENUMPROC)(HDC, HANDLETABLE FAR*, ENHMETARECORD FAR*, int, LPARAM);  wingdi.h


ENUMRESLANGPROC
ENUMRESLANGPROC  STRICT: typedef BOOL (CALLBACK* ENUMRESLANGPROC)(HINSTANCE, LPCTSTR, LPCTSTR, WORD, LONG); else: FARPROC  winbase.h

Pointer to an application-defined callback function that enumerates resource languages


FN_ENUMRESLANGPROC
ENUMRESLANGPROC  STRICT: typedef BOOL (CALLBACK* ENUMRESLANGPROC)(HINSTANCE, LPCTSTR, LPCTSTR, WORD, LONG); else: FARPROC  winbase.h


ENUMRESNAMEPROC
ENUMRESNAMEPROC  STICT: typedef BOOL (CALLBACK* ENUMRESNAMEPROC)(HINSTANCE, LPCTSTR, LPTSTR, LONG); else: FARPROC  winbase.h

Pointer to an application-defined callback function that enumerates resource names


FN_ENUMRESNAMEPROC
ENUMRESNAMEPROC  STICT: typedef BOOL (CALLBACK* ENUMRESNAMEPROC)(HINSTANCE, LPCTSTR, LPTSTR, LONG); else: FARPROC  winbase.h


ENUMRESTYPEPROC
ENUMRESTYPEPROC  STRICT: typedef BOOL (CALLBACK* ENUMRESTYPEPROC)(HINSTANCE, LPTSTR, LONG); else: FARPROC  winbase.h

Pointer to an application-defined callback function that enumerates resource types


FN_ENUMRESTYPEPROC
ENUMRESTYPEPROC  STRICT: typedef BOOL (CALLBACK* ENUMRESTYPEPROC)(HINSTANCE, LPTSTR, LONG); else: FARPROC  winbase.h


FARPROC
FARPROC  typedef int (FAR WINAPI *FARPROC)();  windef.h

Pointer to a callback function


FN_FARPROC
FARPROC  typedef int (FAR WINAPI *FARPROC)();  windef.h


FLOAT
FLOAT  float    windef.h

Floating-point variable


FN_FLOAT
FLOAT  float    windef.h


FONTENUMPROC
FONTENUMPROC  STRICT: typedef int (CALLBACK* FONTENUMPROC)(CONST LOGFONT * , CONST TEXTMETRIC *, DWORD, LPARAM); else: FARPROC    wingdi.h

Pointer to an application-defined callback function that enumerates fonts


FN_FONTENUMPROC
FONTENUMPROC  STRICT: typedef int (CALLBACK* FONTENUMPROC)(CONST LOGFONT * , CONST TEXTMETRIC *, DWORD, LPARAM); else: FARPROC    wingdi.h


FOURCC

A four-character code used in multimedia input/output operations


GOBJENUMPROC
GOBJENUMPROC  STRICT: typedef int (CALLBACK* GOBJENUMPROC)(LPVOID, LPARAM); else: FARPROC    wingdi.h

Pointer to an application-defined callback function that enumerates graphics device interface (GDI) objects


FN_GOBJENUMPROC
GOBJENUMPROC  STRICT: typedef int (CALLBACK* GOBJENUMPROC)(LPVOID, LPARAM); else: FARPROC    wingdi.h


GRAYSTRINGPROC
GRAYSTRINGPROC  STRICT: typedef BOOL (CALLBACK* GRAYSTRINGPROC)(HDC, LPARAM, int); else: FARPROC    winuser.h

Pointer to an application-defined callback function that draws gray text


FN_GRAYSTRINGPROC
GRAYSTRINGPROC  STRICT: typedef BOOL (CALLBACK* GRAYSTRINGPROC)(HDC, LPARAM, int); else: FARPROC    winuser.h


HACCEL
HACCEL  HANDLE    windef.h

Handle of an accelerator table


FN_HACCEL
HACCEL  HANDLE    windef.h


HANDLE
HANDLE  const void *   winnt.h

Handle of an object


FN_HANDLE
HANDLE  const void *   winnt.h


HBITMAP
HBITMAP  HANDLE  windef.h

Handle of a bitmap


FN_HBITMAP
HBITMAP  HANDLE  windef.h


HBRUSH
HBRUSH  HANDLE  windef.h

Handle of a brush


FN_HBRUSH
HBRUSH  HANDLE  windef.h


HCONV
HCONV  DWORD    ddeml.h

Handle of a dynamic data exchange (DDE) conversation


FN_HCONV
HCONV  DWORD    ddeml.h


HCONVLIST
HCONVLIST  DWORD    ddeml.h

Handle of a DDE conversation list


FN_HCONVLIST
HCONVLIST  DWORD    ddeml.h


HCURSOR
HCURSOR  HICON    windef.h

Handle of a cursor


FN_HCURSOR
HCURSOR  HICON    windef.h


HDC
HDC  HANDLE  windef.h

Handle of a device context (DC)


FN_HDC
HDC  HANDLE  windef.h


HDDEDATA
HDDEDATA  DWORD    ddeml.h

Handle of DDE data


FN_HDDEDATA
HDDEDATA  DWORD    ddeml.h


HDWP
HDWP  HANDLE    winuser.h

Handle of a deferred window position structure


FN_HDWP
HDWP  HANDLE    winuser.h


HENHMETAFILE
HENHMETAFILE  HANDLE  windef.h

Handle of an enhanced metafile


FN_HENHMETAFILE
HENHMETAFILE  HANDLE  windef.h


HFILE
HFILE  int    windef.h

Handle of a file


FN_HFILE
HFILE  int    windef.h


HFONT
HFONT  HANDLE  windef.h

Handle of a font


FN_HFONT
HFONT  HANDLE  windef.h


HGDIOBJ
HGDIOBJ  const void NEAR *   windef.h

Handle of a GDI object


FN_HGDIOBJ
HGDIOBJ  const void NEAR *   windef.h


HGLOBAL
HGLOBAL  HANDLE    windef.h

Handle of a global memory block


FN_HGLOBAL
HGLOBAL  HANDLE    windef.h


HHOOK
HHOOK  HANDLE  windef.h

Handle of a hook


FN_HHOOK
HHOOK  HANDLE  windef.h


HICON
HICON  HANDLE  windef.h

Handle of an icon


FN_HICON
HICON  HANDLE  windef.h


HINSTANCE
HINSTANCE  HANDLE    ole.h

Handle of an instance


FN_HINSTANCE
HINSTANCE  HANDLE    ole.h


HKEY
HKEY  HANDLE    winreg.h

Handle of a registry key


FN_HKEY
HKEY  HANDLE    winreg.h


HLOCAL
HLOCAL  HANDLE    windef.h

Handle of a local memory block


FN_HLOCAL
HLOCAL  HANDLE    windef.h


HMENU
HMENU  HANDLE  windef.h

Handle of a menu


FN_HMENU
HMENU  HANDLE  windef.h


HMETAFILE
HMETAFILE  HANDLE  windef.h

Handle of a metafile


FN_HMETAFILE
HMETAFILE  HANDLE  windef.h


HMIDIIN
HMIDIIN  HMIDI    mmsystem.h

Handle of a Musical Instrument Digital Interface (MIDI) input file


FN_HMIDIIN
HMIDIIN  HMIDI    mmsystem.h


HMIDIOUT
HMIDIOUT  HMIDI    mmsystem.h

Handle of a MIDI output file


FN_HMIDIOUT
HMIDIOUT  HMIDI    mmsystem.h


HMMIO
HMMIO  HANDLE    mmsystem.h

Handle of a file


FN_HMMIO
HMMIO  HANDLE    mmsystem.h


HOOKPROC
HOOKPROC  STRICT: typedef LRESULT (CALLBACK* HOOKPROC)(int code, WPARAM wParam, LPARAM lParam); else: FARPROC    winuser.h

Pointer to an application-defined hook function


FN_HOOKPROC
HOOKPROC  STRICT: typedef LRESULT (CALLBACK* HOOKPROC)(int code, WPARAM wParam, LPARAM lParam); else: FARPROC    winuser.h


HPALETTE
HPALETTE  HANDLE  windef.h

Handle of a palette


FN_HPALETTE
HPALETTE  HANDLE  windef.h


HPEN
HPEN  HANDLE  windef.h

Handle of a pen


FN_HPEN
HPEN  HANDLE  windef.h


HRGN
HRGN  HANDLE  windef.h

Handle of a region


FN_HRGN
HRGN  HANDLE  windef.h


HRSRC
HRSRC  HANDLE  windef.h

Handle of a resource


FN_HRSRC
HRSRC  HANDLE  windef.h


HSZ
HSZ  DWORD    ddeml.h

Handle of a DDE string


FN_HSZ
HSZ  DWORD    ddeml.h


HWAVEIN
HWAVEIN  HWAVE    mmsystem.h

Handle of a waveform input file


FN_HWAVEIN
HWAVEIN  HWAVE    mmsystem.h


HWAVEOUT
HWAVEOUT  HWAVE    mmsystem.h

Handle of a waveform output file


FN_HWAVEOUT
HWAVEOUT  HWAVE    mmsystem.h


HWINSTA
HWINSTA  HANDLE  windef.h

Handle of a workstation


FN_HWINSTA
HWINSTA  HANDLE  windef.h


HWND
HWND  HANDLE  windef.h

Handle of a window


FN_HWND
HWND  HANDLE  windef.h


INT
INT  int    windef.h

Signed integer


FN_INT
INT  int    windef.h


LANGID
LANGID  WORD    winnls.h

Language identifier


FN_LANGID
LANGID  WORD    winnls.h


LCID
LCID  DWORD    winnls.h

Locale identifier


FN_LCID
LCID  DWORD    winnls.h


LCTYPE
LCTYPE  int    winnls.h

Locale type


FN_LCTYPE
LCTYPE  int    winnls.h


LINEDDAPROC
LINEDDAPROC  STRICT: typedef VOID (CALLBACK* LINEDDAPROC)(int, int, LPARAM); else: FARPROC  wingdi.h

Pointer to a callback function that processes line coordinates


FN_LINEDDAPROC
LINEDDAPROC  STRICT: typedef VOID (CALLBACK* LINEDDAPROC)(int, int, LPARAM); else: FARPROC  wingdi.h


LONG
LONG  signed long    windef.h

32-bit signed value


FN_LONG
LONG  signed long    windef.h


LP
LP  LPWSTR    winnt.h

Pointer to a null-terminated Unicode™ string


FN_LP
LP  LPWSTR    winnt.h


LPARAM
LPARAM  LONG    windef.h

32-bit message parameter


FN_LPARAM
LPARAM  LONG    windef.h


LPBOOL
LPBOOL  BOOL far *   windef.h

Pointer to a Boolean variable


FN_LPBOOL
LPBOOL  BOOL far *   windef.h


LPBYTE
LPBYTE  BYTE far *   windef.h

Pointer to a byte


FN_LPBYTE
LPBYTE  BYTE far *   windef.h


LPCCH
LPCCH  CONST CHAR *   winnt.h

Pointer to a constant Windows character


FN_LPCCH
LPCCH  CONST CHAR *   winnt.h


LPCCHOOKPROC
LPCCHOOKPROC  typedef UINT (APIENTRY *LPCCHOOKPROC) (HWND, UINT, WPARAM, LPARAM);    commdlg.h

Pointer to an application-defined hook function


FN_LPCCHOOKPROC
LPCCHOOKPROC  typedef UINT (APIENTRY *LPCCHOOKPROC) (HWND, UINT, WPARAM, LPARAM);    commdlg.h


LPCFHOOKPROC
LPCFHOOKPROC  typedef UINT (APIENTRY *LPCFHOOKPROC) (HWND, UINT, WPARAM, LPARAM);  commdlg.h

Pointer to an application-defined hook function


FN_LPCFHOOKPROC
LPCFHOOKPROC  typedef UINT (APIENTRY *LPCFHOOKPROC) (HWND, UINT, WPARAM, LPARAM);  commdlg.h


LPCH
LPCH  CHAR *   winnt.h

Pointer to a Windows character


FN_LPCH
LPCH  CHAR *   winnt.h


LPCOLORREF
LPCOLORREF  DWORD *   windef.h

Pointer to a COLORREF value


FN_LPCOLORREF
LPCOLORREF  DWORD *   windef.h


LPCRITICAL_SECTION
LPCRITICAL_SECTION  PRTL_CRITICAL_SECTION    winbase.h

Pointer to a critical-section object


FN_LPCRITICAL_SECTION
LPCRITICAL_SECTION  PRTL_CRITICAL_SECTION    winbase.h


LPCSTR
LPCSTR    ole.h: LPSTR  winnt.h: CONST CHAR *

Pointer to a constant null-terminated Windows character string


FN_LPCSTR
LPCSTR    ole.h: LPSTR  winnt.h: CONST CHAR *


LPCTSTR
LPCTSTR  Windows: LPCSTR Unicode: LPCWSTR    winnt.h

Pointer to a constant null-terminated Unicode or Windows character string


FN_LPCTSTR
LPCTSTR  Windows: LPCSTR Unicode: LPCWSTR    winnt.h


LPCWCH
LPCWCH  CONST WCHAR *   winnt.h

Pointer to a constant null-terminated Unicode character


FN_LPCWCH
LPCWCH  CONST WCHAR *   winnt.h


LPCWSTR
LPCWSTR  CONST WCHAR *   winnt.h

Pointer to a constant null-terminated Unicode character string


FN_LPCWSTR
LPCWSTR  CONST WCHAR *   winnt.h


LPDWORD
LPDWORD  DWORD far *   windef.h

Pointer to an unsigned doubleword (32 bits)


FN_LPDWORD
LPDWORD  DWORD far *   windef.h


LPFRHOOKPROC
LPFRHOOKPROC  typedef UINT (APIENTRY *LPFRHOOKPROC) (HWND, UINT, WPARAM, LPARAM);  commdlg.h

Pointer to an application-defined hook function


FN_LPFRHOOKPROC
LPFRHOOKPROC  typedef UINT (APIENTRY *LPFRHOOKPROC) (HWND, UINT, WPARAM, LPARAM);  commdlg.h


LPHANDLE
LPHANDLE  HANDLE FAR *   windef.h

Pointer to a handle


FN_LPHANDLE
LPHANDLE  HANDLE FAR *   windef.h


LPHANDLER_FUNCTION
LPHANDLER_FUNCTION  typedef VOID (*LPHANDLER_FUNCTION)(DWORD);  winsvc.h

Pointer to a handler function


FN_LPHANDLER_FUNCTION
LPHANDLER_FUNCTION  typedef VOID (*LPHANDLER_FUNCTION)(DWORD);  winsvc.h


LPHWAVEIN
LPHWAVEIN  HWAVEIN *   mmsystem.h

Pointer to a handle to a waveform input file


FN_LPHWAVEIN
LPHWAVEIN  HWAVEIN *   mmsystem.h


LPHWAVEOUT
LPHWAVEOUT  HWAVEOUT *   mmsystem.h

Pointer to a handle to a waveform output file


FN_LPHWAVEOUT
LPHWAVEOUT  HWAVEOUT *   mmsystem.h


LPINT
LPINT  int far *   windef.h

Pointer to a signed integer


FN_LPINT
LPINT  int far *   windef.h


LPLONG
LPLONG  long far *   windef.h

Pointer to a signed long (32 bits)


FN_LPLONG
LPLONG  long far *   windef.h


LPMMIOPROC
LPMMIOPROC  typedef MMIOPROC *LPMMIOPROC;

Pointer to an MMIOPROC application-defined multimedia input/output callback procedure. See MMIOProc for information on procedures of this type.


FN_LPMMIOPROC
LPMMIOPROC  typedef MMIOPROC *LPMMIOPROC;


LPOFNHOOKPROC
LPOFNHOOKPROC  typedef UINT (APIENTRY *LPOFNHOOKPROC) (HWND, UINT, WPARAM, LPARAM);  commdlg.h

Pointer to an application-defined hook function


FN_LPOFNHOOKPROC
LPOFNHOOKPROC  typedef UINT (APIENTRY *LPOFNHOOKPROC) (HWND, UINT, WPARAM, LPARAM);  commdlg.h


LPPRINTHOOKPROC
LPPRINTHOOKPROC  typedef UINT (APIENTRY *LPPRINTHOOKPROC) (HWND, UINT, WPARAM, LPARAM);  commdlg.h

Pointer to an application-defined hook function


FN_LPPRINTHOOKPROC
LPPRINTHOOKPROC  typedef UINT (APIENTRY *LPPRINTHOOKPROC) (HWND, UINT, WPARAM, LPARAM);  commdlg.h


LPSETUPHOOKPROC
LPSETUPHOOKPROC  typedef UINT (APIENTRY *LPSETUPHOOKPROC) (HWND, UINT, WPARAM, LPARAM);  commdlg.h

Pointer to an application-defined hook function


FN_LPSETUPHOOKPROC
LPSETUPHOOKPROC  typedef UINT (APIENTRY *LPSETUPHOOKPROC) (HWND, UINT, WPARAM, LPARAM);  commdlg.h


LPSTR
LPSTR  CHAR *   winnt.h

Pointer to a null-terminated Windows character string


FN_LPSTR
LPSTR  CHAR *   winnt.h


LPTCH
LPTCH  Windows: LPSTR Unicode: LPWSTR    winnt.h

Pointer to a Unicode character or a Windows character


FN_LPTCH
LPTCH  Windows: LPSTR Unicode: LPWSTR    winnt.h


LPTSTR
LPTSTR  Windows: LPSTR Unicode: LPWSTR    winnt.h

Pointer to a null-terminated Windows or Unicode character string


FN_LPTSTR
LPTSTR  Windows: LPSTR Unicode: LPWSTR    winnt.h


LRESULT
LRESULT  LONG    windef.h

Signed result of message processing


FN_LRESULT
LRESULT  LONG    windef.h


LPVOID
LPVOID  void far *   windef.h

Pointer to any type


FN_LPVOID
LPVOID  void far *   windef.h


LPWCH
LPWCH  WCHAR *   winnt.h

Pointer to a Unicode character


FN_LPWCH
LPWCH  WCHAR *   winnt.h


LPWORD
LPWORD  WORD far *   windef.h

Pointer to an unsigned word (16 bits)


FN_LPWORD
LPWORD  WORD far *   windef.h


LPWSTR
LPWSTR  WCHAR *   winnt.h

Pointer to a null-terminated Unicode character string


FN_LPWSTR
LPWSTR  WCHAR *   winnt.h


LUID
LUID  LARGE_INTEGER  winnt.h

Locally unique identifier


FN_LUID
LUID  LARGE_INTEGER  winnt.h


MCIDEVICEID
MCIDEVICEID  UINT    mmsystem.h

Media control interface (MCI) device identifier


FN_MCIDEVICEID
MCIDEVICEID  UINT    mmsystem.h


MFENUMPROC
MFENUMPROC  typedef int (CALLBACK* MFENUMPROC)(HDC, HANDLETABLE FAR*, METARECORD FAR*, int, LPARAM);  wingdi.h

Pointer to an application-defined callback function that enumerates metafile records


FN_MFENUMPROC
MFENUMPROC  typedef int (CALLBACK* MFENUMPROC)(HDC, HANDLETABLE FAR*, METARECORD FAR*, int, LPARAM);  wingdi.h


MMIOPROC
MMIOPROC  typedef LRESULT MMIOPROC (LPSTR lpmmioinfo, UINT uMsg, LONG lParam1, LONG lParam2)  mmsystem.h

An application-defined multimedia input/output callback procedure. See MMIOProc for information on procedures of this type.


FN_MMIOPROC
MMIOPROC  typedef LRESULT MMIOPROC (LPSTR lpmmioinfo, UINT uMsg, LONG lParam1, LONG lParam2)  mmsystem.h


MMRESULT
MMRESULT  UINT    mmsystem.h

Result of multimedia message processing


FN_MMRESULT
MMRESULT  UINT    mmsystem.h


NPSTR
NPSTR  CHAR *   winnt.h

Pointer to a null-terminated Windows character string


FN_NPSTR
NPSTR  CHAR *   winnt.h


NWPSTR
NWPSTR  WCHAR *   winnt.h

Pointer to a null-terminated Unicode string


FN_NWPSTR
NWPSTR  WCHAR *   winnt.h


PBOOL
PBOOL  BOOL near *   windef.h

Pointer to a Boolean variable


FN_PBOOL
PBOOL  BOOL near *   windef.h


PBOOLEAN
PBOOLEAN  BOOLEAN *   winnt.h

Pointer to a Boolean variable


FN_PBOOLEAN
PBOOLEAN  BOOLEAN *   winnt.h


PBYTE
PBYTE  BYTE near *   windef.h

Pointer to a byte


FN_PBYTE
PBYTE  BYTE near *   windef.h


PCCH
PCCH  CONST CHAR *   winnt.h

Pointer to a constant Windows character


FN_PCCH
PCCH  CONST CHAR *   winnt.h


PCH
PCH  CHAR *   winnt.h

Pointer to a Windows character


FN_PCH
PCH  CHAR *   winnt.h


PCHAR
PCHAR  CHAR *   winnt.h

Pointer to a Windows character


FN_PCHAR
PCHAR  CHAR *   winnt.h


PCRITICAL_SECTION
PCRITICAL_SECTION  PRTL_CRITICAL_SECTION    winbase.h

Pointer to a critical-section object


FN_PCRITICAL_SECTION
PCRITICAL_SECTION  PRTL_CRITICAL_SECTION    winbase.h


PCSTR
PCSTR  CONST CHAR *   winnt.h

Pointer to a constant null-terminated Windows character string


FN_PCSTR
PCSTR  CONST CHAR *   winnt.h


PCWCH
PCWCH  CONST WCHAR *   winnt.h

Pointer to a constant Unicode character


FN_PCWCH
PCWCH  CONST WCHAR *   winnt.h


PCWSTR
PCWSTR  CONST WCHAR *   winnt.h

Pointer to a constant null-terminated Unicode character string


FN_PCWSTR
PCWSTR  CONST WCHAR *   winnt.h


PDWORD
PDWORD  DWORD near *   windef.h

Pointer to an unsigned doubleword (32 bits)


FN_PDWORD
PDWORD  DWORD near *   windef.h


PFLOAT
PFLOAT  FLOAT *   windef.h

Pointer to a floating-point variable


FN_PFLOAT
PFLOAT  FLOAT *   windef.h


PFNCALLBACK
PFNCALLBACK  FNCALLBACK *   ddeml.h

Pointer to a callback function


FN_PFNCALLBACK
PFNCALLBACK  FNCALLBACK *   ddeml.h


PHANDLE
PHANDLE  HANDLE *   winnt.h

Pointer to a handle


FN_PHANDLE
PHANDLE  HANDLE *   winnt.h


PHANDLER_ROUTINE
PHANDLER_ROUTINE  typedef BOOL (WINAPI *PHANDLER_ROUTINE)(DWORD);

Pointer to a handler routine


FN_PHANDLER_ROUTINE
PHANDLER_ROUTINE  typedef BOOL (WINAPI *PHANDLER_ROUTINE)(DWORD);


PHKEY
PHKEY  HANDLE *   winreg.h

Pointer to a registry key


FN_PHKEY
PHKEY  HANDLE *   winreg.h


PINT
PINT  int near *   windef.h

Pointer to a signed integer


FN_PINT
PINT  int near *   windef.h


PLONG
PLONG  LONG *   winnt.h

Pointer to a signed long (32 bits)


FN_PLONG
PLONG  LONG *   winnt.h


PLUID
PLUID  LUID *   winnt.h

Pointer to a locally unique identifier (LUID)


FN_PLUID
PLUID  LUID *   winnt.h


PROPENUMPROC
PROPENUMPROC  STRICT: typedef BOOL (CALLBACK* PROPENUMPROC)(HWND, LPCTSTR, HANDLE); ELSE: typedef FARPROC PROPENUMPROC  winuser.h

Pointer to an application-defined callback function that enumerates window properties. See PropEnumProc for information on functions of this type.


FN_PROPENUMPROC
PROPENUMPROC  STRICT: typedef BOOL (CALLBACK* PROPENUMPROC)(HWND, LPCTSTR, HANDLE); ELSE: typedef FARPROC PROPENUMPROC  winuser.h


PROPENUMPROCEX
PROPENUMPROCEX  STRICT: typedef BOOL (CALLBACK* PROPENUMPROCEX)(HWND, LPTSTR, HANDLE, DWORD); ELSE: typedef FARPROC PROPENUMPROCEX  winuser.h

Pointer to an application-defined callback function that enumerates window properties. See PropEnumProcEx for information on functions of this type.


FN_PROPENUMPROCEX
PROPENUMPROCEX  STRICT: typedef BOOL (CALLBACK* PROPENUMPROCEX)(HWND, LPTSTR, HANDLE, DWORD); ELSE: typedef FARPROC PROPENUMPROCEX  winuser.h


PSHORT
PSHORT  SHORT *   winnt.h

Pointer to a signed short (16 bits)


FN_PSHORT
PSHORT  SHORT *   winnt.h


PSID
PSID  PVOID    winnt.h

Pointer to a security identifier (SID)


FN_PSID
PSID  PVOID    winnt.h


PSTR
PSTR  CHAR *   winnt.h

Pointer to a null-terminated Windows character string


FN_PSTR
PSTR  CHAR *   winnt.h


PSZ
PSZ  char *   windef.h

Pointer to a null-terminated Windows character string


FN_PSZ
PSZ  char *   windef.h


PTCH
PTCH  Windows: LPSTR Unicode: LPWSTR    winnt.h

Pointer to a Windows or Unicode character


FN_PTCH
PTCH  Windows: LPSTR Unicode: LPWSTR    winnt.h


PTCHAR
PTCHAR  char *   winnt.h

Pointer to a Windows or Unicode character


FN_PTCHAR
PTCHAR  char *   winnt.h


PTSTR
PTSTR  Windows: LPSTR Unicode: LPWSTR    winnt.h

Pointer to a null-terminated Windows or Unicode character string


FN_PTSTR
PTSTR  Windows: LPSTR Unicode: LPWSTR    winnt.h


PUCHAR
PUCHAR  UCHAR *   windef.h

Pointer to an unsigned Windows character


FN_PUCHAR
PUCHAR  UCHAR *   windef.h


PUINT
PUINT  unsigned int *   windef.h

Pointer to an unsigned integer


FN_PUINT
PUINT  unsigned int *   windef.h


PULONG
PULONG  ULONG *   windef.h

Pointer to an unsigned long (32 bits)


FN_PULONG
PULONG  ULONG *   windef.h


PUSHORT
PUSHORT  USHORT *   windef.h

Pointer to an unsigned short (16 bits)


FN_PUSHORT
PUSHORT  USHORT *   windef.h


PVOID
PVOID  void *   winnt.h

Pointer to any type


FN_PVOID
PVOID  void *   winnt.h


PWCH
PWCH  WCHAR *   winnt.h

Pointer to a Unicode character


FN_PWCH
PWCH  WCHAR *   winnt.h


PWCHAR
PWCHAR  WCHAR *   winnt.h

Pointer to a Unicode character


FN_PWCHAR
PWCHAR  WCHAR *   winnt.h


PWORD
PWORD  WORD near *   windef.h

Pointer to an unsigned word (16 bits)


FN_PWORD
PWORD  WORD near *   windef.h


PWSTR
PWSTR  WCHAR *   winnt.h

Pointer to a null-terminated Unicode character string


FN_PWSTR
PWSTR  WCHAR *   winnt.h


REGSAM
REGSAM  ACCESS_MASK    winreg.h

Security access mask for registry key


FN_REGSAM
REGSAM  ACCESS_MASK    winreg.h


SC_HANDLE
SC_HANDLE  HANDLE    winsvc.h

Handle of a service


FN_SC_HANDLE
SC_HANDLE  HANDLE    winsvc.h


SENDASYNCPROC
SENDASYNCPROC  STRICT: typedef VOID (CALLBACK* SENDASYNCPROC)(HWND, UINT, DWORD, LRESULT); ELSE: typedef FARPROC SENDASYNCPROC  winuser.h

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.


FN_SENDASYNCPROC
SENDASYNCPROC  STRICT: typedef VOID (CALLBACK* SENDASYNCPROC)(HWND, UINT, DWORD, LRESULT); ELSE: typedef FARPROC SENDASYNCPROC  winuser.h


SERVICE_STATUS_HANDLE
SERVICE_STATUS_HANDLE  DWORD    winsvc.h

Handle of a service status value


FN_SERVICE_STATUS_HANDLE
SERVICE_STATUS_HANDLE  DWORD    winsvc.h


SHORT
SHORT  short    winnt.h

Short integer


FN_SHORT
SHORT  short    winnt.h


SPHANDLE
SPHANDLE  HANDLE NEAR *   windef.h

Pointer to a handle


FN_SPHANDLE
SPHANDLE  HANDLE NEAR *   windef.h


TCHAR
TCHAR  Windows: char Unicode: WCHAR    winnt.h

Unicode character or Windows character


FN_TCHAR
TCHAR  Windows: char Unicode: WCHAR    winnt.h


TIMERPROC
TIMERPROC  STRICT: typedef VOID (CALLBACK* TIMERPROC)(HWND, UINT, UINT, DWORD); else: FARPROC  winuser.h

Pointer to an application-defined timer callback function


FN_TIMERPROC
TIMERPROC  STRICT: typedef VOID (CALLBACK* TIMERPROC)(HWND, UINT, UINT, DWORD); else: FARPROC  winuser.h


UCHAR
UCHAR  unsigned char    windef.h

Unsigned Windows character


FN_UCHAR
UCHAR  unsigned char    windef.h


UINT
UINT  unsigned int    windef.h

Unsigned integer


FN_UINT
UINT  unsigned int    windef.h


ULONG
ULONG  unsigned long    windef.h

Unsigned long integer (32 bits)


FN_ULONG
ULONG  unsigned long    windef.h


USHORT
USHORT  unsigned short    windef.h

Unsigned short integer (16 bits)


FN_USHORT
USHORT  unsigned short    windef.h


VOID
VOID  void    winnt.h

Any type


FN_VOID
VOID  void    winnt.h


WCHAR
WCHAR  unsigned short    winnt.h

Unicode character


FN_WCHAR
WCHAR  unsigned short    winnt.h


WNDENUMPROC
WNDENUMPROC  STRICT: typedef BOOL (CALLBACK* WNDENUMPROC)(HWND, LPARAM); else: FARPROC    winuser.h

Pointer to an application-defined callback function that enumerates windows


FN_WNDENUMPROC
WNDENUMPROC  STRICT: typedef BOOL (CALLBACK* WNDENUMPROC)(HWND, LPARAM); else: FARPROC    winuser.h


WNDPROC
WNDPROC  typedef LRESULT (CALLBACK* WNDPROC)(HWND, UINT, WPARAM, LPARAM);  winuser.h

Pointer to an application-defined window procedure


FN_WNDPROC
WNDPROC  typedef LRESULT (CALLBACK* WNDPROC)(HWND, UINT, WPARAM, LPARAM);  winuser.h


WORD
WORD  unsigned short    windef.h

Unsigned word (16 bits)


FN_WORD
WORD  unsigned short    windef.h


WPARAM
WPARAM    ole.h: WORD windef.h: UINT

32-bit message parameter


FN_WPARAM
WPARAM    ole.h: WORD windef.h: UINT


YIELDPROC
YIELDPROC  typedef UINT (*YIELDPROC) (MCIDEVICEID, DWORD);  mmsystem.h

Pointer to a yield callback function


FN_YIELDPROC
YIELDPROC  typedef UINT (*YIELDPROC) (MCIDEVICEID, DWORD);  mmsystem.h


This section describes the purpose and defines the parameters of macros associated with functions for the Microsoft® Win32™ application programming interface. It lists the Windows macros in alphabetic order.

Alphabetic Reference


GetBValue macro
GetBValue (Win32)

BYTE GetBValue(rgb)

DWORD rgb;	/* 32-bit RGB value	*/

The GetBValue macro retrieves an intensity value for the blue component of a 32-bit red, green, blue (RGB) value.

Parameter	Description

rgb	Specifies an RGB color value.

Returns

The return value is the intensity of the blue component of the specified RGB color.

Comments

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


GetGValue macro
GetGValue (Win32)

BYTE GetGValue(rgb)

DWORD rgb;	/* 32-bit RGB value	*/

The GetGValue macro retrieves an intensity value for the green component of a 32-bit red, green, blue (RGB) value.

Parameter	Description

rgb	Specifies an RGB color value.

Returns

The return value is the intensity of the green component of the specified RGB color.

Comments

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


GetRValue macro
GetRValue (Win32)

BYTE GetRValue(rgb)

DWORD rgb;	/* 32-bit RGB value	*/

The GetRValue macro retrieves an intensity value for the red component of a 32-bit red, green, blue (RGB) value.

Parameter	Description

rgb	Specifies an RGB color value.

Returns

The return value is the intensity of the red component of the specified RGB color.

Comments

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


HIBYTE macro
HIBYTE (Win32)

BYTE HIBYTE(wValue)

WORD wValue;	/* value from which high-order byte is retrieved	*/

The HIBYTE macro retrieves the high-order byte from the given 16-bit value.

Parameter	Description

wValue	Specifies the value to be converted.

Returns

The return value is the high-order byte of the specified value.

Comments

The HIBYTE macro is defined as follows:

#define HIBYTE(w)  ((BYTE)(((WORD)(w) >> 8) & 0xFF))

See Also

HIWORD, LOBYTE


HIWORD macro
HIWORD (Win32)

WORD HIWORD(dwValue)

DWORD dwValue;	/* value from which high-order word is retrieved	*/

The HIWORD macro retrieves the high-order word from the given 32-bit value.

Parameter	Description

dwValue	Specifies the value to be converted.

Returns

The return value is the high-order word of the specified value.

Comments

The HIWORD macro is defined as follows:

#define HIWORD(l)  ((WORD)(((DWORD)(l) >> 16) & 0xFFFF))

See Also

HIBYTE, LOWORD


LANGIDFROMLCID macro
LANGIDFROMLCID (Win32)

WORD LANGIDFROMLCID(lcid)

LCID lcid;	/* locale identifier	*/

The LANGIDFROMLCID macro retrieves a language identifier from a locale identifier.

Parameter	Description

lcid	Specifies the locale identifier. This parameter may have been created by using the MAKELCID macro.

Returns

The return value is a language identifier.

Comments

The LANGIDFROMLCID macro is defined as follows:

#define LANGIDFROMLCID(lcid)  ((WORD) (lcid))

See Also

MAKELANGID, MAKELCID, PRIMARYLANGID, SUBLANGID


LOBYTE macro
LOBYTE (Win32)

BYTE LOBYTE(wValue)

WORD wValue;	/* value from which low-order byte is retrieved	*/

The LOBYTE macro retrieves the low-order byte from the given 16-bit value.

Parameter	Description

wValue	Specifies the value to be converted.

Returns

The return value is the low-order byte of the specified value.

Comments

The LOBYTE macro is defined as follows:

#define LOBYTE(w)  ((BYTE)(w))

See Also

HIBYTE, LOWORD


LOWORD macro
LOWORD (Win32)

WORD LOWORD(dwValue)

DWORD dwValue;	/* value from which low-order word is retrieved	*/

The LOWORD macro retrieves the low-order word from the given 32-bit value.

Parameter	Description

dwValue	Specifies the value to be converted.

Returns

The return value is the low-order word of the specified value.

Comments

The LOWORD macro is defined as follows:

#define LOWORD(l)  ((WORD)(l))

See Also

HIWORD, LOBYTE


MAKEINTATOM macro
MAKEINTATOM (Win32)

LPTSTR MAKEINTATOM(wInteger)

WORD wInteger;	/* integer to make into atom	*/

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.

Parameter	Description

wInteger	Specifies the numeric value to be made into an integer atom.

Returns

The return value is a pointer to the atom created for the given integer.

Comments

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 macro
MAKEINTRESOURCE (Win32)

LPTSTR MAKEINTRESOURCE(wInteger)

WORD wInteger;	/* integer to convert	*/

The MAKEINTRESOURCE macro converts an integer value to a resource type compatible with Windows resource-management functions. This macro is used in place of a string containing the name of the resource.

Parameter	Description

wInteger	Specifies the integer value to be converted.

Returns

The return value is the specified value in the low-order word and zero in the high-order word.

Comments

The return value should be passed only to the Windows resource-management functions, as the lpType parameter.

The MAKEINTRESOURCE macro is defined as follows:

#define MAKEINTRESOURCE(i)  (LPTSTR)((DWORD)((WORD)(i)))


MAKELANGID macro
MAKELANGID (Win32)

WORD MAKELANGID(usPrimaryLanguage, usSubLanguage)

USHORT usPrimaryLanguage;	/* primary language identifier	*/
USHORT usSubLanguage;	/* sublanguage identifier	*/

The MAKELANGID macro creates a language identifier from a primary language identifier and a sublanguage identifier.

Parameter	Description

usPrimaryLanguage	Specifies the primary language identifier. This parameter can be one of the following values:

LANG_ALBANIAN	LANG_ITALIAN

LANG_ARABIC	LANG_JAPANESE

LANG_BAHASA	LANG_KOREAN

LANG_BULGARIAN	LANG_NEUTRAL

LANG_CATALAN	LANG_NORWEGIAN

LANG_CHINESE	LANG_POLISH

LANG_CZECH	LANG_PORTUGUESE

LANG_DANISH	LANG_RHAETO_ROMAN

LANG_DUTCH	LANG_ROMANIAN

LANG_ENGLISH	LANG_RUSSIAN

LANG_FINNISH	LANG_SERBO_CROATIAN

LANG_FRENCH	LANG_SLOVAK

LANG_GERMAN	LANG_SPANISH

LANG_GREEK	LANG_SWEDISH

LANG_HEBREW	LANG_THAI

LANG_HUNGARIAN	LANG_TURKISH

LANG_ICELANDIC	LANG_URDU

usSubLanguage	Specifies the sublanguage identifier. This parameter can be one of the following values:

SUBLANG_CHINESE_SIMPLIFIED	SUBLANG_GERMAN_AUSTRIAN

SUBLANG_CHINESE_TRADITIONAL	SUBLANG_GERMAN_SWISS

SUBLANG_DEFAULT	SUBLANG_ITALIAN

SUBLANG_DUTCH	SUBLANG_ITALIAN_SWISS

SUBLANG_DUTCH_BELGIAN	SUBLANG_NEUTRAL

SUBLANG_ENGLISH_AUS	SUBLANG_NORWEGIAN_BOKMAL

SUBLANG_ENGLISH_CAN	SUBLANG_NORWEGIAN_NYNORSK

SUBLANG_ENGLISH_EIRE	SUBLANG_PORTUGUESE

SUBLANG_ENGLISH_NZ	SUBLANG_PORTUGUESE_BRAZILIAN

SUBLANG_ENGLISH_UK	SUBLANG_SERBO_CROATIAN_CYRILLIC

SUBLANG_ENGLISH_US	SUBLANG_SERBO_CROATIAN_LATIN

SUBLANG_FRENCH	SUBLANG_SPANISH

SUBLANG_FRENCH_BELGIAN	SUBLANG_SPANISH_MEXICAN

SUBLANG_FRENCH_CANADIAN	SUBLANG_SPANISH_MODERN

SUBLANG_FRENCH_SWISS	SUBLANG_SYS_DEFAULT

SUBLANG_GERMAN

Returns

The return value is a language identifier that can be used with the FindResourceEx and EnumResLangProc functions.

Comments

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) ((((USHORT)(s)) << 10) | (USHORT)(p))

See Also

LANGIDFROMLCID, MAKELCID, PRIMARYLANGID, SUBLANGID, EnumResLangProc, FindResourceEx


MAKELCID macro
MAKELCID (Win32)

DWORD MAKELCID(wLanguageID, wSortID)

WORD wLanguageID;	/* language identifier	*/
WORD wSortID;	/* sorting identifier	*/

The MAKELCID macro creates a locale identifier from a language identifier.

Parameter	Description

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. For the first release of Windows NT, use the value SORT_DEFAULT for this parameter.

Returns

The return value is a locale identifier.

Comments

The MAKELCID macro is defined as follows:

#define MAKELCID(lgid, srtid) \

    ((ULONG)((((ULONG)((USHORT)(srtid))) << 16) |  \

            ((ULONG)((USHORT)(lgid)))))

See Also

LANGIDFROMLCID, MAKELANGID, SORTIDFROMLCID


MAKELONG macro
MAKELONG (Win32)

DWORD MAKELONG(wLow, wHigh)

WORD wLow;	/* low-order word of long value	*/
WORD wHigh;	/* high-order word of long value	*/

The MAKELONG macro creates an unsigned 32-bit value by concatenating two given 16-bit values.

Parameter	Description

wLow	Specifies the low-order word of the new long value.

wHigh	Specifies the high-order word of the new long value.

Returns

The return value is an unsigned 32-bit value.

Comments

The MAKELONG macro is defined as follows:

#define MAKELONG(a, b) \

    ((LONG)(((WORD)(a)) | ((DWORD)((WORD)(b))) << 16))


MAKELPARAM macro
MAKELPARAM (Win32)

LPARAM MAKELPARAM(wLow, wHigh)

WORD wLow;	/* low-order word	*/
WORD wHigh;	/* high-order word	*/

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.

Parameter	Description

wLow	Specifies the low-order word of the new long value.

wHigh	Specifies the high-order word of the new long value.

Returns

The return value is an unsigned 32-bit value.

Comments

The MAKELPARAM macro is defined as follows:

#define MAKELPARAM(l, h)   ((LPARAM)MAKELONG(l, h))

See Also

MAKELONG, MAKELRESULT, MAKEWPARAM


MAKELRESULT macro
MAKELRESULT (Win32)

LRESULT MAKELRESULT(wLow, wHigh)

WORD wLow;	/* low-order word	*/
WORD wHigh;	/* high-order word	*/

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.

Parameter	Description

wLow	Specifies the low-order word of the new long value.

wHigh	Specifies the high-order word of the new long value.

Returns

The return value is an unsigned 32-bit value.

Comments

The MAKELRESULT macro is defined as follows:

#define MAKELRESULT(l, h)  ((LRESULT)MAKELONG(l, h))

See Also

MAKELONG, MAKELPARAM, MAKEWPARAM


MAKEPOINTS macro
MAKEPOINTS (Win32)

POINTS MAKEPOINTS(dwValue)

DWORD dwValue;	/* coordinates of a point	*/

The MAKEPOINTS macro converts a value that contains the x- and y-coordinates of a point into a POINTS structure.

Parameter	Description

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.

Returns

The return value is a pointer to a POINTS structure.

Comments

The MAKEPOINTS macro is defined as follows:

#define MAKEPOINTS(l)  (*((POINTS FAR *)&(l)))

For a full description of this structure, see Structures

See Also

GetMessagePos, POINTS


MAKEWORD macro
MAKEWORD (Win32)

WORD MAKEWORD(bLow, bHigh)

BYTE bLow;	/* low-order byte of short value	*/
BYTE bHigh;	/* high-order byte of short value	*/

The MAKEWORD macro creates an unsigned 16-bit integer by concatenating two given unsigned character values.

Parameter	Description

bLow	Specifies the low-order byte of the new short value.

bHigh	Specifies the high-order byte of the new short value.

Returns

The return value is an unsigned 16-bit integer value.

Comments

The MAKEWORD macro is defined as follows:

#define MAKEWORD(a, b) \

    ((WORD)(((BYTE)(a)) | ((WORD)((BYTE)(b))) << 8))


MAKEWPARAM macro
MAKEWPARAM (Win32)

LPARAM MAKEWPARAM(wLow, wHigh)

WORD wLow;	/* low-order word	*/
WORD wHigh;	/* high-order word	*/

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.

Parameter	Description

wLow	Specifies the low-order word of the new long value.

wHigh	Specifies the high-order word of the new long value.

Returns

The return value is an unsigned 32-bit value.

Comments

The MAKEWPARAM macro is defined as follows:

#define MAKEWPARAM(l, h)   ((LPARAM)MAKELONG(l, h))

See Also

MAKELONG, MAKELPARAM, MAKELRESULT


max macro
max (Win32)

max(value1, value2)

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.

Parameter	Description

value1	Specifies the first of two values.

value2	Specifies the second of two values.

Returns

The return value is the greater of the two specified values.

Comments

The max macro is defined as follows:

#define max(a, b)  (((a) > (b)) ? (a) : (b))

See Also

min


min macro
min (Win32)

min(value1, value2)

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.

Parameter	Description

value1	Specifies the first of two values.

value2	Specifies the second of two values.

Returns

The return value is the smaller of the two specified values.

Comments

The min macro is defined as follows:

#define min(a, b)  (((a) < (b)) ? (a) : (b))

See Also

max


PALETTEINDEX macro
PALETTEINDEX (Win32)

COLORREF PALETTEINDEX(wPaletteIndex)

WORD wPaletteIndex;	/* index to palette entry	*/

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 graphics device interface (GDI) functions that expect a color. This allows the function to use the color in the specified palette entry.

Parameter	Description

wPaletteIndex	Specifies an index to the palette entry containing the color to be used for a graphics operation.

Returns

The return value is a logical-palette index specifier.

Comments

The PALETTEINDEX macro is defined as follows:

#define PALETTEINDEX(i) /

    ((COLORREF)(0x01000000 | (DWORD)(WORD)(i)))

See Also

PALETTERGB, RGB


PALETTERGB macro
PALETTERGB (Win32)

COLORREF PALETTERGB(bRed, bGreen, bBlue)

BYTE bRed;	/* red component of palette-relative RGB	*/
BYTE bGreen;	/* green component of palette-relative RGB	*/
BYTE bBlue;	/* blue component of palette-relative RGB	*/

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.

Parameter	Description

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.

Returns

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.

Comments

The PALETTERGB macro is defined as follows:

#define PALETTERGB(r, g, b)  (0x02000000 | RGB(r,g,b))

See Also

PALETTEINDEX, RGB


POINTSTOPOINT macro
POINTSTOPOINT (Win32)

POINTSTOPOINT(pt, pts)

POINT pt;	/* POINT structure	*/
POINTS pts;	/* POINTS structure	*/

The POINTSTOPOINT macro copies the contents of a POINTS structure into a POINT structure.

Parameter	Description

pt	Specifies the POINT structure to receive the contents of the POINTS structure.

For more information about this structure, see Structures

pts	Specifies the POINTS structure to copy.

For more information about this structure, see StructuresComments

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, POINTS


POINTTOPOINTS macro
POINTTOPOINTS (Win32)

POINTS POINTTOPOINTS(pt)

POINT pt;	/* coordinates of a point	*/

The POINTTOPOINTS macro converts a POINT structure to a POINTS structure.

Parameter	Description

pt	Specifies the POINT structure to convert.

For more information about this structure, see Structures

Returns

The return value is a POINTS structure.

Comments

The POINTTOPOINTS macro is defined as follows:

#define POINTTOPOINTS(pt) \

    (MAKELONG((short)((pt).x), (short)((pt).y)))

See Also

MAKEPOINTS, POINTSTOPOINT, POINTS


PRIMARYLANGID macro
PRIMARYLANGID (Win32)

BYTE PRIMARYLANGID (usLanguageID)

USHORT usLanguageID;	/* language identifier	*/

The PRIMARYLANGID macro extracts a primary language identifier from a language identifier.

Parameter	Description

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

Returns

The return value is one of the following primary language identifiers:

LANG_ALBANIAN	LANG_ITALIAN

LANG_ARABIC	LANG_JAPANESE

LANG_BAHASA	LANG_KOREAN

LANG_BULGARIAN	LANG_NEUTRAL

LANG_CATALAN	LANG_NORWEGIAN

LANG_CHINESE	LANG_POLISH

LANG_CZECH	LANG_PORTUGUESE

LANG_DANISH	LANG_RHAETO_ROMAN

LANG_DUTCH	LANG_ROMANIAN

LANG_ENGLISH	LANG_RUSSIAN

LANG_FINNISH	LANG_SERBO_CROATIAN

LANG_FRENCH	LANG_SLOVAK

LANG_GERMAN	LANG_SPANISH

LANG_GREEK	LANG_SWEDISH

LANG_HEBREW	LANG_THAI

LANG_HUNGARIAN	LANG_TURKISH

LANG_ICELANDIC	LANG_URDU

Comments

The PRIMARYLANGID macro is defined as follows:

#define PRIMARYLANGID(lgid)  ((USHORT)(lgid) & 0x3FF)

See Also

LANGIDFROMLCID, MAKELANGID, SUBLANGID


RGB macro
RGB (Win32)

COLORREF RGB(bRed, bGreen, bBlue)

BYTE bRed;	/* red component of color	*/
BYTE bGreen;	/* green component of color	*/
BYTE bBlue;	/* blue component of color	*/

The RGB macro selects a red, green, blue (RGB) color based on the arguments supplied and the color capabilities of the output device.

Parameter	Description

cRed	Specifies the intensity of the red color.

cGreen	Specifies the intensity of the green color.

cBlue	Specifies the intensity of the blue color.

Returns

The return value is the resultant RGB color.

Comments

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.

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


SUBLANGID macro
SUBLANGID (Win32)

BYTE SUBLANGID(usLanguageID)

USHORT usLanguageID;	/* language identifier	*/

The SUBLANGID macro extracts a sublanguage identifier from a language identifier.

Parameter	Description

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

Returns

The return value is one of the following sublanguage identifiers:

SUBLANG_CHINESE_SIMPLIFIED	SUBLANG_GERMAN_AUSTRIAN

SUBLANG_CHINESE_TRADITIONAL	SUBLANG_GERMAN_SWISS

SUBLANG_DEFAULT	SUBLANG_ITALIAN

SUBLANG_DUTCH	SUBLANG_ITALIAN_SWISS

SUBLANG_DUTCH_BELGIAN	SUBLANG_NEUTRAL

SUBLANG_ENGLISH_AUS	SUBLANG_NORWEGIAN_BOKMAL

SUBLANG_ENGLISH_CAN	SUBLANG_NORWEGIAN_NYNORSK

SUBLANG_ENGLISH_EIRE	SUBLANG_PORTUGUESE

SUBLANG_ENGLISH_NZ	SUBLANG_PORTUGUESE_BRAZILIAN

SUBLANG_ENGLISH_UK	SUBLANG_SERBO_CROATIAN_CYRILLIC

SUBLANG_ENGLISH_US	SUBLANG_SERBO_CROATIAN_LATIN

SUBLANG_FRENCH	SUBLANG_SPANISH

SUBLANG_FRENCH_BELGIAN	SUBLANG_SPANISH_MEXICAN

SUBLANG_FRENCH_CANADIAN	SUBLANG_SPANISH_MODERN

SUBLANG_FRENCH_SWISS	SUBLANG_SYS_DEFAULT

SUBLANG_GERMAN

Comments

The SUBLANGID macro is defined as follows:

#define SUBLANGID(lgid) ((USHORT)(lgid) >> 10)

See Also

LANGIDFROMLCID, MAKELANGID, PRIMARYLANGID


SORTIDFROMLCID macro
SORTIDFROMLCID (Win32)

WORD SORTIDFROMLCID(lcid)

LCID lcid;	/* locale identifier	*/

The SORTIDFROMLCID macro retrieves a sort identifier from a locale identifier.

Parameter	Description

lcid	Specifies the locale identifier. This parameter may have been created by using the MAKELCID macro.

Returns

The return value is a sort identifier.

Comments

The SORTIDFROMLCID macro is defined as follows:

#define SORTIDFROMLCID(lcid) \

          ((USHORT) ((((ULONG)(lcid)) & 0x000FFFFF) >> 16 ))

The following sort identifier is defined:

Value	Meaning

SORT_DEFAULT	Specifies the default sort.

See Also

MAKELANGID, MAKELCID, PRIMARYLANGID, SUBLANGID


TEXT macro
TEXT (Win32)

TEXT(string)

LPTSTR string;	/* address of ANSI or Unicode string	*/

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.

Parameter	Description

string	Specifies the string to be interpreted as either Unicode or ANSI.

Comments

The TEXT macro is defined as follows:

#define TEXT(quote) L##quote


Macros (all)

GetBValue	Retrieves blue-intensity value from 32-bit RGB value

GetGValue	Retrieves green-intensity value from 32-bit RGB value

GetRValue	Retrieves red-intensity value from 32-bit RGB value

HIBYTE	Retrieves the high-order byte

HIWORD	Retrieves the high-order word

LANGIDFROMLCID	Retrieves language ID from locale ID

LOBYTE	Retrieves the low-order byte

LOWORD	Retrieves the low-order word

MAKEINTATOM	Creates an integer atom

MAKEINTRESOURCE	Converts a resource identifier into a string

MAKELANGID	Creates a language ID from primary and sub ID

MAKELCID	Creates a locale ID from language ID

MAKELONG	LONG value from two WORDs

MAKELPARAM	Creates unsigned long-integer message parameter

MAKELRESULT	Creates unsigned long-integer message result

MAKEPOINTS	Converts a long value into a POINTS structure

MAKEWORD	Creates WORD value from two BYTEs

MAKEWPARAM	Creates an unsigned long-integer message parameter

max	Larger of two values

min	Returns the smaller of two values

PALETTEINDEX	Returns a logical-palette index specifier

PALETTERGB	Red, green, blue values to COLORREF

POINTSTOPOINT	Copies POINTS structure to POINT structure

POINTTOPOINTS	Converts POINT structure to POINTS structure

PRIMARYLANGID	Extracts primary ID from language ID

RGB	Red, green, blue values to RGB

SUBLANGID	Extracts sublanguage ID from language ID

SORTIDFROMLCID	Retrieves sorting ID from locale ID

TEXT	Converts text to Unicode when UNICODE is defined


ActivateKeyboardLayout function
ActivateKeyboardLayout (Win32)

BOOL ActivateKeyboardLayout(hkl, fuFlags)

HKL hkl;	/* handle of keyboard layout	*/
UINT fuFlags;	/* keyboard layout flags	*/

The ActivateKeyboardLayout function activates a different keyboard layout.

Parameter	Description

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 of 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_PREVIOUS	Selects the previous layout in the circular list of loaded layouts maintained by the system.

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

KLF_UNLOADPREVIOUS	The previously active layout is unloaded.

If less than three layouts are loaded, the value of this flag is irrelevant.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


AdjustWindowRect function
AdjustWindowRect (Win32)

BOOL AdjustWindowRect(lprc, fdwStyle, fMenu)

LPRECT lprc;	/* address of client-rectangle structure	*/
DWORD fdwStyle;	/* window styles	*/
BOOL fMenu;	/* menu-present flag	*/

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 CreateWindow function to create a window whose client area is the desired size.

Parameter	Description

lprc	Points to a RECT structure that contains the coordinates of the client rectangle.

fdwStyle	Specifies the window styles of the window whose required size is to be calculated.

fMenu	Specifies whether the window has a menu.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 take window titles and borders into account when calculating the size of the client area. For window styles that include titles and borders, an application must add the title and border sizes after calling AdjustWindowRect. This function also does not take the extra rows into account when a menu bar wraps to two or more rows.

See Also

AdjustWindowRectEx, CreateWindowEx


AdjustWindowRectEx function
AdjustWindowRectEx (Win32)

BOOL AdjustWindowRectEx(lprc, fdwStyle, fMenu, fdwExStyle)

LPRECT lprc;	/* address of client-rectangle structure	*/
DWORD fdwStyle;	/* window styles	*/
BOOL fMenu;	/* menu-present flag	*/
DWORD fdwExStyle;	/* extended style	*/

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.

Parameter	Description

lprc	Points to a RECT structure that contains the coordinates of the client rectangle.

fdwStyle	Specifies the window styles of the window whose required size is to be calculated.

fMenu	Specifies whether the window has a menu.

fdwExStyle	Specifies the extended style of the window whose required size is to be calculated.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 take window titles and borders into account when computing the size of the client area. For window styles that include titles and borders, an application must add the title and border sizes after calling AdjustWindowRectEx. This function also does not add extra space when a menu bar wraps to two or more rows.

See Also

AdjustWindowRect, CreateWindowEx


AnyPopup function
AnyPopup (Win32)

BOOL AnyPopup(VOID)

The AnyPopup function indicates whether an unowned, 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.

Returns

If a pop-up window exists, the return value is TRUE even if the pop-up window is completely covered by other windows. Otherwise, it is FALSE.

Comments

The AnyPopup function 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 function
AppendMenu (Win32)

BOOL AppendMenu(hmenu, fuFlags, idNewItem, lpszNewItem)

HMENU hmenu;	/* handle of menu	*/
UINT fuFlags;	/* menu item flags	*/
UINT idNewItem;	/* menu item identifier or pop-up menu handle	*/
LPCTSTR lpszNewItem;	/* menu item content	*/

The AppendMenu function appends a new item to the end of the given menu. An application can use this function to specify the content, appearance, and behavior of the menu item.

Parameter	Description

hmenu	Identifies the menu to be changed.

fuFlags	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 Comments section.

idNewItem	Specifies either the identifier of the new menu item or, if the fuFlags parameter is set to MF_POPUP, the handle of the pop-up menu.

lpszNewItem	Specifies the content of the new menu item. The interpretation of lpszNewItem depends on whether the fuFlags parameter includes the MF_BITMAP, MF_OWNERDRAW, or MF_STRING flag, as follows:

Value	Meaning

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 its appearance or updated.

MF_STRING	Contains a pointer to a null-terminated string.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

Following are the flags that must be set in the fuFlags parameter:

Value	Meaning

MF_BITMAP	Uses a bitmap as the item. The lpszNewItem parameter contains the handle of the bitmap.

MF_CHECKED	Places a check mark next to the item. If the application provides check mark bitmaps (see the SetMenuItemBitmaps function), 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 the 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 it cannot be selected.

MF_MENUBARBREAK	Functions the same as the MF_MENUBREAK flag except for pop-up 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 pop-up menus) 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 is a pop-up item; that is, selecting it activates a pop-up menu. The idNewItem parameter specifies the handle of the pop-up menu. This flag is used to add a pop-up item to a menu bar or to a pop-up menu.

MF_SEPARATOR	Draws a horizontal dividing line. This flag is only used in a pop-up menu. The line cannot be grayed, disabled, or highlighted. The lpszNewItem and idNewItem parameters are ignored.

MF_STRING	Specifies that the menu item is a text string; the lpszNewItem 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 the SetMenuItemBitmaps function), this flag displays the unchecked bitmap next to the menu item.

The following list shows groups of flags that 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, ModifyMenu, RemoveMenu, SetMenuItemBitmaps


ArrangeIconicWindows function
ArrangeIconicWindows (Win32)

UINT ArrangeIconicWindows(hwnd)

HWND hwnd;	/* handle of parent window	*/

The ArrangeIconicWindows function arranges all the minimized (iconic) child windows of the given parent window.

Parameter	Description

hwnd	Identifies the parent window.

Returns

If the function succeeds, the return value is the height of one row of icons; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

An application that maintains its own minimized child windows can use ArrangeIconicWindows to arrange icons in a parent window. This function can also arrange icons on the desktop. To retrieve the window handle of 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 function
AttachThreadInput (Win32)

BOOL AttachThreadInput(idAttach, idAttachTo, fAttach)

DWORD idAttach;	/* thread to attach	*/
DWORD idAttachTo;	/* thread to attach to	*/
BOOL fAttach;	/* attach or detach	*/

Parameter	Description

idAttach	Specifies the identifier of the thread to be attached to another thread.

idAttachTo	Specifies the identifier of the thread to be attached to.

fAttach	Specifies whether to attach or detach the threads. If this parameter is TRUE, the two threads are attached. If the parameter FALSE, the threads are detached.

Returns

If the function succeeds, the return value is TRUE. Otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Normally, windows created in different threads 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 this function, a thread can attach its input processing to another thread. This also allows a thread to share its 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 normally possible.

Please note that key state, which can be ascertained by calls to GetKeyState or GetKeyboardState, is reset after a call to AttachThreadInput.

See Also

GetCurrentThreadId, GetWindowThreadProcessId


BeginDeferWindowPos function
BeginDeferWindowPos (Win32)

HDWP BeginDeferWindowPos(cWindows)

int cWindows;	/* number of windows	*/

The BeginDeferWindowPos function allocates memory for a multiple-window-position structure and returns the handle of the structure.

Parameter	Description

cWindows	Specifies the initial number of windows for which to store position information. The DeferWindowPos function increases the size of the structure, if necessary.

Returns

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.

Comments

The multiple-window-position structure is an internal structure; an application cannot access it directly.

The DeferWindowPos function 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 of 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 flag set, none of the windows repositioned.

If Windows must increase the size of the multiple-window-position structure beyond the initial size specified by the cWindows 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 handle failure early in the process.

See Also

DeferWindowPos, EndDeferWindowPos, SetWindowPos


BeginPaint function
BeginPaint (Win32)

HDC BeginPaint(hwnd, lpps)

HWND hwnd;	/* handle of window	*/
LPPAINTSTRUCT lpps;	/* address of structure for paint information	*/

The BeginPaint function prepares the given window for painting and fills a PAINTSTRUCT structure with information about the painting.

Parameter	Description

hwnd	Identifies the window to be repainted.

lpps	Points to the PAINTSTRUCT structure that will receive painting information.

Returns

If the function succeeds, the return value is the handle of a display device context (DC) for the given window. Otherwise, it is NULL, indicating that no display DC is available.

Comments

BeginPaint automatically sets the clipping region of the DC 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, ValidateRect, ValidateRgn, PAINTSTRUCT, RECT, WM_PAINT, WM_ERASEBKGND


BringWindowToTop function
BringWindowToTop (Win32)

BOOL BringWindowToTop(hwnd)

HWND hwnd;	/* handle of window	*/

The BringWindowToTop function brings the given 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.

Parameter	Description

hwnd	Identifies the window to bring to the top of the Z order.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Use BringWindowToTop 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. The BringWindowToTop function 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 SetForegroundWindow.

See Also

SetWindowPos, SetActiveWindow, SetForegroundWindow


CallMsgFilter function
CallMsgFilter (Win32)

BOOL CallMsgFilter(lpmsg, nCode)

LPMSG lpmsg;	/* address of structure with message data	*/
int nCode;	/* hook code	*/

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.

Parameter	Description

lpmsg	Points 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.

Returns

If the application should process the message further, the return value is zero; otherwise, it is nonzero.

Comments

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, SetWindowsHookEx, SysMsgProc


CallNextHookEx function
CallNextHookEx (Win32)

LRESULT CallNextHookEx(hhook, nCode, wParam, lParam)

HHOOK hhook;	/* handle of current hook	*/
int nCode;	/* hook code passed to hook procedure	*/
WPARAM wParam;	/* value passed to hook procedure	*/
LPARAM lParam;	/* value passed to hook procedure	*/

The CallNextHookEx function passes the hook information to the next hook procedure in the current hook chain.

Parameter	Description

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

Returns

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.

Comments

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 function
CallWindowProc (Win32)

LRESULT CallWindowProc(wndprcPrev, hwnd, uMsg, wParam, lParam)

WNDPROC wndprcPrev;	/* address of previous procedure	*/
HWND hwnd;	/* handle of window	*/
UINT uMsg;	/* message	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The CallWindowProc function passes message information to the specified window procedure.

Parameter	Description

wndprcPrev	Points to the previous window procedure.

hwnd	Identifies the window procedure to receive the message.

uMsg	Specifies the message.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

The return value specifies the result of the message processing and depends on the message sent.

Comments

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 wndprcPrev parameter is typed as WNDPROC. The WNDPROC type is declared as:

LRESULT (CALLBACK* WNDPROC)(HWND, UINT, WPARAM, LPARAM);

If STRICT is not defined, the wndprcPrev parameter is typed as FARPROC. The FARPROC type is declared as:

int (FAR WINAPI * FARPROC)()

In C, the FARPROC declaration indicates a callback function that has an unspecified parameters 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. The following code shows one way to handle this situation:

#ifdef STRICT

  WNDPROC MyWindowProcedure

#else

  FARPROC MyWindowProcedure

#endif

...

    lResult = CallWindowProc(MyWindowProcedure, ...) ;

For further information on functions declared with empty argument lists, refer to Section r.18.2 of The C++ Programming Language, Second Edition by Bjarne Stroustrup.

See Also

SetClassLong, SetWindowLong


ChangeClipboardChain function
ChangeClipboardChain (Win32)

BOOL ChangeClipboardChain(hwndRemove, hwndNext)

HWND hwndRemove;	/* handle of window to remove	*/
HWND hwndNext;	/* handle of next window	*/

The ChangeClipboardChain function removes a given window from the chain of clipboard viewers.

Parameter	Description

hwndRemove	Identifies the window to be removed from the chain. The handle must have been passed to the SetClipboardViewer function.

hwndNext	Identifies the window that follows the hwndRemove window in the clipboard viewer chain. (This is the handle returned by the SetClipboardViewer function, unless the sequence was changed in response to a WM_CHANGECBCHAIN message.)

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use GetLastError function.

Comments

The window identified by hwndNext 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


CharLower function
CharLower (Win32)

LPTSTR CharLower(lpszString)

LPTSTR lpszString;	/* address of string or single character	*/

The CharLower function converts a character or a character string to lowercase.

Parameter	Description

lpszString	Points 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.

Returns

If the function succeeds and the value to be converted is a character string, the return value is a pointer to the converted string. Otherwise, the return value is the converted character.

Comments

The language driver makes the conversion for the current language selected by the user at setup or by using Control Panel. If no language driver 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.

See Also

CharLowerBuff, CharUpper, CharUpperBuff


CharLowerBuff function
CharLowerBuff (Win32)

DWORD CharLowerBuff(lpszString, cchString)

LPTSTR lpszString;	/* address of string to convert	*/
DWORD cchString;	/* number of characters to convert	*/

The CharLowerBuff function converts a character string to lowercase. The string is converted in place.

Parameter	Description

lpszString	Points to a buffer containing one or more characters.

cchString	Specifies the number of characters in the buffer to convert.

Returns

If the function succeeds, the return value is the number of characters converted.

Comments

The language driver for the current language selected by the user at setup or by using Control Panel makes the conversion. If no language driver has been selected, Windows completes the conversion using internal default mapping. The conversion is made based on the code page associated with the process locale.

See Also

CharLower, CharUpper, CharUpperBuff


CharNext function
CharNext (Win32)

LPTSTR CharNext(lpszCurrentChar)

LPCTSTR lpszCurrentChar;	/* address of current character	*/

The CharNext function returns a pointer to the next character in a string.

Parameter	Description

lpszCurrentChar	Points to a character in a null-terminated string.

Returns

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.

See Also

CharPrev


CharPrev function
CharPrev (Win32)

LPTSTR CharPrev(lpszStart, lpszCurrentChar)

LPCTSTR lpszStart;	/* address of first character	*/
LPCTSTR lpszCurrentChar;	/* address of current character	*/

The CharPrev function returns a pointer to the preceding character in a string.

Parameter	Description

lpszStart	Points to the beginning of the string.

lpszCurrentChar	Points to a character in a null-terminated string.

Returns

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 lpszCurrentChar parameter equals the lpszStart parameter.

See Also

CharNext


CharToOem function
CharToOem (Win32)

BOOL CharToOem(lpszSrc, lpszDest)

LPCTSTR lpszSrc;	/* address of string to translate	*/
LPTSTR lpszDest;	/* address of translated string	*/

The CharToOem function translates a string into the OEM-defined character set. (OEM stands for original equipment manufacturer.)

Parameter	Description

lpszSrc	Points to the null-terminated string to translate.

lpszDest	Points to the buffer for the translated string. If the string buffer is large enough and the CharToOem function is being used as an ANSI function, the string can be translated in place by setting the lpszDest parameter to the same address as the lpszSrc parameter. This cannot be done if CharToOem is being used as a wide-character function.

Returns

The return value is always TRUE.

See Also

CharToOemBuff, OemToChar, OemToCharBuff


CharToOemBuff function
CharToOemBuff (Win32)

BOOL CharToOemBuff(lpszSrc, lpszDest, cchSrc)

LPCTSTR lpszSrc;	/* address of string to translate	*/
LPTSTR lpszDest;	/* address of translated string	*/
DWORD cchSrc;	/* length of string to translate, in characters	*/

The CharToOemBuff function translates a specified number of characters in a string into the OEM-defined character set. (OEM stands for original equipment manufacturer.)

Parameter	Description

lpszSrc	Points to the null-terminated string to translate.

lpszDest	Points to the buffer for the translated string. If the string buffer is large enough and the CharToOemBuff function is being used as an ANSI function, the string can be translated in place by setting the lpszDest parameter to the same address as the lpszSrc parameter. This cannot be done if CharToOemBuff is being used as a wide-character function.

cchSrc	Specifies the number of characters to translate in the string identified by the lpszSrc parameter.

Returns

The return value is always TRUE.

See Also

CharToOem, OemToChar, OemToCharBuff


CharUpper function
CharUpper (Win32)

LPTSTR CharUpper(lpszString)

LPTSTR lpszString;	/* address of string or single character	*/

The CharUpper function converts a character string to uppercase.

Parameter	Description

lpszString	Points 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.

Returns

If the function succeeds and the value to be converted is a character string, the return value is a pointer to the converted string. Otherwise, the return value is the converted character.

Comments

The language driver for the current language selected by the user at setup or by using Control Panel makes the conversion. If no language driver 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.

See Also

CharLower, CharLowerBuff, CharUpperBuff


CharUpperBuff function
CharUpperBuff (Win32)

DWORD CharUpperBuff(lpszString, cchString)

LPTSTR lpszString;	/* address of string to convert	*/
DWORD cchString;	/* number of characters to convert	*/

The CharUpperBuff function converts a character string to uppercase. The string is converted in place.

Parameter	Description

lpszString	Points to a buffer containing one or more characters.

cchString	Specifies the number of characters in the buffer to convert.

Returns

If the function succeeds, the return value is the number of characters converted.

Comments

The language driver for the current language selected by the user at setup or by using Control Panel makes the conversion. If no language driver has been selected, Windows completes the conversion using internal default mapping. The conversion is made based on the code page associated with the process locale.

See Also

CharLower, CharLowerBuff, CharUpper


CheckDlgButton function
CheckDlgButton (Win32)

BOOL CheckDlgButton(hwndDlg, idButton, uCheck)

HWND hwndDlg;	/* handle of dialog box	*/
int idButton;	/* button-control identifier	*/
UINT uCheck;	/* check state	*/

The CheckDlgButton function places a check mark next to (checks) or removes a check mark from (clears) a button control, or it changes the state of a three-state button.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the button.

idButton	Identifies the button to modify.

uCheck	Specifies the check state of the button. If this parameter is nonzero, CheckDlgButton selects the button; if the parameter is zero, the function clears the button. For a three-state check box, if uCheck is 2, the button is grayed; if uCheck is 1, it is selected; if uCheck is 0, it is cleared.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The CheckDlgButton function sends a BM_SETCHECK message to the specified button control in the given dialog box.

See Also

CheckRadioButton, IsDlgButtonChecked, BM_GETCHECK, BM_SETCHECK


CheckMenuItem function
CheckMenuItem (Win32)

DWORD CheckMenuItem(hmenu, idCheckItem, fuFlags)

HMENU hmenu;	/* handle of menu	*/
UINT idCheckItem;	/* menu item to check or uncheck	*/
UINT fuFlags;	/* menu item flags	*/

The CheckMenuItem function sets the state of the given menu item's check mark attribute to either checked or unchecked.

Parameter	Description

hmenu	Identifies the menu.

idCheckItem	Specifies the menu item whose check mark attribute is to be set, as determined by the fuFlags parameter.

fuFlags	Specifies flags that control the interpretation of the idCheckItem 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 idCheckItem 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 idCheckItem 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.

Returns

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.

Comments

An item in a menu bar cannot have a check mark.

The idCheckItem parameter identifies a pop-up item or a command item. For a pop-up item, the idCheckItem parameter must specify the position of the item, because a pop-up item does not have an identifier. For a command item, the idCheckItem parameter can specify either the item's position or its identifier.

See Also

EnableMenuItem, GetMenuCheckMarkDimensions, GetMenuItemID, SetMenuItemBitmaps


CheckRadioButton function
CheckRadioButton (Win32)

BOOL CheckRadioButton(hwndDlg, idFirstButton, idLastButton, idCheckButton)

HWND hwndDlg;	/* handle of dialog box	*/
int idFirstButton;	/* identifier of first radio button in group	*/
int idLastButton;	/* identifier of last radio button in group	*/
int idCheckButton;	/* identifier of radio button to select	*/

The CheckRadioButton function adds a check mark to (checks) a given radio button in a group and removes a check mark from (clears) all other radio buttons in the group.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the radio button.

idFirstButton	Specifies the identifier of the first radio button in the group.

idLastButton	Specifies the identifier of the last radio button in the group.

idCheckButton	Specifies the identifier of the radio button to select.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The CheckRadioButton function sends a BM_SETCHECK message to the specified radio button control in the given dialog box.

See Also

CheckDlgButton, IsDlgButtonChecked, BM_GETCHECK, BM_SETCHECK


ChildWindowFromPoint function
ChildWindowFromPoint (Win32)

HWND ChildWindowFromPoint(hwndParent, pt)

HWND hwndParent;	/* handle of parent window	*/
POINT pt;	/* structure with point coordinates	*/

The ChildWindowFromPoint function determines which, if any, of the child windows belonging to the given parent window contains the specified point.

Parameter	Description

hwndParent	Identifies the parent window.

pt	Specifies a POINT structure that defines the client coordinates of the point to be checked.

Returns

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 of the parent window.

Comments

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 given point, Windows returns the handle of the first window in the list that contains the point.

See Also

WindowFromPoint


ClientToScreen function
ClientToScreen (Win32)

BOOL ClientToScreen(hwnd, lppt)

HWND hwnd;	/* window handle for source coordinates	*/
LPPOINT lppt;	/* address of structure containing screen coordinates	*/

The ClientToScreen function converts the client coordinates of a given point to screen coordinates.

Parameter	Description

hwnd	Identifies the window whose client area is used for the conversion.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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, ScreenToClient


ClipCursor function
ClipCursor (Win32)

BOOL ClipCursor(lprc)

CONST RECT *lprc;	/* address of structure with rectangle	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SetCursorPos, RECT


CloseClipboard function
CloseClipboard (Win32)

BOOL CloseClipboard(VOID)

The CloseClipboard function closes the clipboard.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

When the window has finished examining or changing the clipboard, close the clipboard by calling the CloseClipboard function. This enables other windows to access the clipboard.

Do not use an object on the clipboard after calling the CloseClipboard function. Instead, use the DuplicateHandle function to create a copy of the data before calling CloseClipboard.

See Also

DuplicateHandle, GetOpenClipboardWindow, OpenClipboard


CloseWindow function
CloseWindow (Win32)

BOOL CloseWindow(hwnd)

HWND hwnd;	/* handle of window to minimize	*/

The CloseWindow function minimizes (but does not destroy) the given window.

Parameter	Description

hwnd	Identifies the window to be minimized.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, IsIconic, OpenIcon


CopyAcceleratorTable function
CopyAcceleratorTable (Win32)

int CopyAcceleratorTable(hacclOriginal, lpacclCopy, cAccel)

HACCEL hacclOriginal;	/* handle of accelerator table to copy	*/
LPACCEL lpacclCopy;	/* address of structure receiving copy	*/
int cAccel;	/* number of entries in table being copied	*/

The CopyAcceleratorTable function copies the given 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.

Parameter	Description

hacclOriginal	Identifies the accelerator table to be copied.

lpacclCopy	Points to an array of ACCEL structures where the accelerator-table information is to be copied.

cAccel	Specifies the number of ACCEL structures to copy to the buffer pointed to by the lpacclCopy parameter.

Returns

If the lpacclCopy parameter 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

CreateAcceleratorTable, DestroyAcceleratorTable, LoadAccelerators, TranslateAccelerator


CopyCursor function
CopyCursor (Win32)

HCURSOR CopyCursor(hcur)

HCURSOR hcur;	/* handle of cursor to copy	*/

The CopyCursor function copies a cursor.

Parameter	Description

hcur	Identifies the cursor to be copied.

Returns

If the function succeeds, the return value is the handle of the duplicate cursor; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

CopyCursor enables an application or dynamic-link library to obtain the handle of 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


CopyIcon function
CopyIcon (Win32)

HICON CopyIcon(hicon)

HICON hicon;	/* handle of icon to copy	*/

The CopyIcon function copies the given icon from another module to the current module.

Parameter	Description

hicon	Identifies the icon to be copied.

Returns

If the function succeeds, the return value is the handle of the duplicate icon; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The CopyIcon function enables an application or dynamic-link library to get its own handle of 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


CopyRect function
CopyRect (Win32)

BOOL CopyRect(lprcDst, lprcSrc)

LPRECT lprcDst;	/* address of struct. for destination rectangle	*/
CONST RECT *lprcSrc;	/* address of struct. with source rectangle	*/

The CopyRect function copies the coordinates of one rectangle to another.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

SetRect, SetRectEmpty, RECT


CountClipboardFormats function
CountClipboardFormats (Win32)

int CountClipboardFormats(VOID)

The CountClipboardFormats function retrieves the number of different data formats currently on the clipboard.

Returns

If the function succeeds, the return value is the number of different data formats currently on the clipboard; otherwise, it is zero. To get extended error information, use the GetLastError function.

See Also

EnumClipboardFormats, RegisterClipboardFormat


CreateAcceleratorTable function
CreateAcceleratorTable (Win32)

HACCEL CreateAcceleratorTable(lpaccl, cEntries)

LPACCEL lpaccl;	/* address of structure array with accelerator data	*/
int cEntries;	/* number of structures in the array	*/

The CreateAcceleratorTable function creates an accelerator table.

Parameter	Description

lpaccl	Points to an array of ACCEL structures that describes the accelerator table.

cEntries	Specifies the number of ACCEL structures in the array.

Returns

If the function succeeds, the return value is the handle of the created accelerator table; otherwise, it is NULL.

Comments

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

CopyAcceleratorTable, DestroyAcceleratorTable, LoadAccelerators, TranslateAccelerator


CreateCaret function
CreateCaret (Win32)

BOOL CreateCaret(hwnd, hbmp, nWidth, nHeight)

HWND hwnd;	/* handle of owner window	*/
HBITMAP hbmp;	/* handle of bitmap for caret shape	*/
int nWidth;	/* caret width	*/
int nHeight;	/* caret height	*/

The CreateCaret function creates a new shape for the system caret and assigns ownership of the caret to the given window. The caret shape can be a line, a block, or a bitmap.

Parameter	Description

hwnd	Identifies the window that owns the caret.

hbmp	Identifies the bitmap that defines the caret shape. If this parameter is NULL, the caret is solid. If this parameter is 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 hbmp 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 NULL, the width is set to the system-defined window border width. If hbmp is a bitmap handle, CreateCaret ignores this parameter.

nHeight	Specifies the height, in logical units, of the caret. If this parameter is NULL, the height is set to the system-defined window border height. If hbmp is a bitmap handle, CreateCaret ignores this parameter.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


CreateCursor function
CreateCursor (Win32)

HCURSOR CreateCursor(hinst, xHotSpot, yHotSpot, nWidth, nHeight, pvANDplane, pvXORplane)

HINSTANCE hinst;	/* handle of 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;	/* address of AND bitmask array	*/
CONST VOID *pvXORplane;	/* address of XOR bitmask array	*/

The CreateCursor function creates a cursor having the specified size, bit patterns, and hot spot.

Parameter	Description

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.

Returns

If the function succeeds, the return value identifies the cursor; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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


CreateDialog function
CreateDialog (Win32)

HWND CreateDialog(hinst, lpszTemplate, hwndOwner, dlgprc)

HANDLE hinst;	/* handle of application instance	*/
LPCTSTR lpszTemplate;	/* identifies dialog box template name	*/
HWND hwndOwner;	/* handle of owner window	*/
DLGPROC dlgprc;	/* address of dialog box procedure	*/

The CreateDialog function creates a modeless dialog box from a dialog box template resource.

Parameter	Description

hinst	Identifies an instance of the module whose executable file contains the dialog box template.

lpszTemplate	Identifies the dialog box template. This parameter is either the address of 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.

hwndOwner	Identifies the window that owns the dialog box.

dlgprc	Points to the dialog box procedure. For more information about the dialog box procedure, see the description of the DialogProc callback function.

Returns

If the function succeeds, the return value is the handle of the dialog box; otherwise, it is NULL.

Comments

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

See Also

CreateDialogIndirect, CreateDialogIndirectParam, CreateDialogParam, CreateWindowEx, DestroyWindow, DialogBox, DialogProc, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDialogIndirect function
CreateDialogIndirect (Win32)

HWND CreateDialogIndirect(hinst, lpTemplate, hwndOwner, dlgprc)

HANDLE hinst;	/* handle of application instance	*/
LPCDLGTEMPLATE lpTemplate;	/* address of dialog box template	*/
HWND hwndOwner;	/* handle of owner window	*/
DLGPROC dlgprc;	/* address of dialog box procedure	*/

The CreateDialogIndirect function creates a modeless dialog box from a dialog box template in memory.

Parameter	Description

hinst	Identifies the instance of the module that creates the dialog box.

lpTemplate	Points to a global memory object that contains a dialog box template used to create the dialog box. This template is in the form of a DLGTEMPLATE structure followed by one or more DLGITEMTEMPLATE structures.

hwndOwner	Identifies the window that owns the dialog box.

dlgprc	Points to the dialog box procedure. For more information about the dialog box procedure, see the description of the DialogProc callback function.

Returns

If the function succeeds, the return value is the window handle of the dialog box; otherwise, it is NULL.

Comments

The CreateDialogIndirect function uses the CreateWindowEx function to create the dialog box. CreateDialogIndirect 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, CreateDialogIndirect returns the window handle of the dialog box.

After CreateDialogIndirect 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.

See Also

CreateDialog, CreateDialogIndirectParam, CreateDialogParam, CreateWindowEx, DestroyWindow, DialogProc, ShowWindow, DLGTEMPLATE, DLGITEMTEMPLATE, WM_INITDIALOG, WM_SETFONT


CreateDialogIndirectParam function
CreateDialogIndirectParam (Win32)

HWND CreateDialogIndirectParam(hinst, lpTemplate, hwndOwner, dlgprc, lParamInit)

HINSTANCE hinst;	/* handle of application instance	*/
LPCDLGTEMPLATE lpTemplate;	/* address of dialog box template	*/
HWND hwndOwner;	/* handle of owner window	*/
DLGPROC dlgprc;	/* address of dialog box procedure	*/
LPARAM lParamInit;	/* initialization value	*/

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.

Parameter	Description

hinst	Identifies the instance of the module that will create the dialog box.

lpTemplate	Points to a global memory object that contains a dialog box template used to create the dialog box. This template is in the form of a DLGTEMPLATE structure followed by one or more DLGITEMTEMPLATE structures.

hwndOwner	Identifies the window that owns the dialog box.

dlgprc	Points to the dialog box procedure. For more information about the dialog box procedure, see the description of the DialogProc callback function.

lParamInit	Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Returns

If the function succeeds, the return value is the window handle of the dialog box; otherwise, it is NULL.

Comments

The CreateDialogIndirectParam function uses the CreateWindowEx function to create the dialog box. CreateDialogIndirectParam 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, CreateDialogIndirectParam returns the window handle of the dialog box.

After CreateDialogIndirectParam 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.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogParam, CreateWindowEx, DestroyWindow, DialogProc, ShowWindow, DLGTEMPLATE, DLGITEMTEMPLATE, WM_INITDIALOG, WM_SETFONT


CreateDialogParam function
CreateDialogParam (Win32)

HWND CreateDialogParam(hinst, lpszTemplate, hwndOwner, dlgprc, lParamInit)

HINSTANCE hinst;	/* handle of application instance	*/
LPCTSTR lpszTemplate;	/* identifies dialog box template	*/
HWND hwndOwner;	/* handle of owner window	*/
DLGPROC dlgprc;	/* address of dialog box procedure	*/
LPARAM lParamInit;	/* initialization value	*/

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 WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

Parameter	Description

hinst	Identifies an instance of the module whose executable file contains the dialog box template.

lpszTemplate	Identifies the dialog box template. This parameter is either the address of 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.

hwndOwner	Identifies the window that owns the dialog box.

dlgprc	Points to the dialog box procedure. For more information about the dialog box procedure, see the description of the DialogProc callback function.

lParamInit	Specifies the value to pass to the dialog box procedure in the lParam parameter in the WM_INITDIALOG message.

Returns

If the function succeeds, the return value is the window handle of the dialog box; otherwise, it is NULL.

Comments

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.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, CreateWindowEx, DestroyWindow, DialogProc, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateIcon function
CreateIcon (Win32)

HICON CreateIcon(hinst, nWidth, nHeight, cPlanes, cBitsPixel, lpbANDbits, lpbXORbits)

HINSTANCE hinst;	/* handle of 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;	/* address of AND bitmask array	*/
CONST BYTE *lpbXORbits;	/* address of XOR bitmask array	*/

The CreateIcon function creates an icon that has the specified size, colors, and bit patterns.

Parameter	Description

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

Returns

If the function succeeds, the return value is the handle of an icon; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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

Before closing, an application must call the DestroyIcon function to free system resources associated with the icon.

See Also

DestroyIcon, GetSystemMetrics


CreateIconFromResource function
CreateIconFromResource (Win32)

HICON CreateIconFromResource(pbIconBits, cbIconBits, fIcon, dwVersion)

PBYTE pbIconBits;	/* address of icon or cursor bits	*/
DWORD cbIconBits;	/* number of bytes in bit buffer	*/
BOOL fIcon;	/* icon or cursor flag	*/
DWORD dwVersion;	/* Windows format version	*/

The CreateIconFromResource function creates an icon or cursor from resource bits describing the icon.

Parameter	Description

pbIconBits	Points to a buffer containing the icon or cursor resource bits. These bits are typically loaded by calls to the LookupIconIdFromDirectory 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 applications use the Windows 3.x format for icons and cursors.

Returns

If the function succeeds, the return value is the handle of the icon or cursor; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

The CreateIconFromResource, CreateIconIndirect, GetIconInfo, and LookupIconIdFromDirectory functions allow shell applications and icon browsers to examine and use resources from throughout the system.

See Also

CreateIconIndirect, GetIconInfo, LookupIconIdFromDirectory


CreateIconIndirect function
CreateIconIndirect (Win32)

HICON CreateIconIndirect(pici)

PICONINFO pici;	/* address of icon information structure	*/

The CreateIconIndirect function creates an icon or cursor from an ICONINFO structure.

Parameter	Description

pici	Points to an ICONINFO structure the function uses to create the icon or cursor.

Returns

If the function succeeds, the return value is the handle of the icon or cursor that is created; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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.

See Also

CreateIcon, CreateIconFromResource, DestroyIcon, DrawIcon, GetIconInfo, LoadIcon, LookupIconIdFromDirectory, ICONINFO


CreateMDIWindow function
CreateMDIWindow (Win32)

HWND CreateMDIWindow(lpszClassName, lpszWindowName, dwStyle, x, y, nWidth, nHeight, hwndParent, hinst, lParam)

LPTSTR lpszClassName;	/* address of registered child class name	*/
LPTSTR lpszWindowName;	/* address of 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 of parent window (MDI client)	*/
HINSTANCE hinst;	/* handle of application instance	*/
LPARAM lParam;	/* application-defined value	*/

The CreateMDIWindow function creates a multiple document interface (MDI) child window.

Parameter	Description

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

lpszWindowName	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	Description

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.

hinst	Identifies the instance of the application creating the MDI child window.

lParam	Specifies an application-defined value.

Returns

If the function succeeds, the return value is the handle of the created window; otherwise, it is NULL.

Comments

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.

See Also

WM_MDICREATE


CreateMenu function
CreateMenu (Win32)

HMENU CreateMenu(VOID)

The CreateMenu function creates a menu. The menu is initially empty, but it can be filled with menu items by using the AppendMenu and InsertMenu functions.

Returns

If the function succeeds, the return value is the handle of the newly created menu; otherwise, it is NULL.

Comments

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.

See Also

AppendMenu, DestroyMenu, InsertMenu, SetMenu


CreatePopupMenu function
CreatePopupMenu (Win32)

HMENU CreatePopupMenu(VOID)

The CreatePopupMenu function creates a pop-up menu. The menu is initially empty, but it can be filled with menu items by using the AppendMenu and InsertMenu functions.

Returns

If the function succeeds, the return value is the handle of the newly created pop-up menu; otherwise, it is NULL.

Comments

The application can add the pop-up menu to an existing menu or pop-up menu, or it can display and track selections on the pop-up menu by calling the TrackPopupMenu function.

Resources associated with a pop-up menu that is assigned to a window are freed automatically. If the pop-up 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.

See Also

AppendMenu, CreateMenu, InsertMenu, SetMenu, TrackPopupMenu


CreateWindow function
CreateWindow (Win32)

HWND CreateWindow(lpszClassName, lpszWindowName, dwStyle, x, y, nWidth, nHeight, hwndParent, hmenu, hinst, lpvParam)

LPCTSTR lpszClassName;	/* address of registered class name	*/
LPCTSTR lpszWindowName;	/* address of 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 of parent or owner window	*/
HMENU hmenu;	/* handle of menu, or child-window identifier	*/
HANDLE hinst;	/* handle of application instance	*/
LPVOID lpvParam;	/* address of window-creation data	*/

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.

Parameter	Description

lpszClassName	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 lpszClassName; the high-order word must be zero.

If lpszClassName 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 Comments section.

lpszWindowName	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 Comments 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, the nWidth and nHeight parameters 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.

hinst	Identifies the instance of the module to be associated with the window.

lpvParam	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, lpvParam must point to a CLIENTCREATESTRUCT structure.

Returns

If the function succeeds, the return value is the handle of the new window; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

Before returning, the CreateWindow function sends a WM_CREATE message to the window procedure.

For overlapped, pop-up, and child windows, the CreateWindow function 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 the lpszWindowName parameter is displayed in the title bar. When using CreateWindow to create controls, such as buttons, check boxes, and static controls, use the lpszWindowName parameter to specify the text of the control.

The following predefined control classes can be specified in the lpszClassName parameter:

Class	Meaning

BUTTON	Designates a small rectangular child window that represents a button the user can turn on or off by clicking. 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; can use the mouse to move the cursor, select characters to be replaced, or position the cursor for inserting characters; or can 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. This control is used 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. A vertical or horizontal scroll bar with a list box is used 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. The WS_HSCROLL and WS_VSCROLL styles are used 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 and can be used 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. This style is used with the WS_CHILD style only.

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 user can change the keyboard focus from one control in the group to the next by using the direction keys. All controls defined with the WS_GROUP style after the first control belong to the same group. The next control with the WS_GROUP style ends the group and starts the next group.

WS_HSCROLL	Creates a window that has a horizontal scroll bar.

WS_MAXIMIZE	Creates a window that is initially maximized.

WS_MAXIMIZEBOX	Creates a window that has a Maximize button.

WS_MINIMIZE	Creates a window that is initially minimized.

WS_MINIMIZEBOX	Creates a window that has a Minimize button.

WS_OVERLAPPED	Creates an overlapped window. An overlapped window has a title bar and a border.

WS_OVERLAPPEDWINDOW	Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles.

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 System menu (also known as Control menu) visible.

WS_SYSMENU	Creates a window that has a System-menu box in 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.

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

BS_AUTOCHECKBOX	Creates a button that is the same as a check box, except that an X appears in the check box when the user selects the box; the X disappears the next time the user selects the box.

BS_AUTORADIOBUTTON	Creates a button that is the same as a radio button, except that when the user selects it, the button automatically highlights itself and removes the selection from any other buttons in the same group.

BS_CHECKBOX	Creates a small empty square, with text displayed to its right, unless this style is combined with the BS_LEFTTEXT style.

BS_DEFPUSHBUTTON	Creates a button that has a heavy black border. The user can select this button by pressing the ENTER key. 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.

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_PUSHBOX	Unsupported. Applications should use BS_PUSHBUTTON instead.

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 that has text displayed to its right, unless this style is combined with the BS_LEFTTEXT style. Use radio buttons for groups of related but mutually exclusive choices.

BS_USERBUTTON	Obsolete. Applications should use BS_OWNERDRAW instead.

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_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 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 AnsiToOem 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 and 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.

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. Edit controls without scroll bars scroll as described in the previous two 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_OEMCONVERT	Converts text entered in the edit control 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_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 CreateWindow 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 specified by the CreateWindow parameters.

SBS_LEFTALIGN

Aligns the left edge of the scroll bar with the left edge of the rectangle defined by the CreateWindow parameters. 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 CreateWindow parameters. 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 CreateWindow parameters.

SBS_SIZEBOXBOTTOMRIGHTALIGN

Aligns the lower right corner of the size box with the lower right corner of the rectangle specified by the CreateWindow parameters. 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 CreateWindow parameters. The size box has the default size for system size boxes. Use this style with the SBS_SIZEBOX style.

SBS_TOPALIGN

Aligns the top edge of the scroll bar with the top edge of the rectangle defined by the CreateWindow parameters. 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 CreateWindow parameters.

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_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 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 centered line.

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_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_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_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_ABSALIGN	Indicates that the coordinates of the dialog box are screen coordinates; otherwise, Windows assumes they are client coordinates.

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_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 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	Applies to Windows NT only. 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.

See Also

CreateDialog, CreateWindowEx, DialogBox, MessageBox, CREATESTRUCT, CLIENTCREATESTRUCT


CreateWindowEx function
CreateWindowEx (Win32)

HWND CreateWindowEx(dwExStyle, lpszClassName, lpszWindowName, dwStyle, x, y, nWidth, nHeight, hwndParent, hmenu, hinst, lpvParam)

DWORD dwExStyle;	/* extended window style	*/
LPCTSTR lpszClassName;	/* address of registered class name	*/
LPCTSTR lpszWindowName;	/* address of 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 of parent or owner window	*/
HMENU hmenu;	/* handle of menu, or child-window identifier	*/
HINSTANCE hinst;	/* handle of application instance	*/
LPVOID lpvParam;	/* address of window-creation data	*/

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 the description of the CreateWindow function.

Parameter	Description

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_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_NOPARENTNOTIFY	Specifies that a child window created this style does not send the WM_PARENTNOTIFY message to its parent window when it is created or destroyed.

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.

lpszClassName	Points to a null-terminated string, or is an integer atom. If lpszClassName 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 lpszClassName; the high-order word must be zero.

If lpszClassName 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.

lpszWindowName	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 the description of the CreateWindow function.

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 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-coordinates 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, 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.

hinst	Identifies the instance of the module to be associated with the window.

lpvParam	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, lpvParam must point to a CLIENTCREATESTRUCT structure.

Returns

If the function succeeds, the return value is the handle of the new window; otherwise, it is NULL.

Comments

The CreateWindowEx function sends WM_NCCREATE, WM_NCCALCSIZE, and WM_CREATE messages to the window being created.

See Also

CreateWindow, SetWindowPos, CREATESTRUCT


DefDlgProc function
DefDlgProc (Win32)

LRESULT DefDlgProc(hwndDlg, uMsg, wParam, lParam)

HWND hwndDlg;	/* handle of dialog box	*/
UINT uMsg;	/* message	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The DefDlgProc function carries out default message processing for a window procedure belonging to an application-defined dialog box class.

Parameter	Description

hwndDlg	Identifies the dialog box.

uMsg	Specifies the message number.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

The return value specifies the result of the message processing and depends on the message sent.

Comments

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 this function instead of the DefWindowProc 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 the WNDCLASS structure for a custom dialog box class must be set to at least DLGWINDOWEXTRA.

DefDlgProc must not be called by a dialog box procedure; doing so results in recursive execution.

See Also

DefWindowProc, GetClassInfo, RegisterClass, WNDCLASS


DeferWindowPos function
DeferWindowPos (Win32)

HDWP DeferWindowPos(hdwp, hwnd, hwndInsertAfter, x, y, cx, cy, dwFlags)

HDWP hdwp;	/* handle of internal structure	*/
HWND hwnd;	/* handle of window to position	*/
HWND hwndInsertAfter;	/* placement-order handle	*/
int x;	/* horizontal position	*/
int y;	/* vertical position	*/
int cx;	/* width	*/
int cy;	/* height	*/
UINT dwFlags;	/* window-positioning flags	*/

The DeferWindowPos function updates the specified multiple-window-position structure for the given window. The function then returns the handle of 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.

Parameter	Description

hdwp	Identifies a multiple-window-position structure that contains size and position information for one or more windows. This structure is returned by the BeginDeferWindowPos function or by the most recent call to the DeferWindowPos function.

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

dwFlags	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_HIDEWINDOW	Hides the window.

SWP_NOACTIVATE	Does not activate the window.

SWP_NOMOVE	Retains the current position (ignores the x and y parameters).

SWP_NOREDRAW	Does not redraw changes. If this flag is set, no repainting 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 needs to be redrawn.

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.

Returns

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.

Comments

If a call to DeferWindowPos fails, the application should abandon the window-positioning operation and not call the EndDeferWindowPos function.

If the SWP_NOZORDER flag 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 the HWND_TOP flag, Windows places the hwnd window at the top of the Z order. If hwndInsertAfter is set to the HWND_BOTTOM flag, Windows places the hwnd window at the bottom of the Z order.

If either the SWP_SHOWWINDOW or the SWP_HIDEWINDOW flag is set, DeferWindowPos will not move or size windows. To show or hide windows, use the ShowWindow function.

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


DefFrameProc function
DefFrameProc (Win32)

LRESULT DefFrameProc(hwndFrame, hwndMDIClient, uMsg, wParam, lParam)

HWND hwndFrame;	/* handle of MDI frame window	*/
HWND hwndMDIClient;	/* handle of MDI client window	*/
UINT uMsg;	/* message	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

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.

Parameter	Description

hwndFrame	Identifies the MDI frame window.

hwndMDIClient	Identifies the MDI client window.

uMsg	Specifies the message to be processed.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

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.

Comments

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 System 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


DefMDIChildProc function
DefMDIChildProc (Win32)

LRESULT DefMDIChildProc(hwndChild, uMsg, wParam, lParam)

HWND hwndChild;	/* handle of MDI child window	*/
UINT uMsg;	/* message	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

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 the DefWindowProc function.

Parameter	Description

hwndChild	Identifies the MDI child window.

uMsg	Specifies the message to be processed.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

The return value specifies the result of the message processing and depends on the message.

Comments

The DefMDIChildProc function assumes that the parent window of the MDI child window identified by the hwndChild 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 System menu commands: SC_NEXTWINDOW, SC_PREVWINDOW, SC_MOVE, SC_SIZE, and SC_MAXIMIZE.

See Also

DefFrameProc, DefWindowProc


DefWindowProc function
DefWindowProc (Win32)

LRESULT DefWindowProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;	/* handle of window	*/
UINT uMsg;	/* message identifier	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

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.

Parameter	Description

hwnd	Identifies the window procedure that received the message.

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.

Returns

The return value is the result of the message processing and depends on the message.

See Also

CallWindowProc, DefDlgProc, WindowProc


DeleteMenu function
DeleteMenu (Win32)

BOOL DeleteMenu(hmenu, uItem, fuFlags)

HMENU hmenu;	/* handle of menu	*/
UINT uItem;	/* menu item identifier or position	*/
UINT fuFlags;	/* menu item flag	*/

The DeleteMenu function deletes an item from the given menu. If the menu item invokes a pop-up menu, this function destroys the handle of the pop-up menu and frees the memory used by the pop-up menu.

Parameter	Description

hmenu	Identifies the menu to be changed.

uItem	Specifies the menu item to be deleted, as determined by the fuFlags parameter.

fuFlags	Specifies how the uItem parameter is interpreted. This parameter must be one of the following values:

Value	Meaning

MF_BYCOMMAND	Indicates that the uItem 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 uItem parameter gives the zero-based relative position of the menu item.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


DestroyAcceleratorTable function
DestroyAcceleratorTable (Win32)

BOOL DestroyAcceleratorTable(haccl)

HACCEL haccl;	/* handle of accelerator table	*/

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.

Parameter	Description

haccl	Identifies the accelerator table to be destroyed. This handle must have been created by a previous call to the CreateAcceleratorTable function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CopyAcceleratorTable, CreateAcceleratorTable, LoadAccelerators, TranslateAccelerator


DestroyCaret function
DestroyCaret (Win32)

BOOL DestroyCaret(VOID)

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
DestroyCursor (Win32)

BOOL DestroyCursor(hcur)

HCURSOR hcur;	/* handle of cursor to destroy	*/

The DestroyCursor function destroys a cursor created by the CreateCursor function and frees any memory the cursor occupied. Do not use it to destroy a cursor that was not created with the CreateCursor function.

Parameter	Description

hcur	Identifies the cursor to be destroyed. The cursor must not be in use.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CreateCursor


DestroyIcon function
DestroyIcon (Win32)

BOOL DestroyIcon(hicon)

HICON hicon;	/* handle of icon to destroy	*/

The DestroyIcon function destroys an icon created by the CreateIcon function and frees any memory the icon occupied. Do not use DestroyIcon to destroy an icon that was not created by the CreateIcon function.

Parameter	Description

hicon	Identifies the icon to be destroyed. The icon must not be in use.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CreateIcon


DestroyMenu function
DestroyMenu (Win32)

BOOL DestroyMenu(hmenu)

HMENU hmenu;	/* handle of menu to destroy	*/

The DestroyMenu function destroys the given menu and frees any memory that the menu occupies.

Parameter	Description

hmenu	Identifies the menu to be destroyed.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Before closing, an application must use this 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, ModifyMenu, RemoveMenu


DestroyWindow function
DestroyWindow (Win32)

BOOL DestroyWindow(hwnd)

HWND hwnd;	/* handle of window to destroy	*/

The DestroyWindow function destroys the given 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 given 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.

The DestroyWindow function also destroys modeless dialog boxes created by the CreateDialog function.

Parameter	Description

hwnd	Identifies the window to be destroyed.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

A thread cannot use the DestroyWindow function 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


DialogBox function
DialogBox (Win32)

int DialogBox(hinst, lpszTemplate, hwndOwner, dlgprc)

HANDLE hinst;	/* handle of application instance	*/
LPCTSTR lpszTemplate;	/* identifies dialog box template	*/
HWND hwndOwner;	/* handle of owner window	*/
DLGPROC dlgprc;	/* address of dialog box procedure	*/

The DialogBox function creates a modal dialog box from a dialog box template resource. DialogBox does not return control until the given callback function terminates the modal dialog box by calling the EndDialog function.

Parameter	Description

hinst	Identifies an instance of the module whose executable file contains the dialog box template.

lpszTemplate	Identifies the dialog box template. This parameter is either the address of 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.

hwndOwner	Identifies the window that owns the dialog box.

dlgprc	Points to the dialog box procedure. For more information about the dialog box procedure, see the description of the DialogProc callback function.

Returns

If the function succeeds, the return value is the nResult parameter in the call to the EndDialog function used to terminate the dialog box; otherwise, the return value is -1.

Comments

The DialogBoxIndirect function 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 finally 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 given by the dialog procedure when it called EndDialog.

See Also

CreateDialog, CreateWindowEx, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, DialogProc, EndDialog, WM_INITDIALOG, WM_SETFONT


DialogBoxIndirect function
DialogBoxIndirect (Win32)

int DialogBoxIndirect(hinst, hTemplate, hwndOwner, dlgprc)

HANDLE hinst;	/* handle of application instance	*/
LPDLGTEMPLATE hTemplate;	/* identifies dialog box template	*/
HWND hwndOwner;	/* handle of owner window	*/
DLGPROC dlgprc;	/* address of dialog box procedure	*/

The DialogBoxIndirect function creates a modal dialog box from a dialog box template in memory. The DialogBoxIndirect function does not return control until the given callback function terminates the modal dialog box by calling the EndDialog function.

Parameter	Description

hinst	Identifies the instance of the module that creates the dialog box.

hTemplate	Identifies a global memory object that contains a dialog box template used to create the dialog box. This template is in the form of a DLGTEMPLATE structure followed by one or more DLGITEMTEMPLATE structures. In Windows NT, this parameter can be either the handle to the global memory object or the address of the object.

hwndOwner	Identifies the window that owns the dialog box.

dlgprc	Points to the dialog box procedure. For more information about the dialog box procedure, see the description of the DialogProc callback function.

Returns

If the function succeeds, the return value is the nResult parameter given in the call to the EndDialog function used to terminate the dialog box; otherwise, the return value is -1.

Comments

The DialogBoxIndirect function uses the CreateWindowEx function to create the dialog box. DialogBoxIndirect 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 finally 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 given by the dialog procedure when it called EndDialog.

See Also

DialogBox, DialogBoxIndirectParam, DialogBoxParam, DialogProc, EndDialog, DLGTEMPLATE, DLGITEMTEMPLATE, WM_INITDIALOG, WM_SETFONT


DialogBoxIndirectParam function
DialogBoxIndirectParam (Win32)

int DialogBoxIndirectParam(hinst, hTemplate, hwndOwner, dlgprc, lParamInit)

HINSTANCE hinst;	/* handle of application instance	*/
LPCDLGTEMPLATE hTemplate;	/* identifies dialog box template	*/
HWND hwndOwner;	/* handle of owner window	*/
DLGPROC dlgprc;	/* address of dialog box procedure	*/
LPARAM lParamInit;	/* initialization value	*/

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.

Parameter	Description

hinst	Identifies the instance of the module that creates the dialog box.

hTemplate	Identifies a global memory object that contains a dialog box template used to create the dialog box. This template is in the form of a DLGTEMPLATE structure followed by one or more DLGITEMTEMPLATE structures. In Windows NT, this parameter can be either the handle of the global memory object or the address of the object.

hwndOwner	Identifies the window that owns the dialog box.

dlgprc	Points to the dialog box procedure. For more information about the dialog box procedure, see the description of the DialogProc callback function.

lParamInit	Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Returns

If the function succeeds, the return value is the nResult parameter given in the call to the EndDialog function used to terminate the dialog box; otherwise, the return value is -1.

Comments

The DialogBoxIndirectParam function uses the CreateWindowEx function to create the dialog box. DialogBoxIndirectParam 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 finally 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 given by the dialog procedure when it called EndDialog.

See Also

DialogBox, DialogBoxIndirect, DialogBoxParam, DialogProc, EndDialog, DLGTEMPLATE, DLGITEMTEMPLATE, WM_INITDIALOG, WM_SETFONT


DialogBoxParam function
DialogBoxParam (Win32)

int DialogBoxParam(hinst, lpszTemplate, hwndOwner, dlgprc, lParamInit)

HINSTANCE hinst;	/* handle of application instance	*/
LPCTSTR lpszTemplate;	/* identifies dialog box template	*/
HWND hwndOwner;	/* handle of owner window	*/
DLGPROC dlgprc;	/* address of dialog box procedure	*/
LPARAM lParamInit;	/* initialization value	*/

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.

Parameter	Description

hinst	Identifies an instance of the module whose executable file contains the dialog box template.

lpszTemplate	Identifies the dialog box template. This parameter is either the address of 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.

hwndOwner	Identifies the window that owns the dialog box.

dlgprc	Points to the dialog box procedure. For more information about the dialog box procedure, see the description of the DialogProc callback function.

lParamInit	Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Returns

If the function succeeds, the return value is the value of the nResult parameter given in the call to the EndDialog function used to terminate the dialog box; otherwise, the return value is -1.

Comments

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 finally 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 given by the dialog procedure when it called EndDialog.

See Also

DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogProc, EndDialog, WM_INITDIALOG, WM_SETFONT


DispatchMessage function
DispatchMessage (Win32)

LONG DispatchMessage(lpmsg)

CONST MSG *lpmsg;	/* address of structure with message	*/

The DispatchMessage function dispatches a message to a window procedure. It is typically used to dispatch a message retrieved by the GetMessage function.

Parameter	Description

lpmsg	Points to an MSG structure that contains the message.

Returns

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.

Comments

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, PeekMessage, PostAppMessage, PostMessage, TranslateMessage, MSG, WM_TIMER


DlgDirList function
DlgDirList (Win32)

int DlgDirList(hwndDlg, lpszPath, idListBox, idStaticPath, uFileType)

HWND hwndDlg;	/* handle of dialog box with list box	*/
LPTSTR lpszPath;	/* address of path or filename string	*/
int idListBox;	/* identifier of list box	*/
int idStaticPath;	/* identifier of static control	*/
UINT uFileType;	/* file attributes to display	*/

The DlgDirList function fills the specified list box with the names of all files matching the specified path or filename.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the list box.

lpszPath	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, see the Comments section.

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

idStaticPath	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, the DlgDirList function sends messages directly to the dialog box procedure.

Returns

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.

Comments

If you specify a zero-length string for the lpszPath parameter or if you specify only a directory name with no filename, the string will be changed to *.*

The lpszPath 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 the lpszPath parameter 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 idStaticPath parameter is also updated with the new drive or directory name, or both.

After the list box is filled, DlgDirList updates lpszPath 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, LB_DIR, LB_RESETCONTENT


DlgDirListComboBox function
DlgDirListComboBox (Win32)

int DlgDirListComboBox(hwndDlg, lpPathSpec, nIDComboBox, nIDStaticPath, uFiletype)

HWND hwndDlg;	/* handle of dialog box with combo box	*/
LPTSTR lpPathSpec;	/* address of path or filename string	*/
int nIDComboBox;	/* identifier of combo box	*/
int nIDStaticPath;	/* identifier of static control	*/
UINT uFiletype;	/* file attributes to display	*/

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.

Parameter	Description

hwndDlg	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 lpPathSpec string.

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	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, the DlgDirList function sends messages directly to the dialog box procedure.

Returns

If the function succeeds, the return value is nonzero; otherwise, it is zero. For example, if the string specified by lpPathSpec is not a valid path, the function fails. To get extended error information, use the GetLastError function.

Comments

If the lpszPath parameter points to a zero-length string or to a string specifying a drive, directory, or both--but no filename--the filename *.* is assumed.

See Also

DlgDirList, DlgDirSelectEx, DlgDirSelectComboBoxEx


DlgDirSelectComboBoxEx function
DlgDirSelectComboBoxEx (Win32)

BOOL DlgDirSelectComboBoxEx(hwndDlg, lpszPath, cchString, nIDComboBox)

HWND hwndDlg;	/* handle of dialog box with list box	*/
LPTSTR lpszPath;	/* address of buffer for path string	*/
int cchString;	/* number of characters in path string	*/
int nIDComboBox;	/* identifier of combo box	*/

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.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the combo box.

lpszPath	Points to the buffer that is to receive the selected path.

cchString	Specifies the length, in characters, of the buffer pointed to by the lpszPath parameter.

nIDComboBox	Specifies the integer ID of the combo box control in the dialog box.

Returns

If the current selection is a directory name, the return value is nonzero; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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 the lpszPath parameter 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

DlgDirSelectEx, DlgDirListComboBox


DlgDirSelectEx function
DlgDirSelectEx (Win32)

BOOL DlgDirSelectEx(hwndDlg, lpString, cchString, nIDListBox)

HWND hwndDlg;	/* handle of dialog box with list box	*/
LPTSTR lpString;	/* address of buffer for path string	*/
int cchString;	/* number of characters in path string	*/
int nIDListBox;	/* identifier of list box	*/

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.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the list box.

lpString	Points to a buffer that is to receive the selected path.

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

Returns

If the current selection is a directory name, the return value is nonzero; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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 DlgDirSelectEx 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, DlgDirSelectComboBoxEx, DlgDirListComboBox, LB_GETCURSEL, LB_GETTEXT


DrawFocusRect function
DrawFocusRect (Win32)

BOOL DrawFocusRect(hdc, lprc)

HDC hdc;	/* handle of device context	*/
CONST RECT *lprc;	/* address of structure with rectangle	*/

The DrawFocusRect function draws a rectangle in the style used to indicate that the rectangle has the focus.

Parameter	Description

hdc	Identifies the device context.

lprc	Points to a RECT structure that specifies the logical coordinates of the rectangle.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Because DrawFocusRect is an XOR function, calling it a second time with the same rectangle removes the rectangle from the screen.

The rectangle this function draws 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 to draw the rectangle in the new position.

See Also

FrameRect, RECT


DrawIcon function
DrawIcon (Win32)

BOOL DrawIcon(hdc, X, Y, hicon)

HDC hdc;	/* handle of device context	*/
int X;	/* x-coordinate of upper left corner	*/
int Y;	/* y-coordinate of upper left corner	*/
HICON hicon;	/* handle of icon to draw	*/

The DrawIcon function draws an icon in the client area of the window of the given device context.

Parameter	Description

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. The icon resource must have been previously loaded by using the LoadIcon function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, LoadIcon, OpenIcon


DrawMenuBar function
DrawMenuBar (Win32)

BOOL DrawMenuBar(hwnd)

HWND hwnd;	/* handle of window with menu bar to redraw	*/

The DrawMenuBar function redraws the menu bar of the given window. If the menu bar changes after Windows has created the window, this function must be called to draw the changed menu bar.

Parameter	Description

hwnd	Identifies the window whose menu bar needs redrawing.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

AppendMenu, DeleteMenu, InsertMenu, ModifyMenu, RemoveMenu


DrawText function
DrawText (Win32)

int DrawText(hdc, lpszStr, cchStr, lprc, wFormat)

HDC hdc;	/* handle of device context	*/
LPCTSTR lpszStr;	/* address of string to draw	*/
int cchStr;	/* string length, in characters	*/
LPRECT lprc;	/* address of structure with formatting dimensions	*/
UINT wFormat;	/* text-drawing flags	*/

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

Parameter	Description

hdc	Identifies the device context.

lpszStr	Points to the string to be drawn. If the cchStr parameter is -1, the string must be null-terminated.

cchStr	Specifies the number of characters in the string. If cchStr is -1, then the lpszStr parameter is assumed to be a pointer to a null-terminated string and DrawText computes the character count automatically.

lprc	Points to a RECT structure that contains the rectangle (in logical coordinates) in which the text is to be formatted.

wFormat	Specifies the method of formatting the text. It can be any combination of the following values:

Value	Description

DT_BOTTOM	Bottom justifies text. 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 lprc 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.

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_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_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 wFormat parameter specify is 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 lprc 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.

Returns

If the function succeeds, the return value is the height of the text.

Comments

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 given 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


EmptyClipboard function
EmptyClipboard (Win32)

BOOL EmptyClipboard(VOID)

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Before calling the EmptyClipboard function, 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


EnableMenuItem function
EnableMenuItem (Win32)

BOOL EnableMenuItem(hmenu, uItem, fuFlags)

HMENU hmenu;	/* handle of menu	*/
UINT uItem;	/* menu item to enable, disable, or gray	*/
UINT fuFlags;	/* menu item flags	*/

The EnableMenuItem function enables, disables, or grays the given menu item.

Parameter	Description

hmenu	Identifies the menu.

uItem	Specifies the menu item to be enabled, disabled, or grayed, as determined by the fuFlags parameter. This parameter specifies an item in a menu bar or in a pop-up menu.

fuFlags	Specifies flags that control the interpretation of the uItem 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 the uItem 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 uItem parameter 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.

Returns

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.

Comments

For information about enabling or disabling input to a menu bar, see the WM_SYSCOMMAND message.

The CreateMenu, InsertMenu, ModifyMenu, and LoadMenuIndirect functions can also set the state (enabled, disabled, or grayed) of a menu item.

An application must use the MF_BYPOSITION flag to specify the correct menu handle. If the menu handle of 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 pop-up or nested pop-up menu by position, an application must specify the handle of the pop-up menu.

When an application specifies the MF_BYCOMMAND flag, Windows checks all pop-up menu items that are subordinate to the menu identified by the specified menu handle. Therefore, unless duplicate menu items are present, specifying the menu handle of the menu bar is sufficient.

See Also

CreateMenu, GetMenuItemID, InsertMenu, LoadMenuIndirect, ModifyMenu


EnableScrollBar function
EnableScrollBar (Win32)

BOOL EnableScrollBar(hwnd, fuSBFlags, fuArrowFlags)

HWND hwnd;	/* handle of window or scroll bar	*/
UINT fuSBFlags;	/* scroll bar type flag	*/
UINT fuArrowFlags;	/* scroll bar arrow flag	*/

The EnableScrollBar function enables or disables one or both scroll bar arrows.

Parameter	Description

hwnd	Identifies a window or a scroll bar control, depending on the value of the fuSBFlags parameter.

fuSBFlags	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 given window. The hwnd parameter must be the handle of the window.

SB_CTL	Identifies the scroll bar as a scroll bar control. The hwnd parameter must be the handle of the scroll bar control.

SB_HORZ	Enables or disables the arrows on the horizontal scroll bar associated with the given window. The hwnd parameter must be the handle of the window.

SB_VERT	Enables or disables the arrows on the vertical scroll bar associated with the given window. The hwnd parameter must be the handle of the window.

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_ENABLE_BOTH	Enables both arrows on a 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_RTDN	Disables the right arrow on a horizontal scroll bar or the down arrow of a vertical scroll bar.

ESB_DISABLE_BOTH	Disables both arrows on a scroll bar.

Returns

If the arrows are enabled or disabled as specified, the return value is TRUE. If the arrows are already in the requested state or an error occurs, the return value is FALSE.

See Also

ShowScrollBar


EnableWindow function
EnableWindow (Win32)

BOOL EnableWindow(hwnd, fEnable)

HWND hwnd;	/* handle of window	*/
BOOL fEnable;	/* flag for enabling or disabling input	*/

The EnableWindow function enables or disables mouse and keyboard input to the given 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.

Parameter	Description

hwnd	Identifies the window to be enabled or disabled.

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

Returns

If the window was previously disabled, the return value is TRUE: otherwise, the return value is FALSE. To get extended error information, use the GetLastError function.

Comments

If the enabled state of a window is changing, a WM_ENABLE message is sent before this 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 the EnableWindow function 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 access it.

See Also

IsWindowEnabled


EndDeferWindowPos function
EndDeferWindowPos (Win32)

BOOL EndDeferWindowPos(hdwp)

HDWP hdwp;	/* handle of internal structure	*/

The EndDeferWindowPos function simultaneously updates the position and size of one or more windows in a single screen-refreshing cycle.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

This function sends the WM_WINDOWPOSCHANGING and WM_WINDOWPOSCHANGED messages to each window identified in the internal structure.

See Also

BeginDeferWindowPos, DeferWindowPos, WM_WINDOWPOSCHANGING, WM_WINDOWPOSCHANGED


EndDialog function
EndDialog (Win32)

BOOL EndDialog(hwndDlg, nResult)

HWND hwndDlg;	/* handle of dialog box	*/
int nResult;	/* value to return	*/

The EndDialog function destroys a modal dialog box, causing the system to end any processing for the dialog box.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 given by nResult as the return value from the function that created the dialog box.

See Also

DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, WM_INITDIALOG


EndPaint function
EndPaint (Win32)

BOOL EndPaint(hwnd, lpPaint)

HWND hwnd;	/* handle of window	*/
CONST PAINTSTRUCT *lpPaint;	/* address of structure for paint data	*/

The EndPaint function marks the end of painting in the given window. This function is required for each call to the BeginPaint function, but only after painting is complete.

Parameter	Description

hwnd	Identifies the window that has been repainted.

lpPaint	Points to a PAINTSTRUCT structure that contains the painting information retrieved by BeginPaint.

Returns

This function always returns TRUE.

Comments

If the caret was hidden by BeginPaint, EndPaint restores the caret to the screen.

See Also

BeginPaint, PAINTSTRUCT


EnumChildWindows function
EnumChildWindows (Win32)

BOOL EnumChildWindows(hwndParent, wndenmprc, lParam)

HWND hwndParent;	/* handle of parent window	*/
WNDENUMPROC wndenmprc;	/* address of callback function	*/
LPARAM lParam;	/* application-defined value	*/

The EnumChildWindows function enumerates the child windows that belong to the given 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.

Parameter	Description

hwndParent	Identifies the parent window whose child windows are to be enumerated.

wndenmprc	Points to an application-defined callback function. For more information about the callback function, see the description of the EnumChildProc callback function.

lParam	Specifies a 32-bit application-defined value to be passed to the callback function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The EnumChildWindows function does not enumerate top-level windows owned by the given 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 GetWindow 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 function
EnumClipboardFormats (Win32)

UINT EnumClipboardFormats(uFormat)

UINT uFormat;	/* known clipboard format	*/

The EnumClipboardFormats function enumerates the formats currently available on the clipboard. On each call to this function, the uFormat parameter specifies an available clipboard format, and the function returns the next available format.

Parameter	Description

uFormat	Specifies a known available clipboard format. Zero is specified to retrieve the first format in the list.

Returns

If the function succeeds, the return value is the next available clipboard format after the specified format; otherwise, it is zero. To get extended error information, use the GetLastError function.

If there are no more available clipboard formats or the clipboard is not open, the return value is zero.

Comments

Before it enumerates the formats by using the EnumClipboardFormats function, an application must open the clipboard by using the OpenClipboard function.

EnumClipboardFormats enumerates the formats in the order they where placed on the clipboard. A window copying information to the clipboard should add clipboard objects in order, from the most descriptive clipboard format to the least descriptive. A window pasting information from the clipboard should retrieve the first format it can handle.

If any of the three text formats (CF_UNICODETEXT, CF_TEXT, and CF_OEMTEXT) have been placed on the clipboard, all three text formats are enumerated. If either of the two metafile formats (CF_ENHMETAFILE and CF_METAFILEPICT) have been placed on the clipboard, both metafile formats are enumerated.

See Also

CountClipboardFormats, OpenClipboard, RegisterClipboardFormat


EnumProps function
EnumProps (Win32)

int EnumProps(hwnd, lpEnumFunc)

HWND hwnd;	/* handle of window	*/
PROPENUMPROC lpEnumFunc;	/* address of callback function	*/

The EnumProps function enumerates all entries in the property list of the given 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.

Parameter	Description

hwnd	Identifies the window whose property list is to be enumerated.

lpEnumFunc	Points to the callback function. For more information, see the description of the PropEnumProc callback function.

Returns

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.

Comments

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, RemoveProp, SetProp


EnumPropsEx function
EnumPropsEx (Win32)

int EnumPropsEx(hwnd, lpEnumFunc, lParam)

HWND hwnd;	/* handle of window	*/
PROPENUMPROCEX lpEnumFunc;	/* address of callback function	*/
LPARAM lParam;	/* application-defined data	*/

The EnumPropsEx function enumerates all entries in the property list of the given 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.

Parameter	Description

hwnd	Identifies the window whose property list is to be enumerated.

lpEnumFunc	Points to the callback function. For more information, see the description of the PropEnumProcEx callback function.

lParam	Contains application-defined data to be passed to the callback function.

Returns

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.

Comments

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


EnumThreadWindows function
EnumThreadWindows (Win32)

BOOL EnumThreadWindows(dwThreadId, lpfn, lParam)

DWORD dwThreadId;	/* thread identifier	*/
WNDENUMPROC lpfn;	/* address of callback function	*/
LPARAM lParam;	/* application-defined value	*/

The EnumThreadWindows function enumerates all 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.

Parameter	Description

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 description of the EnumThreadWndProc callback function.

lParam	Specifies a 32-bit application-defined value to be passed to the callback function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

EnumChildWindows, EnumThreadWndProc, EnumWindows


EnumWindows function
EnumWindows (Win32)

BOOL EnumWindows(wndenmprc, lParam)

WNDENUMPROC wndenmprc;	/* address of callback function	*/
LPARAM lParam;	/* application-defined value	*/

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.

Parameter	Description

wndenmprc	Points to an application-defined callback function. For more information, see the description of the EnumWindowsProc callback function.

lParam	Specifies a 32-bit application-defined value to be passed to the callback function.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The EnumWindows function does not enumerate child windows.

This function is more reliable than calling GetWindow in a loop. An application that calls GetWindow to perform this task risks being caught in an infinite loop or referencing a handle of a window that has been destroyed.

See Also

EnumChildWindows, EnumWindowsProc


EqualRect function
EqualRect (Win32)

BOOL EqualRect(lprc1, lprc2)

CONST RECT *lprc1;	/* address of structure with first rectangle	*/
CONST RECT *lprc2;	/* address of structure with second rectangle	*/

The EqualRect function determines whether the two specified rectangles are equal by comparing the coordinates of their upper left and lower right corners.

Parameter	Description

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.

Returns

If the two rectangles are identical, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

IsRectEmpty, PtInRect, RECT


ExcludeUpdateRgn function
ExcludeUpdateRgn (Win32)

int ExcludeUpdateRgn(hdc, hwnd)

HDC hdc;	/* handle of device context	*/
HWND hwnd;	/* handle of window	*/

The ExcludeUpdateRgn function prevents drawing within invalid areas of a window by excluding an updated region in the window from a clipping region.

Parameter	Description

hdc	Identifies the device context associated with the clipping region.

hwnd	Identifies the window to be updated.

Returns

The return value specifies the complexity of the excluded region; it can be any one of the following values:

Value	Meaning

NULLREGION	Region is empty.

SIMPLEREGION	Region is a single rectangle.

COMPLEXREGION	Region consists of more than one rectangle.

ERROR	An error occurred.

See Also

BeginPaint, GetUpdateRect, GetUpdateRgn, UpdateWindow


ExitWindows function
ExitWindows (Win32)

BOOL ExitWindows(dwReserved, uReturnCode)

DWORD dwReserved;	/* reserved	*/
UINT uReserved;	/* reserved	*/

The ExitWindows function logs the current user off.

Parameter	Description

dwReserved	Reserved; must be zero.

uReserved	Reserved; must be zero.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The ExitWindows function asks applications if they want to terminate by sending the WM_QUERYENDSESSION message to the main window of all running applications. 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

ExitWindowsEx


ExitWindowsEx function
ExitWindowsEx (Win32)

BOOL ExitWindowsEx(fuOptions, dwReserved)

UINT fuOptions;	/* shutdown operation	*/
DWORD dwReserved;	/* reserved	*/

The ExitWindowsEx function either logs off, shuts down, or shuts down and restarts the system.

Parameter	Description

fuOptions	Specifies the type of shutdown. This parameter must be some combination of the following values:

Value	Action

EWX_FORCE	Forces processes to terminate. Instead of bringing up the "application not responding" dialog box for the user, this flag forces an application to terminate if it does not respond.

EWX_LOGOFF	Shuts down all processes running in the security context of the process that called the ExitWindowsEx function. It then logs the user off.

EWX_REBOOT	Shuts down the system and then restarts the system. The application must have the SE_SHUTDOWN_NAME privilege (For more information, see the Comments section).

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. The application must have the SE_SHUTDOWN_NAME privilege (For more information, see the Comments section).

dwReserved	Reserved. This parameter is ignored.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

This 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 flag 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 SetConsoleCtrlHandler. ExitWindowsEx sends these notification messages asynchronously; thus, an application cannot assume that the console notification messages have been handled when a call to ExitWindows returns.

See Also

ExitWindows, HandlerRoutine, SetConsoleCtrlHandler


FillRect function
FillRect (Win32)

int FillRect(hdc, lprc, hbr)

HDC hdc;	/* handle of device context	*/
CONST RECT *lprc;	/* address of structure with rectangle	*/
HBRUSH hbr;	/* handle of brush	*/

The FillRect function fills the specified rectangle by using the given brush. This function includes the left and top borders, but excludes the right and bottom borders of the rectangle.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The brush identified by hbr must have been created by using the CreateHatchBrush, CreatePatternBrush, or CreateSolidBrush function, or retrieved by using the GetStockObject function.

When filling the specified rectangle, the FillRect function does not include the rectangle's right and bottom sides. GDI fills a rectangle up to, but does not include, the right column and bottom row, regardless of the current mapping mode.

See Also

CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, GetStockObject, RECT


FindWindow function
FindWindow (Win32)

HWND FindWindow(lpszClass, lpszWindow)

LPCTSTR lpszClass;	/* address of class name	*/
LPCTSTR lpszWindow;	/* address of window name	*/

The FindWindow function retrieves the handle of the top-level window whose class name and window name match the specified strings. This function does not search child windows.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the handle of the window that has the specified class name and window name; otherwise, it is NULL. To get extended error information, use the GetLastError function.

See Also

EnumWindows, GetClassName


FlashWindow function
FlashWindow (Win32)

BOOL FlashWindow(hwnd, fInvert)

HWND hwnd;	/* handle of window to flash	*/
BOOL fInvert;	/* flash status	*/

The FlashWindow function flashes the given window once.

Parameter	Description

hwnd	Identifies the window to be flashed. The window can be either open or iconic.

fInvert	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 the fInvert parameter is TRUE. If the fInvert parameter is FALSE, the window is returned to its original state (either active or inactive).

Returns

The return value specifies the window's state before the call to the FlashWindow function. If the window was active before the call, it is TRUE; otherwise, it is FALSE.

Comments

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.

This function always returns TRUE for iconic windows. If the window is iconic, FlashWindow simply flashes the icon; the fInvert parameter is ignored for iconic windows.


FrameRect function
FrameRect (Win32)

int FrameRect(hdc, lprc, hbr)

HDC hdc;	/* handle of device context	*/
CONST RECT *lprc;	/* address of rectangle coordinates	*/
HBRUSH hbr;	/* handle of brush	*/

The FrameRect function draws a border around the specified rectangle by using the given brush. The width and height of the border are always one logical unit.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, RECT


FreeDDElParam function
FreeDDElParam (Win32)

BOOL FreeDDElParam(uMsg, lParam)

UINT uMsg;	/* posted DDE message	*/
LONG lParam;	/* lParam of message	*/

The FreeDDElParam function frees the memory specified by the lParam parameter of a posted dynamic data exchange (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.

Parameter	Description

uMsg	Specifies the posted DDE message.

lParam	Specifies the lParam parameter of the posted DDE message.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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


GetActiveWindow function
GetActiveWindow (Win32)

HWND GetActiveWindow(void)

The GetActiveWindow function retrieves the window handle of the active window associated with the thread that calls the function.

Returns

If the function succeeds, the return value is the handle of 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


GetAsyncKeyState function
GetAsyncKeyState (Win32)

SHORT GetAsyncKeyState(nVirtKey)

int nVirtKey;	/* virtual-key code	*/

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 the GetAsyncKeyState function.

Parameter	Description

nVirtKey	Specifies one of 256 possible virtual-key codes.

Returns

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 GetAsyncKeyState call. The return value is zero if a window in another thread or process currently has the keyboard focus.

Comments

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 state 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 in order 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 when using the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

For a complete table of virtual key codes, see Virtual Key Codes.

See Also

GetKeyState, GetKeyboardState, SetKeyboardState, MapVirtualKey


GetCapture function
GetCapture (Win32)

HWND GetCapture(VOID)

The GetCapture function retrieves the handle of the window (if any) that has captured the mouse. Only one window at any given time can capture the mouse; this window receives mouse input whether or not the cursor is within its borders.

Returns

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.

Comments

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 function
GetCaretBlinkTime (Win32)

UINT GetCaretBlinkTime(VOID)

The GetCaretBlinkTime function returns the elapsed time, in milliseconds, required to invert the caret's pixels.

Returns

The return value is the blink time, in milliseconds.

See Also

SetCaretBlinkTime


GetCaretPos function
GetCaretPos (Win32)

BOOL GetCaretPos(lpPoint)

LPPOINT lpPoint;	/* address of structure to receive coordinates	*/

The GetCaretPos function copies the caret's position, in client coordinates, to the specified POINT structure.

Parameter	Description

lpPoint	Points to the POINT structure that is to receive the client coordinates of the caret.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The caret position is always given in the client coordinates of the window that contains the caret.

See Also

SetCaretPos, POINT


GetClassInfo function
GetClassInfo (Win32)

BOOL GetClassInfo(hinst, lpszClass, lpwc)

HINSTANCE hinst;	/* handle of application instance	*/
LPCTSTR lpszClass;	/* address of class name string	*/
LPWNDCLASS lpwc;	/* address of structure for class data	*/

The GetClassInfo function retrieves information about a window class.

Parameter	Description

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.

lpwc	Points to a WNDCLASS structure that receives the information about the class.

Returns

If the function finds a matching class and successfully copies the data, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetClassLong, GetClassName, GetClassWord, GlobalAddAtom, RegisterClass, WNDCLASS


GetClassLong function
GetClassLong (Win32)

DWORD GetClassLong(hwnd, nIndex)

HWND hwnd;	/* handle of window	*/
int nIndex;	/* offset of value to retrieve	*/

The GetClassLong function retrieves the specified 32-bit (long) value from the WNDCLASS structure associated with the given window.

Parameter	Description

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 long integer. To retrieve any other value from the WNDCLASS structure, specify one of the following values:

Value	Action

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 the descriptions of the GetWindowLong and GetWindowWord functions.

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

Returns

If the function succeeds, the return value is the requested 32-bit value; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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, SetClassLong, SetClassWord


GetClassName function
GetClassName (Win32)

int GetClassName(hwnd, lpClassName, cchClassName)

HWND hwnd;	/* handle of window	*/
LPTSTR lpClassName;	/* address of buffer for class name	*/
int cchClassName;	/* size of buffer, in characters	*/

The GetClassName function retrieves the name of the class to which the given window belongs.

Parameter	Description

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.

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

Returns

If the function succeeds, the return value is the number of characters copied to the specified buffer; otherwise, it is zero. To get extended error information, use the GetLastError function.

See Also

FindWindow, GetClassInfo, GetClassLong, GetClassWord


GetClassWord function
GetClassWord (Win32)

WORD GetClassWord(hwnd, nIndex)

HWND hwnd;	/* handle of window	*/
int nIndex;	/* offset of value to retrieve	*/

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 given window belongs.

Parameter	Description

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

Returns

If the function succeeds, the return value is the requested 16-bit value; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

Other than GCW_ATOM, GCW_ values are obsolete in the Win32 application programming interface (API). You must use the GetClassLong function to retrieve the class values of a window.

See Also

GetClassLong, RegisterClass, SetClassLong, SetClassWord, WNDCLASS


GetClientRect function
GetClientRect (Win32)

BOOL GetClientRect(hwnd, lprc)

HWND hwnd;	/* handle of window	*/
LPRECT lprc;	/* address of structure for client coordinates	*/

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

Parameter	Description

hwnd	Identifies the window whose client coordinates are to be retrieved.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetWindowRect, RECT


GetClipboardData function
GetClipboardData (Win32)

HANDLE GetClipboardData(uFormat)

UINT uFormat;	/* clipboard format	*/

The GetClipboardData function retrieves data from the clipboard in the specified format. The clipboard must have been opened previously.

Parameter	Description

uFormat	Specifies a clipboard format. For a description of the clipboard formats, see the SetClipboardData function.

Returns

If the function succeeds, the return value is the handle of a clipboard object in the specified format. Otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

An application can enumerate the available formats in advance by using the EnumClipboardFormats function.

The handle GetClipboardData returns is controlled by the clipboard, not by the application. The application must copy the data immediately, instead of relying on its handle for long-term use. The application must not free the handle or leave it locked.

Windows supports three clipboard formats for text: CF_UNICODETEXT, CF_TEXT, and CF_OEMTEXT. Specify CF_TEXT for ANSI text, CF_UNICODETEXT for Unicode text, and CF_OEMTEXT for text in the OEM character set. If any of the three text formats is placed on the clipboard, all three can be retrieved by using the GetClipboardData function. If necessary, Windows automatically converts data in an available text format to the requested format.

Windows supports two clipboard formats for metafiles: CF_ENHMETAFILE and CF_METAFILEPICT. Specify CF_ENHMETAFILE for enhanced metafiles and CF_METAFILEPICT for Windows metafiles. If either of the two metafile formats is placed on the clipboard, both can be retrieved by GetClipboardData. If necessary, Windows automatically converts data in the available metafile format to the requested format.

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.

See Also

EnumClipboardFormats, SetClipboardData


GetClipboardFormatName function
GetClipboardFormatName (Win32)

int GetClipboardFormatName(uFormat, lpszFormatName, cchFormatName)

UINT uFormat;	/* clipboard format to retrieve	*/
LPTSTR lpszFormatName;	/* address of buffer for name	*/
int cchFormatName;	/* length of name string in characters	*/

The GetClipboardFormatName function retrieves from the clipboard the name of the specified registered format. The function copies the name to the specified buffer.

Parameter	Description

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

cchFormatName	Specifies the maximum length, in characters, of the string to be copied to the buffer. If the name exceeds this limit, it is truncated.

Returns

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer. Otherwise, the return value is zero, indicating the requested format does not exist or is predefined. To get extended error information, use the GetLastError function.

See Also

EnumClipboardFormats, RegisterClipboardFormat


GetClipboardOwner function
GetClipboardOwner (Win32)

HWND GetClipboardOwner(VOID)

The GetClipboardOwner function retrieves the window handle of the current owner of the clipboard.

Returns

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, use the GetLastError function.

Comments

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 function
GetClipboardViewer (Win32)

HWND GetClipboardViewer(VOID)

The GetClipboardViewer function retrieves the handle of the first window in the clipboard viewer chain.

Returns

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, use the GetLastError function.

See Also

GetClipboardOwner, SetClipboardViewer


GetClipCursor function
GetClipCursor (Win32)

BOOL GetClipCursor(lprc)

LPRECT lprc;	/* address of structure for rectangle	*/

The GetClipCursor function retrieves the screen coordinates of the rectangular area to which the cursor is confined.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


GetCurrentTime function
GetCurrentTime (Win32)

DWORD GetCurrentTime(VOID)

The GetCurrentTime function retrieves the number of milliseconds that have elapsed since Windows was started.

Returns

If the function succeeds, the return value is the number of milliseconds that have elapsed since Windows was started.

Comments

The GetCurrentTime function is identical to the GetTickCount function. Applications should use the GetTickCount function because its name matches more closely what the function does.

The GetCurrentTime and GetMessageTime functions return different times. GetMessageTime returns the Windows time when the given message was created, not the current Windows time.

The internal timer wraps around to zero if Windows is run continuously for approximately 49.7 days.

See Also

GetMessageTime, GetSystemTime, GetTickCount, SetSystemTime


GetCursor function
GetCursor (Win32)

HCURSOR GetCursor(VOID)

The GetCursor function retrieves the handle of the current cursor.

Returns

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 function
GetCursorPos (Win32)

BOOL GetCursorPos(lpPoint)

LPPOINT lpPoint;	/* address of structure for cursor position	*/

The GetCursorPos function retrieves the cursor's position, in screen coordinates.

Parameter	Description

lpPoint	Points to the POINT structure that is to receive the screen coordinates of the cursor.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, SetCursor, SetCursorPos, ShowCursor, POINT


GetDC function
GetDC (Win32)

HDC GetDC(hwnd)

HWND hwnd;	/* handle of window	*/

The GetDC function retrieves a handle of a display device context (DC) for the client area of the given window. The display DC can be used in subsequent GDI functions to draw in the client area of the window.

This function retrieves a common, class, or private DC depending on the class style specified for the given window. For common DC, GetDC assigns default attributes to the DC each time it is retrieved. For class and private DCs, GetDC leaves the previously assigned attributes unchanged.

Parameter	Description

hwnd	Identifies the window whose DC is to be retrieved.

Returns

If the function succeeds, the return value identifies the DC for the given window's client area. Otherwise, it is NULL.

Comments

After painting with a common DC, the ReleaseDC function must be called to release the DC. Class and private DCs do not have to be released. The number of DCs is limited only by available memory.

See Also

ReleaseDC, GetWindowDC


GetDCEx function
GetDCEx (Win32)

HDC GetDCEx(hwnd, hrgnClip, flags)

HWND hwnd;	/* handle of window	*/
HRGN hrgnClip;	/* handle of clip region	*/
DWORD flags;	/* DC creation flags	*/

The GetDCEx function retrieves the handle of a display device (DC) context for the given window. The display DC 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.

Parameter	Description

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 DC is created. This parameter can be some combination of the following values:

Value	Meaning

DCX_WINDOW	Returns a DC corresponding to the window rectangle rather than the client rectangle.

DCX_CACHE	Returns a DC from the cache, rather than the OWNDC or CLASSDC window. Essentially, overrides CS_OWNDC and CS_CLASSDC.

DCX_DEFAULTCLIP	Returns a DC by using the default clipping flags specified by WS_CLIPCHILDREN, WS_CLIPSIBLINGS, and CS_PARENTDC.

DCX_PARENTCLIP	Uses the visible region of the parent window. The parent's WS_CLIPCHILDREN and CS_PARENTDC style bits are ignored. The DC 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 DC to the default attributes when this DC is released.

DCX_NORECOMPUTE	If an exact match in the cache is not found, returns NULL rather than creating a new DC. When used with DCX_NORESETATTRS, this gives applications a way to determine whether they must reselect any special attributes.

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

DCX_INTERSECTRGN	The clipping region identified by hrgnClip is intersected with the visible region of the returned DC.

DCX_VALIDATE	When specified with DCX_INTERSECTUPDATE, causes the DC to be completely validated. Using this function with both DCX_INTERSECTUPDATE and DCX_VALIDATE is identical to using the BeginPaint function.

Returns

If the function succeeds, the return value is the handle of the DC for the given window. Otherwise, the return value is NULL, indicating the hwnd parameter is invalid.

Comments

Unless the display DC belongs to a window class, the ReleaseDC function must be called to release the DC after painting. Because only five common DCs are available at any given time, failure to release a DC can prevent other applications from accessing a DC.

A DC 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


GetDesktopWindow function
GetDesktopWindow (Win32)

HWND GetDesktopWindow(VOID)

The GetDesktopWindow function returns the handle of the Windows desktop window. The desktop window covers the entire screen; it is the area on top of which all icons and other windows are painted.

Returns

The return value is the handle of the desktop window.

See Also

GetWindow


GetDialogBaseUnits function
GetDialogBaseUnits (Win32)

LONG GetDialogBaseUnits(VOID)

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.

Returns

If the function succeeds, 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.

Comments

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 units 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


GetDlgCtrlID function
GetDlgCtrlID (Win32)

int GetDlgCtrlID(hwndCtl)

HWND hwndCtl;	/* handle of control	*/

The GetDlgCtrlID function returns the identifier of the given control.

Parameter	Description

hwndCtl	Identifies the control.

Returns

If the function succeeds, the return value is the identifier of the control; otherwise, it is NULL, indicating, for example, that hwndCtl is not a valid window handle.

Comments

GetDlgCtrlID accepts child window handles as well as handles of controls in a 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 function
GetDlgItem (Win32)

HWND GetDlgItem(hwndDlg, idControl)

HWND hwndDlg;	/* handle of dialog box	*/
int idControl;	/* identifier of control	*/

The GetDlgItem function retrieves the handle of a control in the given dialog box.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the control.

idControl	Specifies the identifier of the control to be retrieved.

Returns

If the function succeeds, the return value is the window handle of the given control; otherwise, it is NULL, indicating an invalid dialog box handle or a nonexistent control.

Comments

You can use the GetDlgItem function with any parent-child window pair, not just with dialog boxes. As long as the hwndDlg 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 function
GetDlgItemInt (Win32)

UINT GetDlgItemInt(hDlg, nIDDlgItem, lpTranslated, bSigned)

HWND hDlg;	/* handle of dialog box	*/
int nIDDlgItem;	/* identifier of control	*/
BOOL* lpTranslated;	/* address of variable for error flag	*/
BOOL bSigned;	/* signed or unsigned indicator	*/

The GetDlgItemInt function translates the text of a control in the given dialog box into an integer value.

Parameter	Description

hDlg	Identifies the dialog box.

nIDDlgItem	Specifies the identifier of the control to be translated.

lpTranslated	Points to the Boolean variable that is to receive the translated flag.

bSigned	Specifies whether the value to be retrieved is signed.

Returns

If the function succeeds, the return value is the translated value of the control text. Because zero is a valid return value, you must use the lpTranslated parameter to detect errors. If your application requires a signed return value, it should cast the return value as an int type.

Comments

The function retrieves the text of the given control by sending the control a WM_GETTEXT message. The function then translates the text by stripping any extra spaces at the beginning of the text and converting 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 number. Otherwise, it creates an unsigned value.

GetDlgItemInt returns zero if the translated number is greater than INT_MAX (for signed numbers) or UINT_MAX (for unsigned numbers). When errors occur, such as encountering nonnumeric characters or exceeding the given maximum, GetDlgItemInt copies zero to the location pointed to by the lpTranslated parameter. If there are no errors, lpTranslated receives a nonzero value. If lpTranslated is NULL, GetDlgItemInt does not warn about errors.

GetDlgItemInt sends a WM_GETTEXT message to the control.

See Also

GetDlgCtrlID, GetDlgItem, GetDlgItemText, SetDlgItemInt


GetDlgItemText function
GetDlgItemText (Win32)

UINT GetDlgItemText(hwndDlg, idControl, lpsz, cchMax)

HWND hwndDlg;	/* handle of dialog box	*/
int idControl;	/* identifier of control	*/
LPTSTR lpsz;	/* address of buffer for text	*/
int cchMax;	/* maximum size of string	*/

The GetDlgItemText function retrieves the title or text associated with a control in a dialog box.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the control.

idControl	Specifies the identifier of the control whose title or text is to be retrieved.

lpsz	Points to the buffer to receive the title or text.

cchMax	Specifies the maximum length, in characters, of the string to be copied to the buffer pointed to by lpsz. If the length of the string exceeds the limit, the string is truncated.

Returns

If the function succeeds, the return value specifies the number of characters copied to the buffer, not including the terminating null character; otherwise, it is zero.

Comments

The GetDlgItemText function sends a WM_GETTEXT message to the control.

See Also

GetDlgItemInt, SetDlgItemInt, SetDlgItemText, WM_GETTEXT


GetDoubleClickTime function
GetDoubleClickTime (Win32)

UINT GetDoubleClickTime(VOID)

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.

Returns

If the function succeeds, the return value specifies the current double-click time, in milliseconds.

See Also

SetDoubleClickTime


GetFocus function
GetFocus (Win32)

HWND GetFocus(VOID)

The GetFocus function retrieves the handle of the keyboard focus window associated with the thread that called the function.

Returns

If the function succeeds, the return value is the handle of the keyboard focus window associated with the calling thread. If the calling thread does not contain a keyboard focus window, the return value is NULL.

Comments

Although a return value of NULL means the calling thread does not have a keyboard focus window, another thread may have a keyboard-focus window.

See Also

GetActiveWindow, GetCapture, SetFocus, WM_KILLFOCUS, WM_SETFOCUS


GetForegroundWindow function
GetForegroundWindow (Win32)

HWND GetForegroundWindow(VOID)

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.

Returns

The return value is the handle of the foreground window.

See Also

SetForegroundWindow


GetIconInfo function
GetIconInfo (Win32)

BOOL GetIconInfo(hicon, piconinfo)

HICON hicon;	/* icon handle	*/
PICONINFO piconinfo;	/* address of icon structure	*/

The GetIconInfo function retrieves information about the given icon or cursor.

Parameter	Description

hicon	Identifies the icon or cursor.

piconinfo	Points to an ICONINFO structure. The function fills in the structure's members.

Returns

If the function succeeds, the return value is TRUE and the function fills in the members of the specified ICONINFO structure; otherwise, the return value is FALSE. To get extended error information, use the GetLastError function.

Comments

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, LoadIcon, LookupIconIdFromDirectory


GetInputState function
GetInputState (Win32)

BOOL GetInputState(VOID)

The GetInputState function determines whether there are mouse-button or keyboard messages in the calling thread's message queue.

Returns

If the queue contains one or more new mouse-button or keyboard messages, the return value is TRUE; otherwise, it is FALSE.

See Also

GetQueueStatus


GetKBCodePage function
GetKBCodePage (Win32)

UINT GetKBCodePage(VOID)

The GetKBCodePage function is provided for compatibility with earlier versions of Windows. In Win32 it just calls the GetOEMCP function. New applications should use the GetOEMCP function.

Returns

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. See GetOEMCP for a list of OEM code-page identifiers.

See Also

GetACP, GetOEMCP


GetKeyboardLayoutName function
GetKeyboardLayoutName (Win32)

BOOL GetKeyboardLayoutName(lpszKLName)

LPTSTR lpszKLName;	/* address of buffer for layout name	*/

The GetKeyboardLayoutName function retrieves the name of the active keyboard layout.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

LoadKeyboardLayout


GetKeyboardState function
GetKeyboardState (Win32)

BOOL GetKeyboardState(pbKeyState)

PBYTE pbKeyState;	/* address of array to receive status data	*/

The GetKeyboardState function copies the status of the 256 virtual keys to the specified buffer.

Parameter	Description

pbKeyState	Points to the 256-byte array that will receive the status data for each virtual key.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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

For a complete table of virtual key codes, see Virtual Key Codes.

See Also

GetAsyncKeyState, GetKeyState, MapVirtualKey, SetKeyboardState


GetKeyboardType function
GetKeyboardType (Win32)

int GetKeyboardType(fnKeybInfo)

int fnKeybInfo;	/* type of information to retrieve	*/

The GetKeyboardType function retrieves information about the current keyboard.

Parameter	Description

fnKeybInfo	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

Returns

If the function succeeds, the return value specifies the requested information. Otherwise, it is zero.

Comments

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 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 function
GetKeyNameText (Win32)

int GetKeyNameText(lParam, lpszBuffer, cchMaxKey)

LONG lParam;	/* second parameter of keyboard message	*/
LPTSTR lpszBuffer;	/* address of buffer for key name	*/
int cchMaxKey;	/* maximum length of key-name string length	*/

The GetKeyNameText function retrieves a string that represents the name of a key.

Parameter	Description

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.

lpszBuffer	Points to a buffer that will receive the key name.

cchMaxKey	Specifies the maximum length, in characters, of the key name, not including the terminating null character (this parameter should be one less than the size of the buffer pointed to by the lpszBuffer parameter).

Returns

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.

Comments

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 function
GetKeyState (Win32)

SHORT GetKeyState(nVirtKey)

int nVirtKey;	/* virtual-key code	*/

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

Parameter	Description

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.

Returns

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.

Comments

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 GetAsyncKeyState to retrieve that information.

An application calls the GetKeyState function 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.

For a complete table of virtual key codes, see Virtual Key Codes.

See Also

GetAsyncKeyState, GetKeyboardState, MapVirtualKey, SetKeyboardState


GetLastActivePopup function
GetLastActivePopup (Win32)

HWND GetLastActivePopup(hwndOwner)

HWND hwndOwner;	/* handle of owner window	*/

The GetLastActivePopup function determines which pop-up window owned by the given window was most recently active.

Parameter	Description

hwndOwner	Identifies the owner window.

Returns

The return value identifies the most recently active pop-up window. The return value is the same as the hwndOwner parameter, if any of the following conditions are met:

The window identified by hwndOwner was most recently active.

The window identified by hwndOwner does not own any pop-up windows.

The window identified by hwndOwner is not a top-level window, or it is owned by another window.

See Also

AnyPopup, ShowOwnedPopups


GetMenu function
GetMenu (Win32)

HMENU GetMenu(hwnd)

HWND hwnd;	/* handle of window	*/

The GetMenu function retrieves the handle of the menu assigned to the given window.

Parameter	Description

hwnd	Identifies the window whose menu handle is retrieved.

Returns

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 function
GetMenuCheckMarkDimensions (Win32)

LONG GetMenuCheckMarkDimensions(VOID)

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.

Returns

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


GetMenuItemCount function
GetMenuItemCount (Win32)

int GetMenuItemCount(hmenu)

HMENU hmenu;	/* handle of menu	*/

The GetMenuItemCount function determines the number of items in the given menu bar or pop-up menu.

Parameter	Description

hmenu	Identifies the handle of the menu to be examined.

Returns

If the function succeeds, the return value specifies the number of items in the menu; otherwise, it is -1. To get extended error information, use the GetLastError function.

See Also

GetMenuItemID


GetMenuItemID function
GetMenuItemID (Win32)

UINT GetMenuItemID(hmenu, nPos)

HMENU hmenu;	/* handle of menu	*/
int nPos;	/* position of menu item	*/

The GetMenuItemID function retrieves the menu item identifier of a menu item located at the specified position in the given menu bar or pop-up menu.

Parameter	Description

hmenu	Identifies the menu bar or pop-up 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.

Returns

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 invokes a pop-up menu, the return value is 0xFFFFFFFF.

See Also

GetMenuItemCount, GetMenuString


GetMenuState function
GetMenuState (Win32)

UINT GetMenuState(hmenu, uItem, fuFlags)

HMENU hmenu;	/* handle of menu	*/
UINT uItem;	/* menu item to query	*/
UINT fuFlags;	/* menu flags	*/

The GetMenuState function retrieves the menu flags associated with the specified menu item. If the menu item activates a pop-up menu, this function also returns the number of items in the pop-up menu.

Parameter	Description

hmenu	Identifies the menu that contains the menu item whose flags are to be retrieved.

uItem	Specifies the menu item for which the menu flags are to be retrieved, as determined by the fuFlags parameter.

fuFlags	Specifies how the uItem parameter is interpreted. This parameter can be one of the following values:

Value	Meaning

MF_BYCOMMAND	Indicates that the uItem 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 uItem parameter gives the zero-based relative position of the menu item.

Returns

If the specified item does not exist, the return value is 0xFFFFFFFF. If the menu item activates a pop-up menu, the low-order byte of the return value contains the menu flags associated with the item (for more information, see the Comments section), and the high-order byte contains the number of items in the pop-up menu activated 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	Meaning

MF_CHECKED	Places a check mark next to the item (pop-up 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 pop-up 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 pop-up menus) without separating columns.

MF_SEPARATOR	Creates a horizontal dividing line (for pop-up menus only).

See Also

GetMenu, GetMenuItemCount, GetMenuItemID, GetMenuString


GetMenuString function
GetMenuString (Win32)

int GetMenuString(hmenu, idItem, lpsz, cchMax, fuFlags)

HMENU hmenu;	/* handle of menu	*/
UINT idItem;	/* menu item identifier	*/
LPTSTR lpsz;	/* address of buffer for string	*/
int cchMax;	/* maximum length of string	*/
UINT fuFlags;	/* menu flags	*/

The GetMenuString function copies the text string of the specified menu item into the given buffer.

Parameter	Description

hmenu	Identifies the menu.

idItem	Specifies the menu item to be changed, as determined by the fuFlags parameter.

lpsz	Points to the buffer that is to receive the null-terminated string.

cchMax	Specifies the maximum length, in characters, of the string to be copied. If the string is longer than the maximum specified in cchMax, the extra characters are truncated.

fuFlags	Specifies how the idItem parameter is interpreted. This parameter must be one of the following values:

Value	Meaning

MF_BYCOMMAND	Indicates that the idItem 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 idItem parameter gives the zero-based relative position of the menu item.

Returns

If the function succeeds, the return value specifies the number of characters copied to the buffer, not including the terminating null character; otherwise, it is zero.

Comments

The cchMax parameter must be one larger than the number of characters in the text string to accommodate the terminating null character.

See Also

GetMenuItemID


GetMessage function
GetMessage (Win32)

BOOL GetMessage(lpmsg, hwnd, uMsgFilterMin, uMsgFilterMax)

LPMSG lpmsg;	/* address of structure with message	*/
HWND hwnd;	/* handle of window	*/
UINT uMsgFilterMin;	/* first message	*/
UINT uMsgFilterMax;	/* last message	*/

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 given window and thread messages posted via PostThreadMessage. 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.

Parameter	Description

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.

uMsgFilterMin	Specifies the integer value of the lowest message value to be retrieved.

uMsgFilterMax	Specifies the integer value of the highest message value to be retrieved.

Returns

If a message other than WM_QUIT is retrieved, the return value is TRUE. If the WM_QUIT message is retrieved, the return value is FALSE.

Comments

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 uMsgFilterMin and uMsgFilterMax 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 uMsgFilterMin and uMsgFilterMax are both zero, GetMessage returns all available messages (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 uMsgFilterMin and uMsgFilterMax parameters are both zero, the GetMessage function returns all available messages (without performing any filtering).

GetMessage does not remove WM_PAINT messages from the queue. The messages remain in the queue until processed.

See Also

PeekMessage, PostMessage, PostThreadMessage, WaitMessage, MSG


GetMessageExtraInfo function
GetMessageExtraInfo (Win32)

LONG GetMessageExtraInfo(VOID)

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.

Returns

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 function
GetMessagePos (Win32)

DWORD GetMessagePos(VOID)

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.

Returns

The return value specifies the x- and y-coordinates of the cursor position.

Comments

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, MAKEPOINTS, LOWORD, HIWORD, POINTS


GetMessageTime function
GetMessageTime (Win32)

LONG GetMessageTime(VOID)

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 (placed in the thread's message queue).

Returns

The return value specifies the message time.

Comments

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 and then subtract the time of the first message from the time of the second message.

See Also

GetMessage, GetMessagePos


GetNextDlgGroupItem function
GetNextDlgGroupItem (Win32)

HWND GetNextDlgGroupItem(hwndDlg, hwndCtl, fPrevious)

HWND hwndDlg;	/* handle of dialog box	*/
HWND hwndCtl;	/* handle of control	*/
BOOL fPrevious;	/* direction flag	*/

The GetNextDlgGroupItem function retrieves the handle of the first control in a group of controls that precedes (or follows) the given control in the given dialog box.

Parameter	Description

hwndDlg	Identifies the dialog box being searched.

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

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

Returns

If this function succeeds, the return value is the handle of the previous (or next) control in the group of controls.

Comments

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 hwndCtl 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 hwndCtl if no such control is found.

See Also

GetNextDlgTabItem


GetNextDlgTabItem function
GetNextDlgTabItem (Win32)

HWND GetNextDlgTabItem(hwndDlg, hwndCtl, fPrevious)

HWND hwndDlg;	/* handle of dialog box	*/
HWND hwndCtl;	/* handle of known control	*/
BOOL fPrevious;	/* direction flag	*/

The GetNextDlgTabItem function retrieves the handle of the first control that has the WS_TABSTOP style that precedes (or follows) the given control.

Parameter	Description

hwndDlg	Identifies the dialog box to be searched.

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

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

Returns

If the function succeeds, the return value is the window handle of the previous (or next) control that has the WS_TABSTOP style set.

Comments

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

See Also

GetDlgItem, GetNextDlgGroupItem


GetNextWindow function
GetNextWindow (Win32)

HWND GetNextWindow(hwnd, fuDirection)

HWND hwnd;	/* handle of current window	*/
UINT fuDirection;	/* direction flag	*/

The GetNextWindow function retrieves the handle of the next or previous window in the Z order. The next window is below the given window; the previous window is above. Windows maintains separate Z orders for topmost windows, top-level windows, and child windows. If the given window is a topmost window, the function retrieves the handle of the next (or previous) topmost window. If the given window is a top-level window, the function retrieves the handle of the next (or previous) top-level window. If the given window is a a child window, the function searches for a handle of the next (or previous) child window.

Parameter	Description

hwnd	Identifies a window. The window handle retrieved is relative to this window, based on the value of the fuDirection parameter.

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

Returns

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, use the GetLastError function.

Comments

Using this function is the same as calling the GetWindow function with the GW_HWNDNEXT or GW_HWNDPREV flag set.

See Also

GetTopWindow, GetWindow


GetOpenClipboardWindow function
GetOpenClipboardWindow (Win32)

HWND GetOpenClipboardWindow(VOID)

The GetOpenClipboardWindow function retrieves the handle of the window that currently has the clipboard open.

Returns

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, use the GetLastError function.

Comments

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, the GetOpenClipboardWindow function returns NULL.

See Also

GetClipboardOwner, GetClipboardViewer, OpenClipboard


GetParent function
GetParent (Win32)

HWND GetParent(hwndChild)

HWND hwndChild;	/* handle of child window	*/

The GetParent function retrieves the handle of the given child window's parent window.

Parameter	Description

hwndChild	Identifies the window whose parent window handle is to be retrieved.

Returns

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, use the GetLastError function.

See Also

SetParent


GetPriorityClipboardFormat function
GetPriorityClipboardFormat (Win32)

int GetPriorityClipboardFormat(puPriorityList, cList)

UINT *puPriorityList;	/* address of priority list	*/
int cList;	/* number of entries in list	*/

The GetPriorityClipboardFormat function returns the first available clipboard format in the specified list.

Parameter	Description

puPriorityList	Points to an array of unsigned integers identifying clipboard formats, in priority order. For a description of the clipboard formats, see the SetClipboardData function.

cList	Specifies the number of entries in the puPriorityList array. This value must not be greater than the number of entries in the list.

Returns

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 formats in the list, the return value is -1. To get extended error information, use the GetLastError function.

See Also

CountClipboardFormats, EnumClipboardFormats, GetClipboardFormatName, IsClipboardFormatAvailable, RegisterClipboardFormat, SetClipboardData


GetProp function
GetProp (Win32)

HANDLE GetProp(hwnd, lpsz)

HWND hwnd;	/* handle of window	*/
LPCTSTR lpsz;	/* atom or address of string	*/

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.

Parameter	Description

hwnd	Identifies the window whose property list is to be searched.

lpsz	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 AddAtom function. The atom, a 16-bit value, must be placed in the low-order word of the lpsz parameter; the high-order word must be zero.

Returns

If the property list contains the given string, the return value is the associated data handle. Otherwise, the return value is NULL.

See Also

AddAtom, EnumProps, RemoveProp, SetProp


GetQueueStatus function
GetQueueStatus (Win32)

DWORD GetQueueStatus(fuFlags)

UINT fuFlags;	/* queue-status flags	*/

The GetQueueStatus function returns flags that indicate the type of messages found in the calling thread's message queue.

Parameter	Description

fuFlags	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_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.

Returns

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.

Comments

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


GetScrollPos function
GetScrollPos (Win32)

int GetScrollPos(hwnd, fnBar)

HWND hwnd;	/* handle of window with scroll bar	*/
int fnBar;	/* scroll bar flags	*/

The GetScrollPos function retrieves the current position of the scroll box (thumb) in the given 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.

Parameter	Description

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

Returns

If the function succeeds, the return value is the current position of the scroll box; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

An application can make limited use of 32-bit scroll positions by using the GetScrollPos function. Although the messages that indicate scrollbar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data, the functions SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange support 32-bit scrollbar position data. Thus, an application can call GetScrollPos while processing either of the WM_*SCROLL messages to obtain 32-bit scrollbar position data.

The limitation on this technique applies to real-time scrolling of a window's contents. An application implements such scrolling by processing WM_*SCROLL messages that carry the SB_THUMBTRACK notification code, 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 thus only obtain 32-bit position data before or after a scroll has taken place.

See Also

GetScrollRange, ScrollDC, ScrollWindow, SetScrollPos, SetScrollRange


GetScrollRange function
GetScrollRange (Win32)

BOOL GetScrollRange(hwnd, fnBar, lpMinPos, lpMaxPos)

HWND hwnd;	/* handle of window with scroll bar	*/
int fnBar;	/* scroll bar flags	*/
LPINT lpMinPos;	/* address of variable that receives minimum position	*/
LPINT lpMaxPos;	/* address of variable that receives maximum position	*/

The GetScrollRange function retrieves the current minimum and maximum scroll box (thumb) positions for the given scroll bar.

Parameter	Description

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If the given 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 scrollbar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data. However, since SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange support 32-bit scrollbar position data, there is a way to circumvent the WM_*SCROLL messages' 16 bits barrier. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, SetScrollPos, SetScrollRange


GetSubMenu function
GetSubMenu (Win32)

HMENU GetSubMenu(hmenu, nPos)

HMENU hmenu;	/* handle of menu	*/
int nPos;	/* menu item position	*/

The GetSubMenu function retrieves the handle of the pop-up menu activated by the specified menu item.

Parameter	Description

hmenu	Identifies the menu.

nPos	Specifies the zero-based relative position in the given menu of an item that activates a pop-up menu.

Returns

If the function succeeds, the return value is the handle of the pop-up menu activated by the menu item. If the menu item does not activate a pop-up menu, it is NULL.

See Also

CreatePopupMenu, GetMenu


GetSysColor function
GetSysColor (Win32)

DWORD GetSysColor(nIndex)

int nIndex;	/* display element	*/

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.

Parameter	Description

nIndex	Specifies the display element whose color is to be retrieved. This parameter must be one of the following values:

Value	Meaning

COLOR_ACTIVEBORDER	Active window border.

COLOR_ACTIVECAPTION	Active window caption.

COLOR_APPWORKSPACE	Background color of multiple document interface (MDI) applications.

COLOR_BACKGROUND	Desktop.

COLOR_BTNFACE	Face shading on push buttons.

COLOR_BTNSHADOW	Edge shading on push buttons.

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_MENU	Menu background.

COLOR_MENUTEXT	Text in menus.

COLOR_SCROLLBAR	Scroll bar gray area.

COLOR_SHADOW	Color of automatic window shadows.

COLOR_WINDOW	Window background.

COLOR_WINDOWFRAME	Window frame.

COLOR_WINDOWTEXT	Text in windows.

Returns

If the function succeeds, the return value is the red, green, blue (RGB) color value that specifies the color of the given element.

Comments

System colors for monochrome displays are usually interpreted as shades of gray.

See Also

SetSysColors


GetSystemMenu function
GetSystemMenu (Win32)

HMENU GetSystemMenu(hwnd, fRevert)

HWND hwnd;	/* handle of window to own System menu	*/
BOOL fRevert;	/* reset flag	*/

The GetSystemMenu function allows the application to access the System menu (also known as Control menu) for copying and modifying.

Parameter	Description

hwnd	Identifies the window that will own a copy of the System menu.

fRevert	Specifies the action to be taken. If this parameter is FALSE, the GetSystemMenu function returns the handle of the copy of the System menu currently in use. The copy is initially identical to the System menu, but it can be modified.

If this parameter is TRUE, GetSystemMenu resets the System menu back to the Windows default state. The previous System menu, if any, is destroyed.

Returns

If the fRevert parameter is FALSE, the return value is the handle of a copy of the System menu. If the fRevert parameter is TRUE, the return value is NULL.

Comments

Any window that does not use the GetSystemMenu function to make its own copy of the System menu receives the standard System menu.

The handle returned by the GetSystemMenu function is used with the AppendMenu, InsertMenu, or ModifyMenu function to change the System menu.

The System menu initially contains items with various identifier values, such as SC_CLOSE, SC_MOVE, and SC_SIZE.

Menu items on the System menu send WM_SYSCOMMAND messages.

All predefined System menu items have identifier numbers greater than 0xF000. If an application adds commands to the System menu, it should use identifier numbers less than 0xF000.

Windows automatically grays items on the standard System menu, depending on the situation. The application can carry out its own checking or graying by responding to the WM_INITMENU message, that is sent before any menu is displayed.

See Also

AppendMenu, GetMenu, InsertMenu, ModifyMenu, WM_INITMENU


GetSystemMetrics function
GetSystemMetrics (Win32)

int GetSystemMetrics(nIndex)

int nIndex;	/* system measurement to retrieve	*/

The GetSystemMetrics function retrieves system metrics. System metrics are the widths and heights of various elements of the Windows display. GetSystemMetrics can also return flags that indicate whether the current version is a debugging version, whether a mouse is present, or whether the meanings of the left and right mouse buttons have been exchanged.

Parameter	Description

nIndex	Specifies the system measurement to be retrieved. All measurements are given in pixels. This parameter must be one of the following values:

Index	Meaning

SM_CXBORDER	Width of window frame that cannot be sized.

SM_CYBORDER	Height of window frame that cannot be sized.

SM_CYCAPTION	Actual caption height plus SM_CYBORDER.

SM_CXCURSOR	Width of cursor.

SM_CYCURSOR	Height of cursor.

SM_CXDLGFRAME	Width of frame when window has WS_DLGFRAME style.

SM_CYDLGFRAME	Height of frame when window has WS_DLGFRAME style.

SM_CXDOUBLECLK	Width of rectangle around location of 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.

SM_CYDOUBLECLK	Height of rectangle around location of 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.

SM_CXFRAME	Width of window frame that can be sized.

SM_CYFRAME	Height of window frame that can be sized.

SM_CXFULLSCREEN	Width of window client area for full-screen window.

SM_CYFULLSCREEN	Height of window client area for full-screen window (equivalent to height of the screen minus height of the window caption).

SM_CXHSCROLL	Width of arrow bitmap on horizontal scroll bar.

SM_CYHSCROLL	Height of arrow bitmap on horizontal scroll bar.

SM_CXICON	Width of icon.

SM_CYICON	Height of icon.

SM_CXICONSPACING	Width of rectangles that Program Manager uses to position tiled icons.

SM_CYICONSPACING	Height of rectangles that Program Manager uses to position tiled icons.

SM_CYKANJIWINDOW	Height of Kanji window.

SM_CYMENU	Height of single-line menu bar minus SM_CYBORDER.

SM_CXMIN	Minimum width of window.

SM_CYMIN	Minimum height of window.

SM_CXMINTRACK	Minimum tracking width of window.

SM_CYMINTRACK	Minimum tracking height of window.

SM_CMOUSEBUTTONS	Number of buttons on mouse.

SM_CXSCREEN	Width of screen.

SM_CYSCREEN	Height of screen.

SM_CXSIZE	Width of bitmaps contained in title bar.

SM_CYSIZE	Height of bitmaps contained in title bar.

SM_CXVSCROLL	Width of arrow bitmap on vertical scroll bar.

SM_CYVSCROLL	Height of arrow bitmap on vertical scroll bar.

SM_CXHTHUMB	Width of thumb box on horizontal scroll bar.

SM_CYVTHUMB	Height of thumb box on vertical scroll bar.

SM_DBCSENABLED	Status of double-byte character set: nonzero if enabled.

SM_DEBUG	Debugging version: nonzero if Windows.

SM_MENUDROPALIGNMENT	Alignment of pop-up menus. If this value is zero, the left side of a pop-up menu is aligned with the left side of the corresponding menu-bar item. If this value is nonzero, the left side of a pop-up menu is aligned with the right side of the corresponding menu-bar item.

SM_MOUSEPRESENT	Status of mouse hardware: nonzero if installed.

SM_PENWINDOWS	Handle of Pen Windows dynamic-link library (DLL) if Pen Windows is installed.

SM_SWAPBUTTON	Status of mouse buttons: nonzero if left and right mouse buttons swapped.

Returns

If the function succeeds, the return value is the requested system metric.

Comments

System metrics may vary from display to display.


GetTabbedTextExtent function
GetTabbedTextExtent (Win32)

DWORD GetTabbedTextExtent(hdc, lpszStr, cchString, nTabPos, lpnTabStopPos)

HDC hdc;	/* handle of device context	*/
LPCTSTR lpszStr;	/* address of character string	*/
int cchString;	/* number of characters in string	*/
int nTabPos;	/* number of tab positions	*/
LPINT lpnTabStopPos;	/* address of array of tab positions	*/

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.

Parameter	Description

hdc	Identifies the device context.

lpszStr	Points to a character string.

cchString	Specifies the number of characters in the text string.

nTabPos	Specifies the number of tab-stop positions in the array pointed to by the lpnTabStopPos parameter.

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

Returns

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.

Comments

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 nTabPos parameter is zero and the lpnTabStopPos parameter is NULL, tabs are expanded to eight times the average character width.

If nTabPos is 1, the tab stops are separated by the distance specified by the first value in the array to which lpnTabStopPos points.

See Also

GetTextExtent, HIWORD, LOWORD, TabbedTextOut


GetTickCount function
GetTickCount (Win32)

DWORD GetTickCount(VOID)

The GetTickCount function retrieves the number of milliseconds that have elapsed since Windows was started.

Returns

If the function succeeds, the return value is the number of milliseconds that have elapsed since Windows was started.

Comments

The GetTickCount function is identical to the GetCurrentTime function. Applications should use the GetTickCount function because its name matches more closely what the function does.

The GetTickCount and GetMessageTime functions return different times. GetMessageTime returns the Windows time when the given message was created, not the current Windows time.

The internal timer wraps around to zero if Windows is run continuously for approximately 49.7 days.

See Also

GetCurrentTime, GetMessageTime, GetSystemTime, SetSystemTime


GetTopWindow function
GetTopWindow (Win32)

HWND GetTopWindow(hwndParent)

HWND hwndParent;	/* handle of parent window	*/

The GetTopWindow function examines the Z order of the child windows associated with the given parent window and retrieves the handle of the child window at the top of the Z order.

Parameter	Description

hwndParent	Identifies the parent window whose child windows are to be examined. If this parameter is NULL, the function returns the top-level window at the top of the Z order.

Returns

If the function succeeds, the return value is the handle of the child window at the top of the Z order. If the given window has no child windows, the return value is NULL. To get extended error information, use the GetLastError function.

See Also

GetNextWindow, GetWindow


GetUpdateRect function
GetUpdateRect (Win32)

BOOL GetUpdateRect(hwnd, lprc, bErase)

HWND hwnd;	/* handle of window	*/
LPRECT lprc;	/* address of structure for update rectangle	*/
BOOL bErase;	/* erase flag	*/

The GetUpdateRect function retrieves the coordinates of the smallest rectangle that completely encloses the update region of the given 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, GetUpdateRect retrieves the rectangle in client coordinates. If there is no update region, GetUpdateRect retrieves an empty rectangle (sets all coordinates to zero).

Parameter	Description

hwnd	Identifies the window whose update region is to be retrieved.

lprc	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 given window to erase the background.

Returns

If the update region is not empty, the return value is TRUE; otherwise, it is FALSE.

Comments

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, UpdateWindow, ValidateRect, WM_ERASEBKGND, RECT


GetUpdateRgn function
GetUpdateRgn (Win32)

int GetUpdateRgn(hwnd, hrgn, fErase)

HWND hwnd;	/* handle of window	*/
HRGN hrgn;	/* handle of region	*/
BOOL fErase;	/* erase background flag	*/

The GetUpdateRgn function retrieves the update region of the given window by copying it into the given region. The coordinates of the update region are relative to the upper-left corner of the window (that is, they are client coordinates).

Parameter	Description

hwnd	Identifies the window whose update region is to be retrieved.

hrgn	Identifies the region to receive the update region.

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

Returns

The return value indicates the complexity of the resulting region; it can be one of the following values:

Value	Meaning

NULLREGION	Region is empty.

SIMPLEREGION	Region is a single rectangle.

COMPLEXREGION	Region consists of more than one rectangle.

ERROR	An error occurred.

Comments

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

BeginPaint, GetUpdateRect, InvalidateRgn, UpdateWindow, ValidateRgn


GetWindow function
GetWindow (Win32)

HWND GetWindow(hwnd, uCmd)

HWND hwnd;	/* handle of original window	*/
UINT uCmd;	/* relationship flag	*/

The GetWindow function retrieves the handle of a window that has the specified relationship to the given window.

Parameter	Description

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 given 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 given window is a parent window; otherwise, the retrieved handle is NULL. The function examines only child windows of the given window. It does not examine descendant windows.

GW_HWNDFIRST	The retrieved handle identifies the window at the top of the Z order. If the given window is a topmost window, the handle identifies the topmost window at the top of the Z order. If the given window is a top-level window, the handle identifies the top-level window at the top of the Z order. If the given window is a child window, the handle identifies the sibling window at the top of the Z order.

GW_HWNDLAST	The retrieved handle identifies the window at the bottom of the Z order. If the given window is a topmost window, the handle identifies the topmost window at the bottom of the Z order. If the given window is a top-level window, the handle identifies the top-level window at the bottom of the Z order. If the given window is a child window, the handle identifies the sibling window at the bottom of the Z order.

GW_HWNDNEXT	The retrieved handle identifies the window below the given window in the Z order. If the given window is a topmost window, the handle identifies the topmost window below the given window. If the given window is a top-level window, the handle identifies the top-level window below the given window. If the given window is a child window, the handle identifies the sibling window below the given window.

GW_HWNDPREV	The retrieved handle identifies the window above the given window in the Z order. If the given window is a topmost window, the handle identifies the topmost window above the given window. If the given window is a top-level window, the handle identifies the top-level window above the given window. If the given window is a child window, the handle identifies the sibling window above the given window.

GW_OWNER	The retrieved handle identifies the given window's owner window, if any.

Returns

If the function succeeds, the return value is a window handle. If no window exists with the specified relationship to the given window, the return value is NULL. To get extended error information, use the GetLastError function.

See Also

GetActiveWindow, GetNextWindow, GetTopWindow


GetWindowDC function
GetWindowDC (Win32)

HDC GetWindowDC(hwnd)

HWND hwnd;	/* handle of window	*/

The GetWindowDC function retrieves the device context (DC) for the entire window, including title bar, menus, and scroll bars. A window DC permits painting anywhere in a window, because the origin of the DC is the upper-left corner of the window instead of the client area.

GetWindowDC assigns default attributes to the window DC each time it retrieves the DC. Previous attributes are lost.

Parameter	Description

hwnd	Identifies the window whose DC is to be retrieved.

Returns

If the function succeeds, the return value is the handle of a DC for the given window. Otherwise, it is NULL, indicating an error or an invalid hwnd parameter.

Comments

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 DC. Not releasing the window DC has serious effects on painting requested by applications.

See Also

BeginPaint, GetSystemMetrics, ReleaseDC, GetDC


GetWindowLong function
GetWindowLong (Win32)

LONG GetWindowLong(hwnd, nIndex)

HWND hwnd;	/* handle of window	*/
int nIndex;	/* offset of value to retrieve	*/

The GetWindowLong function retrieves information about the given window. The function also retrieves the 32-bit (long) value at the specified offset into the extra window memory of the given window.

Parameter	Description

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 long integer. To set 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.

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 long value associated with the window. Each window has a corresponding long 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	Specifies the address of the dialog box procedure.

DWL_MSGRESULT	Specifies the return value of a message processed in the dialog box procedure.

DWL_USER	Specifies extra information private to the application, such as handles or pointers.

Returns

If the function succeeds, the return value is the requested 32-bit value; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the WNDCLASS structure used with the RegisterClass function.

See Also

GetWindowWord, SetParent, SetWindowLong, SetWindowWord


GetWindowPlacement function
GetWindowPlacement (Win32)

BOOL GetWindowPlacement(hwnd, lpwndpl)

HWND hwnd;	/* handle of window	*/
WINDOWPLACEMENT * lpwndpl;	/* address of structure for position data	*/

The GetWindowPlacement function retrieves the show state and the restored, minimized, and maximized positions of the given window.

Parameter	Description

hwnd	Identifies the window.

lpwndpl	Points to the WINDOWPLACEMENT structure that receives the show state and position information.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The flags member of the WINDOWPLACEMENT structure 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.

See Also

SetWindowPlacement, WINDOWPLACEMENT


GetWindowRect function
GetWindowRect (Win32)

BOOL GetWindowRect(hwnd, lprc)

HWND hwnd;	/* handle of window	*/
LPRECT lprc;	/* address of structure for window coordinates	*/

The GetWindowRect function retrieves the dimensions of the bounding rectangle of the given window. The dimensions are given in screen coordinates that are relative to the upper-left corner of the screen.

Parameter	Description

hwnd	Identifies the window.

lprc	Points to a RECT structure that receives the screen coordinates of the upper left and lower right corners of the window.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetClientRect, RECT


GetWindowText function
GetWindowText (Win32)

int GetWindowText(hwnd, lpsz, cch)

HWND hwnd;	/* handle of window or control with text	*/
LPTSTR lpsz;	/* address of buffer for text	*/
int cch;	/* maximum number of characters to copy	*/

The GetWindowText function copies the text of the given window's title bar (if it has one) into a buffer. If the given window is a control, the text of the control is copied.

Parameter	Description

hwnd	Identifies the window or control containing the text.

lpsz	Points to the buffer that will receive the text.

cch	Specifies the maximum number of characters to copy to the buffer. If the text exceeds this limit, it is truncated.

Returns

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, use the GetLastError function.

Comments

This function causes a WM_GETTEXT message to be sent to the given window or control.

See Also

GetWindowTextLength, SetWindowText, WM_GETTEXT


GetWindowTextLength function
GetWindowTextLength (Win32)

int GetWindowTextLength(hwnd)

HWND hwnd;	/* handle of window or control with text	*/

The GetWindowTextLength function retrieves the length, in characters, of the given window's title bar text (if the window has a title bar). If the given window is a control, the function retrieves the length of the text within the control.

Parameter	Description

hwnd	Identifies the window or control.

Returns

If the function succeeds, the return value is the length, in characters, of the text. If the window has no text, the return value is zero. To get extended error information, use the GetLastError function.

Comments

This function causes a WM_GETTEXTLENGTH message to be sent to the given window or control.

See Also

GetWindowText, SetWindowText, WM_GETTEXTLENGTH


GetWindowThreadProcessId function
GetWindowThreadProcessId (Win32)

DWORD GetWindowThreadProcessId(hwnd, lpdwProcessId)

HWND hwnd;	/* handle of window	*/
LPDWORD lpdwProcessId;	/* address of variable for process identifier	*/

The GetWindowThreadProcessId function retrieves the identifier of the thread that created the given window and, optionally, the identifier of the process that created the window.

Parameter	Description

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.

Returns

The return value is the identifier of the thread that created the window.

Comments

This function replaces the GetWindowTask function of Windows version 3.x.

See Also

GetWindowTask


GetWindowWord function
GetWindowWord (Win32)

WORD GetWindowWord(hwnd, nIndex)

HWND hwnd;	/* handle of window	*/
int nIndex;	/* offset of value to retrieve	*/

The GetWindowWord function retrieves a 16-bit (word) value at the specified offset into the extra window memory for the given window.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the requested 16-bit value; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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 application programming interface (API). You must use the GetWindowLong function to retrieve information about the window.

See Also

GetParent, GetWindowLong, SetParent, SetWindowLong, SetWindowWord


GrayString function
GrayString (Win32)

BOOL GrayString(hdc, hbr, lpOutputFunc, lParam, nCount, X, Y, nWidth, nHeight)

HDC hdc;	/* handle of device context	*/
HBRUSH hbr;	/* handle of brush for graying	*/
GRAYSTRINGPROC lpOutputFunc;	/* address of callback function	*/
LPARAM lParam;	/* address of application-defined data	*/
int nCount;	/* number of characters to output	*/
int X;	/* horizontal position	*/
int Y;	/* vertical position	*/
int nWidth;	/* width	*/
int nHeight;	/* height	*/

The GrayString function draws gray text at the given 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 given device context (DC).

If the lpOutputFunc parameter is NULL, GDI uses the TextOut function, and the lParam 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.

Parameter	Description

hdc	Identifies the DC.

hbr	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 description of the OutputProc callback function.

lParam	Specifies a pointer to data to be passed to the output function. If the lpOutputFunc parameter is NULL, lParam 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 lParam 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 lParam 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 lParam is a pointer to the string.

Returns

If the string is drawn, the return value is TRUE. If the return value is FALSE, either the TextOut function or the application-defined output function returned FALSE, or there was insufficient memory to create a memory bitmap for graying.

Comments

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, SetTextColor, TabbedTextOut, TextOut


HideCaret function
HideCaret (Win32)

BOOL HideCaret(hwnd)

HWND hwnd;	/* handle of window with caret	*/

The HideCaret function removes the caret from the screen. Hiding the caret does not destroy its current shape or invalidate the insertion point.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

HideCaret hides the caret only if the given window owns the caret. If the given 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 function
HiliteMenuItem (Win32)

BOOL HiliteMenuItem(hwnd, hmenu, uItemHilite, uHilite)

HWND hwnd;	/* handle of window with menu	*/
HMENU hmenu;	/* handle of menu	*/
UINT uItemHilite;	/* menu item to highlight or unhighlight	*/
UINT uHilite;	/* highlight flags	*/

The HiliteMenuItem function highlights or removes the highlighting from an item in a menu bar.

Parameter	Description

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 the uItemHilite parameter gives the identifier of the menu item.

MF_BYPOSITION	Indicates that the uItemHilite parameter 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.

Returns

If the menu item is set to the specified highlight state, the return value is TRUE; otherwise, it is FALSE.

Comments

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


ImpersonateDdeClientWindow function
ImpersonateDdeClientWindow (Win32)

BOOL ImpersonateDdeClientWindow(hwndClient, hwndServer)

HWND hwndClient;	/* handle of DDE client window	*/
HWND hwndServer;	/* handle of DDE server window	*/

The ImpersonateDdeClientWindow function enables a dynamic data exchange (DDE) server application to impersonate a DDE client application's security context in order to protect secure server data from unauthorized DDE clients.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

An application should call the RevertToSelf function to undo the impersonation set by the ImpersonateDdeClientWindow function.

A Dynamic Data Exchange Management Library (DDEML) application should use the DdeImpersonateClient function.

See Also

DdeImpersonateClient, RevertToSelf


InflateRect function
InflateRect (Win32)

BOOL InflateRect(lprc, xAmt, yAmt)

LPRECT lprc;	/* address of rectangle	*/
int xAmt;	/* amount to increase or decrease width	*/
int yAmt;	/* amount to increase or decrease height	*/

The InflateRect function increases or decreases the width and height of the specified rectangle. The InflateRect function adds xAmt units to the left and right ends of the rectangle and yAmt units to the top and bottom. The xAmt and yAmt parameters are signed values; positive values increase the width and height, and negative values decrease them.

Parameter	Description

lprc	Points to the RECT structure that increases or decreases in size.

xAmt	Specifies the amount to increase or decrease the rectangle width. This parameter must be negative to decrease the width.

yAmt	Specifies the amount to increase or decrease the rectangle height. This parameter must be negative to decrease the height.

Returns

If the function is succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

IntersectRect, OffsetRect, UnionRect, RECT


InSendMessage function
InSendMessage (Win32)

BOOL InSendMessage(VOID)

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.

Returns

If the window procedure is processing a message sent to it from another thread by the SendMessage function, the return value is TRUE; otherwise, the return value is FALSE.

See Also

PostThreadMessage, ReplyMessage, SendMessage


InsertMenu function
InsertMenu (Win32)

BOOL InsertMenu(hmenu, uItem, fuFlags, idNewItem, lpszNewItem)

HMENU hmenu;	/* handle of menu	*/
UINT uItem;	/* menu item that new menu item precedes	*/
UINT fuFlags;	/* menu item flags	*/
UINT idNewItem;	/* menu item identifier or pop-up menu handle	*/
LPCTSTR lpszNewItem;	/* menu item content	*/

The InsertMenu function inserts a new menu item into a menu, moving other items down the menu.

Parameter	Description

hmenu	Identifies the menu to be changed.

uItem	Specifies the menu item before which the new menu item is to be inserted, as determined by the fuFlags parameter.

fuFlags	Specifies flags that control the interpretation of the uItem 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 Comments section.

Value	Meaning

MF_BYCOMMAND	Indicates that the uItem 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 uItem parameter gives the zero-based relative position of the new menu item. If uItem is 0xFFFFFFFF, the new menu item is appended to the end of the menu.

idNewItem	Specifies either the identifier of the new menu item or, if the fuFlags parameter is set to the MF_POPUP flag, the handle of the pop-up menu.

lpszNewItem	Specifies the content of the new menu item. The interpretation of this parameter depends on whether the fuFlags 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 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 item is created or its appearance is updated.

MF_STRING	Contains a pointer to a null-terminated string (the default).

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 fuFlags parameter:

Value	Meaning

MF_BITMAP	Uses a bitmap as the menu item. The lpszNewItem 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 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 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 MF_MENUBREAK, except for pop-up 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 pop-up menus) 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 is a pop-up item; that is, selecting it invokes a pop-up menu. The idNewItem parameter specifies the handle of the pop-up menu. This flag is used to add a pop-up item to a menu bar or to a pop-up menu.

MF_SEPARATOR	Draws a horizontal dividing line. This flag is used only in a pop-up menu. The dividing line cannot be grayed, disabled, or highlighted. The lpszNewItem and idNewItem parameters are ignored.

MF_STRING	Specifies that the menu item is a text string; the lpszNewItem 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 list shows groups of flags that 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, ModifyMenu, RemoveMenu, SetMenuItemBitmaps


IntersectRect function
IntersectRect (Win32)

BOOL IntersectRect(lprcDst, lprcSrc1, lprcSrc2)

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

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.

Parameter	Description

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.

Returns

If the rectangles intersect, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

InflateRect, OffsetRect, UnionRect, RECT


InvalidateRect function
InvalidateRect (Win32)

BOOL InvalidateRect(hwnd, lprc, fErase)

HWND hwnd;	/* handle of window with changed update region	*/
CONST RECT *lprc;	/* address of structure with rectangle	*/
BOOL fErase;	/* erase-background flag	*/

The InvalidateRect function adds a rectangle to the given window's update region. The update region represents the portion of the window's client area that must be redrawn.

Parameter	Description

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.

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 fErase 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, ValidateRect, ValidateRgn, WM_ERASEBKGND, WM_NCPAINT, WM_PAINT


InvalidateRgn function
InvalidateRgn (Win32)

BOOL InvalidateRgn(hwnd, hrgn, fErase)

HWND hwnd;	/* handle of window with changed update region	*/
HRGN hrgn;	/* handle of region to add	*/
BOOL fErase;	/* erase-background flag	*/

The InvalidateRgn function invalidates the client area within the given region by adding it to the current update region of the given window. The invalidated region, along with all other areas in the update region, is marked for painting when the next WM_PAINT message occurs.

Parameter	Description

hwnd	Identifies the window whose update region 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.

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

Returns

This function always returns TRUE.

Comments

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 given region must have been created by using one of the region functions.

If the fErase parameter is TRUE for any part of the update region, the background in the entire region is erased, not just in the given part.

See Also

BeginPaint, InvalidateRect, ValidateRect, ValidateRgn, WM_PAINT


InvertRect function
InvertRect (Win32)

BOOL InvertRect(hdc, lprc)

HDC hdc;	/* handle of device context	*/
CONST RECT *lprc;	/* address of structure with rectangle	*/

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.

Parameter	Description

hdc	Identifies the device context.

lprc	Points to a RECT structure that contains the logical coordinates of the rectangle to be inverted.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


IsCharAlpha function
IsCharAlpha (Win32)

BOOL IsCharAlpha(ch)

TCHAR ch;	/* character to test	*/

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.

Parameter	Description

ch	Specifies the character to be tested.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

IsCharAlphaNumeric


IsCharAlphaNumeric function
IsCharAlphaNumeric (Win32)

BOOL IsCharAlphaNumeric(ch)

TCHAR ch;	/* character to test	*/

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.

Parameter	Description

ch	Specifies the character to be tested.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

IsCharAlpha


IsCharLower function
IsCharLower (Win32)

BOOL IsCharLower(ch)

TCHAR ch;	/* character to test	*/

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.

Parameter	Description

ch	Specifies the character to be tested.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

IsCharUpper


IsCharUpper function
IsCharUpper (Win32)

BOOL IsCharUpper(ch)

TCHAR ch;	/* character to test	*/

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.

Parameter	Description

ch	Specifies the character to be tested.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

IsCharLower


IsChild function
IsChild (Win32)

BOOL IsChild(hwndParent, hwnd)

HWND hwndParent;	/* handle of parent window	*/
HWND hwnd;	/* handle of window to test	*/

The IsChild function tests whether a specified window is a child window or descendant window of a given parent window. A child window is the direct descendant of a given parent window, if that parent window is in the chain of parent windows leading from the original overlapped or pop-up window to the child window.

Parameter	Description

hwndParent	Identifies the parent window.

hwnd	Identifies the window to be tested.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

IsWindow, SetParent


IsClipboardFormatAvailable function
IsClipboardFormatAvailable (Win32)

BOOL IsClipboardFormatAvailable(uFormat)

UINT uFormat;	/* clipboard format	*/

The IsClipboardFormatAvailable function determines whether the clipboard contains data in the specified format.

Parameter	Description

uFormat	Specifies a standard or registered clipboard format. For a description of the clipboard formats, see the SetClipboardData function.

Returns

If the clipboard format is available, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, RegisterClipboardFormat, SetClipboardData


IsDialogMessage function
IsDialogMessage (Win32)

BOOL IsDialogMessage(hwndDlg, lpmsg)

HWND hwndDlg;	/* handle of dialog box	*/
LPMSG lpmsg;	/* address of structure with message	*/

The IsDialogMessage function determines whether the specified message is intended for the given dialog box and, if it is, processes the message.

Parameter	Description

hwndDlg	Identifies the dialog box.

lpmsg	Points to an MSG structure that contains the message to be checked.

Returns

If the message has been processed, the return value is TRUE; otherwise, it is FALSE.

Comments

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, TranslateMessage, MSG, DM_GETDEFID, DM_SETDEFID, WM_GETDLGCODE


IsDlgButtonChecked function
IsDlgButtonChecked (Win32)

UINT IsDlgButtonChecked(hwndDlg, idButton)

HWND hwndDlg;	/* handle of dialog box	*/
int idButton;	/* button identifier	*/

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.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the button control.

idButton	Specifies the integer identifier of the button control.

Returns

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

0	Button state is unchecked.

1	Button state is checked.

2	Button state is indeterminate (applies only if the button has the BS_3STATE or BS_AUTO3STATE style).

If the button has any other style, the return value is 0.

Comments

The IsDlgButtonChecked function sends a BM_GETCHECK message to the specified button control.

See Also

CheckDlgButton, BM_GETCHECK, BM_SETCHECK


IsIconic function
IsIconic (Win32)

BOOL IsIconic(hwnd)

HWND hwnd;	/* handle of window	*/

The IsIconic function determines whether the given window is minimized (iconic).

Parameter	Description

hwnd	Identifies the window.

Returns

If function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

IsZoomed


IsMenu function
IsMenu (Win32)

BOOL IsMenu(hMenu)

HMENU hMenu;	/* handle to test	*/

The IsMenu function determines whether a handle is a menu handle.

Parameter	Description

hMenu	The handle to be tested.

Returns

If hMenu is a menu handle, the function returns TRUE. If it is not, the function returns FALSE.


IsRectEmpty function
IsRectEmpty (Win32)

BOOL IsRectEmpty(lprc)

CONST RECT *lprc;	/* address of structure with rectangle	*/

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.

Parameter	Description

lprc	Points to a RECT structure that contains the logical coordinates of the rectangle.

Returns

If the rectangle is empty, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

EqualRect, PtInRect, RECT


IsWindow function
IsWindow (Win32)

BOOL IsWindow(hwnd)

HWND hwnd;	/* handle of window	*/

The IsWindow function determines whether the specified window handle identifies an existing window.

Parameter	Description

hwnd	Specifies the window handle.

Returns

If the window handle identifies an existing window, the return value is TRUE; otherwise, it is FALSE.

See Also

IsWindowEnabled, IsWindowVisible


IsWindowEnabled function
IsWindowEnabled (Win32)

BOOL IsWindowEnabled(hwnd)

HWND hwnd;	/* handle of window to test	*/

The IsWindowEnabled function determines whether the given window is enabled for mouse and keyboard input.

Parameter	Description

hwnd	Identifies the window.

Returns

If the window is enabled, the return value is TRUE; otherwise, it is FALSE.

Comments

A child window receives input only if it is both enabled and visible.

See Also

EnableWindow, IsWindowVisible


IsWindowUnicode function
IsWindowUnicode (Win32)

BOOL IsWindowUnicode(hwnd)

HWND hwnd;	/* handle of window	*/

The IsWindowUnicode function determines whether the given window is a native Unicode window.

Parameter	Description

hwnd	Identifies the window.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The system does automatic two-way translation (Unicode to ANSI-ASCII) translation 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 function
IsWindowVisible (Win32)

BOOL IsWindowVisible(hwnd)

HWND hwnd;	/* handle of window	*/

The IsWindowVisible function retrieves the visibility state of the given window.

Parameter	Description

hwnd	Identifies the window.

Returns

If the given window is visible on the screen (has the WS_VISIBLE style), the return value is TRUE; otherwise, it is FALSE. Because the return value specifies whether the window has the WS_VISIBLE style, it may be TRUE, even if the window is totally obscured by other windows.

Comments

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 function
IsZoomed (Win32)

BOOL IsZoomed(hwnd)

HWND hwnd;	/* handle of window	*/

The IsZoomed function determines whether a window is maximized.

Parameter	Description

hwnd	Identifies the window.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

IsIconic


keybd_event function
keybd_event (Win32)

VOID keybd_event(bVirtualKey, bScanCode, dwFlags, dwExtraInfo)

BYTE bVirtualKey;	/* virtual key code	*/
BYTE bScanCode;	/* hardware scan code	*/
DWORD dwFlags;	/* flags specifying various function options	*/
DWORD dwExtraInfo;	/* additional data associated with keystroke	*/

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.

Parameter	Description

bVirtualKey	Specifies a virtual-key code. The code must be a value in the range 1 to 254.

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

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.

Returns

This function has no return value.

Comments

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 on 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 bVirtualKey set to VK_SNAPSHOT, and bScanCode set to 0 for a snapshot of the full screen or set to 1 for a snapshot of the active window.

See Also

GetAsyncKeyState, GetKeyState, MapVirtualKey, SetKeyboardState, WM_KEYUP, WM_KEYDOWN


KillTimer function
KillTimer (Win32)

BOOL KillTimer(hwnd, idEvent)

HWND hwnd;	/* handle of window that installed timer	*/
UINT idEvent;	/* timer identifier	*/

The KillTimer function destroys the specified timer. The system searches the message queue for any pending WM_TIMER messages associated with the timer and removes them.

Parameter	Description

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.

idEvent	Specifies the timer to be destroyed. If the window handle passed to SetTimer is valid, this parameter must be the same as the idEvent value passed to SetTimer. If the application calls SetTimer with hwnd set to NULL, this parameter must be the timer identifier returned by SetTimer.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

SetTimer


LoadAccelerators function
LoadAccelerators (Win32)

HACCEL LoadAccelerators(hinst, lpTableName)

HINSTANCE hinst;	/* handle of application instance	*/
LPCTSTR lpTableName;	/* address of table-name string	*/

The LoadAccelerators function loads the given accelerator table.

Parameter	Description

hinst	Identifies an instance of the module whose executable file contains the accelerator table to be loaded.

lpTableName	Points to a null-terminated string that names the accelerator table to be loaded. 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.

Returns

If the function succeeds, the return value is the handle of the loaded accelerator table; otherwise, it is NULL.

Comments

If the accelerator table has not yet been loaded, the function loads it from the given executable file.

Accelerator tables loaded from resources are freed automatically when the application terminates.

See Also

CopyAcceleratorTable, CreateAcceleratorTable, DestroyAcceleratorTable


LoadBitmap function
LoadBitmap (Win32)

HBITMAP LoadBitmap(hinst, lpszBitmap)

HINSTANCE hinst;	/* handle of application instance	*/
LPCTSTR lpszBitmap;	/* address of bitmap resource name	*/

The LoadBitmap function loads the specified bitmap resource from the given module's executable file.

Parameter	Description

hinst	Identifies the instance of the module whose executable file contains the bitmap to be loaded.

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

Returns

If the function succeeds, the return value is the handle of the specified bitmap; otherwise, it is NULL.

Comments

If the bitmap pointed to by the lpszBitmap 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 Windows. To do so, the application must set the hinst parameter to NULL and the lpszBitmap 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

DeleteObject, LoadCursor, LoadIcon, CreateBitmap


LoadCursor function
LoadCursor (Win32)

HCURSOR LoadCursor(hinst, lpszCursor)

HINSTANCE hinst;	/* handle of application instance	*/
LPCTSTR lpszCursor;	/* name string or cursor resource identifier	*/

The LoadCursor function loads the specified cursor resource from the executable file associated with the given application instance.

Parameter	Description

hinst	Identifies an instance of the module whose executable file contains the cursor to be loaded.

lpszCursor	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 hinst parameter to NULL and the lpszCursor 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	Empty icon

IDC_NO	Slashed circle

IDC_SIZE	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

Returns

If the function succeeds, the return value is the handle of the newly loaded cursor; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

This function only loads the cursor resource if it has not been loaded; otherwise, it retrieves the handle of the existing resource. LoadCursor returns a valid cursor handle only if the lpszCursor parameter points to a cursor resource. If lpszCursor 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 for the cursor most appropriate for the current display device. The cursor resource can be a color or monochrome bitmap.

See Also

SetCursor, ShowCursor, SetCursorPos, MAKEINTRESOURCE


LoadIcon function
LoadIcon (Win32)

HICON LoadIcon(hinst, lpszIcon)

HINSTANCE hinst;	/* handle of application instance	*/
LPCTSTR lpszIcon;	/* icon-name string or icon resource identifier	*/

The LoadIcon function loads the specified icon resource from the executable file associated with the given application instance.

Parameter	Description

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

lpszIcon	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. The MAKEINTRESOURCE macro can be used to create this value.

To use one of the Windows predefined icons, set the hinst parameter to NULL and the lpszIcon parameter to one 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).

Returns

If the function succeeds, the return value is the handle of the newly loaded icon; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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.

See Also

CreateIcon


LoadKeyboardLayout function
LoadKeyboardLayout (Win32)

HKL LoadKeyboardLayout(lpszKLName, fuFlags)

LPCTSTR lpszKLName;	/* address of buffer for layout name	*/
UINT fuFlags;	/* keyboard layout flags	*/

The LoadKeyboardLayout function loads a keyboard layout.

Parameter	Description

lpszKLName	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, US English has a language identifier of 0x0409, so the primary US English layout is named "00000409". Variants of US 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 description of the MAKELANGID macro in <Microsoft Win32 Programmer's Reference, Volume 5>.

fuFlags	Specifies how the keyboard layout is to be loaded. This parameter can be one of the following values:

Value	Meaning

KLF_ACTIVATE	The layout is loaded (if it is not already loaded) and activated.

KLF_REORDER	This flag is only meaningful if the KLF_ACTIVATE is set and the layout is already loaded. If these conditions are met, and the KLF_REORDER bit is set, the specified layout is removed from its position in the system's circular list of loaded layouts and placed at the head 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 system's circular list of loaded layouts is simply rotated.

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 prefered by the user. For example, if there was a value in this section of name "00000409" equal to "00010409", loading the US English layout ("00000409") with the KLF_SUBSTITUTES_OK flag set would cause the Dvorak US English layout ("00010409") to be loaded.

KLF_UNLOADPREVIOUS	The previously active layout is unloaded.

Returns

If the function succeeds, the return value is the handle of the keyboard layout; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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 rapidly switch between layouts.

See Also

ActivateKeyboardLayout, UnloadKeyboardLayout


LoadMenu function
LoadMenu (Win32)

HMENU LoadMenu(hinst, lpMenuName)

HINSTANCE hinst;	/* handle of application instance	*/
LPCTSTR lpMenuName;	/* menu name string or menu-resource identifier	*/

The LoadMenu function loads the specified menu resource from the executable file associated with the given application instance.

Parameter	Description

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

Returns

If the function succeeds, the return value is the handle of the menu resource; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

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 function
LoadMenuIndirect (Win32)

HMENU LoadMenuIndirect(lpMenuTemplate)

CONST MENUTEMPLATE *lpMenuTemplate;	/* address of menu template	*/

The LoadMenuIndirect function loads the specified menu template in memory.

Parameter	Description

lpMenuTemplate	Points to a menu template, consisting of a MENUITEMTEMPLATEHEADER structure followed by one or more MENUITEMTEMPLATE structures, each of which defines a menu item.

Returns

If the function succeeds, the return value is the handle of the menu; otherwise, it is NULL. To get extended error information, use the GetLastError function.

Comments

For both the ANSI and the Unicode version of this function, the strings in the MENUITEMTEMPLATE structure must be Unicode strings.

See Also

LoadMenu, MENUITEMTEMPLATE


LoadString function
LoadString (Win32)

int LoadString(hinst, wID, lpBuffer, cchBuffer)

HINSTANCE hinst;	/* handle of module containing string resource	*/
UINT wID;	/* resource identifier	*/
LPTSTR lpBuffer;	/* address of buffer for resource	*/
int cchBuffer;	/* size of buffer	*/

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.

Parameter	Description

hinst	Identifies an instance of the module whose executable file contains the string resource.

wID	Specifies the integer identifier of the string to be loaded.

lpBuffer	Points to the buffer to receive the string.

cchBuffer	Specifies the size of the buffer, in characters. The string is truncated and null terminated if it is longer than the number of characters specified.

Returns

If the function succeeds, the return value is the number of characters copied into the buffer, not including the null-terminating character, or zero if the string resource does not exist. To get extended error information, use the GetLastError function.

See Also

FormatMessage, LoadAccelerators, LoadBitmap, LoadCursor, LoadIcon, LoadMenu, LoadMenuIndirect


LockWindowUpdate function
LockWindowUpdate (Win32)

BOOL LockWindowUpdate(hwndLock)

HWND hwndLock;	/* handle of window to lock	*/

The LockWindowUpdate function disables or reenables drawing in the given window. Only one window can be locked at a time.

Parameter	Description

hwndLock	Specifies the window in which drawing will be disabled. If this parameter is NULL, drawing in the locked window is enabled.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE, indicating an error occurred or another window was already locked.

Comments

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 whose visible region 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


LookupIconIdFromDirectory function
LookupIconIdFromDirectory (Win32)

int LookupIconIdFromDirectory(presbits, fIcon)

PBYTE presbits;	/* address of resource data	*/
BOOL fIcon;	/* look for icon or cursor	*/

The LookupIconIdFromDirectory function searches through icon or cursor data for the icon or cursor that best fits the current display device.

Parameter	Description

presbits	Points to the icon or cursor directory data. Because this function does not validate the resource data, this function will cause a general protection (GP) fault or return 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.

Returns

If the function succeeds, the return value is an integer resource identifier for the icon or cursor that best fits the current display device.

Comments

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. FindResource and FindResourceEx use the MAKEINTRESOURCE macro on 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 and LoadCursor functions use this function to search the specified resource data for the icon or cursor that best fits the current display device.

For more information and a code sample that uses this function, see Icons.

See Also

CreateIconFromResource, CreateIconIndirect, GetIconInfo


MapDialogRect function
MapDialogRect (Win32)

BOOL MapDialogRect(hwndDlg, lprc)

HWND hwndDlg;	/* handle of dialog box	*/
LPRECT lprc;	/* address of structure with rectangle	*/

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.

Parameter	Description

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

lprc	Points to a RECT structure that contains the dialog box coordinates to be converted.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The MapDialogRect function assumes that the initial coordinates in the RECT structure represent dialog 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


MapVirtualKey function
MapVirtualKey (Win32)

UINT MapVirtualKey(uCode, fuMapType)

UINT uCode;	/* virtual-key code or scan code	*/
UINT fuMapType;	/* translation to perform	*/

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.

Parameter	Description

uCode	Specifies the virtual-key code or scan code for a key. How this value is interpreted depends on the value of the fuMapType parameter.

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

Returns

The return value depends on the value of the uCode and fuMapType parameters. For more information, see the description of the fuMapType parameter.

Comments

An application can use MapVirtualKeyCode 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.

For a complete table of virtual key codes, see Virtual Key Codes.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyState, SetKeyboardState


MapWindowPoints function
MapWindowPoints (Win32)

int MapWindowPoints(hwndFrom, hwndTo, lppt, cPoints)

HWND hwndFrom;	/* handle of window to be mapped from	*/
HWND hwndTo;	/* handle of window to be mapped to	*/
LPPOINT lppt;	/* address of structure array with points to map	*/
UINT cPoints;	/* number of structures in array	*/

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.

Parameter	Description

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.

lppt	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 lppt parameter.

Returns

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, ScreenToClient, POINT, RECT


MessageBeep function
MessageBeep (Win32)

BOOL MessageBeep(fuType)

UINT fuType;	/* sound type	*/

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.

Parameter	Description

fuType	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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 by using the computer speaker.

The user can disable the warning beep by using the Control Panel Sound application.

See Also

FlashWindow, MessageBox


MessageBox function
MessageBox (Win32)

int MessageBox(hwndOwner, lpszText, lpszTitle, fuStyle)

HWND hwndOwner;	/* handle of owner window	*/
LPCTSTR lpszText;	/* address of text in message box	*/
LPCTSTR lpszTitle;	/* address of title of message box	*/
UINT fuStyle;	/* style of message box	*/

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.

Parameter	Description

hwndOwner	Identifies the owner window of the message box to be created. If this parameter is NULL, the message box has no owner window.

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

fuStyle	Specifies the contents and behavior of the dialog box. This parameter can be a combination of the following values:

Value	Meaning

MB_ABORTRETRYIGNORE	The message box contains three push buttons: Abort, Retry, and Ignore.

MB_APPLMODAL	The user must respond to the message box before continuing work in the window identified by the hwndOwner parameter. However, the user can move to the windows of other applications and work in those windows. MB_APPLMODAL is the default if neither MB_SYSTEMMODAL nor MB_TASKMODAL is specified.

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_DEFBUTTON1	The first button is the default. Note that the first button is always the default unless MB_DEFBUTTON2 or MB_DEFBUTTON3 is specified.

MB_DEFBUTTON2	The second button is the default.

MB_DEFBUTTON3	The third button is the default.

MB_ICONASTERISK	Same as MB_ICONINFORMATION.

MB_ICONEXCLAMATION	An exclamation-point icon appears in the message box.

MB_ICONHAND	Same as MB_ICONSTOP.

MB_ICONINFORMATION	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	A stop-sign icon appears in the message box.

MB_OK	The message box contains one push button: OK.

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_SETFOREGROUND	The message box becomes the foreground window. Internally, Windows calls the SetForegroundWindow function for the message box.

MB_SYSTEMMODAL	All applications are suspended until the user responds to the message box. Unless the application specifies MB_ICONHAND, the message box does not become modal until after it is created; consequently, the owner window and other windows continue to receive messages resulting from its activation. Use system-modal message boxes to notify the user of serious, potentially damaging errors that require immediate attention (for example, running out of memory).

MB_TASKMODAL	Same as MB_APPLMODAL except that all the top-level windows belonging to the current task are disabled if the hwndOwner 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.

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.

Returns

The return value is zero if there is not enough memory to create the message box. Otherwise, it 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.

Comments

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 lpszTitle parameters should not be taken from a resource file, because an attempt to load the resource may fail.

When an application calls the MessageBox function and specifies the MB_ICONHAND and MB_SYSTEMMODAL flags for the fuStyle 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 hwndOwner parameter. The hwndOwner parameter should not identify a child window, such as a control in a dialog box.

See Also

FlashWindow, MessageBeep, MessageBoxEx, SetForegroundWindow


MessageBoxEx function
MessageBoxEx (Win32)

int MessageBoxEx(hwndOwner, lpszText, lpszCaption, fuStyle, wLanguageID)

HWND hwndOwner;	/* handle of owner window	*/
LPCTSTR lpszText;	/* address of text in message box	*/
LPCTSTR lpszTitle;	/* address of title of message box	*/
UINT fuStyle;	/* style of message box	*/
WORD wLanguageID;	/* language identifier	*/

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. 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 the description of the MessageBox function.

Parameter	Description

hwndOwner	Identifies the owner window of the message box to be created. If this parameter is NULL, the message box has no owner window.

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

fuStyle	Specifies the contents and behavior of the dialog box. This parameter can be a combination of the following values:

Value	Meaning

MB_ABORTRETRYIGNORE	The message box contains three push buttons: Abort, Retry, and Ignore.

MB_APPLMODAL	The user must respond to the message box before continuing work in the window identified by the hwndOwner parameter. However, the user can move to the windows of other applications and work in those windows. MB_APPLMODAL is the default if neither MB_SYSTEMMODAL nor MB_TASKMODAL is specified.

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_DEFBUTTON1	The first button is the default. Note that the first button is always the default unless MB_DEFBUTTON2 or MB_DEFBUTTON3 is specified.

MB_DEFBUTTON2	The second button is the default.

MB_DEFBUTTON3	The third button is the default.

MB_ICONASTERISK	Same as MB_ICONINFORMATION.

MB_ICONEXCLAMATION	An exclamation-point icon appears in the message box.

MB_ICONHAND	Same as MB_ICONSTOP.

MB_ICONINFORMATION	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	A stop-sign icon appears in the message box.

MB_OK	The message box contains one push button: OK.

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_SETFOREGROUND	The message box becomes the foreground window. Internally, Windows calls the SetForegroundWindow function for the message box.

MB_SYSTEMMODAL	All applications are suspended until the user responds to the message box. Unless the application specifies MB_ICONHAND, the message box does not become modal until after it is created; consequently, the owner window and other windows continue to receive messages resulting from its activation. Use system-modal message boxes to notify the user of serious, potentially damaging errors that require immediate attention (for example, running out of memory).

MB_TASKMODAL	Same as MB_APPLMODAL except that all the top-level windows belonging to the current task are disabled if the hwndOwner 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.

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.

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 the first release of Windows NT, the set of values is limited. For a list of the possible primary language identifiers and sublanguage identifiers, and a discussion of first-release language availability limitations, see the Comments section below.

Returns

If the function fails, the return value is zero, in which case extended error information can be obtained by calling the GetLastError function.

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.

Comments

When you create a system-modal message box to indicate that the system is low on memory, the strings passed as the lpszText and lpszCaption parameters should not be taken from a resource file, because an attempt to load the resource may fail.

When an application calls the MessageBox function and specifies the MB_ICONHAND and MB_SYSTEMMODAL flags for the fuStyle 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 hwndOwner parameter. The hwndOwner parameter should not identify a child window, such as a dialog box.

The table that follows shows the set of language identifiers and sublanguage identifiers, along with a description of each. Note that, in the first release of Windows NT, each country's version contains only the localized versions of language resources. Thus, for example, the US 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.

Primary Language	Sublanguage	Description
LANG_NEUTRAL	SUBLANG_DEFAULT	Default sublanguage
LANG_ARABIC		Arabic
LANG_BULGARIAN		Bulgarian
LANG_CATALAN		Catalan
LANG_CHINESE	SUBLANG_CHINESE_TRADITIONAL	Traditional Chinese
LANG_CHINESE	SUBLANG_CHINESE_SIMPLIFIED	Simplified Chinese
LANG_CZECH		Czech
LANG_DANISH		Danish
LANG_GERMAN	SUBLANG_GERMAN	German
LANG_GERMAN	SUBLANG_GERMAN_SWISS	Swiss German
LANG_GREEK		Greek
LANG_ENGLISH	SUBLANG_ENGLISH_UK	UK English
LANG_ENGLISH	SUBLANG_ENGLISH_US	US English
LANG_ENGLISH	SUBLANG_ENGLISH_AUS	Australian English
LANG_SPANISH	SUBLANG_SPANISH	Spanish
LANG_SPANISH	SUBLANG_SPANISH_MEXICAN	Spanish Mexican
LANG_FINNISH		Finnish
LANG_FRENCH	SUBLANG_FRENCH	French
LANG_FRENCH	SUBLANG_FRENCH_BELGIAN	Belgian French
LANG_FRENCH	SUBLANG_FRENCH_CANADIAN	Canadian French
LANG_FRENCH	SUBLANG_FRENCH_SWISS	Swiss French
LANG_HEBREW		Hebrew
LANG_HUNGARIAN		Hungarian
LANG_ICELANDIC		Icelandic
LANG_ITALIAN	SUBLANG_ITALIAN	Italian
LANG_ITALIAN	SUBLANG_ITALIAN_SWISS	Swiss Italian
LANG_JAPANESE		Japanese
LANG_KOREAN		Korean
LANG_DUTCH	SUBLANG_DUTCH	Dutch
LANG_DUTCH	SUBLANG_DUTCH_BELGIAN	Belgian Dutch
LANG_NORWEGIAN	SUBLANG_NORWEGIAN_BOKMAL	Norwegian - Bokmal
LANG_NORWEGIAN	SUBLANG_NORWEGIAN_NYNORSK	Norwegian - Nynorsk
LANG_POLISH		Polish
LANG_PORTUGUESE	SUBLANG_PORTUGUESE	Portuguese
LANG_PORTUGUESE	SUBLANG_PORTUGUESE_BRAZILIAN	Brazilian Portugues
LANG_RHAETO_ROMAN		Rhaeto-Romanic
LANG_ROMANIAN		Romanian
LANG_RUSSIAN		Russian
LANG_SERBO_CROATIAN	SUBLANG_SERBO_CROATIAN_LATIN	Serbo-Croatian (Lat)
LANG_SERBO_CROATIAN	SUBLANG_SERBO_CROATIAN_CYRILLIC	Serbo-Croatian (Cyr)
LANG_SLOVAK		Slovak
LANG_ALBANIAN		Albanian
LANG_SWEDISH		Swedish
LANG_THAI		Thai
LANG_TURKISH		Turkish
LANG_URDU		Urdu
LANG_BAHASA		Bahasa (Indonesian)
See Also

MessageBox, MessageBeep


ModifyMenu function
ModifyMenu (Win32)

BOOL ModifyMenu(hmenu, uItem, fuFlags, idNewItem, lpszNewItem)

HMENU hmenu;	/* handle of menu	*/
UINT uItem;	/* menu item to modify	*/
UINT fuFlags;	/* menu item flags	*/
UINT idNewItem;	/* menu item identifier or pop-up menu handle	*/
LPCTSTR lpszNewItem;	/* menu item content	*/

The ModifyMenu function changes an existing menu item. This function is used to specify the content, appearance, and behavior of the menu item.

Parameter	Description

hmenu	Identifies the menu to be changed.

uItem	Specifies the menu item to be changed, as determined by the fuFlags parameter.

fuFlags	Specifies flags that control the interpretation of the uItem 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 Comments section.

Value	Meaning

MF_BYCOMMAND	Indicates that the uItem 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 uItem parameter gives the zero-based relative position of the menu item.

idNewItem	Specifies either the identifier of the modified menu item or, if fuFlags is set to the MF_POPUP flag, the handle of the pop-up menu.

lpszNewItem	Points to the content of the changed menu item. The interpretation of this parameter depends on whether the fuFlags 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_MEASURE 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).

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If ModifyMenu replaces a menu item that activates a pop-up menu, the function destroys the old pop-up menu 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 fuFlags parameter:

Value	Meaning

MF_BITMAP	Uses a bitmap as the menu item. The lpszNewItem parameter contains the handle of the bitmap.

MF_BYCOMMAND	Indicates that the uItem parameter specifies the identifier of the menu item (the default).

MF_BYPOSITION	Indicates that the uItem 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, except for pop-up 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 pop-up menus) 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 is a pop-up item; that is, selecting it activates a pop-up menu. The idNewItem parameter specifies the handle of the pop-up menu. This flag is used to add a pop-up item to a menu bar or to a pop-up menu.

MF_SEPARATOR	Draws a horizontal dividing line. This flag is used only in a pop-up menu. The dividing line cannot be grayed, disabled, or highlighted. The lpszNewItem and idNewItem parameters are ignored.

MF_STRING	Specifies that the menu item is a text string; the lpszNewItem 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 list shows groups of flags that 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


mouse_event function
mouse_event (Win32)

VOID mouse_event(dwFlags, dx, dy, cButtons, dwExtraInfo)

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 cButtons;	/* unused; reserved for future use; set to zero	*/
DWORD dwExtraInfo;	/* 32 bits of caller-defined information	*/

The mouse_event function synthesizes mouse motion and button clicks.

Parameter	Description

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_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_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, irregardless of what kind of mouse or mouse-like device, if any, is connected to the system.

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.

cButtons	This parameter is currently unused. It is reserved for future use. It must be set to zero.

dwExtraInfo	Specifies an additional 32-bit value associated with the mouse event. An application calls GetMessageExtraInfo to obtain this extra information.

Returns

This function has no return value.

Comments

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 65535. 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/down; negative values mean the mouse moved left/up.

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 maker wants to pass pen-windows sorts of extra information to its own applications, it can write a 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 field, some pointer or index to the queued extra information. When the application needs the extra information, it calls the DLL with the pointer/index stored in dwExtraInfo, and the DLL returns the extra information.


MoveWindow function
MoveWindow (Win32)

BOOL MoveWindow(hwnd, x, y, cx, cy, bRepaint)

HWND hwnd;	/* handle of window	*/
int x;	/* horizontal position	*/
int y;	/* vertical position	*/
int cx;	/* width	*/
int cy;	/* height	*/
BOOL bRepaint;	/* repaint flag	*/

The MoveWindow function changes the position and dimensions of the given 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.

Parameter	Description

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.

cx	Specifies the new width of the window.

cy	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 to be redrawn.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

If the bPaint 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 bPaint 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.

The MoveWindow function sends a WM_GETMINMAXINFO message to the window being moved, enabling it to modify the default values for the largest and smallest possible windows. If the parameter of MoveWindow exceed these values, they will be replaced by the minimum or maximum values specified in the WM_GETMINMAXINFO message.

The MoveWindow function sends WM_WINDOWPOSCHANGING, WM_WINDOWPOSCHANGED, WM_MOVE, WM_SIZE, and WM_NCCALCSIZE messages to the window.

See Also

SetWindowPos, WM_GETMINMAXINFO, WM_MOVE, WM_NCCALCSIZE, WM_WINDOWPOSCHANGING, WM_WINDOWPOSCHANGED, WM_SIZE


MsgWaitForMultipleObjects function
MsgWaitForMultipleObjects (Win32)

DWORD MsgWaitForMultipleObjects(cObjects, lphObjects, fWaitAll, dwTimeout, fdwWakeMask )

DWORD cObjects;	/* number of handles in handle array	*/
LPHANDLE lphObjects;	/* address of object-handle array	*/
BOOL fWaitAll;	/* wait for all or wait for one	*/
DWORD dwTimeout;	/* time-out interval in milliseconds	*/
DWORD fdwWakeMask;	/* type of input events to wait for	*/

The MsgWaitForMultipleObjects function returns when one of the following occurs:

Either any one or all of the specified objects are in the signaled state.

A specified type of input becomes available in the thread's input queue.

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.

Parameter	Description

cObjects	Specifies the number of object handles in the array pointed to by lphObjects. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS.

lphObjects	Points to an array of object handles. For a list of the object types whose handles can be specified, see the Comments section. The array can contain handles of objects of different types. The handles must have SYNCHRONIZE access.

fWaitAll	Specifies the wait type. If TRUE, the function returns when all objects in the lphObjects array are signaled at the same time. If FALSE, the function returns when any one of the objects is signaled. In the latter case, the return value indicates the object whose state caused the function to return.

dwTimeout	Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the conditions specified by the fWaitAll or fdwWakeMask parameter are not satisfied. If dwTimeout is zero, the function tests the states of the specified objects and returns immediately. If dwTimeout is INFINITE, the function's time-out interval never elapses.

fdwWakeMask	Specifies the types of input that will cause the function to return. 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.

Returns

If the function succeeds, the return value indicates the event that caused the function to return; otherwise, it is 0xFFFFFFFF. To get extended error information, use the GetLastError function.

The successful return value is one of the following:

Value	Meaning

WAIT_OBJECT_0 to (WAIT_OBJECT_0 + cObjects - 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 lphObjects array index of the object that satisfied the wait.

WAIT_OBJECT_0 + cObjects

Input of the type specified in the fdwWakeMask parameter is available in the thread's input queue.

WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + cObjects - 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 lphObjects 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 fdwWakeMask parameters were not satisfied.

Comments

The MsgWaitForMultipleObjects function determines whether the conditions exist that satisfy the wait. If the wait is not satisfied, the calling thread enters an efficient wait state, consuming very little processor time while waiting for one of the conditions of the wait to be satisfied.

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. For example, a mutex can be signaled, but the thread does not get ownership until the other objects are also signaled. In the meantime, some other thread may get ownership of the mutex, thereby delaying satisfaction of the condition.

The system adjusts the state of some types of objects after the object's signaled state satisfies a wait condition. 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 lphObjects array:

Object	Description

change notification	The handle is returned by the FindFirstChangeNotification function. 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 CONIN$ 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 handle is returned by the CreateEvent or OpenEvent function. 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 handle is returned by the CreateMutex or OpenMutex function. 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 handle is returned by the CreateProcess or OpenProcess function. A process object's state is signaled when the process terminates.

thread	The handle is returned by the CreateProcess, CreateThread, or CreateRemoteThread function. A thread object's state is signaled when the thread terminates.

semaphore	The handle is returned by the CreateSemaphore or OpenSemaphore function. 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.

In some circumstances, you can specify a handle of a file, named pipe, or communications device as a synchronization object in a wait function. However, their use for this purpose is discouraged. For more information, see Synchronization.

The following code fragment illustrates the use of MsgWaitForMultipleObjects in a main message loop that also needs to wait for one or more objects to become signalled :

int MessageLoop (

  HANDLE* lphObjects,  // handles that need to be waited on

  int     cObjects     // number of handles to wait on

  ){

  // message loop lasts until we get a WM_QUIT message

  // upon which we shall return from the function

  while (TRUE) {

    // block-local variable

    DWORD result ;

    // wait for any message sent or posted to this queue

    // or for one of the passed handles to become signalled

      result = MsgWaitForMultipleObjects(cObjects, lphObjects,

                                 FALSE, INFINITE, QS_ALLINPUT);

      // result tells us the type of event we have:

      // a message or a signalled handle

      // if there are one or more messages in the queue ...

      if (result == (WAIT_OBJECT_0 + 1)) {

         // block-local variable

         MSG msg ;

         // read all of the messages in this next loop

         // removing each message as we read it

         while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) {

            /* if it's a quit message we're out of here

            if (msg.message == WM_QUIT)  return 1;

            /* otherwise dispatch it */

            DispatchMessage(&msg);

         } // end of PeekMessage while loop

      } else {

         // one of the handles became signalled

         // deal with that

         DoStuff (result - WAIT_OBJECT_0) ;

      } // end of else-clause

   } // end of the always while-loop

} // end of function

See Also

Sleep, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject


OemKeyScan function
OemKeyScan (Win32)

DWORD OemKeyScan(wOemChar)

WORD wOemChar;	/* ASCII value of OEM character	*/

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.

Parameter	Description

wOemChar	Specifies the ASCII value of the OEM character.

Returns

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.

Comments

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


OemToChar function
OemToChar (Win32)

BOOL OemToChar(lpszOemStr, lpszStr)

LPCSTR lpszOemStr;	/* address of string to translate	*/
LPTSTR lpszStr;	/* address of buffer for translated string	*/

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

Parameter	Description

lpszOemStr	Points to a null-terminated string of characters from the OEM-defined character set.

lpszStr	Points to the buffer for the translated string. If the string buffer is large enough and the OemToChar function is being used as an ANSI function, the string can be translated in place by setting the lpszStr parameter to the same address as the lpszOemStr parameter. This cannot be done if OemToChar is being used as a wide-character function.

Returns

The return value is always TRUE.

See Also

CharToOem, CharToOemBuff, OemToCharBuff


OemToCharBuff function
OemToCharBuff (Win32)

BOOL OemToCharBuff(lpOemStr, lpszStr, cchString)

LPCSTR lpOemStr;	/* address of string to translate	*/
LPTSTR lpszStr;	/* address of buffer for translated string	*/
DWORD cchString;	/* size of buffer	*/

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

Parameter	Description

lpOemStr	Points to a buffer containing one or more characters from the OEM-defined character set.

lpszStr	Points to the buffer for the translated string. If the string buffer is large enough and the OemToCharBuff function is being used as an ANSI function, the string can be translated in place by setting the lpszStr parameter to the same address as the lpOemStr parameter. This cannot be done if the OemToCharBuff function is being used as a wide-character function.

cchString	Specifies the number of characters to translate in the buffer identified by the lpOemStr parameter.

Returns

The return value is always TRUE.

See Also

CharToOem, CharToOemBuff, OemToChar


OffsetRect function
OffsetRect (Win32)

BOOL OffsetRect(lprc, x, y)

LPRECT lprc;	/* address of structure with rectangle	*/
int x;	/* horizontal offset	*/
int y;	/* vertical offset	*/

The OffsetRect function moves the specified rectangle by the specified offsets.

Parameter	Description

lprc	Points to a RECT structure that contains the logical coordinates of the rectangle to be moved.

x	Specifies the amount to move the rectangle left or right. This parameter must be a negative value to move the rectangle to the left.

y	Specifies the amount to move the rectangle up or down. This parameter must be a negative value to move the rectangle up.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

InflateRect, IntersectRect, UnionRect, RECT


OpenClipboard function
OpenClipboard (Win32)

BOOL OpenClipboard(hwnd)

HWND hwnd;	/* handle of window opening clipboard	*/

The OpenClipboard function opens the clipboard for examination and prevents other applications from modifying the clipboard contents.

Parameter	Description

hwnd	Identifies the window to be associated with the open clipboard. If this parameter is NULL, the open clipboard is associated with the current task.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The OpenClipboard function fails if another window has the clipboard open.

An application should call the CloseClipboard function after every successful call to the OpenClipboard function.

The window identified by the hwnd parameter does not become the clipboard owner unless the EmptyClipboard function is called.

See Also

CloseClipboard, EmptyClipboard


OpenIcon function
OpenIcon (Win32)

BOOL OpenIcon(hwnd)

HWND hwnd;	/* handle of window	*/

The OpenIcon function restores a minimized (iconic) window to its previous size and position, and then activates it.

Parameter	Description

hwnd	Identifies the window to be restored and activated.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The OpenIcon function sends a WM_QUERYOPEN message to the given window.

See Also

CloseWindow, IsIconic, ShowWindow, WM_QUERYOPEN


PackDDElParam function
PackDDElParam (Win32)

LONG PackDDElParam(uMsg, uLow, uHigh)

UINT uMsg;	/* DDE message to be posted	*/
UINT uLow;	/* low-order word of lParam of message	*/
UINT uHigh;	/* high-order word of lParam of message	*/

The PackDDElParam function packs a dynamic data exchange (DDE) lParam value into an internal structure used for sharing DDE data between processes.

Parameter	Description

uMsg	Specifies the DDE message to be posted.

uLow	Specifies a value that corresponds to the Windows 3.x low-order word of an lParam parameter for the DDE message being posted.

uHigh	Specifies a value that corresponds to the Windows 3.x high-order word of an lParam parameter for the DDE message being posted.

Returns

If the function succeeds, the return value is nonzero; otherwise, it is zero.

Comments

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.

The PackDDElParam function 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


PeekMessage function
PeekMessage (Win32)

BOOL PeekMessage(lpmsg, hwnd, uMsgFilterMin, uMsgFilterMax, fuRemoveMsg)

LPMSG lpmsg;	/* address of structure for message	*/
HWND hwnd;	/* handle of window	*/
UINT uMsgFilterMin;	/* first message	*/
UINT uMsgFilterMax;	/* last message	*/
UINT fuRemoveMsg;	/* removal flags	*/

The PeekMessage function checks a thread message queue for a message and places the message (if any) in the specified structure.

Parameter	Description

lpmsg	Points to an MSG structure that contains message information from the Windows application queue.

hwnd	Identifies the window whose messages are to be examined.

uMsgFilterMin	Specifies the value of the first message in the range of messages to be examined.

uMsgFilterMax	Specifies the value of the last message in the range of messages to be examined.

fuRemoveMsg	Specifies whether the message should be removed from the queue. This parameter must be one of the following values:

Value	Meaning

PM_NOREMOVE	The message is not removed from the queue after processing by PeekMessage.

PM_REMOVE	The message is removed from the queue after processing by PeekMessage.

Returns

If a message is available, the return value is TRUE; otherwise, it is FALSE.

Comments

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 uMsgFilterMin and uMsgFilterMax 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 uMsgFilterMin and uMsgFilterMax are both zero, PeekMessage returns all available messages (no range filtering is performed).

The WM_KEYFIRST and WM_KEYLAST flags can be used as filter values to retrieve all keyboard messages; the WM_MOUSEFIRST and WM_MOUSELAST flags can be used to retrieve all mouse messages.

PeekMessage does not remove WM_PAINT messages from the queue. The messages remain in the queue until they are processed.

See Also

GetMessage, IsChild, PostAppMessage, WaitMessage


PostMessage function
PostMessage (Win32)

BOOL PostMessage(hwnd, uMsg, wParam, lParam)

HWND hwnd;	/* handle of destination window	*/
UINT uMsg;	/* message to post	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The PostMessage function places (posts) a message in the message queue associated with the thread that created the given 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.

Parameter	Description

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 popup windows. The message is not posted to child windows.

NULL	The function behaves like a call to PostThreadMessage with dwThreadId set to the identifier of the current thread.

uMsg	Specifies the message to be posted.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

A 32-bit application should not post messages less than WM_USER that contain pointers.

See Also

GetMessage, PeekMessage, PostThreadMessage, SendDlgItemMessage, SendMessage


PostQuitMessage function
PostQuitMessage (Win32)

VOID PostQuitMessage(nExitCode)

int nExitCode;	/* exit code	*/

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.

Parameter	Description

nExitCode	Specifies an application exit code. This code is used as the wParam parameter of the WM_QUIT message.

Returns

This function does not return a value.

Comments

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 code returned to Windows must be the wParam parameter of the WM_QUIT message.

See Also

GetMessage, PeekMessage, PostMessage


PostThreadMessage function
PostThreadMessage (Win32)

BOOL PostThreadMessage(dwThreadId, uMsg, wParam, lParam)

DWORD dwThreadId;	/* thread identifier	*/
UINT uMsg;	/* message to post	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The PostThreadMessage function places (posts) a message in the message queue of the given thread and then returns without waiting for the thread to process the message.

Parameter	Description

dwThreadId	Identifies the thread to which the message will be posted.

uMsg	Specifies the type of message to be posted.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

This function replaces the PostAppMessage function. New Win32 applications should use PostThreadMessage, instead. 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, PeekMessage, PostMessage, MSG


ProfClear function
ProfClear (Win32)

The ProfClear function has been deleted from the Win32 API.


ProfFinish function
ProfFinish (Win32)

The ProfFinish function has been deleted from the Win32 API.


ProfFlush function
ProfFlush (Win32)

The ProfFlush function has been deleted from the Win32 API.


ProfInsChk function
ProfInsChk (Win32)

The ProfInsChk function has been deleted from the Win32 API.


ProfSampRate function
ProfSampRate (Win32)

The ProfSampRate function has been deleted from the Win32 API.


ProfSetup function
ProfSetup (Win32)

The ProfSetup function has been deleted from the Win32 API.


ProfStart function
ProfStart (Win32)

The ProfStart function has been deleted from the Win32 API.


ProfStop function
ProfStop (Win32)

The ProfStop function has been deleted from the Win32 API.


PtInRect function
PtInRect (Win32)

BOOL PtInRect(lprc, pt)

CONST RECT *lprc;	/* address of structure with rectangle	*/
POINT pt;	/* structure with point	*/

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.

Parameter	Description

lprc	Points to a RECT structure that contains the specified rectangle.

pt	Specifies a POINT structure that contains the specified point.

Returns

If the specified point lies within the rectangle, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

EqualRect, IsRectEmpty, POINT, RECT


RedrawWindow function
RedrawWindow (Win32)

BOOL RedrawWindow(hwnd, lprcUpdate, hrgnUpdate, afuRedraw)

HWND hwnd;	/* handle of window	*/
CONST RECT *lprcUpdate;	/* address of structure with update rectangle	*/
HRGN hrgnUpdate;	/* handle of update region	*/
UINT afuRedraw;	/* array of redraw flags	*/

The RedrawWindow function updates the given rectangle or region in a window's client area.

Parameter	Description

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.

afuRedraw	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	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	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 not belonging to the WS_CLIPCHILDREN style windows are not affected; however, 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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, UpdateWindow, WM_ERASEBKGND, WM_PAINT, WM_PAINTICON


RegisterClass function
RegisterClass (Win32)

ATOM RegisterClass(lpwc)

CONST WNDCLASS *lpwc;	/* address of structure with class data	*/

The RegisterClass function registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function.

Parameter	Description

lpwc	Points to a WNDCLASS structure. You must fill the structure with the appropriate class attributes before passing it to the function.

Returns

If the function succeeds, the return value is an atom that uniquely identifies the class being registered; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

All window classes registered by an application are unregistered when it terminates.

See Also

CreateWindow, CreateWindowEx, GetClassInfo, GetClassName, UnregisterClass, WindowProc, WNDCLASS


RegisterClipboardFormat function
RegisterClipboardFormat (Win32)

UINT RegisterClipboardFormat(lpszFormat)

LPCTSTR lpszFormat;	/* address of name string	*/

The RegisterClipboardFormat function registers a new clipboard format. This format can then be used as a valid clipboard format.

Parameter	Description

lpszFormat	Points to a null-terminated string that names the new format.

Returns

If the function succeeds, the return value identifies the registered clipboard format; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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.

Registered clipboard formats are identified by values in the range 0xC000 through 0xFFFF.

See Also

CountClipboardFormats, EnumClipboardFormats, GetClipboardFormatName


RegisterHotKey function
RegisterHotKey (Win32)

BOOL RegisterHotKey(hwnd, idHotKey, fuModifiers, uVirtKey)

HWND hwnd;	/* window to receive hot-key notification	*/
int idHotKey;	/* identifier of hot key	*/
UINT fuModifiers;	/* key-modifier flags	*/
UINT uVirtKey;	/* virtual-key code	*/

The RegisterHotKey function defines a hot key for the current thread.

Parameter	Description

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.

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

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

uVirtKey	Specifies the virtual-key code of the hot key.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 idHotKey parameter, the new values for the fuModifiers and uVirtKey parameters replace the previously specified values for these parameters.

See Also

UnregisterHotKey, WM_HOTKEY


RegisterWindowMessage function
RegisterWindowMessage (Win32)

UINT RegisterWindowMessage(lpsz)

LPCTSTR lpsz;	/* address of message string	*/

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.

Parameter	Description

lpsz	Points to a null-terminated string that specifies the message to be registered.

Returns

If the message is successfully registered, the return value is a message identifier in the range 0xC000 through 0xFFFF; otherwise, it is zero.

Comments

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 the RegisterWindowMessage function 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


ReleaseCapture function
ReleaseCapture (Win32)

BOOL ReleaseCapture(VOID)

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

An application calls this function after calling the SetCapture function.

See Also

GetCapture, SetCapture


ReleaseDC function
ReleaseDC (Win32)

int ReleaseDC(hwnd, hdc)

HWND hwnd;	/* handle of window	*/
HDC hdc;	/* handle of device context	*/

The RealeaseDC 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 DCs. It has no effect on class or private DCs.

Parameter	Description

hwnd	Identifies the window whose DC is to be released.

hdc	Identifies the DC to be released.

Returns

The return value specifies whether the DC is released. It is 1 if the DC is released. Otherwise, it is zero.

Comments

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

An application cannot use the ReleaseDC function to release a DC that was created by calling the CreateDC function; instead, it must use the DeleteDC function.

See Also

CreateDC, DeleteDC, GetDC, GetWindowDC


RemoveMenu function
RemoveMenu (Win32)

BOOL RemoveMenu(hmenu, uItem, fuFlags)

HMENU hmenu;	/* handle of menu	*/
UINT uItem;	/* menu item identifier or position	*/
UINT fuFlags;	/* menu item flag	*/

The RemoveMenu function deletes a menu item from the given menu. If the menu item activates a pop-up menu, RemoveMenu does not destroy the pop-up menu or its handle, allowing the menu to be reused. Before this function is called, the GetSubMenu function should retrieve the handle of the pop-up menu.

Parameter	Description

hmenu	Identifies the menu to be changed.

uItem	Specifies the menu item to be deleted, as determined by the fuFlags parameter.

fuFlags	Specifies how the uItem parameter is interpreted. This parameter must be one of the following values:

Value	Meaning

MF_BYCOMMAND	Indicates that the uItem 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 uItem parameter gives the zero-based relative position of the menu item.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
RemoveProp (Win32)

HANDLE RemoveProp(hwnd, lpsz)

HWND hwnd;	/* handle of window	*/
LPCTSTR lpsz;	/* atom or address of string	*/

The RemoveProp function removes an entry from the property list of the given window. The given character string identifies the entry to be removed.

Parameter	Description

hwnd	Identifies the window whose property list is to be changed.

lpsz	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 lpsz; the high-order word must be zero.

Returns

If the function succeeds, the return value identifies the given string. If the string cannot be found in the given property list, the return value is NULL.

Comments

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


ReplyMessage function
ReplyMessage (Win32)

BOOL ReplyMessage(lResult)

LRESULT lResult;	/* message-dependent reply	*/

The ReplyMessage function is used to reply to a message sent through the SendMessage function without returning control to the function that called SendMessage.

Parameter	Description

lResult	Specifies the result of the message processing. The possible values are based on the message sent.

Returns

If the calling thread was processing a message sent from another thread or process, the return value is TRUE; otherwise, it is FALSE.

Comments

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 the SendMessage function or if the message was sent by the same thread, ReplyMessage has no effect.

See Also

InSendMessage, SendMessage


ReuseDDElParam function
ReuseDDElParam (Win32)

LONG ReuseDDElParam(lParam, uMsgIn, uMsgOut, uLow, uHigh)

LONG lParam;	/* posted lParam to be reused	*/
UINT uMsgIn;	/* identifier of received message	*/
UINT uMsgOut;	/* identifier of posted message	*/
UINT uLow;	/* low-order word of new lParam	*/
UINT uHigh;	/* high-order word of new lParam	*/

The ReuseDDElParam function allows an application to reuse a packed dynamic data exchange (DDE) lParam parameter, rather than allocating a new packed lParam parameter. Using this function reduces reallocations for applications that pass packed DDE messages.

Parameter	Description

lParam	Specifies the lParam parameter of the posted DDE message being reused.

uMsgIn	Specifies the identifier of the received DDE message.

uMsgOut	Specifies the identifier of the DDE message to be posted. The DDE message will reuse the packed lParam parameter.

uLow	Specifies the value to be packed into the low-order word of the reused lParam parameter.

uHigh	Specifies the value to be packed into the high-order word of the reused lParam parameter.

Returns

If the function succeeds, the return value is nonzero; otherwise, it is zero.

Comments

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 the ReuseDDElParam function instead of the FreeDDElParam function 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


ScreenToClient function
ScreenToClient (Win32)

BOOL ScreenToClient(hwnd, lpPoint)

HWND hwnd;	/* window handle for source coordinates	*/
LPPOINT lpPoint;	/* address of structure containing coordinates	*/

The ScreenToClient function converts the screen coordinates of a specified point on the screen to client coordinates.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 given window's client area.

The ScreenToClient function assumes the given point is in screen coordinates.

See Also

ClientToScreen, MapWindowPoints, POINT


ScrollDC function
ScrollDC (Win32)

BOOL ScrollDC(hdc, dx, dy, lprcScroll, lprcClip, hrgnUpdate, lprcUpdate)

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

The ScrollDC function scrolls a rectangle of bits horizontally and vertically.

Parameter	Description

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. The ScrollDC function 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 given device context. This allows applications to use the update region in a call to the InvalidateRgn function, if required.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 the ScrollDC function).

When you must scroll the entire client area of a window, use the ScrollWindow function; otherwise, use ScrollDC.

See Also

InvalidateRgn, ScrollWindow, RECT


ScrollWindow function
ScrollWindow (Win32)

BOOL ScrollWindow(hwnd, dx, dy, lprcScroll, lprcClip)

HWND hwnd;	/* handle of window to scroll	*/
int dx;	/* amount of horizontal scrolling	*/
int dy;	/* amount of vertical scrolling	*/
CONST RECT * lprcScroll;	/* address of structure with scroll rectangle	*/
CONST RECT * lprcClip;	/* address of structure with clip rectangle	*/

The ScrollWindow function scrolls the contents of the given window's client area.

Parameter	Description

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 the contents of the window to the left.

dy	Specifies the amount, in device units, of vertical scrolling. This parameter must be a negative value to scroll the contents of the window up.

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

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If the caret is in the window being scrolled, the ScrollWindow function 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 lprcScroll parameter is NULL, the positions of any child windows in the window are offset by the amount specified by the dx and dy parameters; invalid (unpainted) areas in the window are also offset. ScrollWindow is faster when lprcScroll is NULL.

If lprcScroll 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 lprcScroll is not NULL, call UpdateWindow to repaint the window before calling ScrollWindow.

See Also

ScrollDC, ScrollWindowEx, UpdateWindow, RECT


ScrollWindowEx function
ScrollWindowEx (Win32)

int ScrollWindowEx(hwnd, dx, dy, lprcScroll, lprcClip, hrgnUpdate, lprcUpdate, fuScroll)

HWND hwnd;	/* handle of window to scroll	*/
int dx;	/* amount of horizontal scrolling	*/
int dy;	/* amount of vertical scrolling	*/
CONST RECT *lprcScroll;	/* address of structure with scroll rectangle	*/
CONST RECT *lprcClip;	/* address of structure with clip rectangle	*/
HRGN hrgnUpdate;	/* handle of update region	*/
LPRECT lprcUpdate;	/* address of structure for update rectangle	*/
UINT fuScroll;	/* scrolling flags	*/

The ScrollWindowEx function scrolls the contents of the given window's client area. This function is similar to the ScrollWindow function, but it has additional features.

Parameter	Description

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.

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

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 that is modified to hold the region invalidated by scrolling. This parameter may be NULL.

lprcUpdate	Points to the RECT structure receiving the boundaries of the rectangle invalidated by scrolling. This parameter may be NULL.

fuScroll	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 lprcScroll 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 lprcScroll rectangle, even if they do not move.

Returns

If the function succeeds, the return value is SIMPLEREGION (rectangular invalidated region), COMPLEXREGION (nonrectangular invalidated region; overlapping rectangles), or NULLREGION (no invalidated region). Otherwise, the return value is ERROR.

Comments

If the SW_INVALIDATE and SW_ERASE flags are not specified, the ScrollWindowEx function does not invalidate the area that is scrolled away 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 the hrgnUpdate and lprcUpdate parameters 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 redrawn properly in its new destination. To move child windows that do not lie completely within the rectangle specified by the lprcScroll parameter, 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 the lprcScroll, lprcClip, lprcUpdate, and hrgnUpdate parameters) 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, RedrawWindow, ScrollDC, ScrollWindow, UpdateWindow, RECT


SendDlgItemMessage function
SendDlgItemMessage (Win32)

LONG SendDlgItemMessage(hwndDlg, idControl, uMsg, wParam, lParam)

HWND hwndDlg;	/* handle of dialog box	*/
int idControl;	/* identifier of control	*/
UINT uMsg;	/* message to send	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The SendDlgItemMessage function sends a message to the specified control in the given dialog box.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the control.

idControl	Specifies the identifier of the control that receives the message.

uMsg	Specifies the message to be sent.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

The return value specifies the result of the message processing and depends on the message sent.

Comments

The SendDlgItemMessage function does not return until the message has been processed.

Using SendDlgItemMessage is identical to retrieving a handle of the given control and calling the SendMessage function.

See Also

SendMessage


SendMessage function
SendMessage (Win32)

LRESULT SendMessage(hwnd, uMsg, wParam, lParam)

HWND hwnd;	/* handle of destination window	*/
UINT uMsg;	/* message to send	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The SendMessage function sends the specified message to the given window or windows. The function calls the window procedure for the given 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.

Parameter	Description

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 popup windows; but the message is not sent to child windows.

uMsg	Specifies the message to be sent.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

The return value specifies the result of the message processing and depends on the message sent.

Comments

If the given window was created by the calling thread, the window procedure is called immediately as a subroutine. If the given window was created by a different thread, Windows switches to that thread and calls the appropriate window procedure.

See Also

InSendMessage, PostMessage, SendDlgItemMessage


SendMessageCallback function
SendMessageCallback (Win32)

BOOL SendMessageCallback(hwnd, uMsg, wParam, lParam, lpResultCallBack, dwData)

HWND hwnd;	/* handle of destination window	*/
UINT uMsg;	/* 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	*/

The SendMessageCallback function sends the specified message to the given window or windows. The function calls the window procedure for the given 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.

Parameter	Description

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 popup windows; but the message is not sent to child windows.

uMsg	Specifies the message to be sent.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

lpfnResultCallBack	Points to a callback function that the system calls after the window procedure processes the message. See SendAsyncProc for information on suitable callback functions.

dwData	Specifies an application-defined value to be sent to the callback function pointed to by the lpfnResultCallBack parameter.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

InSendMessage, PostMessage, SendAsyncProc, SendDlgItemMessage, SendMessage, SendMessageTimeout, SendNotifyMessage


SendMessageTimeout function
SendMessageTimeout (Win32)

LRESULT SendMessageTimeout(hwnd, uMsg, wParam, lParam, wFlags, uTimeout, lpdwResult)

HWND hwnd;	/* handle of destination window	*/
UINT uMsg;	/* 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	*/

The SendMessageTimeout function sends the specified message to the given window or windows. The function calls the window procedure for the given window and does not return until the window procedure has processed the message or the specified time-out period has elapsed.

Parameter	Description

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.

uMsg	Specifies the message to be sent.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent 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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

InSendMessage, PostMessage, SendDlgItemMessage, SendMessage, SendMessageCallback, SendNotifyMessage


SendNotifyMessage function
SendNotifyMessage (Win32)

BOOL SendNotifyMessage(hwnd, uMsg, wParam, lParam)

HWND hwnd;	/* handle of destination window	*/
UINT uMsg;	/* message to send	*/
WPARAM wParam;	/* first message parameter	*/
LPARAM lParam;	/* second message parameter	*/

The SendNotifyMessage function sends the specified message to the given 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.

Parameter	Description

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 popup windows; but the message is not sent to child windows.

uMsg	Specifies the message to be sent.

wParam	Specifies additional message-dependent information.

lParam	Specifies additional message-dependent information.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

PostMessage, PostThreadMessage, SendMessage


SetActiveWindow function
SetActiveWindow (Win32)

HWND SetActiveWindow(hwnd)

HWND hwnd;	/* handle of window to activate	*/

The SetActiveWindow function makes the given top-level window associated with the thread calling this function the active window.

Parameter	Description

hwnd	Identifies the top-level window to be activated.

Returns

If the function succeeds, the return value is the handle of the window that was previously active.

Comments

Applications must use the SetActiveWindow function carefully, because the function allows an application to arbitrarily take over the active window and keyboard focus. Usually, Windows takes care of all 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, and the active window status of the thread that created the window is set to hwnd.

The SetActiveWindow function activates a window, but it only brings the window to the foreground if the window is owned by the thread making the SetActiveWindow call.

The SetForegroundWindow window function, on the other hand, activates a window and forces the thread that created the window into the foreground. An application should call SetForegroundWindow if it wants to put itself into the foreground.

See Also

GetActiveWindow, SetForegroundWindow, WM_ACTIVATE


SetCapture function
SetCapture (Win32)

HWND SetCapture(hwnd)

HWND hwnd;	/* handle of window to receive mouse capture	*/

The SetCapture function sets the mouse capture to the given 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 given window only if a mouse button is down.

Parameter	Description

hwnd	Identifies the window in the current thread that is to capture the mouse.

Returns

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.

Comments

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.

See Also

GetCapture, ReleaseCapture


SetCaretBlinkTime function
SetCaretBlinkTime (Win32)

BOOL SetCaretBlinkTime(wMSeconds)

UINT wMSeconds;	/* blink time, in milliseconds	*/

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.

Parameter	Description

wMSeconds	Specifies the new blink time, in milliseconds.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The caret is a shared resource; there is only one caret in the system. A window should set the caret blink time only if it owns the caret. The window should restore the previous blink time before losing the keyboard focus or becoming inactive.

See Also

GetCaretBlinkTime


SetCaretPos function
SetCaretPos (Win32)

BOOL SetCaretPos(nX, nY)

int nX;	/* horizontal position	*/
int nY;	/* vertical position	*/

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.

Parameter	Description

nX	Specifies the new x-coordinate of the caret.

nY	Specifies the new y-coordinate of the caret.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
SetClassLong (Win32)

DWORD SetClassLong(hwnd, nIndex, lNewVal)

HWND hwnd;	/* handle of window	*/
int nIndex;	/* index of value to change	*/
LONG lNewVal;	/* new value	*/

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 given window belongs.

Parameter	Description

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 the descriptions of the SetWindowLong and SetWindowWord functions.

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.

lNewVal	Specifies the replacement value.

Returns

If the function succeeds, the return value is the previous value of the specified 32-bit integer; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

If you use the SetClassLong function and the GCL_WNDPROC index to replace the window procedure, the given 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 cannot 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 function
SetClassWord (Win32)

WORD SetClassWord(hwnd, nIndex, wNewWord)

HWND hwnd;	/* handle of window	*/
int nIndex;	/* index of value to change	*/
WORD wNewWord;	/* new value	*/

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 given window belongs.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the previous value of the specified 16-bit integer; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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 application programming interface (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 function
SetClipboardData (Win32)

HANDLE SetClipboardData(uFormat, hData)

UINT uFormat;	/* clipboard format	*/
HANDLE hData;	/* data handle	*/

The SetClipboardData function places data on the clipboard in the 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.)

Parameter	Description

uFormat	Specifies a clipboard format. This parameter can be a registered format or any of the standard clipboard formats listed in the Comments section. For information about registered clipboard formats, see the RegisterClipboardFormat function.

hData	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) on request. If a window delays rendering, it must process the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages.

Returns

If the function succeeds, the return value is the handle of the data; otherwise, the return value is NULL. To get extended error information, use the GetLastError function.

Comments

Once the hData parameter has been passed to SetClipboardData, it is owned by the system. The application can read the data, but must not free the handle or leave it locked.

If hData is a memory handle, it must be allocated by using the GlobalAlloc function with the GMEM_MOVEABLE and GMEM_DDESHARE flags.

The uFormat parameter can identify a registered clipboard format, or it can be one of the following values:

Value	Meaning

CF_BITMAP

A handle of 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 hData 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 hData 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 hData 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 hData 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_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 hData 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 hData 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 in 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 Windows operating system.

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.

CF_WAVE

Represents audio data in one of the standard wave formats, such as 11 kHz or 22 kHz PCM.

CF_TIFF

Tag image file format.

CF_UNICODETEXT

Unicode text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.

Windows supports three clipboard formats for text: CF_UNICODETEXT, CF_TEXT, and CF_OEMTEXT. Specify CF_TEXT for ANSI text, CF_UNICODETEXT for Unicode text, and CF_OEMTEXT for text in the OEM character set. If any of the three text formats is placed on the clipboard, all three can be retrieved by using the GetClipboardData function. If necessary, Windows automatically converts data in an available text format to the requested format. An application can place more than one text format on the clipboard if it does so at one time (between the same calls to OpenClipboard and CloseClipboard).

Windows supports two clipboard formats for metafiles: CF_ENHMETAFILE and CF_METAFILEPICT. Specify CF_ENHMETAFILE for enhanced metafiles and CF_METAFILEPICT for Windows metafiles. If either of the two metafile formats is placed on the clipboard, both can be retrieved by GetClipboardData. If necessary, Windows automatically converts data in the available metafile format to the requested format. An application can place both metafile formats on the clipboard if it does so at one time (between the same calls to OpenClipboard and CloseClipboard).

See Also

GetClipboardData, RegisterClipboardFormat, BITMAPINFO, METAFILEPICT


SetClipboardViewer function
SetClipboardViewer (Win32)

HWND SetClipboardViewer(hwnd)

HWND hwnd;	/* handle of clipboard viewer	*/

The SetClipboardViewer function adds the specified window to the chain of clipboard viewers. Clipboard viewer windows receive a WM_DRAWCLIPBOARD message whenever the contents of the clipboard change.

Parameter	Description

hwnd	Identifies the window to be added to the clipboard chain.

Returns

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, use the GetLastError information.

Comments

Windows that are part of the clipboard viewer chain, called clipboard viewer windows, must process the clipboard notification 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


SetCursor function
SetCursor (Win32)

HCURSOR SetCursor(hcur)

HCURSOR hcur;	/* handle of cursor	*/

The SetCursor function establishes the cursor shape.

Parameter	Description

hcur	Identifies the cursor. The cursor must have been loaded by the LoadCursor function or created by the CreateCursor function. If this parameter is NULL, the cursor is removed from the screen.

Returns

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.

Comments

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 given 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

LoadCursor, SetCursorPos, ShowCursor


SetCursorPos function
SetCursorPos (Win32)

BOOL SetCursorPos(X, Y)

int X;	/* horizontal position	*/
int Y;	/* vertical position	*/

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.

Parameter	Description

X	Specifies the new x-coordinate (in screen coordinates) of the cursor.

Y	Specifies the new y-coordinate (in screen coordinates) of the cursor.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


SetDlgItemInt function
SetDlgItemInt (Win32)

BOOL SetDlgItemInt(hwndDlg, idControl, uValue, fSigned)

HWND hwndDlg;	/* handle of dialog box	*/
int idControl;	/* identifier of control	*/
UINT uValue;	/* value to set	*/
BOOL fSigned;	/* signed or unsigned indicator	*/

The SetDlgItemInt function sets the text of a given control in a dialog box to the string representation of a given integer value.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the control.

idControl	Specifies the control to be changed.

uValue	Specifies the integer value used to generate the item text.

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

Returns

If the function succeeds, the return value is TRUE; otherwise it is FALSE. Use the GetLastError function to obtain extended error information.

Comments

To set the new text, this function sends a WM_SETTEXT message to the given control.

See Also

GetDlgItemInt, SetDlgItemText, WM_SETTEXT


SetDlgItemText function
SetDlgItemText (Win32)

BOOL SetDlgItemText(hwndDlg, idControl, lpsz)

HWND hwndDlg;	/* handle of dialog box	*/
int idControl;	/* identifier of control	*/
LPCTSTR lpsz;	/* text to set	*/

The SetDlgItemText function sets the title or text of a control in a dialog box.

Parameter	Description

hwndDlg	Identifies the dialog box that contains the control.

idControl	Identifies the control whose title or text is to be set.

lpsz	Points to the null-terminated string that contains the text to be copied to the control.

Returns

If the function succeeds, the return value is TRUE; otherwise it is FALSE. Use the GetLastError function to get extended error information.

Comments

The SetDlgItemText function sends a WM_SETTEXT message to the given control.

See Also

GetDlgItemText, GetDlgItemInt, SetDlgItemInt, WM_SETTEXT


SetDoubleClickTime function
SetDoubleClickTime (Win32)

BOOL SetDoubleClickTime(uInterval)

UINT uInterval;	/* double-click interval	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The SetDoubleClickTime function alters the double-click time for all windows in the system.

See Also

GetDoubleClickTime


SetFocus function
SetFocus (Win32)

HWND SetFocus(hwnd)

HWND hwnd;	/* handle of window to receive focus	*/

The SetFocus function sets the keyboard focus to the given window. All subsequent keyboard input is directed to this window. The window, if any, that previously had the keyboard focus loses it.

Parameter	Description

hwnd	Identifies the window that will receive the keyboard input. If this parameter is NULL, keystrokes are ignored.

Returns

If the function succeeds, the return value is the handle of the window that previously had the keyboard focus. If there is no such window or if the hwnd parameter is invalid, the return value is NULL.

Comments

If the window identified by the hwnd parameter was created by the calling thread, the keyboard-focus status of the calling thread is set to hwnd.

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 (that is, no window has 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.

If an application is not in the foreground, and wants to be in the foreground, it should call SetForegroundWindow.

See Also

GetActiveWindow, GetFocus, SetActiveWindow, SetCapture, SetForegroundWindow, WM_KILLFOCUS, WM_SETFOCUS, WM_SYSCHAR, WM_SYSKEYDOWN, WM_SYSKEYUP


SetForegroundWindow function
SetForegroundWindow (Win32)

BOOL SetForegroundWindow(hwnd)

HWND hwnd;	/* handle of window to bring to foreground	*/

The SetForegroundWindow function puts the thread that created the given window into the foreground and activates the window. Keyboard input is directed to the window, and various visual cues are changed for the user.

Parameter	Description

hwnd	Identifies the window that should be activated and brought to the foreground.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The foreground window is the window at the top of the z-order. It is the window that the user is working with. The system assigns a slightly higher priority to the thread that created the foreground window than it does to other threads.

SetForegroundWindow activates a window and forces the thread that created the window into the foreground.

An application should call SetForegroundWindow if it wants to put itself into the foreground. A good example is a debugger when it hits a breakpoint.

Unlike SetForegroundWindow, the SetActiveWindow function activates a window, but it only brings the window to the foreground if the window is owned by the thread making the SetActiveWindow call.

See Also

GetForegroundWindow, SetActiveWindow


SetKeyboardState function
SetKeyboardState (Win32)

BOOL SetKeyboardState(lpbKeyState)

LPBYTE lpbKeyState;	/* address of array with virtual-key codes	*/

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.

Parameter	Description

lpbKeyState	Points to a 256-byte array that contains keyboard key states.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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.

For a complete table of virtual key codes, see Virtual Key Codes.

See Also

GetKeyboardState, GetKeyState, GetAsyncKeyState, MapVirtualKey


SetMenu function
SetMenu (Win32)

BOOL SetMenu(hwnd, hmenu)

HWND hwnd;	/* handle of window	*/
HMENU hmenu;	/* handle of menu	*/

The SetMenu function assigns a new menu to the given window.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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


SetMenuItemBitmaps function
SetMenuItemBitmaps (Win32)

BOOL SetMenuItemBitmaps(hmenu, uItem, fuFlags, hbmUnchecked, hbmChecked)

HMENU hmenu;	/* handle of menu	*/
UINT uItem;	/* menu item to receive new bitmaps	*/
UINT fuFlags;	/* menu item flags	*/
HBITMAP hbmUnchecked;	/* handle of unchecked bitmap	*/
HBITMAP hbmChecked;	/* handle of checked bitmap	*/

The SetMenuItemBitmaps function associates the given bitmap with a menu item. Whether the menu item is checked or unchecked, Windows displays the appropriate bitmap next to the menu item.

Parameter	Description

hmenu	Identifies the menu containing the item to receive new check mark bitmaps.

uItem	Specifies the menu item to be changed, as determined by the fuFlags parameter.

fuFlags	Specifies how the uItem parameter is interpreted. The fuFlags parameter must be one of the following values:

Value	Meaning

MF_BYCOMMAND	Indicates that the uItem parameter gives the identifier of the menu item. MF_BYCOMMAND is the default if neither MF_BYCOMMAND nor MF_BYPOSITION is specified.

MF_BYPOSITION	Indicates that the uItem parameter gives the zero-based relative position of the menu item.

hbmUnchecked	Identifies the bitmap displayed when the menu item is not checked.

hbmChecked	Identifies the bitmap displayed when the menu item is checked.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

If either the hbmUnchecked or hbmChecked 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.

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.

See Also

CheckMarkDimensions, GetMenu


SetMessageQueue function
SetMessageQueue (Win32)

BOOL SetMessageQueue(cMessagesMax)

int cMessagesMax;	/* size of message queue	*/

The SetMessageQueue function creates a new message queue. It is useful in Win 3.x applications that require a queue that contains more than eight messages (the maximum size of the default queue). It does nothing under Windows NT, since queues are expanded dynamically as necessary.


SetParent function
SetParent (Win32)

HWND SetParent(hwndChild, hwndNewParent)

HWND hwndChild;	/* handle of window whose parent is changing	*/
HWND hwndNewParent;	/* handle of new parent window	*/

The SetParent function changes the parent window of the given child window.

Parameter	Description

hwndChild	Identifies the child window.

hwndNewParent	Identifies the new parent window. If this parameter is NULL, the desktop window becomes the new parent window.

Returns

If the function succeeds, the return value is the handle of the previous parent window; otherwise, the return value is NULL. To get extended error information, use the GetLastError function.

Comments

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


SetProp function
SetProp (Win32)

BOOL SetProp(hwnd, lpsz, hData)

HWND hwnd;	/* handle of window	*/
LPCTSTR lpsz;	/* atom or address of string	*/
HANDLE hData;	/* handle of data	*/

The SetProp function adds a new entry or changes an existing entry in the property list of the given window. The function adds a new entry to the list if the given 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 given handle.

Parameter	Description

hwnd	Identifies the window whose property list receives the new entry.

lpsz	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 lpsz; 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.

Returns

If the data handle and string are added to the property list, the return value is TRUE; otherwise, it is FALSE.

Comments

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 function
SetRect (Win32)

BOOL SetRect(lprc, nLeft, nTop, nRight, nBottom)

LPRECT lprc;	/* address of structure with rectangle to set	*/
int nLeft;	/* left side	*/
int nTop;	/* top side	*/
int nRight;	/* right side	*/
int nBottom;	/* bottom side	*/

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.

Parameter	Description

lprc	Points to the RECT structure that contains the rectangle to be set.

nLeft	Specifies the x-coordinate of the rectangle's upper left corner.

nTop	Specifies the y-coordinate of the rectangle's upper left corner.

nRight	Specifies the x-coordinate of the rectangle's lower right corner.

nBottom	Specifies the y-coordinate of the rectangle's lower right corner.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CopyRect, SetRectEmpty, RECT


SetRectEmpty function
SetRectEmpty (Win32)

BOOL SetRectEmpty(lprc)

LPRECT lprc;	/* address of struct. with rectangle to set to empty	*/

The SetRectEmpty function creates an empty rectangle in which all coordinates are set to zero.

Parameter	Description

lprc	Points to the RECT structure that contains the coordinates of the rectangle.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CopyRect, SetRect, RECT


SetScrollPos function
SetScrollPos (Win32)

int SetScrollPos(hwnd, fnBar, nPos, fRedraw)

HWND hwnd;	/* handle of window with scroll bar	*/
int fnBar;	/* scroll bar flag	*/
int nPos;	/* new position of scroll box	*/
BOOL fRedraw;	/* redraw flag	*/

The SetScrollPos function sets the position of the scroll box (thumb) in the given scroll bar and, if requested, redraws the scroll bar to reflect the new position of the scroll box.

Parameter	Description

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 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 description of the SetScrollRange function.

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

Returns

If the function succeeds, the return value is the previous position of the scroll box; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

Setting the fRedraw parameter to FALSE is useful if the scroll bar is redrawn by a subsequent call to another function.

Since the messages that indicate scrollbar position are limited to 16 bits, there is a practical maximum value of 65535 for the nPos parameter.

Since the messages that indicate scrollbar 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 65535 for the SetScrollPos function's nPos parameter.

However, since SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange support 32-bit scrollbar position data, there is a way to circumvent the WM_*SCROLL messages' 16 bits barrier. See GetScrollPos or for a description of the technique and its limits.

See Also

GetScrollPos, GetScrollRange, ScrollDC, ScrollWindow, SetScrollRange


SetScrollRange function
SetScrollRange (Win32)

BOOL SetScrollRange(hwnd, fnBar, nMinPos, nMaxPos, fRedraw)

HWND hwnd;	/* handle of window with scroll bar	*/
int fnBar;	/* scroll bar flag	*/
int nMinPos;	/* minimum scrolling position	*/
int nMaxPos;	/* maximum scrolling position	*/
BOOL fRedraw;	/* redraw flag	*/

The SetScrollRange function sets the minimum and maximum position values for the given scroll bar. It can also be used to hide or show a standard scroll bar.

Parameter	Description

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

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

Returns

If the function succeeds, the return value is TRUE; otherwise it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 fRedraw 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 values are zero). The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than the value of MAXLONG.

Since the messages that indicate scrollbar 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 65535 for the SetScrollRange function's nMaxPos parameter.

However, since SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange support 32-bit scrollbar position data, there is a way to circumvent the WM_*SCROLL messages' 16 bits barrier. See GetScrollPos or for a description of the technique and its limits.

See Also

GetScrollPos, GetScrollRange, SetScrollPos


SetSysColors function
SetSysColors (Win32)

BOOL SetSysColors(cDspElements, lpnDspElements, lpdwRgbValues)

int cDspElements;	/* number of elements to change	*/
CONST INT *lpnDspElements;	/* address of array of elements	*/
CONST COLORREF *lpdwRgbValues;	/* address of array of RGB values	*/

The SetSysColors function sets the system colors for one or more display elements. Display elements are the various parts of a window and the Windows background that appear on the screen.

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.

Parameter	Description

cDspElements	Specifies the number of display elements in the array pointed to by the lpnDspElements parameter.

lpnDspElements	Points to an array of integers that specify the display elements to be changed. This parameter must be one of the following values:

Value	Meaning

COLOR_ACTIVEBORDER	Active window border.

COLOR_ACTIVECAPTION	Active window caption.

COLOR_APPWORKSPACE	Background color of multiple document interface (MDI) applications.

COLOR_BACKGROUND	Desktop.

COLOR_BTNFACE	Face shading on push buttons.

COLOR_BTNSHADOW	Edge shading on push buttons.

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_MENU	Menu background.

COLOR_MENUTEXT	Text in menus.

COLOR_SCROLLBAR	Scroll bar gray area.

COLOR_SHADOW	Color of automatic window shadows.

COLOR_WINDOW	Window background.

COLOR_WINDOWFRAME	Window frame.

COLOR_WINDOWTEXT	Text in windows.

lpdwRgbValues	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 lpnDspElements parameter.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The SetSysColors function changes the current Windows session only. The new colors are not saved when Windows terminates.

See Also

GetSysColor, WM_SYSCOLORCHANGE


SetTimer function
SetTimer (Win32)

UINT SetTimer(hwnd, idTimer, uTimeout, tmprc)

HWND hwnd;	/* handle of window for timer messages	*/
UINT idTimer;	/* timer identifier	*/
UINT uTimeout;	/* time-out value	*/
TIMERPROC tmprc;	/* address of timer procedure	*/

The SetTimer function creates a timer with the specified time-out value.

Parameter	Description

hwnd	Identifies the window to be associated with the timer. If this parameter is NULL, no window is associated with the timer and the idTimer parameter is ignored.

idTimer	Specifies a nonzero timer identifier. If the hwnd parameter is NULL, this parameter is ignored.

uTimeout	Specifies the time-out value, in milliseconds.

tmprc	Points to the function to be notified when the time-out value elapses. For more information, see the description of the TimerProc callback function.

If tmprc 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.

Returns

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.

Comments

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.

The wParam parameter of the WM_TIMER message contains idTimer.

See Also

KillTimer, TimerProc, MSG


SetWindowLong function
SetWindowLong (Win32)

LONG SetWindowLong(hwnd, nIndex, lNewLong)

HWND hwnd;	/* handle of window	*/
int nIndex;	/* offset of value to set	*/
LONG lNewLong;	/* new value	*/

The SetWindowLong function changes an attribute of the given window. The function also sets a 32-bit (long) value at the specified offset into the extra window memory of the given window.

Parameter	Description

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 four; for example, if you specified 12 or more bytes of extra memory, a value of 8 would be an index to the third long 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 long value associated with the window. Each window has a corresponding long 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.

lNewLong	Specifies the replacement value.

Returns

If the function succeeds, the return value is the previous value of the specified 32-bit integer; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

If you use the SetWindowLong function and the GWL_WNDPROC index to replace the window procedure, the given 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 cannot 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


SetWindowPlacement function
SetWindowPlacement (Win32)

BOOL SetWindowPlacement(hwnd, lpwndpl)

HWND hwnd;	/* handle of window	*/
CONST WINDOWPLACEMENT * lpwndpl;	/* address of structure with position data	*/

The SetWindowPlacement function sets the show state and the restored, minimized, and maximized positions of the given window.

Parameter	Description

hwnd	Identifies the window.

lpwndpl	Points to a WINDOWPLACEMENT structure that specifies the new show state and window positions.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetWindowPlacement, WINDOWPLACEMENT


SetWindowPos function
SetWindowPos (Win32)

BOOL SetWindowPos(hwnd, hwndInsertAfter, x, y, cx, cy, fuFlags)

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 fuFlags;	/* window-positioning flags	*/

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.

Parameter	Description

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 rules about how this parameter is used, see the Comments 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.

fuFlags	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_NOSIZE	Retains the current size (ignores the cx and cy parameters).

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 to be redrawn.

SWP_NOZORDER	Retains the current Z order (ignores the hwndInsertAfter parameter).

SWP_SHOWWINDOW	Displays the window.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 the HWND_TOPMOST flag 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.

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.

If an application is not in the foreground, and wants to be in the foreground, it should call SetForegroundWindow.

See Also

MoveWindow, SetActiveWindow, SetForegroundWindow


SetWindowsHook function
SetWindowsHook (Win32)

HHOOK SetWindowsHook(nHookType, pfnHookProc)

int nHookType;	/* type of hook to install	*/
HOOKPROC pfnHookProc;	/* address of hook procedure	*/

The SetWindowsHook function is obsolete. For Win32 applications, use the SetWindowsHookEx function.


SetWindowsHookEx function
SetWindowsHookEx (Win32)

HHOOK SetWindowsHookEx(idHook, hkprc, hMod, dwThreadID)

int idHook;	/* type of hook to install	*/
HOOKPROC hkprc;	/* address of hook procedure	*/
HINSTANCE hMod;	/* handle of application instance	*/
DWORD dwThreadID;	/* identity of thread to install hook for	*/

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.

Parameter	Description

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 sent to a window procedure. For more information, see the description of the CallWndProc 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. For more information, see the description of the MessageProc hook procedure.

WH_SHELL	Installs a hook procedure that receives notifications useful to shell applications. 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.

hkprc	Points to the hook procedure. If the dwThreadID parameter is zero or specifies the identifier of a thread created by a different process, the hkprc parameter must point to a hook procedure in a dynamic-link library (DLL). Otherwise, hkprc 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 hkprc 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.

Returns

If the function succeeds, the return value is the handle of the hook procedure. Otherwise, the return value is NULL.

Comments

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.

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 given 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, UnhookWindowsHookEx


SetWindowText function
SetWindowText (Win32)

BOOL SetWindowText(hwnd, lpsz)

HWND hwnd;	/* handle of window or control	*/
LPCTSTR lpsz;	/* address of string	*/

The SetWindowText function changes the text of the given window's title bar (if it has one). If the given window is a control, the text of the control is changed.

Parameter	Description

hwnd	Identifies the window or control whose text is to be changed.

lpsz	Points to a null-terminated string to be used as the new title or control text.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The SetWindowText function causes a WM_SETTEXT message to be sent to the given 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


SetWindowWord function
SetWindowWord (Win32)

WORD SetWindowWord(hwnd, nIndex, wNewWord)

HWND hwnd;	/* handle of window	*/
int nIndex;	/* offset of value to set	*/
WORD wNewWord;	/* new value	*/

The SetWindowWord function replaces the 16-bit (word) value at the specified offset into the extra window memory for the given window.

Parameter	Description

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.

Returns

If the function succeeds, the return value is the previous value of the specified 16-bit integer; otherwise, it is zero. To get extended error information, use the GetLastError function.

Comments

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 application programming interface (API). You must use the SetWindowLong function to set information about the window.

See Also

GetParent, GetWindowLong, GetWindowWord, SetParent, SetWindowLong


ShowCaret function
ShowCaret (Win32)

BOOL ShowCaret(hwnd)

HWND hwnd;	/* handle of window with caret	*/

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.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

ShowCaret shows the caret only if the given 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 function
ShowCursor (Win32)

int ShowCursor(bShow)

BOOL bShow;	/* cursor visibility flag	*/

The ShowCursor function displays or hides the cursor.

Parameter	Description

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.

Returns

The return value specifies the new display counter.

Comments

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, it is -1.

See Also

ClipCursor, GetCursorPos, SetCursor, SetCursorPos


ShowOwnedPopups function
ShowOwnedPopups (Win32)

BOOL ShowOwnedPopups(hwnd, fShow)

HWND hwnd;	/* handle of window	*/
BOOL fShow;	/* window visibility flag	*/

The ShowOwnedPopups function shows or hides all pop-up windows owned by the given window.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

The ShowOwnedPopups function shows only windows hidden by a previous call to ShowOwnedPopups. For example, if a pop-up window is hidden by using the ShowWindow function, calling ShowOwnedPopups subsequently with the fShow parameter set to TRUE does not cause the window to be shown.

See Also

IsWindowVisible, ShowWindow


ShowScrollBar function
ShowScrollBar (Win32)

BOOL ShowScrollBar(hwnd, fnBar, fShow)

HWND hwnd;	/* handle of window with scroll bar	*/
int fnBar;	/* scroll bar flag	*/
BOOL fShow;	/* scroll bar visibility flag	*/

The ShowScrollBar function shows or hides the given scroll bar.

Parameter	Description

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

fShow	Specifies whether the scroll bar is shown or hidden. If this parameter is TRUE, the scroll bar is shown; otherwise, it is hidden.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
ShowWindow (Win32)

BOOL ShowWindow(hwnd, nCmdShow)

HWND hwnd;	/* handle of window	*/
int nCmdShow;	/* show state of window	*/

The ShowWindow function sets the given window's show state.

Parameter	Description

hwnd	Identifies the window.

nCmdShow	Specifies how the window is to be shown. This parameter can be one of the following values:

Value	Meaning

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_HIDE	Hides the window and activates another 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. However, if the first call by an application to ShowWindow has nCmdShow set to SW_SHOW, the system uses the startup information mentioned in the description of the SW_SHOWDEFAULT flag. For additional information, see the Comments section.

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.

Returns

If the window was previously visible, the return value is TRUE. If the window was previously hidden, the return value is FALSE.

Comments

The ShowWindow function must be called only once per program with the nCmdShow parameter from the WinMain function. Subsequent calls to ShowWindow must use one of the values in the preceding list, instead of the one specified by nCmdShow from WinMain.

As noted in the discussion of the nCmdShow parameter, an application should call ShowWindow with nCmdShow set to the SW_SHOWDEFAULT flag to use application startup information that affects how a window is displayed. For example, Windows Program Manager specifies that applications start with a minimized main window. Win32 applications also use the application startup information when calling ShowWindow for the first time and set nCmdShow to the SW_SHOW flag. This behavior is designed for the following situations:

Applications that create their main window by calling CreateWindow with the WS_VISIBLE flag set.

Applications that 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

CreateWindow, ShowOwnedPopups


SubtractRect function
SubtractRect (Win32)

BOOL SubtractRect(lprcDest, lprcSource1, lprcSource2)

LPRECT lprcDest;	/* pointer to destination rectangle	*/
CONST RECT * lprcSrc1;	/* pointer to rect. to subtract from	*/
CONST RECT * lprcSrc2;	/* pointer to rect. to subtract	*/

The SubtractRect function obtains the coordinates of a rectangle determined by subtracting one rectangle from another.

Parameter	Description

lprcDest	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 lprcSrc2.

Returns

If the function succeeds, the return value is nonzero; otherwise, it is zero.

Comments

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 lprcDest 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 lprcDest to (10,10,50,100).

See Also

IntersectRect, UnionRect, RECT


SwapMouseButton function
SwapMouseButton (Win32)

BOOL SwapMouseButton(fSwap)

BOOL fSwap;	/* reverse or restore buttons	*/

The SwapMouseButton function reverses or restores the meaning of the left and right mouse buttons.

Parameter	Description

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.

Returns

If the meaning of the mouse buttons was reversed previously, before the function was called, the return value is TRUE; otherwise, it is FALSE.

Comments

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.


SystemParametersInfo function
SystemParametersInfo (Win32)

BOOL SystemParametersInfo(wAction, wParam, lpvParam, fUpdateProfile)

UINT wAction;	/* system parameter to query or set	*/
UINT wParam;	/* depends on action to be taken	*/
PVOID lpvParam;	/* depends on action to be taken	*/
UINT fUpdateProfile;	/* user profile update flag	*/

The SystemParametersInfo function queries or sets system-wide parameters. This function can also update the user profile while setting a parameter.

Parameter	Description

wAction	Specifies the system-wide parameter to query or set. This parameter can be one of the following values:

Value	Action

SPI_GETBEEP	Retrieves a BOOL value that indicates whether the warning beeper is on or off.

SPI_GETBORDER	Retrieves the border multiplier factor that determines the width of a window's sizing border.

SPI_GETFASTTASKSWITCH	Determines whether fast task switching is on or off.

SPI_GETGRIDGRANULARITY	Retrieves the current granularity value of the desktop sizing grid.

SPI_GETICONTITLELOGFONT	Retrieves the logical font information for the current icon-title font.

SPI_GETICONTITLEWRAP	Determines whether icon-title wrapping is on or off.

SPI_GETKEYBOARDDELAY	Retrieves the keyboard repeat-delay setting.

SPI_GETKEYBOARDSPEED	Retrieves the keyboard repeat-speed setting.

SPI_GETMENUDROPALIGNMENT	Determines whether pop-up menus are left aligned or right aligned relative to the corresponding menu-bar item.

SPI_GETMOUSE	Retrieves the mouse speed and the x and y mouse threshold values.

SPI_GETSCREENSAVEACTIVE	Retrieves a BOOL value that indicates whether screen saving is on or off.

SPI_GETSCREENSAVETIMEOUT	Retrieves the screen saver time-out value.

SPI_ICONHORIZONTALSPACING	Sets the width, in pixels, of an icon cell.

SPI_ICONVERTICALSPACING	Sets the height, in pixels, of an icon cell.

SPI_LANGDRIVER	Identifies the language driver.

SPI_SETBEEP	Turns the warning beeper on or off.

SPI_SETBORDER	Sets the border multiplier factor that determines the width of a window's sizing border.

SPI_SETDESKPATTERN	Sets the current desktop pattern by causing the Windows USER.EXE program to read the Pattern= parameter from the WIN.INI file.

SPI_SETDESKWALLPAPER	Specifies the filename that contains the bitmap to be used as the desktop wallpaper.

SPI_SETDOUBLECLICKTIME	Sets the double-click time for the mouse. 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 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 rectangle within which the second click of a double-click must fall for it to be registered as a double-click.

SPI_SETFASTTASKSWITCH	Turns fast task switching on or off.

SPI_SETGRIDGRANULARITY	Sets the granularity of the desktop sizing grid.

SPI_SETICONTITLELOGFONT	Sets the font that is used for icon titles.

SPI_SETICONTITLEWRAP	Turns icon-title wrapping on or off.

SPI_SETKEYBOARDDELAY	Sets the keyboard repeat-delay setting.

SPI_SETKEYBOARDSPEED	Sets the keyboard repeat-speed setting.

SPI_SETMENUDROPALIGNMENT	Sets the alignment value of pop-up menus.

SPI_SETMOUSE	Sets the mouse speed and the x and y mouse threshold values.

SPI_SETMOUSEBUTTONSWAP	Swaps or restores the meaning of the left and right mouse buttons.

SPI_SETSCREENSAVEACTIVE	Sets the state of the screen saver.

SPI_SETSCREENSAVETIMEOUT	Sets the screen saver time-out value.

wParam	Depends on the wAction parameter. See the Comments section for details.

lpvParam	Depends on the wAction parameter. See the Comments section for details.

fUpdateProfile	If a system parameter is being set, specifies whether the user profile is to be updated, and if so, whether the WM_WININICHANGE message is to be broadcast to all top-level windows to notify them of the change. This parameter can be one of the following values:

Value	Action

SPIF_UPDATEINIFILE	Writes the new system-wide parameter setting to the user profile.

SPIF_SENDWININICHANGE	Broadcasts the WM_WININICHANGE message after updating the user profile.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

This function is intended for use with applications such as Control Panel that allow the user to customize the Windows environment.

The following table describes the wParam and lpvParam parameters for each SPI_ constant:

Constant	wParam	lpvParam
SPI_GETBEEP	0	Points to a BOOL variable that receives TRUE if the beeper is on, FALSE if it is off.
SPI_GETBORDER	0	Points to an integer variable that receives the border multiplier factor.
SPI_GETFASTTASKSWITCH	0	Points to a BOOL variable that receives TRUE if fast task switching is on, FALSE if it is off.
SPI_GETGRIDGRANULARITY	0	Points to an integer variable that receives the grid-granularity value.
SPI_GETICONTITLELOGFONT	Specifies the size of a LOGFONT structure.	Points to a LOGFONT structure that receives the logical font information.
SPI_GETICONTITLEWRAP	0	Points to a BOOL variable that receives TRUE if wrapping is on, FALSE if wrapping is off.
SPI_GETKEYBOARDDELAY	0	Points to an integer variable that receives the keyboard repeat-delay setting.
SPI_GETKEYBOARDSPEED	0	Points to a WORD variable that receives the current keyboard repeat-speed setting.
SPI_GETMENUDROPALIGNMENT	0	Points to a BOOL variable that receives TRUE if pop-up menus are right aligned, FALSE if they are left aligned.
SPI_GETMOUSE	0	Points to an integer array where lpiMouse[0] receives MouseThreshold1, lpiMouse[1] receives MouseThreshold2, and lpiMouse[2] receives MouseSpeed.
SPI_GETSCREENSAVEACTIVE	0	Points to a BOOL variable that receives TRUE if the screen saver is active, FALSE if it is not.
SPI_GETSCREENSAVETIMEOUT	0	Points to an integer variable that receives the screen saver time-out value, in milliseconds.
SPI_ICONHORIZONTALSPACING	Specifies the icon cell width.	Is NULL if the icon cell width, in pixels, is returned in wParam. If this value is a pointer to an integer, the current horizontal spacing is returned in that variable and wParam is ignored.
SPI_ICONVERTICALSPACING	Specifies the icon cell height.	Is NULL if the icon cell height, in pixels, is returned in wParam. If this value is a pointer to an integer, the current vertical spacing is returned in that variable and wParam is ignored.
SPI_LANGDRIVER	0	Points to a string containing the new language driver filename.
SPI_SETBEEP	Specifies TRUE to turn the beeper on, FALSE to turn the beeper off.	NULL
SPI_SETBORDER	Specifies the border multiplier factor.	NULL
SPI_SETDESKPATTERN	0	NULL
SPI_SETDESKWALLPAPER	0	Points to a string that specifies the name of the bitmap file.
SPI_SETDOUBLECLICKTIME	Specifies the double-click time, in milliseconds.	NULL
SPI_SETDOUBLECLKHEIGHT	Specifies the double-click height, in pixels.	NULL
SPI_SETDOUBLECLKWIDTH	Specifies the double-click width, in pixels.	NULL
SPI_SETFASTTASKSWITCH	Specifies TRUE to turn fast task switching on, FALSE to turn it off.	NULL
SPI_SETGRIDGRANULARITY	Specifies the grid granularity.
SPI_SETICONTITLELOGFONT	Specifies the size of a LOGFONT structure.	Points to a LOGFONT structure that contains the logical font information to set.
SPI_SETICONTITLEWRAP	Specifies TRUE to turn wrapping on, FALSE to turn wrapping off.	NULL
SPI_SETKEYBOARDDELAY	Specifies the keyboard-delay setting.	NULL
SPI_SETKEYBOARDSPEED	Specifies the repeat-speed setting.	NULL
SPI_SETMENUDROPALIGNMENT	Specifies TRUE to use right alignment, FALSE to use left alignment.	NULL
SPI_SETMOUSE	0	Points to an integer array where lpiMouse[0] receives xMouseThreshold, lpiMouse[1] receives yMouseThreshold, and lpiMouse[2] receives MouseSpeed.
SPI_SETMOUSEBUTTONSWAP	Specifies TRUE to reverse the meaning of the left and right mouse buttons, FALSE to restore the buttons to their original meanings.	NULL
SPI_SETSCREENSAVEACTIVE	Specifies TRUE to activate screen saving, FALSE to deactivate screen saving.	NULL
SPI_SETSCREENSAVETIMEOUT	Specifies the idle time-out duration, in seconds, before the screen is saved.	NULL


TabbedTextOut function
TabbedTextOut (Win32)

LONG TabbedTextOut(hdc, x, y, lpString, nCount, nTabPositions, lpnTabStopPositions, nTabOrigin)

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

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.

Parameter	Description

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.

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.

nTabOrigin	Specifies the x-coordinate of the starting position from which tabs are expanded, in logical units.

Returns

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.

Comments

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


ToAscii function
ToAscii (Win32)

int ToAscii(uVirtKey, uScanCode, lpbKeyState, lpwTransKey, fuState)

UINT uVirtKey;	/* virtual-key code	*/
UINT uScanCode;	/* scan code	*/
PBYTE lpbKeyState;	/* address of key-state array	*/
LPWORD lpwTransKey;	/* buffer for translated key	*/
UINT fuState;	/* active-menu flag	*/

The ToAscii function translates the specified virtual-key code and keyboard state to the corresponding Windows character or characters.

Parameter	Description

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.

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

lpwTransKey	Points to the buffer that will receive the translated Windows character or characters.

fuState	Specifies whether a menu is active. This parameter must be 1 if a menu is active, or 0 otherwise.

Returns

If the specified key is a dead key, the return value is negative. Otherwise, it is one of the following values:

Value	Meaning

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.

1	One Windows character was copied to the buffer.

0	The specified virtual key has no translation for the current state of the keyboard.

Comments

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.

See Also

OemKeyScan, ToUnicode, VkKeyScan


ToUnicode function
ToUnicode (Win32)

int ToUnicode(wVirtKey, wScanCode, lpKeyState, pwszBuff, cchBuff, wFlags)

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

The ToUnicode function translates the specified virtual-key code and keyboard state to the corresponding Unicode character or characters.

Parameter	Description

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

wFlags	A set of bit flags that condition the behavior of the function.

Bits	Meaning

0	Must be set to 1 if a menu is active, cleared to 0 otherwise.

1-31	Reserved.

Returns

The function returns one of the following values:

Value	Meaning

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.

1	One character was written to the buffer specified by pwszBuffer.

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

Comments

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 may be used to distinguish between a key press and a key release.

See Also

ToAscii, VkKeyScan


TrackPopupMenu function
TrackPopupMenu (Win32)

BOOL TrackPopupMenu(hmenu, fuFlags, x, y, nReserved, hwnd, lprc)

HMENU hmenu;	/* handle of pop-up menu	*/
UINT fuFlags;	/* screen-position and mouse-button flags	*/
int x;	/* horizontal screen position	*/
int y;	/* vertical screen position	*/
int nReserved;	/* reserved	*/
HWND hwnd;	/* handle of owner window	*/
CONST RECT *lprc;	/* address of structure with rectangle	*/

The TrackPopupMenu function displays the given floating pop-up menu at the specified location and tracks the selection of items on the pop-up menu. The floating pop-up menu can appear anywhere on the screen.

Parameter	Description

hmenu	Identifies the pop-up menu to be displayed. This handle is obtained by calling CreatePopupMenu to create a new pop-up menu or by calling GetSubMenu to retrieve the handle of a pop-up menu associated with an existing menu item.

fuFlags	Specifies a screen-position flag and a mouse-button flag. The screen-position flag must be one of the following values:

Value	Meaning

TPM_CENTERALIGN	Centers the pop-up menu horizontally relative to the coordinate specified by the x-parameter.

TPM_LEFTALIGN	Positions the pop-up menu so that its left side is aligned with the coordinate specified by the x-parameter.

TPM_RIGHTALIGN	Positions the pop-up menu so that its right side is aligned with the coordinate specified by the x-parameter.

The mouse-button flag must be one of the following values:

Value	Meaning

TPM_LEFTBUTTON	Causes the pop-up menu to track the left mouse button.

TPM_RIGHTBUTTON	Causes the pop-up menu to track the right mouse button.

x	Specifies the horizontal position, in screen coordinates, of the pop-up menu. Depending on the value of the fuFlags parameter, the pop-up menu can be left-aligned, right-aligned, or centered relative to this position.

y	Specifies the vertical position, in screen coordinates, of the top of the menu on the screen.

nReserved	Reserved; must be zero.

hwnd	Identifies the window that owns the pop-up menu. This window receives all messages from the menu. The window does not receive a WM_COMMAND message from the menu until the TrackPopupMenu function returns.

lprc	Points to a RECT structure that contains the screen coordinates of a rectangle in which the user can select without dismissing the pop-up menu. If this parameter is NULL, the pop-up menu is dismissed if the user clicks outside the pop-up menu.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

CreatePopupMenu, GetSubMenu


TranslateAccelerator function
TranslateAccelerator (Win32)

int TranslateAccelerator(hwnd, haccl, lpmsg)

HWND hwnd;	/* handle of destination window	*/
HACCEL haccl;	/* handle of accelerator table	*/
LPMSG lpmsg;	/* address of structure with message	*/

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.

Parameter	Description

hwnd	Identifies the window whose messages are to be translated.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

To differentiate the message from messages sent by menus or controls, the high-order word of the lParam parameter of the WM_COMMAND or WM_SYSCOMMAND message contains the value 1.

Accelerator key combinations used to select items from the System 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 are present:

The window is disabled.

The menu item is disabled.

The accelerator key combination does not correspond to an item on the System menu and the window is minimized.

A mouse capture is in effect. For information about mouse capture, see the description of 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 System menu, the function sends a WM_COMMAND message, even if the window is minimized.

See Also

CreateAcceleratorTable, GetMessage, LoadAccelerators, PeekMessage, SetCapture, MSG


TranslateMDISysAccel function
TranslateMDISysAccel (Win32)

BOOL TranslateMDISysAccel(hwndClient, lpmsg)

HWND hwndClient;	/* handle of MDI client window	*/
LPMSG lpmsg;	/* address of structure with message data	*/

The TranslateMDISysAccel function processes accelerator keystrokes for System menu commands of the multiple document interface (MDI) child windows associated with the given 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.

Parameter	Description

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.

Returns

If the function translates a message into a system command, the return value is TRUE; otherwise, it is FALSE.

See Also

GetMessage, PeekMessage, TranslateAccelerator, MSG, WM_SYSCOMMAND


TranslateMessage function
TranslateMessage (Win32)

BOOL TranslateMessage(lpmsg)

CONST MSG *lpmsg;	/* address of structure with message	*/

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.

Parameter	Description

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.

Returns

If the message is translated (that is, a character message is posted to the thread's message queue), the return value is TRUE; otherwise, it is FALSE.

Comments

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

See Also

GetMessage, PeekMessage, TranslateAccelerator


UnhookWindowsHook function
UnhookWindowsHook (Win32)

BOOL UnhookWindowsHook(nCode, hkprc)

int nCode;	/* type of hook to remove procedure from	*/
HOOKPROC hkprc;	/* address of hook procedure	*/

The UnhookWindowsHook function is obsolete. For Win32 applications, use the UnhookWindowsHookEx function.


UnhookWindowsHookEx function
UnhookWindowsHookEx (Win32)

BOOL UnhookWindowsHookEx(hhook)

HHOOK hhook;	/* handle of hook procedure to remove	*/

The UnhookWindowsHookEx function removes a hook procedure installed in a hook chain by the SetWindowsHookEx function.

Parameter	Description

hhook	Identifies the hook to be removed. This parameter is a hook handle obtained by a previous call to SetWindowsHookEx.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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 function
UnionRect (Win32)

BOOL UnionRect(lprcDst, lprcSrc1, lprcSrc2)

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

The UnionRect function creates the union of two rectangles. The union is the smallest rectangle that contains both source rectangles.

Parameter	Description

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.

Returns

If the specified structure contains a nonempty rectangle, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

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 function
UnloadKeyboardLayout (Win32)

BOOL UnloadKeyboardLayout(hkl)

HKL hkl;	/* handle of keyboard layout	*/

The UnloadKeyboardLayout function removes a keyboard layout.

Parameter	Description

hkl	Identifies the keyboard layout to unload.

Returns

If the function succeeds, the return value is the handle of the keyboard layout; otherwise, it is NULL. To get extended error information, use the GetLastError function.

See Also

LoadKeyboardLayout


UnpackDDElParam function
UnpackDDElParam (Win32)

BOOL UnpackDDElParam(uMsg, lParam, puLow, puHigh)

UINT uMsg;	/* posted DDE message	*/
LONG lParam;	/* lParam of posted DDE message	*/
PUINT puLow;	/* address of low-order word of lParam	*/
PUINT puHigh;	/* address of high-order word of lParam	*/

The UnpackDDElParam function unpacks a dynamic data exchange (DDE) lParam value received from a posted DDE message.

Parameter	Description

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

puLow	Points to a value the function will set to the low-order word of lParam.

puHigh	Points to a value the function will set to the high-order word of lParam.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The PackDDElParam function eases the porting of 16-bit DDE applications to 32-bit DDE applications.

See Also

FreeDDElParam, PackDDElParam, ReuseDDElParam


UnregisterClass function
UnregisterClass (Win32)

BOOL UnregisterClass(lpszClass, hinst)

LPCTSTR lpszClass;	/* address of class name string	*/
HINSTANCE hinst;	/* handle of application instance	*/

The UnregisterClass function removes a window class, freeing the memory required for the class.

Parameter	Description

lpszClass	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 lpszClass; the high-order word must be zero.

The lpszClass string 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.

hinst	Identifies the instance of the module that created the class.

Returns

If the function succeeds, the return value is TRUE. If the class could not be found or if a window still exists that was created with the class, the return value is FALSE. To get extended error information, use the GetLastError function.

Comments

Before calling this function, an application must destroy all windows created with the specified class.

All window classes registered by an application are unregistered when it terminates.

See Also

GlobalAddAtom, RegisterClass, WNDCLASS


UnregisterHotKey function
UnregisterHotKey (Win32)

BOOL UnregisterHotKey(hwnd, idHotKey)

HWND hwnd;	/* window associated with hot key	*/
int idHotKey;	/* identifier of hot key	*/

The UnregisterHotKey function frees a hot key previously registered by the calling thread.

Parameter	Description

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.

idHotKey	Specifies the identifier of the hot key to be freed.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

RegisterHotKey, WM_HOTKEY


UpdateWindow function
UpdateWindow (Win32)

BOOL UpdateWindow(hwnd)

HWND hwnd;	/* handle of window	*/

The UpdateWindow function updates the client area of the given 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 given window, bypassing the application queue. If the update region is empty, no message is sent.

Parameter	Description

hwnd	Identifies the window to be updated.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

See Also

ExcludeUpdateRgn, GetUpdateRect, GetUpdateRgn, InvalidateRgn, InvalidateRect, WM_PAINT


ValidateRect function
ValidateRect (Win32)

BOOL ValidateRect(hwnd, lprc)

HWND hwnd;	/* handle of window	*/
CONST RECT *lprc;	/* address of structure with validation rectangle	*/

The ValidateRect function validates the client area within the given rectangle by removing the rectangle from the update region of the given window.

Parameter	Description

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.

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

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

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, ValidateRgn, RECT, WM_ERASEBKGND, WM_NCPAINT, WM_PAINT


ValidateRgn function
ValidateRgn (Win32)

BOOL ValidateRgn(hwnd, hrgn)

HWND hwnd;	/* handle of window	*/
HRGN hrgn;	/* handle of valid region	*/

The ValidateRgn function validates the client area within the given region by removing the region from the current update region of the given window.

Parameter	Description

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE.

Comments

The given 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, InvalidateRgn, InvalidateRect, ValidateRect, WM_PAINT


VkKeyScan function
VkKeyScan (Win32)

SHORT VkKeyScan(ch)

TCHAR ch;	/* character to translate	*/

The VkKeyScan function translates a character to the corresponding virtual-key code and shift state for the current keyboard.

Parameter	Description

ch	Specifies the character to be translated into a virtual-key code.

Returns

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.

Comments

For keyboard layouts that use the right-hand ALT key (AltGr) as a shift key (for example, the French keyboard layout), the shift state is represented by the value 6, because AltGr 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, GetKeyNameText, GetKeyboardState, GetKeyState, SetKeyboardState


WaitMessage function
WaitMessage (Win32)

BOOL WaitMessage(VOID)

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.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetMessage, PeekMessage


WindowFromDC function
WindowFromDC (Win32)

HWND WindowFromDC(hdc)

HDC hdc;	/* handle of window	*/

The WindowFromDC function returns the handle of the window associated with the given display device context (DC). Output functions that use the given DC draw into this window.

Parameter	Description

hdc	Identifies the DC from which a handle for the associated window is to be retrieved.

Returns

If the function succeeds, the return value is the handle of the window associated with the given display DC; otherwise, the return value is NULL.

See Also

GetDC, GetDCEx, GetWindowDC


WindowFromPoint function
WindowFromPoint (Win32)

HWND WindowFromPoint(pt)

POINT pt;	/* structure with point	*/

The WindowFromPoint function retrieves the handle of the window that contains the specified point.

Parameter	Description

pt	Specifies a POINT structure that defines the point to be checked.

Returns

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.

Comments

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


WinHelp function
WinHelp (Win32)

BOOL WinHelp(hwnd, lpszHelpFile, fuCommand, dwData)

HWND hwnd;	/* handle of window requesting Help	*/
LPCTSTR lpszHelpFile;	/* address of directory-path string	*/
UINT fuCommand;	/* type of Help	*/
DWORD dwData;	/* additional data	*/

The WinHelp function starts the Windows Help application (WINHLP32.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.

Parameter	Description

hwnd	Identifies the window requesting Help. The WinHelp function uses this handle to keep track of which applications have requested Help.

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

fuCommand	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 following Comments section.

dwData	Specifies additional data. The value used depends on the value of the fuCommand parameter. For a list of possible values, see the following Comments section.

Returns

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

Comments

Before closing the window that requested Help, the application must call WinHelp with the fuCommand parameter set to HELP_QUIT. Until all applications have done this, Windows Help does not terminate.

The following table shows the possible values for the fuCommand parameter and the corresponding formats of the dwData parameter:

fuCommand	dwData	Action
HELP_COMMAND	Long pointer to a string containing the name of a Help macro to be executed.	Executes a Help macro.
HELP_CONTENTS	Ignored; applications should set to 0L.	Displays the Help contents topic as defined by the Contents option in the [OPTIONS] section of the .HPJ file.
HELP_CONTEXT	Unsigned long integer containing the context number for the topic.	Displays Help for a particular topic identified by a context number that has been defined in the [MAP] section of the .HPJ file.
HELP_CONTEXTPOPUP	Unsigned long integer containing the context number for a topic.	Displays in a pop-up window Help for a particular topic identified by a context number that has been defined in the [MAP] section of the .HPJ file.
HELP_FORCEFILE	Ignored; applications should set to 0L.	Ensures that WinHelp is displaying the correct Help file. If the correct Help file is currently displayed, there is no action. If the incorrect Help file is displayed, WinHelp opens the correct file.
HELP_HELPONHELP	Ignored; applications should set to 0L.	Displays the Contents topic of the designated Using Help file.
HELP_INDEX	Ignored; applications should set to 0L.	Displays the Help Contents topic as defined by the Index option in the [OPTIONS] section of the .HPJ file.
HELP_KEY	Long pointer to a string containing a keyword for the desired topic.	Displays the topic found in the keyword list that matches the keyword passed in the dwData parameter, if there is one exact match. If there is more than one match, displays the Search dialog box with the topics listed in the Go To list box.
HELP_MULTIKEY	Long pointer to the MULTIKEYHELP structure, as defined in WINDOWS.H.This structure specifies the table footnote character and the keyword.	Displays the Help topic identified by a keyword in an alternative keyword table.
HELP_PARTIALKEY	Long pointer to a string containing a keyword for the desired topic.	Displays the topic found in the keyword list that matches the keyword passed in the dwData parameter, if there is one exact match. If there is more than one match, displays the Search dialog box with the topics listed in the Go To list box. If there is no match, displays the Search dialog box. To bring up the Search dialog box without passing a keyword (the third result), you should use a long pointer to an empty string.
HELP_QUIT	Ignored; applications should set to 0L.	Informs the Help application that Help is no longer needed. If no other applications have asked for Help, Windows closes the Help application.
HELP_SETCONTENTS	Unsigned long integer containing the context number for the topic to be designated as the Contents topic.	Determines the Contents topic Help is to display when a user presses the F1 key.
HELP_SETINDEX	Unsigned long integer containing the context number for the topic to be designated as the Index topic.	Determines the topic WinHelp is to display when a user selects Index.
HELP_SETWINPOS	Long pointer to the HELPWININFO structure, as defined in WINDOWS.H.This structure specifies the size and position of either a primary or secondary Help window.	Displays the Help window, if it is minimized or in memory, and positions it according to the data passed.
See Also

MULTIKEYHELP


AnsiLower function
AnsiLower (Win32)

The AnsiLower function is obsolete.

For compatibility with earlier versions of Windows, this function is implemented as a macro that calls the CharLower function.


AnsiLowerBuff function
AnsiLowerBuff (Win32)

The AnsiLowerBuff function is obsolete.

For compatibility with earlier versions of Windows, this function is implemented as a macro that calls the CharLowerBuff function.


AnsiNext function
AnsiNext (Win32)

The AnsiNext function is obsolete.

For compatibility with earlier versions of Windows, this function is implemented as a macro that calls the CharNext function.


AnsiPrev function
AnsiPrev (Win32)

The AnsiPrev function is obsolete.

For compatibility with earlier versions of Windows, this function is implemented as a macro that calls the CharPrev function.


AnsiToOem function
AnsiToOem (Win32)

The AnsiToOem function is obsolete.

For compatibility with earlier versions of Windows, this function is implemented as a macro that calls the CharToOem function.


AnsiToOemBuff function
AnsiToOemBuff (Win32)

The AnsiToOemBuff function is obsolete.

For compatibility with earlier versions of Windows, this function is implemented as a macro that calls the CharToOemBuff function.


AnsiUpper function
AnsiUpper (Win32)

The AnsiUpper function is obsolete.

For compatibility with earlier versions of Windows, this function is implemented as a macro that calls the CharUpper function.


AnsiUpperBuff function
AnsiUpperBuff (Win32)

The AnsiUpperBuff function is obsolete.

For compatibility with earlier versions of Windows, this function is implemented as a macro that calls the CharUpperBuff function.


ChangeMenu function
ChangeMenu (Win32)

The ChangeMenu function has been replaced with the following five specialized functions.

Function	Description

AppendMenu	Appends a menu item to the end of a menu.

DeleteMenu	Deletes a menu item from a menu, destroying the menu item.

InsertMenu	Inserts a menu item into a menu.

ModifyMenu	Modifies a menu item in a menu.

RemoveMenu	Removes a menu item from a menu but does not destroy the menu item.

Applications written for versions earlier than Windows 3.0 may continue to call ChangeMenu as previously documented. Applications written for Windows versions 3.0 and later should call the new functions listed above.

Example

This example illustrates how a call to ChangeMenu should be rewritten to the AppendMenu function.

ChangeMenu(hMenu,                          /* handle of the menu      */

    0,                                     /* not used                */

    "&White",                              /* menu item string        */

    IDM_PATTERN1,                          /* identifier of menu item */

    MF_APPEND | MF_STRING | MF_CHECKED);   /* flags                   */

AppendMenu(hMenu,                          /* handle of the menu      */

    MF_STRING | MF_CHECKED,                /* flags                   */

    IDM_PATTERN1,                          /* identifier of menu item */

    "&White");                             /* menu item string        */

See Also

AppendMenu, DeleteMenu, InsertMenu, ModifyMenu, RemoveMenu


DefHookProc function
DefHookProc (Win32)

DWORD DefHookProc(nCode, wParam, lParam, lplpfnNextHook)

int nCode;	/* hook code passed to hook procedure	*/
DWORD wParam;	/* value passed to hook procedure	*/
LONG lParam;	/* value passed to hook procedure	*/
FARPROC *lplpfnNextHook;	/* not used	*/

The DefHookProc function is obsolete. For Win32 applications, use the CallNextHookEx function.


DlgDirSelect function
DlgDirSelect (Win32)

The DlgDirSelect function has been deleted. Win32 applications should use the DlgDirSelectEx function.

See Also

DlgDirSelectEx


DlgDirSelectComboBox function
DlgDirSelectComboBox (Win32)

The DlgDirSelectComboBox function has been deleted. Win32 applications should use the DlgDirSelectComboBoxEx function.

See Also

DlgDirSelectComboBoxEx


EnumTaskWindows function
EnumTaskWindows (Win32)

The EnumTaskWindows function is now obsolete. It has been replaced by the EnumThreadWindows function.

To maintain compatibility for older applications, EnumTaskWindows has been replaced with a macro that calls EnumThreadWindows. Older applications may continue to call EnumTaskWindows as previously documented, but new applications should use EnumThreadWindows.

See Also

EnumThreadWindows


GetWindowTask function
GetWindowTask (Win32)

The GetWindowTask function is now obsolete. It has been replaced by the GetWindowThreadProcessId function.

To maintain compatibility for older applications, GetWindowTask has been replaced with a macro that calls GetWindowThreadProcessId. Older applications may continue to call GetWindowTask as previously documented, but new applications should use GetWindowThreadProcessId .

Comments

GetWindowTask is defined as returning a value with a HANDLE data type. GetWindowThreadProcessId returns a value with a DWORD data type. The macro that maps GetWindowTask to GetWindowThreadProcessId includes a cast to HANDLE, as follows:

#define GetWindowTask(hwnd) ((HANDLE) GetWindowThreadProcessId(hwnd, NULL))

See Also

GetWindowThreadProcessId


GetSysModalWindow function
GetSysModalWindow (Win32)

The GetSysModalWindow function has been deleted.


OemToAnsi function
OemToAnsi (Win32)

The OemToAnsi function is obsolete.

For compatibility with earlier versions of Windows, this function is implemented as a macro that calls the OemToChar function.


OemToAnsiBuff function
OemToAnsiBuff (Win32)

The OemToAnsiBuff function is obsolete.

For compatibility with earlier versions of Windows, this function is implemented as a macro that calls the OemToCharBuff function.


PostAppMessage function
PostAppMessage (Win32)

The PostAppMessage function is retained only for compatibility with earlier versions of Microsoft® Windows. For Win32 applications, use the PostThreadMessage function.

Comments

The PostAppMessage function used a process identifier as its first parameter, but its replacement, the PostThreadMessage function, uses a thread identifier as its first parameter.

See Also

PostThreadMessage


SetSysModalWindow function
SetSysModalWindow (Win32)

The SetSysModalWindow function has been deleted.


Window Manager Functions (all)

ActivateKeyboardLayout	Activates a new keyboard layout

AdjustWindowRect	Computes required size of window rectangle

AdjustWindowRectEx	Computes required size of window rectangle

AnyPopup	Indicates if a popup window exists

AppendMenu	Appends a new item to a menu

ArrangeIconicWindows	Arranges minimized child windows

AttachThreadInput	Attach one thread to another

BeginDeferWindowPos	Creates a window-position structure

BeginPaint	Prepares a window for painting

BringWindowToTop	Uncovers an overlapped window

CallMsgFilter	Passes a message to a message-filter procedure

CallNextHookEx	Calls the next hook procedure in a chain

CallWindowProc	Passes a message to a window function

ChangeClipboardChain	Removes a window from clipboard-viewer chain

CharLower	Converts a character or string to lowercase

CharLowerBuff	Converts a character string to lowercase

CharNext	Moves to the next character in a string

CharPrev	Moves to the previous character in a string

CharToOem	Translates a string to OEM characters

CharToOemBuff	Translates a string to OEM characters

CharUpper	Converts a character or string to uppercase

CharUpperBuff	Converts a string to uppercase

CheckDlgButton	Changes a check mark by a dialog button

CheckMenuItem	Changes a menu-item's check mark attribute

CheckRadioButton	Places a check mark by a radio button

ChildWindowFromPoint	Determines the window containing a point

ClientToScreen	Converts client point to screen coordinates

ClipCursor	Confines cursor to a specified rectangle

CloseClipboard	Closes the clipboard

CloseWindow	Minimizes a window

CopyAcceleratorTable	Copies an accelerator table

CopyCursor	Copies a cursor

CopyIcon	Copies an icon

CopyRect	Copies the dimensions of a rectangle

CountClipboardFormats	Returns the number of clipboard formats

CreateAcceleratorTable	Creates an accelerator table

CreateCaret	Creates a new shape for the system caret

CreateCursor	Creates a cursor with specified dimensions

CreateDialog	Creates a modeless dialog box

CreateDialogIndirect	Creates modeless dialog box from memory template

CreateDialogIndirectParam	Creates modeless dialog box from memory template

CreateDialogParam	Creates a modeless dialog box

CreateIcon	Creates an icon with specified attributes

CreateIconFromResource	Creates an icon or cursor

CreateIconIndirect	Creates an icon or cursor

CreateMDIWindow	Creates a new MDI window

CreateMenu	Creates a menu

CreatePopupMenu	Creates a pop-up menu

CreateWindow	Creates a window

CreateWindowEx	Creates a window

DefDlgProc	Provides default window message processing

DeferWindowPos	Updates a multiple window position structure

DefFrameProc	Default MDI frame window message processing

DefMDIChildProc	Default MDI child window message processing

DefWindowProc	Calls the default window procedure

DeleteMenu	Deletes an item from a menu

DestroyAcceleratorTable	Destroys an accelerator table

DestroyCaret	Destroys the current caret

DestroyCursor	Destroys a cursor created by CreateCursor

DestroyIcon	Destroys an icon created by CreateIcon

DestroyMenu	Destroys a menu and frees memory

DestroyWindow	Destroys a window

DialogBox	Creates a modal dialog box

DialogBoxIndirect	Creates modal dialog box from template in memory

DialogBoxIndirectParam	Creates modal dialog box from template in memory

DialogBoxParam	Creates a modal dialog box

DispatchMessage	Dispatches a message to a window

DlgDirList	Fills a directory list box

DlgDirListComboBox	Fills a directory list box

DlgDirSelectComboBoxEx	Retrieves selection from dir. list box

DlgDirSelectEx	Retrieves a selection from a directory list box

DrawFocusRect	Draws a rectangle in the focus style

DrawIcon	Draws an icon in the specified device context

DrawMenuBar	Redraws the menu bar

DrawText	Draws formatted text in a rectangle

EmptyClipboard	Empties the clipboard and frees data handles

EnableMenuItem	Enabls, disables, or grays a menu item

EnableScrollBar	Enables or disables scroll-bar arrows

EnableWindow	Sets the window-enable state

EndDeferWindowPos	Updates position and size of multiple windows

EndDialog	Destroys a modal dialog box

EndPaint	Marks end of painting in the specified window

EnumChildWindows	Passes child-window handles to callback function

EnumClipboardFormats	Returns available clipboard formats

EnumProps	Returns window property list

EnumPropsEx	Returns window property list

EnumThreadWindows	Returns thread windows

EnumWindows	Returns parent windows

EqualRect	Determines whether two rectangles are equal

ExcludeUpdateRgn	Excludes updated region from clipping region

ExitWindows	Logs off the current user

ExitWindowsEx	Shuts down Windows

FillRect	Fills a rectangle with the specified brush

FindWindow	Returns window handle for class and window name

FlashWindow	Flashes a window once

FrameRect	Draws a window border with a specified brush

FreeDDElParam	Frees a DDE message lParam

GetActiveWindow	Retrieves the handle of the active window

GetAsyncKeyState	Determines key state

GetCapture	Returns the handle of the mouse-capture window

GetCaretBlinkTime	Returns the caret blink time

GetCaretPos	Returns the caret position

GetClassInfo	Returns window class information

GetClassLong	Returns window-class data

GetClassName	Returns window class name

GetClassWord	Returns window class memory word

GetClientRect	Returns window client area coordinates

GetClipboardData	Returns a handle to clipboard data

GetClipboardFormatName	Returns registered clipboard format name

GetClipboardOwner	Returns clipboard owner window handle

GetClipboardViewer	Returns first clipboard viewer window handle

GetClipCursor	Returns coordinates of cursor-confining rectangle

GetCurrentTime	Returns elapsed time since Windows started

GetCursor	Retrieves the handle to the current cursor

GetCursorPos	Returns current cursor position

GetDC	Returns window device-context handle

GetDCEx	Retrieves the handle of a display context

GetDesktopWindow	Returns desktop window handle

GetDialogBaseUnits	Returns dialog box base units

GetDlgCtrlID	Returns a control identifier

GetDlgItem	Returns handle of a dialog control

GetDlgItemInt	Translates dialog box text into an integer

GetDlgItemText	Retrieves dialog control text

GetDoubleClickTime	Returns mouse double-click time

GetFocus	Returns current focus window handle

GetForegroundWindow	Returns handle for foreground window

GetIconInfo	Returns icon or cursor information

GetInputState	Determines mouse, keyboard and timer queuing status

GetKBCodePage	Get OEM system code page

GetKeyboardLayoutName	Retrieves name of active keyboard layout

GetKeyboardState	Returns virtual-keyboard keys status

GetKeyboardType	Retrieves keyboard information

GetKeyNameText	Retrieves string representing the name of a key

GetKeyState	Retrieves the status of a virtual key

GetLastActivePopup	Determines most recently active pop-up window

GetMenu	Returns menu handle for the specified window

GetMenuCheckMarkDimensions	Returns default check mark bitmap dimensions

GetMenuItemCount	Returns the number of items in a menu

GetMenuItemID	Returns a menu-item identifier

GetMenuState	Returns menu flags for the specified menu item

GetMenuString	Copies a menu-item string into a buffer

GetMessage	Retrieves a message from a thread message queue

GetMessageExtraInfo	Retrieves information about a hardware message

GetMessagePos	Returns cursor position for last message

GetMessageTime	Returns the time for the last message

GetNextDlgGroupItem	Returns handle of previous or next group control

GetNextDlgTabItem	Returns the next or previous WS_TABSTOP control

GetNextWindow	Returns next or previous window-manager window

GetOpenClipboardWindow	Returns handle to window that opened clipboard

GetParent	Returns parent window handle

GetPriorityClipboardFormat	Returns first clipboard format

GetProp	Returns data handle from a window property list

GetQueueStatus	Determines content of message queue

GetScrollPos	Returns the scroll-bar position

GetScrollRange	Returns minimcmum and maximum scroll-bar positions

GetSubMenu	Returns pop-up menu handle

GetSysColor	Returns display-element color

GetSystemMenu	Provides access to the System menu

GetSystemMetrics	Retrieves the system metrics

GetTabbedTextExtent	Determines dimensions of tabbed string

GetTickCount	Returns amount of time Windows has been running

GetTopWindow	Returns handle of top child of given window

GetUpdateRect	Returns window update region dimensions

GetUpdateRgn	Returns window update region

GetWindow	Returns specified window handle

GetWindowDC	Returns window device context

GetWindowLong	Returns long value from extra window memory

GetWindowPlacement	Returns window show state and min/max position

GetWindowRect	Returns window coordinates

GetWindowText	Copies window title-bar text to a buffer

GetWindowTextLength	Returns length of window title-bar text

GetWindowThreadProcessId	Returns window thread and process IDs

GetWindowWord	Returns word value from extra window memory

GrayString	Draws gray text at the specified location

HideCaret	Removes the caret from the screen

HiliteMenuItem	Changes highlight of top-level menu item

ImpersonateDdeClientWindow	Impersonates a DDE client window

InflateRect	Changes rectangle dimensions

InSendMessage	Determines if a window is processing SendMessage

InsertMenu	Inserts a new item in a menu

IntersectRect	Calculates the intersection of two rectangles

InvalidateRect	Adds a rectangle to the update region

InvalidateRgn	Adds a region to the update region

InvertRect	Inverts a rectangular region

IsCharAlpha	Determines if a character is alphabetic

IsCharAlphaNumeric	Determines is a character is alphanumeric

IsCharLower	Determines if a character is lowercase

IsCharUpper	Determines if a character is uppercase

IsChild	Determines if a window is a child

IsClipboardFormatAvailable	Determines if a format is available

IsDialogMessage	Determines if a message is for a dialog box

IsDlgButtonChecked	Determines the state of a button control

IsIconic	Determines if a window is minimized

IsMenu	Determines whether handle is a menu handle

IsRectEmpty	Determines whether rectangle is empty

IsWindow	Determines if a window handle is valid

IsWindowEnabled	Determines if a window accepts user input

IsWindowUnicode	Determines if a window uses Unicode

IsWindowVisible	Determines if a window exists on the screen

IsZoomed	Determines if a window is maximized

keybd_event	Synthesizes a keystroke

KillTimer	Removes a timer

LoadAccelerators	Loads an accelerator table

LoadBitmap	Loads a bitmap resource

LoadCursor	Loads a cursor resource

LoadIcon	Loads an icon resource

LoadKeyboardLayout	Loads a keyboard layout

LoadMenu	Loads a menu resource

LoadMenuIndirect	Obtains a menu handle for a menu template

LoadString	Loads a string resource

LockWindowUpdate	Disables or reenables drawing in a window

LookupIconIdFromDirectory	Returns an icon or cursor ID

MapDialogRect	Maps dialog box units to pixels

MapVirtualKey	Translates a virual-key code or scan code

MapWindowPoints	Converts points to another coordinate system

MessageBeep	Generates a sound

MessageBox	Creates a message-box window

MessageBoxEx	Creates a message-box window

ModifyMenu	Changes an existing menu item

mouse_event	Synthesizes mouse motion and button clicks

MoveWindow	Changes the position and dimensions of a window

MsgWaitForMultipleObjects	Waits for multiple object handles or input

OemKeyScan	Maps OEM ASCII to scan codes

OemToChar	Translates an OEM string

OemToCharBuff	Translates an OEM string

OffsetRect	Moves a rectangle by an offset

OpenClipboard	Opens the clipboard

OpenIcon	Restores and activates a minimized window

PackDDElParam	Packs data into a DDE message lParam

PeekMessage	Checks message queue

PostMessage	Places a message in a thread's message queue

PostQuitMessage	Tells Windows that a thread is terminating

PostThreadMessage	Posts a message to a thread

ProfClear	Obsolete

ProfFinish	Obsolete

ProfFlush	Obsolete

ProfInsChk	Obsolete

ProfSampRate	Obsolete

ProfSetup	Obsolete

ProfStart	Obsolete

ProfStop	Obsolete

PtInRect	Determines if a point is in a rectangle

RedrawWindow	Updates a client rectangle or region

RegisterClass	Registers a window class

RegisterClipboardFormat	Registers a new clipboard format

RegisterHotKey	Registers hot key with a thread

RegisterWindowMessage	Defines a new unique window message

ReleaseCapture	Releases the mouse capture

ReleaseDC	Frees a device context

RemoveMenu	Deletes a menu item and pop-up menu

RemoveProp	Removes a property-list entry

ReplyMessage	Replies to a message sent through SendMessage

ReuseDDElParam	Reuse a DDE message lParam

ScreenToClient	Converts screen point to client coordinates

ScrollDC	Scrolls a rectangle horizontally and vertically

ScrollWindow	Scrolls a window's client area

ScrollWindowEx	Scrolls a window's client area

SendDlgItemMessage	Sends a message to a dialog box control

SendMessage	Sends a message to a window procedure

SendMessageCallback	Sends a message to a window procedure

SendMessageTimeout	Sends a message to a window procedure

SendNotifyMessage	Sends a message to a window procedure

SetActiveWindow	Activates a top-level window

SetCapture	Sets the mouse capture to a window

SetCaretBlinkTime	Sets caret blink time

SetCaretPos	Sets the caret position

SetClassLong	Sets a long value in extra class memory

SetClassWord	Sets a word value in extra class memory

SetClipboardData	Sets the data in the clipboard

SetClipboardViewer	Adds a window to the clipboard-viewer chain

SetCursor	Changes the mouse cursor

SetCursorPos	Sets mouse-cursor position in screen coordinates

SetDlgItemInt	Converts an integer to a dialog text string

SetDlgItemText	Sets dialog title or item text

SetDoubleClickTime	Sets the mouse double-click time

SetFocus	Sets the keyboard focus to a window

SetForegroundWindow	Puts a window in the foreground

SetKeyboardState	Sets the keyboard state table

SetMenu	Sets the menu for a window

SetMenuItemBitmaps	Associates check mark bitmaps with a menu item

SetMessageQueue	Creates a new message queue

SetParent	Changes a child's parent window

SetProp	Adds or changes a property-list entry

SetRect	Sets a rectangle's dimensions

SetRectEmpty	Creates an empty rectangle

SetScrollPos	Sets scroll-box position

SetScrollRange	Sets minimum and maximum scroll-bar positions

SetSysColors	Sets one or more system colors

SetTimer	Installs a system timer

SetWindowLong	Sets a long value in extra window memory

SetWindowPlacement	Sets window show state and min/max position

SetWindowPos	Sets a windows size, position, and order

SetWindowsHook	Installs a hook procedure

SetWindowsHookEx	Installs a hook procedure

SetWindowText	Sets text in a caption title or control window

SetWindowWord	Sets a word value in extra window memory

ShowCaret	Shows (unhides) the caret

ShowCursor	Shows or hides the mouse cursor

ShowOwnedPopups	Shows or hides pop-up windows

ShowScrollBar	Shows or hides a scroll bar

ShowWindow	Sets window visibility state

SubtractRect	Subtracts one rectangle from another

SwapMouseButton	Reverses the meaning of the mouse buttons

SystemParametersInfo	Queries or sets system-wide parameters

TabbedTextOut	Writes a tabbed character string

ToAscii	Translates virtual-key code to Windows character

ToUnicode	Maps virtual-key code to Unicode character

TrackPopupMenu	Displays and tracks a pop-up menu

TranslateAccelerator	Processes accelerator keys for menu commands

TranslateMDISysAccel	Processes MDI keyboard accelerators

TranslateMessage	Translates virtual-key messages

UnhookWindowsHook	Removes a filter function

UnhookWindowsHookEx	Removes a function from the hook chain

UnionRect	Creates the union of two rectangles

UnloadKeyboardLayout	Unloads a keyboard layout

UnpackDDElParam	Unpacks data from a DDE message lParam

UnregisterClass	Removes a window class

UnregisterHotKey	Releases a hot key from a thread

UpdateWindow	Updates a window's client area

ValidateRect	Removes a rectangle from the update region

ValidateRgn	Removes a region from the update region

VkKeyScan	Translates character to virtual-key code

WaitMessage	Suspends an application and yields control

WindowFromDC	Returns a window for a device context

WindowFromPoint	Returns window containing a point

WinHelp	Invokes Windows Help

AnsiLower	Obsolete

AnsiLowerBuff	Obsolete

AnsiNext	Obsolete

AnsiPrev	Obsolete

AnsiToOem	Obsolete

AnsiToOemBuff	Obsolete

AnsiUpper	Obsolete

AnsiUpperBuff	Obsolete

ChangeMenu	Obsolete

DefHookProc	Obsolete

DlgDirSelect	Obsolete

DlgDirSelectComboBox	Obsolete

EnumTaskWindows	Obsolete

GetWindowTask	Obsolete

GetSysModalWindow	Obsolete

OemToAnsi	Obsolete

OemToAnsiBuff	Obsolete

PostAppMessage	Obsolete

SetSysModalWindow	Obsolete


Windows Overview

About Windows

A window in an application written for Microsoft® Windows™ is a rectangular area of the screen where the application displays output and receives input from the user. A window shares the screen with other windows, including those from other applications. Only one window at a time can receive input from the user. The user can use the mouse, keyboard, or other input device to interact with this window and the application that owns it.

Windows are the only means a Windows-based application has to interact with the user and accomplish tasks, so one of the first tasks of a Windows-based application is to create a window. This topic describes the application programming interface (API) elements of Windows that applications use to create and use windows; manage relationships between windows; and size, move, and display windows.

The following topics discuss windows:

Terms

Desktop Window

Application Windows

Window Creation

Window Handles

Window Styles

Owned Windows

Disabled Windows

Foreground and Background Windows

Show State

Size and Position

Window Destruction

Creating a Main Window

Creating, Enumerating, and Sizing Child Windows

Destroying a Window

Functions and Messages


Desktop Window

When Windows starts, it automatically creates the desktop window. The desktop window is a system-defined window that paints the background of the screen and serves as the base for all windows displayed by all Windows-based applications.

The desktop window uses a bitmap stored in a bitmap file (with the .BMP filename extension) to paint the background of the screen. The pattern created by the bitmap is called the desktop wallpaper. By default, the desktop window uses the bitmap from the file specified in the following key of the registry as the desktop wallpaper:

HKEY_CURRENT_USER\Control Panel\Desktop\Wallpaper

A system configuration application, such as Windows Control Panel, can change the desktop wallpaper by using the SystemParametersInfo function with the wAction parameter set to SPI_SETDESKWALLPAPER and the lpvParam parameter specifying a bitmap filename. SystemParametersInfo then loads the bitmap from the specified file, uses the bitmap to paint the background of the screen, and enters the new filename in the Wallpaper key of the registry. For more information about bitmaps, see Bitmaps. For more information about the registry, see Registry and Initialization Files.


Application Windows

Every Windows-based application creates at least one window, called the main window that serves as the main window for the application. This window, serves as the primary interface between the user and the application. Most applications also create many other windows, either directly or indirectly, to carry out tasks related to the main window. Each window plays a part in displaying output and receiving input from the user.

Components of an Application Window

An application window can include a title bar, a menu bar, a System menu (also called the Control menu), a minimize box, a maximize box, a sizing border, a client area, a horizontal scroll bar, and a vertical scroll bar. An application's main window typically includes all of these components. The following illustration shows these components in a typical main window.

The title bar displays an application-defined line of text; typically, the text specifies the name of the application or indicates the purpose of the window. An application specifies the text when creating the window. The title bar also makes it possible for the user to move the window by using a mouse or other pointing device.

Most applications include a menu that lists the commands supported by the application. Items in the menu bar represent the main categories of commands. Choosing an item from the menu bar typically opens a pop-up menu whose items correspond to the tasks within a given category. By selecting a command, the user directs the application to carry out a task.

The System-menu box is a bitmap that, when clicked, displays the System menu. The System menu is a menu created and managed by Windows. It contains a standard set of menu items that, when chosen by the user, set a window's size or position, close the application, or open the Windows Task List. For more information about menus and the System menu, see Menus.

The maximize and minimize boxes are bitmaps that, when clicked, affect a window's size and position. When the user clicks the maximize box, Windows enlarges the window to the size of the screen and positions the window, so it covers the entire screen. At the same time, Windows replaces the maximize box with the restore box. The restore box is a bitmap that, when clicked, restores the window to its previous size and position.

When the user clicks the minimize box, Windows reduces the window to the size of an icon, positions the window at the bottom of the screen, and displays the window's icon at the position of the window. An icon is a 32- by 32-pixel bitmap that represents a window. For more information about icons, see Icons.

The sizing border is an area around the perimeter of the window that enables the user to size the window by using a mouse or other pointing device.

The client area is the part of a window where the application displays output, such as text or graphics. For example, a desktop publishing application displays the current page of a document in the client area. The application must provide a function, called a window procedure, to process input to the window and display output in the client area. For more information about window procedures, see Window Procedures.

The horizontal and vertical scroll bars convert mouse or keyboard input into values that an application uses to shift the contents of the client area either horizontally or vertically. For example, a word processing application that displays a lengthy document typically provides a vertical scroll bar to enable the user to page up and down through the document.

The title bar, menu bar, System menu, minimize and maximize boxes, sizing border, and scroll bars are referred to collectively as the window's nonclient area. Windows manages most aspects of the nonclient area; the application manages everything else about the window. In particular, the application manages the appearance and behavior of the client area.

Controls, Dialog Boxes, and Message Boxes

An application uses several types of windows in addition to its main window, including controls, dialog boxes, and message boxes.

A control is a window that an application uses to obtain a specific piece of information from the user, such as the name of a file to open or the desired point size of a text selection. Applications also use controls to obtain information needed to control a particular feature of an application. For example, a word processing application typically provides a control to let the user turn wordwrapping on and off. For more information about controls, see Controls, Buttons, List Boxes, EditControls, Combo Boxes, Scroll Bars, and Static Controls.

Controls are always used in conjunction with another window--typically, a dialog box. A dialog box is a window that contains one or more controls. An application uses a dialog box to prompt the user for input needed to complete a command. For example, an application that includes a command to open a file would display a dialog box that includes controls in which the user specifies a path and filename. The following illustration shows the Open dialog box and its associated controls file.

A message box is a window that displays a note, caution, or warning to the user. For example, a message box can inform the user of a problem the application has encountered while carrying out a task. The following illustration shows a message box that explains why the application, Microsoft® Word for Windows™ cannot complete a file-save operation.

Dialog boxes and message boxes do not typically use the same set of window components as does a main window. Most have a title bar, a System menu, a border (non-sizing), and a client area, but they typically do not have a menu bar, minimize and maximize buttons, or scroll bars. For more information about dialog boxes and message boxes, see Dialog Boxes.


Window Creation

An application creates its main window by using the CreateWindow or CreateWindowEx function and providing information Windows needs to define the attributes of the window. The CreateWindowEx function has a parameter, dwExStyle, that the CreateWindow function does not have; otherwise, the functions are identical. In fact, CreateWindow simply calls CreateWindowEx, setting the dwExStyle parameter to zero. For this reason, the remainder of this topic refers only to the CreateWindowEx function.

Windows provides additional functions--including DialogBox, CreateDialog, and MessageBox--for creating special-purpose windows such as dialog boxes and message boxes. For more information about these functions, see Dialog Boxes.

Window Attributes

An application must provide the following information when creating a window:

Window class

Window name

Window style

Parent or owner window

Size

Location

Position

Child-window identifier or menu handle

Instance handle

Creation data

These attributes are described in the following sections.

Window Class

Every window belongs to a window class. An application must register a window class before creating any windows of that class. The window class defines most aspects of a window's appearance and behavior. The chief component of a window class is the window procedure, a function that receives and processes all input and requests sent to the window. Windows provides the input and requests in the form of messages. For more information about window classes, window procedures, or messages, see Window Classes, Window Procedures, or Messages and Message Queues.

Window Name

A window can have a name. A window name (also called window text) is a text string that identifies a window for the user. A main window, dialog box, or message box typically displays its window name in its title bar, if present. For a control, the appearance of the window name depends on the control's class. A button, edit control, or static control displays its window name within the rectangle occupied by the control. A list box, combo box, or static control does not display its window name.

An application uses the SetWindowText function to change the window name after creating the window. It uses the GetWindowTextLength and GetWindowText functions to retrieve the current window-name text from a window.

Window Style

Every window has one or more window styles. A window style is a named constant that defines an aspect of the window's appearance and behavior that is not specified by the window's class. For example, the SCROLLBAR class creates a scroll bar control, but the SBS_HORZ and SBS_VERT styles determine whether a horizontal or vertical scroll bar control is created. A few window styles apply to all windows, but most apply to windows of specific window classes. Windows and, to some extent, the window procedure for the class, interpret the styles.

Parent or Owner Window

A window can have a parent window. A window that has a parent is called a child window. The parent window provides the coordinate system used for positioning a child window. Having a parent window affects aspects of a window's appearance; for example, a child window is clipped so that no part of the child window can appear outside the borders of its parent window. A window that has no parent, or whose parent is the desktop window, is called a top-level window. An application uses the EnumWindows function to obtain the handle of each of its top-level windows. EnumWindows passes the handle of each top-level window, in turn, to an application-defined callback function (a function called by Windows).

A window can own, or be owned by, another window. An owned window always appears in front of its owner window, is hidden when its owner window is minimized, and is destroyed when its owner window is destroyed.

Location, Size, and Position in the Z Order

Every window has a location, size, and position in the Z order. The location is the coordinates of the window's upper-left corner, relative to the upper-left corner of the screen or, in the case of a child window, the upper-left corner of the parent's client area. A window's size is its width and height measured in pixels. A window's position in the Z order is the position of the window in a stack of overlapping windows.

Child-Window Identifier or Menu Handle

A child window can have a child-window identifier, a unique application-defined value associated with the child window. Child-window identifiers are especially useful in applications that create multiple child windows. When creating a child window, an application specifies the identifier of the child window. After creating the window, the application can change the window's identifier by using the SetWindowLong function, or it can retrieve the identifier by using the GetWindowLong function.

Every window, except a child window, can have a menu. An application can include a menu by providing a menu handle either when registering the window's class or when creating the window.

Instance Handle

Every Windows-based application has an instance handle associated with it. Windows provides the instance handle to an application when the application starts. Because it can run multiple copies of the same application, Windows uses instance handles internally to distinguish one instance of an application from another. The application must specify the instance handle in many different windows, including those that create windows.

Creation Data

Every window can have application-defined creation data associated with it. When the window is first created, Windows passes a pointer to the data on to the window procedure of the window being created. The window procedure uses the data to initialize application-defined variables.

Main Window Creation

Every Windows-based application must have a WinMain function as its entry point. The WinMain function performs a number of tasks, including registering the window class for the main window and creating the main window. WinMain registers the main window class by calling the RegisterClass function, and it creates the main window by calling the CreateWindowEx function.

Portability Issue:	In Windows NT, the entry point can have a name other than WinMain. In Windows version 3.x, the entry point must be named WinMain.

Windows does not automatically display the main window after creating it; the application must use the ShowWindow function to display the main window. Typically, the application's WinMain function calls ShowWindow immediately after creating the main window. WinMain passes two parameters to ShowWindow: the handle of the main window and a flag specifying whether the main window should be minimized or maximized when it is first displayed. Normally, the flag can be set to any of the constants beginning with the SW_ prefix that are defined in the Windows header files. However, when ShowWindow is called to display the application's main window, the flag must be set to SW_SHOWDEFAULT. This flag tells Windows to display the window as directed by the program that launched the application.

Window-Creation Messages

When creating any window, Windows sends messages to the window procedure for the window. Windows sends the WM_NCCREATE message after creating the window's nonclient area and the WM_CREATE message after creating the client area. The window procedure receives both messages before Windows displays the window. Both messages include a pointer to a CREATESTRUCT structure that contains all the information specified in the CreateWindowEx function. Typically, the window procedure performs initialization tasks upon receiving these messages.

When creating a child window, Windows sends the WM_PARENTNOTIFY message to the parent window after sending the WM_NCCREATE and WM_CREATE messages. It also sends other messages while creating a window. The number and order of these messages depend on the window class and style and on the function used to create the window. These messages are described in the remaining sections of this topic and in other chapters of this book.

Multithread Applications

A Windows NT application can have multiple threads of execution, and each thread can create windows. An application can use the EnumThreadWindows function to enumerate the windows created by a particular thread. This function passes the handle of each thread window, in turn, to an application-defined callback function. The GetWindowThreadProcessId function returns the identifier of the thread that created a particular window.


Window Handles

After creating a window, the creation function returns a window handle that uniquely identifies the window. An application uses this handle in other functions to direct their actions to the window. A window handle has the HWND data type; an application must use this type when declaring a variable that holds a window handle.

Windows includes several special constants that can replace a window handle in certain functions. These constants begin with the HWND_ prefix. For example, an application can use the HWND_TOP or HWND_BOTTOM constant in the SetWindowPos function to move a window to the top or bottom of the Z order.

Although the NULL constant is not a window handle, an application can use it in some functions to specify that no window is affected. For example, specifying NULL for the CreateWindowEx function's hwndParent parameter creates a window that has no parent or owner. Some functions may return NULL instead of a handle, indicating that the given action applies to no window.

An application can use the FindWindow function to discover whether a window with the specified class name or window name exists in the system. If such a window exists, FindWindow returns the handle of the window. The IsWindow function determines whether a window handle identifies a valid, existing window.


Window Styles

Windows provides general window styles and class-specific window styles. The general windows styles are constants that begin with the WS_ prefix; they can be combined to form different types of windows, including main windows, dialog boxes, and child windows. The class-specific window styles define the appearance and behavior of windows belonging to the predefined control classes such as edit controls and list boxes. This section describes the general window styles. For information about class-specific window styles, see Buttons, List Boxes, EditControls, Combo Boxes, Scroll Bars, and Static Controls.

An application usually sets a window's styles when creating the window. It can also set the styles after creating the window by using the SetWindowLong function.

Overlapped Window

An overlapped window is a top-level window that has a title bar, border, and client area; it is meant to serve as an application's main window. It can also have a System menu, minimize and maximize boxes, and scroll bars. An overlapped window used as a main window typically includes all of these components.

An application creates an overlapped window by specifying the WS_OVERLAPPED or WS_OVERLAPPEDWINDOW style in the CreateWindowEx function. An overlapped window created with the WS_OVERLAPPED style has a title bar and border. The WS_OVERLAPPEDWINDOW style creates an overlapped window with a title bar, sizing border, System menu, and minimize and maximize boxes.

Pop-up Window

A pop-up window is 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. A title bar is optional for a pop-up window; otherwise, a pop-up window is the same as an overlapped window created with the WS_OVERLAPPED style.

An application creates a pop-up window by specifying the WS_POPUP style in the CreateWindowEx function. To include a title bar, the WS_CAPTION style must also be specified. An application can use the WS_POPUPWINDOW style to create a pop-up window that has a border and a System menu. The WS_CAPTION style must be combined with the WS_POPUPWINDOW style to make the System menu visible.

Child Window

A child window has the WS_CHILD style and is confined to the client area of its parent window. An application typically uses child windows to divide the client area of a parent window into functional areas. An application creates a child window by specifying the WS_CHILD style in the CreateWindowEx function.

A child window must have a parent window. The parent window can be an overlapped window, a pop-up window, or even another child window. An application specifies the parent window when it calls the CreateWindowEx function. If the application specifies the WS_CHILD style in the CreateWindowEx function but does not specify a parent window, Windows does not create the window.

A child window has a client area, but it does not have any other features unless they are explicitly requested. An application can request a title bar, a System menu, minimize and maximize boxes, a border, and scroll bars for a child window, but a child window cannot have a menu. If the application specifies a menu handle, either when it registers the child's window class or creates the child window, the menu handle is ignored.

Positioning

Windows always positions the child window relative to the upper-left corner of the parent window's client area. No part of a child window ever appears outside the borders of its parent window. If an application creates a child window that is larger than the parent window or positions a child window so that some or all of the child window extends beyond the borders of the parent, Windows clips the child window; that is, the portion outside the parent window's client area is not displayed. Actions that affect the parent window can also affect the child window, as follows.

Parent window	Child window

Destroyed	Destroyed before the parent window is destroyed.

Hidden	Hidden before the parent window is hidden. A child window is visible only when the parent window is visible.

Moved	Moved with the parent window's client area. The child window is responsible for painting its client area after the move.

Shown	Shown after the parent window is shown.

Clipping

Windows does not automatically clip a child window from the parent window's client area. This means the parent window draws over the child window if it carries out any drawing in the same location as the child window. Windows does, however, clip the child window from the parent window's client area if the parent window has the WS_CLIPCHILDREN style. If the child window is clipped, the parent window cannot draw over it.

A child window can overlap other child windows in the same client area. A child window that shares the same parent window as one or more other child windows is called a sibling window. Sibling windows can draw in each other's client area, unless one of the child windows has the WS_CLIPSIBLINGS style. If the application specifies this style for a child window, any portion of the child's sibling window that lies within this window is clipped.

If a window has either the WS_CLIPCHILDREN or WS_CLIPSIBLINGS style, a slight loss in performance occurs. Each window takes up system resources, so an application should not use child windows indiscriminately. For optimum performance, an application that needs to logically divide its main window should do so in the window procedure of the main window rather than by using child windows.

Relationship to Parent Window

An application can change the parent window of an existing child window by calling the SetParent function. In this case, Windows removes the child window from the client area of the old parent window and moves it to the client area of the new parent window. If SetParent specifies a NULL handle, the desktop window becomes the new parent window. In this case, the child window is drawn on the desktop, outside the borders of any other window. The GetParent function retrieves the handle of a child window's parent window.

The parent window relinquishes a portion of its client area to a child window, and the child window receives all input from this area. The window class need not be the same for each of the child windows of the parent window. This means that an application can fill a parent window with child windows that look different and carry out different tasks. For example, a dialog box can contain many types of controls; each control is a child window that accepts a different type of data from the user.

A child window has only one parent window, but a parent can have any number of child windows. Each child window, in turn, can have child windows. In this chain of windows, each child window is called a descendant window of the original parent window. An application uses the IsChild function to discover whether a given window is a child window or a descendant window of a given parent window.

The EnumChildWindows function enumerates the child windows of a parent window. Then EnumChildWindows passes the handle of each child window to an application-defined callback function. Descendant windows of the given parent window are also enumerated.

Messages

Windows passes a child window's input messages directly to the child window; the messages are not passed through the parent window. The only exception is if the child window has been disabled by the EnableWindow function. In this case, Windows passes any input messages that would have gone to the child window to the parent window instead. This permits the parent window to examine the input messages and enable the child window, if necessary.

A child window can have a unique integer identifier. Child window identifiers are important when working with control windows. An application directs a control's activity by sending it messages. The application uses the control's child window identifier to direct the messages to the control. In addition, a control sends notification messages to its parent window. A notification message includes the control's child window identifier, which the parent uses to identify which control sent the message. An application specifies the child-window identifier for other types of child windows by setting the hmenu parameter of the CreateWindowEx function to a value rather than a menu handle.

Window Border

Windows provides the following border style.

Style	Description

WS_BORDER	Creates a window with a thin-line border.

WS_DLGFRAME	Creates a window with a double border, a style typically used with dialog boxes. A window with this style cannot have a title bar.

WS_EX_DLGMODALFRAME	Creates a window with a double border. Unlike the WS_DLGFRAME style, an application can also specify the WS_CAPTION style to create a title bar for the window.

WS_THICKFRAME	Creates a window with a sizing border.

A window with the WS_OVERLAPPED or WS_POPUPWINDOW style has the WS_BORDER style by default. One of the other border styles must be combined with the WS_OVERLAPPED or WS_POPUPWINDOW style to give an overlapped window a different border style.

If no border style is specified for a window with the WS_POPUP or WS_CHILD style, the system creates a borderless window. An application can use borderless child windows to divide the parent window's client area while keeping the divisions invisible to the user.

Nonclient-Area Components

The nonclient area of a window can include a title bar, System menu, minimize and maximize boxes, sizing border, and horizontal and vertical scroll bars. An application can create a window with one or more of these components by specifying the following styles in the CreateWindowEx function.

Style	Description

WS_CAPTION	Creates a window that has a title bar (includes the WS_BORDER style).

WS_HSCROLL	Creates a window that has a horizontal scroll bar.

WS_MAXIMIZEBOX	Creates a window that has a maximize box.

WS_MINIMIZEBOX	Creates a window that has a minimize box.

WS_SYSMENU	Creates a window that has a System-menu box in its title bar. The WS_CAPTION style must also be specified.

WS_VSCROLL	Creates a window that has a vertical scroll bar.

Initial State

The following styles determine whether a window is enabled or disabled, visible or invisible, and minimized or maximized.

Style	Description

WS_DISABLED	Creates a window that is initially disabled. A disabled window cannot receive input from the user.

WS_MAXIMIZE	Creates a window that is initially maximized.

WS_MINIMIZE	Creates a window that is initially minimized.

WS_VISIBLE	Creates a window that is initially visible.

Parent and Child Styles

The following styles affect the clipping relationship between a parent window and its child windows and between a child window and its sibling windows.

Style	Description

WS_CLIPCHILDREN	Excludes the area occupied by child windows when drawing within the parent window. Use this style 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 one child window, to draw within the client area of another neighboring child window. Use this style with the WS_CHILD style only.

Dialog Box Styles

A dialog box includes a built-in keyboard interface that processes the direction and TAB keys. The user can use these keys instead of the mouse to navigate among the controls in the dialog box. The following styles affect how the built-in keyboard interface processes the direction and TAB keys.

Style	Description

WS_GROUP	Specifies the first control of a group of controls. The user can change the keyboard focus from one control in the group to the next by using the direction keys. All controls defined with the WS_GROUP style after the first control belong to the same group. The next control with the WS_GROUP style ends the group and starts the next group.

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 that has the WS_TABSTOP style.

Extended Styles

The following styles can be specified in the dwExStyle parameter of the CreateWindowEx function.

Style	Description

WS_EX_ACCEPTFILES	Specifies that a window created with this style accepts drag-drop files. For more information about drag-drop files, see Shell Library.

WS_EX_DLGMODALFRAME	Creates a window with a double border. Unlike the WS_DLGFRAME style, an application can also specify the WS_CAPTION style to create a title bar for the window.

WS_EX_NOPARENTNOTIFY	Specifies that a child window created with this style will not send the WM_PARENTNOTIFY message to its parent window when either created or destroyed.

WS_EX_TOPMOST	Specifies that a window created with this style should be placed above all non-topmost windows and stay above them even when the window is deactivated.


Owned Windows

An overlapped or pop-up window can be owned by another overlapped or pop-up window. Being owned places several constraints on a window.

An owned window is always above its owner in the Z order.

Windows automatically destroys an owned window when its owner is destroyed.

An owned window is hidden when its owner is minimized.

Only an overlapped or pop-up window can be an owner window; a child window cannot be one. An application creates an owned window by specifying the owner's window handle as the hwndParent parameter of the CreateWindowEx function when it creates a window with the WS_OVERLAPPED or WS_POPUP style. The hwndParent parameter must identify an overlapped or pop-up window. If hwndParent identifies a child window, Windows assigns ownership to the top-level parent window of the child window. After creating an owned window, an application cannot transfer ownership of the window to another window.

Dialog boxes and message boxes are owned windows by default. An application specifies the owner window when calling a function that creates a dialog box or message box.

An application can use the GetWindow function with the GW_OWNER flag to retrieve the handle of a window's owner.


Disabled Windows

A window can be disabled. A disabled window receives no keyboard or mouse input, but it can receive messages from other windows, from other applications, and from Windows. An application typically disables a window to prevent the user from using the window. For example, an application may disable a push button in a dialog box to prevent the user from choosing it. An application can enable a disabled window at any time; enabling a window restores normal input.

By default, a window is enabled when created. An application can specify the WS_DISABLED style, however, to disable a new window. An application enables or disables an existing window by using the EnableWindow function. Windows sends a WM_ENABLE message to a window when its enabled state is about to change. An application can determine whether a window is enabled by using the IsWindowEnabled function.

When a child window is disabled, Windows passes the child's mouse input messages to the parent window. The parent uses the messages to determine whether to enable the child window. For more information about mouse input, see Mouse Input.

Only one window at a time can receive keyboard input; that window is said to have the keyboard focus. If an application uses the EnableWindow function to disable a keyboard-focus window, the window loses the keyboard focus in addition to being disabled. EnableWindow then sets the keyboard focus to NULL, meaning no window has the focus. If a child window or other descendant window has the keyboard focus, the descendant window loses the focus when the parent window is disabled. For more information about the keyboard focus, see Keyboard Input.


Foreground and Background Windows

In Windows NT, each process can have multiple threads of execution, and each thread can create windows. The thread that created the window with which the user is currently working is called the foreground thread, and the window is called the foreground window. All other threads are background threads, and the windows created by background threads are called background windows.

Each thread has a priority level that determines the amount of CPU time the thread receives. Although an application can set the priority level of its threads, normally the foreground thread has a slightly higher priority level than the background threads. Because it has a higher priority, the foreground thread receives more CPU time than the background threads. The foreground thread has a normal base priority of 9; a background thread has a normal base priority of 7.

The user sets the foreground window by clicking a window or by using the ALT+TAB or ALT+ESC key combination. An application sets the foreground window by using the SetForegroundWindow function. If the new foreground window is a top-level window, Windows activates it; otherwise, Windows activates the associated top-level window. An application retrieves the handle of the foreground window by using the GetForegroundWindow function.


Show State

At any one given time, a window may be active or inactive; hidden or visible; and minimized, maximized, or restored. These qualities are referred to collectively as the window's show state.

Active Window

An active window is the top-level window of the application with which the user is currently working. To allow the user to easily identify the active window, Windows places it at the top of the Z order and changes the color of its title bar and border to the system-defined active window colors. Only a top-level window can be an active window. When the user is working with a child window, Windows activates the top-level parent window associated with the child window.

Only one top-level window in the system is active at any particular time. The user activates a top-level window by clicking it (or one of its child windows) or by using the ALT+ESC or ALT+TAB key combination. An application activates a top-level window by calling the SetActiveWindow function. A number of other functions can cause Windows to activate a different top-level window, including SetWindowPos, DeferWindowPos, SetWindowPlacement, and DestroyWindow. Although an application can activate a different top-level window at any time, to avoid confusing the user, it should do so only in response to a user action. An application uses the GetActiveWindow function to retrieve the handle of the active window.

When the activation changes from a top-level window of one application to the top-level window of another, Windows sends both applications the WM_ACTIVATEAPP message notifying them of the change. When the activation changes to a different top-level window in the same application, Windows sends the WM_ACTIVE message to both windows.

Visibility

A window can be either visible or hidden. Windows displays a visible window on the screen. It hides a hidden window by not drawing it. If a window is visible, the user can supply input to the window and view the window's output. If a window is hidden, it is effectively disabled. A hidden window can process messages from Windows or from other windows, but it cannot process input from the user or display output. An application sets a window's visibility state when creating the window. Later, the application can change the visibility state.

A window is visible when the WS_VISIBLE style is set for the window. By default, the CreateWindowEx function creates a hidden window unless the application specifies the WS_VISIBLE style. Typically, an application sets the WS_VISIBLE style after it has created a window to keep details of the creation process hidden from the user. For example, an application may keep a new window hidden while it customizes the window's appearance. If the WS_VISIBLE style is specified in the CreateWindowEx function, Windows sends the WM_SHOWWINDOW message to the window after creating the window, but before displaying it.

An application can determine whether a window is visible by using the IsWindowVisible function. An application can show (make visible) or hide a window by using the ShowWindow, SetWindowPos, DeferWindowPos, or SetWindowPosition function. These functions show or hide a window by setting or removing the WS_VISIBLE style for the window. They also send the WM_SHOWWINDOW message to the window before showing or hiding it.

When an owner window is minimized, Windows automatically hides the associated owned windows. Likewise, when an owner window is restored, Window automatically shows the associated owned windows. In both cases, Windows sends the WM_SHOWWINDOW message to the owned windows before hiding or showing them. Occasionally, an application may need to hide the owned windows without having to minimize or hide the owner. In this case, the application uses the ShowOwnedPopups function. This function sets or removes the WS_VISIBLE style for all owned windows and sends the WM_SHOWWINDOW message to the owned windows before hiding or showing them. Hiding an owner window has no effect on the visibility state of the owned windows.

When a parent window is visible, its associated child windows are also visible. Likewise, when the parent window is hidden, its child windows are also hidden. Minimizing the parent window has no effect on the visibility state of the child windows; that is, the child windows are minimized along with the parent, but the WS_VISIBLE style is not changed.

Even if a window has the WS_VISIBLE style, the user may not be able to see the window on the screen; other windows may completely overlap it or it may have been moved beyond the edge of the screen. Also, a visible child window is subject to the clipping rules established by its parent-child relationship. If the window's parent window is not visible, it will also not be visible. Because a child window is drawn relative to the parent's upper-left corner, if the parent window moves beyond the edge of the screen, the child window also moves. For example, a user may move the parent window containing the child window far enough off the edge of the screen that the user may not be able to see the child window, even though the child window and its parent window both have the WS_VISIBLE style.

Minimized, Maximized, and Restored Windows

A maximized window is a window that has the WS_MAXIMIZED style. By default, Windows enlarges a maximized window so that it fills the screen or, in the case of a child window, the parent window's client area. Although a window's size can be set to the same size of a maximized window, a maximized window is slightly different. Windows automatically moves the window's title bar to the top of the screen or to the top of the parent window's client area. Also, Windows disables the window's sizing border and the window-positioning capability of the title bar (so that the user can not move the window by dragging the title bar).

A minimized window is a window that has the WS_MINIMIZED style. By default, Windows reduces a minimized window to the size of an icon and moves the minimized window to the lower part of the screen or the lower part of the parent window's client area. The lower part of the screen or client area is sometimes called the icon area. Windows moves a minimized window into the first available position in the icon area, unless the application specifies another position. A restored window is a window that has been returned to its pre-minimized or pre-maximized size and position.

If an application specifies the WS_MAXIMIZED or WS_MINIMIZED style in the CreateWindowEx function, the window is initially maximized or minimized. After creating a window, an application can use the CloseWindow function to minimize the window. The ArrangeIconicWindows function arranges the application's minimized top-level windows along the bottom of the screen, or it arranges a parent window's minimized child windows along the bottom of the parent window.

The ShowWindow function can minimize, maximize, or restore a window. At the same time it can set the window's visibility and activation states. The SetWindowPlacement function includes the same functionality as ShowWindow, but it can also override the window's default minimized, maximized, and restored positions.

The IsZoomed function determines whether a given window is maximized, and the IsIconic function determines whether a given window is minimized. The GetWindowPlacement function retrieves the minimized, maximized, and restored positions for the window, and it also determines the window's show state.

When Windows receives a command to maximize or restore a minimized window, Windows sends the window a WM_QUERYOPEN message. If the window procedure returns FALSE, Windows ignores the maximize or restore command.

Windows automatically sets the size and position of a maximized window to the system-defined defaults for a maximized window. An application can override these defaults by using the SetWindowPlacement function or by processing the WM_GETMINMAXINFO message that is received by a window when Windows is about to maximize the window. The message includes a pointer to a MINMAXINFO structure containing values Windows uses to set the maximized size and position. Replacing these values overrides the defaults.


Size and Position

A window's size and position are expressed as a bounding rectangle, given in coordinates relative to the screen or the parent window. The coordinates of a top-level window are relative to the upper-left corner of the screen; the coordinates of a child window are relative to the upper-left corner of the parent window. An application specifies a window's initial size and position when it creates the window, but it can change the window's size and position at any time.

Size

A window's size (width and height) is given in pixels. A window can have zero width or height. If an application sets a window's width and height to zero, Windows sets the size to the default minimum window size. To discover the default minimum window size, an application uses the GetSystemMetrics function with the SM_CXMIN and SM_CYMIN flags.

An application may need to create a window with a client area of a particular size. The AdjustWindowRect and AdjustWindowRectEx functions calculate the required size of a window based on the desired size of the client area. The application can pass the resulting size values to the CreateWindowEx function.

An application can size a window so that it is extremely large; however, it should not size a window so that it is larger than the screen. Before setting a window's size, the application should check the width and height of the screen by using the GetSystemMetrics function with the SM_CXSCREEN and SM_CYSCREEN flags.

Position

A window's position is defined as the coordinates of its upper-left corner. These coordinates, sometimes called window coordinates, are always relative to the upper-left corner of the screen or, for a child window, the upper-left corner of the parent window's client area. For example, a top-level window having the coordinates (10,10) is placed 10 pixels to the right of the upper-left corner of the screen and 10 pixels down from it. A child window having the coordinates (10,10) is placed 10 pixels to the right of the upper-left corner of its parent window's client area and 10 pixels down from it.

The WindowFromPoint function retrieves the handle of the window occupying a particular point on the screen. The ChildWindowFromPoint function retrieves the handle of the child window occupying a particular point in the parent window's client area.

Default Size and Position

An application can allow Windows to calculate the initial size or position of a top-level window by specifying the CW_USEDEFAULT constant in the CreateWindowEx function. If the application sets the window's coordinates to CW_USEDEFAULT and the application has created no other top-level windows, Windows sets the new window's position relative to the upper-left corner of the screen; otherwise, Windows sets the position relative to the position of the top-level window that the application created most recently. Similarly, if the width and height parameters are set to CW_USEDEFAULT, Windows calculates the size of the new window. If the application has created other top-level windows, Windows bases the size of the new window on the size of the application's most recently created top-level window. Specifying CW_USEDEFAULT when creating a child or pop-up window causes Windows to set the window's size to the default minimum window size.

Tracking Size

Windows maintains a minimum and maximum tracking size for a window of the WS_THICKFRAME style; a window with this style has a sizing border. The minimum tracking size is the smallest window size the user can produce by dragging the window's sizing border. Likewise, the maximum tracking size is the largest window size the user can produce by dragging the sizing border.

A window's minimum and maximum tracking sizes are set to system-defined default values when Windows creates the window. An application can discover the defaults and override them by processing the WM_GETMINMAXINFO message.

System Commands

An application that has a window with a System menu can change the size and position of that window by sending system commands. System commands are generated when the user chooses commands from the System menu. An application can emulate the user action by sending a WM_SYSCOMMAND message to the window. The following system commands affect the size and position of a window.

Command	Description

SC_CLOSE	Closes the window. This command sends a WM_CLOSE message to the window. The window carries out any steps needed to clean up and destroy itself.

SC_MAXIMIZE	Maximizes the window.

SC_MINIMIZE	Minimizes the window.

SC_RESTORE	Restores a minimized or maximized window to its previous size and position.

SC_SIZE	Starts a size command. The user can change the size of the window by using the mouse or keyboard.

Z Order

The Z order of a window indicates the window's position in a stack of overlapping windows. This window stack is oriented along an imaginary axis, the z-axis, extending outward from the screen. The window at the top of the Z order overlaps all other windows. The window at the bottom of the Z order is overlapped by all other windows. An application sets a window's position in the Z order by placing it behind a given window, or at the top or bottom of the stack.

Windows maintains three separate Z orders--one for top-level windows, one for sibling windows, and one for topmost windows. A topmost window overlaps all other non-topmost windows, regardless of whether it is the active or foreground window. An application creates a topmost window by assigning it the WS_EX_TOPMOST style.

By default, Windows puts a window at the top of the Z order when creating the window. The user changes the Z order by activating a different window; Windows always positions the active window at the top of the Z order. An application uses the BringWindowToTop function to bring a window to the top of the Z order. It can rearrange the Z order by using the SetWindowPos or DeferWindowPos function.

Size and Position Functions

After creating a window, an application can set the window's size or position by calling one of a several different functions, including MoveWindow, SetWindowPos, DeferWindowPos, and SetWindowPlacement. The MoveWindow and SetWindowPos functions are similar; both set the size or position of a single application window. The SetWindowPos function includes a set of flags that affect the window's show state; MoveWindow does not include these flags. The BeginDeferWindowPos, DeferWindowPos, and EndDeferWindowPos functions are used together to set the size, position, position in the Z order, and show state of a number of windows simultaneously. The SetWindowPlacement function sets a window's minimized position, maximized position, restored size and position, and show state.

An application can retrieve the coordinates of a window's bounding rectangle by using the GetWindowRect function. GetWindowRect fills a RECT structure with the coordinates of the window's upper-left and lower-right corners. The coordinates are relative to the upper-left corner of the screen, even for a child window. The ScreenToClient or MapWindowPoints function maps the screen coordinates of a child window's bounding rectangle to coordinates relative to the parent window's client area.

The GetClientRect function retrieves the coordinates of a window's client area. GetClientRect fills a RECT structure with the coordinates of the upper-left and lower-right corners of the client area, but the coordinates are relative to the client area itself. This means the coordinates of a client area's upper-left corner are always (0,0), and the coordinates of the lower-right corner are the width and height of the client area.

Size and Position Messages

Windows sends the WM_GETMINMAXINFO message to a window whose size or position is about to change. For example, WM_GETMINMAXINFO is sent when the user chooses the Move or Size command from the System menu or clicks the sizing border or title bar, or when an application calls the SetWindowPos function to move or size the window. The WM_GETMINMAXINFO message includes a pointer to a MINMAXINFO structure containing the default maximized size and position for the window, and the default minimum and maximum tracking sizes for the window. An application can override these defaults by processing the WM_GETMINMAX message and setting the appropriate members of the MINMAXINFO structure. A window must have the WS_THICKFRAME or WS_CAPTION style to receive the WM_GETMINMAXINFO message. A window with the WS_THICKFRAME style receives this message during the window-creation process, as well as when it is being moved or sized.

Windows sends the WM_WINDOWPOSCHANGING message to a window whose size, position, position in the Z order, or show state is about to change. This message includes a pointer to a WINDOWPOS structure that specifies the window's new size, position, position in the Z order, and show state. By setting the members of the WINDOWPOS structure, an application can affect the window's new size, position, and appearance.

After changing a window's size, position, position in the Z order, or show state, Windows sends the WM_WINDOWPOSCHANGED message to the window. This message includes a pointer to a WINDOWPOS structure that informs the window of its new size, position, position in the Z order, and show state. Setting the members of the WINDOWPOS structure that is passed with the WM_WINDOWPOSCHANGED message has no effect on the window. A window that must process WM_SIZE and WM_MOVE messages must pass the WM_WINDOWPOSCHANGED message to the DefWindowProc function; otherwise, Windows does not send WM_SIZE and WM_MOVE messages to the window.

Windows sends the WM_NCCALCSIZE message to a window when the window is created or sized. Windows uses the message to calculate the size of a window's client area and the position of the client area relative to the upper-left corner of the window. A window typically passes this message to the default window procedure; however, this message can be useful in applications that customize a window's nonclient area or preserve portions of the client area when the window is sized.


Window Destruction

In general, an application must destroy all the windows it creates. It does this by using the DestroyWindow function. When a window is destroyed, the system hides the window, if it is visible, and then it removes any internal data associated with the window. This invalidates the window handle; it can no longer be used by the application.

An application destroys many of the windows it creates soon after creating them. For example, an application usually destroys a dialog box window as soon as the application has sufficient input from the user to continue its task. An application eventually destroys the main window of the application (before terminating).

Before destroying a window, an application should save or remove any data associated with the window, and it should release any system resources allocated for the window. If the application does not release the resources, Windows will free any resources not freed by the application.

Destroying a window does not affect the window class from which the window is created. New windows can still be created using that class, and any existing windows of that class continue to operate.

Destroying a window also destroys the window's descendant windows. The DestroyWindow function sends a WM_DESTROY message first to the window, then to its child windows and descendant window. In this way, all descendant windows of the window being destroyed are also destroyed.

A window with a System menu receives a WM_CLOSE message when the user chooses Close from the System menu. By processing this message, an application can prompt the user for confirmation before destroying the window. If the user confirms that the window should be destroyed, the application can call the DestroyWindow function to destroy the window.

If the window being destroyed is the active window, both the active and focus states are transferred to another window. The window that becomes the active window is the next window, as determined by the ALT+ESC key combination. The new active window then determines which window receives the keyboard focus.


Creating a Main Window

The first window an application creates is typically the main window. You create the main window by using the CreateWindowEx function, specifying the window class, window name, window styles, size, position, menu handle, instance handle, and creation data. A main window belongs to an application-defined window class, so you must register the window class and provide a window procedure for the class before creating the main window.

Most applications typically use the WS_OVERLAPPEDWINDOW style to create the main window. This style gives the window a title bar, a System menu, a sizing border, and minimize and maximize boxes. The CreateWindowEx function returns a handle that uniquely identifies the window.

The following example creates a main window belonging to an application-defined window class. The window name, "Main Window", will appear in the window's title bar. By combining the WS_VSCROLL and WS_HSCROLL styles with the WS_OVERLAPPEDWINDOW style, the application creates a main window with horizontal and vertical scroll bars in addition to the components provided by the WS_OVERLAPPED WINDOW style. The four occurrences of the CW_USEDEFAULT constant set the initial size and position of the window to the system-defined default values. Specifying NULL instead of a menu handle means the window will have the menu defined for the window class.

HINSTANCE hinst;

HWND hwndMain;

.

. /* Register the window class for the main window. */

.

/* Create the main window. */

hwndMain = CreateWindowEx(

    0,                      /* no extended styles          */

    "MainWClass",           /* class name                  */

    "Main Window",          /* window name                 */

    WS_OVERLAPPEDWINDOW |   /* overlapped window           */

        WS_HSCROLL |        /* horizontal scroll bar       */

        WS_VSCROLL,         /* vertical scroll bar         */

    CW_USEDEFAULT,          /* default horizontal position */

    CW_USEDEFAULT,          /* default vertical position   */

    CW_USEDEFAULT,          /* default width               */

    CW_USEDEFAULT,          /* default height              */

    (HWND) NULL,            /* no parent or owner window   */

    (HMENU) NULL,           /* class menu used             */

    hinstance,              /* instance handle             */

    NULL);                  /* no window creation data     */

if (!hwndMain)

    return FALSE;

/*

 * Show the window using the flag specified by the program

 * that launched the application, and send the application

 * a WM_PAINT message.

 */

ShowWindow(hwndMain, SW_SHOWDEFAULT);

UpdateWindow(hwndMain);

.

. /* Start the message loop for the application. */

.

Notice that the preceding example calls the ShowWindow function after creating the main window. This is done because Windows does not automatically display the main window after creating it. By passing the SW_SHOWDEFAULT flag to ShowWindow, the application allows the program that launched the application to set the initial show state of the main window. The UpdateWindow function sends the window its first WM_PAINT message.


Creating, Enumerating, and Sizing Child Windows

You can divide a window's client area into different functional areas by using child windows. Creating a child window is like creating a main window--you use the CreateWindowEx function. To create a window of an application-defined window class, you must register the window class and provide a window procedure before creating the child window. You must give the child window the WS_CHILD style and specify a parent window for the child window when you create it.

The following example divides the client area of an application's main window into three functional areas by creating three child windows of equal size. Each child window is the same height as the main window's client area, but is each one-third its width. The main window creates the child windows in response to the WM_CREATE message, which the main window receives during its own window-creation process. Because each child window has the WS_BORDER style, each has a thin line border. Also, because the WS_VISIBLE style is not specified, each child window is initially hidden. Notice also that each child window is assigned a child-window identifier.

The main window sizes and positions the child windows in response to the WM_SIZE message, which the main window receives when its size changes. In response to WM_SIZE, the main window retrieves the dimensions of its client area by using the GetWindowRect function and then passes the dimensions to the EnumChildWindows function. EnumChildWindows passes the handle of each child window, in turn, to the application-defined EnumChildProc callback function. This function sizes and positions each child window by calling the MoveWindow function; the size and position are based on the dimensions of the main window's client area and the identifier of the child window. Afterward, EnumChildProc calls the ShowWindow function to make the window visible.

#define ID_FIRSTCHILD  100

#define ID_SECONDCHILD 101

#define ID_THIRDCHILD  102

LONG APIENTRY MainWndProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;

UINT uMsg;

UINT wParam;

LONG lParam;

{

    RECT rcClient;

    int i;

    switch(uMsg) {

        case WM_CREATE: /* creating main window */

            /* Create three invisible child windows. */

            for (i = 0; i < 3; i++)

                CreateWindowEx(

                    0,

                    "ChildWClass",

                    (LPCTSTR) NULL,

                    WS_CHILD | WS_BORDER,

                    0,0,0,0,

                    hwnd,

                    (HMENU) (int) (ID_FIRSTCHILD + i),

                    hinst,

                    NULL);

            return 0;

        case WM_SIZE: /* main window changed size */

            /*

             * Get the dimensions of the main window's client

             * area, and enumerate the child windows. Pass the

             * dimensions to the child windows during enumeration.

             */

            GetClientRect(hwnd, &rcClient);

            EnumChildWindows(hwnd, EnumChildProc,

                (LPARAM) &rcClient);

            return 0;

        .

        . /* Process other messages. */

        .

    }

    return DefWindowProc(hwnd, uMsg, wParam, lParam);

}

BOOL CALLBACK EnumChildProc(hwndChild, lParam)

HWND hwndChild;

LPARAM lParam;

{

    LPRECT rcParent;

    int i, idChild;

    /*

     * Retrieve the child-window identifier. Use it to set the

     * position of the child window.

     */

    idChild = GetWindowLong(hwndChild, GWL_ID);

    if (idChild == ID_FIRSTCHILD)

        i = 0;

    else if (idChild == ID_SECONDCHILD)

        i = 1;

    else

        i = 2;

    /* Size and position the child window. */

    rcParent = (LPRECT) lParam;

    MoveWindow(hwndChild,

        (rcParent->right / 3) * i,

        0,

        rcParent->right / 3,

        rcParent->bottom,

        TRUE);

    /* Make sure the child window is visible. */

    ShowWindow(hwndChild, SW_SHOW);

    return TRUE;

}


Destroying a Window

You can use the DestroyWindow function to destroy a window. Typically, an application sends the WM_CLOSE message before destroying a window, giving the window the opportunity to prompt the user for confirmation before the window is destroyed. A window that includes a System menu automatically receives the WM_CLOSE message when the user chooses the Close command from the menu. If the user confirms that the window should be destroyed, the application calls DestroyWindow. Windows sends the WM_DESTROY message to the window after removing it from the screen. In response to WM_DESTROY, the window saves its data and frees any resources it allocated. A main window concludes its processing of WM_DESTROY by calling the PostQuitMessage function to quit the application.

The following example shows how to prompt for user confirmation before destroying a window. In response to WM_CLOSE, the example displays a dialog box that contains Yes, OK, and Cancel buttons. If the user clicks the Yes button, DestroyWindow is called; otherwise, the window is not destroyed. Because the window being destroyed is a main window, the example calls PostQuitMessage in response to WM_DESTROY.

case WM_CLOSE:

    /*

     * Create the message box. If the user clicks

     * the Yes button, destroy the main window.

     */

    if (MessageBox(hwnd, szConfirm, szAppName,

            MB_YESNOCANCEL) == IDYES)

        DestroyWindow(hwndMain);

    else

        return 0;

case WM_DESTROY:

    /*

     * Post the WM_QUIT message to

     * quit the application terminate.

     */

    PostQuitMessage(0);

    return 0;


Functions and Messages

Following are the functions and messages to create and manage windows.

Functions

AdjustWindowRect

AdjustWindowRectEx

AnyPopup

ArrangeIconicWindows

BeginDeferWindowPos

BringWindowToTop

ChildWindowFromPoint

CloseWindow

CreateWindow

CreateWindowEx

DeferWindowPos

DestroyWindow

EndDeferWindowPos

EnumChildProc

EnumChildWindows

EnumTaskWindows (Obsolete)

EnumThreadWindows

EnumThreadWndProc

EnumWindows

EnumWindowsProc

FindWindow

GetClientRect

GetDesktopWindow

GetForegroundWindow

GetLastActivePopup

GetNextWindow

GetParent

GetTopWindow

GetWindow

GetWindowPlacement

GetWindowRect

GetWindowTask (Obsolete)

GetWindowText

GetWindowTextLength

GetWindowThreadProcessId

IsChild

IsIconic

IsWindow

IsWindowUnicode

IsWindowVisible

IsZoomed

MoveWindow

OpenIcon

SetForegroundWindow

SetParent

SetWindowPlacement

SetWindowPos

SetWindowText

ShowOwnedPopups

ShowWindow

WindowFromPoint

WinMain

Messages

WM_ACTIVATE

WM_ACTIVATEAPP

WM_CANCELMODE

WM_CHILDACTIVATE

WM_CLOSE

WM_COPYDATA

WM_CREATE

WM_DESTROY

WM_ENABLE

WM_ENDSESSION

WM_GETMINMAXINFO

WM_GETTEXT

WM_MOVE

WM_NCACTIVATE

WM_NCCALCSIZE

WM_NCCREATE

WM_NCDESTROY

WM_PARENTNOTIFY

WM_POWER

WM_QUERYENDSESSION

WM_QUERYOPEN

WM_QUIT

WM_SETTEXT

WM_SHOWWINDOW

WM_SIZE

WM_WINDOWPOSCHANGED

WM_WINDOWPOSCHANGING


Messages and Message Queues Overview

About Messages and Message Queues

Unlike traditional applications, applications written for Microsoft® Windows™ do not make explicit function calls (such as to getchar) to obtain input. Instead, they wait for Windows to pass input to them.

Windows passes all input for an application to the various windows in the application. Each window has a function, called a window procedure, that Windows calls whenever it has input for the window. The window procedure processes the input and returns control to Windows. For more information about window procedures, see Window Procedures.

This topic describes messages and message queues and explains how to use them in your application.

The following topics describe messages and messages queues and explains how to use them in your application:

Terms

Messages

Message Routing

Message Handling

Posting and Sending Messages

Message Types

Message Filtering

Message Deadlocks

Creating a Message Loop

Examining a Message Queue

Posting a Message

Sending a Message

Functions


Messages

Windows passes input to a window procedure in the form of messages. Messages are generated by Windows and by applications. Windows generates a message at each input event--for example, when the user types, moves the mouse, or clicks a control such as a scroll bar. Windows also generates messages in response to changes in the system brought about by an application, such as when an application changes the pool of system font resources or resizes one of its windows. An application can generate messages to direct its own windows to carry out tasks or to communicate with windows in other applications.

Windows sends a message to a window procedure with a set of four parameters: a window handle, a message identifier, and two 32-bit values called message parameters. The window handle identifies the window for which the message is intended. Windows uses it to determine which window procedure to send the message to.

A message identifier is a named constant that identifies the purpose of a message. When a window procedure receives a message, it uses a message identifier to determine how to process the message. For example, the message identifier WM_PAINT tells the window procedure that the window's client area has changed and must be repainted.

Message parameters specify data or the location of data used by a window procedure when processing a message. The meaning and value of the message parameters depend on the message. A message parameter can contain an integer, packed bit flags, a pointer to a structure containing additional data, and so on. When a message does not use message parameters, it typically sets them to NULL. A window procedure must check the message identifier to determine how to interpret the message parameters.


Message Routing

Windows uses two methods to route messages to a window procedure: posting messages to a first-in, first-out queue called a message queue, a system-defined memory object that temporarily stores messages, and sending messages directly to a window procedure.

Messages posted to a message queue are called queued messages. They are primarily the result of user input entered through the mouse or keyboard, such as WM_MOUSEMOVE, WM_LBUTTONDOWN, WM_KEYDOWN, and WM_CHAR messages. Other queued messages include the timer, paint, and quit messages: WM_TIMER, WM_PAINT, and WM_QUIT. Most other messages, which are sent directly to a window procedure, are called nonqueued messages.

Queued Messages

Windows can display any number of windows at a time. To route mouse and keyboard input to the appropriate window, Windows uses message queues. It maintains a single system message queue and any number of thread message queues, one for each thread.

Whenever the user moves the mouse, clicks the mouse buttons, or types at the keyboard, the device driver for the mouse or keyboard converts the input into messages and places them in the system message queue. Windows removes the messages, one at a time, from the system message queue, examines them to determine the destination window, and then posts them to the message queue of the thread that created the destination window. A thread's message queue receives all mouse and keyboard messages for the windows created by the thread. The thread removes messages from its queue and directs Windows to send them to the appropriate window procedure for processing. For more information about threads, see Processes and Threads.

With the exception of the WM_PAINT message, Windows always posts messages at the end of a message queue. This ensures that a window receives its input messages in the proper first-in, first-out sequence. The WM_PAINT message, however, is kept in the queue and is forwarded to the window procedure only when the queue contains no other messages. Multiple WM_PAINT messages for the same window are combined into a single WM_PAINT message, consolidating all invalid parts of the client area into a single area. Combining WM_PAINT messages reduces the number of times a window must redraw the contents of its client area.

The system posts a message to a thread's message queue by filling an MSG structure and then copying it to the message queue. Information in the MSG structure includes the handle of the window for which the message is intended, the message identifier, the two message parameters, the message time, and the mouse cursor position. A thread can post a message to its own message queue or to the queue of another thread by using the PostMessage or PostThreadMessage function.

An application can remove a message from its queue by using the GetMessage function. To examine a message without removing it from its queue, an application can use the PeekMessage function. This function fills an MSG structure with information about the message.

After removing a message from its queue, an application can use the DispatchMessage function to direct Windows to send the message to a window procedure for processing. DispatchMessage takes a pointer to the MSG structure that was filled by a previous call to the GetMessage or PeekMessage function. DispatchMessage passes the window handle, the message identifier, and the two message parameters to the window procedure, but it does not pass the time or mouse cursor position. An application can retrieve this information by calling the GetMessageTime and GetMessagePos functions while processing a message.

Nonqueued Messages

Nonqueued messages are sent immediately to the destination window procedure, bypassing the system message queue and thread message queue. Windows typically sends nonqueued messages to notify a window of events that affect it. For example, when the user activates a new application window, Windows sends the window a series of messages, including WM_ACTIVATE, WM_SETFOCUS, and WM_SETCURSOR. These messages notify the window that it has been activated, that keyboard input is being directed to the window, and that the mouse cursor has been moved within the borders of the window. Nonqueued messages can also result when an application calls certain Windows functions. For example, Windows sends the WM_WINDOWPOSCHANGED message after an application uses the SetWindowPos function to move a window.

An application can send a message by calling the SendMessage, SendNotifyMessage, or SendDlgItemMessage function. For more information about sending messages, see Sending a Message.


Message Handling

An application must remove and process messages posted to the message queues of its threads. A single-threaded application usually uses a message loop in its WinMain function to remove and send messages to the appropriate window procedures for processing. Applications with multiple threads can include a message loop in each thread that creates a window. The following sections describe how a message loop works and explain the role of a window procedure.

Message Loop

A simple message loop consists of one function call to each of these functions: GetMessage, TranslateMessage, and DispatchMessage. The GetMessage function retrieves a message from the queue and copies it to an MSG structure. GetMessage returns TRUE unless it encounters the WM_QUIT message, in which case it returns FALSE and ends the loop. In a single-threaded application, ending the message loop is often the first step in closing the application. An application can end its own loop by using the PostQuitMessage function, typically in response to the WM_DESTROY message in the window procedure of the application's main window.

If you specify a window handle in GetMessage, only messages for the specified window are retrieved from the queue. GetMessage can also filter messages in the queue, retrieving only those messages that fall within a specified range. For more information about filtering messages, see Message Filtering.

A thread's message loop must include TranslateMessage if the thread is to receive character input from the keyboard. Windows generates virtual-key messages (WM_KEYDOWN and WM_KEYUP) each time the user presses a key. A virtual-key message contains a virtual-key code that identifies which key was pressed, but not its character value. To retrieve this value, the message loop must contain TranslateMessage, which translates the virtual-key message into a character message (WM_CHAR) and places it back into the application message queue. The character message can then be removed on a subsequent iteration of the message loop and dispatched to a window procedure.

The DispatchMessage function sends a message to the window procedure associated with the window handle specified in the MSG structure. If the window handle is HWND_TOPMOST, DispatchMessage sends the message to the window procedures of all top-level windows in the system. If the window handle is NULL, DispatchMessage does nothing with the message.

An application's main thread starts its message loop after initializing the application and creating at least one window. Once started, the message loop continues to retrieve messages from the thread's message queue and to dispatch them to the appropriate windows. The message loop ends when the GetMessage function removes the WM_QUIT message from the message queue.

Only one message loop is needed for a message queue, even if an application contains many windows. Because each message in the queue is an MSG structure that contains the handle of the window to which the message belongs, DispatchMessage always dispatches the message to the proper window.

An application can modify its message loop in a variety of ways. For example, it can retrieve messages from the queue without dispatching them to a window. This is useful for applications that post messages not specifying a window. (These messages apply to the application rather than to a specific window, because they have NULL window handles.) An application can also direct GetMessage to search for specific messages, leaving other messages in the queue. This is useful for applications that must temporarily bypass the usual first-in, first-out order of the message queue.

An application that uses accelerator keys must be able to translate keyboard messages into command messages. To do this, the application's message loop must include a call to the TranslateAccelerator function. For more information about accelerator keys, see Keyboard Accelerators.

Window Procedure

A window procedure is a function that receives and processes all messages sent to the window. Every window class has a window procedure, and every window created with that class uses that same window procedure to respond to messages.

The system sends a message to a window procedure by passing the message data as arguments to the procedure. The window procedure then carries out an appropriate action for the message; it checks the message identifier and, while processing the message, uses the information specified by the message parameters.

A window procedure does not usually ignore a message. If it does not process a message, it must send the message back to the system for default processing. The window procedure does this by calling the DefWindowProc function, which carries out a default action and returns a message result. The window procedure must then return this value as its own message result. Most window procedures process just a few types of messages and pass the others on to the system by calling DefWindowProc.

Because a window procedure is shared by all windows belonging to the same class, it can process messages for several different windows. To identify the specific window affected by the message, a window procedure can examine the window handle passed with a message. For more information about window procedures, see Window Procedures.


Posting and Sending Messages

Any application can post and send messages. Like the system, an application posts a message by copying it to a message queue and sends a message by passing the message data as arguments to a window procedure. To post and send messages, an application uses the PostMessage and SendMessage functions.

An application typically posts a message to notify a specific window to carry out a task. PostMessage creates an MSG structure for the message and copies the message to the message queue. The application's message loop eventually retrieves the message and dispatches it to the appropriate window procedure.

An application typically sends a message to notify a window procedure to carry out a task immediately. The SendMessage function sends the message to the window procedure corresponding to the given window. The function waits until the window procedure completes processing and then returns the message result. Parent and child windows often communicate by sending messages to each other. For example, a parent window that has an edit control as its child window can set the text of the control by sending a message to it. The control can notify the parent window of changes to the text that are carried out by the user by sending messages back to the parent.

Occasionally, an application may be required to send or post a message to all top-level windows in the system. For example, if the application changes the system time, it must notify all top-level windows about the change by sending a WM_TIMECHANGE message. An application can send or post a message to all top-level windows by calling the SendMessage or PostMessage function and specifying HWND_TOPMOST in the hwnd parameter.

An application can post a message without specifying a window. If the application supplies a NULL window handle when calling PostMessage, the message is posted to the queue associated with the current thread. Because no window handle is specified, the application must process the message in the message loop. This is one way to create a message that applies to the entire application instead of to a specific window.

By using the InSendMessage function, a window procedure can determine whether it is processing a message sent by another thread. This capability is useful when message processing depends on the origin of the message.

A common programming error is to assume that the PostMessage function always posts a message. This is not true when the message queue is full. An application should check the return value of the PostMessage function to determine whether the message has been posted and, if it has not been, repost it.


Message Types

This section describes the two types of Windows messages: system defined and application defined.

System-Defined Messages

The system uses system-defined messages to control the operations of applications and to provide input and other information for applications to process. The system sends or posts a system-defined message when it communicates with an application. An application can also send or post system-defined messages. Applications usually use these messages to control the operation of control windows created by using preregistered window classes.

Each system message has a unique message identifier and a corresponding symbolic constant (defined in the Windows header files) that states the purpose of the message. For example, the WM_PAINT constant requests that a window paint its contents.

Symbolic constants specify the category to which system-defined messages belong. The prefix of the constant identifies the type of window that can interpret and process the message. Following are the prefixes and their related message categories.

Prefix	Message category

BM	Button control

CB	Combo box control

DM	Default push button control

EM	Edit control

LB	List box control

SBM	Scroll bar control

WM	General window

General window messages cover a wide range of information and requests, including messages for mouse and keyboard input, menu and dialog box input, window creation and management, and dynamic data exchange (DDE).

Application-Defined Messages

An application can create messages to use in its own windows or to communicate with windows in other processes. If an application creates its own messages, the window procedure that receives them must interpret the messages and provide appropriate processing.

Windows reserves message-identifier values in the range 0x0000 through 0x03FF (the value of WM_USER - 1) and 0x8000 through 0xBFFF for system-defined messages. Applications cannot use these values for private messages.

Values in the range 0x0400 (the value of WM_USER) through 0x7FFF are available for message identifiers defined by an application for its own use. Values in the range 0xC000 through 0xFFFF are available for message identifiers defined by an application for use in communicating with windows in other applications.

Windows returns a message identifier in the range 0xC000 through 0xFFFF when an application calls the RegisterWindowMessage function to register a message. The message identifier returned by this function is guaranteed to be unique throughout the system. If your application creates messages to communicate with windows in other applications, it should use RegisterWindowMessage to register the message. Use of this function prevents conflicts that can arise if other applications use the same message identifier for different purposes.


Message Filtering

An application can choose specific messages to retrieve from the message queue (while ignoring other messages) by using the GetMessage or PeekMessage function to specify a message filter. This is a range of message identifiers (specified by a first and last identifier), a window handle, or both. GetMessage and PeekMessage use a message filter to select which messages to retrieve from the queue. Message filtering is useful if an application must search the message queue for messages that have arrived later in the queue.

Any application that filters messages must ensure that a message satisfying the message filter can be posted. For example, if an application filters for a WM_CHAR message in a window that does not receive keyboard input, the GetMessage function does not return. This effectively "hangs" the application.

To filter for keyboard, mouse, and DDE messages, an application can use the WM_KEYFIRST and WM_KEYLAST, WM_MOUSEFIRST and WM_MOUSELAST, and WM_DDE_FIRST and WM_DDE_LAST constants.


Message Deadlocks

A thread that calls the SendMessage function to send a message to another thread cannot continue executing until the window procedure that receives the message returns. If the receiving thread yields control while processing the message, the sending thread cannot continue executing, because it is waiting for SendMessage to return. This situation is called a deadlock. The receiving thread need not yield explicitly; calling any of the following functions can cause a thread to yield control.

DialogBox

DialogBoxIndirect

DialogBoxIndirectParam

DialogBoxParam

GetMessage

MessageBox

PeekMessage

A window procedure can determine whether a message it has received was sent by another thread by calling the InSendMessage function. Before calling any of the functions in the preceding list while processing a message, the window procedure should first call InSendMessage. If this function returns TRUE, the window procedure must call the ReplyMessage function before any function that causes the thread to yield control.


Creating a Message Loop

Windows automatically creates a message queue for each thread. If the thread creates one or more windows, a message loop that retrieves messages from the thread's message queue and dispatches them to the appropriate window procedures must be provided.

Because Windows directs messages to individual windows in an application, a thread must create at least one window before starting its message loop. Most Windows-based applications contain a single thread that creates windows. A typical application registers the window class for its main window, creates and shows the main window, and then starts its message loop--all in the WinMain function.

You create a message loop by using the GetMessage and DispatchMessage functions. If your application must obtain character input from the user, include the TranslateMessage function in the loop. TranslateMessage translates virtual-key messages into character messages. The following example shows the message loop in the WinMain function of a simple Windows-based application.

HINSTANCE hinst;

HWND hwndMain;

int APIENTRY WinMain(hInstance, hPrevInstance, lpszCmdLine,

    nCmdShow)

HINSTANCE hInstance;

HINSTANCE hPrevInstance;

LPSTR lpszCmdLine;

int nCmdShow;

{

    MSG msg;

    WNDCLASS wc;

    UNREFERENCED_PARAMETER(lpszCmdLine);

    /* Register the window class for the main window. */

    if (!hPrevInstance) {

        wc.style = 0;

        wc.lpfnWndProc = (WNDPROC) WndProc;

        wc.cbClsExtra = 0;

        wc.cbWndExtra = 0;

        wc.hInstance = hInstance;

        wc.hIcon = LoadIcon((HINSTANCE) NULL, IDI_APPLICATION);

        wc.hCursor = LoadCursor((HINSTANCE) NULL, IDC_ARROW);

        wc.hbrBackground = GetStockObject(WHITE_BRUSH);

        wc.lpszMenuName =  "MainMenu";

        wc.lpszClassName = "MainWndClass";

        if (!RegisterClass(&wc))

            return FALSE;

    }

    hinst = hInstance;  /* saves handle of application instance */

    /* Create the main window. */

    hwndMain = CreateWindow("MainWndClass", "Sample",

        WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT,

        CW_USEDEFAULT, CW_USEDEFAULT, (HWND) NULL,

        (HMENU) NULL, hinst, (LPVOID) NULL);

    /*

     * If the main window cannot be created, terminate

     * the application.

     */

    if (!hwndMain)

        return FALSE;

    /* Show the window and paint its contents. */

    ShowWindow(hwndMain, nCmdShow);

    UpdateWindow(hwndMain);

    /* Start the message loop. */

    while (GetMessage(&msg, (HWND) NULL, 0, 0)) {

        TranslateMessage(&msg);

        DispatchMessage(&msg);

    }

    /* Return the exit code to Windows. */

    return msg.wParam;

}

z The GetMessage, TranslateMessage, and DispatchMessage functions take a pointer to an MSG structure as a parameter. If a message is available, GetMessage copies it to the MSG structure. If the message is a virtual-key message (such as WM_KEYDOWN or WM_SYSKEYDOWN), TranslateMessage generates a character message (WM_CHAR or WM_SYSCHAR) and places it in the message queue. DispatchMessage uses the members of the MSG structure as arguments for the window procedure but does not return until the window procedure finishes processing the message.

If a thread supports accelerators, its message loop must include the TranslateAccelerator function. This function checks for key combinations that match an entry in the thread's accelerator table. When it finds a match, TranslateAccelerator translates the key combination into a WM_COMMAND message and dispatches it to the window procedure. For more information about accelerators, see Keyboard Accelerators.

If a thread uses a modeless dialog box, the message loop must include the IsDialogMessage function so that the dialog box can receive keyboard input. For more information about dialog boxes, see Dialog Boxes.

The following example shows a message loop for a thread that uses accelerators and displays a modeless dialog box. When TranslateAccelerator or IsDialogMessage returns TRUE (indicating that the message has been processed), TranslateMessage and DispatchMessage are not called. The reason for this is that TranslateAccelerator and IsDialogMessage perform all necessary translating and dispatching of messages.

HWND hwndMain;

HWND hwndDlgModeless = NULL;

MSG msg;

HACCEL haccel;

.

. /* Perform initialization and create a main window. */

.

while (GetMessage(&msg, (HWND) NULL, 0, 0)) {

    if (hwndDlgModeless == (HWND) NULL ||

            !IsDialogMessage(hwndDlgModeless, &msg) &&

            !TranslateAccelerator(hwndMain, haccel, &msg)) {

        TranslateMessage(&msg);

        DispatchMessage(&msg);

    }

}


Examining a Message Queue

Occasionally, an application needs to examine the contents of a thread's message queue from outside the thread's message loop. For example, if an application's window procedure performs a lengthy drawing operation, you may want the user to be able to interrupt the operation. Unless your application periodically examines the message queue during the operation for mouse and keyboard messages, it will not respond to user input until after the operation has completed. The reason for this is that the DispatchMessage function in the thread's message loop does not return until the window procedure finishes processing a message.

You can use the PeekMessage function to examine a message queue during a lengthy operation. PeekMessage is similar to the GetMessage function; both check a message queue for a message that matches the filter criteria and then copy the message to an MSG structure. The main difference between them is that GetMessage does not return until a message matching the filter criteria is placed in the queue, whereas PeekMessage returns immediately regardless of whether a message is in the queue.

The following example shows how to use PeekMessage to examine a message queue for mouse clicks and keyboard input during a lengthy operation.

HWND hwnd;

BOOL fDone;

MSG msg;

/*

 * Begin the operation and continue until it is complete

 * or until the user clicks the mouse or presses a key.

 */

fDone = FALSE;

while (!fDone) {

    fDone = DoLengthyOperation(); /* application-defined */

    /*

     * Remove any messages that may be in the queue. If the

     * queue contains any mouse or keyboard

     * messages, end the operation.

     */

    while (PeekMessage(&msg, hwnd,  0, 0, PM_REMOVE)) {

        switch(msg.message) {

            case WM_LBUTTONDOWN:

            case WM_RBUTTONDOWN:

            case WM_KEYDOWN:

                .

                . /* Perform any required cleanup. */

                .

                fDone = TRUE;

        }

    }

}

Other functions, including GetQueueStatus and GetInputState, also allow you to examine the contents of a thread's message queue. GetQueueStatus returns an array of flags that indicates the types of messages in the queue; using it is the fastest way to discover whether the queue contains any messages. GetInputState returns TRUE if the queue contains mouse or keyboard messages. Both of these functions can be used to determine whether the queue contains messages that need to be processed.


Posting a Message

You can post a message to a message queue by using the PostMessage function. PostMessage places a message at the end of a thread's message queue and returns immediately, without waiting for the thread to process the message. The function's parameters include a window handle, a message identifier, and two message parameters. Windows copies these parameters to an MSG structure, fills the time and pt members of the structure, and places the structure in the message queue.

Windows uses the window handle passed with the PostMessage function to determine which thread message queue should receive the message. If the handle is HWND_TOPMOST, Windows posts the message to the thread message queues of all top-level windows.

You can use the PostThreadMessage function to post a message to a specific thread message queue. PostThreadMessage is similar to PostMessage, except the first parameter is a thread identifier rather than a window handle. You can retrieve the thread identifier by calling the GetCurrentThreadId function.

Use the PostQuitMessage function to exit a message loop. PostQuitMessage posts the WM_QUIT message to the currently executing thread. The thread's message loop terminates and returns control to Windows when it encounters the WM_QUIT message. An application usually calls PostQuitMessage in response to the WM_DESTROY message, as shown in the following example.

case WM_DESTROY:

    .

    . /* Perform cleanup tasks. */

    .

    PostQuitMessage(0);

    break;


Sending a Message

The SendMessage function is used to send a message directly to a window procedure. SendMessage calls a window procedure and waits for that procedure to process the message and return a result.

A message can be sent to any window in the system; all that is required is a window handle. Windows uses the handle to determine which window procedure should receive the message.

If a window procedure yields control when processing a message sent by another thread, a message deadlock may result (For more information about message deadlocks, see Message Deadlocks.) Before processing a message that may have been sent from another thread, a window procedure should first call the InSendMessage function. If this function returns TRUE, the window procedure should call ReplyMessage before any function that causes the thread to yield control, as shown in the following example.

case WM_USER + 5:

    if (InSendMessage())

        ReplyMessage(TRUE);

    DialogBox(hInst, "MyDialogBox", hwndMain, (DLGPROC) MyDlgProc);

    break;

A number of messages can be sent to controls in a dialog box. These control messages set the appearance, behavior, and content of controls or retrieve information about controls. For example, the CB_ADDSTRING message can add a string to a combo box, and the BM_SETCHECK message can set the check state of a check box or radio button.

Use the SendDlgItemMessage function to send a message to a control, specifying the identifier of the control and the handle of the dialog box window that contains the control. The following example, taken from a dialog box procedure, copies a string from a combo box's edit control into its list box. The example uses SendDlgItemMessage to send a CB_ADDSTRING message to the combo box.

HWND hwndCombo;

int cTxtLen;

PSTR pszMem;

switch (uMsg) {

    case WM_COMMAND:

        switch (LOWORD(wParam)) {

            case IDD_ADDCBITEM:

                /*

                 * Get the handle of the combo box and the

                 * length of the string in the edit control of

                 * the combo box.

                 */

                hwndCombo = GetDlgItem(hwndDlg, IDD_COMBO);

                cTxtLen = GetWindowTextLength(hwndCombo);

                /*

                 * Allocate memory for the string and copy

                 * the string into the memory.

                 */

                pszMem = (PSTR) VirtualAlloc((LPVOID) NULL,

                    (DWORD) (cTxtLen + 1), MEM_COMMIT,

                    PAGE_READWRITE);

                GetWindowText(hwndCombo, pszMem, cTxtLen + 1);

                /*

                 * Add the string to the list box of the

                 * combo box and remove the string from the

                 * edit control of the combo box.

                 */

                if (*pszMem != NULL) {

                    SendDlgItemMessage(hwndDlg, IDD_COMBO,

                        CB_ADDSTRING, 0,

                        (DWORD) ((LPSTR) pszMem));

                    SetWindowText(hwndCombo, (LPSTR) NULL);

                }

                /* Free the memory and return. */

                VirtualFree(pszMem, 0, MEM_RELEASE);

                return TRUE;

            .

            . /* Process other dialog box commands. */

            .

        }

    .

    . /* Process other dialog box messages. */

    .

}


Functions

Following are the functions used with messages and message queues.

CallWndProc

DefWindowProc

DispatchMessage

GetInputState

GetMessage

GetMessageExtraInfo

GetMessagePos

GetMessageTime

GetMsgProc

GetQueueStatus

InSendMessage

IsDialogMessage

IsWindowUnicode

PeekMessage

PostMessage

PostQuitMessage

PostThreadMessage

RegisterWindowMessage

ReplyMessage

SendDlgItemMessage

SendMessage

SendNotifyMessage

TranslateAccelerator

TranslateMessage

WaitMessage


Window Classes Overview

About Window Classes

Every window is a member of a window class. A window class is a set of attributes that Microsoft® Windows™ uses as a template to create a window in an application. Each window class has an associated window procedure shared by all windows of the same class. The window procedure processes messages for all windows of that class and therefore controls their behavior and appearance. For more information about window procedures, see Window Procedures.

An application must register a window class before it can create a window of that class. Registering a window class associates a window procedure, class styles, and other class attributes with a class name. When an application specifies a class name in the CreateWindow or CreateWindowEx function, the operating system creates a window with the window procedure, styles, and other attributes associated with that class name.

The following topics discuss window classes:

Types of Window Classes

How Windows Locates a Class

Class Ownership

Elements of a Window Class

Class and Private Device Contexts

Using Window Classes

Functions


Types of Window Classes

There are three types of window classes: system global, application global, and application local. These types differ in scope and in when and how they are registered and destroyed.

System Global Classes

When Windows starts, it registers a set of system global classes for controls, including buttons, combo boxes, list boxes, scroll bars, edit controls, and static controls. For more information about controls, see Controls, through Static Controls.

Any application can use a system global class at any time. Because Windows registers system global classes on behalf of all applications, an application cannot destroy any of these classes.

Application Global Classes

An application global class is a window class registered by a dynamic-link library (DLL) and available to all applications in the system. For example, you can register a window class that defines a custom control as an application global class so that all applications can create instances of the custom control.

In Windows, all window classes are process specific. An application can create a global class by creating the window class in a DLL and listing the name of the DLL in the registration database under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\

    CurrentVersion\Windows\APPINIT_DLLS

Whenever a process starts, the system loads the specified DLL 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. For more information about class styles, see Class Styles. After a class has been registered, any application can use it to create any number of windows belonging to that class.

Windows destroys an application global class when the DLL that registered it is unloaded. For this reason, all applications must destroy all windows that belong to an application global class before unloading that DLL. Use the UnregisterClass function to remove an application global class and free the storage associated with it.

Application Local Classes

An application local class is any window class that an application registers for its exclusive use. Although an application can register any number of local classes, most applications register only one. This window class supports the window procedure of the application's main window.

Registering a local class is similar to registering an application global class, except that the CS_GLOBALCLASS style is not specified in the style member of the WNDCLASS structure.

Windows destroys a local class when the application that registered it closes. An application can also use the UnregisterClass function to remove a local class and free the storage associated with it.


How Windows Locates a Class

Windows maintains a list of WNDCLASS structures for each of the three types of window classes. When an application calls the CreateWindow or CreateWindowEx function to create a window with a specified class, Windows uses the following procedure to locate the class:

1	Windows searches the list of application local classes for a class with the specified name.

2	If the name is not in the application local class list, Windows searches the list of application global classes.

3	If the name is not in the application global class list, Windows searches the list of system global classes.

All windows created by the application use this procedure, including windows created by Windows on the application's behalf, such as dialog boxes. It is possible to override system global classes without affecting other applications. That is, an application can register an application local class having the same name as a system global class. This replaces the system global class in the context of the application but does not prevent other applications from using the system global class.


Class Ownership

The owner of a class is the application or DLL that registered the class. Windows determines class ownership from the hInstance member of the WNDCLASS structure passed to the RegisterClass function when the class is registered. For Windows DLLs, the hInstance member must be the instance handle of the DLL. The class is destroyed when the owner closes or is unloaded. For this reason, the application must destroy all windows using the class before it closes or the DLL is unloaded.


Elements of a Window Class

The elements of a window class define the default behavior of windows belonging to the class. The application that registers a window class assigns elements to the class by setting appropriate members in a WNDCLASS structure and passing the structure to the RegisterClass function. The GetClassInfo and GetClassLong functions retrieve information about a given window class. The SetClassLong function changes elements of a local or global class that the application has already registered.

Although a complete window class consists of many elements, Windows requires only that an application supply a class name, the window-procedure address, and an instance handle. Use the other elements to define default attributes for windows of the class, such as the shape of the cursor and the content of the menu for the window. The window class elements are as follows.

Element	Purpose

Class name	Distinguishes the class from other registered classes.

Window-procedure address	Points to the function that processes all messages sent to windows in the class and defines the behavior of the window.

Instance handle	Identifies the application or DLL that registered the class.

Class cursor	Defines the shape of the cursor in a window of the class.

Class icon	Defines the shape of the icon when a window belonging to the class is minimized.

Class background brush	Defines the color and pattern that fill the client area when the window is opened or painted.

Class menu	Specifies the default menu for windows that do not explicitly define a menu.

Class styles	Defines how to update the window after moving or resizing it, how to process double-clicks of the mouse, how to allocate space for the device context, and other aspects of the window.

Extra class memory	Specifies the amount of extra memory, in bytes, that Windows should reserve for the class. All windows in the class share the extra memory and can use it for any application-defined purpose. Windows initializes this memory to zero.

Extra window memory	Specifies the amount of extra memory, in bytes, that Windows should reserve for each window belonging to the class. The extra memory can be used for any application-defined purpose. Windows initializes this memory to zero.

Class Name

Every window class needs a class name to distinguish one class from another. Assign a class name by setting the lpszClassName member of the WNDCLASS structure to the address of a null-terminated string that specifies the name. Because window classes are process specific in Windows, window class names need to be unique only within the same process.

The GetClassName function retrieves the name of the class to which a given window belongs.

Window-Procedure Address

Every class needs a window-procedure address to define the entry point of the window procedure used to process all messages for windows in the class. Windows passes messages to the procedure when it requires the window to carry out tasks, such as painting its client area or responding to input from the user. An application assigns a window procedure to a class by copying its address to the lpfnWndProc member of the WNDCLASS structure. For more information about window procedures, see Window Procedures

Instance Handle

Every window class requires an instance handle to identify the application or DLL that registered the class. As a multitasking system, Windows lets several applications or DLLs run at the same time, so it requires instance handles to keep track of all of them. Windows assigns a handle to each copy of a running application or DLL.

Multiple instances of the same application or DLL all use the same code segment, but each has its own data segment. Windows uses an instance handle to identify the data segment that corresponds to a particular instance of an application or DLL.

Windows passes an instance handle to an application or DLL when the application starts. The application or DLL assigns this instance handle to the class by copying it to the hInstance member of the WNDCLASS structure.

Class Cursor

The class cursor defines the shape of the cursor when it is in the client area of a window in the class. Windows automatically sets the cursor to the given shape when the cursor enters the window's client area and ensures it keeps that shape while it remains in the client area. To assign a cursor shape to a window class, load a predefined cursor shape by using the LoadCursor function and then assign the returned cursor handle to the hCursor member of the WNDCLASS structure. Alternatively, provide a custom cursor resource and use the LoadCursor function to load it from the application's resources.

Windows does not require a class cursor. If an application sets the hCursor member of the WNDCLASS structure to NULL, a class cursor is not defined. Windows assumes the window sets the cursor shape each time the cursor moves into the window. A window can set the cursor shape by calling the SetCursor function whenever the window receives the WM_MOUSEMOVE message. For more information about cursors, see Cursors

Class Icon

The class icon defines the shape of the icon used when the window of the given class is minimized. To assign an icon to a window class, load the icon from the application's resources by using the LoadIcon function and then assign the returned icon handle to the hIcon member of the WNDCLASS structure. For more information about icons, see Icons.

Windows does not require that a window class have a class icon. If an application sets the hIcon member of the WNDCLASS structure to NULL, a class icon is not defined. In this case, Windows sends the WM_ICONERASEBKGND message to a window of the class whenever it must paint the background of the icon. If the window does not process the WM_ICONERASEBKGND message, Windows draws an image of the contents of the window's client area onto the icon when it is minimized.

Class Background Brush

A class background brush prepares the client area of a window for subsequent drawing by the application. Windows uses the brush to fill the client area with a solid color or pattern, thereby removing all previous images from that location whether they belonged to the window or not. Windows notifies a window that its background should be painted by sending the WM_ERASEBKGND message to the window. For more information about brushes, see Brushes.

To assign a background brush to a class, create a brush by using the appropriate functions from the graphics device interface (GDI) and assign the returned brush handle to the hbrBackground member of the WNDCLASS structure.

Instead of creating a brush, an application can set the hbrBackground member to one of the standard system color values.

To use a standard system color, the application must increase the background-color value by one. For example, COLOR_BACKGROUND + 1 is the system background color.

Windows does not require that a window class have a class background brush. If this parameter is set to NULL, the window must paint its own background whenever it receives the WM_ERASEBKGND message.

Class Menu

A class menu defines the default menu to be used by the windows in the class if no explicit menu is given when the windows are created. A menu is a list of commands from which a user can choose actions for the application to carry out.

To assign a menu to a class, set the lpszMenuName member of the WNDCLASS structure to the address of a null-terminated string that specifies the resource name of the menu. The menu is assumed to be a resource in the given application. Windows automatically loads the menu when it is needed. Note that if the menu resource is identified by an integer and not by a name, the application can set the lpszMenuName member to that integer by applying the MAKEINTRESOURCE macro before assigning the value.

Windows does not require a class menu. If an application sets the lpszMenuName member of the WNDCLASS structure to NULL, Windows assumes the windows in the class have no menu bars. Even if no class menu is given, an application can still define a menu bar for a window when it creates the window.

Windows does not allow menu bars with child windows. If a menu is given for a class and a child window of that class is created, the menu is ignored. For more information about menus, see Menus.

Class Styles

The class styles define additional elements of the window class. Two or more styles can be combined by using the bitwise OR (|) operator. To assign a style to a window class, assign the style to the style member of the WNDCLASS structure. The class styles are as follows.

Style	Action

CS_BYTEALIGNCLIENT	Aligns the window's client area on a byte boundary (in the x direction) to enhance performance during drawing operations. This style affects the width of the window and its horizontal placement on the display.

CS_BYTEALIGNWINDOW	Aligns the 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 placement on the display.

CS_CLASSDC	Allocates one device context to be shared by all windows in the class. For more information about device contexts, see Class and Private Device Contexts, and Device Contexts.

CS_DBLCLKS	Instructs Windows to send a double-click message to the window procedure when the user double-clicks the mouse while the cursor is within a window belonging to the class. For more information about double-clicks, see Mouse Input.

CS_GLOBALCLASS	Specifies that the window class is an application global class. For more information, see Application Global Classes.

CS_HREDRAW	Specifies that the entire window is to be redrawn 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	Gives the parent window's device context to the child windows. For more information about device contexts, see Class and Private Device Contexts, and Device Contexts.

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 other screen actions have not invalidated the stored image. Use this style for small windows that are displayed briefly and then removed before other screen activity takes place (for example, menus or dialog boxes). This style increases the time required to display the window, because the operating system must first allocate memory to store the bitmap.

CS_VREDRAW	Specifies that the entire window is to be redrawn if a movement or size adjustment changes the height of the client area.

Extra Class Memory

Windows maintains a WNDCLASS structure internally for each window class in the system. When an application registers a window class, it can direct Windows to allocate and append a number of additional bytes of memory to the end of the WNDCLASS structure. This memory is called extra class memory and is shared by all windows belonging to the class. Use the extra class memory to store any information pertaining to the class.

The SetClassWord and SetClassLong functions copy a value to the extra class memory. To retrieve a value from the extra class memory, use the GetClassWord and GetClassLong functions. The cbClsExtra member of the WNDCLASS structure specifies the amount of extra class memory to allocate. An application that doesn't use extra class memory must initialize the cbClsExtra member to zero.

Extra Window Memory

Windows maintains an internal data structure for each window. When registering a window class, an application can specify a number of additional bytes of memory, called extra window memory. When creating a window of the class, Windows allocates and appends the specified amount of extra window memory to the end of the window's structure. An application can use this memory to store window-specific data.

The SetWindowWord and SetWindowLong functions copy a value to the extra memory. The GetWindowWord and GetWindowLong functions retrieve a value from the extra window memory. The cbWndExtra member of the WNDCLASS structure specifies the amount of extra window memory to allocate. An application that doesn't use extra window memory must initialize the cbWndExtra member to zero.


Class and Private Device Contexts

A device context is a special set of values that applications use for drawing in the client area of their windows. Windows requires a device context for each window on the display but allows some flexibility in how the operating system stores and treats that device context.

If no device-context style is explicitly given, Windows assumes each window uses a device context retrieved from a pool of contexts maintained by Windows. In such cases, each window must retrieve and initialize the device context before painting and free it after painting.

To avoid retrieving a device context each time it needs to paint inside a window, an application can specify the CS_OWNDC style for the window class. This class style directs Windows to create a private device context--that is, to allocate a unique device context for each window in the class. The application need retrieve the context only once and then use it for all subsequent painting. Although the CS_OWNDC style is convenient, use it carefully, because each device context uses a significant portion of system resources.

By specifying the CS_CLASSDC style, an application can create a class device context. A class device context is a rarely used feature that allows multiple windows created from the same window class within a process to use exactly the same device context for drawing.

An application can specify the CS_PARENTDC style to create child windows that inherit the device context of their parent window. This style allows a child window to draw in the client area of its parent.

For more information about device contexts, see Device Contexts. For more information about painting, see Painting and Drawing.


Using Window Classes

In Windows, each application must register its own window classes. Your application can register an application local class at any time by using the RegisterClass function. You must define the window procedure in the application, fill the members of the WNDCLASS structure, and then pass a pointer to the structure to the RegisterClass function.

The following example shows how to register a local window class and use it to create your application's main window.

#include <windows.h>

/* Global variable */

HINSTANCE hinst;

/* Function prototypes */

int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int);

InitApplication(HINSTANCE);

InitInstance(HINSTANCE, int);

LRESULT CALLBACK MainWndProc(HWND, UINT, WPARAM, LPARAM);

/* Application entry point */

int WINAPI WinMain(hinstance, hPrevInstance, lpCmdLine, nCmdShow)

HINSTANCE hinstance;

HINSTANCE hPrevInstance;

LPSTR lpCmdLine;

int nCmdShow;

{

    MSG msg;

    if (!InitApplication(hinstance))

        return FALSE;

    if (!InitInstance(hinstance, nCmdShow))

        return FALSE;

    while (GetMessage(&msg, (HWND) NULL, 0, 0)) {

        TranslateMessage(&msg);

        DispatchMessage(&msg);

    }

    return msg.wParam;

        UNREFERENCED_PARAMETER(lpCmdLine);

}

BOOL InitApplication(hinstance)

HINSTANCE hinstance;

{

    WNDCLASS wc;

    /*

     * Fill in the window class structure with parameters

     * that describe the main window.

     */

    wc.style = CS_HREDRAW |

        CS_VREDRAW;                    /* redraw if size changes */

    wc.lpfnWndProc = MainWndProc;      /* points to window proc. */

    wc.cbClsExtra = 0;                 /* no extra class memory  */

    wc.cbWndExtra = 0;                 /* no extra window memory */

    wc.hInstance = hinstance;          /* handle of instance     */

    wc.hIcon = LoadIcon(NULL,

        IDI_APPLICATION);              /* predefined app. icon   */

    wc.hCursor = LoadCursor(NULL,

        IDC_ARROW);                    /* predefined arrow       */

    wc.hbrBackground = GetStockObject(

        WHITE_BRUSH);                  /* white background brush */

    wc.lpszMenuName =  "MainMenu";     /* name of menu resource  */

    wc.lpszClassName = "MainWClass";   /* name of window class   */

    /* Register the window class. */

    return RegisterClass(&wc);

}

BOOL InitInstance(hinstance, nCmdShow)

HINSTANCE hinstance;

int nCmdShow;

{

    HWND hwnd;

    /* Save the application-instance handle. */

    hinst = hinstance;

    /* Create the main window. */

    hwnd = CreateWindow(

        "MainWClass",        /* name of window class        */

        "Sample",            /* title-bar string            */

        WS_OVERLAPPEDWINDOW, /* top-level window            */

        CW_USEDEFAULT,       /* default horizontal position */

        CW_USEDEFAULT,       /* default vertical position   */

        CW_USEDEFAULT,       /* default width               */

        CW_USEDEFAULT,       /* default height              */

        (HWND) NULL,         /* no owner window             */

        (HMENU) NULL,        /* use class menu              */

        hinstance,           /* handle of app. instance     */

        (LPVOID) NULL);      /* no window-creation data     */

    if (!hwnd)

        return FALSE;

     /*

      * Show the window and send a WM_PAINT message to the window

      * procedure.

      */

    ShowWindow(hwnd, nCmdShow);

    UpdateWindow(hwnd);

    return TRUE;

}

Registering an application global class is similar to registering an application local class, with the following exceptions:

The style parameter of the WNDCLASS structure must specify the CS_GLOBALCLASS style.

The class can be registered in the context of either an application or a DLL.

The application or DLL need not check for a previous instance of the application or DLL before registering the class.


Functions

Following are the functions used with window classes.

GetClassInfo

GetClassLong

GetClassName

GetClassWord

GetWindowLong

GetWindowWord

RegisterClass

SetClassLong

SetClassWord

SetWindowLong

SetWindowWord

UnregisterClass


Window Procedures Overview

About Window Procedures

In Microsoft® Windows™, every window has an associated window procedure--a function that processes all messages sent or posted to all windows of the class. All aspects of a window's appearance and behavior depend on the window procedure's response to these messages.

Each window is a member of a particular window class. The window class determines the window procedure that an individual window uses to process its messages. All windows belonging to the same class use the same window procedure. For example, the system defines a window procedure for the combo box class (COMBOBOX), and all combo boxes use that window procedure.

An application typically registers at least one new window class and an associated window procedure. After registering a class, the application can create many windows of that class, all of which use the same window procedure. Because this means several sources could simultaneously call the same piece of code, the developer must be careful when modifying shared resources from a window procedure.

Dialog box procedures have the same structure and function as window procedures. All points referring to window procedures in this section also apply to dialog box procedures.

The following topics discuss Win32 window procedures:

Terms

Structure of a Window Procedure

Default Window Procedure

Window-Procedure Subclassing

Window-Procedure Superclassing

Designing a Window Procedure

Associating a Window Procedure With a Window Class

Subclassing a Window

Functions


Structure of a Window Procedure

A window procedure is a function that has four parameters and returns a 32-bit signed value. The parameters consist of a window handle, a UINT message identifier, and two message parameters declared with the WPARAM and LPARAM data types. The operating system defines a WPARAM value as a 32-bit unsigned integer and an LPARAM value as a 32-bit signed integer.

The window procedure parameters are described in the following table.

Parameter	Description

hwnd	Handle of the window receiving the message.

uMsg	Message identifier. The identifier corresponds to one of the predefined constants (for example, WM_CREATE) defined in the system header files or to an application-defined message identifier.

wParam, lParam	Message parameters. Their interpretation depends on the value of the uMsg parameter.

Message parameters often contain information in both their low-order and high-order words. The Win32 application programming interface (API) includes several macros an application can use to extract information from the message parameters. The LOWORD macro, for example, extracts the low-order word (bits 0 through 15) from a message parameter. Other macros include HIWORD, LOBYTE, and HIBYTE.

The return value of a window procedure is declared as an LRESULT data type, which is defined as a 32-bit signed value. The interpretation of the return value depends on the particular message. Consult the description of each message to determine the appropriate return value.

Because it is possible to call a window procedure recursively, it is important to minimize the number of local variables that it uses. When processing individual messages, an application should call functions outside the window procedure to avoid excessive use of local variables, possibly causing the stack to overflow during deep recursion.


Default Window Procedure

The default window procedure function DefWindowProc defines certain fundamental behavior shared by all windows. The default window procedure provides the minimal functionality for a window. An application-defined window procedure should pass any messages that it does not process to the DefWindowProc function for default processing.


Window Procedure Subclassing

When an application creates a window, the operating system allocates a block of memory for storing information specific to the window, including the address of the window procedure that processes messages for the window. When Windows needs to pass a message to the window, it searches the window-specific information for the address of the window procedure and passes the message to that procedure.

Subclassing is 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. By subclassing a window, an application can augment, modify, or monitor the behavior of the window. An application can subclass any window, including those belonging to a system global class, such as an edit control or a list box. For example, an application could subclass an edit control to prevent the control from accepting certain characters.

An application subclasses a window by replacing the address of the window's original window procedure with the address of a new window procedure, called the subclass procedure. Thereafter, the subclass procedure receives any messages sent or posted to the window.

The subclass procedure can take three actions when it receives a message: it can pass the message to the original window procedure, modify the message and pass it to the original window procedure, or process the message and not pass it to the original window procedure. If the subclass procedure processes a message, it can do so before, after, or both before and after it passes the message to the original window procedure.

Windows provides two types of subclassing: instance and global. In instance subclassing, an application replaces the window procedure address of a single instance of a window. An application must use instance subclassing to subclass an existing window. In global subclassing, an application replaces the address of the window procedure in the WNDCLASS structure of a window class. All subsequent windows created with the class have the address of the subclass procedure, but existing windows of the class are not affected.

Instance Subclassing

An application subclasses an instance of a window by using the SetWindowLong function. The application passes the GWL_WNDPROC flag, the handle of the window to subclass, and the address of the subclass procedure to SetWindowLong. The subclass procedure can reside in either the application's module or a dynamic-link library (DLL). An application must list the name of the subclass procedure in the EXPORTS statement of the application's or DLL's module-definition (.DEF) file.

SetWindowLong returns the address of the window's original window procedure. The application must save the address, using it in subsequent calls to the CallWindowProc function, to pass intercepted messages to the original window procedure. The application also needs the original window procedure address to remove the subclass from the window. To do so, the application calls SetWindowLong again, passing the address of the original window procedure with the GWL_WNDPROC flag and the handle of the window.

An application can subclass any window in the system; however, when subclassing a window it does not own, the application must ensure the subclass procedure does not destroy the original behavior of the window. Because the application does not control the window, it must not depend on information about the window that the owner might change in the future.

An application should not use the extra window bytes or the class bytes for a window without knowing exactly what the bytes mean and how the original window procedure uses them. Even so, the application should not use them unless it owns the window. If the application uses the extra window bytes of a window that another application owns and the owner changes some aspect of the extra bytes, the subclass procedure may fail. For this reason, an application should not subclass a window that belongs to a system global control class. Windows owns the system global classes, and aspects of the controls might change from one version of Windows to the next. If the application must subclass a window that belongs to a system global class, the developer may need to update the application when a new version of Windows is released.

Because instance subclassing occurs after a window is created, the application subclassing the window cannot add any extra bytes to the window. Applications that subclass a window should use the window's property list to store any data needed for an instance of the subclassed window.

When an application subclasses a subclassed window, it must remove the subclasses in the reverse order they were performed. If the removal order is not reversed, an unrecoverable system error may occur.

Global Subclassing

To globally subclass a window class, the application must have a handle of a window of the class. The application also needs the handle to remove the subclass. To get the handle, an application typically creates a hidden window of the class to be subclassed. After obtaining the handle, the application calls the SetClassLong function, specifying the handle, the GCL_WNDPROC flag, and the address of the subclass procedure. SetClassLong returns the address of the original window procedure for the class.

The original window procedure address is used in global subclassing in the same way it is used in instance subclassing. The subclass procedure passes messages to the original window procedure by calling the CallWindowProc function. The application removes the subclass from the window class by calling SetClassLong again, specifying the address of the original window procedure, the GCL_WNDPROC flag, and the handle of a window of the class being subclassed. An application that globally subclasses a control class must remove the subclass when the application terminates; otherwise, an unrecoverable system error may occur.

Global subclassing has the same limitations as instance subclassing, plus some additional restrictions. An application should not use the extra bytes for either the class or the window instance without knowing exactly how the original window procedure uses them. If the application must associate data with a window, it should use window properties.

An application must not globally subclass a system global class. An unrecoverable system error may occur if more than one application globally subclasses a control class. If the application could benefit from globally subclassing a control class, use the technique called superclassing, described in the following section.


Window Procedure Superclassing

Superclassing is a technique that allows an application to create a new window class with the basic functionality of the existing class, plus enhancements provided by the application. A superclass is based on an existing window class called the base class. Frequently, the base class is a system global window class such as an edit control, but it can be any window class.

Note:	An application must not superclass the system global SCROLLBAR class.

A superclass has its own window procedure, called the superclass procedure. The superclass procedure can take three actions with a message: it can pass the message to the original window procedure, modify the message and pass it to the original window procedure, or process the message and not pass it to the original window procedure. If the superclass procedure processes a message, it can do so before, after, or both before and after it passes the message to the original window procedure.

Unlike a subclass procedure, a superclass procedure can process window creation messages (WM_NCCREATE, WM_CREATE, and so on), but it must also pass them to the original base-class window procedure so that the base-class window procedure can perform its initialization procedure.

To superclass a window class, an application first calls the GetClassInfo function to retrieve information about the base class. GetClassInfo fills a WNDCLASS structure with the values from the WNDCLASS structure of the base class. Next, the application copies its own instance handle into the hInstance member of the WNDCLASS structure and copies the name of the superclass into the lpszClassName member. If the base class has a menu, the application must provide a new menu with the same menu identifiers and copy the menu name into the lpszMenuName member. If the superclass procedure processes the WM_COMMAND message and does not pass it to the window procedure of the base class, the menu does not need to have corresponding identifiers. The GetClassInfo function does not return the lpszMenuName, lpszClassName, or hInstance member of the WNDCLASS structure.

An application must also set the lpfnWndProc member of the WNDCLASS structure. The GetClassInfo function fills this member with the address of the original window procedure for the class. The application must save this address, to pass messages to the original window procedure, and then copy the address of the superclass procedure into the lpfnWndProc member. The application can, if necessary, modify any other members of the WNDCLASS structure. After it fills the WNDCLASS structure, the application registers the superclass by passing the address of the structure to the RegisterClass function. The superclass can then be used to create windows.

Because superclassing registers a new window class, an application can add to both the extra class bytes and the extra window bytes. The superclass must not use the original extra bytes for the base class or the window for the same reasons that an instance subclass or a global subclass should not use them. Also, if the application adds extra bytes for its use to either the class or the window instance, it must reference the extra bytes relative to the number of extra bytes used by the original base class. Because the number of bytes used by the base class may vary from one version of the base class to the next, the starting offset for the superclass's own extra bytes may also vary from one version of the base class to the next.


Designing a Window Procedure

The following example shows the structure of a typical window procedure. The window procedure uses the message argument in a switch statement with individual messages handled by separate case statements. Notice that each case returns a specific value for each message. For messages that it does not process, the window procedure calls the DefWindowProc function.

LRESULT APIENTRY MainWndProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;      /* handle of the window     */

UINT uMsg;      /* message identifier       */

WPARAM wParam;  /* first message parameter  */

LPARAM lParam;  /* second message parameter */

{

    switch (uMsg) {

        case WM_CREATE:

            /* Initialize the window. */

            return 0;

        case WM_PAINT:

            /* Paint the window's client area. */

            return 0;

        case WM_SIZE:

            /* Set the size and position of the window. */

            return 0;

        case WM_DESTROY:

            /* Clean up window-specific data objects. */

            return 0;

        .

        . /* Process other messages. */

        .

        default:

            return DefWindowProc(hwnd, uMsg, wParam, lParam);

    }

    return 0;

}

At the very least, a window procedure should process the WM_PAINT message to draw itself. Typically, it should handle mouse and keyboard messages as well. Consult the descriptions of individual messages to determine whether your window procedure should handle them.

Your application can call the DefWindowProc function as part of the processing of a message. In such a case, the application can modify the message parameters before passing the message to DefWindowProc, or it can continue with the default processing after performing its own operations.

A dialog box procedure receives a WM_INITDIALOG message instead of a WM_CREATE message and does not pass unprocessed messages to the DefDlgProc function. Otherwise, a dialog box procedure is exactly the same as a window procedure.


Associating a Window Procedure with a Window Class

You associate a window procedure with a window class when registering the class. You must fill a WNDCLASS structure with information about the class, and the lpfnWndProc member must specify the address of the window procedure. To register the class, pass the address of WNDCLASS structure to the RegisterClass function. Once the window class is registered, the window procedure is automatically associated with each new window created with that class.

The following example shows how to associate the window procedure in the previous example with a window class.

int APIENTRY WinMain(hinstance, hinstPrev, lpCmdLine, nCmdShow)

HINSTANCE hinstance;  /* handle of current instance     */

HINSTANCE hinstPrev;  /* handle of previous instance    */

LPSTR lpCmdLine;      /* address of command-line string */

int nCmdShow;         /* show-window type               */

{

    WNDCLASS wc;

    /* Register the main window class. */

    wc.style = CS_HREDRAW | CS_VREDRAW;

    wc.lpfnWndProc = (WNDPROC) MainWndProc;

    wc.cbClsExtra = 0;

    wc.cbWndExtra = 0;

    wc.hInstance = hinstance;

    wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);

    wc.hCursor = LoadCursor(NULL, IDC_ARROW);

    wc.hbrBackground = GetStockObject(WHITE_BRUSH);

    wc.lpszMenuName =  "MainMenu";

    wc.lpszClassName = "MainWindowClass";

    if (!RegisterClass(&wc))

       return FALSE;

    .

    . /* Process other messages. */

    .

}


Subclassing a Window

To subclass an instance of a window, call the SetWindowLong function and specify the GWL_WNDPROC flag, the handle of the window to subclass, and a pointer to the subclass procedure. The SetWindowLong function returns a pointer to the original window procedure; use this pointer to pass messages to the original procedure.

The following example shows how to subclass an instance of an edit control in a dialog box. The subclass window procedure allows the edit control to receive all keyboard input, including the ENTER and TAB keys, whenever the control has the input focus.

WNDPROC wpOrigEditProc;

LRESULT APIENTRY EditBoxProc(hwndDlg, uMsg, wParam, lParam)

HWND hwndDlg;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    HWND hwndEdit;

    switch(uMsg) {

        case WM_INITDIALOG:

            /* Retrieve the handle of the edit control. */

            hwndEdit = GetDlgItem(hwndDlg, ID_EDIT);

            /* Subclass the edit control. */

            wpOrigEditProc = (WNDPROC) SetWindowLong(hwndEdit,

                GWL_WNDPROC, (LONG) EditSubclassProc);

            .

            . /* Continue the initialization procedure. */

            .

            return TRUE;

        case WM_DESTROY:

            /* Remove the subclass from the edit control. */

            SetWindowLong(hwndEdit, GWL_WNDPROC,

                (LONG) wpOrigEditProc);

            .

            . /* Continue the cleanup procedure. */

            .

            break;

    }

    return FALSE;

        UNREFERENCED_PARAMETER(lParam);

}

/*

 * Subclass procedure

 */

LRESULT APIENTRY EditSubclassProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    if (uMsg == WM_GETDLGCODE)

        return DLGC_WANTALLKEYS;

    return CallWindowProc(wpOrigEditProc, hwnd, uMsg,

        wParam, lParam);

}


Functions

Following are the functions used with window classes.

CallWindowProc

DefWindowProc

WindowProc


Keyboard Input Overview

About Keyboard Input

All applications written for Microsoft® Windows™ should accept user input from the keyboard as well as from the mouse. A Windows-based application receives keyboard input in the form of messages posted to its windows. This topic describes how Windows generates keyboard input and how an application receives and processes that input.

The following topics discuss keyboard input:

Terms

Keyboard Input Model

Keyboard Focus and Activation

Keystroke Messages

Character Messages

Key Status

Keystroke and Character Translations

Hot Key Support

Processing Keystroke Messages

Translating Character Messages

Processing Character Messages

Using the Caret

Example: Displaying Keyboard Input

Keyboard Functions and Messages


Keyboard Input Model

Windows provides device-independent keyboard support for applications by installing a keyboard device driver appropriate for the current keyboard. Windows provides language-independent keyboard support by using the language-specific keyboard layout currently selected by the user or the application. The keyboard device driver receives scan codes from the keyboard, which are sent to the keyboard layout where they are translated into messages and posted to the appropriate windows in your application.

Assigned to each key on a keyboard is a unique value called a scan code, a device-dependent identifier for the key on the keyboard. A keyboard generates two scan codes when the user types a key--one when the user presses the key and another when the user releases the key.

The keyboard device driver interprets a scan code and translates (maps) it to a virtual-key code, a device-independent value defined by Windows that identifies the purpose of a key. After translating a scan code, the keyboard layout creates a message that includes the scan code, the virtual-key code, and other information about the keystroke, and then places the message in the system message queue. Windows removes the message from the system message queue and posts it to the message queue of the appropriate thread. Eventually, the thread's message loop removes the message and passes it to the appropriate window procedure for processing. The following figure illustrates the keyboard input model for Windows.


Keyboard Focus and Activation

Windows posts keyboard messages to the message queue of the thread that created the window with the keyboard focus. The keyboard focus is a temporary property of a window. Windows shares the keyboard among all windows on the display by shifting the keyboard focus, at the user's direction, from one window to another. The window that has the keyboard focus receives (from the message queue of the thread that created it) all keyboard messages until the focus changes to a different window.

A thread can call the GetFocus function to determine which of its windows (if any) currently has the keyboard focus. A thread can give the keyboard focus to one of its windows by calling the SetFocus function. When the keyboard focus changes from one window to another, the system sends a WM_KILLFOCUS message to the window that has lost the focus, and then sends a WM_SETFOCUS message to the window that has gained the focus.

The concept of keyboard focus is related to that of the active window. The active window is the top-level window the user is currently working with. The window with the keyboard focus is either the active window itself, or a child window of the active window. So the user can easily identify the active window, the system places it at the top of the Z order and highlights its title bar (if it has one) and border.

The user can activate a top-level window by clicking it, by selecting it using the ALT+TAB or ALT+ESC key combination, or by selecting if from Task List. A thread can activate a top-level window by using the SetActiveWindow function. It can determine whether a top-level window it created is active by using the GetActiveWindow function.

When one window is deactivated and another activated, Windows sends the WM_ACTIVATE message first to the window being deactivated, then to the window being activated. The low-order word of the wParam parameter is zero if the window is being deactivated and nonzero if it is being activated. When the default window procedure receives the WM_ACTIVATE message, it sets the keyboard focus to the active window.


Keystroke Messages

Pressing a key results in a WM_KEYDOWN or WM_SYSKEYDOWN message being placed in the thread message queue associated with the window that has the keyboard focus. Releasing a key results in a WM_KEYUP or WM_SYSKEYUP message being placed in the queue.

Key-up and key-down messages typically occur in pairs, but if the user holds down a key long enough to start the keyboard's automatic repeat feature, the system generates a number of WM_KEYDOWN or WM_SYSKEYDOWN messages in a row, then a single WM_KEYUP or WM_SYSKEYUP message when the user releases the key.

System and Nonsystem Keystrokes

Windows makes a distinction between system keystrokes and nonsystem keystrokes. System keystrokes produce system keystroke messages: WM_SYSKEYDOWN and WM_SYSKEYUP. Nonsystem keystrokes produce nonsystem keystroke messages: WM_KEYDOWN and WM_KEYUP.

If your window procedure must process a system keystroke message, make sure that after processing the message the procedure passes it to the DefWindowProc function. Otherwise, all system operations involving the ALT key will be disabled whenever the window has the keyboard focus. That is, the user won't be able to access the window's menus or System menu, or use the ALT+ESC or ALT+TAB key combination to activate a different window.

System keystroke messages are primarily for use by Windows rather than by an application. Windows uses them to provide its built-in keyboard interface to menus and to allow the user to control which window is active. System keystroke messages are generated when the user types a key in combination with the ALT key, or when the user types and no window has the keyboard focus (for example, when the active application is minimized). In this case, the messages are posted to the message queue associated with the active window.

Nonsystem keystroke messages are for use by application windows; the DefWindowProc function does nothing with them. A window procedure can discard any nonsystem keystroke messages that it does not need.

Virtual-Key Codes

The wParam parameter of a keystroke message contains the virtual-key code of the key that was pressed or released. A window procedure processes or ignores a keystroke message, depending on the value of the virtual-key code.

A typical window procedure processes only a small subset of the keystroke messages that it receives and ignores the rest. For example, a window procedure might process only WM_KEYDOWN keystroke messages, and only those that contain virtual-key codes for the cursor movement keys, shift keys (also called control keys), and function keys. A typical window procedure does not process keystroke messages from character keys. Instead, it uses the TranslateMessage function to convert the message into character messages. For more information about TranslateMessage and character messages, see Character Messages.

Keystroke Message Flags

The lParam parameter of a keystroke message contains additional information about the keystroke that generated the message. This information includes the repeat count, the scan code, the extended-key flag, the context code, the previous key-state flag, and the transition-state flag. The following illustration shows the locations of these flags and values in the lParam parameter:

Repeat Count

You can check the repeat count to determine whether a keystroke message represents more than one keystroke. The system increments the count when the keyboard generates WM_KEYDOWN or WM_SYSKEYDOWN messages faster than an application can process them. This often occurs when the user holds down a key long enough to start the keyboard's automatic repeat feature. Instead of filling the system message queue with the resulting key-down messages, the system combines the messages into a single key down message and increments the repeat count. Releasing a key cannot start the automatic repeat feature, so the repeat count for WM_KEYUP and WM_SYSKEYUP messages is always set to 1.

Scan Code

The scan code is the value that the keyboard hardware generates when the user presses a key. It is a device-dependent value that identifies the key pressed, as opposed to the character represented by the key. An application typically ignores scan codes. Instead, it uses the device-independent virtual-key codes to interpret keystroke messages.

Extended-Key Flag

The extended-key flag indicates whether the keystroke message originated from one of the additional keys on the enhanced keyboard. The extended keys consist of the ALT and CTRL keys on the right-hand side 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 NUM LOCK key; the BREAK (CTRL+PAUSE) key; the PRINT SCRN key; and the divide (/) and ENTER keys in the numeric keypad. The extended-key flag is set if the key is an extended key.

Context Code

The context code indicates whether the ALT key was down when the keystroke message was generated. The code is 1 if the ALT key was down and 0 if it was up.

Previous Key-State Flag

The previous key-state flag indicates whether the key that generated the keystroke message was previously up or down. It is 1 if the key was previously down and 0 if the key was previously up. You can use this flag to identify keystroke messages generated by the keyboard's automatic repeat feature. This flag is set to 1 for WM_KEYDOWN and WM_SYSKEYDOWN keystroke messages generated by the automatic repeat feature. It is always set to 0 for WM_KEYUP and WM_SYSKEYUP messages.

Transition-State Flag

The transition-state flag indicates whether pressing a key or releasing a key generated the keystroke message. This flag is always set to 0 for WM_KEYDOWN and WM_SYSKEYDOWN messages; it is always set to 1 for WM_KEYUP and WM_SYSKEYUP messages.


Character Messages

Keystroke messages provide a lot of information about keystrokes, but they don't provide character codes for character keystrokes. To retrieve character codes, an application must include the TranslateMessage function in its thread message loop. TranslateMessage passes a WM_KEYDOWN or WM_SYSKEYDOWN message to the keyboard layout. The layout examines the message's virtual-key code and, if it corresponds to a character key, provides the character code equivalent (taking into account the state of the SHIFT and CAPS LOCK keys). It then generates a character message that includes the character code and places the message at the top of the message queue. The next iteration of the message loop removes the character message from the queue and dispatches the message to the appropriate window procedure.

System and  Nonsystem Character Messages

A window procedure can receive four different character messages, including WM_CHAR, WM_DEADCHAR, WM_SYSCHAR, and WM_SYSDEADCHAR. The TranslateMessage function generates a WM_CHAR or WM_DEADCHAR message when it processes a WM_KEYDOWN message. Similarly, it generates a WM_SYSCHAR or WM_SYSDEADCHAR message when it processes a WM_SYSKEYDOWN message.

An application that processes keyboard input typically ignores all but the WM_CHAR message, passing any other messages to the DefWindowProc function. Windows uses the WM_SYSCHAR and WM_SYSDEADCHAR messages to implement menu mnemonics.

The wParam parameter of all character messages contains the character code of the character key that was pressed. The value of the character code depends on the window class of the window receiving the message. If the Unicode™ version of the RegisterClass function was used to register the window class, the system provides Unicode characters to all windows of that class. Otherwise, the system provides ASCII character codes from the Windows character set.

The contents of the lParam parameter of a character message are identical to the contents of the lParam parameter of the key-down message that was translated to produce the character message. For information about the contents of the lParam parameter, see Keystroke Message Flags.

Dead-Character Messages

Some non-English keyboards contain character keys that are not expected to produce characters by themselves. Instead, they are used to add a diacritic to the character produced by the subsequent keystroke. These keys are called dead keys. The circumflex key on a German keyboard is an example of a dead key. To enter the character consisting of an o with an circumflex, a German user would type the circumflex key followed by the o key. The window with the keyboard focus would receive the following sequence of messages:

WM_KEYDOWN

WM_DEADCHAR

WM_KEYUP

WM_KEYDOWN

WM_CHAR

WM_KEYUP

TranslateMessage generates the WM_DEADCHAR message when it processes the WM_KEYDOWN message from a dead key. Although the wParam parameter of the WM_DEADCHAR message contains the character code of the diacritic for the dead key, an application typically ignores the message. Instead, it processes the WM_CHAR message generated by the subsequent keystroke. The wParam parameter of the WM_CHAR message contains the character code of the letter with the diacritic. If the subsequent keystroke generates a character that cannot be combined with a diacritic, Windows generates two WM_CHAR messages. The wParam parameter of the first contains the character code of the diacritic; the wParam parameter of the second contains the character code of the subsequent character key.

The TranslateMessage function generates the WM_SYSDEADCHAR message when it processes the WM_SYSKEYDOWN message from a system dead key (a dead key that is pressed in combination with the ALT key). An application typically ignores the WM_SYSDEADCHAR message.


Key Status

While processing a keyboard message, an application may need to determine the status of another key besides the one that generated the current message. For example, a word processing application that allows the user to press SHIFT+END to highlight a block of text must check the status of the SHIFT key whenever it receives a keystroke message from the END key. The application can use the GetKeyState function to determine the status of a virtual key at the time the current message was generated, and it can use the GetAsyncKeyState function to retrieve the current status of a virtual key.

The keyboard layout maintains a list of names. The name of a key that produces a single character is the same as the character produced by the key. The name of a noncharacter key such as TAB and ENTER is stored as a character string. An application can retrieve the name of any key from the device driver by calling GetKeyNameText.


Keystroke and Character Translations

index "ToUnicode function"

Windows includes several special purpose functions that translate scan codes, character codes, and virtual-key codes provided by various keystroke messages. These functions include MapVirtualKey, ToAscii, ToUnicode, and VkKeyScan.


Hot Key Support

Windows provides a set of functions that applications can use to define hot keys. A hotkey for your application. A hot key is a key combination that generates a WM_HOTKEY message, a message the system places at the top of a thread's message queue, bypassing any existing messages in the queue. Applications use hot keys to obtain high-priority keyboard input from the user. For example, by defining a hot key consisting of the CTRL+C key combination, an application can allow the user to cancel a lengthy operation.

To define a hot key, an application calls the RegisterHotKey function, specifying the combination of keys that generates the WM_HOTKEY message, the handle of the window to receive the message, and the identifier of the hot key. When the user presses the hot key, a WM_HOTKEY message is placed in the message queue of the thread that created the given window. The wParam parameter of the message contains the identifier of the hot key. The application can define multiple hot keys for a thread, but each hot key in the thread must have a unique identifier. Before the application terminates, it should use the UnregisterHotKey function to destroy the hot key.


Processing Keystroke Messages

The window procedure of the window that has the keyboard focus receives keystroke messages when the user types at the keyboard. The keystroke messages are WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, and WM_SYSKEYUP. A typical window procedure ignores all keystroke messages except WM_KEYDOWN. Windows posts the WM_KEYDOWN message when the user presses a key.

When the window procedure receives the WM_KEYDOWN message, it should examine the virtual-key code that accompanies the message to determine how to process the keystroke. The virtual-key code is in the message's wParam parameter. Typically, an application processes only keystrokes generated by noncharacter keys, including the function keys, the cursor movement keys, and the special-purpose keys such as INS, DEL, HOME and END.

The following example shows the window procedure framework that a typical application uses to receive and process keystroke messages

case WM_KEYDOWN:

    switch (wParam) {

        case VK_LEFT:

            .

            . /* Process the LEFT ARROW key. */

            .

            break;

        case VK_RIGHT:

            .

            . /* Process the RIGHT ARROW key. */

            .

            break;

        case VK_UP:

            .

            . /* Process the UP ARROW key. */

            .

            break;

        case VK_DOWN:

            .

            . /* Process the DOWN ARROW key. */

            .

            break;

        case VK_HOME:

            .

            . /* Process the HOME key. */

            .

            break;

        case VK_END:

            .

            . /* Process the END key. */

            .

            break;

        case VK_INSERT:

            .

            . /* Process the INS key. */

            .

            break;

        case VK_DELETE:

            .

            . /* Process the DEL key. */

            .

            break;

        case VK_F2:

            .

            . /* Process the F2 key. */

            .

            break;

        .

        . /* Process other noncharacter keystrokes. */

        .

        default:

            break;

    }


Translating Character Messages

Any thread that receives character input from the user must include the TranslateMessage function in its message loop. This function examines the virtual-key code of a keystroke message and, if the code corresponds to a character, places a character message into the message queue. The character message is removed and dispatched on the next iteration of the message loop; the wParam parameter of the message contains the character code.

In general, a thread's message loop should use the TranslateMessage function to translate every message, not just virtual-key messages. Although TranslateMessage has no effect on other types of messages, it guarantees that keyboard input is translated correctly. The following example shows how to include the TranslateMessage function in a typical thread message loop.

while (GetMessage(&msg, (HWND) NULL, 0, 0)) {

    if (TranslateAccelerator(hwndMain, haccl, &msg) == 0) {

        TranslateMessage(&msg);

        DispatchMessage(&msg);

    }

}


Processing Character Messages

A window procedure receives a character message when the TranslateMessage function translates a virtual-key code corresponding to a character key. The character messages are WM_CHAR, WM_DEADKEY, WM_SYSCHAR, and WM_SYSDEADKEY. A typical window procedure ignores all character messages except WM_CHAR. The TranslateMessage function generates a WM_CHAR message when the user presses any of the following keys:

Any character key

BACKSPACE

ENTER (carriage return)

ESC

SHIFT+ENTER (linefeed)

TAB

When a window procedure receives the WM_CHAR message, it should examine the character code that accompanies the message to determine how to process the character. The character code is in the message's wParam parameter.

The following example shows the window procedure framework that a typical application uses to receive and process character messages.

case WM_CHAR:

    switch (wParam) {

        case 0x08:

            .

            . /* Process a backspace. */

            .

            break;

        case 0x0A:

            .

            . /* Process a linefeed. */

            .

            break;

        case 0x1B:

            .

            . /* Process an escape. */

            .

            break;

        case 0x09:

            .

            . /* Process a tab. */

            .

            break;

        case 0x0D:

            .

            . /* Process a carriage return. */

            .

            break;

        default:

            .

            . /* Process displayable characters. */

            .

            break;

    }


Using the Caret

A window that receives keyboard input typically displays the characters the user types in the window's client area. A window should use a caret to indicate the position in the client area where the next character will appear. The window should also create and display the caret when it receives the keyboard focus, and hide and destroy the caret when it loses the focus. A window can perform these operations in the processing of the WM_SETFOCUS and WM_KILLFOCUS messages.


Example: Displaying Keyboard Input

The example in this section shows how an application can receive characters from the keyboard, display them in the client area of a window, and update the position of the caret with each character typed. It also demonstrates how to move the caret in response to the LEFT ARROW, RIGHT ARROW, HOME and END keystrokes, and shows how to highlight selected text in response to the SHIFT+RIGHT ARROW key combination.

During processing of the WM_CREATE message, the window procedure shown in the example allocates a 64K buffer for storing keyboard input. It also retrieves the metrics of the currently loaded font, saving the height and average width of characters in the font. The height and width are used in processing the WM_SIZE message to calculate the line length and maximum number of lines, based on the size of the client area.

The window procedure creates and displays the caret when processing the WM_SETFOCUS message. It hides and deletes the caret when processing the WM_KILLFOCUS message.

When processing the WM_CHAR message, the window procedure displays characters, stores them in the input buffer, and updates the caret position. The window procedure also converts tab characters to four consecutive space characters. Backspace, linefeed, and escape characters generate a beep but are not otherwise processed.

The window procedure performs the left, right, end, and home caret movements when processing the WM_KEYDOWN message. While processing the action of the RIGHT ARROW key, the window procedure checks the state of the SHIFT key and, if it is down, highlights the character to the right of the caret as the caret is moved.

Note that the following code is written so that it can be compiled either as Unicode or as ANSI. If the source code defines Unicode, strings are handled as Unicode characters; otherwise, they are handled as ANSI characters.

#define BUFSIZE 65535

#define SHIFTED 0x8000

LONG APIENTRY MainWndProc(hwndMain, uMsg, wParam, lParam)

HWND hwndMain;

UINT uMsg;

UINT wParam;

LONG lParam;

{

    HDC hdc;                   /* handle of device context      */

    TEXTMETRIC tm;             /* structure for text metrics    */

    static DWORD dwCharX;      /* average width of characters   */

    static DWORD dwCharY;      /* height of characters          */

    static DWORD dwClientX;    /* width of client area          */

    static DWORD dwClientY;    /* height of client area         */

    static DWORD dwLineLen;    /* line length                   */

    static DWORD dwLines;      /* text lines in client area     */

    static int nCaretPosX = 0; /* horizontal position of caret  */

    static int nCaretPosY = 0; /* vertical position of caret    */

    static int nCharWidth = 0; /* width of a character          */

    static int cch = 0;        /* characters in buffer          */

    static int nCurChar = 0;   /* index of current character    */

    static PTCHAR pchInputBuf; /* address of input buffer       */

    int i, j;                  /* loop counters                 */

    int cCR = 0;               /* count of carriage returns     */

    int nCRIndex = 0;          /* index of last carriage return */

    int nVirtKey;              /* virtual-key code              */

    TCHAR szBuf[128];          /* temporary buffer              */

    TCHAR ch;                  /* current character             */

    PAINTSTRUCT ps;            /* required by BeginPaint        */

    RECT rc;                   /* output rectangle for DrawText */

    SIZE sz;                   /* string dimensions             */

    COLORREF crPrevText;       /* previous text color           */

    COLORREF crPrevBk;         /* previous background color     */

    switch (uMsg) {

        case WM_CREATE:

            /* Get the metrics of the current font. */

            hdc = GetDC(hwndMain);

            GetTextMetrics(hdc, &tm);

            ReleaseDC(hwndMain, hdc);

            /* Save the average character width and height. */

            dwCharX = tm.tmAveCharWidth;

            dwCharY = tm.tmHeight;

            /* Allocate a buffer to store keyboard input. */

            pchInputBuf = (LPTSTR) GlobalAlloc(GPTR,

                BUFSIZE * sizeof(TCHAR));

            return 0;

        case WM_SIZE:

            /* Save the new width and height of the client area. */

            dwClientX = LOWORD(lParam);

            dwClientY = HIWORD(lParam);

            /*

             * Calculate the maximum width of a line and the

             * maximum number of lines in the client area.

             */

            dwLineLen = dwClientX - dwCharX;

            dwLines = dwClientY / dwCharY;

            break;

        case WM_SETFOCUS:

            /*

             * Create, position, and display the caret when the

             * window receives the keyboard focus.

             */

            CreateCaret(hwndMain, (HBITMAP) 1, 0, dwCharY);

            SetCaretPos(nCaretPosX, nCaretPosY * dwCharY);

            ShowCaret(hwndMain);

            break;

        case WM_KILLFOCUS:

            /*

             * Hide and destroy the caret when the window loses the

             * keyboard focus.

             */

            HideCaret(hwndMain);

            DestroyCaret();

            break;

        case WM_CHAR:

            switch (wParam) {

                case 0x08: /* backspace */

                case 0x0A: /* linefeed */

                case 0x1B: /* escape */

                    MessageBeep(0xFFFFFFFF);

                    return 0;

                case 0x09: /* tab */

                    /* Convert tabs to four consecutive spaces. */

                    for (i = 0; i < 4; i++)

                        SendMessage(hwndMain, WM_CHAR, 0x20, 0);

                    return 0;

                case 0x0D: /* carriage return */

                    /*

                     * Record the carriage return and position the

                     * caret at the beginning of the new line.

                     */

                    pchInputBuf[cch++] = 0x0D;

                    nCaretPosX = 0;

                    nCaretPosY += 1;

                    break;

                default: /* displayable character */

                    ch = (TCHAR) wParam;

                    HideCaret(hwndMain);

                     /*

                      * Retrieve the character's width and output

                      * the character.

                      */

                    hdc = GetDC(hwndMain);

                    GetCharWidth(hdc, (UINT) wParam, (UINT) wParam,

                        &nCharWidth);

                    TextOut(hdc, nCaretPosX, nCaretPosY * dwCharY,

                        &ch, 1);

                    ReleaseDC(hwndMain, hdc);

                    /* Store the character in the buffer. */

                    pchInputBuf[cch++] = ch;

                    /*

                     * Calculate the new horizontal position of the

                     * caret. If the position exceeds the maximum,

                     * insert a carriage return and move the caret

                     * to the beginning of the next line.

                     */

                    nCaretPosX += nCharWidth;

                    if ((DWORD) nCaretPosX > dwLineLen) {

                        nCaretPosX = 0;

                        pchInputBuf[cch++] = 0x0D;

                        ++nCaretPosY;

                    }

                    nCurChar = cch;

                    ShowCaret(hwndMain);

                    break;

            }

            SetCaretPos(nCaretPosX, nCaretPosY * dwCharY);

            break;

        case WM_KEYDOWN:

            switch (wParam) {

                case VK_LEFT: /* LEFT ARROW */

                    /*

                     * The caret can move only to the beginning of

                     * the current line.

                     */

                    if (nCaretPosX > 0) {

                        HideCaret(hwndMain);

                        /*

                         * Retrieve the character to the left of

                         * the caret, calculate the character's

                         * width, then subtract the width from the

                         * current horizontal position of the caret

                         * to obtain the new position.

                         */

                        ch = pchInputBuf[--nCurChar];

                        hdc = GetDC(hwndMain);

                        GetCharWidth(hdc, ch, ch, &nCharWidth);

                        ReleaseDC(hwndMain, hdc);

                        nCaretPosX = max(nCaretPosX - nCharWidth,

                            0);

                        ShowCaret(hwndMain);

                    }

                    break;

                case VK_RIGHT: /* RIGHT ARROW */

                    /*

                     * Caret moves to the right or, when a carriage

                     * return is encountered, to the beginning of

                     * the next line.

                     */

                    if (nCurChar < cch) {

                        HideCaret(hwndMain);

                        /*

                         * Retrieve the character to the right of

                         * the caret. If it's a carriage return,

                         * position the caret at the beginning of

                         * the next line.

                         */

                        ch = pchInputBuf[nCurChar];

                        if (ch == 0x0D) {

                            nCaretPosX = 0;

                            nCaretPosY++;

                        }

                        /*

                         * If the character isn't a carriage

                         * return, check to see whether the SHIFT

                         * key is down. If it is, invert the text

                         * colors and output the character.

                         */

                        else {

                            hdc = GetDC(hwndMain);

                            nVirtKey = GetKeyState(VK_SHIFT);

                            if (nVirtKey & SHIFTED) {

                                crPrevText = SetTextColor(hdc,

                                    RGB(255, 255, 255));

                                crPrevBk = SetBkColor(hdc,

                                    RGB(0,0,0));

                                TextOut(hdc, nCaretPosX,

                                    nCaretPosY * dwCharY,

                                    &ch, 1);

                                SetTextColor(hdc, crPrevText);

                                SetBkColor(hdc, crPrevBk);

                            }

                            /*

                             * Get the width of the character and

                             * calculate the new horizontal

                             * position of the caret.

                             */

                            GetCharWidth(hdc, ch, ch, &nCharWidth);

                            ReleaseDC(hwndMain, hdc);

                            nCaretPosX = nCaretPosX + nCharWidth;

                        }

                        nCurChar++;

                        ShowCaret(hwndMain);

                        break;

                    }

                    break;

                case VK_UP: /* UP ARROW   */

                case VK_DOWN: /* DOWN ARROW */

                    MessageBeep(0xFFFFFFFF);

                    return 0;

                case VK_HOME: /* HOME */

                    /*

                     * Set the caret's position to the upper left

                     * corner of the client area.

                     */

                    nCaretPosX = nCaretPosY = 0;

                    nCurChar = 0;

                    break;

                case VK_END: /* END */

                    /* Move the caret to the end of the text. */

                    for (i=0; i < cch; i++) {

                        /*

                         * Count the carriage returns and save the

                         * index of the last one.

                         */

                        if (pchInputBuf[i] == 0x0D) {

                            cCR++;

                            nCRIndex = i + 1;

                        }

                    }

                    nCaretPosY = cCR;

                    /*

                     * Copy all text between the last carriage

                     * return and the end of the keyboard input

                     * buffer to a temporary buffer.

                     */

                    for (i = nCRIndex, j = 0; i < cch; i++, j++)

                        szBuf[j] = pchInputBuf[i];

                    szBuf[j] = TEXT('\0');

                    /*

                     * Retrieve the text extent and use it

                     * to set the horizontal position of the

                     * caret.

                     */

                    hdc = GetDC(hwndMain);

                    GetTextExtentPoint(hdc, szBuf, lstrlen(szBuf),

                        &sz);

                    nCaretPosX = sz.cx;

                    ReleaseDC(hwndMain, hdc);

                    nCurChar = cch;

                    break;

                default:

                    break;

            }

            SetCaretPos(nCaretPosX, nCaretPosY * dwCharY);

            break;

        case WM_PAINT:

            if (cch == 0)       /* nothing in input buffer */

                break;

            hdc = BeginPaint(hwndMain, &ps);

            HideCaret(hwndMain);

            /*

             * Set the clipping rectangle, and then draw the text

             * into it.

             */

            SetRect(&rc, 0, 0, dwLineLen, dwClientY);

            DrawText(hdc, pchInputBuf, -1, &rc, DT_LEFT);

            ShowCaret(hwndMain);

            EndPaint(hwndMain, &ps);

            break;

        .

        . /* Process other messages. */

        .

        case WM_DESTROY:

            PostQuitMessage(0);

            /* Free the input buffer. */

            GlobalFree((HGLOBAL) pchInputBuf);

            break;

        default:

            return DefWindowProc(hwndMain, uMsg, wParam, lParam);

    }

    return NULL;

}


Keyboard Functions and Messages

Following are the functions and messages used to receive and process keyboard input:

Functions

EnableWindow

GetActiveWindow

GetAsyncKeyState

GetFocus

GetKeyboardState

GetKeyNameText

GetKeyState

IsWindowEnabled

keybd_event

MapVirtualKey

RegisterHotKey

SetActiveWindow

SetFocus

SetKeyboardState

ToAscii

ToUnicode

UnregisterHotKey

VkKeyScan

Messages

WM_ACTIVATE

WM_CHAR

WM_DEADCHAR

WM_HOTKEY

WM_KEYDOWN

WM_KEYUP

WM_KILLFOCUS

WM_SETFOCUS

WM_SYSCHAR

WM_SYSDEADCHAR

WM_SYSKEYDOWN

WM_SYSKEYUP


Mouse Input Overview

About Mouse Input

The mouse is an important, but optional, user-input device for applications written for Microsoft® Windows™. A well-written Windows-based application should include a mouse interface, but it should not depend on the mouse as the sole means of acquiring user input. The application should provide full keyboard support as well.

A Windows-based application receives mouse input in the form of messages that are sent or posted to its windows. This topic describes how Windows generates mouse input and explains how an application receives and processes that input.

The following topics discuss Win32 mouse input:

Terms

Mouse Cursor

Mouse Capture

Mouse Configuration

Mouse Messages

The WM_NCHITTEST Message

Window Activation

Tracking the Mouse Cursor

Example: Drawing Lines With the Mouse

Processing a Double-Click Message

Example: Selecting a Line of Text

Mouse Input Functions and Messages


Mouse Cursor

When the user moves the mouse, the system moves a bitmap on the screen called the mouse cursor. The mouse cursor contains a single-pixel point called the hot spot, a point that the system tracks and recognizes as the position of the cursor. When a mouse event occurs, the window that contains the hot spot typically receives the mouse message resulting from the event. The window need not be active or have the keyboard focus to receive a mouse message.

The system maintains a variable that controls the mouse speed--that is, the distance the cursor moves when the user moves the mouse. You can use the SystemParametersInfo function with the SPI_GETMOUSE or SPI_SETMOUSE flag to retrieve or set the mouse speed.


Mouse Capture

The system typically posts a mouse message to the window that contains the cursor hot spot at the time a mouse event occurs. An application can change this behavior by using the SetCapture function to route mouse messages to a specific window. The window receives all mouse messages until the application calls the ReleaseCapture function or specifies another capture window, or until the user clicks a window created by another thread.

Only the foreground window can capture mouse input. When a background window attempts to capture mouse input, it receives messages only for mouse events that occur when the cursor hot spot is within the visible portion of the window.

Capturing mouse input is useful if a window must receive all mouse input, even when the cursor moves outside the window. For example, an application typically tracks the cursor position after a mouse "button down" event, following the cursor until a "button up" event occurs. If an application has not captured mouse input and the user releases the mouse button outside the window, the window does not receive the button up message.

A thread can use the GetCapture function to determine whether one of its windows has captured the mouse. If one of the thread's windows has captured the mouse, GetCapture retrieves the handle of the window.


Mouse Configuration

Although the mouse is an important input device for Windows-based applications, not every user necessarily has a mouse. An application can determine whether the system includes a mouse by passing the SM_MOUSEPRESENT value to the GetSystemMetrics function.

Windows supports a mouse having up to three buttons. On a three-button mouse, the buttons are designated as the left, middle, and right buttons. Windows messages and named constants related to the mouse buttons use the letters L, M, and R to identify the buttons. The button on a single-button mouse is considered to be the left button. Although Windows supports a mouse with multiple buttons, most applications use the left button primarily and use the others little, if at all.

An application can determine the number of buttons on the mouse by passing the SM_CMOUSEBUTTONS value to the GetSystemMetrics function. To configure the mouse for a left-handed user, the application can use the SwapMouseButton function to reverse the meaning of the left and right mouse buttons. Passing the SPI_SETMOUSEBUTTONSWAP value to the SystemParametersInfo function is another way to reverse the meaning of the buttons. Note, however, that the mouse is a shared resource, so reversing the meaning of the buttons affects all applications.


Mouse Messages

The mouse generates an input event whenever the user moves the mouse, or presses or releases a mouse button. Windows converts mouse input events into messages and posts them to the appropriate thread's message queue. When mouse messages are posted faster than a thread can process them, Windows discards all but the most recent mouse message.

A window receives a mouse message when a mouse event occurs while the cursor is within the borders of the window, or when the window has captured the mouse. Mouse messages are divided into two groups: client area messages and nonclient area messages. Typically, an application processes client area messages and ignores nonclient area messages.

Client Area Mouse Messages

A window receives a client area mouse message when a mouse event occurs within the window's client area. The system posts the WM_MOUSEMOVE message to the window when the user moves the cursor within the client area. It posts one of the following messages when the user presses or releases a mouse button while the cursor is within the client area.

Message	Meaning

WM_LBUTTONDBLCLK	The left mouse button was double-clicked.

WM_LBUTTONDOWN	The left mouse button was pressed.

WM_LBUTTONUP	The left mouse button was released.

WM_MBUTTONDBLCLK	The middle mouse button was double-clicked.

WM_MBUTTONDOWN	The middle mouse button was pressed.

WM_MBUTTONUP	The middle mouse button was released.

WM_RBUTTONDBLCLK	The right mouse button was double-clicked.

WM_RBUTTONDOWN	The right mouse button was pressed.

WM_RBUTTONUP	The right mouse button was released.

Message Parameters

The lParam parameter of a client area mouse message indicates the position of the cursor hot spot. The low-order word indicates the x-coordinate of the hot spot, and the high-order word indicates the y-coordinate. The coordinates are given in client coordinates. In the client coordinate system, all points on the screen are given relative to the coordinates (0,0) of the upper-left corner of the client area.

The wParam parameter contains flags that indicate the status of the other mouse buttons and the CTRL and SHIFT keys at the time of the mouse event. You can check for these flags when mouse-message processing depends on the state of another mouse button or of the CTRL or SHIFT key. The lParam parameter can be a combination of the following values.

Value	Meaning

MK_CONTROL	The CTRL key is down.

MK_LBUTTON	The left mouse button is down.

MK_MBUTTON	The middle mouse button is down.

MK_RBUTTON	The right mouse button is down.

MK_SHIFT	The SHIFT key is down.

Double-Click Messages

The system generates a double-click message when the user clicks a mouse button twice in quick succession. When the user clicks a button, the system establishes a rectangle centered around the cursor hot spot. It also marks the time at which the click occurred. When the user clicks the same button a second time, the system determines whether the hot spot is still within the rectangle and calculates the time elapsed since the first click. If the hot spot is still within the rectangle and the elapsed time does not exceeded the double-click time-out value, the system generates a double-click message.

An application can get and set double-click time-out values by using the GetDoubleClickTime and SetDoubleClickTime functions, respectively. Alternatively, the application can set the double-click time-out value by using the SPI_SETDOUBLECLICKTIME flag with the SystemParametersInfo function. It can also set the size of the rectangle that Windows uses to detect double-clicks by passing the SPI_SETDOUBLECLKWIDTH and SPI_SETDOUBLECLKHEIGHT flags to SystemParametersInfo. Note, however, that setting the double-click time-out value and rectangle affects all applications.

An application-defined window does not, by default, receive double-click messages. Because of the system overhead involved in generating double-click messages, these messages are generated only for windows belonging to classes that have the CS_DBLCLKS class style. Your application must set this style when registering the window class.

A double-click message is always the third message in a four-message series. The first two messages are the button down and button up messages generated by the first click. The second click generates the double-click message followed by another button up message. For example, double-clicking the left mouse button generates the following message sequence:

WM_LBUTTONDOWN

WM_LBUTTONUP

WM_LBUTTONDBLCLK

WM_LBUTTONUP

Because a window always receives a button down message before receiving a double-click message, an application typically uses a double-click message to extend a task it began during a button down message. For example, when the user clicks a color in the color palette of Windows PaintBrush, PaintBrush displays the selected color next to the palette. When the user double-clicks a color, PaintBrush displays the color and opens the Edit Colors dialog box.

Nonclient Area Mouse Messages

A window receives a nonclient area mouse message when a mouse event occurs in any part of a window except the client area. A window's nonclient area consists of its border, menu bar, title bar, scroll bar, System menu, Minimize button, and Maximize button.

Windows generates nonclient area messages primarily for its own use. For example, Windows uses nonclient area messages to change the cursor to a two-headed arrow when the cursor hot spot moves into a window's border. A window must pass nonclient area mouse messages to the DefWindowProc function to take advantage of the built-in mouse interface found in Windows.

There is a corresponding nonclient area mouse message for each client area mouse message. The names of these messages are similar except that the named constants for the nonclient area messages include the letters "NC". For example, moving the cursor in the nonclient area generates a WM_NCMOUSEMOVE message, and pressing the left mouse button while the cursor is in the nonclient area generates a WM_NCLBUTTONDOWN message.

The lParam parameter of a nonclient area mouse message is a POINTS structure that contains the x- and y-coordinates of the cursor hot spot. Unlike coordinates of client area mouse messages, the coordinates are given in screen coordinates rather than client coordinates. In the screen coordinate system, all points on the screen are relative to the coordinates (0,0) of the upper-left corner of the screen.

The wParam parameter contains a hit-test code, a value that indicates where in the nonclient area the mouse event occurred. The following section explains the purpose of hit-test codes.


The WM_NCHITTEST Message

Whenever a mouse event occurs, the system sends a WM_NCHITTEST message to either the window that contains the cursor hot spot or the window that has captured the mouse. Windows uses this message to determine whether to send a client area or nonclient area mouse message. An application that must receive mouse movement and mouse button messages must pass the WM_NCHITTEST message to the DefWindowProc function.

The lParam parameter of the WM_NCHITTEST message contains the screen coordinates of the cursor hot spot. The DefWindowProc function examines the coordinates and returns a hit-test code that identifies the location of the hot spot. The hit-test code can be one of the following values.

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

If the cursor is in the client area of a window, DefWindowProc returns the HTCLIENT hit-test code to the window procedure. When the window procedure returns this code to the system, Windows converts the screen coordinates of the cursor hot spot to client coordinates, and then posts the appropriate client area mouse message.

The DefWindowProc function returns one of the other hit-test codes when the cursor hot spot is in a window's nonclient area. When the window procedure returns one of these hit-test codes, Windows posts a nonclient area mouse message, placing the hit-test code in the message's wParam parameter and the cursor coordinates in the lParam parameter.


Window Activation

When the user clicks an inactive top-level window or the child window of a inactive top-level window, Windows sends the WM_MOUSEACTIVATE message (among others) to the top-level or child window. Windows sends this message after posting the WM_NCHITTEST message to the window, but before posting the button down message. When WM_MOUSEACTIVATE is passed to the DefWindowProc function, Windows activates the top-level window and then posts the button down message to the top-level or child window.

By processing WM_MOUSEACTIVATE, a window can control whether the top-level window becomes the active window as a result of a mouse click, and whether the window that was clicked receives the subsequent button down message. It does so by returning one of the following values after processing WM_MOUSEACTIVATE.

Value	Meaning

MA_ACTIVATE	Activate the window, and do not discard the mouse message.

MA_NOACTIVATE	Do not activate the window, and do not discard the mouse message.

MA_ACTIVATEANDEAT	Activate the window, and discard the mouse message.

MA_NOACTIVATEANDEAT	Do not activate the window, but discard the mouse message.


Tracking the Mouse Cursor

Windows-based applications often perform tasks that involve tracking the position of the mouse cursor. Most drawing applications, for example, track it during drawing operations, allowing the user to draw in a window's client area by dragging the mouse. Word-processing applications also track the cursor, enabling the user to select a word or block of text by clicking and dragging the mouse.

Tracking the cursor typically involves processing the WM_LBUTTONDOWN, WM_MOUSEMOVE, and WM_LBUTTONUP messages. A window determines when to begin tracking the cursor by checking the cursor position provided in the lParam parameter of the WM_LBUTTONDOWN message. For example, a word-processing application would begin tracking the cursor only if the WM_LBUTTONDOWN message occurred while the cursor was on a line of text, but not if it was past the end of the document.

A window tracks the position of the cursor by processing the stream of WM_MOUSEMOVE messages posted to the window as the mouse moves. Processing the WM_MOUSEMOVE message typically involves a repetitive painting or drawing operation in the client area. For example, a drawing application might redraw a line repeatedly as the mouse moves. A window uses the WM_LBUTTONUP message as a signal to stop tracking the cursor.


Example: Drawing Lines With the Mouse

Drawing Lines with the Mouse

The example in this section demonstrates how to track the mouse cursor. It contains portions of a window procedure that enables the user to draw lines in a window's client area by dragging the mouse.

When the window procedure receives a WM_LBUTTONDOWN message, it captures the mouse and saves the coordinates of the cursor, using the coordinates as the starting point of the line. It also uses the ClipCursor function to confine the cursor to the client area during the line drawing operation.

During the first WM_MOUSEMOVE message, the window procedure draws a line from the starting point to the current position of the cursor. During subsequent WM_MOUSEMOVE messages, the window procedure erases the previous line by drawing over it with an inverted pen color. Then it draws a new line from the starting point to the new position of the cursor.

The WM_LBUTTONUP message signals the end of the drawing operation. The window procedure releases the mouse capture and frees the mouse from the client area.

LRESULT APIENTRY MainWndProc(hwndMain, uMsg, wParam, lParam)

HWND hwndMain;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    HDC hdc;                       /* handle of device context  */

    RECT rcClient;                 /* client area rectangle     */

    POINT ptClientUL;              /* client upper-left corner  */

    POINT ptClientLR;              /* client lower-right corner */

    static POINTS ptsBegin;        /* beginning point           */

    static POINTS ptsEnd;          /* new endpoint              */

    static POINTS ptsPrevEnd;      /* previous endpoint         */

    static BOOL fPrevLine = FALSE; /* previous line flag        */

    switch (uMsg) {

        case WM_LBUTTONDOWN:

            /* Capture mouse input. */

            SetCapture(hwndMain);

            /*

             * Retrieve the screen coordinates of the client area,

             * and convert them into client coordinates.

            /*

            GetClientRect(hwndMain, &rcClient);

            ptClientUL.x = rcClient.left;

            ptClientUL.y = rcClient.top;

            /*

             * Add one to the right and bottom sides, because the

             * coordinates retrieved by GetClientRect do not

             * include the far left and lowermost pixels.

             */

            ptClientLR.x = rcClient.right + 1;

            ptClientLR.y = rcClient.bottom + 1;

            ClientToScreen(hwndMain, &ptClientUL);

            ClientToScreen(hwndMain, &ptClientLR);

            /*

             * Copy the client coordinates of the client area

             * to the rcClient structure. Confine the mouse cursor

             * to the client area by passing the rcClient structure

             * to the ClipCursor function.

             */

            SetRect(&rcClient, ptClientUL.x, ptClientUL.y,

                ptClientLR.x, ptClientLR.y);

            ClipCursor(&rcClient);

            /*

             * Convert the cursor coordinates into a POINTS

             * structure, which defines the beginning point of the

             * line drawn during a WM_MOUSEMOVE message.

             */

            ptsBegin = MAKEPOINTS(lParam);

            return 0;

        case WM_MOUSEMOVE:

            /*

             * When moving the mouse, the user must hold down

             * the left mouse button to draw lines.

             */

            if (wParam & MK_LBUTTON) {

                /*

                 * Retrieve a device context (DC) for the client

                 * area.

                 */

                hdc = GetDC(hwndMain);

                /*

                 * The following function ensures that pixels of

                 * the previously drawn line are set to white and

                 * those of the new line are set to black.

                 */

                SetROP2(hdc, R2_NOTXORPEN);

                /*

                 * If a line was drawn during an earlier

                 * WM_MOUSEMOVE message, draw over it. This erases

                 * the line by setting the color of its pixels to

                 * white.

                 */

                if (fPrevLine) {

                    MoveToEx(hdc, ptsBegin.x, ptsBegin.y,

                        (LPPOINT) NULL);

                    LineTo(hdc, ptsPrevEnd.x, ptsPrevEnd.y);

                }

                /*

                 * Convert the current cursor coordinates to a

                 * POINTS structure, and then draw a new line.

                 */

                ptsEnd = MAKEPOINTS(lParam);

                MoveToEx(hdc, ptsBegin.x, ptsBegin.y,

                    (LPPOINT) NULL);

                LineTo(hdc, ptsEnd.x, ptsEnd.y);

                /*

                 * Set the previous line flag, save the ending

                 * point of the new line, and then release the DC.

                 */

                fPrevLine = TRUE;

                ptsPrevEnd = ptsEnd;

                ReleaseDC(hwndMain, hdc);

            }

            break;

        case WM_LBUTTONUP:

            /*

             * The user has finished drawing the line. Reset the

             * previous line flag, release the mouse cursor, and

             * release the mouse capture.

             */

            fPrevLine = FALSE;

            ClipCursor(NULL);

            ReleaseCapture();

            return 0;

        case WM_DESTROY:

            PostQuitMessage(0);

            break;

        .

        . /* Process other messages. */

        .


Processing a Double-Click Message

To receive double-click messages, a window must belong to a window class that has the CS_DBLCLKS class style. You set this style when registering the window class, as shown in the following example.

BOOL InitApplication(hInstance)

HINSTANCE hInstance;

{

    WNDCLASS wc;

    wc.style = CS_DBLCLKS | CS_HREDRAW | CS_VREDRAW;

    wc.lpfnWndProc = (WNDPROC) MainWndProc;

    wc.cbClsExtra = 0;

    wc.cbWndExtra = 0;

    wc.hInstance = hInstance;

    wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);

    wc.hCursor = LoadCursor(NULL, IDC_IBEAM);

    wc.hbrBackground = GetStockObject(WHITE_BRUSH);

    wc.lpszMenuName = "MainMenu";

    wc.lpszClassName = "MainWClass";

    return RegisterClass(&wc);

}

A double-click message is always preceded by a button down message. For this reason, applications typically use a double-click message to extend a task that it began during a button down message.


Example: Selecting a Line of Text

The example in this section is taken from a simple word-processing application. It includes code that enables the user to set the position of the caret by clicking anywhere on a line of text, and to select (highlight) a line of text by double-clicking anywhere on the line.

LRESULT APIENTRY MainWndProc(hwndMain, uMsg, wParam, lParam)

HWND hwndMain;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    HDC hdc;                     /* handle of device context     */

    TEXTMETRIC tm;               /* font size data               */

    int i, j;                    /* loop counters                */

    int cCR = 0;                 /* count of carriage returns    */

    char ch;                     /* character from input buffer  */

    static int nBegLine;         /* beginning of selected line   */

    static int nCurrentLine = 0; /* currently selected line      */

    static int nLastLine = 0;    /* last text line               */

    static int nCaretPosX = 0;   /* x-coordinate of caret        */

    static int cch = 0;          /* number of characters entered */

    static int nCharWidth = 0;   /* exact width of a character   */

    static char szHilite[128];   /* text string to highlight     */

    static DWORD dwCharX;        /* average width of characters  */

    static DWORD dwLineHeight;   /* line height                  */

    static POINTS ptsCursor;     /* coordinates of mouse cursor  */

    static COLORREF crPrevText;  /* previous text color          */

    static COLORREF crPrevBk;    /* previous background color    */

    static PTCHAR pchInputBuf;   /* address of input buffer      */

    static BOOL fTextSelected = FALSE; /* text-selection flag    */

    switch (uMsg) {

        case WM_CREATE:

            /* Get the metrics of the current font. */

            hdc = GetDC(hwndMain);

            GetTextMetrics(hdc, &tm);

            ReleaseDC(hwndMain, hdc);

            /* Save the average character width and height. */

            dwCharX = tm.tmAveCharWidth;

            dwLineHeight = tm.tmHeight;

            /* Allocate a buffer to store keyboard input. */

            pchInputBuf = (LPSTR) GlobalAlloc(GPTR,

                BUFSIZE * sizeof(TCHAR));

            return 0;

        case WM_CHAR:

            switch (wParam) {

                case 0x08: /* backspace */

                case 0x0A: /* linefeed */

                case 0x1B: /* escape */

                    MessageBeep(0xFFFFFFFF);

                    return 0;

                case 0x09: /* tab */

                    /* Convert tabs to four consecutive spaces. */

                    for (i = 0; i < 4; i++)

                        SendMessage(hwndMain, WM_CHAR, 0x20, 0);

                    return 0;

                case 0x0D: /* carriage return */

                    /*

                     * Record the carriage return, and position the

                     * caret at the beginning of the new line.

                     */

                    pchInputBuf[cch++] = 0x0D;

                    nCaretPosX = 0;

                    nCurrentLine += 1;

                    break;

                default: /* displayable character */

                    ch = (char) wParam;

                    HideCaret(hwndMain);

                    /*

                     * Retrieve the character's width, and display the

                     * character.

                     */

                    hdc = GetDC(hwndMain);

                    GetCharWidth(hdc, (UINT) wParam, (UINT) wParam,

                        &nCharWidth);

                    TextOut(hdc, nCaretPosX,

                        nCurrentLine * dwLineHeight, &ch, 1);

                    ReleaseDC(hwndMain, hdc);

                    /* Store the character in the buffer. */

                    pchInputBuf[cch++] = ch;

                    /*

                     * Calculate the new horizontal position of

                     * the caret. If the new position exceeds the

                     * maximum, insert a carriage return and

                     * reposition the caret at the beginning of

                     * the next line.

                     */

                    nCaretPosX += nCharWidth;

                    if ((DWORD) nCaretPosX > dwMaxCharX) {

                        nCaretPosX = 0;

                        pchInputBuf[cch++] = 0x0D;

                        ++nCurrentLine;

                    }

                    ShowCaret(hwndMain);

                    break;

            }

            SetCaretPos(nCaretPosX, nCurrentLine * dwLineHeight);

            nLastLine = max(nLastLine, nCurrentLine);

            break;

        .

        . /* Process other messages. */

        .

        case WM_LBUTTONDOWN:

            /*

             * If a line of text is currently highlighted, redraw

             * the text to remove the highlighting.

             */

            if (fTextSelected) {

                hdc = GetDC(hwndMain);

                SetTextColor(hdc, crPrevText);

                SetBkColor(hdc, crPrevBk);

                TextOut(hdc, 0, nCurrentLine * dwLineHeight,

                    szHilite, lstrlen(szHilite));

                ReleaseDC(hwndMain, hdc);

                ShowCaret(hwndMain);

                fTextSelected = FALSE;

            }

            /* Save the current mouse-cursor coordinates. */

            ptsCursor = MAKEPOINTS(lParam);

            /*

             * Determine which line the cursor is on, and save

             * the line number. Do not allow line numbers greater

             * than the number of the last line of text. The

             * line number is later multiplied by the average height

             * of the current font. The result is used to set the

             * y-coordinate of the caret.

             */

            nCurrentLine = min((int)(ptsCursor.y / dwLineHeight),

                nLastLine);

            /*

             * Parse the text input buffer to find the first

             * character in the selected line of text. Each

             * line ends with a carriage return, so it is possible

             * to count the carriage returns to find the selected

             * line.

             */

            cCR = 0;

            nBegLine = 0;

            if (nCurrentLine != 0) {

                for (i = 0; (i < cch) &&

                        (cCR < nCurrentLine); i++) {

                    if (pchInputBuf[i] == 0x0D)

                        ++cCR;

                }

                nBegLine = i;

            }

            /*

             * Starting at the beginning of the selected line,

             * measure  the width of each character, summing the

             * width with each character measured. Stop when the

             * sum is greater than the x-coordinate of the cursor.

             * The sum is used to set the x-coordinate of the caret.

             */

            hdc = GetDC(hwndMain);

            nCaretPosX = 0;

            for (i = nBegLine;

                    (pchInputBuf[i] != 0x0D) && (i < cch); i++) {

                ch = pchInputBuf[i];

                GetCharWidth(hdc, (int) ch, (int) ch, &nCharWidth);

                if ((nCaretPosX + nCharWidth) > ptsCursor.x)

                    break;

                else

                    nCaretPosX += nCharWidth;

            }

            ReleaseDC(hwndMain, hdc);

            /* Set the caret to the user-selected position. */

            SetCaretPos(nCaretPosX, nCurrentLine * dwLineHeight);

            break;

        case WM_LBUTTONDBLCLK:

            /* Copy the selected line of text to a buffer. */

            for (i = nBegLine, j = 0; (pchInputBuf[i] != 0x0D) &&

                    (i < cch); i++)

                szHilite[j++] = pchInputBuf[i];

            szHilite[j] = '\0';

            /*

             * Hide the caret, invert the background and foreground

             * colors, and then redraw the selected line.

             */

            HideCaret(hwndMain);

            hdc = GetDC(hwndMain);

            crPrevText = SetTextColor(hdc, RGB(255, 255, 255));

            crPrevBk = SetBkColor(hdc, RGB(0, 0, 0));

            TextOut(hdc, 0, nCurrentLine * dwLineHeight, szHilite,

                lstrlen(szHilite));

            SetTextColor(hdc, crPrevText);

            SetBkColor(hdc, crPrevBk);

            ReleaseDC(hwndMain, hdc);

            fTextSelected = TRUE;

            break;

            .

            . /* Process other messages. */

            .

        default:

            return DefWindowProc(hwndMain, uMsg, wParam, lParam);

    }

    return NULL;

}


Mouse Input Functions and Messages

Following are the functions and messages used to receive and process mouse input.

Functions

GetCapture

GetDoubleClickTime

mouse_event

ReleaseCapture

SetCapture

SetDoubleClickTime

SwapMouseButton

Messages

WM_LBUTTONDBLCLK

WM_LBUTTONDOWN

WM_LBUTTONUP

WM_MBUTTONDBLCLK

WM_MBUTTONDOWN

WM_MBUTTONUP

WM_MOUSEACTIVATE

WM_MOUSEMOVE

WM_NCHITTEST

WM_NCLBUTTONDBLCLK

WM_NCLBUTTONDOWN

WM_NCLBUTTONUP

WM_NCMBUTTONDBLCLK

WM_NCMBUTTONDOWN

WM_NCMBUTTONUP

WM_NCMOUSEMOVE

WM_NCRBUTTONDBLCLK

WM_NCRBUTTONDOWN

WM_NCRBUTTONUP

WM_RBUTTONDBLCLK

WM_RBUTTONDOWN

WM_RBUTTONUP


Timers Overview

About Timers

A timer is an internal routine that repeatedly measures a specified interval, in milliseconds. Each time the interval called a time-out value elapses, the system notifies the window associated with the timer. Because the accuracy of a timer depends on the system clock rate and how often the application retrieves messages from the message queue, the time-out value is only approximate.

An application written for Microsoft® Windows™ creates a timer by using the SetTimer function. If a window handle is given in this function, the application creates the timer for that window. Then, whenever the time-out value elapses, the system posts a WM_TIMER message to the window. If no window handle is given in the SetTimer function, the application that created the timer must monitor its message queue for WM_TIMER messages and dispatch them to the appropriate window.

A new timer starts timing as soon as it is created. An application can change a timer's time-out value by using SetTimer and can destroy a timer by using the KillTimer function. To use system resources efficiently, applications should destroy timers that are no longer necessary.

Each timer has a unique identifier. When creating a timer, an application can either specify an identifier or have the system create a unique value. The first parameter of a WM_TIMER message contains the identifier of the timer that posted the message.

The following topics discuss Win32 timers:

Terms

Creating a Timer

Destroying a Timer

Example: Creating a Mousetrap

Functions


Creating a Timer

The following code sample uses the SetTimer function to create two timers. The first timer is set for every 10 seconds, the second for every 5 minutes.

/* Set two timers. */

SetTimer(hwnd,             /* handle of main window */

    IDT_TIMER1,            /* timer identifier      */

    10000,                 /* 10-second interval    */

    (TIMERPROC) NULL);     /* no timer callback     */

SetTimer(hwnd,             /* handle of main window */

    IDT_TIMER2,            /* timer identifier      */

    300000,                /* 5-minute interval     */

    (TIMERPROC) NULL);     /* no timer callback     */

To process the WM_TIMER messages generated by these timers, add a WM_TIMER case statement to the window procedure for hwnd.

case WM_TIMER:

    switch (wParam) {

        case IDT_TIMER1:

            .

            . /* Process the 10-second timer. */

            .

            return 0;

        case IDT_TIMER2:

            .

            . /* Process the 5-minute timer. */

            .

            return 0;

    }

An application can also create a timer whose WM_TIMER messages are processed not by the main window procedure but by an application-defined callback function, as in the following code sample, which creates a timer and uses the callback function MyTimerProc to process the timer's WM_TIMER messages.

/* Set the timer. */

SetTimer(hwnd,                /* handle of main window */

    IDT_TIMER3,               /* timer identifier      */

    5000,                     /* 5-second interval     */

    (TIMERPROC) MyTimerProc); /* timer callback        */

The calling convention for MyTimerProc must be based on the Microsoft® Win32™ callback function TimerProc.

If your application creates a timer without specifying a window handle, your application must monitor the message queue for WM_TIMER messages and dispatch them to the appropriate window.

HWND hwndTimer;   /* handle of window for timer messages */

MSG msg;          /* message structure */

    while (GetMessage(&msg, /* message structure                */

            NULL,           /* handle of window receiving msg. */

            NULL,           /* lowest message to examine        */

            NULL))          /* highest message to examine       */

        {

        /* Post WM_TIMER messages to the hwndTimer procedure. */

        if (msg.message == WM_TIMER) {

            msg.hwnd = hwndTimer;

        }

        TranslateMessage(&msg); /* translates virtual-key codes */

        DispatchMessage(&msg);  /* dispatches message to window */

    }


Destroying a Timer

Applications should use the KillTimer function to destroy timers that are no longer necessary. The following example destroys the timers identified by the constants IDT_TIMER1, IDT_TIMER2, and IDT_TIMER3.

/* Destroy the timers. */

KillTimer(hwnd, IDT_TIMER1);

KillTimer(hwnd, IDT_TIMER2);

KillTimer(hwnd, IDT_TIMER3);


Example: Creating a Mousetrap

Sometimes it is necessary to prevent more input while you have a cursor on the screen. One way to accomplish this is to create a special routine that traps mouse input until a specific event occurs. Many developers refer to this routine as "building a mousetrap."

The following code sample uses the SetTimer and KillTimer functions to create a simple mousetrap. SetTimer creates a timer that sends a WM_TIMER message every 10 seconds. Each time the application receives a WM_TIMER message, it records the cursor location. If the current location is the same as the previous location and the application's main window is minimized, the application moves the cursor to the icon. When the application closes, KillTimer stops the timer.

HICON hIcon1;               /* icon handle                       */

POINT ptOld;                /* previous cursor location          */

UINT uResult;               /* SetTimer's return value           */

HINSTANCE hinstance;        /* handle of current instance        */

.

. /* Perform application initialization here. */

.

wc.hIcon = LoadIcon(hinstance, MAKEINTRESOURCE(400));

wc.hCursor = LoadCursor(hinstance, MAKEINTRESOURCE(200));

/* Record the initial cursor position. */

GetCursorPos(&ptOld);

/* Set the timer for the mousetrap. */

uResult = SetTimer(hwnd,             /* handle of main window */

    IDT_MOUSETRAP,                   /* timer identifier      */

    10000,                           /* 10-second interval    */

    (TIMERPROC) NULL);               /* no timer callback     */

if (uResult == 0) {

    ErrorHandler("No timer is available.");

}

LONG APIENTRY MainWndProc(

HWND hwnd,          /* handle of main window  */

UINT message,       /* type of message        */

UINT wParam,        /* additional information */

LONG lParam)        /* additional information */

{

    HDC hdc;        /* handle of device context     */

    POINT pt;       /* current cursor location      */

    RECT rc;        /* location of minimized window */

    switch (message) {

        .

        . /* Process other messages. */

        .

        case WM_TIMER:

            /*

             * If the window is minimized, compare the current

             * cursor position with the one from 10 seconds

             * earlier. If the cursor position has not changed,

             * move the cursor to the icon.

             */

            if (IsIconic(hwnd)) {

                GetCursorPos(&pt);

                if ((pt.x == ptOld.x) && (pt.y == ptOld.y)) {

                    GetWindowRect(hwnd, &rc);

                    SetCursorPos(rc.left, rc.top);

                }

                else {

                    ptOld.x = pt.x;

                    ptOld.y = pt.y;

                }

            }

            return 0;

        case WM_DESTROY:

            /* Destroy the timer. */

            KillTimer(hwnd, IDT_MOUSETRAP);

            PostQuitMessage(0);

            break;

        .

        . /* Process other messages. */

        .

}

Although the following code sample also creates a mousetrap, it processes the WM_TIMER message through the application-defined callback function MyTimerProc, rather than through the application's message queue.

UINT uResult;               /* SetTimer's return value     */

HICON hIcon1;               /* icon handle                 */

POINT ptOld;                /* previous cursor location    */

HINSTANCE hinstance;        /* handle of current instance  */

.

. /* Perform application initialization here. */

.

wc.hIcon = LoadIcon(hinstance, MAKEINTRESOURCE(400));

wc.hCursor = LoadCursor(hinstance, MAKEINTRESOURCE(200));

/* Record the current cursor position. */

GetCursorPos(&ptOld);

/* Set the timer for the mousetrap. */

uResult = SetTimer(hwnd,      /* handle of main window */

    IDT_MOUSETRAP,            /* timer identifier      */

    10000,                    /* 10-second interval    */

    (TIMERPROC) MyTimerProc); /* timer callback        */

if (uResult == 0) {

    ErrorHandler("No timer is available.");

}

LONG APIENTRY MainWndProc(

HWND hwnd,          /* handle of main window  */

UINT message,       /* type of message        */

UINT wParam,        /* additional information */

LONG lParam)        /* additional information */

{

    HDC hdc;        /* handle of device context */

    switch (message) {

        .

        . /* Process other messages. */

        .

        case WM_DESTROY:

            /* Destroy the timer. */

            KillTimer(hwnd, IDT_MOUSETRAP);

            PostQuitMessage(0);

            break;

        .

        . /* Process other messages. */

        .

}

/*

 * MyTimerProc is an application-defined callback function that

 * processes WM_TIMER messages.

 */

VOID CALLBACK MyTimerProc(

    HWND hwnd,        /* handle of window for timer messages */

    UINT message,     /* WM_TIMER message                    */

    UINT idTimer,     /* timer identifier                    */

    DWORD dwTime)     /* current system time                 */

{

    RECT rc;

    POINT pt;

    /*

     * If the window is minimized, compare the current

     * cursor position with the one from 10 seconds earlier.

     * If the cursor position has not changed, move the

     * cursor to the icon.

     */

    if (IsIconic(hwnd)) {

        GetCursorPos(&pt);

        if ((pt.x == ptOld.x) && (pt.y == ptOld.y)) {

            GetWindowRect(hwnd, &rc);

            SetCursorPos(rc.left, rc.top);

        }

        else {

            ptOld.x = pt.x;

            ptOld.y = pt.y;

        }

    }

}


Functions

The following functions are used with timers.

KillTimer

SetTimer

TimerProc


Hooks Overview

About Hooks

A hook is a point in the Microsoft® Windows™ message-handling mechanism where an application can install a subroutine to monitor the message traffic in the system and process certain types of messages before they reach the target window procedure. This topic describes Windows hooks and explains how to use them in a Windows-based application.

The following topics discuss Win32 hooks:

Terms

Hook Chains

Hook Procedures

Hook Types

Installing and Releasing Hook Procedures

Example: Monitoring System Events

Functions


Hook Chains

Windows contains many different types of hooks; each type provides access to a different aspect of the Windows message-handling mechanism. For example, an application can use the WH_MOUSE hook to monitor the message traffic for mouse messages.

Windows maintains a separate hook chain for each type of hook. A hook chain is a list of pointers to special, application-defined callback functions called hook procedures. When a message occurs that is associated with a particular type of hook, Windows passes the message to each hook procedure referenced in the hook chain, one after the other. The action a hook procedure can take depends on the type of hook involved. The hook procedures for some types of hooks can only monitor messages; others can modify messages or stop their progress though the chain, preventing them from reaching the next hook procedure or the destination window.

Hooks tend to slow down the system because they increase the amount of processing the system must perform for each message. A developer should install a hook only when necessary, and remove it as soon as possible.


Hook Procedures

To take advantage of a particular type of hook, the developer provides a hook procedure and uses the SetWindowsHookEx function to install it into the chain associated with the hook. A hook procedure must have the following syntax:

LRESULT CALLBACK HookProc(nCode, wParam, lParam)

int nCode;

WPARAM wParam;

LPARAM lParam;

HookProc is a placeholder for an application-defined name. Because Windows must call the hook procedure, the actual name must be exported by listing it and, optionally, its ordinal value, in the EXPORTS statement of the application's module-definition file.

The nCode parameter is a hook code that the hook procedure uses to determine the action to perform. The value of the hook code depends on the type of the hook; each type has its own characteristic set of hook codes. The values of the wParam and lParam parameters depend on the hook code, but they typically contain information about a message that was sent or posted.

SetWindowsHookEx always installs a hook procedure at the beginning of a hook chain. When an event occurs that is monitored by a particular type of hook, Windows calls the procedure at the beginning of the hook chain associated with the hook. Each hook procedure in the chain determines whether to pass the event to the next procedure. A hook procedure passes an event to the next procedure by calling the CallNextHookEx function.

Note that the hook procedures for some types of hooks can only monitor messages. Windows passes messages to each hook procedure, regardless of whether a particular procedure calls CallNextHookEx.

A hook procedure can be global, monitoring messages for all threads in the system, or it can be thread specific, monitoring messages for only an individual thread. A global hook procedure can be called in the context of any application, so the procedure must be in a separate dynamic-link library (DLL) module. A thread specific hook procedure is called only in the context of the associated thread. If an application installs a hook procedure for one of its own threads, the hook procedure can be in either the same module as the rest of the application's code or in a DLL. If the application installs a hook procedure for a thread of a different application, the procedure must be in a DLL.


Hook Types

Each type of hook enables an application to monitor a different aspect of the Windows message-handling mechanism. The following sections describe the types of hooks available in Windows. For more information about each type of hook, see the description of the appropriate hook procedure in the Microsoft Win32 Programmer's Reference, Volumes 3 and 4.

WH_CALLWNDPROC Hook

The WH_CALLWNDPROC hook enables an application to monitor messages sent to window procedures by the SendMessage function. Windows calls a WH_CALLWNDPROC hook procedure before passing the message to the receiving window procedure.

WH_CBT Hook

Windows calls a WH_CBT hook procedure 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 input focus; or before synchronizing with the system message queue. The value the hook procedure returns determines whether Windows allows or prevents one of these operations. The WH_CBT hook is intended primarily for Windows computer-based training (CBT) applications.

WH_DEBUG Hook

Windows calls a WH_DEBUG hook procedure before calling hook procedures associated with any other hook in the system. An application can use this hook to determine whether to allow the system to call hook procedures associated with other types of hooks.

WH_GETMESSAGE Hook

The WH_GETMESSAGE hook enables an application to monitor messages about to be returned by the GetMessage or PeekMessage function. An application uses the WH_GETMESSAGE hook to monitor mouse and keyboard input and other messages posted to a queue.

WH_JOURNALRECORD Hook

The WH_JOURNALRECORD hook enables an application to monitor and record input events. Typically, an application uses this hook to record a sequence of mouse and keyboard events it can play back later by using the WH_JOURNALPLAYBACK hook. The WH_JOURNALRECORD hook is a global hook--it cannot be used as a thread-specific hook.

WH_JOURNALPLAYBACK Hook

The WH_JOURNALPLAYBACK hook enables an application to insert messages into the system message queue. An application might use this hook to play back a series of mouse and keyboard events recorded earlier by using the WH_JOURNALRECORD hook. Regular mouse and keyboard input is disabled as long as a WH_JOURNALPLAYBACK hook is installed. A WH_JOURNALPLAYBACK hook is a global hook--it cannot be used as a thread-specific hook.

The WH_JOURNALPLAYBACK hook returns a time-out value. This value tells the system how many milliseconds to wait before processing the current message from the playback hook. This enables the hook to control the timing of the events it plays back.

WH_KEYBOARD Hook

The WH_KEYBOARD hook enables an application to monitor message traffic for WM_KEYDOWN and WM_KEYUP messages about to be returned by the GetMessage or PeekMessage function. An application uses the WH_KEYBOARD hook to monitor keyboard input posted to a message queue.

WH_MOUSE Hook

The WH_MOUSE hook enables an application to monitor mouse messages about to be returned by the GetMessage or PeekMessage function. An application uses the WH_MOUSE hook to monitor mouse input posted to a message queue.

WH_MSGFILTER and WH_SYSMSGFILTER Hooks

The WH_MSGFILTER and WH_SYSMSGFILTER hooks enable an application to monitor messages about to be processed by a menu, scroll bar, message box, or dialog box, and to detect when a different window is about to be activated as a result of the user's pressing the ALT+TAB or ALT+ESC key combination. The WH_MSGFILTER hook can monitor only messages passed to a menu, scroll bar, message box, or dialog box created by the application that installed the hook procedure. The WH_SYSMSGFILTER hook monitors such messages for all applications.

The WH_MSGFILTER and WH_SYSMSGFILTER hooks enable an application to perform message filtering during modal loops that is equivalent to the filtering done in the main message loop. For example, an application often examines a new message in the main loop between the time it retrieves the message from the queue and the time it dispatches the message, performing special processing as appropriate. However, during a modal loop, the system retrieves and dispatches messages without allowing an application the chance to filter the messages in its main message loop. If an application installs a WH_MSGFILTER or WH_SYSMSGFILTER hook procedure, the system calls the procedure during the modal loop.

An application can call the WH_MSGFILTER hook directly by calling the CallMsgFilter function. By using this function, the application can use the same code to filter messages during modal loops as it uses in the main message loop. To do so, the application encapsulates the filtering operations in a WH_MSGFILTER hook procedure and calls CallMsgFilter between the calls to the GetMessage and DispatchMessage functions.

while (GetMessage(&msg, (HWND) NULL, 0, 0)) {

    if (!CallMsgFilter(&qmsg, 0))

        DispatchMessage(&qmsg);

}

The last argument of CallMsgFilter is simply passed to the hook procedure; the application can enter any value. The hook procedure, by defining a constant such as MSGF_MAINLOOP, can use this value to determine where the procedure was called from.

WH_SHELL Hook

A Windows shell application can use the WH_SHELL hook to receive important notifications. Windows calls a WH_SHELL hook procedure when the shell application is about to be activated and when a top-level window is created or destroyed.


Installing and Releasing Hook Procedures

You can install a hook procedure by calling the SetWindowsHookEx function and specifying the type of hook calling the procedure, whether the procedure should be associated with all threads or with a particular thread, and a pointer to a procedure entry point.

You must place a global hook procedure in a DLL separate from the application installing the hook procedure. The installing application must have the handle of the DLL module before it can install the hook procedure. The LoadLibrary function, when given the name of the DLL, returns the handle of the DLL module. After you have the handle, you can call the GetProcAddress function to retrieve the address of the hook procedure. Finally, you use SetWindowsHookEx to install the hook procedure address in the appropriate hook chain. SetWindowsHookEx passes the module handle, a pointer to the hook-procedure entry point, and 0 for the thread identifier, indicating that the hook procedure should be associated with all threads in the system. This sequence is shown in the following example.

HOOKPROC hkprcSysMsg;

static HINSTANCE hinstDLL;

static HHOOK hhookSysMsg;

    .

    .

    .

hinstDLL = LoadLibrary((LPCTSTR) "c:\\windows\\sysmsg.dll");

hkprcSysMsg = (HOOKPROC)GetProcAddress(hinstDLL, "SysMessageProc");

hhookSysMsg = SetWindowsHookEx(WH_SYSMSGFILTER,

    hkprcSysMsg, hinstDLL, 0);

    .

    .

    .

You can release a thread-specific hook procedure (remove its address from the hook chain) by calling the UnhookWindowsHookEx function, specifying the handle of the hook procedure to release. Release a hook procedure as soon as your application no longer needs it.

You can release a global hook procedure by using UnhookWindowsHookEx, but this function does not free the DLL containing the hook procedure. This is because global hook procedures are called in the process context of every Windows-based application in the system, causing an implicit call to the LoadLibrary function for all of those processes. Because a call to the FreeLibrary function cannot be made for another process, there is then no way to free the DLL. Windows eventually frees the DLL after all processes explicitly linked to the DLL have either terminated or called FreeLibrary and all processes that called the hook procedure have resumed processing outside the DLL.

An alternative method for installing a global hook procedure is to provide an installation function in the DLL, along with the hook procedure. With this method, the installing application does not need the handle of the DLL module. By linking with the DLL, the application gains access to the installation function. The installation function can supply the DLL module handle and other details in the call to SetWindowsHookEx. The DLL can also contain a function that releases the global hook procedure; the application can call this hook-releasing function when terminating.


Example: Monitoring System Events

The example in this section uses a variety of thread-specific hook procedures to monitor the system for events affecting a thread. It demonstrates how to process events for the following types of hook procedures:

WH_CALLWNDPROC

WH_CBT

WH_DEBUG

WH_GETMESSAGE

WH_KEYBOARD

WH_MOUSE

WH_MSGFILTER

In this example, the user can install and remove a hook procedure by using the menu. When a hook procedure is installed and an event that is monitored by the procedure occurs, the procedure writes information about the event to the client area of the application's main window.

#define NUMHOOKS 7

/* Global variables */

typedef struct _MYHOOKDATA {

    int nType;

    HOOKPROC hkprc;

    HHOOK hhook;

} MYHOOKDATA;

MYHOOKDATA myhookdata[NUMHOOKS];

LONG APIENTRY MainWndProc(hwndMain, uMsg, wParam, lParam)

HWND hwndMain;

UINT uMsg;

UINT wParam;

LONG lParam;

{

    static BOOL afHooks[NUMHOOKS];

    int index;

    static HMENU hmenu;

    switch (uMsg) {

        case WM_CREATE:

            /* Save the menu handle. */

            hmenu = GetMenu(hwndMain);

            /*

             * Initialize structures with hook data. The menu-item

             * identifiers are defined as 0 through 6 in the

             * header file. They can be used to identify array

             * elements both here and during the WM_COMMAND

             * message.

             */

            myhookdata[IDM_CALLWNDPROC].nType = WH_CALLWNDPROC;

            myhookdata[IDM_CALLWNDPROC].hkprc = CallWndProc;

            myhookdata[IDM_CBT].nType = WH_CBT;

            myhookdata[IDM_CBT].hkprc = CBTProc;

            myhookdata[IDM_DEBUG].nType = WH_DEBUG;

            myhookdata[IDM_DEBUG].hkprc = DebugProc;

            myhookdata[IDM_GETMESSAGE].nType = WH_GETMESSAGE;

            myhookdata[IDM_GETMESSAGE].hkprc = GetMsgProc;

            myhookdata[IDM_KEYBOARD].nType = WH_KEYBOARD;

            myhookdata[IDM_KEYBOARD].hkprc = KeyboardProc;

            myhookdata[IDM_MOUSE].nType = WH_MOUSE;

            myhookdata[IDM_MOUSE].hkprc = MouseProc;

            myhookdata[IDM_MSGFILTER].nType = WH_MSGFILTER;

            myhookdata[IDM_MSGFILTER].hkprc = MessageProc;

            /* Initialize all flags in the array to FALSE. */

            memset(afHooks, FALSE, sizeof(afHooks));

            return 0;

        case WM_COMMAND:

            switch (LOWORD(wParam)) {

                /*

                 * The user selected a hook command from the menu.

                 */

                case IDM_CALLWNDPROC:

                case IDM_CBT:

                case IDM_DEBUG:

                case IDM_GETMESSAGE:

                case IDM_KEYBOARD:

                case IDM_MOUSE:

                case IDM_MSGFILTER:

                    /*

                     * Use the menu-item identifier as an index

                     * into the array of structures with hook data.

                     */

                    index = LOWORD(wParam);

                    /*

                     * If the selected type of hook procedure isn't

                     * installed yet, install it and check the

                     * associated menu item.

                     */

                    if (!afHooks[index]) {

                        myhookdata[index].hhook = SetWindowsHookEx(

                            myhookdata[index].nType,

                            myhookdata[index].hkprc,

                            (HINSTANCE) NULL, GetCurrentThreadId());

                        CheckMenuItem(hmenu, index,

                            MF_BYCOMMAND | MF_CHECKED);

                        afHooks[index] = TRUE;

                    }

                    /*

                     * If the selected type of hook procedure is

                     * already installed, remove it and remove the

                     * check mark from the associated menu item.

                     */

                    else {

                        UnhookWindowsHookEx(myhookdata[index].hhook);

                        CheckMenuItem(hmenu, index,

                            MF_BYCOMMAND | MF_UNCHECKED);

                        afHooks[index] = FALSE;

                    }

                default:

                    return (DefWindowProc(hwndMain, uMsg, wParam,

                        lParam));

            }

            break;

            .

            . /* Process other messages. */

            .

        default:

            return DefWindowProc(hwndMain, uMsg, wParam, lParam);

    }

    return NULL;

}

/****************************************************************

  WH_CALLWNDPROC hook procedure

 ****************************************************************/

LRESULT CALLBACK CallWndProc(nCode, wParam, lParam)

int nCode;

WPARAM wParam;

LPARAM lParam;

{

    CHAR szCWPBuf[256];

    CHAR szMsg[16];

    HDC hdc;

    static int c = 0;

    int cch;

    if (nCode < 0)  /* do not process message */

        return CallNextHookEx(myhookdata[CALLWNDPROC].hhook, nCode,

                wParam, lParam);

    /*

     * Call an application-defined function that converts a message

     * constant to a string and copies it to a buffer.

     */

    LookUpTheMessage((PMSG) lParam, szMsg);

    hdc = GetDC(hwndMain);

    switch (nCode) {

        case HC_ACTION:

            cch = wsprintf(szCWPBuf,

               "CALLWNDPROC - tsk: %ld, msg: %s, %d times   ",

                wParam, szMsg, c++);

            TextOut(hdc, 2, 15, szCWPBuf, cch);

            break;

        default:

            break;

    }

    ReleaseDC(hwndMain, hdc);

    return CallNextHookEx(myhookdata[CALLWNDPROC].hhook, nCode,

        wParam, lParam);

}

/****************************************************************

  WH_GETMESSAGE hook procedure

 ****************************************************************/

LRESULT CALLBACK GetMsgProc(nCode, wParam, lParam)

int nCode;

WPARAM wParam;

LPARAM lParam;

{

    CHAR szMSGBuf[256];

    CHAR szRem[16];

    CHAR szMsg[16];

    HDC hdc;

    static int c = 0;

    int cch;

    if (nCode < 0) /* do not process message */

        return CallNextHookEx(myhookdata[GETMESSAGE].hhook, nCode,

            wParam, lParam);

    switch (nCode) {

        case HC_ACTION:

            switch (wParam) {

                case PM_REMOVE:

                    lstrcpy(szRem, "PM_REMOVE");

                    break;

                case PM_NOREMOVE:

                    lstrcpy(szRem, "PM_NOREMOVE");

                    break;

                default:

                    lstrcpy(szRem, "Unknown");

                    break;

            }

            /*

             * Call an application-defined function that converts a

             * message constant to a string and copies it to a

             * buffer.

             */

            LookUpTheMessage((PMSG) lParam, szMsg);

            hdc = GetDC(hwndMain);

            cch = wsprintf(szMSGBuf,

                "GETMESSAGE - wParam: %s, msg: %s, %d times   ",

                szRem, szMsg, c++);

            TextOut(hdc, 2, 35, szMSGBuf, cch);

            break;

        default:

            break;

    }

    ReleaseDC(hwndMain, hdc);

    return CallNextHookEx(myhookdata[GETMESSAGE].hhook, nCode,

        wParam, lParam);

}

/****************************************************************

  WH_DEBUG hook procedure

 ****************************************************************/

LRESULT CALLBACK DebugProc(nCode, wParam, lParam)

int nCode;

WPARAM wParam;

LPARAM lParam;

{

    CHAR szBuf[128];

    HDC hdc;

    static int c = 0;

    int cch;

    if (nCode < 0)  /* do not process message */

        return CallNextHookEx(myhookdata[DEBUG].hhook, nCode,

            wParam, lParam);

    hdc = GetDC(hwndMain);

    switch (nCode) {

        case HC_ACTION:

            cch = wsprintf(szBuf,

                "DEBUG - nCode: %d, tsk: %ld, %d times   ",

                nCode,wParam, c++);

            TextOut(hdc, 2, 55, szBuf, cch);

            break;

        default:

            break;

    }

    ReleaseDC(hwndMain, hdc);

    return CallNextHookEx(myhookdata[DEBUG].hhook, nCode, wParam,

        lParam);

}

/****************************************************************

  WH_CBT hook procedure

 ****************************************************************/

LRESULT CALLBACK CBTProc(nCode, wParam, lParam)

int nCode;

WPARAM wParam;

LPARAM lParam;

{

    CHAR szBuf[128];

    CHAR szCode[128];

    HDC hdc;

    static int c = 0;

    int cch;

    if (nCode < 0)  /* do not process message */

        return CallNextHookEx(myhookdata[CBT].hhook, nCode, wParam,

            lParam);

    hdc = GetDC(hwndMain);

    switch (nCode) {

        case HCBT_ACTIVATE:

            lstrcpy(szCode, "HCBT_ACTIVATE");

            break;

        case HCBT_CLICKSKIPPED:

            lstrcpy(szCode, "HCBT_CLICKSKIPPED");

            break;

        case HCBT_CREATEWND:

            lstrcpy(szCode, "HCBT_CREATEWND");

            break;

        case HCBT_DESTROYWND:

            lstrcpy(szCode, "HCBT_DESTROYWND");

            break;

        case HCBT_KEYSKIPPED:

            lstrcpy(szCode, "HCBT_KEYSKIPPED");

            break;

        case HCBT_MINMAX:

            lstrcpy(szCode, "HCBT_MINMAX");

            break;

        case HCBT_MOVESIZE:

            lstrcpy(szCode, "HCBT_MOVESIZE");

            break;

        case HCBT_QS:

            lstrcpy(szCode, "HCBT_QS");

            break;

        case HCBT_SETFOCUS:

            lstrcpy(szCode, "HCBT_SETFOCUS");

            break;

        case HCBT_SYSCOMMAND:

            lstrcpy(szCode, "HCBT_SYSCOMMAND");

            break;

        default:

            lstrcpy(szCode, "Unknown");

            break;

    }

    cch = wsprintf(szBuf, "CBT - nCode: %s, tsk: %ld, %d times   ",

        szCode, wParam, c++);

    TextOut(hdc, 2, 75, szBuf, cch);

    ReleaseDC(hwndMain, hdc);

    return CallNextHookEx(myhookdata[CBT].hhook, nCode, wParam,

        lParam);

}

/****************************************************************

  WH_MOUSE hook procedure

 ****************************************************************/

LRESULT CALLBACK MouseProc(nCode, wParam, lParam)

int nCode;

WPARAM wParam;

LPARAM lParam;

{

    CHAR szBuf[128];

    CHAR szMsg[16];

    HDC hdc;

    static int c = 0;

    int cch;

    if (nCode < 0)  /* do not process the message */

        return CallNextHookEx(myhookdata[MOUSE].hhook, nCode,

            wParam, lParam);

    /*

     * Call an application-defined function that converts a message

     * constant to a string and copies it to a buffer.

     */

    LookUpTheMessage((PMSG) lParam, szMsg);

    hdc = GetDC(hwndMain);

    cch = wsprintf(szBuf,

        "MOUSE - nCode: %d, msg: %s, x: %d, y: %d, %d times   ",

        nCode, szMsg, LOWORD(lParam), HIWORD(lParam), c++);

    TextOut(hdc, 2, 95, szBuf, cch);

    ReleaseDC(hwndMain, hdc);

    return CallNextHookEx(myhookdata[MOUSE].hhook, nCode, wParam,

        lParam);

}

/****************************************************************

  WH_KEYBOARD hook procedure

 ****************************************************************/

LRESULT CALLBACK KeyboardProc(nCode, wParam, lParam)

int nCode;

WPARAM wParam;

LPARAM lParam;

{

    CHAR szBuf[128];

    HDC hdc;

    static int c = 0;

    int cch;

    if (nCode < 0)  /* do not process message */

        return CallNextHookEx(myhookdata[KEYBOARD].hhook, nCode,

            wParam, lParam);

    hdc = GetDC(hwndMain);

    cch = wsprintf(szBuf, "KEYBOARD - nCode: %d, vk: %d, %d times ",

        nCode, wParam, c++);

    TextOut(hdc, 2, 115, szBuf, cch);

    ReleaseDC(hwndMain, hdc);

    return CallNextHookEx(myhookdata[KEYBOARD].hhook, nCode, wParam,

        lParam);

}

/****************************************************************

  WH_MSGFILTER hook procedure

 ****************************************************************/

LRESULT CALLBACK MessageProc(nCode, wParam, lParam)

int nCode;

WPARAM wParam;

LPARAM lParam;

{

    CHAR szBuf[128];

    CHAR szMsg[16];

    CHAR szCode[32];

    HDC hdc;

    static int c = 0;

    int cch;

    if (nCode < 0)  /* do not process message */

        return CallNextHookEx(myhookdata[MSGFILTER].hhook, nCode,

            wParam, lParam);

    switch (nCode) {

        case MSGF_DIALOGBOX:

            lstrcpy(szCode, "MSGF_DIALOGBOX");

            break;

        case MSGF_MENU:

            lstrcpy(szCode, "MSGF_MENU");

            break;

        case MSGF_SCROLLBAR:

            lstrcpy(szCode, "MSGF_SCROLLBAR");

            break;

        case MSGF_NEXTWINDOW:

            lstrcpy(szCode, "MSGF_NEXTWINDOW");

            break;

        default:

            wsprintf(szCode, "Unknown: %d", nCode);

            break;

    }

    /*

     * Call an application-defined function that converts a message

     * constant to a string and copies it to a buffer.

     */

    LookUpTheMessage((PMSG) lParam, szMsg);

    hdc = GetDC(hwndMain);

    cch = wsprintf(szBuf,

        "MSGFILTER  nCode: %s, msg: %s, %d times    ",

        szCode, szMsg, c++);

    TextOut(hdc, 2, 135, szBuf, cch);

    ReleaseDC(hwndMain, hdc);

    return CallNextHookEx(myhookdata[MSGFILTER].hhook, nCode,

        wParam, lParam);

}


Functions

Following are the Windows functions and the message used with hooks.

Functions

CallMsgFilter

CallNextHookEx

CallWndProc

CBTProc

DebugProc

DefHookProc

GetMsgProc

JournalPlaybackProc

JournalRecordProc

KeyboardProc

MessageProc

MouseProc

SetWindowsHook

SetWindowsHookEx

ShellProc

SysMsgProc

UnhookWindowsHook

UnhookWindowsHookEx

Message

WM_QUEUESYNC


Controls Overview

About Controls

In Microsoft® Windows™, a control is a child window an application uses in conjunction with another window to carry out simple input and output (I/O) tasks. Controls are most often used within dialog boxes, but they can also be used in other windows. Controls within dialog boxes provide the user with the means to type text, choose options, and direct a dialog box to complete its action. Controls in other windows provide a variety of services, such as letting the user choose commands, view status, and view and edit text.

Like other windows, each control belongs to a window class, either predefined or application defined. The window class and the corresponding window procedure define the properties of the control, its appearance, behavior, and purpose. An application can create controls individually by specifying the name of the window class when calling the CreateWindow or CreateWindowEx function. An application can also direct Windows to create controls for a dialog box by specifying the controls in the dialog box template.

Controls are child windows. When Windows creates controls for a dialog box, each control is the child of the dialog box. When an application creates a control, the control is the child of a window identified by the application. This relationship is important because a control sends messages, called notification messages, to its parent window when events, such as input from the user, occur in the control. The application relies on these notification messages to determine what action the user wants the application to take.

Because controls are windows, an application can manipulate them by using the window-management functions, such as the ShowWindow and EnableWindow functions. If the window class for a control supports control messages, an application can also manipulate a control of that class by using the SendMessage function to send these messages to the control. The purpose and function of each control message is specific to the window class and is defined by the control's window procedure.

The following topics discuss controls:

Terms

Predefined Controls

Custom Controls


Predefined Controls

Windows provides several predefined window classes for controls. Controls belonging to these window classes are called predefined controls. An application creates a predefined control of a particular type by specifying the appropriate window class name in either the CreateWindow function or the dialog box template. Following are the predefined window classes.

Name	Description

BUTTON	Creates button controls. These controls typically notify the parent window when the user chooses the control.

LISTBOX	Creates list boxes. These controls display a list from which the user can select one or more items.

EDIT	Creates edit controls. These controls let the user view and edit text.

COMBOBOX	Creates combo boxes. These controls are a combination of list boxes and edit controls, letting the user choose and edit items.

SCROLLBAR	Creates scroll bar controls. These controls let the user choose the direction and distance to scroll information in a related window.

STATIC	Creates static controls. These controls often act as labels for other controls.

Each predefined window class has a corresponding set of control styles that enable an application to vary the appearance and behavior of the controls it creates. For example, the BUTTON class supports styles to create push buttons, radio buttons, check boxes, and group boxes. An application specifies the style when creating the control.

Each predefined window class has a corresponding set of notification and control messages. Applications rely on the notification messages to determine when the user has provided input to the controls. For example, a push button sends a BN_CLICKED message to the parent window when the user chooses the button. Applications use the control messages to retrieve information from the controls and to manipulate the appearance and behavior of the controls. For example, an application can send a BM_GETCHECK message to a check box to determine whether it currently contains a check mark.

Most applications make extensive use of predefined controls in dialog boxes and other windows. Because predefined controls offer many capabilities, a full discussion of each is beyond the scope of this topic. For more information about the predefined controls, see the individual chapters for each window class following this topic.


Custom Controls

Applications can create custom controls to carry out tasks not supported by predefined controls. Windows provides the following ways to create custom controls:

Use owner-drawn buttons, list boxes, and combo boxes.

Subclass an existing control-window class.

Register and implement from scratch an application-defined window class.

Buttons, list boxes, and combo boxes have owner-drawn styles available that direct the control to send a message to the parent window whenever the control must be drawn. This feature permits an application to alter the appearance of a control. For buttons, the owner-drawn style affects how the system draws the entire control. For list boxes and combo boxes, the parent window draws the items within the control, and the control draws its own outline. For example, an application can customize a list box so that it displays a small bitmap beside each item in the list.

An application can designate list boxes, combo boxes, and buttons as owner-drawn controls by creating them with the appropriate style. When a control has the owner-drawn style, Windows handles the user's interaction with the control as usual, performing such tasks as detecting when a user has chosen a button and notifying the button's owner of the event. However, because the control is owner drawn, the parent window of the control is responsible for the visual appearance of the control. For more information about owner-drawn controls, see the individual chapters for buttons, list boxes, and combo boxes.

Subclassing an existing control is another way to create a custom control. The subclass procedure can alter selected behaviors of the control by processing those messages that affect the selected behaviors. All other messages pass to the original window procedure for the control. For example, an application can display a small bitmap next to the text in a read-only, single-line edit control by subclassing the control and processing the WM_PAINT message. For more information about subclassing, see Window Classes.

Although an application may subclass a predefined control, it relies on the window procedure of the control to provide all other aspects of the control's behavior. For more information about a control's behavior, see the individual chapters for the predefined controls.

An application can create custom controls by registering an application-defined window class and specifying the name of the window class in the CreateWindow or CreateWindowEx function or in the dialog box template. The process for registering an application-defined window class for a custom control is the same as for registering a class for an ordinary window. Each class must have a unique name, a corresponding window procedure, and other information.

At a minimum, the window procedure draws the control. If an application uses the control to let the user type information, the window procedure also processes input messages from the keyboard and mouse and sends notification messages to the parent window. In addition, if the control supports control messages, the window procedure processes messages sent to it by the parent window or other windows. For example, controls often process the WM_GETDLGCODE message sent by dialog boxes to direct a dialog box to process keyboard input in a given way.

Notification Messages

A control should send a notification message to its parent window to notify the parent about user input or changes to the control. The notification message is a WM_COMMAND message that includes a control identifier and a notification code identifying the nature of the event. A control identifier is a unique number the application uses to identify the control sending the message. The application sets the identifier for a control when it creates the control. The application specifies the identifier either in the hMenu parameter of the CreateWindow or CreateWindowEx function or in the id member of the dialog box template.

Because the control does not set the control identifier, the control must retrieve the identifier before it can send notification messages. A control must use the GetDlgCtrlID function to retrieve its own control identifier. Although the control identifier is specified as the menu handle when the control is created, the GetMenu function cannot be used to retrieve the identifier. Alternatively, a control can retrieve the identifier from the hMenu member in the CREATESTRUCT structure while processing the WM_CREATE message.

Control Messages

A parent window or other windows send control messages to direct a control to carry out specific tasks. The window procedure processes these messages and carries out the requested action.

Control messages can be predefined or application defined. Windows has several predefined messages, such as WM_GETTEXT and WM_GETDLGCODE, that it sends to controls. These messages typically correspond to window-management functions that carry out actions on windows. In general, the window procedure for an application-defined control should process any predefined control message in the following table if the message affects the operation of the control.

Message	Recommendation

WM_GETDLGCODE	Process if the control uses the ENTER, ESC, TAB, or direction keys. The IsDialogMessage function sends this message to controls in a dialog box to determine whether to process the keys or pass them to the control.

WM_GETFONT	Process if the WM_SETFONT message is also processed.

WM_GETTEXT	Process if the control text is not the same as the title specified by the CreateWindow or CreateWindowEx function.

WM_GETTEXTLENGTH	Process if the control text is not the same as the title specified by the CreateWindow or CreateWindowEx function.

WM_KILLFOCUS	Process if the control displays a caret, a focus rectangle, or another item to indicate that it has the input focus.

WM_SETFOCUS	Process if the control displays a caret, a focus rectangle, or another item to indicate that it has the input focus.

WM_SETTEXT	Process if the control text is not the same as the title specified by the CreateWindow or CreateWindowEx function.

WM_SETFONT	Process if the control displays text. Windows sends this message when creating a dialog box that has the DS_SETFONT style.

Application-defined control messages are specific to the given control and must be explicitly sent to the control by using a SendMessage or SendDlgItemMessage function. The numeric value for each message must be unique and must not conflict with the values of other window messages. To ensure that application-defined message values do not conflict, an application should create each value by adding a unique number to the WM_USER value.

Messages

Following are the messages used with controls.

WM_GETFONT

WM_SETFONT

WM_SETTEXT


Buttons Overview

About Buttons

Microsoft® Windows™ provides dialog boxes and controls to support communication between an application and the user. A button is a control the user can turn on or off to provide input to an application. There are several types of buttons and, within each type, one or more styles to distinguish among buttons of the same type. The user turns a button on or off by selecting it using the mouse or keyboard. Selecting a button typically changes its visual appearance and state (from checked to unchecked, for example). Windows, the button, and the application cooperate in changing the button's appearance and state. A button can send messages to its parent window, and a parent window can send messages to a button. Some buttons are painted by Windows, some by the application. Buttons can be used alone or in groups and can appear with or without a label. They belong to the BUTTON window class.

Although an application can use buttons in overlapped, pop-up, and child windows, they are designed for use in dialog boxes, where Windows standardizes their behavior. If an application uses buttons outside dialog boxes, it increases the risk that the application may behave in a nonstandard fashion. Applications typically either use buttons in dialog boxes or use window subclassing to create customized buttons.

The following topics discuss buttons:

Terms

Button Types and Styles

Button States

Messages from Buttons

Messages to Buttons

Buttons and Colors

Default Button Behavior

Creating a Button Outside a Dialog Box

Using Buttons That Are Not Owner-Drawn

Using Owner-Drawn Buttons

Functions and Messages


Button Types and Styles

Windows provides five kinds of buttons: push buttons, check boxes, radio buttons, group boxes, and owner-drawn buttons. Each type has one or more styles.

Push Buttons

A push button is a round-cornered rectangle containing application-defined text (label) that specifies what the button does when the user selects it. The push button includes the following styles: push button and default push button, defined by the constants BS_PUSHBUTTON and BS_DEFPUSHBUTTON, respectively. A standard push button is typically used to start an operation. It receives the keyboard focus when the user selects it. A default push button, on the other hand, is typically used to cancel an operation. It receives the keyboard focus when it is created (thus, becoming the default).

When the user selects a push button (of either style), it receives the keyboard focus from Windows, which sends the button's parent window a WM_COMMAND message containing the BN_CLICKED notification code. In response, the parent window typically sets the button's highlight state to highlighted, closes the dialog box, and starts (or cancels) the operation.

The following figure shows both a standard and a default push button.

The labels on push buttons are always centered on the button.

Check Boxes

A check box consists of a square box and application-defined text (label) that specifies a choice the user can make by selecting the button. Applications typically display check boxes in a group box to permit the user to choose from a set of related but independent options. For example, an application might present a group of check boxes from which the user can select error conditions that produce warning beeps.

A check box can be one of four styles: check box, automatic check box, three-state check box, and automatic three-state check box, which are defined by the constants BS_CHECKBOX, BS_AUTOCHECKBOX, BS_3STATE, and BS_AUTO3STATE, respectively. All four styles can assume two check states: checked (an X inside the box) or unchecked (no X). In addition, a three-state check box can assume a disabled state (the box is grayed). Repeatedly selecting a standard or automatic check box toggles it from checked to unchecked and back again. Repeatedly selecting a three-state check box toggles it from checked to unchecked to grayed and back again.

The following figure shows all three states of a three-state check box.

When the user selects a check box (of any style), the check box receives the keyboard focus from Windows, which sends the check box's parent window a WM_COMMAND message containing the BN_CLICKED notification code. The parent window doesn't acknowledge this message if it comes from an automatic check box or automatic three-state check box, because Windows automatically sets the check state and the highlight state for those styles. But the parent window must acknowledge the message if it comes from a check box or three-state check box because the parent window, not Windows, is responsible for setting the check state and highlight state for those styles. Regardless of the check box style, Windows automatically repaints the check box once its state is changed.

By default, a label is placed on the right of a check box. An application can place labels on the left instead by using the left-text style (BS_LEFTTEXT). The left-text style is only a style, not a distinct button type.

Radio Buttons

A radio button consists of a round button and application-defined text (a label) that specifies a choice the user can make by selecting the button. An application typically uses radio buttons in a group box to permit the user to choose from a set of related but mutually exclusive options. For example, the application might present a group of radio buttons from which the user can select a format preference for text selected in the client area. The user could select a left-aligned, right-aligned, or centered format by selecting the corresponding radio button. Typically, the user can select only one option at a time from a set of radio buttons.

The radio button includes the following styles: radio button and automatic radio button, defined by the constants BS_RADIOBUTTON and BS_AUTORADIOBUTTON, respectively. Both styles can assume two check states: checked (a black dot on the button) or unchecked (no dot on the button). Repeatedly selecting a check box (standard or automatic) toggles it from checked to unchecked and back again. Repeatedly selecting a three-state check box (standard or automatic) toggles it from checked to unchecked to grayed and back again.

The following figure shows both states of a radio button.

When the user selects either state, the radio button receives the keyboard focus from Windows, which sends the button's parent window a WM_COMMAND message containing the BN_CLICKED notification code. The parent window doesn't acknowledge this message if it comes from an automatic radio button because Windows automatically sets the check state and the highlight state for that style. But the parent window should acknowledge the message if it comes from a radio button because the parent window, not Windows, is responsible for setting the check state and highlight state for that style. Regardless of the radio button style, Windows automatically repaints the button as its state changes.

When the user selects an automatic radio button, Windows automatically removes the highlighting from any previously selected automatic radio button within the same group. The same behavior is available for standard radio buttons by using the WS_GROUP style.

By default, a label is placed on the right of a radio button. An application can place labels on the left instead by using the left-text style (BS_LEFTTEXT). The left-text style is only a style, not a distinct button type.

Owner-Drawn Buttons

Unlike radio buttons, an owner-drawn button is painted by the application, not Windows, and has no predefined appearance or usage. Its purpose is to provide a button whose appearance and behavior are defined by the application alone. There is only one owner-drawn button style: BS_OWNERDRAW.

When the user selects an owner-drawn button, Windows sends the button's parent window a WM_COMMAND message containing the BN_CLICKED notification code, just as it does for a button that is not owner-drawn. The application must respond appropriately.

Group Boxes

A group box is a rectangle that surrounds a set of controls, such as check boxes or radio buttons, with application-defined text (label) in its upper-left corner. The sole purpose of a group box is to organize controls related by a common purpose (usually indicated by the label). The group box has only one style, defined by the constant BS_GROUPBOX.

The following figure shows a group box containing two radio buttons.

Because a group box cannot be selected, it has no check state, focus state, highlight state, or enabled state. An application cannot send messages to a group box.

Button Styles

Many developers create dialog boxes by using stand-alone tools not requiring them to specify button styles. However, if an application creates a button by using the CreateWindow or CreateWindowEx function, the following table of constants can be used to define the button style.

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

BS_AUTOCHECKBOX	Creates a button that is the same as a check box, except that an X appears in the check box when the user selects the box; the X disappears the next time the user selects the box.

BS_AUTORADIOBUTTON	Creates a button that is the same as a radio button, except that when the user selects it, the button automatically highlights itself and removes the selection from any other buttons in the same group.

BS_CHECKBOX	Creates a small empty square, with text displayed to its right, unless this style is combined with the BS_LEFTTEXT style.

BS_DEFPUSHBUTTON	Creates a button that has a heavy black border. The user can select this button by pressing the ENTER key. 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.

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_PUSHBOX	Unsupported. Applications should use BS_PUSHBUTTON instead.

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 that has text displayed to its right, unless this style is combined with the BS_LEFTTEXT style. Use radio buttons for groups of related but mutually exclusive choices.

BS_USERBUTTON	Obsolete. Applications should use BS_OWNERDRAW instead.


Button States

This section discusses how selecting a button changes its state and how the application should respond.

Button Selection

The user can select a button in three ways: by clicking it with the mouse, by tabbing to it and then pressing the ENTER key, or (if the button is part of a group defined by the WS_GROUP style) by tabbing to the selected button in the group and using the arrow keys to move within that group. The two tabbing methods are part of the predefined keyboard interface provided by Windows.

Selecting a button typically causes the following events:

Windows gives the button the keyboard focus.

The button sends its parent window a message to notify it of the selection.

The parent window (or Windows) sends the button a message to change its state.

The parent window (or Windows) repaints the button to reflect its new state.

The following paragraphs discuss these events and button states in greater detail.

Elements of a Button State

A button's state can be characterized by its focus state, highlight state, check state, and enabled state. The focus state applies to a check box, radio button, push button, or owner-drawn button. A button receives the keyboard focus when the user selects it and loses the focus when the user selects another button. Only one button can have the keyboard focus at a time. For example, when one radio button in a group receives the focus, the previously selected radio button in the group loses it, to preserve the mutually exclusive nature of radio buttons.

The highlight state applies to a check box, radio button, push button, or owner-drawn button. A button is highlighted when it receives the keyboard focus and loses its highlighting when it loses the focus. Typically, a highlighted button surrounds its text with a dotted line and has a heavy dark border. Windows automatically changes the highlight state for an automatic button, but the application must change the highlight state for a non-automatic button.

The check state applies to a check box, radio button, or three-state check box, but does not apply to other buttons. The state can be checked, unchecked, or (for three-state check boxes) disabled. A check box is checked when it contains an X, and is unchecked when it does not. A radio button is checked when it contains a black dot, and is unchecked when it does not. A three-state check box is checked when it contains an X, unchecked when it does not, and is disabled when it is grayed. Windows changes the check state of an automatic button automatically, but the application must change the check state of a non-automatic button.

The enabled state applies to a standard or automatic three-state check box, but does not apply to other buttons. The state can be enabled or disabled.

Changes to a Button State

When the user selects a button, it is generally necessary to change one or more of the button's state elements. Windows automatically changes the focus state for all button types and the highlight, check, and enabled states for all automatic buttons, but the application must make all other state changes, taking into account the button's type, style, and current state. The following list shows the state elements that must be changed for each button type:

A push button must change the highlight state but not the check state or the enabled state, because push buttons cannot be checked or disabled.

A check box must change the check state, the highlight state, and the enabled state for three-state check boxes.

A radio button must change the check state and the highlight state, but not the enabled state (because radio buttons cannot be disabled). It may also be necessary to change other radio buttons in the same group to ensure the mutually exclusive nature of radio buttons.

Because the state of an owner-drawn button is application dependent, what the application must change in the button can vary. No elements of a group box must be changed, because users cannot select group boxes.

An application can determine a button's state by sending it a BM_GETCHECK or BM_GETSTATE message; the application can set a button's state by sending it a BM_SETCHECK or BM_SETSTATE message.


Notification Messages from Buttons

When the user selects a button, its state changes, and the button sends notification messages to its parent window. For example, a push button control sends the BN_CLICKED notification message whenever the user chooses the button. In all cases, the low word of the wParam parameter contains the control identifier, the high word of wParam contains the notification code, and the lParam parameter contains the control window handle.

Portability Issue:	In Windows® NT™, the placement of the notification code in a notification message has moved from the lParam parameter to the wParam parameter. To accommodate this change in placement, when porting your Windows 3.x-based application to Windows NT, you must modify the code that processes notification messages.

Both the message and the parent window's response depend on the type, style, and current state of the button. Following are the button notification messages an application should monitor and process.

Message	Description

BN_CLICKED	The user clicked a button.

BN_DISABLE	A button is disabled.

BN_DOUBLECLICKED	The user double-clicked a button.

BN_HILITE	The user highlighted a button.

BN_PAINT	The button should be painted.

BN_UNHILITE	The highlight should be removed.

For automatic buttons, the operating system performs disabling, highlighting, unhighlighting, and painting. In this case, the application typically processes only the BN_CLICKED and BN_DOUBLECLICKED notification messages. For buttons that are not automatic, the application typically responds to the notification message by sending a message to change the state of the button. For information about sending messages to buttons, see Messages to Buttons.

When the user selects an owner-drawn button, the button sends its parent window a WM_DRAWITEM message containing the identifier of the control to be drawn and information about its dimensions and state. For more information about this message, see Using Owner-Drawn Buttons.


Messages to Buttons

A parent window can send messages to a button in an overlapped or child window by using the SendMessage function, or it can send messages to a button in a dialog box by using the SendDlgItemMessage, CheckDlgButton, CheckRadioButton, and IsDlgButtonChecked functions.

An application can use the BM_GETCHECK message to retrieve the check state of two-state buttons (check boxes, automatic check boxes, radio buttons, and automatic radio buttons). An application can also use the BM_GETSTATE message to retrieve the button's current states (the check state, highlight state, and focus state). It retrieves the check state of a three-state check box or the focus or highlight state of a button. To get information about a specific state, use a bitmask on the returned state value.

The BM_SETCHECK message sets the check state of a check box or radio button; the message returns zero. The BM_SETSTATE message sets the highlight state of a button; this message also returns zero. The BM_SETSTYLE message changes the style of a button. It is designed for changing button styles within a type (for example, changing a check box to an automatic check box). It is not designed for changing between types (for example, changing a check box to a push button). An application should not change a button from one type to another.

An application can also use the DM_GETDEFID message to retrieve the identifier of the default push button control. An application can use the DM_SETDEFID message to set the default push button for a dialog box.

Calling the CheckDlgButton or CheckRadioButton function is equivalent to sending a BM_SETCHECK message. Calling the IsDlgButtonChecked function is equivalent to sending a BM_GETCHECK message.


Button Color Messages

Windows provides default color values for buttons. The system sends a WM_CTLCOLORBTN message to a button's parent window before the button is drawn. This message contains a handle of the button's device context and a handle of the child window. The parent window can use these handles to change the button's text and background colors. The following table shows the default button-color values.

Value	Element colored

COLOR_BTNFACE	Button faces.

COLOR_BTNHIGHLIGHT	Highlight area (the top and left edges) of a button.

COLOR_BTNSHADOW	Shadow area (the bottom and right edges) of a button.

COLOR_BTNTEXT	Regular (non-gray) text in buttons.

COLOR_GRAYTEXT	Disabled (gray) text in buttons. This color is set to 0 if the current display driver does not support a solid gray color.

COLOR_WINDOW	Window backgrounds.

COLOR_WINDOWFRAME	Window frames.

COLOR_WINDOWTEXT	Text in windows.

An application can retrieve the default values for these colors by calling the GetSysColor function, or set the values by calling the SetSysColors function.

Portability Issue:	In Windows NT, the WM_CTLCOLOR message has been replaced by the set of control-color messages. When porting your Windows 3.x-based application to Windows NT, you must modify any code that processes the WM_CTLCOLOR message.


Default Message Processing

The window procedure for the predefined button control window class carries out default processing for all messages that the button control procedure does not process. When the button control procedure returns FALSE for any message, the predefined window procedure checks the messages and carries out the default actions listed in the following table.

Message	Default action

BM_GETCHECK	Returns the check state of the button.

BM_GETSTATE	Returns the current state of the button.

BM_SETCHECK	Sets the check mark for all styles of radio buttons and check boxes. If the wParam parameter is greater than zero for radio buttons, the button is given the WS_TABSTOP style.

BM_SETSTATE	Highlights or unhighlights the button. For owner-drawn buttons, a WM_DRAWITEM message is sent to the parent window if the state of the button has changed.

BM_SETSTYLE	Sets the button style. If the low word of the lParam parameter is TRUE, the button is redrawn.

WM_CHAR	Checks a check box or automatic check box when the user presses the + or = keys. Removes the check mark from a check box or automatic check box when the user presses the - key.

WM_ENABLE	Paints the button.

WM_ERASEBKGND	Erases the background for owner-drawn buttons. The backgrounds of other buttons are erased as part of the WM_PAINT and WM_ENABLE processing.

WM_GETDLGCODE	Returns values indicating the type of input processed by the default button procedure, as shown in the following.

Button style	Returns

BS_AUTOCHECKBOX

DLGC_WANTCHARS | DLGC_BUTTON

BS_AUTORADIOBUTTON

DLGC_RADIOBUTTON

BS_CHECKBOX

DLGC_WANTCHARS | DLGC_BUTTON

BS_DEFPUSHBUTTON

DLGC_DEFPUSHBUTTON

BS_GROUPBOX

DLGC_STATIC

BS_PUSHBUTTON

DLGC_UNDEFPUSHBUTTON

BS_RADIOBUTTON

DLGC_RADIOBUTTON

WM_GETFONT	Returns a handle of the current font.

WM_KEYDOWN	Highlights the button if the user presses the SPACEBAR.

WM_KEYUP	Releases the mouse capture for all cases except the TAB key.

WM_KILLFOCUS	Removes the focus rectangle from a button. For push buttons and default push buttons, the focus rectangle is invalidated. If the button has the mouse capture, the capture is released, the button is not clicked, and any highlighting is removed.

WM_LBUTTONDBLCLK	Sends a BN_DOUBLECLICKED notification message to the parent window for radio buttons and owner-drawn buttons. For other buttons, a double-click is processed as a WM_LBUTTONDOWN message.

WM_LBUTTONDOWN	Highlights the button if the position of the mouse cursor is within the button's client rectangle.

WM_LBUTTONUP	Releases the mouse capture if the button had the mouse capture.

WM_MOUSEMOVE	Performs the same action as WM_LBUTTONDOWN if the button has the mouse capture. Otherwise, no action is performed.

WM_NCCREATE	Turns any BS_USERBUTTON button into a BS_PUSHBUTTON button.

WM_NCHITTEST	Returns HTTRANSPARENT if the button control is a group box.

WM_PAINT	Draws the button according to its style and current state.

WM_SETFOCUS	Draws a focus rectangle on the button getting the focus. For radio buttons and automatic radio buttons, the parent window is sent a BN_CLICKED notification message.

WM_SETFONT	Sets a new font and optionally updates the window.

WM_SETTEXT	Sets the text of the button. In the case of a group box, paints over the preexisting text before repainting the group box with the new text.

WM_SYSKEYUP	Releases the mouse capture for all cases except the TAB key.

The predefined window procedure passes all other messages to the DefWindowProc function for default processing.


Creating a Button Outside a Dialog Box

The following code sample shows how to use the CreateWindow function to create a default push button.

hwndButton = CreateWindow(

    "BUTTON",   /* predefined class                              */

    "OK",       /* button text                                   */

    WS_VISIBLE | WS_CHILD | BS_DEFPUSHBUTTON, /* styles          */

     /*

      * Size and position values are given explicitly, because

      * the CW_USEDEFAULT constant gives zero values for buttons.

      */

    10,         /* starting x position                           */

    10,         /* starting y position                           */

    100,        /* button width                                  */

    100,        /* button height                                 */

    hwnd,       /* parent window                                 */

    NULL,       /* No menu                                       */

    (HINSTANCE) GetWindowLong(hwnd, GWL_HINSTANCE),

    NULL);      /* pointer not needed                            */


Using Buttons That Are Not Owner-Drawn

The code example in this section is the window procedure for a dialog box, as shown in the following illustration.

The check boxes and radio buttons in the Buttons dialog box are automatic. The check boxes are three-state. The Clear colors push button is a default push button. The check boxes, radio buttons, and push buttons are defined as follows in the application's header file.

#define IDB_BOX1        101               /* first check box     */

#define IDB_BOX2        102               /* second check box    */

#define IDB_BOX3        103               /* third check box     */

#define IDB_REDBACK     104               /* top radio button    */

#define IDB_BLUEBACK    105               /* bottom radio button */

#define IDB_CLEARBOXES  107               /* top push button     */

#define IDB_CLEARBACK   108               /* bottom push button  */

HBRUSH hbrRed, hbrBlue, hbrWhite;

BOOL fRedBack, fBlueBack, fClearColor; /* background-state flags */

Note that it is not necessary to define IDOK, the identifier for the OK push button.

In the following window procedure, the WM_CTLCOLORDLG message notifies the application that the dialog box is about to be drawn. If the user presses the Clear colors button (signified by the fClearColor flag), the procedure uses the SendDlgItemMessage function to uncheck the check boxes and radio buttons. The BN_CLICKED notification message contains the identifiers of the buttons.

LRESULT APIENTRY ButtonProc(hDlg, message, wParam, lParam)

HWND hDlg;                /* window handle of dialog box  */

UINT message;             /* type of message              */

UINT wParam;              /* message-specific information */

LONG lParam;

{

    LRESULT lState;

    switch (message) {

        case WM_INITDIALOG:

            hbrRed = CreateSolidBrush(RGB(255, 0, 0));

            hbrBlue = CreateSolidBrush(RGB(0, 0, 255));

            hbrWhite = GetStockObject(WHITE_BRUSH);

            return TRUE;

        case WM_CTLCOLORDLG:

            if (fRedBack) {

                fRedBack = FALSE;

                return (LRESULT) hbrRed;

            }

            else if (fBlueBack) {

                fBlueBack = FALSE;

                return (LRESULT) hbrBlue;

            }

            else if (fClearColor) {

                fClearColor = FALSE;

                /*

                 * Uncheck all check boxes and radio buttons.

                 */

                SendDlgItemMessage(hDlg,    /* window handle     */

                    IDB_BOX1,         /* button identifier       */

                    BM_SETCHECK,      /* message                 */

                    0,                /* check state (unchecked) */

                    0);               /* must be zero            */

                SendDlgItemMessage(hDlg, IDB_BOX2,

                    BM_SETCHECK, 0, 0);

                SendDlgItemMessage(hDlg, IDB_BOX3,

                    BM_SETCHECK, 0, 0);

                SendDlgItemMessage(hDlg, IDB_REDBACK,

                    BM_SETCHECK, 0, 0);

                SendDlgItemMessage(hDlg, IDB_BLUEBACK,

                    BM_SETCHECK, 0, 0);

            }

            return (LRESULT) hbrWhite;

        case WM_COMMAND:

                if (wParam == IDOK) {

                    EndDialog(hDlg, TRUE);

                    return TRUE;

                }

                if (HIWORD(wParam) == BN_CLICKED) {

                    switch (LOWORD(wParam)) {

                        case IDB_BOX1:

                            /* Retrieve the state of the check box. */

                            lState = SendDlgItemMessage(hDlg,

                                IDB_BOX1, BM_GETSTATE, 0, 0);

                            /*

                             * The box-painting function is

                             * application defined.

                             */

                            BoxPainter(hDlg, /* window handle    */

                                1,           /* box to paint     */

                                lState);     /* check box state  */

                            break;

                        case IDB_BOX2:

                            lState = SendDlgItemMessage(hDlg,

                                IDB_BOX2, BM_GETSTATE, 0, 0);

                            BoxPainter(hDlg, 2, lState);

                            break;

                        case IDB_BOX3:

                            lState = SendDlgItemMessage(hDlg,

                                IDB_BOX3, BM_GETSTATE, 0, 0);

                            BoxPainter(hDlg, 3, lState);

                            break;

                        case IDB_REDBACK:

                            fRedBack = TRUE;

                            InvalidateRect(hDlg, NULL, TRUE);

                            break;

                        case IDB_BLUEBACK:

                            fBlueBack = TRUE;

                            InvalidateRect(hDlg, NULL, TRUE);

                            break;

                        case IDB_CLEARBACK:

                            fClearColor = TRUE;

                            InvalidateRect(hDlg, NULL, TRUE);

                            break;

                        case IDB_CLEARBOXES:

                            BoxPainter(hDlg, 4, (LRESULT) 0);

                            break;

                    }

                }

        case WM_DESTROY:

            DeleteObject(hbrRed);

            DeleteObject(hbrBlue);

             /*

              * Do not delete hbrWhite, because it is a stock

              * object.

              */

            break;

    }

    return FALSE;       /* did not process a message */

        UNREFERENCED_PARAMETER(lParam);

}


Using Owner-Drawn Buttons

The parent window of an owner-drawn button typically responds to at least three messages for the button: WM_INITDIALOG, WM_COMMAND, and WM_DRAWITEM. It is not necessary to process the WM_MEASUREITEM message for owner-drawn buttons.

When you must paint an owner-drawn button, Windows sends the parent window a WM_DRAWITEM message whose lParam parameter points to a DRAWITEMSTRUCT structure. Use this structure with all owner-drawn controls to provide the application with the information it requires to paint the control. The itemAction and itemState structure members define how to paint an owner-drawn button.

The following code sample shows how to process WM_INITDIALOG, WM_DRAWITEM, and WM_COMMAND messages for owner-drawn buttons. This code demonstrates how to draw one of two bitmaps for a control, depending on whether the control is selected. You would typically use the wParam parameter of the WM_DRAWITEM message to identify the control; in this example, only one control is assumed.

LRESULT APIENTRY OwnDrawProc(hDlg, message, wParam, lParam)

HWND hDlg;      /* window handle of dialog box           */

UINT message;   /* type of message                       */

UINT wParam;    /* message-specific information          */

LONG lParam;

{

    HDC hdcMem;

    LPDRAWITEMSTRUCT lpdis;

    switch (message) {

        case WM_INITDIALOG:

            /* hinst, hbm1 and hbm2 are defined globally. */

            hbm1 = LoadBitmap((HANDLE) hinst, "OwnBit1");

            hbm2 = LoadBitmap((HANDLE) hinst, "OwnBit2");

            return TRUE;

        case WM_DRAWITEM:

            lpdis = (LPDRAWITEMSTRUCT) lParam;

            hdcMem = CreateCompatibleDC(lpdis->hDC);

            if (lpdis->itemState & ODS_SELECTED) /* if selected     */

                SelectObject(hdcMem, hbm2);

            else

                SelectObject(hdcMem, hbm1);

            StretchBlt(

                lpdis->hDC,        /* destination device context    */

                lpdis->rcItem.left, /* x upper-left destination     */

                lpdis->rcItem.top,  /* y upper-left destination     */

                /* The next two lines specify the width and height. */

                lpdis->rcItem.right - lpdis->rcItem.left,

                lpdis->rcItem.bottom - lpdis->rcItem.top,

                hdcMem,    /* handle of source device context       */

                0,         /* x-coordinate upper-left source        */

                0,         /* y-coordinate upper-left source        */

                32,        /* source bitmap width                   */

                32,        /* source bitmap height                  */

                SRCCOPY);  /* raster operation                      */

            DeleteDC(hdcMem);

            return TRUE;

        case WM_COMMAND:

            if (wParam == IDOK

                || wParam == IDCANCEL) {

                EndDialog(hDlg, TRUE);

                return TRUE;

            }

            if (HIWORD(wParam) == BN_CLICKED) {

                switch (LOWORD(wParam)) {

                    case IDB_OWNERDRAW:

                        .

                        . /* application-defined processing */

                        .

                    break;

                }

            }

            break;

        case WM_DESTROY:

            DeleteObject(hbm1); /* delete bitmaps                */

            DeleteObject(hbm2);

            break;

    }

    return FALSE;

        UNREFERENCED_PARAMETER(lParam);

}


Functions and Messages

The following functions and messages can be used with buttons.

Functions

CheckDlgButton

CheckRadioButton

IsDlgButtonChecked

Messages

BM_GETCHECK

BM_GETSTATE

BM_SETCHECK

BM_SETSTATE

BM_SETSTYLE

BN_CLICKED

BN_DISABLE

BN_DOUBLECLICKED

BN_HILITE

BN_PAINT

BN_UNHILITE

DM_GETDEFID

DM_SETDEFID

WM_CTLCOLORBTN


List Boxes Overview

About List Boxes

Microsoft® Windows™ provides dialog boxes and controls to support communication between an application and the user. A list box is a control window that contains a list of items from which the user can choose. List box items can be represented by text strings, bitmaps, or both. If the list box is not large enough to display all the list box items at once, the list box can provide a scroll bar.

The user selects a list box item or cancels a selection by using the mouse or keyboard. Selecting a list box item changes its visual appearance, usually by changing the text and background colors to the colors specified by the operating system metrics for selected items. When the user selects or cancels an item, Windows sends a notification message to the parent window of the list box.

Although an application can use a list box in an overlapped, child, or pop-up window, list boxes are mainly designed for use in dialog boxes, where most of their functionality is predefined by Windows. When using a list box in windows other than dialog boxes, it is difficult to maintain a consistent user interface. Therefore, you should use window subclassing to implement a list box outside a dialog box. This topic primarily discusses the use of list boxes within dialog boxes, but this discussion also applies to the use of list boxes in any parent window. For more information about window subclassing, see Window Procedures.

A dialog box procedure is responsible for initializing and monitoring its child windows, including any list boxes. The dialog box procedure communicates with the list box by sending messages to it and by processing the notification messages sent by the list box. For more information about dialog boxes, see Dialog Boxes.

For general information about controls, see Controls.

The following topics discuss list boxes:

Terms

List Box Styles

List Box Functions

Notification Messages from List Boxes

Messages to List Boxes

Default Window-Message Processing

Creating a Simple List Box

Creating a Directory Listing in a Single-Selection List Box

Creating a Multiple-Selection List Box

Creating an Owner-Drawn List Box

Functions and Messages


List Box Styles

Windows provides two general styles of list box: single-selection and multiple-selection. In a single-selection list box (the default), the user can select only one item at a time. In a multiple-selection list box, the user can select more than one item at a time. Either the LBS_MULTIPLESEL or the LBS_EXTENDEDSEL style must be specified for a multiple-selection list box.

Windows provides many other list box and window styles that control the appearance and operation of a list box. These styles indicate whether list box items are sorted, arranged in multiple columns, drawn by the application, and so on. The dimensions and styles of a list box are typically defined in a dialog box template included in an application's resources. For information about how to create a dialog box template and include it in an application, refer to the documentation provided with your application-development tools.

To create a list box by using the CreateWindow or CreateWindowEx function, use the LISTBOX class, appropriate window-style constants, and the following list box-style constants to define the list box.

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 an application does 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. An application can create an owner-drawn list box either with or without this style.

LBS_MULTICOLUMN

Specifies a multicolumn list box with horizontal scrolling. 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 the string. The user can select any number of strings.

LBS_NODATA

Specifies a no-data list box. To use memory efficiently, an application should specify this style when the count of items in the list box 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.

LBS_NOINTEGRALHEIGHT

Specifies that the size of the list box is exactly the size specified by the application when it created the list box. By default, Windows sizes a list box so that the list box does not display partial items.

LBS_NOREDRAW

Specifies that the appearance of the list box is not updated when changes are made. An application can change this style at any time by sending a WM_SETREDRAW message.

LBS_NOTIFY

Sends an input message to the parent window whenever the user clicks or double-clicks a string.

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 whenever a visual aspect of the list box changes.

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 list box when the list box is created and a WM_DRAWITEM message whenever the visual aspect of the list box changes.

LBS_SORT

Sorts strings in the list box alphabetically.

LBS_STANDARD

Specifies a standard list box. Specifying this style is equivalent to specifying LBS_SORT, LBS_NOTIFY, and LBS_BORDER.

LBS_USETABSTOPS

Allows a list box to recognize and expand tab characters when drawing its strings. The default tab positions are 32 dialog box units. Windows computes the dialog box base units based on the height and width of the current operating system font. One horizontal dialog box unit is equal to one-fourth of the current dialog box base width unit. 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 allows an application to perform special processing on the keyboard input.


List Box Functions

Windows supports two functions specific to list boxes. The DlgDirList function fills a list box with the files and directories in a specified path. The DlgDirSelectEx function retrieves the current selection in a list box initialized by DlgDirList. These functions make it possible for the user to select a file from a list box without typing the location and name of the file.


Notification Messages from List Boxes

When an event occurs in a list box, the list box sends a notification message to the dialog box procedure of the owner window. List box notification messages are sent when a user selects, double-clicks, or cancels a list box item; when the list box receives or loses the keyboard focus; and when the operating system cannot allocate enough memory for a list box request. A notification message is sent as a WM_COMMAND message in which the low-order word of the wParam parameter contains the list box identifier, the high-order word of wParam contains the notification code, and the lParam parameter contains the control window handle.

Portability Issue:	In Microsoft® Windows NT™, the placement of the notification code has moved from the lParam parameter to the wParam parameter. Windows 3.x applications that process notification messages must be modified in this respect when they are ported to Windows NT.

A dialog box procedure is not required to process these messages; the default window procedure processes them.

An application should monitor and process the following list box notification messages.

Notification code	Meaning

LBN_DBLCLK	The user double-clicks an item in the list box.

LBN_ERRSPACE	The list box cannot allocate enough memory to fulfill a request.

LBN_KILLFOCUS	The list box loses the keyboard focus.

LBN_SELCANCEL	The user cancels the selection of an item in the list box.

LBN_SELCHANGE	The selection in a list box is about to change.

LBN_SETFOCUS	The list box receives the keyboard focus.


Messages to List Boxes

A dialog box procedure can send messages to a list box to add, delete, examine, and change list box items. For example, a dialog box procedure could send an LB_ADDSTRING message to a list box to add an item, and the LB_GETSEL message to determine whether the item is selected. Other messages set and retrieve information about the size, appearance, and behavior of the list box. For example, the LB_SETHORIZONTALEXTENT message sets the scrollable width of a list box. A dialog box procedure can send any message to a list box by using the SendMessage or SendDlgItemMessage function.

A list box item is often referenced by its index, an integer that represents the item's position in the list box. The index of the first item in a list box is 0, the index of the second item is 1, and so on.

The following table describes how the predefined list box procedure responds to list box messages.

Message	Response

LB_ADDFILE	Inserts a file into a directory list box filled by the DlgDirList function and retrieves the list box index of the inserted item.

LB_ADDSTRING	Adds a string to a list box and returns its index.

LB_DELETESTRING	Removes a string from a list box and returns the number of strings remaining in the list.

LB_DIR	Adds a list of filenames to a list box and returns the index of the last filename added.

LB_FINDSTRING	Returns the index of the first string in the list box that matches a given prefix.

LB_FINDSTRINGEXACT	Returns the index of the string that is equivalent to or prefixed by a given prefix.

LB_GETANCHORINDEX	Returns the index of the item that the mouse last selected.

LB_GETCARETINDEX	Returns the index of the item that has the focus rectangle.

LB_GETCOUNT	Returns the number of items in the list box.

LB_GETCURSEL	Returns the index of the currently selected item in a single-selection list box.

LB_GETHORIZONTALEXTENT	Returns the scrollable width, in pixels, of a list box.

LB_GETITEMDATA	Returns the 32-bit value associated with the given item.

LB_GETITEMHEIGHT	Returns the height, in pixels, of an item in a list box.

LB_GETITEMRECT	Retrieves the client coordinates of the given list box item.

LB_GETLOCALE	Retrieves the locale of the list box. The high-order word contains the country code and the low-order word contains the language identifier.

LB_GETSEL	Returns the selection state of a list box item.

LB_GETSELCOUNT	Returns the number of selected items in a multiple-selection list box.

LB_GETSELITEMS	Creates an array of the indexes of all selected items in a multiple-selection list box and returns the total number of selected items.

LB_GETTEXT	Retrieves the string associated with a given item and the length of the string.

LB_GETTEXTLEN	Returns the length, in characters, of the string associated with a given item.

LB_GETTOPINDEX	Returns the index of the first visible item in a list box.

LB_INSERTSTRING	Inserts a string at a given index in a list box.

LB_RESETCONTENT	Removes all items from a list box.

LB_SELECTSTRING	Selects the first string it finds that matches a given prefix.

LB_SELITEMRANGE	Selects a given range of items in a list box.

LB_SELITEMRANGEEX	Selects a given range of items if the index of the first item in the range is less than the index of the last item in the range. Cancels the selection in the range if the index of the first item is greater than the last.

LB_SETANCHORINDEX	Sets the item that the mouse last selected to a given item.

LB_SETCARETINDEX	Sets the focus rectangle to a given list box item.

LB_SETCOLUMNWIDTH	Sets the width, in pixels, of all columns in a list box.

LB_SETCOUNT	Sets the number of items in a list box.

LB_SETCURSEL	Selects a given list box item.

LB_SETHORIZONTALEXTENT	Sets the scrollable width, in pixels, of a list box.

LB_SETITEMDATA	Associates a 32-bit value with a list box item.

LB_SETITEMHEIGHT	Sets the height, in pixels, of an item or items in a list box.

LB_SETLOCALE	Sets the locale of a list box and returns the previous locale identifier.

LB_SETSEL	Selects an item in a multiple-selection list box.

LB_SETTABSTOPS	Sets the tab stops to those specified in a given array.

LB_SETTOPINDEX	Scrolls the list box so the specified item is at the top of the visible range.


Default Window-Message Processing

The window procedure for the predefined list box window class carries out default processing for all messages that the list box does not process. When the list box procedure returns FALSE for a message, the predefined window procedure checks the message and carries out default actions, as shown in the following table.

Message	Default

WM_CHAR	Moves the selection to the first item that begins with the character the user typed. If the list box has the LBS_OWNERDRAW style, nothing happens.

WM_CREATE	Creates an empty list box.

WM_DESTROY	Destroys the list box and frees any resources it uses.

WM_DROPFILES	Passes the message to the dialog box procedure or parent window process.

WM_ENABLE	If the control is visible, invalidates the rectangle so the strings can be painted gray.

WM_ERASEBKGND	Erases the background of a list box. If the list box has the LBS_OWNERDRAW style, the background is not erased.

WM_GETDLGCODE	Returns DLGC_WANTARROWS | DLGC_WANTCHARS, indicating the default list box procedure processes the arrow keys and WM_CHAR messages.

WM_GETFONT	Returns a handle of the current font for the list box.

WM_HSCROLL	Scrolls the list box horizontally.

WM_KEYDOWN	Processes virtual keys for scrolling. The virtual key is the index of the item to move the caret to. The selection is not changed.

WM_KILLFOCUS	Turns the caret off and destroys it. Sends an LBN_KILLFOCUS message to the owner of the list box.

WM_LBUTTONDBLCLK	Tracks the mouse in the list box client area. This enables the user to cancel a selection if the mouse button is released outside the list box client area.

WM_LBUTTONDOWN	Tracks the mouse in the list box client area. This enables the user to cancel a selection if the mouse button is released outside the list box client area.

WM_LBUTTONUP	Tracks the mouse in the list box client area. This enables the user to cancel a selection if the mouse button is released outside the list box client area.

WM_MOUSEMOVE	Tracks the mouse in the list box client area. This enables the user to cancel a selection if the mouse button is released outside the list box client area.

WM_PAINT	Performs a subclassed paint operation by using the list box handle of the device context.

WM_SETFOCUS	Turns the caret on and sends an LBN_SETFOCUS message to the owner of the list box.

WM_SETFONT	Sets a new font for the list box.

WM_SETREDRAW	Sets or clears the redraw flag based on the value of wParam.

WM_SIZE	Resizes the list box to an integral number of items.

WM_VSCROLL	Scrolls the list box vertically.

The predefined list box procedure passes all other messages to the DefWindowProc function for default processing.


Creating a Simple List Box

The following code sample demonstates how a dialog box procedure creates a simple list box and fills it with the names of people on a softball team. When a name in the list is selected, additional information about the player is displayed in the dialog box. The following illustration shows the dialog box.

The list box has the LBS_STANDARD style, a combination of LBS_SORT, LBS_NOTIFY, WS_VSCROLL, and WS_BORDER. The code initializes the dialog box while processing the WM_INITDIALOG message. For each name that appears in the list box, the code sends an LB_ADDSTRING message to the list box. By processing the LBN_SELCHANGE notification, the code also keeps track of when the selection changes.

#define BUFFER MAX_PATH

#define NAMELENGTH 15

#define POSITIONLENGTH 20

#define TEAMSIZE 15

typedef struct {

    TCHAR tchName[NAMELENGTH];

    TCHAR tchPosition[POSITIONLENGTH];

    int nGamesPlayed;

    int nInningsPlayed;

    double xBattingAverage;

    TCHAR tchFoodName[NAMELENGTH];

} Player;

Player Roster[] = {

      {"Pete", "shortstop", 26, 90, .608, "Rutabaga"},

      {"Suzanna", "catcher", 16, 53, .286, "Toast"},

      {"Jack", "pitcher", 27, 110, .542, "Animal Crackers"},

      {"Karen", "second base", 26, 140, .238, "Pez"},

      {"Dave", "first base", 28, 138, .508, "Suds"},

      {"Wendy", "third base", 25, 154, .493, "Ham"},

      {"Matt", "shortstop", 24, 112, .579, "Oats"},

      {"Jenny", "right field", 22, 101, .509, "Mashed Potatoes"},

      {"Seth", "left-center field", 20, 76, .407, "Otter Pop"},

      {"Kathie", "left field", 26, 127, .353, "Baba Ganouj"},

      {"Colin", "pitcher", 26, 96, .456, "Lefse"},

      {"Penny", "right field", 24, 112, .393, "Zotz"},

      {"Art", "left-center field", 17, 56, .375, "Cannelloni"},

      {"Cindy", "second base", 13, 58, .207, "Tequila"},

      {"David", "center field", 18, 101, .612, "Bok Choy"}

    };

   /*

    * FUNCTION: DlgTeamProc(HWND, unsigned, WORD, LONG)

    *

    * PURPOSE: Dialog box for "BFG Softball Statistics"

    */

BOOL APIENTRY DlgTeamProc(

    HWND hDlg,            /* window handle of dialog box   */

    UINT message,         /* type of message               */

    UINT wParam,          /* message-specific information  */

    LONG lParam)          /* message-specific information  */

{

  TCHAR tchName[NAMELENGTH];

  TCHAR tchBuffer[BUFFER];

  int nItem;

  int i;

  switch (message) {

    case WM_INITDIALOG:

      /* Initialize the list box (fill it with player names). */

      for (i = 0; i < TEAMSIZE; i++) {

          SendMessage(GetDlgItem(hDlg, IDL_SOFTBALL),

              LB_ADDSTRING, 0, (LPARAM) Roster[i].tchName);

      }

      SetFocus(GetDlgItem(hDlg, IDL_SOFTBALL));

      return FALSE;

    case WM_COMMAND:

      switch (LOWORD(wParam)) {

        case IDL_SOFTBALL:

          switch (HIWORD(wParam)) {

            case LBN_SELCHANGE:

              /* Display the selected player's statistics. */

              nItem = SendMessage(GetDlgItem(hDlg, IDL_SOFTBALL),

                  LB_GETCURSEL, 0, 0);

              SendMessage(GetDlgItem(hDlg, IDL_SOFTBALL),

                  LB_GETTEXT, nItem, (LPARAM) tchName);

              for (i = 0; strcmp(tchName, Roster[i].tchName); i++);

              SetDlgItemText(hDlg, IDS_POS, Roster[i].tchPosition);

              SetDlgItemText(hDlg, IDS_GAME,

                  _itoa(Roster[i].nGamesPlayed, tchBuffer, 10));

              SetDlgItemText(hDlg, IDS_INN,

                  _itoa(Roster[i].nInningsPlayed, tchBuffer, 10));

              SetDlgItemText(hDlg, IDS_BA,

                  _gcvt(Roster[i].xBattingAverage, 3, tchBuffer));

              SetDlgItemText(hDlg, IDS_FOOD,

                  Roster[i].tchFoodName);

              return TRUE;

           }

           break;

        case IDOK:

        case IDCANCEL:

          /* Destroy the dialog box. */

          EndDialog(hDlg, TRUE);

          return TRUE;

        default:

          return FALSE;

      }

    default:

        return FALSE;

  }

}


Creating a Directory Listing in a Single-Selection List Box

The following code sample demonstrates how to display the contents of the current directory in a list box and enable the user to delete one file at a time. The following illustration shows the dialog box.

In addition to the standard list box styles, this list box has the LBS_MULTICOLUMN and LBS_HSCROLL styles. The code initializes the list box by using the DlgDirList function to fill the list box with the names of all the files in the current directory. When the user selects the Delete button, the DlgDirSelectEx function retrieves the name of the selected file. The code deletes the file by using the DeleteFile function and updates the directory list box by sending the LB_DELETESTRING message.

#define BUFFER MAX_PATH

    /*

     * FUNCTION: DlgDelFileProc(HWND, unsigned, WORD, LONG)

     *

     * PURPOSE: "Delete File" dialog box

     */

BOOL APIENTRY DlgDelFileProc(

    HWND hDlg,            /* window handle of dialog box     */

    UINT message,         /* type of message                 */

    UINT wParam,          /* message-specific information    */

    LONG lParam)

{

  DWORD cchCurDir;

  LPTSTR lpszCurDir;

  LPTSTR lpszFileToDelete;

  int nItem;

  int nTotal;

  TCHAR tchBuffer[BUFFER];

  BOOL fResult;

  switch (message) {

    case WM_INITDIALOG:

      /*

       * Initialize the list box by filling it with files from

       * the current directory.

       */

      lpszCurDir = tchBuffer;

      GetCurrentDirectory(cchCurDir, lpszCurDir);

      DlgDirList(hDlg, lpszCurDir, IDL_FILES, IDS_PATHTOFILL, 0);

      SetFocus(GetDlgItem(hDlg, IDL_FILES));

      return FALSE;

    case WM_COMMAND:

      switch (LOWORD(wParam)) {

        case IDOK:

          /*

           * When the user presses the DEL (IDOK) button,

           * delete the selected file.

           */

          lpszFileToDelete = tchBuffer;

          DlgDirSelectEx(hDlg, lpszFileToDelete, MAX_PATH,

              IDL_FILES);

          fResult = DeleteFile(lpszFileToDelete);

          if (!fResult) {

              MessageBox(hDlg, "Could not delete file.",

                  NULL, MB_OK);

          } else {

              nItem = SendMessage(GetDlgItem(hDlg, IDL_FILES),

                  LB_GETCURSEL, 0, 0);

              nTotal = SendMessage(GetDlgItem(hDlg, IDL_FILES),

                  LB_DELETESTRING, nItem, 0);

              /* Update the list box. */

              if (nTotal > nItem) {

                  SendMessage(GetDlgItem(hDlg, IDL_FILES),

                      LB_SETCURSEL, nItem, 0);

              } else {

                  SendMessage(GetDlgItem(hDlg, IDL_FILES),

                      LB_SETCURSEL, nTotal, 0);

              }

          }

          return TRUE;

        case IDCANCEL:

          /* Destroy the dialog box. */

          EndDialog(hDlg, TRUE);

          return TRUE;

        default:

          return FALSE;

      }

    default:

        return FALSE;

  }

}


Creating a Multiple-Selection List Box

The following code sample displays and initializes the same dialog box used in the preceding example. However, this code uses the LBS_MULTIPLESEL style to enable the user to select more than one file at a time. When the user selects the Delete button, the example sends the LB_GETSELCOUNT message (to retrieve the number of files selected) and the LB_GETSELITEMS message (to retrieve an array of selected list box items). After deleting a file, the code removes the corresponding item from the list box by sending the LB_DELETESTRING message.

#define BUFFER MAX_PATH

#define BIGBUFF 8192

    /*

     * FUNCTION: DlgDelFilesProc(HWND, unsigned, WORD, LONG)

     *

     * PURPOSE: "Delete files" dialog box

     */

BOOL APIENTRY DlgDelFilesProc(

    HWND hDlg,            /* window handle of dialog box  */

    UINT message,         /* type of message              */

    UINT wParam,          /* message-specific information */

    LONG lParam)

{

  DWORD cchCurDir;

  LPTSTR lpszCurDir;

  LPTSTR lpszFileToDelete;

  int nSelItems;

  int nSelItemsInBuffer;

  TCHAR tchBuffer[BUFFER];

  TCHAR tchMsgBuff[BUFFER];

  int nBuffer[BIGBUFF];

  int i;

  BOOL fResult;

  HWND hListBox;

  switch (message) {

    case WM_INITDIALOG:

      /*

       * Initialize the list box by filling it with files from

       * the current directory.

       */

      lpszCurDir = tchBuffer;

      GetCurrentDirectory(cchCurDir, lpszCurDir);

      DlgDirList(hDlg, lpszCurDir, IDL_FILES, IDS_PATHTOFILL, 0);

      SetFocus(GetDlgItem(hDlg, IDL_FILES));

      return FALSE;

    case WM_COMMAND:

      switch (LOWORD(wParam)) {

        case IDOK:

          /*

           * When the user presses the Delete (IDOK) button,

           * delete all the selected files.

           */

          lpszFileToDelete = tchBuffer;

          hListBox = GetDlgItem(hDlg, IDL_FILES);

          nSelItems = SendMessage(hListBox, LB_GETSELCOUNT, 0, 0);

          nSelItemsInBuffer = SendMessage(hListBox, LB_GETSELITEMS,

              512, (LPARAM) nBuffer);

          if (nSelItems > nSelItemsInBuffer) {

              MessageBox(hDlg, "Too many items selected.",

                  NULL, MB_OK);

          } else {

              for (i = nSelItemsInBuffer - 1; i > -1; i--) {

                SendMessage(hListBox, LB_GETTEXT, nBuffer[i],

                    (LPARAM) lpszFileToDelete);

                fResult = DeleteFile(lpszFileToDelete);

                if (!fResult) {

                    sprintf(tchMsgBuff,

                        "Could not delete file: %s GetLastError = %u",

                        (LPARAM) lpszFileToDelete);

                    ErrorHandler(tchMsgBuff);   /* app-defined */

                } else {

                    SendMessage(hListBox, LB_DELETESTRING,

                        nBuffer[i], 0);

                }

              }

              SendMessage(hListBox, LB_SETCARETINDEX, 0, 0);

          }

          return TRUE;

        case IDCANCEL:

          /* Destroy the dialog box. */

          EndDialog(hDlg, TRUE);

          return TRUE;

        default:

          return FALSE;

      }

    default:

        return FALSE;

  }

}


Creating an Owner-Drawn List Box

The following code sample shows how to draw a list box that contains five owner-drawn items and prompts the user to select the item not like the others. The following illustration shows the dialog box.

The list box has the LBS_OWNERDRAW and LBS_HASSTRINGS styles, in addition to the standard list box styles. The code initializes the list box by sending the LB_ADDSTRING message to set the text, and then sends the LB_SETITEMDATA message to associate a bitmap with each list box item. The code also sets the height of each list box item by processing the WM_MEASUREITEM message and draws the text and bitmap for each item by processing the WM_DRAWITEM message.

#define XBITMAP 80

#define YBITMAP 20

#define BUFFER MAX_PATH

HBITMAP hbmpPencil, hbmpCrayon, hbmpMarker, hbmpPen, hbmpFork;

HBITMAP hbmpPicture, hbmpOld;

    /*

     * FUNCTION: DlgDrawProc(HWND, unsigned, WORD, LONG)

     *

     * PURPOSE: "One of these things..." dialog box

     */

DWORD APIENTRY DlgDrawProc(

        HWND hDlg,            /* window handle of dialog box     */

        UINT message,         /* type of message                 */

        UINT wParam,          /* message-specific information    */

        LONG lParam)

{

  int nItem;

  TCHAR tchBuffer[BUFFER];

  HWND hListBox;

  TEXTMETRIC tm;

  int y;

  HDC hdcMem;

  LPMEASUREITEMSTRUCT lpmis;

  LPDRAWITEMSTRUCT lpdis;

  RECT rcBitmap;

  switch (message) {

    case WM_INITDIALOG:

      /* Load bitmaps. */

      hbmpPencil = LoadBitmap(hinst, MAKEINTRESOURCE(700));

      hbmpCrayon = LoadBitmap(hinst, MAKEINTRESOURCE(701));

      hbmpMarker = LoadBitmap(hinst, MAKEINTRESOURCE(702));

      hbmpPen = LoadBitmap(hinst, MAKEINTRESOURCE(703));

      hbmpFork = LoadBitmap(hinst, MAKEINTRESOURCE(704));

      /* Retrieve list box handle. */

      hListBox = GetDlgItem(hDlg, IDL_STUFF);

      /*

       * Initialize the list box text and associate a bitmap

       * with each list box item.

       */

      nItem = SendMessage(hListBox, LB_ADDSTRING, 0,

          (LPARAM) "pencil");

      SendMessage(hListBox, LB_SETITEMDATA, nItem,

          (LPARAM) hbmpPencil);

      nItem = SendMessage(hListBox, LB_ADDSTRING, 0,

          (LPARAM) "crayon");

      SendMessage(hListBox, LB_SETITEMDATA, nItem,

          (LPARAM) hbmpCrayon);

      nItem = SendMessage(hListBox, LB_ADDSTRING, 0,

          (LPARAM) "marker");

      SendMessage(hListBox, LB_SETITEMDATA, nItem,

          (LPARAM) hbmpMarker);

      nItem = SendMessage(hListBox, LB_ADDSTRING, 0,

          (LPARAM) "pen");

      SendMessage(hListBox, LB_SETITEMDATA, nItem,

          (LPARAM) hbmpPen);

      nItem = SendMessage(hListBox, LB_ADDSTRING, 0,

          (LPARAM) "fork");

      SendMessage(hListBox, LB_SETITEMDATA, nItem,

          (LPARAM) hbmpFork);

      SetFocus(hListBox);

      SendMessage(hListBox, LB_SETCURSEL, 0, 0);

      return TRUE;

    case WM_MEASUREITEM:

      lpmis = (LPMEASUREITEMSTRUCT) lParam;

      /* Set the height of the list box items. */

      lpmis->itemHeight = 20;

      return TRUE;

    case WM_DRAWITEM:

      lpdis = (LPDRAWITEMSTRUCT) lParam;

      /* If there are no list box items, skip this message. */

      if (lpdis->itemID == -1) {

        break;

      }

      /*

       * Draw the bitmap and text for the list box item. Draw a

       * rectangle around the bitmap if it is selected.

       */

      switch (lpdis->itemAction) {

        case ODA_SELECT:

        case ODA_DRAWENTIRE:

          /* Display the bitmap associated with the item. */

          hbmpPicture = (HBITMAP) SendMessage(lpdis->hwndItem,

              LB_GETITEMDATA, lpdis->itemID, (LPARAM) 0);

          hdcMem = CreateCompatibleDC(lpdis->hDC);

          hbmpOld = SelectObject(hdcMem, hbmpPicture);

          BitBlt(lpdis->hDC,

              lpdis->rcItem.left, lpdis->rcItem.top,

              lpdis->rcItem.right - lpdis->rcItem.left,

              lpdis->rcItem.bottom - lpdis->rcItem.top,

              hdcMem, 0, 0, SRCCOPY);

          /* Display the text associated with the item. */

          SendMessage(lpdis->hwndItem, LB_GETTEXT, lpdis->itemID,

              (LPARAM) tchBuffer);

          GetTextMetrics(lpdis->hDC, &tm);

          y = (lpdis->rcItem.bottom + lpdis->rcItem.top -

              tm.tmHeight) / 2;

          TextOut(lpdis->hDC,

              XBITMAP + 6,

              y,

              tchBuffer,

              strlen(tchBuffer));

          SelectObject(hdcMem, hbmpOld);

          DeleteDC(hdcMem);

          /* Is the item selected? */

          if (lpdis->itemState & ODS_SELECTED) {

            /* Set RECT coordinates to surround only the bitmap. */

            rcBitmap.left = lpdis->rcItem.left;

            rcBitmap.top = lpdis->rcItem.top;

            rcBitmap.right = lpdis->rcItem.left + XBITMAP;

            rcBitmap.bottom = lpdis->rcItem.top + YBITMAP;

            /* Draw a rectangle around bitmap to indicate the selection. */

            DrawFocusRect(lpdis->hDC, &rcBitmap);

          }

          break;

        case ODA_FOCUS:

          /*

           * Do not process focus changes. The focus caret (outline

           * rectangle) indicates the selection. The Which one? (IDOK)

           * button indicates the final selection.

           */

          break;

      }

      return TRUE;

    case WM_COMMAND:

      switch (LOWORD(wParam)) {

        case IDOK:

          /* Get the selected item's text. */

          nItem = SendMessage(GetDlgItem(hDlg, IDL_STUFF),

              LB_GETCURSEL, 0, (LPARAM) 0);

          SendMessage(GetDlgItem(hDlg, IDL_STUFF), LB_GETTEXT,

              nItem, (LPARAM) tchBuffer);

          /*

           * If the item is not the correct answer, tell the

           * user to try again.

           *

           * If the item is the correct answer, congratulate

           * the user and destroy the dialog box.

           */

          if (strcmp(tchBuffer, "fork")) {

              MessageBox(hDlg, "Try again!", "Oops.", MB_OK);

              return FALSE;

          } else {

              MessageBox(hDlg, "You're right!", "Congratulations.",

                MB_OK);

            /* Fall through. */

          }

        case IDCANCEL:

          /* Destroy the dialog box. */

          EndDialog(hDlg, TRUE);

          return TRUE;

        default:

          return FALSE;

      }

    case WM_DESTROY:

        /* Free any resources used by the bitmaps. */

        DeleteObject(hbmpPencil);

        DeleteObject(hbmpCrayon);

        DeleteObject(hbmpMarker);

        DeleteObject(hbmpPen);

        DeleteObject(hbmpFork);

        return TRUE;

    default:

        return FALSE;

  }

  return FALSE;

}


Functions and Messages

Following are the functions and messages used with list boxes.

Functions

DlgDirList

DlgDirSelectEx

Messages

LB_ADDFILE

LB_ADDSTRING

LB_DELETESTRING

LB_DIR

LB_FINDSTRING

LB_FINDSTRINGEXACT

LB_GETANCHORINDEX

LB_GETCARETINDEX

LB_GETCOUNT

LB_GETCURSEL

LB_GETHORIZONTALEXTENT

LB_GETITEMDATA

LB_GETITEMHEIGHT

LB_GETITEMRECT

LB_GETLOCALE

LB_GETSEL

LB_GETSELCOUNT

LB_GETSELITEMS

LB_GETTEXT

LB_GETTEXTLEN

LB_GETTOPINDEX

LB_INSERTSTRING

LB_RESETCONTENT

LB_SELECTSTRING

LB_SELITEMRANGE

LB_SELITEMRANGEEX

LB_SETANCHORINDEX

LB_SETCARETINDEX

LB_SETCOLUMNWIDTH

LB_SETCOUNT

LB_SETCURSEL

LB_SETHORIZONTALEXTENT

LB_SETITEMDATA

LB_SETITEMHEIGHT

LB_SETLOCALE

LB_SETSEL

LB_SETTABSTOPS

LB_SETTOPINDEX

LBN_DBLCLK

LBN_ERRSPACE

LBN_KILLFOCUS

LBN_SELCANCEL

LBN_SELCHANGE

LBN_SETFOCUS

WM_CHARTOITEM

WM_DELETEITEM

WM_VKEYTOITEM


Edit Controls Overview

About Edit Controls

Microsoft® Windows™ provides dialog boxes and controls to support communication between the application and the user. An edit control is a rectangular control window typically used in a dialog box to permit the user to enter and edit text from the keyboard. The user selects an edit control giving it the input focus by clicking the mouse inside it or by pressing the TAB key. After it is selected, the edit control displays its text (if any) and a flashing caret that indicates the insertion point. The user can then enter text, move the insertion point, or select text to be moved or deleted by using the keyboard or the mouse. An edit control can send notification messages to its parent window in the form of WM_COMMAND messages. For more information about messages from an edit control, see Messages From Edit Controls. A parent window can send messages to an edit control in a dialog box by calling the SendDlgItemMessage function. Each of the messages sent to edit controls are discussed in this topic.

Edit controls can be single-line (the default) or multiline. Multiline edit controls (sometimes called MLEs) can have scroll bars. Edit controls belong to the EDIT window class.

Although edit controls can be used in overlapped, pop-up, and child windows, they are designed for use in dialog boxes, where Windows standardizes their behavior. If the application uses edit controls outside dialog boxes, this creates extra work and increases the risk that the application may behave in a nonstandard fashion. For these reasons, the application should either use edit controls in dialog boxes or use window subclassing to create customized edit controls.

A combo box is a control that combines much of the functionality of an edit control and a list box. In a combo box, the edit control displays the current selection and the list box presents options a user can select.

Many developers use the dialog boxes provided in the common dialog box library (COMDLG32.DLL) to perform tasks that otherwise might require customized edit controls.

The following topics discuss edit controls:

Terms

Edit Control Styles

The Text Buffer

Text Operations

Messages From Edit Controls

Default Edit-control Behavior

Using Edit Controls

Simple Word Processing with an Edit Control

Using Single-line Edit Controls

Functions and Messages


Edit Control Styles

Windows provides 13 edit control styles. An individual edit control can have several styles at the same time. Most developers use stand-alone tools to develop dialog boxes and so may not need to specify edit control styles explicitly. If an application creates an edit control using the CreateWindow or CreateWindowEx function, however, it must specify these edit control styles.

Every edit control specifies a combination of style values that define the appearance and features of the edit control. The style values can establish the appearance of a single-line or multiline edit control, align the text in the control, and determine how, and even if, text appears in the edit control. The number and type of styles the application uses depend on the type and purpose of the edit control.

There are two line styles for edit controls. The default is a single-line edit control that doesn't require an associated style. An application can create a multiline edit control by using the ES_MULTILINE style.

There are three styles that cause Windows to align the text in an edit control. The ES_LEFT, ES_CENTER, and ES_RIGHT styles determine whether text is aligned on the left, center, or right, respectively. These styles apply only to multiline edit controls.

An application can use a style to determine how Windows displays text that a user enters in an edit control. The ES_LOWERCASE style converts the text into lowercase characters; the ES_UPPERCASE style converts the text into uppercase characters. Some applications may need to convert the text in a Windows string (such as a filename) into a specific character set. The ES_OEMCONVERT style ensures the proper conversion of characters in these instances.

When the amount of text to be displayed exceeds the size of the edit control, an application can use two styles to scroll the text through the edit control. The ES_AUTOHSCROLL style automatically scrolls text horizontally in single-line and multiline edit controls. When the application has a multiline edit control, it can also use the ES_AUTOVSCROLL style to automatically scroll text vertically, if necessary.

Other available styles define different aspects of an edit control. The ES_NOHIDESEL style specifies that the selected text is not hidden when the edit control loses the keyboard focus. The ES_READONLY style makes the edit control read-only. The ES_PASSWORD style displays all characters in the edit control as asterisks. (An application can define a different character to display by using the EM_SETPASSWORDCHAR message, as described later in this topic.) In multiline edit controls, an application can specify the ES_WANTRETURN style to request that Windows insert a carriage return when the user presses the ENTER key in the edit control.

By default, an edit control has no border. To give it one, an application can use the WS_BORDER window style.


The Text Buffer

Windows stores edit control text in a buffer and copies it to the control as necessary. This section discusses the tools Windows provides to allocate and initialize the buffer and to change its characteristics.

Allocating a Text Buffer

When Windows creates an edit control, it automatically creates a text buffer, sets its initial size, and increases the size as necessary, up to a predefined limit of approximately 32 kilobytes for single-line edit controls. Because this limit can change, it is called a soft limit. An application can set a hard limit to the buffer size by sending an EM_LIMITTEXT message to the edit control. If the buffer exceeds either limit, Windows sends the application an EN_ERRSPACE message.

Windows typically creates an edit control buffer in a dialog box, using memory outside the application's data segment. An application can suppress this default allocation behavior and create the buffer from its local heap by using the DS_LOCALEDIT style when creating the edit control. An application that uses the DS_LOCALEDIT style is responsible for all buffer allocations. To make the initial allocation, an application can call the LocalAlloc function and pass the returned buffer handle to the edit control by sending it an EM_SETHANDLE message. To make subsequent allocations (in response to an EN_ERRSPACE message, for example), an application should save the current buffer contents (if necessary) and obtain a new buffer as follows:

1	Retrieve the handle of the memory currently allocated for the text in a multiline edit control by sending the control an EM_GETHANDLE message.

2	Free the buffer by calling the LocalFree function.

3	Obtain a new buffer (and buffer handle) by calling LocalAlloc.

4	Give the buffer handle to Windows by sending the control an EM_SETHANDLE message.

The EM_SETHANDLE and EM_GETHANDLE messages apply only to multiline edit controls.

An application that uses the default allocation behavior (that is, does not use the DS_LOCALEDIT style) must not send EM_SETHANDLE and EM_GETHANDLE messages to the edit control.

Sending an EM_SETHANDLE message has several side effects: it clears the undo flag (making the EM_CANUNDO message return zero), it clears the modify flag (making the EM_GETMODIFY message return zero), and it redraws the edit control window.

Initializing a Text Buffer

An application can initialize or reinitialize an edit control's text buffer by calling the SetDlgItemText function. An application can retrieve the contents of a text buffer by calling the GetDlgItemText function.

Making a Text Buffer Read-Only

For each edit control, Windows maintains a read-only flag that indicates whether the control's text is read-write (the default) or read-only. An application can set the read-write or read-only flag for the text by sending the control an EM_SETREADONLY message. To determine whether an edit control is read-only, an application can call the GetWindowLong function using the GWL_STYLE constant. The EM_SETREADONLY message applies to both single-line and multiline edit controls.

Changing the Formatting Rectangle

The visibility of an edit control's text is governed by the dimensions of its window rectangle and its formatting rectangle. The window rectangle is the client area of the window containing the edit control. The formatting rectangle is a construct maintained by Windows for formatting the text displayed in the window rectangle. When an edit control is first displayed, the two rectangles are identical on the screen. An application can make the formatting rectangle larger than the window rectangle (thereby limiting the visibility of the edit control's text) or smaller than the window rectangle (thereby creating extra white space around the text).

An application can set the coordinates of an edit control's formatting rectangle by sending it an EM_SETRECT message. The EM_SETRECT message also automatically redraws the edit control's text. To establish the coordinates of the formatting rectangle without redrawing the control's text, an application can send the control an EM_SETRECTNP message. To retrieve the coordinates of the formatting rectangle, an application can send the control an EM_GETRECT message. These messages apply to multiline edit controls only.


Text Operations

Windows automatically processes all user-initiated text operations and notifies the application when the operations are completed. This section discusses user-initiated text operations and the application's response.

Character Sets

Windows supports two character sets: Unicode, a two-byte character set, and ANSI, a one-byte character set that is a strict subset of Unicode. In ANSI, n characters equals n bytes, but in Unicode, n characters equals 2n bytes.

Fonts

An application can change the font that an edit control uses by sending the WM_SETFONT message. Most applications do this while processing the WM_INITDIALOG message. Changing the font does not change the size of the edit control; applications that send the WM_SETFONT message may have to retrieve the font metrics for the text and recalculate the size of the edit control.

Selecting an Edit Control

The user can select an edit control in three ways: by clicking it with the mouse, by tabbing to it and pressing the SPACEBAR, or (when the edit control is part of a group defined using the WS_GROUP style) by tabbing to the selected edit control in the group and using the arrow keys to move within the group. (The latter two "tabbing" methods are part of a predefined keyboard interface that Windows provides. When the user selects an edit control, Windows gives the control the keyboard focus and highlights its text by using reverse video.

Selecting Text

After selecting an edit control, the user can select text in the control by using the mouse or the keyboard. An application can retrieve the starting and ending character positions of the current selection in an edit control by sending the control an EM_GETSEL message. The return value for the ending position is one greater than the last character in the selection (that is, the position of the first character following the last selected character).

An application can also select text in an edit control by sending the control an EM_SETSEL message with the starting and ending character indices for the selection. For example, the application can use EM_SETSEL with EM_REPLACESEL to delete text from an edit control.

These three messages apply to both single-line and multiline edit controls.

Replacing Text

An application can replace selected text in an edit control by sending the control an EM_REPLACESEL message with a pointer to the replacement text. If there is no current selection, EM_REPLACESEL inserts the replacement text at the insertion point. The application may receive an EN_ERRSPACE message if the replacement text exceeds the available memory. This message applies to both single-line and multiline edit controls.

An application can use EM_REPLACESEL to replace part of an edit control's text or the SetDlgItemText function to replace all of it.

Cut, Copy, Paste, and Clear Operations

Windows provides four messages for moving text between an edit control and the Clipboard. The WM_COPY message copies the current selection (if any) from an edit control to the Clipboard without deleting it from the edit control. The WM_CUT message deletes the current selection, if any, in the edit control and copies the deleted text to the Clipboard. The WM_CLEAR message deletes the current selection (if any) from an edit control, but does not copy it to the Clipboard (unless the user pressed the SHIFT key). The WM_PASTE message copies text from the Clipboard into an edit control at the insertion point. These four messages apply to both single-line and multiline edit controls.

Modifying Text

The user can select, delete, or move text in an edit control. Windows maintains an internal flag for each edit control indicating whether the contents of the control have been modified. Windows clears this flag when it creates the control and sets the flag whenever the text in the control is modified. An application can retrieve the modification flag by sending the control an EM_GETMODIFY message and set or clear the modification flag by sending the control an EM_SETMODIFY message. These messages apply to both single-line and multiline edit controls.

Limiting User-Entered Text

The default limit to the amount of text a user can enter in an edit control is 32 kilobytes. An application can change the amount of text the user can enter by sending the control an EM_LIMITTEXT message. This message sets a hard limit to the number of bytes the user can enter into an edit control, but affects neither text in the control when the message was sent nor text copied to the control by the SetDlgItemText function. For example, suppose that the application uses the SetDlgItemText function to place 500 bytes in an edit control, and the user also enters 500 bytes (1000 bytes total). If the application then sends an EM_LIMITTEXT message limiting user-entered text to 300 bytes, the 1000 bytes already in the edit control remain there, and the user cannot add any more text (having entered 500 bytes already). On the other hand, if the application sends an EM_LIMITTEXT message limiting user-entered text to 1300 bytes, the 1000 bytes remain, but the user can add 800 more bytes (having entered only 500 bytes).

When the user reaches the character limit of an edit control, Windows sends the application a WM_COMMAND message containing an EN_MAXTEXT notification message. This notification message does not mean that memory has been exhausted, but that the limit for user-entered text has been reached and the user cannot enter any more text. To change this limit, an application must send the control a new EM_LIMITTEXT message with a higher limit.

As an example of the use of EM_LIMITTEXT and EN_MAXTEXT, suppose that the application must limit the user to no more than four characters in an edit control. The application would use EM_LIMITTEXT to specify a four-character limit. If the user tried to enter a fifth character, Windows would send an EN_MAXTEXT notification message to the application.

Character and Line Operations

The Win32 application programming interface (API) provides several messages that return information about the characters and lines in an edit control. Most of the messages return an index, usually a zero-based number, to refer to a character or line. Given this, a single-line edit control containing n characters, the line index is zero and the characters are indexed from zero to n - 1. In a multiline edit control containing m lines and n characters, the lines are indexed from zero to m - 1, and the characters are indexed from zero to n - 1. Note that character indexing ignores line breaks.

An application can determine the number of characters in an edit control by sending the WM_GETTEXTLENGTH message to the edit control. This message returns the length, in characters (not including the terminating null character), of the text in a single-line or multiline edit control. The EM_LINELENGTH message returns the length, in characters, of a line specified by the character index of a character in the line. The returned length does not include any selected characters. An application can use these messages in a single-line or multiline edit control.

The EM_GETFIRSTVISIBLELINE message returns the zero-based index of the uppermost visible line in a multiline edit control, or the zero-based index of the first visible character in a single-line edit control. An application can copy a line from an edit control to a buffer by sending the EM_GETLINE message to the edit control. The line is specified by its line index and the first word of the receiving buffer contains the maximum number of bytes to be copied to the buffer. The return value is the number of bytes copied. This message can also be used in a single-line or multiline edit control.

There are unique messages available to return the information about a line in a multiline edit control. The EM_GETLINECOUNT message returns the number of lines in an edit control. An application can determine the index of a character in a specific line by using the EM_LINEFROMCHAR and EM_LINEINDEX messages. The EM_LINEFROMCHAR message returns the index of the line containing a specified character index. This message is the reverse of the EM_LINEINDEX message, which returns the index of the first character in a specified line.

Scrolling Text

An application can implement scrolling in an edit control by using the automatic scrolling styles discussed in Edit Control Styles, or by explicitly adding scroll bars to the control. To add a horizontal scroll bar, use the style WS_HSCROLL; to add a vertical scroll bar, use the style WS_VSCROLL. An edit control with scroll bars processes its own scroll bar messages.

Windows provides two messages that an application can send to an edit control with scroll bars. The EM_LINESCROLL message scrolls a multiline edit control vertically, or horizontally if the control has the ES_LEFT style. The lParam parameter specifies the number of lines to scroll vertically starting from the current line and the wParam parameter specifies the number of characters to scroll horizontally, starting from the current character. The edit control doesn't acknowledge horizontal scrolling messages if it has the ES_CENTER or ES_RIGHT style. This message applies to multiline edit controls only.

The EM_SCROLL message scrolls a multiline edit control vertically, which is the same effect as sending a WM_VSCROLL message. The wParam parameter specifies the scrolling action. The EM_SCROLL message applies to multiline edit controls only.

The EM_SCROLLCARET message scrolls the caret into view in an edit control. This was done in previous versions of Windows by specifying fScroll = FALSE in an EM_SETSEL message. A Win32 application should use the EM_SCROLLCARET message for the task.

Tab Stops

An application can set tab stops in a multiline edit control by using the EM_SETTABSTOPS message. (The default for a tab stop is eight characters.) When an application adds text to the edit control, tab characters in the text automatically generate space up to the next tab stop. The EM_SETTABSTOPS message does not automatically cause Windows to redraw the text. To do that, an application can call the InvalidateRect function. The EM_SETTABSTOPS message applies to multiline edit controls only.

Password Characters

An application can use a password character in an edit control to conceal user input. When a password character is set, it is displayed in place of each character the user types. When a password character is removed, the control displays the characters the user types. If the application creates an edit control using the style ES_PASSWORD, the default password character is an asterisk (*). An application can use the EM_SETPASSWORDCHAR message to remove or define a different password character and the EM_GETPASSWORDCHAR message to retrieve the current password character. These messages apply to single-line edit controls only.

Using Integers

Windows provides two integer-conversion functions for edit controls designed to contain numbers only. The SetDlgItemInt function creates the string representation of a specified integer (signed or unsigned) and sends the string to an edit control. SetDlgItemInt returns no value. The GetDlgItemInt function creates an integer (signed or unsigned) from its string representation in an edit control. GetDlgItemInt returns the integer (or an error code).

Undoing Text Operations

Every edit control maintains an undo flag that indicates whether an application can reverse (undo) the most recent operation on the edit control (to undo a text deletion, for example). The edit control sets the undo flag to indicate that the operation can be undone and resets it to indicate that the operation cannot be undone. An application can determine the setting of the undo flag by sending the control an EM_CANUNDO message.

An application can undo the most recent operation by sending the control an EM_UNDO message. An operation can be undone provided no other edit control operation occurs first. For example, the user can delete text, replace the text (undo the deletion), and then delete the text again (undo the replacement). The EM_UNDO message applies to both single-line and multiline edit controls and always works for single-line edit controls.

An application can reset an edit control's undo flag by sending the control an EM_EMPTYUNDOBUFFER message. Windows automatically resets the undo flag whenever an edit control receives an EM_SETHANDLE or WM_SETTEXT message. The SetDlgItemText function sends a WM_SETTEXT message.

Wordwrap Functions

An application can use wordwrap functions with multiline edit controls to locate the word or word fragment that should be wrapped to the next line. Using the default wordwrap function provided by Windows, lines always end at the spaces between words. An application can specify its own wordwrap function by supplying a EditWordBreakProc wordwrap function and sending an edit control an EM_SETWORDBREAKPROC message. An application can retrieve the address of the current wordwrap function by sending the control an EM_GETWORDBREAKPROC message.

An application may direct a multiline edit control to add or remove a soft line-break character (two carriage returns and a linefeed) automatically at the end of wrapped text lines. An application can turn this feature on or off by sending the edit control an EM_FMTLINES message. This message applies only to multiline edit controls and does not affect a line that ends with a hard line break (one carriage return and a linefeed entered by the user).


Messages From Edit Controls

Edit Control Notifications

The user makes editing requests by using the keyboard and mouse. Windows sends each request to the edit control's parent window in the form of a WM_COMMAND message. The message includes the edit control identifier in the low-order word of the wParam parameter, the handle of the edit control in the lParam parameter, and an edit control notification message corresponding to the user's action in the high-order word of the wParam parameter.

Portability issue:	In Microsoft® Windows NT™, the placement of the notification code in a notification message has moved from the lParam parameter to the wParam parameter. Windows 3.x applications that process notification messages must modify this code when porting to Windows NT.

An application should examine each notification message and respond appropriately. The following table lists each edit control notification message and the action that generates it.

Notification message	User action

EN_CHANGE	The user has modified text in an edit control. Windows updates the display before sending this message (unlike EN_UPDATE).

EN_ERRSPACE	The edit control cannot allocate enough memory to meet a specific request.

EN_HSCROLL	The user has clicked the edit control's horizontal scroll bar. Windows sends this message before updating the screen.

EN_KILLFOCUS	The user has selected another control.

EN_MAXTEXT	While inserting text, the user has exceeded the specified number of characters for the edit control. Insertion has been truncated. This message is also sent either when an edit control does not have the ES_AUTOHSCROLL style and the number of characters to be inserted exceeds the width of the edit control or when an edit control does not have the ES_AUTOVSCROLL style and the total number of lines to be inserted exceeds the height of the edit control.

EN_SETFOCUS	The user has selected this edit control.

EN_UPDATE	The user has altered the text in the edit control and Windows is about to display the new text. Windows sends this message after formatting the text, but before displaying it, so that the application can resize the edit control window.

EN_VSCROLL	The user has clicked the edit control's vertical scroll bar. Windows sends this message before updating the screen.

In addition, the system sends a WM_CTLCOLOREDIT message to an edit control's parent window before the edit control is drawn. This message contains a handle of the edit control's display context and a handle of the child window. The parent window can use these handles to change the edit control's text and background colors.


Default Edit-control Behavior

Default Message Processing

The window procedure for the predefined edit control window class carries out default processing for all messages that the edit control procedure does not process. When the edit control procedure returns FALSE for any message, the predefined window procedure checks the messages and carries out the following default actions.

Message	Default action

EM_CANUNDO	Returns TRUE if the edit control operation can be undone.

EM_EMPTYUNDOBUFFER	Empties the undo buffer and sets the undo flag retrieved by the EM_CANUNDO message to FALSE. Windows automatically clears the undo flag whenever the edit control receives a WM_SETTEXT or EM_SETHANDLE message.

EM_FMTLINES	Adds or removes soft line-break characters (two carriage returns and a linefeed) to the ends of wrapped lines in a multiline edit control. It is not processed by single-line edit controls.

EM_GETFIRSTVISIBLELINE	Returns the zero-based index of the first visible character in a single-line edit control or the zero-based index of the uppermost visible line in a multiline edit control.

EM_GETHANDLE	Returns a handle identifying the buffer containing the multiline edit control's text. It is not processed by single-line edit controls.

EM_GETLINE	Copies characters in a single-line edit control to a buffer and returns the number of characters copied. In a multiline edit control, retrieves a line of text from the control and returns the number of characters copied.

EM_GETLINECOUNT	Returns the number of lines in the edit control.

EM_GETMODIFY	Returns a flag indicating whether the contents of an edit control have been modified.

EM_GETPASSWORDCHAR	Returns the character that edit controls use in conjunction with the ES_PASSWORD style.

EM_GETRECT	Returns the coordinates of the formatting rectangle in an edit control.

EM_GETSEL	Returns the starting and ending character positions of the current selection in the edit control.

EM_GETTHUMB	Unsupported.

EM_GETWORDBREAKPROC	Returns the address of the current wordwrap function in an edit control.

EM_LIMITTEXT	Sets the maximum number of characters the user may enter in the edit control. For single-line edit controls, this value is either 0x7FFFFFFE or the value of the wParam parameter, whichever is smaller. For multiline edit controls, this value is either 0xFFFFFFFF or the value of the wParam parameter, whichever is smaller.

EM_LINEFROMCHAR	Returns the zero-based number of the line in a multiline edit control that contains a specified character index This message is the reverse of the EM_LINEINDEX message. It is not processed by single-line edit controls.

EM_LINEINDEX	Returns the character of a line in a multiline edit control. This message is the reverse of the EM_LINEFROMCHAR message. It is not processed by single-line edit controls.

EM_LINELENGTH	Returns the length, in characters, of a single-line edit control. In a multiline edit control, returns the length, in characters, of a specified line.

EM_LINESCROLL	Scrolls the text vertically in a single-line edit control or horizontally in a multiline edit control (when the control has the ES_LEFT style). The lParam parameter specifies the number of lines to scroll vertically, starting from the current line. The wParam parameter specifies the number of characters to scroll horizontally, starting from the current character.

EM_MSGMAX	Unsupported.

EM_REPLACESEL	Replaces the current selection with the text in an application-supplied buffer, sends the parent window EN_UPDATE and EN_CHANGE messages, and updates the undo buffer.

EM_SCROLL	Scrolls the text vertically in a multiline edit control. This message is equivalent to sending a WM_VSCROLL message to the edit control. It is not processed by single-line edit controls.

EM_SCROLLCARET	Scrolls the caret into view in an edit control. In previous versions of Windows this was done via EM_SETSEL using particular parameters. A Win32 application should use EM_SCROLLCARET.

EM_SETFONT	Unsupported.

EM_SETHANDLE	Sets a handle to the memory used as a text buffer, empties the undo buffer, resets the scroll positions to zero, and redraws the window.

EM_SETMODIFY	Sets or clears the modification flag to indicate whether the edit control has been modified.

EM_SETPASSWORDCHAR	Defines the character that edit controls use in conjunction with the ES_PASSWORD style.

EM_SETREADONLY	Sets or removes the read-only style (ES_READONLY) in an edit control.

EM_SETRECT	Sets the formatting rectangle for the multiline edit control and redraws the window. It is not processed by single-line edit controls.

EM_SETRECTNP	Sets the formatting rectangle for the multiline edit control but does not redraw the window. It is not processed by single-line edit controls.

EM_SETSEL	Selects a range of characters in the edit control by setting the starting and ending positions to be selected.

EM_SETTABSTOPS	Sets tab-stop positions in the multiline edit control. It is not processed by single-line edit controls.

EM_SETWORDBREAKPROC	Replaces the default wordwrap function with an application-defined wordwrap function.

EM_UNDO	Removes any text that was just inserted or inserts any deleted characters and sets the selection to the inserted text. If necessary, sends the EN_UPDATE and EN_CHANGE notification messages to the parent window.

WM_CHAR	Writes a character to the single-line edit control and sends the EN_UPDATE and EN_CHANGE notification messages to the parent window. Writes a character to the multiline edit control. Handles the accelerator keys for standard functions, such as CTRL+C for copying and CTRL+V for pasting. In multiline edit controls, also processes TAB, and CTRL+TAB keystrokes to move among the controls in a dialog box and to insert tabs into multiline edit controls. Uses the MessageBeep function for illegal characters.

WM_CLEAR	Clears the current selection, if any, in an edit control. If there is no current selection, deletes the character to the right of the caret. If the user presses the SHIFT key, this cuts the selection to the Clipboard, or deletes the character to the left of the caret when there is no selection. If the user presses the CTRL key, this deletes the selection, or deletes to the end of the line when there is no selection.

WM_COPY	Copies text to the Clipboard unless the style is ES_PASSWORD, in which case the message returns zero.

WM_CREATE	Creates the edit control and notifies the parent window with TRUE for success or -1 for failure.

WM_CUT	Cuts the selection to the Clipboard, or deletes the character to the left of the cursor if there is no selection.

WM_ENABLE	Causes the rectangle to be redrawn in gray for single-line edit controls. Returns the enabled state for single-line and multiline edit controls.

WM_ERASEBKGND	Fills the multiline edit control window with the current color of the edit control.

WM_GETDLGCODE	Returns the following values: DLGC_WANTCHARS, DLGC_HASSETSEL, and DLGC_WANTARROWS. In multiline edit controls, it also returns DLGC_WANTALLKEYS. If the user presses ALT+BACKSPACE, it also returns DLGC_WANTMESSAGE.

WM_GETFONT	Returns the handle of the font being used by the control, or NULL if the control uses the system font.

WM_GETTEXT	Copies the specified number of characters to a buffer and returns the number of characters copied.

WM_GETTEXTLENGTH	Returns the length, in characters, of the text in an edit control. The length does not include the null- terminating character.

WM_HSCROLL	Scrolls the text in a multiline edit control horizontally and handles scroll box movement.

WM_KEYDOWN	Performs standard processing of the virtual-key codes.

WM_KILLFOCUS	Removes the keyboard focus of an edit control window, destroys the caret, hides the current selection, and notifies the parent window that the edit control has lost the focus.

WM_LBUTTONDBLCLK	Clears the current selection and selects the word under the cursor. If the SHIFT key is down, extends the selection to the word under the cursor.

WM_LBUTTONDOWN	Changes the current insertion point. If the SHIFT key is down, it extends the selection to the position of the cursor. In multiline edit controls, also sets the timer to automatically scroll when the user holds down the mouse button outside the multiline edit control window.

WM_LBUTTONUP	Releases the mouse capture and sets the text insertion point in the single-line edit control. In a multiline edit control, it also kills the timer set in the WM_LBUTTONDOWN message.

WM_MOUSEMOVE	Changes the current selection in the single-line edit control, if the mouse button is down. In a multiline edit controls, also sets the timer to automatically scroll if the user holds down the mouse button outside the multiline edit control window.

WM_NCCREATE	Points to the CREATESTRUCT structure for the window. This message is sent to the WM_CREATE message when a window is first created.

WM_NCDESTROY	Frees all memory associated with the edit control window, including the text buffer, undo buffer, tab-stop buffer, and highlight brush.

WM_PAINT	Erases the background, fills the window with the current color of the edit control window, draws the border (if any), sets the font and draws any text, and shows the text-insertion caret.

WM_PASTE	Pastes text from the Clipboard into the edit control window at the caret position.

WM_SETFOCUS	Sets the keyboard focus of an edit control window (shows the current selection, if it was hidden, and creates the caret).

WM_SETFONT	Sets the font and optionally redraws the edit control.

WM_SETTEXT	Copies text to the single-line edit control, notifies the parent window when there is insufficient memory, empties the undo buffer, and sends the EN_UPDATE and EN_CHANGE notification messages to the parent window. In multiline edit controls, also rewraps the lines (if necessary) and sets the scroll positions.

WM_SIZE	Changes the size of the edit control window and ensures that the minimum size accommodates the height and width of a character.

WM_SYSCHAR	Returns TRUE if the user presses ALT+BACKSPACE; otherwise, it takes no action.

WM_SYSKEYDOWN	Undoes the last action if the user presses ALT+BACKSPACE; otherwise, it takes no action.

WM_TIMER	Scrolls the text in the edit control window if the user holds down the mouse button outside the multiline edit control window.

WM_UNDO	Removes any text that was just inserted or inserts any deleted characters and sets the selection to the inserted text. If necessary, sends the EN_UPDATE and EN_CHANGE notification messages to the parent window.

WM_VSCROLL	Scrolls a multiline edit control vertically and handles scroll box movement. It is not processed by single-line edit controls.

The predefined edit control window procedure passes all other messages to the DefWindowProc function for default processing.


Using Edit Controls

Edit controls are typically used in dialog boxes, but you can use them in the client area of a standard window as well. Single-line edit controls are useful for retrieving a single string from the user. Multiline edit controls make it easy for your application to implement most of the features of a simple word processor.


Simple Word Processing with an Edit Control

The following code sample implements much of the functionality of a simple word processor by filling the client area of a window with a multiline edit control. The system automatically performs wordwrap operations for this edit control and also handles the processing for the vertical scroll bar (created by specifying ES_AUTOVSCROLL in the call to the CreateWindow function). The WM_COMMAND message processes menu items; they allow the user to undo the previous action, cut or copy selections to the Clipboard, paste text from the Clipboard, and delete the current selection.

LONG APIENTRY MainWndProc(

HWND hwnd,                /* window handle                   */

UINT message,             /* type of message                 */

UINT wParam,              /* additional information          */

LONG lParam)              /* additional information          */

{

    static HWND hwndEdit;

    CHAR lpszTrouble[] = "When in the Course of human Events "

                         "it becomes necessary for one People "

                         "to dissolve the Political Bands which "

                         "have connected them with another, and "

                         "to assume among the Powers of the "

                         "Earth, the separate and equal Station "

                         "to which the Laws of Nature and of "

                         "Nature's God entitle them, a decent "

                         "Respect to the Opinions of Mankind "

                         "requires that they should declare the "

                         "causes which impel them to the "

                         "Separation. ";

    switch (message) {

        case WM_CREATE:

            hwndEdit = CreateWindow(

                "EDIT",     /* predefined class                  */

                NULL,       /* no window title                   */

                WS_CHILD | WS_VISIBLE | WS_VSCROLL |

                    ES_LEFT | ES_MULTILINE | ES_AUTOVSCROLL,

                0, 0, 0, 0, /* set size in WM_SIZE message       */

                hwnd,       /* parent window                     */

                (HMENU) ID_EDITCHILD, /* edit control ID         */

                (HINSTANCE) GetWindowLong(hwnd, GWL_HINSTANCE),

                NULL);                /* pointer not needed      */

             /* Add text to the window. */

             SendMessage(hwndEdit, WM_SETTEXT, 0,

                (LPARAM) lpszTrouble);

            return 0;

        case WM_COMMAND:

            switch (wParam) {

                case IDM_EDUNDO:

                   SingleLine

                     /*

                     * Send WM_UNDO only if there is something

                     * to be undone.

                     */

                    if (SendMessage(hwndEdit, EM_CANUNDO, 0, 0))

                        SendMessage(hwndEdit, WM_UNDO, 0, 0);

                    else

                        MessageBox(hwndEdit,

                            "Nothing to undo.",

                            "Undo notification", MB_OK);

                    break;

                case IDM_EDCUT:

                    SendMessage(hwndEdit, WM_CUT, 0, 0);

                    break;

                case IDM_EDCOPY:

                    SendMessage(hwndEdit, WM_COPY, 0, 0);

                    break;

                case IDM_EDPASTE:

                    SendMessage(hwndEdit, WM_PASTE, 0, 0);

                    break;

                case IDM_EDDEL:

                    SendMessage(hwndEdit, WM_CLEAR, 0, 0);

                    break;

                default:

                    return DefWindowProc(hwnd, message, wParam, lParam);

            }

            break;

        case WM_SETFOCUS:

            SetFocus(hwndEdit);

            return 0;

        case WM_SIZE:

            /*

             * Make the edit control the size of the window's

             * client area.

             */

            MoveWindow(hwndEdit,

                0, 0,           /* starting x- and y-coordinates */

                LOWORD(lParam), /* width of client area          */

                HIWORD(lParam), /* height of client area         */

                TRUE);          /* repaint window                */

            return 0;

        case WM_DESTROY:

            PostQuitMessage(0);

            return 0;

        default:

            return DefWindowProc(hwnd, message, wParam, lParam);

    }

    return NULL;

}


Using Single-Line Edit Controls

The code sample in this section demonstrates how to use a window procedure to produce a dialog box, as shown in the following illustration.

The single-line edit control in the Password dialog box has the ES_PASSWORD style. By default, edit controls with this style display an asterisk for each character the user types. This example, however, uses the EM_SETPASSWORDCHAR message to change the default character from an asterisk to a plus sign (+).

This window procedure changes the default push button from Cancel to OK as soon as the user enters text in the edit control. If the user presses the OK button, the window procedure uses the EM_LINELENGTH and EM_GETLINE messages to retrieve the text.

LRESULT CALLBACK PassProc(hDlg, message, wParam, lParam)

HWND hDlg;                /* window handle of the dialog box */

UINT message;             /* type of message                 */

UINT wParam;              /* message-specific information    */

LONG lParam;

{

    CHAR lpszPassword[16];

    WORD cchPassword;

    switch (message) {

        case WM_INITDIALOG:

            /* Set password character to a plus sign (+) */

            SendDlgItemMessage(hDlg,

                IDE_PASSWORDEDIT,

                EM_SETPASSWORDCHAR,

                (WPARAM) '+',

                (LPARAM) 0);

            /* Set the default push button to "Cancel." */

            SendMessage(hDlg,

                DM_SETDEFID,

                (WPARAM) IDCANCEL,

                (LPARAM) 0);

            return TRUE;

        case WM_COMMAND:

            /*

             * Set the default push button to "OK" when the user

             * enters text.

             */

            if(HIWORD (wParam) == EN_CHANGE &&

                    LOWORD(wParam) == IDE_PASSWORDEDIT)

                SendMessage(hDlg,

                    DM_SETDEFID,

                    (WPARAM) IDOK,

                    (LPARAM) 0);

            switch(wParam) {

                case IDOK:

                    /* Get number of characters. */

                    cchPassword = (WORD) SendDlgItemMessage(hDlg,

                        IDE_PASSWORDEDIT,

                        EM_LINELENGTH,

                        (WPARAM) 0,

                        (LPARAM) 0);

                    if (cchPassword >= 16) {

                        MessageBox(hDlg,

                            "Too many characters.",

                            "Error",

                            MB_OK);

                        EndDialog(hDlg, TRUE);

                        return FALSE;

                    }

                    else if (cchPassword == 0) {

                        MessageBox(hDlg,

                            "No characters entered.",

                            "Error",

                            MB_OK);

                        EndDialog(hDlg, TRUE);

                        return FALSE;

                    }

                    /*

                     * Put the number of characters into first word

                     * of buffer.

                     */

                    *((LPWORD)lpszPassword) = cchPassword;

                    /* Get the characters. */

                    SendDlgItemMessage(hDlg,

                        IDE_PASSWORDEDIT,

                        EM_GETLINE,

                        (WPARAM) 0,       /* line 0 */

                        (LPARAM) lpszPassword);

                    /* Null-terminate the string. */

                    lpszPassword[cchPassword] = 0;

                    /* Call a local password-parsing function. */

                    ParsePassword(lpszPassword);

                    EndDialog(hDlg, TRUE);

                    return TRUE;

                case IDCANCEL:

                    EndDialog(hDlg, TRUE);

                    return TRUE;

            }

            return 0;

    }

    return FALSE;

        UNREFERENCED_PARAMETER(lParam);

}


Functions and Messages

Following are the function and messages used with edit controls.

Function

EditWordBreakProc

Messages

EM_CANUNDO

EM_EMPTYUNDOBUFFER

EM_FMTLINES

EM_GETFIRSTVISIBLELINE

EM_GETHANDLE

EM_GETLINE

EM_GETLINECOUNT

EM_GETMODIFY

EM_GETPASSWORDCHAR

EM_GETRECT

EM_GETSEL

EM_GETWORDBREAKPROC

EM_LIMITTEXT

EM_LINEFROMCHAR

EM_LINEINDEX

EM_LINELENGTH

EM_LINESCROLL

EM_REPLACESEL

EM_SCROLL

EM_SCROLLCARET

EM_SETHANDLE

EM_SETMODIFY

EM_SETPASSWORDCHAR

EM_SETREADONLY

EM_SETRECT

EM_SETRECTNP

EM_SETSEL

EM_SETTABSTOPS

EM_SETWORDBREAKPROC

EM_UNDO

EN_CHANGE

EN_ERRSPACE

EN_HSCROLL

EN_KILLFOCUS

EN_MAXTEXT

EN_SETFOCUS

EN_UPDATE

EN_VSCROLL

WM_COMMAND

WM_COPY

WM_CTLCOLOREDIT

WM_CUT

WM_PASTE

WM_UNDO


Combo Boxes Overview

About Combo Boxes

As discussed in Controls, control boxes and controls provide users of the Microsoft® Windows™ operating system with the means to enter text, choose options, and complete actions. A combo box, however, is a unique type of control. It is defined by the COMBOBOX class and combines much of the functionality of a list box and an edit control.

Windows provides three types of combo box: simple combo boxes (CBS_SIMPLE), drop-down combo boxes (CBS_DROPDOWN), and drop-down list boxes (CBS_DROPDOWNLIST).

There are also a number of combo box styles that define specific properties. For example, two styles enable an application to create an owner-drawn combo box, making the application responsible for displaying information in the control.

A combo box consists of a list and a selection field. The list presents the options a user can select and the selection field displays the current selection. Except in drop-down list boxes, the selection field is an edit control and can be used to enter text not in the list.

Combo boxes are used primarily in dialog boxes. Dialog boxes can process keyboard input messages that combo boxes cannot, such as the TAB, ENTER, and ESCAPE keys. However, an application can provide this functionality outside a dialog box by using window subclassing. For more information about dialog boxes, see Dialog Boxes.

This topic describes the types and styles of combo box, the parts of a combo box, the use of an owner-drawn combo box, and how to subclass a combo box. Additional features of combo boxes are also discussed.

The following topics discuss combo boxes:

Terms

Combo Box Types and Styles

Combo Box List

Edit Control Selection Fields

Owner-Drawn Combo Boxes

Subclassing Combo Boxes

Special Combo-Box Features

Combo Box Notifications

Default Message Processing

Creating a Simple Combo Box

Creating an Owner-Drawn Combo Box

Subclassing a Combo Box

Functions and Messages


Combo Box Types and Styles

Combo boxes can be characterized by type and style. Combo box types determine whether the combo box list is a drop-down list and whether the selection field is an edit control. A drop-down list appears only when the user opens it, so it uses less screen space than a list that is always visible. If the selection field is an edit control, the user can enter information not in the list; otherwise, the user can only select items in the list.

The following table shows the three combo box types and indicates whether each includes a drop-down list and an edit control.

Combo box type	Drop-down list	Edit control

Simple combo box	No	Yes

Drop-down combo box	Yes	Yes

Drop-down list box	Yes	No

Combo box styles define specific properties of a combo box. An application can combine styles; however some styles only apply to certain combo box types. The following table describes the combo box styles.

Style	Desription

CBS_AUTOHSCROLL	Automatically scrolls text to the left when the user types beyond the right end of the selection field. If an application does not specify this style, only text that fits within the edit control is allowed. This style does not apply to drop-down list boxes.

CBS_DISABLENOSCROLL	Displays a scroll bar in the list even if the entire contents are visible at once. Ordinarily, the scroll bar only appears if the list contains enough items to scroll through.

CBS_HASSTRINGS	Keeps track of strings for list items in an owner-drawn combo box. For more information, see Owner-Drawn Combo Boxes.

CBS_NOINTEGRALHEIGHT	Specifies that the combo box is exactly the size set forth by the application when it created the combo box. Ordinarily, Windows adjusts the size of a combo box so it does not display partial items.

CBS_OEMCONVERT	Specifies that text in the selection field is in the OEM character set. Windows automatically converts text to and from the OEM character set as it is entered in and retrieved from the selection field. This style does not apply to drop-down list boxes.

CBS_OWNERDRAWFIXED	Assigns responsibility for displaying information to the parent window or dialog box procedure It specifies that list items are all the same size. For more information, see Owner-Drawn Combo Boxes.

CBS_OWNERDRAWVARIABLE	Assigns responsibility for displaying information to the parent window or dialog box procedure It specifies that list items vary in size. For more information, see Owner-Drawn Combo Boxes.

CBS_SORT	Automatically sorts the contents of the list. An application can ensure that sorted combo box items are correct for a given language and sublanguage by using CB_SETLOCALE message. To retrieve the current locale for a combo box, use the CB_GETLOCALE message.


Combo Box List

The list is the portion of a combo box that displays the items a user can select. Typically, an application initializes the contents of the list when it creates a combo box. Any list item selected by the user is the current selection. In simple and drop-down combo boxes, the user can type in the selection field instead of selecting a list item. In these cases, there is no current selection. For more information, see Edit Control Selection Fields.

List Contents

When an application creates a combo box, it typically initializes the combo box by adding one or more strings to the list. Later, an application may add or delete list items reinitialize the list, or retrieve strings from it.

An application adds list items to a combo box by sending the CB_ADDSTRING message to it. The specified string is added to the end of the list or, in a sorted combo box, in its correct sorted position. In an unsorted combo box, an application can use the CB_INSERTSTRING message to insert a string at a specific position. Once added, a list item is identified by its position.

An application can determine the position of a list item by using the CB_FINDSTRING or CB_FINDSTRINGEXACT message. The CB_FINDSTRING message finds an item beginning with the specified string. The CB_FINDSTRINGEXACT message finds an item that matches the string exactly. Neither message is case sensitive.

An application can remove a list item by using the CB_DELETESTRING message. If an application needs to reinitialize the combo box list, it can first clear its entire contents by using the CB_RESETCONTENT message. When adding multiple strings to the list after a combo box has already been shown, an application can clear the redraw flag to prevent the combo box from being repainted after each string is added. For more information, see the WM_SETREDRAW message.

To retrieve the text for a list entry, an application can use the CB_GETLBTEXT message. The string is copied to the buffer specified by the application. To ensure that the buffer is large enough to receive the string, the application can first use the CB_GETLBTEXTLEN message to determine the length of the string. To get the number of list items in a combo box, an application can use the CB_GETCOUNT message.

Current Selection

The current selection is a list item the user has selected; the selected text appears in the selection field edit control in the combo box. However, the current selection is only one form of possible user input in a combo box. The user can also type text in the selection field. In a drop-down list box, the current selection is the only form of user input.

The current selection is identified by the zero-based index of the selected list item. An application can set and retrieve it at any time. The parent window or dialog box procedure receives notifications when the current selection for a combo box changes.

When a combo box is created, there is no current selection. This is also true for a simple or drop-down combo box if the user has edited the contents of the selection field. To set the current selection, an application sends the CB_SETCURSEL message to the combo box. An application can also use the CB_SELECTSTRING message to set the current selection to a list item beginning with a specified string. To determine the current selection, an application sends the CB_GETCURSEL message to the combo box. If there is no current selection, this message returns CB_ERR.

When the current selection in a combo box changes, the parent window or dialog-box procedure receives a WM_COMMAND message with the CBN_SELCHANGE notification code in the high-order word of wParam. As a result, the application can respond to this notification message and execute a specific process each time the user selects a list item. This notification is not sent when the current selection is set using the CB_SETCURSEL message nor when the user modifies the current selection in a simple or drop-down combo box.

In a drop-down combo box or drop-down list box, an application can close the list and wait to process a change in the current selection until the user selects a new item. This can be useful when significant processing is required. For example, to update a directory list based on the selected drive, an application can process the CBN_CLOSEUP message instead of CBN_SELCHANGE to update a directory list after the user selects a drive.

Alternatively, an application can process the CBN_SELENDOK and CBN_SELENDCANCEL messages. The system sends the CBN_SELENDOK notification when the user clicks a list item or selects an item and then closes the list. This indicates the user has finished and the selection should be processed. The CBN_SELENDCANCEL notification is sent when the user selects an item but then selects another control or closes the dialog box. This indicates the user's selection should be ignored. In a simple combo box, a CBN_SELENDOK notification is sent before every CBN_SELCHANGE message. The system does not send the CBN_SELENDOK and CBN_SELENDCANCEL messages if the WS_EX_NOPARENTNOTIFY extended window style is specified for the combo box.

In a simple combo box, the system sends the CBN_DBLCLK notification when the user double-clicks a list item. In a drop-down combo box or drop-down list, however, a single click hides the list so it is not possible to double-click an item.

Drop-Down Lists

Certain notifications and messages apply only to combo boxes containing drop-down lists. When a drop-down list is open or closed, the parent window of a combo box receives a notification in the form of a WM_COMMAND message. If the list is being opened, the high-order word of wParam is CBN_DROPDOWN. If the list is being closed, it is CBN_CLOSEUP.

An application can open the list of a drop-down combo box or drop-down list box by using the CB_SHOWDROPDOWN message. It can determine whether the list is open by using the CB_GETDROPPEDSTATE message and can determine the coordinates of a drop-down list by using the CB_GETDROPPEDCONTROLRECT message.


Edit Control Selection Fields

The selection field is the portion of a combo box that displays the currently selected list item. In simple and drop-down combo boxes, the selection field is an edit control and can be used to enter text that is not in the list.

An application can retrieve or set the contents of the selection field and can determine or set the edit selection. The application can also limit the amount of text a user can type in the selection field. When the contents of the selection field change, Windows sends notification messages to the parent window or dialog box procedure.

To retrieve the contents of the selection field of a simple or drop-down combo box, an application can send the WM_GETTEXT message to the combo box. To set the contents of the selection field, an application can send the WM_SETTEXT message to the combo box.

The edit selection is the range of selected text, if any, in the selection field of a simple or drop-down combo box. An application can determine the starting and ending character positions of the current selection by using the CB_GETEDITSEL message. It can also select characters in the edit selection by using the CB_SETEDITSEL message.

By using the CB_LIMITTEXT message, an application can limit the amount of text a user can type into the selection field.

When the user edits the contents of the selection field, the parent window or dialog box procedure receives notification messages. Windows sends the CBN_EDITUPDATE notification first, indicating that the text in the selection field has been edited. After the altered text is displayed, Windows sends the CBN_EDITCHANGE notification. When the contents of the selection field change as the result of a list item being selected, these notifications are not sent.


Owner-Drawn Combo Boxes

An application can create an owner-drawn combo box to take responsibility for painting list items. The parent window or dialog box of an owner-drawn combo box (its owner) receives WM_DRAWITEM messages when a portion of the combo box needs to be painted. An owner-drawn combo box can list information other than, or in addition to, text strings. Owner-drawn combo boxes can be of any type. However, the edit control in a simple or drop-down combo box can only display text, while the owner paints the selection field in a drop-down list box.

The owner of an owner-drawn combo box must process the WM_DRAWITEM message. This message is sent whenever a portion of the combo box must be redrawn. The owner may need to process other messages, depending on the styles specified for the combo box.

An application can create an owner-drawn combo box by specifying the CBS_OWNERDRAWFIXED or CBS_OWNERDRAWVARIABLE style. If all list items in the combo box are the same height, such as strings or icons, an application can use the CBS_OWNERDRAWFIXED style. If list items are of varying height, bitmaps of different size, for example, an application can use the CBS_OWNERDRAWVARIABLE style.

The owner of an owner-drawn combo box can process a WM_MEASUREITEM message to specify the dimensions of list items in the combo box. If the application creates the combo box by using the CBS_OWNERDRAWFIXED style, Windows sends the WM_MEASUREITEM message only once. The dimensions specified by the owner are used for all list items. If the CBS_OWNERDRAWVARIABLE style is used, Windows sends a WM_MEASUREITEM message for each list item added to the combo box. The owner can determine or set the height of a list item at any time by using the CB_GETITEMHEIGHT and CB_SETITEMHEIGHT messages, respectively.

If the information displayed in an owner-drawn combo box includes text, an application can keep track of the text for each list item by specifying the CBS_HASSTRINGS style. Combo boxes with the CBS_SORT style are sorted based on this text. If a combo box is sorted and does not have the CBS_HASSTRINGS style, the owner must process the WM_COMPAREITEM message.

In an owner-drawn combo box, the owner must keep track of list items containing information other than or in addition to text. One convenient way to do this is to save the handle of the information as item data. For more information about item data, see Data Associated With List Items. To free data objects associated with items in a combo box, the owner can process the WM_DELETEITEM message.

For an example of an owner-drawn combo box, see Creating an Owner-Drawn Combo Box.


Subclassing Combo Boxes

Subclassing is a procedure that allows an application to intercept and process messages sent or posted to a window. By using subclassing, an application can substitute its own processing for certain messages, while leaving most message processing to the class-defined window procedure.

When the operating system creates a window, it saves information about it in an internal data structure that includes the address of the window procedure. To subclass a window, an application calls the SetClassLong function to replace the address of that procedure with the instance address of an application-defined subclass procedure. Thereafter, all messages to the window are sent to the subclass procedure. This procedure then uses the CallWindowProc function to pass unprocessed messages to the original window procedure. For a description of the message processing performed by the COMBOBOX class window procedure, see .

When the combo box is outside a dialog box, an application cannot process the TAB, ENTER, and ESCAPE keys unless it uses a subclass procedure. When a simple or drop-down combo box receives the input focus, it immediately sets the focus to its child edit control. Therefore, an application must subclass the edit control to intercept keyboard input for a simple or drop-down combo box. For an example of this, see Subclassing a Combo Box.

If a subclass procedure processes the WM_PAINT message, it must use the BeginPaint function to prepare for painting. Before calling the EndPaint function, it passes the device-context handle as the wParam parameter for the window procedure. If EndPaint is called first, the class window procedure does no painting because EndPaint validates the entire window.

A technique related to subclassing is superclassing. A superclass resembles any other class except that its window procedure does not call DefWindowProc to handle unprocessed messages. Instead, it passes unprocessed messages to the window procedure for the parent window class. Follow the guidelines in Window Procedures, to avoid problems that can occur with subclassing and superclassing.


Special Combo-Box Features

Special Combo Box Features

The Win32 API provides special-purpose messages and functions that enable an application to display a directory listing in a combo box, associate data with list items in a combo box, and change the keyboard interface for a drop-down combo box or drop-down list box.

Directory Lists

An application can add the names of files or subdirectories to a combo box by sending the CB_DIR message to it. The wParam parameter for the window procedure specifies the attributes of the files to add, and the lParam parameter points to the text string that defines the file specification.

Within a dialog box, an application can also use the DlgDirListComboBox function. If the specified filename includes a drive, path, or both, the DlgDirListComboBox function changes the current drive or directory and removes the drive and path from the filename string. To show the directory name, the function updates the specified static control, if any. It then resets the contents of the combo box, and sends the CB_DIR message to the combo box to add the specified filenames.

To remove the selected filename, directory name, or drive letter from a combo box that has been filled by using the DlgDirListComboBox function, an application can use the DlgDirSelectComboBoxEx function.

The CB_DIR message and the DlgDirListComboBox and DlgDirSelectComboBoxEx functions are similar to the LB_DIR message and the DlgDirList and DlgDirSelectEx functions used with list boxes.

Data Associated With List Items

An application can associate data with the list items in a combo box. The CB_SETITEMDATA message associates a DWORD value with a list item, and the CB_GETITEMDATA retrieves the value associated with a list item.

The example in Creating an Owner-Drawn Combo Box. uses item data to associate a constant with each item in a drop-down list box. Such a unique value identifies each item independent of its sorted position.

Other applications might use item data to associate a handle or pointer with a list item. If so, an application can process a WM_DELETEITEM message to delete or free the specified object when the list item is deleted.

The Extended User Interface

Drop-down combo boxes and drop-down list boxes support an alternative keyboard interface called the extended user interface. 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, however, the F4 key is disabled and pressing the DOWN ARROW key opens the drop-down list.

To select the user interface for a combo box, an application can send the CB_SETEXTENDEDUI message to the combo box. A TRUE value for the wParam parameter enables the extended user interface; a FALSE value sets the default user interface. To determine whether a combo box uses the extended user interface, an application can send the CB_GETEXTENDEDUI message to the combo box.


Combo Box Notifications

Messages from combo boxes are sent as notifications in the form of WM_COMMAND messages. The notification code is stored in the high word of the wParam parameter and an application can process the following combo box notification messages:

Notification code	Description

CBN_CLOSEUP	Indicates the list in a drop-down combo box or drop-down list box is about to close.

CBN_DBLCLK	Indicates the user has double-clicked a list item in a simple combo box.

CBN_DROPDOWN	Indicates the list in a drop-down combo box or drop-down list box is about to open.

CBN_EDITCHANGE	Indicates the user has changed the text in the edit control of a simple or drop-down combo box. This notification is sent after the altered text is displayed.

CBN_EDITUPDATE	Indicates the user has changed the text in the edit control of a simple or drop-down combo box. This notification is sent before the altered text is displayed.

CBN_ERRSPACE	Indicates the combo box cannot allocate enough memory to carry out a request, such as adding a list item.

CBN_KILLFOCUS	Indicates the combo box is about to lose the input focus.

CBN_SELCHANGE	Indicates the current selection has changed.

CBN_SETFOCUS	Indicates the combo box has received the input focus.


Default Message Processing

Default Combo Box Behavior

This section describes the messages specifically handled by the predefined COMBOBOX class window procedure.

Message	Description

CB_ADDSTRING	Sends an LB_ADDSTRING message to the list window to add a list item.

CB_DELETESTRING	Sends an LB_DELETESTRING message to the list window to delete a list item.

CB_DIR	Adds the filenames matching the specified attributes and path to the list.

CB_FINDSTRING	Sends an LB_FINDSTRING message to the list window. This message returns the index of the first list item that begins with the specified text.

CB_FINDSTRINGEXACT	Sends an LB_FINDSTRING message to the list window. This message returns the index of the first list item exactly matching the specified text.

CB_GETCOUNT	Sends an LB_GETCOUNT message to the list window. It returns the number of list items.

CB_GETCURSEL	Sends an LB_GETCURSEL message to the list window. It returns the index of the currently selected item, if any.

CB_GETDROPPEDCONTROLRECT	Fills the specified rectangle structure with the screen coordinates of a drop-down list.

CB_GETDROPPEDSTATE	Returns TRUE if a drop-down list is open. Otherwise, it returns FALSE.

CB_GETEDITSEL	Sends an EM_GETSEL message to the edit control, and it returns the starting and ending position of the current selection. In drop-down list boxes, the window procedure returns CB_ERR.

CB_GETEXTENDEDUI	Returns TRUE if the combo box is a drop-down combo box or drop-down list box and the extend user-interface flag is set. Otherwise, it returns FALSE.

CB_GETITEMDATA	Sends an LB_GETITEMDATA message to the list window. It returns the 32-bit value associated with the specified list item.

CB_GETITEMHEIGHT	Sends an LB_GETITEMHEIGHT message to the list window. It returns the height, in pixels, of the specified owner-drawn list item.

CB_GETLBTEXT	Sends an LB_GETTEXT message to the list window. It copies the specified list text to the specified buffer.

CB_GETLBTEXTLEN	Sends an LB_GETTEXTLEN message to the list window. It returns the length, in bytes, of the specified list text.

CB_GETLOCALE	Sends an LB_GETLOCALE message to the list window. It returns the current locale for the list.

CB_INSERTSTRING	Sends an LB_INSERTSTRING message to the list window. It inserts a list item at the specified position.

CB_LIMITTEXT	Sends an EM_LIMITTEXT message to the edit control. It sets the maximum number of characters a user can enter in the edit control. In drop-down list boxes, the window procedure returns CB_ERR.

CB_RESETCONTENT	Sends an LB_RESETCONTENT message to the list window, and it removes the contents of the list.

CB_SELECTSTRING	Sends an LB_SELECTSTRING message to the list window. It selects the first list item, if any, that begins with the characters in the specified text.

CB_SETCURSEL	Sends an LB_SETCURSEL message to the list window, and it sets the current selection.

CB_SETEDITSEL	Sends an EM_SETSEL message to the edit control. It selects the specified range of text. In drop-down list boxes, the window procedure returns CB_ERR.

CB_SETEXTENDEDUI	Sets or clears the extended user interface flag. This flag changes the keys that open and close the list in a drop-down combo box or drop-down list box. if the combo box is a simple combo box, the window procedure returns CB_ERR.

CB_SETITEMDATA	Sends an LB_SETITEMDATA message to the list window. It associates the specified 32-bit value with a list item.

CB_SETITEMHEIGHT	Sends an LB_SETITEMHEIGHT message to the list window. It sets the height of the specified owner-drawn list item or the selection field.

CB_SETLOCALE	Sends an LB_SETLOCALE message to the list window, and it sets the current locale for the list. The locale affects how the list is sorted if it has the CBS_SORT style and strings are added using CB_ADDSTRING.

CB_SHOWDROPDOWN	Shows or hides the drop-down list. This message has no effect on simple combo boxes.

WM_CHAR	Processes character input. In drop-down list boxes, this message is passed on to the list window, which moves the selection to the first item beginning with the specified character. In simple and drop-down combo boxes, this message is passed on to the edit control.

WM_CLEAR	Deletes the edit selection. In simple and drop-down combo boxes, the edit control processes this message. In drop-down list boxes, the window procedure returns CB_ERR.

WM_COMMAND	Processes notification messages from the edit control and list window and sends corresponding combo box notifications to the parent window.

For edit control notifications, the window procedure may update the list window's current selection, caret index, and top index. For list notifications, the window procedure may update the contents of the selection field.

WM_COMPAREITEM	Passes the message on to the parent window, enabling the application to specify the relative sort position of two owner-drawn list items. The combo box window receives this message from the list window.

WM_COPY	Copies the edit selection to the clipboard. In simple and drop-down combo boxes, the edit control processes this message. In drop-down list boxes, the window procedure returns CB_ERR.

WM_CREATE	Initializes the combo box.

WM_CUT	Deletes the edit selection and places it on the clipboard. In simple and drop-down combo boxes, the edit control processes this message. In drop-down list boxes, the window procedure returns CB_ERR.

WM_DELETEITEM	Passes the message on to the parent window, notifying the application that a list item has been deleted. The combo box window receives this message from the list window.

WM_DRAWITEM	Passes the message on to the parent window enabling the application to paint the specified list item. The combo box window receives this message from the list window. The window procedure can also originate this message to have the application paint the selection field of a drop-down list box.

WM_ENABLE	Sets the state to enable or prohibit mouse and keyboard input.

WM_ERASEBKGND	Returns 1, indicating that the background is erased.

WM_GETDLGCODE	Returns a combination of the DLG_WANTCHARS and DLGC_WANTARROWS values.

WM_GETFONT	Returns the handle of the current font with which the combo box will draw its text.

WM_GETTEXT	Copies the contents of the selection field to the specified buffer. In simple and drop-down combo boxes, the edit control processes this message.

WM_GETTEXTLENGTH	Returns the length, in characters, of the text in the selection field. In simple and drop-down combo boxes, the edit control processes this message.

WM_KEYDOWN	Processes non-character keyboard input. In drop-down list boxes, this message is passed on to the list window, and it can be open or close, or change the current selection or caret index. In simple and drop-down combo boxes, this message is passed on to the edit control. The edit control passes certain keys to the list window, such as the UP and DOWN ARROW keys and the F4 key.

WM_KILLFOCUS	Hides the highlight in the selection field and closes the drop-down list, if necessary. If the window receiving the input focus is part of the combo box (for example, the edit control), this message is ignored.

WM_LBUTTONDBLCLK	Same as WM_LBUTTONDOWN.

WM_LBUTTONDOWN	Sets the focus to the combo box and, for drop-down combo boxes and drop-down lists, can open or close the list. If it opens the list, the window procedure captures the mouse to enable selection by dragging and releasing the mouse button.

WM_LBUTTONUP	Releases the mouse capture if the mouse opened the list.

WM_MEASUREITEM	Posts the message to the parent window, enabling the application to modify the contents of the specified MEASUREITEMSTRUCT structure. The combo box window receives this message from the list window.

WM_MOUSEMOVE	Posts the message to the list window if the mouse has opened the list and the mouse button is still down. This enables a user to select an item by dragging the mouse pointer to a list item and then releasing the button.

WM_NCCREATE	Allocates an internal data structure used by the combo box window procedure.

WM_NCDESTROY	Frees resources allocated in response to the WM_NCCREATE message.

WM_PAINT	Paints the invalid region of the combo box. If wParam is not NULL, it is assumed to be a device context handle passed from a subclass function. The window procedure uses the specified device context instead of calling BeginPaint and EndPaint.

WM_PASTE	Replaces the edit selection with the contents of the clipboard. In simple and drop-down combo boxes, the edit control processes this message. In drop-down list boxes, the window procedure returns CB_ERR.

WM_SETFOCUS	Sets the focus to the edit control or, in drop-down list boxes, inverts the selection field and turns on the caret in the list window.

WM_SETFONT	Saves the specified font handle in an internal structure, adjusts the dimensions of the selection field and list, and invalidates the combo box window. Text in the selection field and the list is displayed in the saved font.

WM_SETREDRAW	Sets or clears the redraw flag. If the redraw flag is cleared, the combo box is not repainted until the flag is set again.

WM_SETTEXT	Sets the contents of the edit control. In simple and drop-down combo boxes, the edit control processes this message. In drop-down list boxes, the window procedure returns CB_ERR.

WM_SIZE	Resizes the child windows, if necessary.

WM_SYSKEYDOWN	Opens or closes the drop-down list depending on which arrow key the user pressed.

All other messages are passed to the DefWindowProc function for default processing.


Creating a Simple Combo Box

This section describes how to use a simple combo box in a dialog box. The code example in Creating a Spell Dialog Box, uses a simple combo box in a dialog box for a spelling checker. When it finds a misspelled word, the spelling checker suggests alternative spellings. The user can ignore the misspelling, change to one of the suggested spellings, or type a spelling not suggested. A simple combo box is well suited for receiving this kind of user input.

Creating the Dialog Box

The dialog box template defines the window styles, buttons, and control identifiers for the combo box. In this example, the combo box uses the CBS_SIMPLE, CBS_SORT, WS_VSCROLL, and WS_TABSTOP styles.

The dialog box also contains three buttons: Change (IDOK), Ignore (IDSKIP), and Cancel (IDCANCEL). The constants IDOK and IDCANCEL are defined by the Win32 API. The constant IDSKIP is defined in the application's header file, as is the control identifier, IDCOMBO.

For more information about dialog boxes, see Dialog Boxes

Processing the WM_INITDIALOG and WM_DESTROY Messages

When you use a combo box in a dialog box, you usually respond to the WM_INITDIALOG message by initializing the combo box. The code example in Creating a Spell Dialog Box, calls the application-defined OpenDictionary function to load the dictionary. It then calls the application-defined SelectNextWord and InitSpellList functions to select the first misspelled word.

SelectNextWord selects the next word in the edit control and copies it to the specified buffer. InitSpellList determines whether the selected word is in the dictionary. If not, it places the word in the selection field of the combo box and adds suggested spellings to the list.

The dialog box procedure processes the WM_DESTROY message to free the resources allocated to the spelling dictionary.

Processing the WM_COMMAND Message

When an event occurs in a dialog box control, the control sends a WM_COMMAND message to the dialog box procedure.

For edit controls, the window procedure may update the current selection in the list window. Once the user types something in the edit control, triggering an edit control notification, there is no current selection. The window procedure also sets the top index, specifying the zero-based index of the list item at the top of the window. It may also set the caret index, indicating the index of the highlighted list item when the list window has the input focus.

The code example in Creating a Spell Dialog Box, processes notification messages from the combo box, the Change button, the Ignore button, and the Cancel button. The control identifier is in the low-order word of wParam, and the notification code is in the high-order word of wParam.

The control identifier IDCOMBO signifies that an event occurred in the combo box, although the dialog box procedure ignores all events in it except one. CBN_DBLCLK indicates the user has double-clicked a list item; this event is processed in the same way as a Change button click.

The control identifier IDOK signifies the user clicked the Change button. The dialog box procedure replaces the current selection in the application's edit control with the contents of the selection field in the combo box. The selection field may contain either the selected list item or text the user has typed. The dialog box procedure then selects the next misspelled word in the same way it processes an Ignore button click.

The control identifier IDSKIP signifies the user has clicked the Ignore button. The dialog box procedure calls SelectNextWord and InitSpellList to select the next misspelled word in the application's edit control. InitSpellList places the misspelled word in the selection field of the combo box and adds suggested spellings to the combo box list.

The control identifier IDCANCEL indicates the user clicked the Cancel button. The dialog box procedure calls the EndDialog function to close the dialog box.

Creating a Spell Dialog Box

Following are the dialog box procedure and supporting functions for the spelling checker dialog box.

HWND hwndMain;

HWND hwndEdit;

char achTemp[256];       /* temporary buffer            */

LPSTR lpstrDict;         /* buffer for dictionary file  */

LPSTR *paLpDict;         /* array of pointers to words  */

UINT  cWords;            /* number of words             */

/********************************************************

    FUNCTION: SpellDlgProc

    PURPOSE: Dialog procedure for Spell dialog box.

*********************************************************/

BOOL CALLBACK SpellDlgProc(hwndDlg, msg, wParam, lParam)

HWND hwndDlg;

UINT msg;

WPARAM wParam;

LPARAM lParam;

{

    switch (msg) {

        case WM_INITDIALOG:

            if (!OpenDictionary()) {

                EndDialog(hwndDlg, 0);

                break;

            }

            SendMessage(hwndEdit, EM_SETSEL, 0, 0);

            do

                if (!SelectNextWord(hwndEdit, achTemp)) {

                    GlobalFree((HGLOBAL) lpstrDict);

                    LocalFree((HLOCAL) paLpDict);

                    EndDialog(hwndDlg, 0);

                    break;

                }

            while (!InitSpellList(

                GetDlgItem(hwndDlg, IDCOMBO), achTemp));

            break;

        case WM_COMMAND:

            switch (LOWORD(wParam)) {

                case IDCOMBO:

                    if (HIWORD(wParam) != CBN_DBLCLK)

                        break;

                    /* For a double-click, process the OK case. */

                case IDOK:

                    SendDlgItemMessage(hwndDlg, IDCOMBO,

                        WM_GETTEXT, sizeof(achTemp),

                        (LPARAM) achTemp);

                    SendMessage(hwndEdit, EM_REPLACESEL, 0,

                        (LPARAM) achTemp);

                    /* Fall through to get the next word. */

                case IDSKIP:

                    do

                        if (!SelectNextWord(hwndEdit, achTemp)) {

                            EndDialog(hwndDlg, 0);

                            break;

                        }

                    while (!InitSpellList(GetDlgItem(hwndDlg,

                        IDCOMBO), achTemp));

                    break;

                case IDCANCEL:

                    EndDialog(hwndDlg, 0);

            }

            break;

        case WM_DESTROY:

            GlobalFree((HGLOBAL) lpstrDict);

            LocalFree((HLOCAL) paLpDict);

            break;

        default:

            return FALSE;

    }

    return TRUE;

}

/********************************************************

    FUNCTION: InitSpellList

    PURPOSE: Initializes the selection field and list

                of suggestions for the specified word, if

                it is not in the dictionary.

    RETURNS: If the list is initialized, the return

                value is TRUE. If an error occurs or the

                word is in the dictionary, the return

                value is FALSE.

*********************************************************/

BOOL PASCAL InitSpellList(HWND hwndCombo, LPSTR lpszWord)

{

    int min = 0;        /* beginning of search range */

    int max = cWords;   /* end of search range       */

    int n;              /* index of word             */

    int cmp;            /* result of comparison      */

    char ch;            /* first character in word   */

    ch = *lpszWord;

    AnsiLowerBuff(&ch, 1);

    /*

     * Perform a binary search for the word.

     *

     * The global array paLpDict contains pointers to words

     * in the global array lpstrDict. These two variables are

     * initialized by the OpenDictionary function.

     */

    n = max / 2;

    while (min < max) {

        cmp = lstrcmpi(lpszWord, paLpDict[n]);

        if (cmp == 0)

            return FALSE;       /* not misspelled */

        if (cmp < 0)

            max = n;

        else

            min = n + 1;

        n = (min + max) / 2;

    }

    /* List the words beginning with the same letter as lpszWord. */

    SendMessage(hwndCombo, CB_RESETCONTENT, 0, 0);

    while (n > 0 && *paLpDict[n - 1] == ch)

        n--;

    while (*paLpDict[n] == ch)

        SendMessage(hwndCombo, CB_ADDSTRING,

            0, (LPARAM) paLpDict[n++]);

    /* Place the word in the selection field. */

    SendMessage(hwndCombo, WM_SETTEXT, 0, (LPARAM) lpszWord);

    return TRUE;

}


Creating an Owner-Drawn Combo Box

This section describes how to use an owner-drawn combo box. The code example in Creating a Square Meal Dialog Box, uses an owner-drawn drop-down list box to display the four food groups, each represented by a bitmap and a name. Selecting a food group causes the foods in that group to appear in a list.

Creating the Dialog Box

The dialog box template defines the window styles, buttons, and control identifiers for the combo box. The combo box in this example uses the CBS_DROPDOWNLIST, CBS_OWNERDRAWFIXED, CBS_SORT, CBS_HASSTRINGS, WS_VSCROLL, and WS_TABSTOP styles.

The dialog box also contains a list box (IDLIST) and two buttons: OK (IDOK) and Cancel (IDCANCEL). The constants IDOK and IDCANCEL are defined by the Win32 API. The constant IDLIST is defined in the application's header file, as is the control identifier, IDCOMBO.

For more information about dialog boxes, see Dialog Boxes.

Processing the WM_INITDIALOG and WM_DESTROY Messages

When you use a combo box in a dialog box, you usually respond to a WM_INITDIALOG message by initializing the combo box. The code example in Creating a Square Meal Dialog Box, loads the bitmaps used for the owner-drawn combo box, then calls the application-defined InitGroupList function to initialize the combo box. It also selects the first list item in the combo box, then calls the application-defined InitFoodList function to initialize the list box.

In the example, the owner-drawn combo box is a drop-down list box containing the names of each of the four food groups. InitGroupList adds the name of each food group, and calls SetItemData to associate a constant with each list item that identifies a corresponding food group.

The list box in the example contains the names of foods in the selected food group. InitFoodList resets the contents of the list box, then adds the names of the current food selection in the current food group drop-down list box.

The dialog box procedure processes the WM_DESTROY message to delete the bitmaps in the owner-drawn combo box.

Processing the WM_MEASUREITEM Message

An owner-drawn combo box sends the WM_MEASUREITEM message to its parent window or dialog box procedure so the application can set the dimensions of each list item. Because the example combo box has the CBS_OWNERDRAWFIXED style, the system sends the WM_MEASUREITEM message only once. Combo boxes with the CBS_OWNERDRAWVARIABLE style send a WM_MEASUREITEM message for each list item.

The lParam parameter points to a MEASUREITEMSTRUCT structure that identifies the control and list item. It also contains the default dimensions of the list item. The code example in Creating a Square Meal Dialog Box, modifies the itemHeight structure member to ensure that the list items are high enough to accommodate the food-group bitmaps.

Processing the WM_DRAWITEM Message

An owner-drawn combo box sends the WM_DRAWITEM message to its parent window or dialog box procedure each time the application must repaint a list item. The lParam parameter points to a DRAWITEMSTRUCT structure that identifies the control and list item. It also contains information needed to paint the item.

The code example in Creating a Square Meal Dialog Box, displays the list-item text and the bitmap associated with the food group. If the item has the focus, it also draws a focus rectangle. Before displaying the text, the example sets the foreground and background colors, based on the item selected. Because the combo box has the CBS_HASSTRINGS style, the combo box maintains the text for each list item, that can be retrieved using the CB_GETLBTEXT message.

The bitmaps used for the list item depend on the food group. InitGroupList uses the CB_SETITEMDATA message to associate a constant with each list item, identifying the corresponding food group. The window procedure uses this value, contained in the itemData member of the DRAWITEMSTRUCT structure, to determine which bitmaps to display. The system uses two bitmaps for each food group symbol: a monochrome bitmap with the SRCAND raster operation to erase the irregular region behind the image and a color bitmap with the SRCPAINT raster operation to paint the image.

Processing the WM_COMMAND Message

When an event occurs in a dialog box control, the control notifies the dialog box procedure, by means of a WM_COMMAND message. The code example in Creating a Square Meal Dialog Box, processes notification messages from the combo box, the list box, and the OK button. The control identifier is in the low-order word of wParam, and the notification code is in the high-order word of wParam.

If the control identifier is IDCOMBO, an event has occurred in the combo box. In response, the dialog box procedure ignores all other combo box events except CBN_SELCHANGE, used to indicate that the current selection has changed. The dialog box procedure calls InitFoodList to reset the contents of the list box and to add the names of the current selection in the drop-down list box.

If the control identifier is IDLIST, an event has occurred in the list box. This causes the dialog box procedure to ignore all list box events except LBN_DBLCLK, used to indicate that the user has double-clicked a list item. This event is processed in the same way as an OK button click.

If the control identifier is IDOK, the user has clicked the OK button. In response, the dialog box procedure inserts the name of the selected food into the application's multiline edit control, then calls the EndDialog function to close the dialog box.

If the control identifier is IDCANCEL, the user has clicked the Cancel button. In response, the dialog box procedure calls EndDialog to close the dialog box.

Creating a Square Meal Dialog Box

Following are the dialog box procedure and supporting functions for the Square Meal dialog box.

HWND hwndMain;

HWND hwndEdit;

char achTemp[256];       /* temporary buffer            */

HBITMAP hbmBread;

HBITMAP hbmDairy;

HBITMAP hbmFruit;

HBITMAP hbmMeat;

HBITMAP hbmBreadMask;

HBITMAP hbmDairyMask;

HBITMAP hbmFruitMask;

HBITMAP hbmMeatMask;

/********************************************************

    FUNCTION: FoodDlgProc

    PURPOSE: Dialog procedure for Food dialog box.

*********************************************************/

BOOL CALLBACK FoodDlgProc(hwndDlg, msg, wParam, lParam)

HWND hwndDlg;

UINT msg;

WPARAM wParam;

LPARAM lParam;

{

    LPMEASUREITEMSTRUCT lpmis;

    LPDRAWITEMSTRUCT lpdis;

    HBITMAP hbmIcon;

    HBITMAP hbmMask;

    COLORREF clrBackground;

    COLORREF clrForeground;

    TEXTMETRIC tm;

    HDC hdc;

    HWND hwnd;

    int x;

    int y;

    switch (msg) {

        case WM_INITDIALOG:

            /*

             * Call an application-defined function to load

             * bitmap resources.

             */

            if (!LoadIconBitmaps()) {

                EndDialog(hwndDlg, -1);

                break;

            }

            /* Initialize the drop-down list box. */

            if (!InitGroupList(hwndDlg)) {

                DeleteIconBitmaps();

                EndDialog(hwndDlg, -1);

                break;

            }

            /* Select the first food group. */

            SendDlgItemMessage(hwndDlg, IDCOMBO, CB_SETCURSEL,

                0, 0);

            /* List the foods and select the first food. */

            InitFoodList(hwndDlg);

            SendDlgItemMessage(hwndDlg, IDLIST, LB_SETCURSEL,

                0, 0);

            break;

        case WM_MEASUREITEM:

            lpmis = (LPMEASUREITEMSTRUCT) lParam;

            if (lpmis->itemHeight < CY_BITMAP + 2)

                lpmis->itemHeight = CY_BITMAP + 2;

            break;

        case WM_DRAWITEM:

            lpdis = (LPDRAWITEMSTRUCT) lParam;

            if (lpdis->itemID == -1)            /* empty item */

                break;

            /* Determine the bitmaps used to draw the icon. */

            switch (lpdis->itemData) {

                case ID_BREAD:

                    hbmIcon = hbmBread;

                    hbmMask = hbmBreadMask;

                    break;

                case ID_DAIRY:

                    hbmIcon = hbmDairy;

                    hbmMask = hbmDairyMask;

                    break;

                case ID_FRUIT:

                    hbmIcon = hbmFruit;

                    hbmMask = hbmFruitMask;

                    break;

                default: /* meat */

                    hbmIcon = hbmMeat;

                    hbmMask = hbmMeatMask;

                    break;

            }

            /* The colors depend on whether the item is selected. */

            clrForeground = SetTextColor(lpdis->hDC,

                GetSysColor(lpdis->itemState & ODS_SELECTED ?

                COLOR_HIGHLIGHTTEXT : COLOR_WINDOWTEXT));

            clrBackground = SetBkColor(lpdis->hDC,

                GetSysColor(lpdis->itemState & ODS_SELECTED ?

                COLOR_HIGHLIGHT : COLOR_WINDOW));

            /* Calculate the vertical and horizontal position. */

            GetTextMetrics(lpdis->hDC, &tm);

            y = (lpdis->rcItem.bottom + lpdis->rcItem.top -

                tm.tmHeight) / 2;

            x = LOWORD(GetDialogBaseUnits()) / 4;

            /* Get and display the text for the list item. */

            SendMessage(lpdis->hwndItem, CB_GETLBTEXT,

                lpdis->itemID, (LPARAM) (LPCSTR) achTemp);

            ExtTextOut(lpdis->hDC, CX_BITMAP + 2 * x, y,

                ETO_CLIPPED | ETO_OPAQUE, &lpdis->rcItem,

                achTemp, lstrlen(achTemp), NULL);

            /* Restore the previous colors. */

            SetTextColor(lpdis->hDC, clrForeground);

            SetBkColor(lpdis->hDC, clrBackground);

            /* Show the icon. */

            hdc = CreateCompatibleDC(lpdis->hDC);

            if (hdc == NULL)

                break;

            SelectObject(hdc, hbmMask);

            BitBlt(lpdis->hDC, x, lpdis->rcItem.top + 1,

                CX_BITMAP, CY_BITMAP, hdc, 0, 0, SRCAND);

            SelectObject(hdc, hbmIcon);

            BitBlt(lpdis->hDC, x, lpdis->rcItem.top + 1,

                CX_BITMAP, CY_BITMAP, hdc, 0, 0, SRCPAINT);

            DeleteDC(hdc);

            /* If the item has the focus, draw focus rectangle. */

            if (lpdis->itemState & ODS_FOCUS)

                DrawFocusRect(lpdis->hDC, &lpdis->rcItem);

            break;

        case WM_COMMAND:

            switch (LOWORD(wParam)) {

                case IDCOMBO:

                    if (HIWORD(wParam) == CBN_SELCHANGE) {

                        InitFoodList(hwndDlg);

                        SendDlgItemMessage(hwndDlg, IDLIST,

                            LB_SETCURSEL, 0, 0);

                    }

                    break;

                case IDLIST:

                    if (HIWORD(wParam) != LBN_DBLCLK)

                        break;

                    /* For a double-click, process the OK case. */

                case IDOK:

                    /* Get the text for the selected list item. */

                    hwnd = GetDlgItem(hwndDlg, IDLIST);

                    SendMessage(hwnd, LB_GETTEXT,

                        SendMessage(hwnd, LB_GETCURSEL, 0, 0),

                        (LPARAM) achTemp);

                    /* Insert the text into the edit window. */

                    SendMessage(hwndEdit, EM_REPLACESEL, 0,

                        (LPARAM) achTemp);

                    EndDialog(hwndDlg, 0);

                    break;

                case IDCANCEL:

                    hwnd = GetDlgItem(hwndDlg, IDCOMBO);

                    if (SendMessage(hwnd, CB_GETDROPPEDSTATE,

                            0, 0))

                        SendMessage(hwnd, CB_SHOWDROPDOWN,

                            FALSE, 0);

                    else

                        EndDialog(hwndDlg, 0);

            }

            break;

        case WM_DESTROY:

            /*

             * Call the application-defined function to free

             * bitmap resources.

             */

            DeleteIconBitmaps();

            break;

        default:

            return FALSE;

    }

    return TRUE;

}

/********************************************************

    FUNCTION: InitGroupList

    PURPOSE: Initializes the "food groups" drop-down

                list box.

    COMMENTS: The ID of the food group associated with

                each list item is saved as item data.

*********************************************************/

BOOL PASCAL InitGroupList(HWND hwndDlg)

{

    HWND hwndCombo = GetDlgItem(hwndDlg, IDCOMBO);

    DWORD dwIndex;

    /* Add an item for each food group. */

    LoadString(hinst, ID_BREAD, achTemp, sizeof(achTemp));

    dwIndex = SendMessage(hwndCombo, CB_ADDSTRING, 0,

        (LPARAM) (LPCSTR) achTemp);

    SendMessage(hwndCombo, CB_SETITEMDATA, dwIndex, ID_BREAD);

    LoadString(hinst, ID_DAIRY, achTemp, sizeof(achTemp));

    dwIndex = SendMessage(hwndCombo, CB_ADDSTRING, 0,

        (LPARAM) (LPCSTR) achTemp);

    SendMessage(hwndCombo, CB_SETITEMDATA, dwIndex, ID_DAIRY);

    LoadString(hinst, ID_FRUIT, achTemp, sizeof(achTemp));

    dwIndex = SendMessage(hwndCombo, CB_ADDSTRING, 0,

        (LPARAM) (LPCSTR) achTemp);

    SendMessage(hwndCombo, CB_SETITEMDATA, dwIndex, ID_FRUIT);

    LoadString(hinst, ID_MEAT, achTemp, sizeof(achTemp));

    dwIndex = SendMessage(hwndCombo, CB_ADDSTRING, 0,

        (LPARAM) (LPCSTR) achTemp);

    SendMessage(hwndCombo, CB_SETITEMDATA, dwIndex, ID_MEAT);

    return TRUE;

}

/********************************************************

    FUNCTION: InitFoodList

    PURPOSE: Clears the contents of the food list, and

                adds the names of foods for the current

                food group.

*********************************************************/

void PASCAL InitFoodList(HWND hwndDlg)

{

    HWND hwndCombo = GetDlgItem(hwndDlg, IDCOMBO);

    HWND hwndList = GetDlgItem(hwndDlg, IDLIST);

    UINT idFoodGroup;

    LPSTR lpsz;

    LPSTR lpszEnd;

    /* Determine the current food group. */

    idFoodGroup = SendMessage(

        hwndCombo,

        CB_GETITEMDATA,

        SendMessage(hwndCombo, CB_GETCURSEL, 0, 0),

        0

    );

    /* Clear the list contents. */

    SendMessage(hwndList, LB_RESETCONTENT, 0, 0);

    .

    . /* Add food names for the current food group. */

    .

}


Subclassing a Combo Box

This section demonstrates how to subclass combo boxes so your application can use them outside a dialog box. The code example in Creating a Tool Bar, shows the window procedure for a tool bar window containing two combo boxes. By subclassing the edit controls within the combo boxes, the tool bar window intercepts TAB, ENTER, and ESC keys that would otherwise be ignored.

The following illustration shows the tool bar window:

Processing the WM_CREATE Message

The code example in Creating a Tool Bar, processes the WM_CREATE message to create two combo box controls as child windows. It then subclasses the edit controls (selection fields) in each combo box because they receive the character input for simple and drop-down combo box. The application gets the handle of each edit control by using the ChildWindowFromPoint function.

To subclass the edit controls, the application calls the SetWindowLong function, replacing the address of the class window procedure with the address of the application-defined SubClassProc function. The address of the original window procedure is saved in the global variable lpfnEditWndProc.

The SubClassProc function intercepts TAB, ESC, and ENTER keys and notifies the tool bar window by sending application-defined messages (WM_TAB, WM_ESC, and WM_ENTER). SubClassProc uses the CallWindowProc function to pass most messages to the original window procedure, lpfnEditWndProc.

Processing the WM_SETFOCUS Message

When the tool bar window receives the input focus, it immediately sets the focus to the first combo box in the tool bar. To do so, the code example in Creating a Tool Bar, calls the SetFocus function in response to the WM_SETFOCUS message.

Processing the Application-Defined Messages

In the code example in Creating a Tool Bar, SubClassProc sends application-defined messages to the tool bar window when the user presses the TAB, ESC, or ENTER key in a combo box. The WM_TAB message is sent for the TAB key, the WM_ESC message for the ESC key, and the WM_ENTER message for the ENTER key.

The example processes the WM_TAB message by setting the focus to the next combo box in the tool bar. It processes the WM_ESC message by setting the focus to the main application window.

In response to the WM_ENTER message, the example ensures that the current selection for the combo box is valid and then sets the focus to the main application window. If the combo box contains no current selection, the example uses the CB_FINDSTRINGEXACT message to search for a list item that matches the contents of the selection field. If there is a match, the example sets the current selection; otherwise, it adds a new list item.

Creating a Tool Bar

Following are the window procedure for the tool bar and the subclass procedure for the two combo boxes.

#define WM_TAB (WM_USER)

#define WM_ESC (WM_USER + 1)

#define WM_ENTER (WM_USER + 2)

HWND hwndMain;

HWND hwndEdit;

WNDPROC lpfnEditWndProc; /* original window procedure for */

                         /*   the combo box edit windows  */

int cyToolbar;           /* tool bar window height        */

/********************************************************

    FUNCTION: ToolbarWindowProc

    PURPOSE: Window procedure for the tool bar window

*********************************************************/

LRESULT CALLBACK ToolbarWindowProc(hwnd, msg, wParam, lParam)

HWND hwnd;

UINT msg;

WPARAM wParam;

LPARAM lParam;

{

    static HWND   hwndEdit1;

    static HWND   hwndEdit2;

    static HWND   hwndCombo1;

    static HWND   hwndCombo2;

    .

    .

    .

    FARPROC     lpfnSubClassProc;

    POINT       pt;

    DWORD       dwBaseUnits;

    HWND        hwndCombo;

    DWORD       dwIndex;

    switch (msg) {

        case WM_CREATE:

            /* Create two combo box child windows. */

            dwBaseUnits = GetDialogBaseUnits();

            hwndCombo1 = CreateWindow("COMBOBOX", "",

                CBS_DROPDOWN | WS_CHILD | WS_VISIBLE,

                (6 * LOWORD(dwBaseUnits)) / 4,

                (2 * HIWORD(dwBaseUnits)) / 8,

                (100 * LOWORD(dwBaseUnits)) / 4,

                (50 * HIWORD(dwBaseUnits)) / 8,

                hwnd, NULL, hinst, NULL);

            hwndCombo2 = CreateWindow("COMBOBOX", "",

                CBS_DROPDOWN | WS_CHILD | WS_VISIBLE,

                (112 * LOWORD(dwBaseUnits)) / 4,

                (2 * HIWORD(dwBaseUnits)) / 8,

                (100 * LOWORD(dwBaseUnits)) / 4,

                (50 * HIWORD(dwBaseUnits)) / 8,

                hwnd, NULL, hinst, NULL);

            /* Get the edit window handle for each combo box. */

            pt.x = 1;

            pt.y = 1;

            hwndEdit1 = ChildWindowFromPoint(hwndCombo1, pt);

            hwndEdit2 = ChildWindowFromPoint(hwndCombo2, pt);

            /*

             * Change the window procedure for both edit windows

             * to the subclass procedure.

             */

            lpfnSubClassProc = MakeProcInstance(

                (FARPROC) SubClassProc, hinst);

            lpfnEditWndProc = (WNDPROC) SetWindowLong(hwndEdit1,

                GWL_WNDPROC, (DWORD) lpfnSubClassProc);

            SetWindowLong(hwndEdit2, GWL_WNDPROC,

                (DWORD) lpfnSubClassProc);

            break;

        case WM_SETFOCUS:

            SetFocus(hwndCombo1);

            break;

        case WM_TAB:

            if (GetFocus() == hwndEdit1)

                SetFocus(hwndCombo2);

            else

                SetFocus(hwndCombo1);

            break;

        case WM_ESC:

            hwndCombo = GetFocus() == hwndEdit1 ?

                hwndCombo1 : hwndCombo2;

            /* Clear the current selection. */

            SendMessage(hwndCombo, CB_SETCURSEL, (WPARAM) (-1), 0);

            /* Set the focus to the main window. */

            SetFocus(hwndMain);

            break;

        case WM_ENTER:

            hwndCombo = GetFocus() == hwndEdit1 ?

                hwndCombo1 : hwndCombo2;

            SetFocus(hwndMain);

            /* If there is no current selection, set one. */

            if (SendMessage(hwndCombo, CB_GETCURSEL, 0, 0)

                    == CB_ERR) {

                if (SendMessage(hwndCombo, WM_GETTEXT,

                        sizeof(achTemp), (LPARAM) achTemp) == 0)

                    break;      /* empty selection field */

                dwIndex = SendMessage(hwndCombo,

                    CB_FINDSTRINGEXACT, (WPARAM) (-1),

                    (LPARAM) achTemp);

                /* Add the string, if necessary, and select it. */

                if (dwIndex == CB_ERR)

                    dwIndex = SendMessage(hwndCombo, CB_ADDSTRING,

                        0, (LPARAM) achTemp);

                if (dwIndex != CB_ERR)

                    SendMessage(hwndCombo, CB_SETCURSEL,

                        dwIndex, 0);

            }

            break;

            .

            . /* Process additional messages. */

            .

        default:

            return DefWindowProc(hwnd, msg, wParam, lParam);

    }

    return 0;

}

/********************************************************

    FUNCTION: SubClassProc

    PURPOSE: Process TAB and ESCAPE keys, and pass all

                other messages to the class window

                procedure.

*********************************************************/

LRESULT CALLBACK SubClassProc(hwnd, msg, wParam, lParam)

HWND hwnd;

UINT msg;

WPARAM wParam;

LPARAM lParam;

{

    switch (msg) {

        case WM_KEYDOWN:

            switch (wParam) {

                case VK_TAB:

                    SendMessage(hwndToolbar, WM_TAB, 0, 0);

                    return 0;

                case VK_ESCAPE:

                    SendMessage(hwndToolbar, WM_ESC, 0, 0);

                    return 0;

                case VK_RETURN:

                    SendMessage(hwndToolbar, WM_ENTER, 0, 0);

                    return 0;

            }

            break;

        case WM_KEYUP:

        case WM_CHAR:

            switch (wParam) {

                case VK_TAB:

                case VK_ESCAPE:

                case VK_RETURN:

                    return 0;

            }

    }

    /* Call the original window procedure for default processing. */

    return CallWindowProc(lpfnEditWndProc, hwnd,

        msg, wParam, lParam);

}


Functions

Functions and Messages

Following are the functions and messages used with combo boxes.

Functions

DlgDirListComboBox

DlgDirSelect

DlgDirSelectComboBox

DlgDirSelectComboBoxEx

Messages

CB_ADDSTRING

CB_DELETESTRING

CB_DIR

CB_FINDSTRING

CB_FINDSTRINGEXACT

CB_GETCOUNT

CB_GETCURSEL

CB_GETDROPPEDCONTROLRECT

CB_GETDROPPEDSTATE

CB_GETEDITSEL

CB_GETEXTENDEDUI

CB_GETITEMDATA

CB_GETITEMHEIGHT

CB_GETLBTEXT

CB_GETLBTEXTLEN

CB_GETLOCALE

CB_INSERTSTRING

CB_LIMITTEXT

CB_RESETCONTENT

CB_SELECTSTRING

CB_SETCURSEL

CB_SETEDITSEL

CB_SETEXTENDEDUI

CB_SETITEMDATA

CB_SETITEMHEIGHT

CB_SETLOCALE

CB_SHOWDROPDOWN

CBN_CLOSEUP

CBN_DBLCLK

CBN_DROPDOWN

CBN_EDITCHANGE

CBN_EDITUPDATE

CBN_ERRSPACE

CBN_KILLFOCUS

CBN_SELCHANGE

CBN_SETFOCUS

WM_COMPAREITEM

WM_DRAWITEM

WM_MEASUREITEM


Scroll Bars Overview

About Scroll Bars

A window in an application written for Microsoft® Windows™ can display a data object, such as a document or a bitmap, that is larger than the window's client area. When provided with a scroll bar, the user can scroll a data object in the client area to bring into view the portions of the object that extend beyond the borders of the window. Scroll bars should be included in any window sized such that the contents of the client area extend beyond the window's borders.

The following topics discuss Win32 scroll bars:

Terms

Parts of a Scroll Bar

Standard Scroll Bars and Scroll Bar Controls

Scroll-Box Position and Scrolling Range

Scroll Bar Requests

Keyboard Interface for a Scroll Bar

Scrolling the Client Area

Scroll Bar Visibility

Scroll Bar Colors and Metrics

Creating Scroll Bars

Scrolling Text

Example: Scrolling Text

Scrolling a Bitmap

Example: Scrolling a Bitmap

Creating a Keyboard Interface for a Standard Scroll Bar

Functions

Messages

A scroll bar's orientation determines the direction in which scrolling occurs when the user operates the scroll bar. A horizontal scroll bar enables the user to scroll the contents of a window to the left or right. A vertical scroll bar enables the user to scroll the contents up or down. The following illustration shows horizontal and vertical scroll bars in Windows Write.


Parts of a Scroll Bar

A scroll bar consists of a shaded shaft with an arrow button at each end and a scroll box (sometimes called a thumb) between the arrow buttons. The following illustration shows the parts of a scroll bar.

A scroll bar represents the overall length or width of a data object in a window's client area; the scroll box represents the portion of the object that is visible in the client area. The position of the scroll box changes whenever the user scrolls a data object to display a different portion of it.

The user scrolls the contents of a window by clicking one of the arrow buttons, by clicking the area in the shaded shaft, or by dragging the scroll box. When the user clicks an arrow button, the application scrolls the contents by one unit (typically a single line or column). When the user clicks the shaded areas, the application scrolls the contents by one window. The amount of scrolling that occurs when the user drags the scroll box depends on the distance the user drags the scroll box and on the scrolling range of the scroll bar. For more information about the scrolling range, see Scroll Box Position and Scrolling Range.


Standard Scroll Bars and Scroll Bar Controls

A scroll bar is included in a window either as a standard scroll bar or as a scroll bar control. A standard scroll bar is located in the nonclient area of a window. It is created with the window and displayed when the window is displayed. The sole purpose of a standard scroll bar is to enable the user to generate scrolling requests for viewing the entire contents of the client area. You can include a standard scroll bar in a window by specifying WS_HSCROLL, WS_VSCROLL, or both styles when you create the window. The WS_HSCROLL style creates a horizontal scroll bar positioned at the bottom of the client area. The WS_VSCROLL style creates a vertical scroll bar positioned at the right of the client area. The SM_CXHSCROLL and SM_CYHSCROLL system metric values define the width and height of a standard horizontal scroll bar. The SM_CXVSCROLL and SM_CYVSCROLL values define the width and height of a standard vertical scroll bar.

A scroll bar control is a control window that belongs to the SCROLLBAR window class. A scroll bar control appears and functions like a standard scroll bar, but it is a separate window. As a separate window, a scroll bar control receives direct input focus, indicated by a flashing caret displayed in the scroll box. Unlike a standard scroll bar, a scroll bar control also has a built-in keyboard interface that enables the user to direct scrolling. You can use as many scroll bar controls as needed in a single window. When you create a scroll bar control, you must specify the scroll bar's size and position. However, if a scroll bar control's window can be resized, adjustments to the scroll bar's size must be made whenever the size of the window changes.

The advantage of using a standard scroll bar is that Windows creates the scroll bar and automatically sets its size and position. However, standard scroll bars are sometimes too restrictive. For example, suppose that you want to divide a client area into quadrants and use a separate set of scroll bars to control the contents of each quadrant. You cannot use standard scroll bars, because you can only create one set of scroll bars for a particular window. Use scroll bar controls instead, because you can add as many of them to a window as you want.

Applications can provide scroll bar controls for purposes other than scrolling the contents of a window. For example, the Mouse application in Windows Control Panel provides scroll bar controls making it possible for the user to set the mouse tracking speed and double-click speed. The following figure shows the Double-Click Speed scroll bar control in the Mouse application.

A scroll bar control can have a number of styles that serves to control the orientation and position of the scroll bar. You specify the styles that you want when you call the CreateWindowEx function to create a scroll bar control. Some of the styles create a scroll bar control that uses a default width or height. However, you must always specify the x- and y-coordinates and the other dimensions of the scroll bar. Following are the scroll bar control styles.

Style	Description

SBS_BOTTOMALIGN	Positions a horizontal scroll bar at the bottom of the rectangle specified by the x, y, nWidth and nHeight parameters of the CreateWindowEx function. The SBS_HORZ style must also be specified. The scroll bar uses the default height for standard horizontal scroll bars.

SBS_HORZ	Creates a horizontal scroll bar. If neither the SBS_BOTTOMALIGN nor SBS_TOPALIGN style is specified, the scroll bar uses the height, width, and position given in the CreateWindowEx function.

SBS_LEFTALIGN	Positions a vertical scroll bar at the left side of the rectangle specified by the x, y, nWidth and nHeight parameters of the CreateWindowEx function. The SBS_VERT style must also be specified. The scroll bar uses the default width for standard vertical scroll bars.

SBS_RIGHTALIGN	Positions a vertical scroll bar at the right side of the rectangle specified by the x, y, nWidth and nHeight parameters of the CreateWindowEx function. The SBS_VERT style must also be specified. The scroll bar uses the default width for standard vertical scroll bars.

SBS_TOPALIGN	Positions a horizontal scroll bar at the top of the rectangle specified by the x, y, nWidth and nHeight parameters of the CreateWindowEx function. The SBS_HORZ style must also be specified. The scroll bar uses the default height for standard horizontal scroll bars.

SBS_VERT	Creates a vertical scroll bar. If neither the SBS_RIGHTALIGN nor SBS_LEFTALIGN style is specified, the scroll bar uses the height, width, and position given by the CreateWindowEx function.


Scroll Box Position and Scrolling Range

The position of the scroll box is represented as an integer; it is relative to the left or upper end of the scroll bar, depending on whether the scroll bar is horizontal or vertical. The position must be within the minimum and maximum values of the scrolling range. For example, in a scroll bar with a range of 0 through 100, position 50 is in the middle, with the remaining positions distributed equally along the scroll bar. The initial range depends on the scroll bar. Standard scroll bars have an initial range of 0 through 100; scroll bar controls have an empty range (both minimum and maximum values are zero), unless you supply an explicit range when the control is created. You can change the range at any time by using the SetScrollRange function to set new minimum and maximum values. The GetScrollRange function retrieves the current minimum and maximum values.

You can adjust the scroll range to convenient integers by using the SetScrollRange function. This function makes it easy to translate the scroll box position into a value corresponding to the scrolled data. For example, if an application must display 260 lines of text in a window that can show only 16 lines at a time, the vertical scroll bar range can be set to 1 through 244. If the scroll box is at position 1, the first line will be at the top of the window. If the scroll box is at position 244, the last line (line 260) will be at the bottom of the window. If the SetScrollPos function specifies a position value that is less than the minimum or more than the maximum, the minimum or maximum scrolling range value is used instead.

To establish a useful relationship between the scroll bar range and the data, an application must adjust the range whenever the data or the size of the window changes. The application must, therefore, adjust the scroll bar range when processing WM_SIZE messages.

As the user moves the scroll box in a scroll bar, the scroll bar reports the scroll box position as an integer in the scrolling range. If the position is the minimum value, the scroll box is at the top of a vertical scroll bar or at the left end of a horizontal scroll bar. If the position is the maximum value, the scroll box is at the bottom of a vertical scroll bar or at right end of a horizontal scroll bar.

An application must move the scroll box in a scroll bar. Although the user makes a request for scrolling in a scroll bar, the scroll bar does not update the scroll box position. Instead, it passes the request to the parent window, which must scroll the data and update the scroll box position by using the SetScrollPos function. Because it controls the scroll box movement, the application can move the scroll box in increments that work best for the data being scrolled.


Scroll Bar Requests

The user makes scrolling requests by clicking various parts of a scroll bar. Windows sends the request to the given window in the form of a WM_HSCROLL or WM_VSCROLL message. A horizontal scroll bar sends the WM_HSCROLL message; a vertical scroll bar sends the WM_VSCROLL message. Each message includes a notification code that corresponds to the user's action, to the handle of the scroll bar (scroll bar controls only), and, in some cases, to the position of the scroll box.

The following figure shows the notification codes that the user generates when clicking various parts of a scroll bar.

The scroll bar notification codes specify the action the user takes. An application examines the codes that accompany the WM_HSCROLL and WM_VSCROLL messages and then performs the appropriate scrolling operation. In the following table of notification codes, the user's action is specified for each code, followed by the application's response. In each case, a unit is defined by the application as appropriate for the given data. For example, the typical unit for scrolling text vertically is a line.

Notification code	Action	Response
SB_LINEUP	The user clicks the top scroll arrow.	Decrement of the scroll box position; scrolls toward the top of the data by one unit.
SB_LINEDOWN	The user clicks the bottom scroll arrow.	Increment of the scroll box position; scrolls toward the bottom of the data by one unit.
SB_LINELEFT	The user clicks the left scroll arrow.	Decrement of the scroll box position; scrolls toward the left end of the data by one unit.
SB_LINERIGHT	The user clicks the right scroll arrow.	Increment of the scroll box position; scrolls toward the right end of the data by one unit.
SB_PAGEUP	The user clicks the scroll bar shaft above the scroll box.	Decrement of the scroll box position by the number of data units in the window; scrolls toward the top of the data by the same number of units.
SB_PAGEDOWN	The user clicks the scroll bar shaft below the scroll box.	Increment of the scroll box position by the number of data units in the window; scrolls toward the bottom of the data by the same number of units.
SB_PAGELEFT	The user clicks the scroll bar shaft to the left of the scroll box.	Decrement of the scroll box position by the number of data units in the window; scrolls toward the left end of the data by the same number of units.
SB_PAGERIGHT	The user clicks the scroll bar shaft to the right of the scroll box.	Increment of the scroll box position by the number of data units in the window; scrolls toward the right end of the data by the same number of units.
SB_THUMBPOSITION	The user releases the scroll box after dragging it.	Setting of the scroll box to the position given in the message; scrolls the data by the same number of units the scroll box has moved.
SB_THUMBTRACK	The user drags the scroll box.	Applications that draw data quickly can set the scroll box to the position given in the message and scroll the data by the same number of units the scroll box has moved. Applications that cannot draw data quickly must wait for the SB_THUMBPOSITION code before moving the scroll box and scrolling the data.
SB_ENDSCROLL	The user releases the mouse after holding it on an arrow or in the scrollbar shaft.	No response is needed.
A scroll bar generates the SB_THUMBPOSITION and SB_THUMBTRACK notification codes when the user clicks and drags the scroll box. An application should be programmed to process either the SB_THUMBTRACK or the SB_THUMBPOSITION notification code.

The SB_THUMBPOSITION notification code occurs when the user releases the mouse button after clicking the scroll box. An application that processes this code performs the scrolling operation after the user has dragged the scroll box to the desired position and released the mouse button.

SB_THUMBTRACK notification codes occur as the user drags the scroll box. If an application processes SB_THUMBTRACK messages, it can scroll the contents of a window as the user drags the scroll box. However, a scroll bar can generate many SB_THUMBTRACK notification codes in a short period, so an application should process these codes only if it can quickly repaint the contents of the window.


Keyboard Interface for a Scroll Bar

A scroll bar control provides a built-in keyboard interface that enables the user to issue scrolling requests by using the keyboard; a standard scroll bar does not. When a scroll bar control has the keyboard focus, it sends WM_HSCROLL and WM_VSCROLL messages to its parent window when the user presses the arrow keys. The notification code is sent with each message corresponding to the arrow key the user has pressed. Following are the arrow keys and their corresponding notification codes.

Arrow key	Notification code

UP	SB_LINEUP or SB_LINELEFT

DOWN	SB_LINEDOWN or SB_LINERIGHT

LEFT	SB_LINEUP or SB_LINELEFT

RIGHT	SB_LINEDOWN or SB_LINERIGHT

PGUP	SB_PAGEUP or SB_PAGELEFT

PGDN	SB_PAGEDOWN or SB_PAGERIGHT

HOME	SB_TOP

END	SB_BOTTOM

Note that the keyboard interface of a scroll bar control sends the SB_TOP and SB_BOTTOM notification codes. The SB_TOP code indicates that the user has reached the top value of the scrolling range. An application scrolls the window contents downward so that the top of the data object is visible. The SB_BOTTOM code indicates that the user has reached the bottom value of the scrolling range. If an application processes the SB_BOTTOM code, it scrolls the window contents upward so that the bottom of the data object is visible.

If you want a keyboard interface for a standard scroll bar, you can create one yourself by processing the WM_KEYDOWN message in your window procedure and then performing the appropriate scrolling action based on the virtual-key code that accompanies the message. For information about how to create a keyboard interface for a scroll bar, see Creating a Keyboard Interface for a Standard Scroll Bar.


Scrolling the Client Area

The simplest way to scroll the contents of a client area is to erase and then redraw it. This is the method an application is likely to use with SB_PAGEUP, SB_PAGEDOWN, SB_TOP, and SB_END commands, which typically require completely new contents.

For some commands, such as SB_LINEUP and SB_LINEDOWN, not all the contents need be erased, since some remain visible after scrolling occurs. The ScrollWindow and ScrollWindowEx functions preserve a portion of the client area's contents, move the preserved portion a specified amount, and then prepare the rest of the client area for painting new information. ScrollWindow and ScrollWindowEx use the BitBlt function to move a specific part of the data object to a new location within the client area. Any uncovered part of the client area (anything not preserved) is invalidated, erased, and painted when the next WM_PAINT message occurs.

The ScrollWindow and ScrollWindowEx functions can be used to exclude a portion of the client area from the scrolling operation. This keeps items with fixed positions, such as child windows, from moving within the client area. It automatically invalidates the portion of the client area that is to receive the new information, so the application does not have to compute its own clipping regions.

Usually an application scrolls the contents of a window in the direction opposite that indicated by the scroll bar. For example, when the user clicks the shaft in the area below the scroll box, an application scrolls the object in the window upward to reveal a portion of the object that is below the visible portion. The following figure shows the scrolling operation an application performs when processing the SB_PAGEDOWN notification code.


Scroll Bar Visibility

The SetScrollRange function hides and disables a standard scroll bar when equal minimum and maximum values are specified. This is the way to temporarily hide a scroll bar when it is not needed for the contents of the client area. There is no need to make scrolling requests through the scroll bar when it is hidden. SetScrollRange enables the scroll bar and shows it again when it sets the minimum and maximum values to unequal values. The ShowScrollBar function can also be used to hide or show a scroll bar. It does not affect the scroll bar's range or scroll box position.

The EnableScrollBar function can be used to disable one or both arrows of a scroll bar. An application displays disabled arrows in gray and does not respond to user input.


Scroll Bar Colors and Metrics

The system-defined color value, COLOR_SCROLLBAR, controls the color within a scroll bar's shaft. Use the GetSysColor function to determine the color of the shaft and the SetSysColors function to set the color of the shaft. Note, however, that this change of color affects all scroll bars in the system.

You can get the dimensions of the bitmaps that Windows uses in standard scroll bars by calling the GetSystemMetrics function. Following are the system metric values associated with scroll bars.

System metric	Description

SM_CXHSCROLL	Width of arrow bitmap on horizontal scroll bar

SM_CYHSCROLL	Height of arrow bitmap on horizontal scroll bar

SM_CXVSCROLL	Width of arrow bitmap on vertical scroll bar

SM_CYVSCROLL	Height of arrow bitmap on vertical scroll bar

SM_CXHTHUMB	Width of scroll box on horizontal scroll bar

SM_CYVTHUMB	Height of scroll box on vertical scroll bar


Creating Scroll Bars

When creating an overlapped, pop-up, or child window, you can add standard scroll bars by using the CreateWindowEx function and specifying WS_HSCROLL, WS_VSCROLL, or both styles. Doing this adds a horizontal or vertical scroll bar, or both, to the window. The code in the following example creates a window with standard horizontal and vertical scroll bars.

hwnd = CreateWindowEx(

    0L,                          /* no extended styles        */

    "MyAppClass",                /* window class              */

    "Scroll Bar Application",    /* text for window title bar */

    WS_OVERLAPPEDWINDOW |        /* window styles             */

        WS_HSCROLL |

        WS_VSCROLL,

    CW_USEDEFAULT,             /* default horizontal position */

    CW_USEDEFAULT,             /* default vertical position   */

    CW_USEDEFAULT,             /* default width               */

    CW_USEDEFAULT,             /* default height              */

    (HWND) NULL,         /* no parent for overlapped windows  */

    (HMENU) NULL,        /* window class menu                 */

    hinst,               /* instance owning this window       */

    (LPVOID) NULL        /* pointer not needed                */

);

To process scroll bar messages for these scroll bars, you must include appropriate code in the main window procedure.

When using the CreateWindowEx function to create a window, you can add a scroll bar control by specifying the SCROLLBAR window class. This creates a horizontal or vertical scroll bar, depending on whether SBS_HORZ or SBS_VERT is specified as the window style. The scroll bar size and its position relative to its parent window can also be specified. The following code example creates a horizontal scroll bar control and positions it in the upper-right corner of the window.

hwndScroll = CreateWindowEx(

    0L,                          /* no extended styles        */

    "SCROLLBAR",                 /* scroll bar control class  */

    (LPSTR) NULL,                /* text for window title bar */

    WS_CHILD | SBS_HORZ,         /* scroll bar styles         */

    0,                           /* horizontal position       */

    0,                           /* vertical position         */

    200,                         /* width of the scroll bar   */

    CW_USEDEFAULT,               /* default height            */

    hwnd,                   /* handle of main window          */

    (HMENU) NULL,           /* no menu for a scroll bar       */

    hinst,                  /* instance owning this window    */

    (LPVOID) NULL           /* pointer not needed             */

);


Scrolling Text

This section describes the changes you can make to an application's main window procedure to enable a user to scroll text. The example in Example of Scrolling Text, creates and displays an array of text strings and processes WM_HSCROLL and WM_VSCROLL messages generated by the scroll bars so that the user can scroll text both vertically and horizontally.

Processing the WM_CREATE Message

Scrolling units are typically set while processing the WM_CREATE message. It is convenient to base the scrolling units on the dimensions of the font associated with the window's display context. To retrieve the font dimensions for a specific display context, use the GetTextMetrics function.

In the example in Example of Scrolling Text, one vertical scrolling unit is equivalent to the height of a character cell, plus external leading. One horizontal scrolling unit is equivalent to the average width of a character cell. The horizontal scrolling positions, therefore, do not correspond to actual characters, unless the screen font is fixed-width.

Processing the WM_SIZE Message

When processing the WM_SIZE message, it is convenient to adjust the scrolling range and scrolling position to reflect the dimensions of the client area as well as the number of lines of text that will be displayed.

The SetScrollRange function sets the minimum and maximum position values for a scroll bar. The SetScrollPos function adjusts the scroll box to reflect the scrolling position.

Processing the WM_HSCROLL and WM_VSCROLL Messages

The scroll bar sends WM_HSCROLL and WM_VSCROLL messages to the window procedure whenever the user clicks the scroll bar or drags the scroll box. The low-order words of WM_VSCROLL and WM_HSCROLL each contain a notification code that indicates the direction and magnitude of the scrolling action.

When the WM_HSCROLL and WM_VSCROLL messages are processed, the scroll bar notification code is examined and the scrolling increment is calculated. After the increment is applied to the current scrolling position, the window is scrolled to the new position by using the ScrollWindow function, and the position of the scroll box is adjusted by using the SetScrollPos function.

After a window is scrolled, part of its client area is made invalid. To ensure that the invalid region is updated, the UpdateWindow function is used to generate a WM_PAINT message.

Processing the WM_PAINT Message

When processing the WM_PAINT message, it is convenient to draw the lines of text that you want to appear in the invalid portion of the window. The example code uses the current scrolling position and the dimensions of the invalid region to determine the range of lines within the invalid region to display them.


Example: Scrolling Text

Example of Scrolling Text

The following example shows how to have your application scroll text in response to input from the horizontal and vertical scroll bars.

HDC hdc;

PAINTSTRUCT ps;

TEXTMETRIC tm;

/* These variables are required to display text. */

static int xClient;     /* width of client area                  */

static int yClient;     /* height of client area                 */

static int xClientMax;  /* maximum width of client area          */

static int xChar;       /* horizontal scrolling unit             */

static int yChar;       /* vertical scrolling unit               */

static int xUpper;      /* average width of uppercase letters    */

static int xPos;        /* current horizontal scrolling position */

static int yPos;        /* current vertical scrolling position   */

static int xMax;        /* maximum horiz. scrolling position     */

static int yMax;        /* maximum vert. scrolling position      */

int xInc;               /* horizontal scrolling increment        */

int yInc;               /* vertical scrolling increment          */

int i;                  /* loop counter                          */

int x, y;               /* horiz. and vert. printing coords      */

int FirstLine;          /* first line in the invalidated area    */

int LastLine;           /* last line in the invalidated area     */

/* Create an array of lines to display. */

#define LINES 27

static char *abc[] = { "anteater", "bear", "cougar", "dingo",

  "elephant", "frog", "gazelle", "hyena", "iguana", "jackal",

  "kangaroo", "llama", "moose", "newt", "octopus", "penguin",

  "quail", "rat", "squid", "tortoise", "urus", "vole",

  "walrus", "xylophone", "yak", "zebra",

  "This line contains many words, but no character. Go figure." };

switch (uMsg) {

    case WM_CREATE :

        /* Get the handle of the client area's device context. */

        hdc = GetDC (hwnd);

        /* Extract font dimensions from the text metrics. */

        GetTextMetrics (hdc, &tm);

        xChar = tm.tmAveCharWidth;

        xUpper = (tm.tmPitchAndFamily & 1 ? 3 : 2) * xChar/2;

        yChar = tm.tmHeight + tm.tmExternalLeading;

        /* Free the device context. */

        ReleaseDC (hwnd, hdc);

        /*

         * Set an arbitrary maximum width for client area.

         * (xClientMax is the sum of the widths of 48 average

         * lowercase letters and 12 uppercase letters.)

         */

        xClientMax = 48 * xChar + 12 * xUpper;

        return 0;

    case WM_SIZE:

        /* Retrieve the dimensions of the client area. */

        yClient = HIWORD (lParam);

        xClient = LOWORD (lParam);

        /*

         * Determine the maximum vertical scrolling position.

         * The two is added for extra space below the lines

         * of text.

         */

        yMax = max (0, LINES + 2 - yClient/yChar);

        /*

         * Make sure the current vertical scrolling position

         * does not exceed the maximum.

         */

        yPos = min (yPos, yMax);

        /*

         * Adjust the vertical scrolling range and scroll box

         * position to reflect the new yMax and yPos values.

         */

        SetScrollRange (hwnd, SB_VERT, 0, yMax, TRUE);

        SetScrollPos (hwnd, SB_VERT, yPos, TRUE);

        /*

         * Determine the maximum horizontal scrolling position.

         * The two is added for extra space to the right of the

         * lines of text.

         */

        xMax = max (0, 2 + (xClientMax - xClient)/xChar);

        /*

         * Make sure the current horizontal scrolling position

         * does not exceed the maximum.

         */

        xPos = min (xPos, xMax);

        /*

         * Adjust the horizontal scrolling range and scroll box

         * position to reflect the new xMax and xPos values.

         */

        SetScrollRange (hwnd, SB_HORZ, 0, xMax, TRUE);

        SetScrollPos (hwnd, SB_HORZ, xPos, TRUE);

        return 0;

    case WM_PAINT:

        /* Prepare the window for painting. */

        hdc = BeginPaint(hwnd, &ps);

        /*

         * Use the current vertical scrolling position and

         * coordinates of the invalid rectangle to determine

         * the range of new lines that should be drawn in the

         * client area.

         */

        FirstLine = max (0, yPos + ps.rcPaint.top/yChar - 1);

        LastLine = min (LINES, yPos + ps.rcPaint.bottom/yChar);

        /* Display these lines. */

        for (i = FirstLine;i < LastLine;i++) {

            x = xChar * (1 - xPos);

            y = yChar * (1 - yPos + i);

            TextOut (hdc, x, y, abc[i], lstrlen(abc[i]));

            }

        /* Indicate that painting is finished. */

        EndPaint(hwnd, &ps);

        break;

    case WM_HSCROLL:

        switch(LOWORD (wParam)) {

            /* User clicked shaft left of the scroll box. */

            case SB_PAGEUP:

                 xInc = -8;

                 break;

            /* User clicked shaft right of the scroll box. */

            case SB_PAGEDOWN:

                 xInc = 8;

                 break;

            /* User clicked the left arrow. */

            case SB_LINEUP:

                 xInc = -1;

                 break;

            /* User clicked the right arrow. */

            case SB_LINEDOWN:

                 xInc = 1;

                 break;

            /* User dragged the scroll box. */

            case SB_THUMBTRACK:

                 xInc = HIWORD(wParam) - xPos;

                 break;

            default:

                 xInc = 0;

        }

        /*

         * If applying the horizontal scrolling increment does not

         * take the scrolling position out of the scrolling range,

         * increment the scrolling position, adjust the position

         * of the scroll box, and update the window.

         */

        if (xInc = max (-xPos, min (xInc, xMax - xPos))) {

            xPos += xInc;

            ScrollWindow (hwnd, -xChar * xInc, 0,

                (CONST RECT *) NULL, (CONST RECT *) NULL);

            SetScrollPos (hwnd, SB_HORZ, xPos, TRUE);

            UpdateWindow (hwnd);

        }

        return 0;

    case WM_VSCROLL:

            switch(LOWORD (wParam)) {

            /* User clicked the shaft above the scroll box. */

            case SB_PAGEUP:

                 yInc = min(-1, -yClient / yChar);

                 break;

            /* User clicked the shaft below the scroll box. */

            case SB_PAGEDOWN:

                 yInc = max(1, yClient / yChar);

                 break;

            /* User clicked the top arrow. */

            case SB_LINEUP:

                 yInc = -1;

                 break;

            /* User clicked the bottom arrow. */

            case SB_LINEDOWN:

                 yInc = 1;

                 break;

            /* User dragged the scroll box. */

            case SB_THUMBTRACK:

                 yInc = HIWORD(wParam) - yPos;

                 break;

            default:

                 yInc = 0;

        }

        /*

         * If applying the vertical scrolling increment does not

         * take the scrolling position out of the scrolling range,

         * increment the scrolling position, adjust the position

         * of the scroll box, and update the window. UpdateWindow

         * sends the WM_PAINT message.

         */

        if (yInc = max(-yPos, min(yInc, yMax - yPos))) {

            yPos += yInc;

            ScrollWindow(hwnd, 0, -yChar * yInc,

                (CONST RECT *) NULL, (CONST RECT *) NULL);

            SetScrollPos(hwnd, SB_VERT, yPos, TRUE);

            UpdateWindow(hwnd);

        }

        return 0;


Scrolling a Bitmap

This section describes changes you can make to an application's main window procedure to enable the user to scroll a bitmap. The example in Example of Scrolling a Bitmap, includes a menu item that copies the screen contents to a bitmap and displays the bitmap in the client area.

The example also processes the WM_HSCROLL and WM_VSCROLL messages generated by the scroll bars so that the user may scroll the bitmap horizontally and vertically. Unlike the example for scrolled text, the bitmap example employs the BitBlt function to draw the invalid portion of the client area.

Processing the WM_CREATE Message

When the WM_CREATE message is processed, the variables required for scrolling are initialized. Then the CreateCompatibleDC function is used to create a compatible device context (DC), the CreateBitmap function is used to create a bitmap, and the SelectObject function is used to select the bitmap for the device context. Note that a compatible DC is also known as a memory DC.

The device-specific information about the display device is retrieved. If a compatible DC is created for the screen, as in the example, the GetDeviceCaps function can be used to get this information. The information includes the number of adjacent color bits per pixel, the number of color planes, and the height and width of the DC.

Processing the WM_SIZE Message

Processing of the WM_SIZE message requires adjusting the scrolling range and position, so it reflects the dimensions of the client area and the bitmap that will be displayed.

The SetScrollRange function sets the minimum and maximum position values for a scroll bar. The SetScrollPos function adjusts the scroll box to reflect the scrolling position.

Processing the WM_HSCROLL and WM_VSCROLL Messages

When the WM_HSCROLL and WM_VSCROLL messages are processed, the scroll bar notification code is examined and the scrolling position is set to a new value that reflects the scrolling action of the user. If the scrolling position is within the scrolling range, the window is scrolled to the new position by using the ScrollWindow function. The position of the scroll box is then adjusted by using the SetScrollPos function.

After a window is scrolled, part of its client area is made invalid. To ensure that the invalid region is updated, the UpdateWindow function is used to generate a WM_PAINT message.

The following figure shows the client area before the ScrollWindow function is called.

The next figure shows the same client area after the operating system has processed the ScrollWindow function.

When processing the WM_PAINT message, an application must repaint the invalid region at the bottom of the client area.

Processing the WM_PAINT Message

When scrolling or resizing the client area, the example uses the BitBlt function to copy the appropriate portion of the bitmap to the invalid portion of the client area.

The following figure shows the client area after the application has processed the WM_PAINT message and called the BitBlt function to repaint the invalid region.


Example: Scrolling a Bitmap

Example of Scrolling a Bitmap

The following example enables the user to capture the screen contents into a bitmap and scroll the bitmap in the client area.

HDC hdc;

PAINTSTRUCT ps;

/* These variables are required by BitBlt. */

static HDC hdcWin;           /* window DC                       */

static HDC hdcScreen;        /* DC for entire screen            */

static HDC hdcScreenCompat;  /* memory DC for screen            */

static HBITMAP hbmpCompat;   /* bitmap handle for old DC        */

static BITMAP bmp;           /* bitmap data structure           */

static BOOL fBlt;            /* TRUE if BitBlt occurred         */

static BOOL fScroll;         /* TRUE if scrolling occurred      */

static BOOL fSize;           /* TRUE if fBlt & WM_SIZE          */

/* These variables are required for horizontal scrolling. */

static int xMinScroll;       /* minimum horizontal scroll value */

static int xCurrentScroll;   /* current horizontal scroll value */

static int xMaxScroll;       /* maximum horizontal scroll value */

/* These variables are required for vertical scrolling. */

static int yMinScroll;       /* minimum vertical scroll value   */

static int yCurrentScroll;   /* current vertical scroll value   */

static int yMaxScroll;       /* maximum vertical scroll value   */

switch (uMsg) {

    case WM_CREATE:

        /*

         * Create a normal DC and a memory DC for the entire

         * screen. The normal DC provides a snapshot of the

         * screen contents. The memory DC keeps a copy of this

         * snapshot in the associated bitmap.

         */

        hdcScreen = CreateDC("DISPLAY", (LPCSTR) NULL,

            (LPCSTR) NULL, (CONST DEVMODE *) NULL);

        hdcScreenCompat = CreateCompatibleDC(hdcScreen);

        /*

         * Retrieve the metrics for the bitmap associated with the

         * regular device context.

         */

        bmp.bmBitsPixel =

            (BYTE) GetDeviceCaps(hdcScreen, BITSPIXEL);

        bmp.bmPlanes = (BYTE) GetDeviceCaps(hdcScreen, PLANES);

        bmp.bmWidth = GetDeviceCaps(hdcScreen, HORZRES);

        bmp.bmHeight = GetDeviceCaps(hdcScreen, VERTRES);

        /* The width must be byte-aligned. */

        bmp.bmWidthBytes = ((bmp.bmWidth + 15) &~15)/8;

        /* Create a bitmap for the compatible DC. */

        hbmpCompat = CreateBitmap(bmp.bmWidth, bmp.bmHeight,

            bmp.bmPlanes, bmp.bmBitsPixel, (CONST VOID *) NULL);

        /* Select the bitmap for the compatible DC. */

        SelectObject(hdcScreenCompat, hbmpCompat);

        /* Initialize the flags. */

        fBlt = FALSE;

        fScroll = FALSE;

        fSize = FALSE;

        /* Initialize the horizontal scrolling variables. */

        xMinScroll = 0;

        xCurrentScroll = 0;

        xMaxScroll = 0;

        /* Initialize the vertical scrolling variables. */

        yMinScroll = 0;

        yCurrentScroll = 0;

        yMaxScroll = 0;

        break;

    case WM_SIZE: {

        int xNewSize;

        int yNewSize;

        xNewSize = LOWORD(lParam);

        yNewSize = HIWORD(lParam);

        if (fBlt)

            fSize = TRUE;

        /*

         * The horizontal scrolling range is defined by

         * (bitmap_width) - (client_width).

         */

        xMaxScroll = max(bmp.bmWidth-xNewSize, 0);

        SetScrollRange(hwnd, SB_HORZ, xMinScroll, xMaxScroll,

            FALSE);

        /*

         * The current horizontal scroll value remains within the

         * horizontal scrolling range.

         */

        xCurrentScroll = min(xCurrentScroll, xMaxScroll);

        SetScrollPos(hwnd, SB_HORZ, xCurrentScroll, TRUE);

        /*

         * The vertical scrolling range is defined by

         * (bitmap_height) - (client_height).

         */

        yMaxScroll = max(bmp.bmHeight - yNewSize, 0);

        SetScrollRange(hwnd, SB_VERT,

            yMinScroll, yMaxScroll, FALSE);

        /*

         * The current vertical scroll value remains within the

         * vertical scrolling range.

         */

        yCurrentScroll = min(yCurrentScroll, yMaxScroll);

        SetScrollPos(hwnd, SB_VERT, yCurrentScroll, TRUE);

    }

        break;

    case WM_PAINT: {

        PRECT prect;

        hdc = BeginPaint(hwnd, &ps);

        /*

         * If the window has been resized and the user has

         * captured the screen, use the following call to

         * BitBlt to paint the window's client area.

         */

        if (fSize) {

            BitBlt(ps.hdc,

                0, 0,

                bmp.bmWidth, bmp.bmHeight,

                hdcScreenCompat,

                xCurrentScroll, yCurrentScroll,

                SRCCOPY);

            fSize = FALSE;

        }

        /*

         * If scrolling has occurred, use the following call to

         * BitBlt to paint the invalid rectangle.

         *

         * The coordinates of this rectangle are specified in the

         * RECT structure to which prect points.

         *

         * Note that it is necessary to increment the seventh

         * argument (prect->left) by xCurrentScroll and the

         * eighth argument (prect->top) by yCurrentScroll in

         * order to map the correct pixels from the source bitmap.

         */

        if (fScroll) {

            prect = &ps.rcPaint;

            BitBlt(ps.hdc,

                prect->left, prect->top,

                (prect->right - prect->left),

                (prect->bottom - prect->top),

                hdcScreenCompat,

                prect->left + xCurrentScroll,

                prect->top + yCurrentScroll,

                SRCCOPY);

            fScroll = FALSE;

        }

        EndPaint(hwnd, &ps);

    }

        break;

    case WM_HSCROLL: {

        int xDelta;     /* xDelta = new_pos - current_pos */

        int xNewPos;    /* new position */

        int yDelta = 0;

        switch (LOWORD(wParam)) {

            /* User clicked the shaft left of the scroll box. */

            case SB_PAGEUP:

                xNewPos = xCurrentScroll - 50;

                break;

            /* User clicked the shaft right of the scroll box. */

            case SB_PAGEDOWN:

                xNewPos = xCurrentScroll + 50;

                break;

            /* User clicked the left arrow. */

            case SB_LINEUP:

                xNewPos = xCurrentScroll - 5;

                break;

            /* User clicked the right arrow. */

            case SB_LINEDOWN:

                xNewPos = xCurrentScroll + 5;

                break;

            /* User dragged the scroll box. */

            case SB_THUMBPOSITION:

                xNewPos = HIWORD(wParam);

                break;

            default:

                xNewPos = xCurrentScroll;

        }

        /* New position must be between 0 and the screen width. */

        xNewPos = max(0, xNewPos);

        xNewPos = min(xMaxScroll, xNewPos);

        /* If the current position does not change, do not scroll.*/

        if (xNewPos == xCurrentScroll)

            break;

        /* Set the scroll flag to TRUE. */

        fScroll = TRUE;

        /* Determine the amount scrolled (in pixels). */

        xDelta = xNewPos - xCurrentScroll;

        /* Reset the current scroll position. */

        xCurrentScroll = xNewPos;

        /*

         * Scroll the window. (The system repaints most of the

         * client area when ScrollWindow is called; however, it is

         * necessary to call UpdateWindow in order to repaint the

         * rectangle of pixels that were invalidated.)

         */

        ScrollWindow(hwnd, -xDelta, -yDelta, (CONST RECT *) NULL,

            (CONST RECT *) NULL);

        UpdateWindow(hwnd);

        /* Reset the scroll bar. */

        SetScrollPos(hwnd, SB_HORZ, xCurrentScroll, TRUE);

    }

        break;

    case WM_VSCROLL: {

        int xDelta = 0;

        int yDelta;     /* yDelta = new_pos - current_pos */

        int yNewPos;    /* new position */

        switch (LOWORD(wParam)) {

            /* User clicked the shaft above the scroll box. */

            case SB_PAGEUP:

                yNewPos = yCurrentScroll - 50;

                break;

            /* User clicked the shaft below the scroll box. */

            case SB_PAGEDOWN:

                yNewPos = yCurrentScroll + 50;

                break;

            /* User clicked the top arrow. */

            case SB_LINEUP:

                yNewPos = yCurrentScroll - 5;

                break;

            /* User clicked the bottom arrow. */

            case SB_LINEDOWN:

                yNewPos = yCurrentScroll + 5;

                break;

            /* User dragged the scroll box. */

            case SB_THUMBPOSITION:

                yNewPos = HIWORD(wParam);

                break;

            default:

                yNewPos = yCurrentScroll;

        }

        /* New position must be between 0 and the screen height. */

        yNewPos = max(0, yNewPos);

        yNewPos = min(yMaxScroll, yNewPos);

        /* If the current position does not change, do not scroll.*/

        if (yNewPos == yCurrentScroll)

            break;

        /* Set the scroll flag to TRUE. */

        fScroll = TRUE;

        /* Determine the amount scrolled (in pixels). */

        yDelta = yNewPos - yCurrentScroll;

        /* Reset the current scroll position. */

        yCurrentScroll = yNewPos;

        /*

         * Scroll the window. (The system repaints most of the

         * client area when ScrollWindow is called; however, it is

         * necessary to call UpdateWindow in order to repaint the

         * rectangle of pixels that were invalidated.)

         */

        ScrollWindow(hwnd, -xDelta, -yDelta, (CONST RECT *) NULL,

            (CONST RECT *) NULL);

        UpdateWindow(hwnd);

        /* Reset the scroll bar. */

        SetScrollPos(hwnd, SB_VERT, yCurrentScroll, TRUE);

    }

        break;

    case WM_COMMAND: /* uMsg: command from app. menu */

        switch(wParam) {

            case IDM_STC:

                /*

                 * Copy the contents of the current screen

                 * into the compatible DC.

                 */

                BitBlt(hdcScreenCompat, 0, 0, bmp.bmWidth,

                    bmp.bmHeight, hdcScreen, 0, 0, SRCCOPY);

                /*

                 * Copy the compatible DC to the client area.

                 */

                hdcWin = GetDC(hwnd);

                BitBlt(hdcWin, 0, 0, bmp.bmWidth, bmp.bmHeight,

                    hdcScreenCompat, 0, 0, SRCCOPY);

                ReleaseDC(hwnd, hdcWin);

                fBlt = TRUE;

                break;

            default:

                return (DefWindowProc(hwnd, uMsg,

                    wParam, lParam));

        }

        break;


Creating a Keyboard Interface for a Standard Scroll Bar

Although a scroll bar control provides a built-in keyboard interface, a standard scroll bar does not. To implement a keyboard interface for a standard scroll bar, a window procedure must process the WM_KEYDOWN message and examine the virtual-key code specified by the wParam parameter. If the virtual-key code corresponds to an arrow key, the window procedure sends itself a WM_HSCROLL or WM_VSCROLL message with the wParam parameter set to the appropriate scroll bar notification code. For example, when the user presses the UP ARROW key, the window procedure receives a WM_KEYDOWN message with wParam equal to VK_UP. In response, the window procedure sends itself a WM_VSCROLL message with the low-order word of wParam set to the SB_LINEUP notification code.

The following example shows how to include a keyboard interface for a standard scroll bar.

WORD wScrollNotify = 0xFFFF;

.

.

.

case WM_KEYDOWN:

    switch (wParam) {

        case VK_UP:

            wScrollNotify = SB_LINEUP;

            break;

        case VK_PRIOR:

            wScrollNotify = SB_PAGEUP;

            break;

        case VK_NEXT:

            wScrollNotify = SB_PAGEDOWN;

            break;

        case VK_DOWN:

            wScrollNotify = SB_LINEDOWN;

            break;

        case VK_HOME:

            wScrollNotify = SB_TOP;

            break;

        case VK_END:

            wScrollNotify = SB_BOTTOM;

            break;

    }

    if (wScrollNotify != -1)

        SendMessage(hwnd, WM_VSCROLL,

            MAKELONG(wScrollNotify, 0), 0L);

    break;

.

.

.


Functions and Messages

Following are the functions and messages used with scroll bars.

Functions

EnableScrollBar

ScrollWindowEx

GetScrollPos

SetScrollPos

GetScrollRange

SetScrollRange

ScrollDC

ShowScrollBar

ScrollWindow


Messages

Messages

SBM_ENABLE_ARROWS

SBM_GETPOS

SBM_GETRANGE

SBM_SETPOS

SBM_SETRANGE

SBM_SETRANGEREDRAW

WM_CTLCOLORSCROLLBAR

WM_HSCROLL

WM_VSCROLL


Static Controls Overview

About Static Controls

Microsoft® Windows™ provides dialog boxes and controls to support communications between an application and the user. A static control is a control that enables an application to provide the user with certain types of text and graphics that require no response. Applications often use static controls to label other controls or to separate a group of controls. Although static controls are child windows, they cannot be selected. Therefore, they cannot receive the keyboard focus, cannot have a keyboard interface, and cannot receive user input. A static control does not send messages to its parent window. Static controls belong to the STATIC window class.

Although static controls can be used in overlapped, pop-up, and child windows, they are designed for use in dialog boxes, where Windows standardizes their behavior. If a developer uses static controls outside dialog boxes, it increases the risk that the application might behave in a nonstandard fashion. Typically, developers either use static controls in dialog boxes or use window subclassing to create customized static controls.

The following topics discuss static controls:

Terms

Static Control Types and Styles

Messages for Icons

Static Controls and Colors

Default Static-control Behavior

Using Static Controls

Messages


Static Control Types and Styles

Windows provides four types of static controls: rectangle, frame, text, and icon. Each type has one or more styles.

Rectangle

A rectangle static control displays a rectangle filled with color in one of three styles: black, gray, or white. These styles are defined by the constants SS_BLACKRECT, SS_GRAYRECT, and SS_WHITERECT. The following figure shows the three rectangle styles. For clarity, the illustration shows the white rectangle on a black background; the actual display does not contain a black rectangle.

Frame

A frame static control displays a colored frame in one of three styles: black, gray, or white. These styles are defined by the constants SS_BLACKFRAME, SS_GRAYFRAME, and SS_WHITEFRAME. The following figure shows the three frame styles. For clarity, the illustration shows the white frame on a black background; the actual display does not contain a black rectangle.

Text

A text static control displays text in a rectangle in one of five styles: centered, left aligned with word wrap, left aligned without word wrap, right aligned, or "simple." These styles are defined by the constants SS_CENTER, SS_LEFT, SS_LEFTNOWORDWRAP, SS_RIGHT, and SS_SIMPLE, respectively. Windows rearranges the text in these controls in predefined ways, except for "simple" text, which is not rearranged. The following figure shows three text styles: centered, left aligned, and right aligned. For clarity, the illustration shows the text inside a box; the actual display does not contain a box.

An application can change the text in a text static control at any time by using the SetWindowText function or the WM_SETTEXT message.

The system displays as much text as it can in the static control and clips whatever does not fit. Retrieve the font metrics for the text to calculate an appropriate size for the control.

Icon

An icon static control displays an icon in an icon control. There is one icon style, defined by the constant SS_ICON. An application can use this type of control only in dialog boxes. An icon is also the only type of static control that can receive messages from its parent window. The following figure shows a sample icon.

Static Control Styles

Many developers develop dialog boxes by using stand-alone tools and so may not need to specify static control styles. However, if a developer uses the CreateWindow or CreateWindowEx function to create a static control for an application, the developer must use the following constants to define the style.

Style	Description

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 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 centered line.

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

For more information about the colors used by static controls, see Static Control Color Messages.


Messages for Icons

An application can retrieve the handle of the current icon or change it by sending a message to the icon control using the SendDlgItemMessage function. An icon is the only static control that can receive messages from its parent window. The following table describes these messages.

Message	Response

STM_GETICON	Returns the handle of the icon associated with the icon control.

STM_SETICON	Associates an icon with an icon control. This message returns the handle of the icon previously associated with the icon control (or zero, if an error occurs).


Static Control Color Messages

Windows provides default color values for static controls. The system sends a WM_CTLCOLORSTATIC message to a static control's parent window before the control is drawn. This message contains a handle of the static control's device context (DC) and a handle of the child window. The parent window can use these handles to change the static control's text and background colors. The following table shows the default static control color messages.

Value	Use

COLOR_BACKGROUND	For coloring black rectangles and frames

COLOR_WINDOW	For coloring gray rectangles and frames

COLOR_WINDOWFRAME	For coloring white rectangles and frames

COLOR_WINDOWTEXT	For coloring text in text controls

An application can obtain the default values for these colors by calling the GetSysColor function or set the color values by calling the SetSysColors function.

Portability Issue:	In Windows NT, the WM_CTLCOLOR message has been replaced by the set of control color messages. For applications written for earlier versions of Windows, the developer must modify the code for processing the WM_CTLCOLOR message when porting the application to Windows NT.


Default Message Processing

The window procedure for the predefined static control window class carries out default processing for all messages that the static control procedure does not process. When the static control returns FALSE for any message, the predefined window procedure checks the messages and carries out the default action described in the following table. In the table, a text static control is a static control with the SS_LEFT, SS_CENTER, SS_RIGHT, SS_SIMPLE, or SS_LEFTNOWORDWRAP style.

Message	Default action

STM_GETICON	Returns the handle of the icon if the static control is an icon; otherwise, returns zero.

STM_SETICON	Sets a new icon for the static control; invalidates the rectangle to draw the new icon; returns a handle of the previous icon.

WM_CREATE	Loads the icon and sizes the window to the icon size, for icon controls. Takes no action for other static controls.

WM_DESTROY	Frees and destroys any icon, for icon controls. Takes no action for other static controls.

WM_ENABLE	Repaints visible static controls.

WM_GETDLGCODE	Returns DLGC_STATIC.

WM_GETFONT	Returns the handle of the font for text static controls.

WM_GETTEXT	Returns 2 if the control is an icon that was set by using the STM_SETICON message; otherwise, copies the text of the control into an application-defined buffer.

WM_GETTEXTLENGTH	Returns the length, in characters, of the text for a text static control.

WM_NCCREATE	Sets the window text for text static controls; otherwise, returns TRUE.

WM_NCDESTROY	Takes no action if the control style is SS_LEFT, SS_CENTER, SS_RIGHT, or SS_SIMPLE; otherwise, calls the DefWindowProc function.

WM_NCHITTEST	Returns HTTRANSPARENT.

WM_PAINT	Repaints the control.

WM_SETFONT	Sets the font and repaints for text static controls.

WM_SETTEXT	Sets the text and repaints for text static controls.

The predefined window procedure passes all other messages to DefWindowProc for default processing.


Using Static Controls

The following code example uses a timer and the STM_SETICON message to animate an icon in a dialog box. The icon handles and the icon identifier (IDI_ICON) are defined in a global header file.

LRESULT APIENTRY StaticProc(hDlg, message, wParam, lParam)

HWND hDlg;      /* window handle of dialog box           */

UINT message;   /* type of message                       */

UINT wParam;    /* message-specific information          */

LONG lParam;

{

    UINT idTimer = 1;

    static UINT i;

    static HICON aIcons[11];

    switch (message) {

        case WM_INITDIALOG: /* initialize dialog box */

            i = 0;

            /* Load icons("hinst" is defined globally). */

            hiconOne    = LoadIcon(hinst, "OneIco");

            aIcons[i]   = hiconOne;

            hiconTwo    = LoadIcon(hinst, "TwoIco");

            aIcons[++i] = hiconTwo;

                .

                . /* Continue with the remaining icons. */

                .

            i = 0;

             /*

              * Use STM_SETICON to associate an icon with the

              * IDI_ICON identifier.

              */

            SendDlgItemMessage(hDlg, /* dialog box window handle */

               IDI_ICON,             /* icon identifier          */

               STM_SETICON,          /* message to send          */

               (WPARAM) aIcons[i++], /* icon handle              */

               0);                   /* not used                 */

            /* Set a timer for 50-millisecond intervals. */

            SetTimer(hDlg, idTimer, 50, (TIMERPROC) NULL);

            return TRUE;

        case WM_TIMER:

             /*

              * Use STM_SETICON to associate a new icon with

              * the IDI_ICON identifier whenever a WM_TIMER

              * message is received.

              */

            SendDlgItemMessage(hDlg, /* dialog box window handle */

               IDI_ICON,             /* icon identifier          */

               STM_SETICON,          /* message to send          */

               (WPARAM) aIcons[i++], /* new icon handle          */

               0);                   /* not used                 */

            if (i == 10)

                i = 0;

            break;

        case WM_COMMAND:

            if (wParam == IDOK

                || wParam == IDCANCEL) {

                EndDialog(hDlg, TRUE);

                return TRUE;

            }

            return 0;

        case WM_DESTROY: /* clean up  */

            KillTimer(hDlg, idTimer);

            DeleteObject(hiconOne);

            DeleteObject(hiconTwo);

                .

                . /* Continue with the remaining icons. */

                .

            return 0;

    }

    return FALSE;

        UNREFERENCED_PARAMETER(lParam);

}


Messages

Following are the messages used with static controls. (STM_GETICON and STM_SETICON are used only with icons.)

STM_GETICON

STM_SETICON

WM_CTLCOLORSTATIC


Menus Overview

About Menus

A menu is one or more lists of application commands. Each command, which is represented by a text string or bitmap, is called a menu item. By using the mouse or the keyboard to choose a menu item, the user directs the application to perform the command associated with that menu item. When the user chooses a menu item, Microsoft® Windows™ sends the application a command message that indicates which menu item the user chose.

This topic describes menus and explains how to use them in a Win32 application.

The following topics discuss Win32 menus:

Terms

Menu Bars and Pop-up Menus

Menu Handles

Class Menus

Menu Items

Keyboard Access to Menus

Menu Creation

Menu Display

Menu Destruction

Menu Messages

Menu Modifications

Using a Menu-Template Resource

Creating a Floating Pop-up Menu

Using Menu-Item Bitmaps

Creating Owner-drawn Menu Items

Using Custom Check Mark Bitmaps

Functions and Messages


Menu Bars and Pop-up Menus

The menus in an application written for Microsoft Windows are arranged hierarchically. A menu bar (sometimes called a top-level menu) resides at the uppermost level of the hierarchy; the lower levels consist of pop-up menus (also known as submenus).

The items in a menu bar represent the main categories of commands provided by an application. Selecting an item from the menu bar typically activates a pop-up menu whose items correspond to the commands in a given category. For example, a menu bar might contain a File item that, when the user selects it, activates a pop-up menu with menu items such as New, Open, Save, and so on. The following illustration shows the menu bar and the pop-up menu for the file command in Windows Notepad.

Only an overlapped or pop-up window can contain a menu bar; a child window cannot contain one. A menu bar is always visible. If the window has a title bar, Windows positions the menu bar just below it. By contrast, a pop-up menu is not visible until the user selects a menu item that activates it. When this menu is displayed, it is attached to the title bar.

Every menu must have an owner window. Windows sends messages to a menu's owner window when the user selects the menu or chooses a command from the menu. These messages are described in Menu Messages.

Floating Pop-up Menus

Windows provides a special type of pop-up menu called a floating pop-up menu. A floating pop-up menu is not attached to the menu bar; it can appear anywhere on the screen. An application typically associates a floating pop-up menu with a portion of a window such as the client area or with a specific object such as an icon.

A floating pop-up menu remains hidden until the user selects it (for example, by clicking the appropriate screen location with the mouse.) A floating pop-up menu is typically displayed at the position of the caret or mouse cursor.

The System Menu

A System menu (also known as the Control menu) is a pop-up menu defined and managed almost exclusively by the system. It is represented by a small box containing a horizontal line that is displayed at the left end of the title bar. When the user clicks the box, Windows displays the System menu. Windows also displays the System menu when the user clicks the icon of a minimized application.

A System menu provides a standard set of menu items the user can choose to change a window's size or position, close the application, or activate the Windows Task List. Items in a System menu can be added, deleted, and modified, but most applications just use the standard set of menu items. The following illustration shows a System Menu with the standard menu items.

An overlapped, pop-up, or child window can have a System menu. It is uncommon for an overlapped or pop-up window not to include a System menu.

When the user chooses a command from a System menu, Windows sends a WM_SYSCOMMAND message to the menu's owner window. In most applications, the window procedure does not process messages from a System menu. Instead, it simply passes the messages to the DefWindowProc function for system-default processing of the message. If a command is added to a System menu, the window procedure must process the command.


Menu Handles

The system generates a unique handle for each menu. A menu handle is a value of the HMENU type. An application must specify a menu handle in many of the Windows menu functions. The developer receives the handle of a menu bar when he or she creates the menu or loads a menu resource. For information about creating menus and loading menus, see Menu Creation.

The GetMenu or GetSubMenu function is used to retrieve the handle of a menu that has been created or loaded. GetMenu returns the handle of the menu bar assigned to the specified window. GetSubMenu returns the handle of a pop-up menu within the specified menu bar or pop-up menu. The GetSystemMenu function is used to retrieve the handle of a window's System menu.


Class Menus

When registering a window class, the developer can specify a default menu for that class. This default menu is known as the class menu. To specify a class menu, the developer must assign the name of the menu, as given in your application's resource-definition file, to the lpszMenuName member of the WNDCLASS structure used to register the window class. After the window class has been registered, each window of that class will have the specified class menu. The developer can override the class menu by specifying the handle of a different menu when creating a window of that class. For more information about window classes, see Window Classes.


Menu Items

There are two kinds of menu items in Win32 applications: command items and pop-up items. When the user chooses a command item, Windows sends a WM_COMMAND or WM_SYSCOMMAND message to the window procedure of the menu's owner window. A command item on a System menu generates a WM_SYSCOMMAND message; command items in other menus generate WM_COMMAND messages. When the user selects a pop-up item, Windows displays a pop-up menu but doesn't send a command message to the window procedure.

As a rule, menu items in a menu bar consist of pop-up items; menu items in a pop-up menu consist of command items. Because a pop-up menu can contain pop-up items, pop-up menus can originate from within pop-up menus, producing a cascading effect as shown in the following illustration.

When a pop-up item is included in a pop-up menu, Windows automatically adds a small arrow to the right of the menu item's text string or bitmap (see the Word Processing and Spreadsheet items in the preceding illustration). The arrow is a visual cue to the user that Windows will display another pop-up menu when the item is selected.

Menu-Item Identifier

Each command item has an identifier associated with it. An identifier is an application-defined integer value that Windows sends to the window procedure of the menu's owner window when the user chooses a command item. Windows sends the identifier as part of a WM_COMMAND message. The window procedure examines the identifier to determine the source of the message, and then processes the message accordingly.

A menu identifier must be a value from 0 to 65,535, even though it is a 32-bit integer. This is because the WM_COMMAND message passes a menu identifier as the low-order word of its wParam parameter.

A pop-up item has no identifier. A pop-up item does not need an identifier, because Windows does not send a WM_COMMAND message when the user selects a pop-up item. Instead, Windows activates the pop-up menu associated with the pop-up item.

Checked and Unchecked Menu Items

A menu item can be either checked or unchecked. When a menu item is checked, Windows uses a bitmap to display a check mark to the left of the menu item. When the menu item is unchecked, Windows does not display the check mark. Only menu items in a pop-up menu can be checked; menu items in a menu bar can not be checked.

An application typically uses check marks to indicate menu options that are in effect. For example, when the user selects paragraph formatting options from a menu in a word processing application, the application places check marks next to the selected options. The following illustration shows check marks next to the Left and Single Space options in a word processing application's Paragraph menu.

A check mark attribute controls whether a menu item is checked or not. A menu item's check mark attribute can be set by using the CheckMenuItem function. The GetMenuState function is used to determine whether a menu item is currently checked or unchecked.

Windows provides a default bitmap for displaying check marks. The developer, however, can substitute other bitmaps and direct Windows to use them instead of the default. Windows requires, however, that these check mark bitmaps have the same dimensions as the default check mark bitmap. The GetMenuCheckMarkDimensions function can be used to retrieve the default dimensions.

Two bitmaps can be associated with each menu item: one for when the menu item is checked and another for when it is unchecked. The SetMenuItemBitmaps function can be used to associate bitmaps with a menu item.

The developer can either provide check mark bitmaps as bitmap resources or create the bitmaps at run time by using graphic device interface (GDI) bitmap functions. A bitmap resource, however, isn't suitable for all video resolutions and aspect ratios, so the bitmap must be sized appropriately. The check mark bitmaps can be either monochrome or color. However, on a color screen the bitmap colors are inverted when the menu item is highlighted, and this result may be undesirable. For more information about bitmaps, see Bitmaps.

Enabled, Disabled, and Grayed Menu Items

A menu item can be enabled, disabled, or grayed. By default, a menu item is enabled. When the user chooses an enabled menu item, Windows sends a command message to the corresponding window procedure or displays the corresponding pop-up menu, depending on whether the menu item is a command item or a pop-up item.

When menu items are not available to the user, they should be disabled or grayed. Disabled or grayed menu items do not generate a command message or display a pop-up menu when a user chooses them. Typically, applications gray an unavailable menu item to provide a visual clue to the user that a command is not available. A disabled menu item does not provide this visual clue. A disabled item can serve as a heading for group related menu items. (For example, a Save heading can be listed and then a series of commands such as Save File, Save All, and Save As). A grayed item can be used when an action is not appropriate. (For example, the Print command in the File menu can be grayed when the system does not have a printer installed.) The following illustration shows grayed items in an Edit menu.

The EnableMenuItem function is used to enable, disable, or gray a menu item, and the GetMenuState function is used to determine whether a menu item is enabled, disabled, or grayed.

Menu-Item Separators and Line Breaks

Windows provides a special type of menu item, called a separator, that consists of a horizontal line. A separator menu item can be used in a pop-up menu to divide a menu into groups of related items. A separator item cannot be used in a menu bar. The user cannot select a separator menu item, and a separator does not send command messages to the window procedure.

When a menu bar contains more items than will fit on one line, Windows automatically breaks it into two or more lines. You can force a line break at a specific item on a menu bar by assigning the MF_MENUBREAK flag to the item. Windows places that item and all remaining items on a new line.

The MF_MENUBREAK and MF_MENUBARBREAK flags are used to divide items in a pop-up menu into multiple columns. When MF_MENUBREAK flag is assigned to an item, Windows places it and all remaining items in a new column. The MF_MENUBARBREAK flag creates a similar effect, except Windows includes a vertical line in the menu to separate the new column from the old one.

Menu-Item Position

Windows assigns an integer position value to each item on a menu and uses the value to keep track of each item's position in the menu. Position values are zero-based; that is, the first item on a menu occupies position zero, the next position one, and so on. In a menu bar, the leftmost menu item is considered the first item, so it occupies position zero; in a pop-up menu, the uppermost menu item occupies position zero. Windows assigns position values to menu-item separators. The following illustration shows the position values of both items and separators in a menu bar and a pop-up menu.

A number of functions are used to add an item to a menu, delete an item from a menu, or modify an existing item on a menu. When one of these functions is called, the item to be modified is identified either by its position value or, if it is a command item, by its identifier. Either the MF_BYPOSITION or MF_BYCOMMAND flag is also specified. For more information about modifying the contents of a menu, see Menu Modifications.

Highlighted Menu Items

Windows automatically highlights menu items as the user selects them. Highlighting can, however, be explicitly added or removed from a menu item on the menu bar by calling the HiliteMenuItem function. This function has no effect on menu items in pop-up menus. When you use HiliteMenuItem to highlight a menu item, however, the menu item only appears to be selected; if the user presses the ENTER key, the highlighted item is not chosen.

Owner-drawn Menu Items

An application can completely control the appearance of a menu item by using an owner-drawn item. Owner-drawn items require an application to take total responsibility for drawing selected (highlighted), checked, and unchecked states. For example, if an application provided a font menu it could draw each menu item by using the corresponding font; the item for roman would be drawn with a roman font, the item for italic would be drawn in italic, and so on.

For information on how to create owner-drawn menu items, see Creating Owner-drawn Menu Items.

Help Item

The developer should provide a standard interface for the user, including a Help item on an application's menu bars. The item should read "Help," and it should be the rightmost item on the menu bar.


Keyboard Access to Menus

Windows provides a standard keyboard interface for menus. You can enhance this interface by including mnemonics and accelerator keys for your menu items. The following three sections describe the standard keyboard interface, mnemonics, and accelerator keys.

Standard Keyboard Interface

Windows is designed to work with or without a mouse or other pointing device. Because Windows provides a standard keyboard interface the user can use the keyboard to select menu items. Special code is not needed to support this keyboard interface. An application receives a command message whether a menu item is selected through the keyboard or by using a mouse. The standard keyboard interface processes the following keystrokes.

Keystroke	Action

ALT	Toggles in and out of menu bar mode.

ALT+SPACEBAR	Displays the System menu.

ESC	Exits menu mode.

RIGHT ARROW	Cycles to the next top-level menu item. This keystroke cycles between the application and System menus. If the selected item is in a pop-up menu, the next column in the pop-up menu is selected or the next top-level menu item is selected.

LEFT ARROW	Works like the RIGHT ARROW key, except in the opposite direction. In pop-up menus, this keystroke backs up one column; when the currently selected item is in the far-left column, the previous pop-up menu is selected.

UP or DOWN ARROWS	Activate a pop-up menu when pressed in a top-level menu. When pressed in a pop-up menu, either keystroke selects the next or previous item.

ENTER	Activates a pop-up menu and highlights the first item if an item has a pop-up menu associated with it; otherwise, this keystroke chooses the item as if the user released the mouse button while the item was selected.

Alphabetic character	Selects the first menu item with the specified character as its mnemonic. If the selected item onvokes a pop-up menu, the menu is displayed and the first item is highlighted; otherwise, the item is chosen.

Mnemonics

The standard keyboard interface for menus can be enhanced by adding mnemonics to menu items. A mnemonic is a underlined letter in the text of a menu item. When a menu is active, the user can select a menu item by pressing the key that corresponds to the item's underlined letter. The menu bar is active when the user presses and releases the ALT key and the first item on the menu bar is highlighted. A pop-up menu is active when it is displayed.

A mnemonic keystroke for a menu item is created by preceding a character in the item's text string with an ampersand. For example, "&Move" causes Windows to underline the "M" character. The following illustration shows the mnemonics in the System menu.

 Keyboard Accelerators

In addition to having a mnemonic, a menu item can have a keyboard accelerator associated with it. A keyboard accelerator is different from a mnemonic in that the menu need not be active for the accelerator key to work. Also, a mnemonic is always associated with a menu item, while a keyboard accelerator is usually associated with a menu item, but it does not have to be.

Text to identify the keyboard accelerator is added to the menu-item text string. The accelerator text appear to the right of the menu-item name after a backslash and tab character. For example, "$ClosetF4" represents a Close item with the F4 key as its keyboard accelerator and with C as its mnemonic. For more information on accelerators, see Keyboard Accelerators. The following illustration shows accelerators in the System menu.


Menu Creation

The developer can use the following methods to create a menu for use in an application:

Load a menu from a menu-template resource.

Build a menu from a menu template created at run time.

Use the menu creation functions to build a menu at run time.

The following sections describe how to use these three methods to create menus.

Menu-Template Resources

Most developers implement menus by creating a menu-template resource that is loaded at run time. A menu template defines a menu, including the items in the menu bar and all pop-up menus.

The first step in using a menu-template resource is to define a menu template in the resource-definition file for an application. Then a resource compiler is used to create the resource and add it to the application's executable file. At run time, the LoadMenu function is called to load the menu-template resource into memory and to retrieve the handle of the menu. Then a call the SetMenu function assigns the menu to a window.

Implementing menus as resources makes an application easier to localize for use in other countries. The resource-definition file is edited and recompiled, and the new resources are added to the application's executable file. For more information on creating a menu resource, see Using a Menu-Template Resource.

Menu Template in Memory

A menu can be created from a menu template that is built in memory at run time. A menu is created from the menu template by passing the address of the MENUITEMTEMPLATEHEADER structure to the LoadMenuIndirect function. The last member of the MENUITEMTEMPLATEHEADER structure specifies the offset of the array of MENUITEMTEMPLATE structures. Each member of the array describes a menu item. LoadMenuIndirect returns the handle of the menu.

Menu-Creation Functions

Another way to create a menu at run time is to use the CreateMenu and CreatePopupMenu functions to create empty menus. CreateMenu creates an empty menu bar; CreatePopupMenu creates an empty pop-up menu. Then menu items are added to the menus by using the AppendMenu or InsertMenu functions.


Menu Display

After a menu has been loaded or created, it must be assigned to a window before Windows can display it. This can be done by creating a class menu (see Class Menus), by specifying the handle of the menu as the hmenu parameter of the CreateWindowEx function, or by calling the SetMenu function.

The TrackPopupMenu function can be used to display a pop-up menu. To do so, the handle of a pop-up menu is passed to the function. The menu's owner window, the screen position where Windows should display the menu, and the mouse button the user must use to choose an item must also be specified.


Menu Destruction

If a menu is assigned to a window and that window is destroyed, Windows automatically destroys the menu, freeing the menu's handle and the memory occupied by the menu. Windows does not automatically destroy a menu that is not assigned to a window. An application must destroy the unassigned menu by calling the DestroyMenu function; otherwise, the menu continues to exist in memory even after the application closes.


Menu Messages

Windows reports menu-related activity by sending messages to the window procedure of the window that owns the menu. The first menu-related message the window procedure receives is WM_SYSCOMMAND. Windows sends this message when the user activates the menu by clicking the menu bar or by pressing a key that activates the menu (for more information, see Standard Keyboard Interface). The WM_SYSCOMMAND message includes a flag, either SC_KEYMENU or SC_MOUSEMENU, that indicates the hardware device used to activate the menu.

Next, Windows sends the WM_INITMENU message to the window procedure before Windows displays any pop-up menus, so an application can modify the menus before the user sees them. Windows sends the WM_INITMENU message only once per menu activation.

When the user selects a pop-up item, Windows sends the owner window the WM_INITMENUPOPUP message before displaying the pop-up menu. This message gives the application a second opportunity to modify the pop-up menu before it is displayed.

Each time the user moves the highlighting from one item to another, Windows sends a WM_MENUSELECT message to the window procedure of the menu's owner window. This message identifies the currently selected menu item. Many applications provide an information area at the bottom of their main windows and use this message to display additional information about the selected menu item.

Windows sends a WM_COMMAND message to the window procedure when the user chooses a command item from a menu. The low-order word of the WM_COMMAND message's wParam parameter contains the identifier of the chosen item. The window procedure should examine the identifier and process the message accordingly.


Menu Modifications

A number of functions can be used to modify a menu after it has been loaded or created. The AppendMenu and InsertMenu functions are used to add items to a menu. AppendMenu appends a menu item to the end of a menu; InsertMenu inserts a menu item at a specified position in a menu. Both functions permit the attributes of the menu item to be specified, including whether the menu item is enabled, checked, grayed, and so on.

The ModifyMenu function is used to change the appearance or attributes of an existing menu item. For example, the text string or bitmap of a menu item can be enabled, disabled, grayed, checked, or unchecked. ModifyMenu replaces the specified menu item with a new item.

The DeleteMenu or RemoveMenu functions are used to delete a menu item from a menu. If the item being deleted is a pop-up item, DeleteMenu deletes the associated pop-up menu, discarding the menu handle and freeing the memory used by the pop-up menu. The RemoveMenu function deletes a menu item, but if the item activates a pop-up menu, it does not destroy the pop-up menu or its handle, allowing the menu to be reused.

After a menu bar has been modified, the DrawMenuBar function must be called to redraw the menu bar. Otherwise, the modifications will not appear until Windows redraws the owner window.


Using a Menu-Template Resource

The developer typically includes a menu in an application by defining a menu template in the application's resource-definition file and then loading the menu at run time. This section describes how to define and load a menu-template resource.

Defining a Menu-Template Resource

A menu-template resource represents an application's menu bar and all the related pop-up menus. The MENU statement marks the beginning of a menu template and provides the identifier used to load the menu. The identifier must be either a unique string or a unique integer.

The POPUP statement defines a pop-up item. A top-level pop-up item appears in the menu bar and activates a pop-up menu when it is selected. A nested pop-up item appears in a pop-up menu and activates a cascaded pop-up menu when it is selected.

The MENUITEM statement defines a command item. A top-level command item appears in the menu bar and generates a command message when it is selected. A nested command item appears in a pop-up menu and also generates a command message.

To define a string for a pop-up item or command item, enclose it in quotation marks and place it immediately to the right of the POPUP statement. You should include an ampersand (&) in the string to specify the mnemonic for the menu item. You should also include a keyboard accelerator, if applicable, and use the "\t" escape sequence to separate the accelerator text from the menu-item text.

The command identifier for a command item must appear immediately to the right of the menu-item text string. Use a named constant as the identifier and define the constant in your application's header file.

A number of options control the appearance and behavior of pop-up and command items. You can specify these options to the right of the menu-item text string (for a pop-up item) or to the right of the menu-item identifier (for a command item). The following menu-item options can be specified:

Option	Description

CHECKED	Item has a check mark next to it. This option is not valid for a top-level pop-up menu.

GRAYED	Item is disabled and its text string appears on the menu in a dimmed (grayed) shade of the menu-text color.

INACTIVE	Item is disabled and its text string appears in the normal menu-text color.

MENUBARBREAK	Same as MENUBREAK except that in pop-up menus, it separates the new column from the old column with a vertical line.

MENUBREAK	Menu-bar item is placed on a new line. An item on a pop-up menu is placed in a new column with no dividing line between the columns.

You can use the bitwise OR operator to combine these options. The INACTIVE and GRAYED options cannot be used together.

Here is a resource-definition file defining a menu bar with three pop-up items: File, Edit, and Font. The File and Edit pop-up items each activates a pop-up menu containing several command items. The Font pop-up menu has two other pop-up menus (Style and Size) within it.

MyMenuResource MENU

BEGIN

    POPUP "&File"

    BEGIN

        MENUITEM "&Open...",            IDM_FI_OPEN

        MENUITEM "&Close\tF3",          IDM_FI_CLOSE, GRAYED

        MENUITEM "&Quit",               IDM_FI_QUIT

        MENUITEM SEPARATOR

        MENUITEM "&About Sample...",    IDM_FI_ABOUT

    END

    POPUP "&Edit"

    BEGIN

        MENUITEM "&Undo",   IDM_ED_UNDO, GRAYED

        MENUITEM SEPARATOR

        MENUITEM "&Cut",    IDM_ED_CUT

        MENUITEM "C&opy",   IDM_ED_COPY

        MENUITEM "&Paste",  IDM_ED_PASTE

        MENUITEM "C&lear",  IDM_ED_ABOUT

    END

    POPUP "Fo&nt"

    BEGIN

        POPUP "&Style"

        BEGIN

            MENUITEM "&Regular\tF5",        IDM_FNT_STY_REGULAR

            MENUITEM SEPARATOR

            MENUITEM "&Bold\tCtrl+B",       IDM_FNT_STY_BOLD

            MENUITEM "&Italic\tCtrl+I",     IDM_FNT_STY_ITALIC

            MENUITEM "&Underline\tCtrl+U",  IDM_FNT_STY_ULINE

        END

        POPUP "Si&ze"

        BEGIN

            MENUITEM "10",  IDM_FNT_SZ_10

            MENUITEM "12",  IDM_FNT_SZ_12

            MENUITEM "14",  IDM_FNT_SZ_14

        END

    END

END

Loading a Menu-Template Resource

You can load a menu-template resource for your application by calling the LoadMenu function, specifying the handle of the module that contains the resource and the menu-template's identifier. LoadMenu returns a menu handle that you can use to assign the menu to a window. This window becomes the menu's owner window, receiving all the messages generated by the menu.

Use the SetMenu function to assign a menu to a window, or specify the menu's handle in the hmenu parameter of the CreateWindowEx function when you create a window. Another way that you can assign a menu to a window is to specify a menu template when you register a window class. This identifies the menu as the class menu for the given window class. Whenever you create a window of the given class, Windows automatically assigns the given menu to the window.

You can create a class menu by including the identifier of the menu-template resource as the lpszMenuName member of a WNDCLASS structure and then passing the address of the structure to the RegisterClass function.

Creating a Class Menu

The following example shows how to create a class menu for an application, how to create a window that uses the class menu, and how to process menu commands in the window procedure.

HINSTANCE hinst;

int APIENTRY WinMain(hinstance, hPrevInstance, lpCmdLine, nCmdShow)

HINSTANCE hinstance;

HINSTANCE hPrevInstance;

LPSTR lpCmdLine;

int nCmdShow;

{

    MSG msg;        /* message               */

    WNDCLASS wc;    /* window-class data     */

    HWND hwnd;      /* handle of main window */

    /*

     * Create the window class for the main window. Specify

     * the identifier of the menu-template resource as the

     * lpszMenuName member of the WNDCLASS structure to create

     * the class menu.

     */

    wc.style = 0;

    wc.lpfnWndProc = (WNDPROC) MainWndProc;

    wc.cbClsExtra = 0;

    wc.cbWndExtra = 0;

    wc.hInstance = hinstance;

    wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);

    wc.hCursor = LoadCursor(NULL, IDC_ARROW);

    wc.hbrBackground = GetStockObject(WHITE_BRUSH);

    wc.lpszMenuName =  "MyMenuResource";

    wc.lpszClassName = "MainWClass";

    if (!RegisterClass(&wc))

        return FALSE;

    hinst = hinstance;

    /*

     * Create the main window. Set the hmenu parameter to NULL so

     * that Windows uses the class menu for the window.

     */

    hwnd = CreateWindow("MainWClass", "Sample Application",

        WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT,

        CW_USEDEFAULT, CW_USEDEFAULT, NULL, NULL, hinstance,

        NULL);

    if (hwnd == NULL)

        return FALSE;

    /*

     * Make the window visible and send a WM_PAINT message to the

     * window procedure.

     */

    ShowWindow(hwnd, nCmdShow);

    UpdateWindow(hwnd);

    /* Start the main message loop. */

    while (GetMessage(&msg, NULL, 0, 0)) {

        TranslateMessage(&msg);

        DispatchMessage(&msg);

    }

    return msg.wParam;

        UNREFERENCED_PARAMETER(hPrevInstance);

}

LRESULT APIENTRY MainWndProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    switch (uMsg) {

        .

        . /* Process other window messages. */

        .

        case WM_COMMAND:

            /* Test for the identifier of a command item. */

            switch(LOWORD(wParam)) {

                case IDM_FI_OPEN:

                    DoFileOpen();   /* application-defined */

                    break;

                case IDM_FI_CLOSE:

                    DoFileClose();  /* application-defined */

                    break;

                .

                . /* Process other menu commands. */

                .

                default:

                    break;

            }

            return 0;

        .

        . /* Process other window messages. */

        .

        default:

            return DefWindowProc(hwnd, uMsg, wParam, lParam);

    }

    return NULL;

}


Creating a Floating Pop-up Menu

To use a floating pop-up menu in an application, pass the handle of a pop-up menu to the TrackPopupMenu function. An application typically calls TrackPopupMenu in a window procedure in response to a user-generated message, such as WM_LBUTTONDOWN or WM_KEYDOWN.

In addition to the pop-up menu handle, TrackPopupMenu requires that you specify the handle of the owner window, the position of the floating pop-up menu (in screen coordinates), and the mouse button the user can use to choose an item.

Specify the position by providing x- and y-coordinates along with the TPM_CENTERALIGN, TPM_LEFTALIGN, or TPM_RIGHTALIGN flag. The flag specifies the position of the menu relative to the x- and y-coordinates.

You should permit the user to choose an item from a pop-up menu by using the same mouse button used to display the menu. To do this, specify either TPM_LEFTBUTTON or TPM_RIGHTBUTTON flags to indicate which mouse button the user can use to select a menu item.

Creating a Floating Font-Attributes Menu

The example in this section contains portions of code from an application that creates and displays a floating pop-up menu that enables the user to set fonts and font attributes. The application displays the menu in the client area of its main window whenever the user clicks the left mouse button.

Here is the menu template for the pop-up menu that is provided in the application's resource-definition file.

PopupMenu MENU

BEGIN

  POPUP "Dummy Popup"

    BEGIN

      POPUP "Fonts"

        BEGIN

          MENUITEM "Courier",     IDM_FONT_COURIER

          MENUITEM "Times Roman", IDM_FONT_TMSRMN

          MENUITEM "Swiss",       IDM_FONT_SWISS

          MENUITEM "Helvetica",   IDM_FONT_HELV

          MENUITEM "Old English", IDM_FONT_OLDENG

        END

      POPUP "Sizes"

        BEGIN

          MENUITEM "7",  IDM_SIZE_7

          MENUITEM "8",  IDM_SIZE_8

          MENUITEM "9",  IDM_SIZE_9

          MENUITEM "10", IDM_SIZE_10

          MENUITEM "11", IDM_SIZE_11

          MENUITEM "12", IDM_SIZE_12

          MENUITEM "14", IDM_SIZE_14

        END

      POPUP "Styles"

        BEGIN

          MENUITEM "Bold",        IDM_STYLE_BOLD

          MENUITEM "Italic",      IDM_STYLE_ITALIC

          MENUITEM "Strike Out",  IDM_STYLE_SO

          MENUITEM "Superscript", IDM_STYLE_SUPER

          MENUITEM "Subscript",   IDM_STYLE_SUB

        END

    END

END

The following example gives the window procedure and supporting functions used to create and display the floating pop-up menu.

LRESULT APIENTRY MenuWndProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    RECT rc;    /* client area             */

    POINT pt;   /* location of mouse click */

    switch (uMsg) {

        case WM_LBUTTONDOWN:

            /* Get the bounding rectangle of the client area. */

            GetClientRect(hwnd, (LPRECT) &rc);

            /* Get the client coordinates for the mouse click. */

            pt.x = LOWORD(lParam);

            pt.y = HIWORD(lParam);

            /*

             * If the mouse click took place inside the client

             * area, execute the application-defined function

             * that displays the floating pop-up menu.

             */

            if (PtInRect((LPRECT) &rc, pt))

                HandlePopupMenu(hwnd, pt);

            break;

        .

        . /* Process other window messages. */

        .

        default:

            return DefWindowProc(hwnd, uMsg, wParam, lParam);

    }

    return NULL;

}

VOID APIENTRY HandlePopupMenu(hwnd, pt)

HWND hwnd;

POINT pt;

{

    HMENU hmenu;            /* menu template         */

    HMENU hmenuTrackPopup;  /* floating pop-up menu  */

    /*

     * Load the menu template containing the pop-up menu from the

     * application's resources.

     */

    hmenu = LoadMenu(hinst, "PopupMenu");

    if (hmenu == NULL)

        return;

    /*

     * Get the first pop-up menu in the menu template. This is the

     * menu that TrackPopupMenu displays.

     */

    hmenuTrackPopup = GetSubMenu(hmenu, 0);

    /*

     * TrackPopup uses screen coordinates, so convert the

     * coordinates of the mouse click to screen coordinates.

     */

    ClientToScreen(hwnd, (LPPOINT) &pt);

    /* Draw and track the floating pop-up menu. */

    TrackPopupMenu(hmenuTrackPopup, TPM_LEFTALIGN | TPM_LEFTBUTTON,

        pt.x, pt.y, 0, hwnd, NULL);

    /* Destroy the menu.*/

    DestroyMenu(hmenu);

}


Using Menu-Item Bitmaps

Windows can use a bitmap instead of a text string to display a menu item. To use a bitmap, you must set the MF_BITMAP flag for the menu item and specify the handle of the bitmap that Windows should display for the menu item. This section describes how to set the MF_BITMAP flag and retrieve the handle of a bitmap.

Setting the MF_BITMAP Flag

The MF_BITMAP flag tells Windows to use a bitmap rather than a text string to display a menu item. A menu item's MF_BITMAP flag must be set at run time; you cannot set it in the resource-definition file.

You can use the ModifyMenu, InsertMenu, or AppendMenu function to set the MF_BITMAP flag. To convert a menu item from a text string item to a bitmap item, use ModifyMenu. To add a new bitmap item to a menu, use the MF_BITMAP flag with the InsertMenu or AppendMenu function.

Creating the Bitmap

When you set the MF_BITMAP flag for a menu item, you must also specify the handle of the bitmap that Windows should display for the menu item. You can provide the bitmap as a bitmap resource or create the bitmap at run time.

To provide a bitmap resource, use a resource editor, such as ImageEdit, to create a bitmap resource, and then use a resource compiler to add the bitmap to your application's executable file. At run time, use the LoadBitmap function to load the bitmap and obtain its handle.

To create the bitmap at run time, use GDI functions. GDI provides several ways to create a bitmap at run time, but developers typically use the following method:

Use the CreateCompatibleDC function to create a device context compatible with the device context used by the application's main window.

Use the CreateCompatibleBitmap function to create a bitmap compatible with the application's main window.

Use the SelectObject function to select the bitmap into the compatible device context.

Use GDI drawing functions, such as Ellipse and LineTo, to draw an image into the bitmap.

Pass the handle of the bitmap to the ModifyMenu, InsertMenu, or AppendMenu function.

For more information about bitmaps, see Bitmaps.

Adding Lines and Graphs to a Menu

The following code sample shows how to create a menu that contains menu-item bitmaps. It creates two pop-up menus shown in the following illustration. The first is a Chart menu that contains three menu-item bitmaps: a pie chart, a line chart, and a bar chart. The example demonstrates how to load these bitmaps from the application's resource file, and then use the CreatePopupMenu and AppendMenu functions to create the menu and menu items.

The second pop-up menu is a Lines menu. It contains bitmaps showing the line styles provided by the predefined pen in Windows. The line-style bitmaps are created at run time by using GDI functions.

Here are the definitions of the bitmap resources in the application's resource-definition file.

PIE BITMAP pie.bmp

LINE BITMAP line.bmp

BAR BITMAP bar.bmp

Here are the relevant portions of the application's header file.

/* Menu-item identifiers */

#define IDM_SOLID       PS_SOLID

#define IDM_DASH        PS_DASH

#define IDM_DASHDOT     PS_DASHDOT

#define IDM_DASHDOTDOT  PS_DASHDOTDOT

#define IDM_PIE  1

#define IDM_LINE 2

#define IDM_BAR  3

/* Line-type flags */

#define SOLID       0

#define DOT         1

#define DASH        2

#define DASHDOT     3

#define DASHDOTDOT  4

/* Count of pens */

#define CPENS 5

/* Chart-type flags */

#define PIE  1

#define LINE 2

#define BAR  3

/* Function prototypes */

LRESULT APIENTRY MainWndProc(HWND, UINT, WPARAM, LPARAM);

VOID MakeChartMenu(HWND);

VOID MakeLineMenu(HWND, HPEN, HBITMAP);

The following example shows how menus and menu-item bitmaps are created in an application.

LRESULT APIENTRY MainWndProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    static HPEN hpen[CPENS];

    static HBITMAP hbmp[CPENS];

    int i;

    switch (uMsg) {

        case WM_CREATE:

            /* Create the Chart and Line menus. */

            MakeChartMenu(hwnd);

            MakeLineMenu(hwnd, hpen, hbmp);

            return 0;

        .

        . /* Process other window messages. */

        .

        case WM_DESTROY:

            for (i = 0; i < CPENS; i++) {

                DeleteObject(hbmp[i]);

                DeleteObject(hpen[i]);

            }

            PostQuitMessage(0);

            break;

        default:

            return DefWindowProc(hwnd, uMsg, wParam, lParam);

    }

    return NULL;

}

VOID MakeChartMenu(hwnd)

HWND hwnd;              /* handle of owner window      */

{

    HBITMAP hbmpPie;    /* handle of pie chart bitmap  */

    HBITMAP hbmpLine;   /* handle of line chart bitmap */

    HBITMAP hbmpBar;    /* handle of bar chart bitmap  */

    HMENU hmenuMain;    /* handle of main menu         */

    HMENU hmenuChart;   /* handle of chart pop-up menu */

    /*

     * Load the pie, line, and bar chart bitmaps from the

     * resource-definition file.

     */

    hbmpPie = LoadBitmap(hinst, MAKEINTRESOURCE(PIE));

    hbmpLine = LoadBitmap(hinst, MAKEINTRESOURCE(LINE));

    hbmpBar = LoadBitmap(hinst, MAKEINTRESOURCE(BAR));

    /*

     * Create the Chart pop-up menu and add it to the menu bar.

     * Append the Pie, Line, and Bar menu items to the Chart

     * pop-up menu.

     */

    hmenuMain = GetMenu(hwnd);

    hmenuChart = CreatePopupMenu();

    AppendMenu(hmenuMain, MF_STRING | MF_POPUP, (UINT) hmenuChart,

        "Chart");

    AppendMenu(hmenuChart, MF_BITMAP, IDM_PIE, (LPCTSTR) hbmpPie);

    AppendMenu(hmenuChart, MF_BITMAP, IDM_LINE,

        (LPCTSTR) hbmpLine);

    AppendMenu(hmenuChart, MF_BITMAP, IDM_BAR, (LPCTSTR) hbmpBar);

    return;

}

VOID MakeLineMenu(hwnd, phpen, phbmp)

HWND hwnd;

HPEN *phpen;

HBITMAP *phbmp;

{

    HMENU hmenuLines;       /* handle of Lines pop-up menu     */

    HMENU hmenu;            /* handle of main menu             */

    COLORREF crMenuClr;     /* menu-item background color      */

    HBRUSH hbrBackground;   /* handle of background brush      */

    HBRUSH hbrOld;          /* handle of previous brush        */

    LONG lCheckXY;          /* dimensions of check mark bitmap */

    WORD wLineX;            /* width of line bitmaps           */

    WORD wLineY;            /* height of line bitmaps          */

    HDC hdcMain;            /* handle of main window's DC      */

    HDC hdcLines;           /* handle of compatible DC         */

    HBITMAP hbmpOld;        /* handle of previous bitmap       */

    int i;                  /* loop counter                    */

    /* Create the Lines pop-up menu. Add it to the menu bar. */

    hmenu = GetMenu(hwnd);

    hmenuLines = CreatePopupMenu();

    AppendMenu(hmenu, MF_STRING | MF_POPUP,

        (UINT) hmenuLines, "&Lines");

    /* Create a brush for the menu-item background color. */

    crMenuClr = GetSysColor(COLOR_MENU);

    hbrBackground = CreateSolidBrush(crMenuClr);

    /*

     * Create a compatible device context for the line bitmaps,

     * and then select the background brush into it.

     */

    hdcMain = GetDC(hwnd);

    hdcLines = CreateCompatibleDC(hdcMain);

    hbrOld = SelectObject(hdcLines, hbrBackground);

    /*

     * Get the dimensions of the check mark bitmap. The width of

     * the line bitmaps will be five times the width of the

     * check mark bitmap.

     */

    lCheckXY = GetMenuCheckMarkDimensions();

    wLineX = LOWORD(lCheckXY) * (WORD) 5;

    wLineY = HIWORD(lCheckXY);

    /*

     * Create the bitmaps and select them, one at a time, into the

     * compatible device context. Initialize each bitmap by

     * filling it with the menu-item background color.

     */

    for (i = 0; i < CPENS; i++) {

        phbmp[i] = CreateCompatibleBitmap(hdcMain, wLineX, wLineY);

        if (i == 0)

            hbmpOld = SelectObject(hdcLines, phbmp[i]);

        else

            SelectObject(hdcLines, phbmp[i]);

        ExtFloodFill(hdcLines, 0, 0, crMenuClr, FLOODFILLBORDER);

    }

    /* Create the pens. */

    phpen[0] = CreatePen(PS_SOLID, 1, RGB(0, 0, 0));

    phpen[1] = CreatePen(PS_DOT, 1, RGB(0, 0, 0));

    phpen[2] = CreatePen(PS_DASH, 1, RGB(0, 0, 0));

    phpen[3] = CreatePen(PS_DASHDOT, 1, RGB(0, 0, 0));

    phpen[4] = CreatePen(PS_DASHDOTDOT, 1, RGB(0, 0, 0));

    /*

     * Select a pen and a bitmap into the compatible device

     * context, draw a line into the bitmap, and then append

     * the bitmap as an item in the Lines menu.

     */

    for (i = 0; i < CPENS; i++) {

        SelectObject(hdcLines, phbmp[i]);

        SelectObject(hdcLines, phpen[i]);

        MoveToEx(hdcLines, 0, wLineY / 2, NULL);

        LineTo(hdcLines, wLineX, wLineY / 2);

        AppendMenu(hmenuLines, MF_BITMAP, i + 1,

            (LPCTSTR) phbmp[i]);

    }

    /*

     * Release the main window's device context and destroy the

     * compatible device context. Also, destroy the background

     * brush.

     */

    ReleaseDC(hwnd, hdcMain);

    SelectObject(hdcLines, hbrOld);

    DeleteObject(hbrBackground);

    SelectObject(hdcLines, hbmpOld);

    DeleteDC(hdcLines);

    return;

}


Creating Owner-drawn Menu Items

If you need complete control over the appearance of a menu item, you can use an owner-drawn menu item on your application. This section describes the steps involved in creating and using an owner-drawn menu item.

Setting the MF_OWNERDRAW Flag

You cannot define an owner-drawn menu item on your application's resource-definition file. Instead, you must create a new menu item or modify an existing one by using the MF_OWNERDRAW menu flag.

You can use the AppendMenu, InsertMenu, or ModifyMenu function to specify an owner-drawn menu item. Use AppendMenu to add a new item to the end of the given menu. Use InsertMenu to place a new item onto a menu, moving the other items down. Use ModifyMenu to change the contents of a menu.

When you call any of these three functions, you can pass a 32-bit value as the lpNewItem parameter. This value can represent any information that is meaningful to your application, and that will be available to your application when the item is to be displayed. For example, the value could contain a pointer to a structure; the structure, in turn, might contain a text string and the handle of a logical font that your application will use to draw the string.

Responding to the WM_MEASUREITEM Message

Before Windows displays an owner-drawn menu item for the first time, it sends the WM_MEASUREITEM message to the window procedure of the window that owns the item's menu. This message contains a pointer to a MEASUREITEMSTRUCT structure that identifies the item and contains an optional 32-bit value for the item. When the window procedure receives the WM_MEASUREITEM message, it must fill the itemWidth and itemHeight members of the structure before returning from processing the message. Windows uses the information in these members when creating the bounding rectangle in which your application draws the menu item. It also uses the information to detect when the user chooses the item.

Responding to the WM_DRAWITEM Message

Whenever the item must be drawn (for example, when it is first displayed or when the user chooses it as a command), Windows sends the WM_DRAWITEM message to the window procedure of the menu's owner window. This message contains a pointer to a DRAWITEMSTRUCT structure. Like the MEASUREITEMSTRUCT structure, DRAWITEMSTRUCT contains information about the item and its optional 32-bit data. In addition, DRAWITEMSTRUCT contains flags that indicate the state of the item (such as whether it is grayed or checked) as well as a bounding rectangle and a device context that the application uses to draw the item.

In response to the WM_DRAWITEM message, your application must perform the following actions before returning from processing the message:

1	Determine the type of drawing that is necessary. To do so, check the itemAction member of the DRAWITEMSTRUCT structure.

2	Draw the menu item appropriately, using the bounding rectangle and device context obtained from the DRAWITEMSTRUCT structure. Your application must draw only within the bounding rectangle. For performance reasons, Windows doesn't clip portions of the image that are drawn outside the rectangle.

3	Restore all GDI objects selected for the menu item's device context.

If the menu item is selected, Windows sets the itemAction member of the DRAWITEMSTRUCT structure to ODA_SELECT and sets the ODS_SELECTED flag in the itemState member. This is an application's cue to redraw the menu item to indicate that it is selected.

Setting Fonts for Menu-Item Text Strings

This section contains an example from an application that uses owner-drawn menu items in a pop-up menu. The pop-up menu contains items that set the attributes of the current font, and the items are displayed using the appropriate font attribute, as shown in the following illustration.

Here is how the menu is defined in the resource-definition file. Note that the strings for the Regular, Bold, Italic, and Underline items are assigned at run time, so their strings are empty in the resource-definition file.

MainMenu MENU

BEGIN

    POPUP   "&Character"

    BEGIN

        MENUITEM    "",    IDM_REGULAR

        MENUITEM SEPARATOR

        MENUITEM    "",    IDM_BOLD

        MENUITEM    "",    IDM_ITALIC

        MENUITEM    "",    IDM_ULINE

    END

END

The application's window procedure processes the messages involved in using owner-drawn menu items. The application uses the WM_CREATE message to do the following:

Set the MF_OWNERDRAW flag for the menu items.

Set the text strings for the menu items.

Obtain handles of the fonts used to draw the items.

Obtain the text and background color values for selected menu items.

The text strings and font handles are stored in an array of application-defined MYITEM structures. The application-defined GetAFont function creates a font that corresponds to the given font attribute and returns the handle of the font. The handles are destroyed during the processing of the WM_DESTROY message.

During the processing of the WM_MEASUREITEM message, the example gets the width and height of a menu-item string and copies these values into the MEASUREITEMSTRUCT structure. Windows uses the width and height values to calculate the size of the pop-up menu.

During the processing of the WM_DRAWITEM message, the menu item's string is drawn with room left next to the string for the check mark bitmap. If the user selects the item, the selected text and background colors are used to draw the item.

LRESULT APIENTRY MainWndProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    typedef struct _MYITEM {

        HFONT hfont;

        LPSTR psz;

    } MYITEM;             /* structure for item font and string */

    MYITEM *pmyitem;      /* pointer to item's font and string       */

    static MYITEM myitem[CITEMS];   /* array of MYITEMS              */

    static HMENU hmenu;             /* handle of main menu           */

    static COLORREF crSelText;  /* text color of selected item       */

    static COLORREF crSelBkgnd; /* background color of selected item */

    COLORREF crText;            /* text color of unselected item     */

    COLORREF crBkgnd;           /* background color unselected item  */

    LPMEASUREITEMSTRUCT lpmis;  /* points to item of data            */

    LPDRAWITEMSTRUCT lpdis;     /* points to item drawing data       */

    HDC hdc;                    /* handle of screen DC               */

    SIZE size;                  /* menu-item text extents            */

    DWORD dwCheckXY;            /* check mark dimensions             */

    WORD wCheckX;               /* check mark width                  */

    int nTextX;                 /* width of menu item                */

    int nTextY;                 /* height of menu item               */

    int i;                      /* loop counter                      */

    HFONT hfontOld;             /* handle of old font                */

    BOOL fSelected = FALSE;     /* menu-item selection flag          */

    switch (uMsg) {

        case WM_CREATE:

            /*

             * Modify the Regular, Bold, Italic, and Underline

             * menu items to make them owner-drawn items. Associate

             * a MYITEM structure with each item to contain the

             * string and font handle for each item.

             */

            hmenu = GetMenu(hwnd);

            ModifyMenu(hmenu, IDM_REGULAR, MF_BYCOMMAND |

                MF_CHECKED | MF_OWNERDRAW, IDM_REGULAR,

                (LPTSTR) &myitem[REGULAR]);

            ModifyMenu(hmenu, IDM_BOLD, MF_BYCOMMAND |

                MF_OWNERDRAW, IDM_BOLD, (LPTSTR) &myitem[BOLD]);

            ModifyMenu(hmenu, IDM_ITALIC, MF_BYCOMMAND |

                MF_OWNERDRAW, IDM_ITALIC,

                (LPTSTR) &myitem[ITALIC]);

            ModifyMenu(hmenu, IDM_ULINE, MF_BYCOMMAND |

                MF_OWNERDRAW, IDM_ULINE, (LPTSTR) &myitem[ULINE]);

            /*

             * Retrieve each item's font handle and copy it into

             * the hfont member of each item's MYITEM structure.

             * Also, copy each item's string into the structures.

             */

            myitem[REGULAR].hfont = GetAFont(REGULAR);

            myitem[REGULAR].psz = "Regular";

            myitem[BOLD].hfont = GetAFont(BOLD);

            myitem[BOLD].psz = "Bold";

            myitem[ITALIC].hfont = GetAFont(ITALIC);

            myitem[ITALIC].psz = "Italic";

            myitem[ULINE].hfont = GetAFont(ULINE);

            myitem[ULINE].psz = "Underline";

            /*

             * Retrieve the text and background colors of the

             * selected menu text.

             */

            crSelText = GetSysColor(COLOR_HIGHLIGHTTEXT);

            crSelBkgnd = GetSysColor(COLOR_HIGHLIGHT);

            return 0;

        case WM_MEASUREITEM:

            /* Retrieve a device context for the main window. */

            hdc = GetDC(hwnd);

            /*

             * Retrieve pointers to the menu item's

             * MEASUREITEMSTRUCT structure and MYITEM structure.

             */

            lpmis = (LPMEASUREITEMSTRUCT) lParam;

            pmyitem = (MYITEM *) lpmis->itemData;

            /*

             * Select the font associated with the item into

             * the main window's device context.

             */

            hfontOld = SelectObject(hdc, pmyitem->hfont);

            /*

             * Retrieve the width and height of the item's string,

             * and then copy the width and height into the

             * MEASUREITEMSTRUCT structure's itemWidth and

             * itemHeight members.

             */

            GetTextExtentPoint(hdc, pmyitem->psz,

                lstrlen(pmyitem->psz), &size);

            lpmis->itemWidth = size.cx;

            lpmis->itemHeight = size.cy;

            /*

             * Select the old font back into the device context,

             * and then release the device context.

             */

            SelectObject(hdc, hfontOld);

            ReleaseDC(hwnd, hdc);

            return TRUE;

            break;

        case WM_DRAWITEM:

            /*

             * Get pointers to the menu item's DRAWITEMSTRUCT

             * structure and MYITEM structure.

             */

            lpdis = (LPDRAWITEMSTRUCT) lParam;

            pmyitem = (MYITEM *) lpdis->itemData;

            /*

             * If the user has selected the item, use the selected

             * text and background colors to display the item.

             */

            if (lpdis->itemState & ODS_SELECTED) {

                crText = SetTextColor(lpdis->hDC, crSelText);

                crBkgnd = SetBkColor(lpdis->hDC, crSelBkgnd);

                fSelected = TRUE;

            }

            /*

             * Remember to leave space in the menu item for the

             * check mark bitmap. Retrieve the width of the bitmap

             * and add it to the width of the menu item.

             */

            dwCheckXY = GetMenuCheckMarkDimensions();

            wCheckX = LOWORD(dwCheckXY);

            nTextX = wCheckX + lpdis->rcItem.left;

            nTextY = lpdis->rcItem.top;

            /*

             * Select the font associated with the item into the

             * item's device context, and then draw the string.

             */

            hfontOld = SelectObject(lpdis->hDC, pmyitem->hfont);

            ExtTextOut(lpdis->hDC, nTextX, nTextY, ETO_OPAQUE,

                &lpdis->rcItem, pmyitem->psz,

                lstrlen(pmyitem->psz), NULL);

            /*

             * Select the previous font back into the device

             * context.

             */

            SelectObject(lpdis->hDC, hfontOld);

            /*

             * Return the text and background colors to their

             * normal state (not selected).

             */

            if (fSelected) {

                SetTextColor(lpdis->hDC, crText);

                SetBkColor(lpdis->hDC, crBkgnd);

            }

            return TRUE;

        .

        . /* Process other messages. */

        .

        case WM_DESTROY:

            /* Destroy the menu items' font handles. */

            for (i = 0; i < CITEMS; i++)

                DeleteObject(myitem[i].hfont);

            PostQuitMessage(0);

            break;

        default:

            return DefWindowProc(hwnd, uMsg, wParam, lParam);

    }

    return NULL;

}

HFONT GetAFont(fnFont)

int fnFont;             /* font-attribute flag            */

{

    static LOGFONT lf;  /* structure for font information */

    /*

     * Get a handle to the ANSI fixed-pitch font, and copy

     * information about the font to a LOGFONT structure.

     */

    GetObject(GetStockObject(ANSI_FIXED_FONT), sizeof(LOGFONT),

        &lf);

    /* Set the font attributes, as appropriate. */

    if (fnFont == BOLD)

        lf.lfWeight = FW_BOLD;

    else

        lf.lfWeight = FW_NORMAL;

    lf.lfItalic = (fnFont == ITALIC);

    lf.lfItalic = (fnFont == ULINE);

    /* Create the font, and then return its handle. */

    return CreateFont(lf.lfHeight, lf.lfWidth,

        lf.lfEscapement, lf.lfOrientation, lf.lfWeight,

        lf.lfItalic, lf.lfUnderline, lf.lfStrikeOut, lf.lfCharSet,

        lf.lfOutPrecision, lf.lfClipPrecision, lf.lfQuality,

        lf.lfPitchAndFamily, lf.lfFaceName);

}


Using Custom Check Mark Bitmaps

A Windows video device driver provides a default check mark bitmap that Windows displays next to a menu item that is checked. You can customize an individual menu item by providing a pair of bitmaps to replace the default check mark bitmap. Windows displays one bitmap when the item is checked and the other when it is unchecked. This section describes the steps involved in creating and using custom check mark bitmaps.

Creating Custom Check Mark Bitmaps

A custom check mark bitmap must be the same size as the default check mark bitmap. You can retrieve the default check mark bitmap's size by calling the GetMenuCheckMarkDimensions function. The low-order word of this function's return value specifies the width; the high-order word specifies the height.

Bitmap resources can be used to provide check mark bitmaps. However, a bitmap resource is not suitable for all screen resolutions and aspect ratios, so you'll need to use the StretchBlt function to size the bitmap, as appropriate. Depending on the bitmap being sized, the result of the sizing may not be acceptable, because stretching may distort the bitmap.

Instead of using a bitmap resource, GDI functions can be used to provide check mark bitmaps at run time. This involves the following steps, which an application typically performs during the WM_CREATE message:

1	Create a device context in memory that is compatible with the screen.

2	Create a bitmap that is compatible with the display.

3	Select the bitmap into the device context.

4	Draw or copy an image into the bitmap.

Call the CreateCompatibleDC function to create a device context that is compatible with the screen. The function's hdc parameter can specify either NULL or the return value from the GetDC function. CreateCompatibleDC returns the handle of the compatible device context.

Call the CreateCompatibleBitmap function to create an "empty" bitmap that is compatible with the screen. This function's nWidth and nHeight parameters set the size of the bitmap; they should specify the width and height information returned by the GetMenuCheckMarkDimensions function.

The CreateCompatibleBitmap function returns the handle of the bitmap. Pass this handle of the SelectObject function to select the bitmap into the compatible device context. Afterward, you can use the GDI drawing functions such as Rectangle and Ellipse to draw into the bitmap, or you can use functions such as BitBlt and StretchBlt to copy an image into the bitmap.

GDI provides several other ways to create bitmaps. For more information about bitmaps, see Bitmaps.

Associating Bitmaps with a Menu Item

You associate a pair of check mark bitmaps with a menu item by passing the handles of the bitmaps to the SetMenuItemBitmaps function. The hbmUnchecked parameter identifies the unchecked bitmap; the hbmChecked parameter identifies the checked bitmap. If you want to remove one or both check marks from a menu item, you can set the hbmUnchecked or hbmChecked parameter, or both, to NULL.

Setting the Check Mark Attribute

The CheckMenuItem function sets a menu item's check mark attribute to either checked or unchecked. Specify the MF_CHECKED flag to set the check mark attribute to checked, or specify MF_UNCHECKED to set it to unchecked.

Simulating Check Boxes in a Menu

This section contains an example that shows how to simulate check boxes in a pop-up menu. The example contains a Character menu whose items allow the user to set the bold, italic, and underline attributes of the current font. When a font attribute is in effect, a check mark is displayed in the check box next to the corresponding menu item; otherwise, it is displayed in an empty check box next to the item. The following illustration shows both kinds of check boxes.

The example in this section replaces the default check mark bitmap with two bitmaps: a bitmap with a checked box and the bitmap with an empty box. The checked check box bitmap is displayed next to the Bold, Italic, or Underline menu item when the item's check mark attribute is set to MF_CHECKED. The unchecked or empty check box bitmap is displayed when the check mark attribute is set to MF_UNCHECKED.

Windows provides a predefined bitmap that contains the images used for check boxes and radio buttons (as shown in the following illustration). The example in this section isolates the checked and empty check boxes, copies them to two separate bitmaps, and then uses them as the checked and unchecked bitmaps for items in the Character menu.

To retrieve the handle of the system-defined check box bitmap, the example in this section calls the LoadBitmap function, specifying NULL as the hinst parameter and OBM_CHECKBOXES as the lpBitmapName parameter. Because the images in the bitmap are all the same size, the example can isolate them by dividing the bitmap's width and height by the number of images in its rows and columns.

The following portion of a resource-definition file shows how the menu items in the Character menu are defined. Note that no font attributes are in effect initially, so the check mark attribute for the Regular item is set to checked and, by default, the check mark attribute of the remaining items is set to unchecked.

#include "men3.h"

MainMenu MENU

BEGIN

    POPUP   "&Character"

    BEGIN

        MENUITEM    "&Regular",     IDM_REGULAR, CHECKED

        MENUITEM SEPARATOR

        MENUITEM    "&Bold",        IDM_BOLD

        MENUITEM    "&Italic",      IDM_ITALIC

        MENUITEM    "&Underline",   IDM_ULINE

    END

END

Here is the relevant contents of the application's header file.

/* Menu-item identifiers */

#define IDM_REGULAR 0x1

#define IDM_BOLD    0x2

#define IDM_ITALIC  0x4

#define IDM_ULINE   0x8

/* Check mark flags */

#define CHECK   1

#define UNCHECK 2

/* Font-attribute mask */

#define ATTRIBMASK 0xe

/* Function prototypes */

LRESULT APIENTRY MainWndProc(HWND, UINT, WPARAM, LPARAM);

HBITMAP GetMyCheckBitmaps(UINT);

BYTE CheckOrUncheckMenuItem(BYTE, HMENU);

The following example shows the portions of the window procedure that create the check mark bitmaps, set the check mark attribute of the Bold, Italic, and Underline menu items, and destroy check mark bitmaps.

LRESULT APIENTRY MainWndProc(hwndMain, uMsg, wParam, lParam)

HWND hwndMain;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    static HBITMAP hbmpCheck;   /* handle of checked bitmap   */

    static HBITMAP hbmpUncheck; /* handle of unchecked bitmap */

    static HMENU hmenu;         /* handle of main menu        */

    BYTE fbFontAttrib;          /* font-attribute flags       */

    switch (uMsg) {

        case WM_CREATE:

            /*

             * Call the application-defined GetMyCheckBitmaps

             * function to get the predefined checked and

             * unchecked check box bitmaps.

             */

            hbmpCheck = GetMyCheckBitmaps(CHECK);

            hbmpUncheck = GetMyCheckBitmaps(UNCHECK);

            /*

             * Set the checked and unchecked bitmaps for the menu

             * items.

             */

            hmenu = GetMenu(hwndMain);

            SetMenuItemBitmaps(hmenu, IDM_BOLD, MF_BYCOMMAND,

                hbmpUncheck, hbmpCheck);

            SetMenuItemBitmaps(hmenu, IDM_ITALIC, MF_BYCOMMAND,

                hbmpUncheck, hbmpCheck);

            SetMenuItemBitmaps(hmenu, IDM_ULINE, MF_BYCOMMAND,

                hbmpUncheck, hbmpCheck);

            return 0;

        case WM_COMMAND:

            switch (LOWORD(wParam)) {

                /* Process the menu commands. */

                case IDM_REGULAR:

                case IDM_BOLD:

                case IDM_ITALIC:

                case IDM_ULINE:

                    /*

                     * CheckOrUncheckMenuItem is an application-

                     * defined function that sets the menu item

                     * check marks and returns the user-selected

                     * font attributes.

                     */

                    fbFontAttrib = CheckOrUncheckMenuItem(

                        (BYTE) LOWORD(wParam), hmenu);

                    .

                    . /* Set the font attributes. */

                    .

                    return 0;

                .

                . /* Process other command messages. */

                .

                default:

                    break;

            }

            break;

        .

        . /* Process other window messages. */

        .

        case WM_DESTROY:

            /* Destroy the checked and unchecked bitmaps. */

            DeleteObject(hbmpCheck);

            DeleteObject(hbmpUncheck);

            PostQuitMessage(0);

            break;

        default:

            return DefWindowProc(hwndMain, uMsg, wParam, lParam);

    }

    return NULL;

}

HBITMAP GetMyCheckBitmaps(fuCheck)

UINT fuCheck;               /* CHECK or UNCHECK flag            */

{

    COLORREF crBackground;  /* background color                 */

    HBRUSH hbrBackground;   /* background brush                 */

    HBRUSH hbrTargetOld;    /* original background brush        */

    HDC hdcSource;          /* source device context            */

    HDC hdcTarget;          /* target device context            */

    HBITMAP hbmpCheckboxes; /* handle of check box bitmap       */

    BITMAP bmCheckbox;      /* structure for bitmap data        */

    HBITMAP hbmpSourceOld;  /* handle of original source bitmap */

    HBITMAP hbmpTargetOld;  /* handle of original target bitmap */

    HBITMAP hbmpCheck;      /* handle of check mark bitmap      */

    RECT rc;                /* rectangle for check box bitmap   */

    DWORD dwCheckXY;        /* dimensions of check mark bitmap  */

    WORD wBitmapX;          /* width of check mark bitmap       */

    WORD wBitmapY;          /* height of check mark bitmap      */

    /*

     * Get the menu background color and create a solid brush

     * with that color.

     */

    crBackground = GetSysColor(COLOR_MENU);

    hbrBackground = CreateSolidBrush(crBackground);

    /*

     * Create memory device contexts for the source and

     * destination bitmaps.

     */

    hdcSource = CreateCompatibleDC((HDC) NULL);

    hdcTarget = CreateCompatibleDC(hdcSource);

    /*

     * Get the size of the Windows default check mark bitmap and

     * create a compatible bitmap of the same size.

     */

    dwCheckXY = GetMenuCheckMarkDimensions();

    wBitmapX = LOWORD(dwCheckXY);

    wBitmapY = LOWORD(dwCheckXY);

    hbmpCheck = CreateCompatibleBitmap(hdcSource, wBitmapX,

        wBitmapY);

    /*

     * Select the background brush and bitmap into the target DC.

     */

    hbrTargetOld = SelectObject(hdcTarget, hbrBackground);

    hbmpTargetOld = SelectObject(hdcTarget, hbmpCheck);

    /*

     * Use the selected brush to initialize the background color

     * of the bitmap in the target device context.

     */

    PatBlt(hdcTarget, 0, 0, wBitmapX, wBitmapY, PATCOPY);

    /*

     * Load the predefined check box bitmaps and select it

     * into the source DC.

     */

    hbmpCheckboxes = LoadBitmap((HINSTANCE) NULL,

        (LPTSTR) OBM_CHECKBOXES);

    hbmpSourceOld = SelectObject(hdcSource, hbmpCheckboxes);

    /*

     * Fill a BITMAP structure with information about the

     * check box bitmaps, and then find the upper-left corner of

     * the unchecked check box or the checked check box.

     */

    GetObject(hbmpCheckboxes, sizeof(BITMAP), &bmCheckbox);

    if (fuCheck == UNCHECK) {

        rc.left = 0;

        rc.right = (bmCheckbox.bmWidth / 4);

    }

    else {

        rc.left = (bmCheckbox.bmWidth / 4);

        rc.right = (bmCheckbox.bmWidth / 4) * 2;

    }

    rc.top = 0;

    rc.bottom = (bmCheckbox.bmHeight / 3);

    /*

     * Copy the appropriate bitmap into the target DC. If the

     * check box bitmap is larger than the default check mark

     * bitmap, use StretchBlt to make it fit; otherwise, just

     * copy it.

     */

    if (((rc.right - rc.left) > (int) wBitmapX) ||

            ((rc.bottom - rc.top) > (int) wBitmapY))

        StretchBlt(hdcTarget, 0, 0, wBitmapX, wBitmapY,

            hdcSource, rc.left, rc.top, rc.right - rc.left,

            rc.bottom - rc.top, SRCCOPY);

    else

        BitBlt(hdcTarget, 0, 0, rc.right - rc.left,

            rc.bottom - rc.top,

            hdcSource, rc.left, rc.top, SRCCOPY);

    /*

     * Select the old source and destination bitmaps into the

     * source and destination DCs, and then delete the DCs and

     * the background brush.

     */

    SelectObject(hdcSource, hbmpSourceOld);

    SelectObject(hdcTarget, hbrTargetOld);

    hbmpCheck = SelectObject(hdcTarget, hbmpTargetOld);

    DeleteObject(hbrBackground);

    DeleteObject(hdcSource);

    DeleteObject(hdcTarget);

    /* Return the handle of the new check mark bitmap. */

    return hbmpCheck;

}

BYTE CheckOrUncheckMenuItem(bMenuItemID, hmenu)

BYTE bMenuItemID;

HMENU hmenu;

{

    DWORD fdwMenu;

    static BYTE fbAttributes;

    switch (bMenuItemID) {

        case IDM_REGULAR:

            /*

             * Whenever the Regular menu item is selected, add a

             * check mark to it and then remove check marks from

             * any font-attribute menu items.

             */

            CheckMenuItem(hmenu, IDM_REGULAR, MF_BYCOMMAND |

                MF_CHECKED);

            if (fbAttributes & ATTRIBMASK) {

                CheckMenuItem(hmenu, IDM_BOLD, MF_BYCOMMAND |

                    MF_UNCHECKED);

                CheckMenuItem(hmenu, IDM_ITALIC, MF_BYCOMMAND |

                    MF_UNCHECKED);

                CheckMenuItem(hmenu, IDM_ULINE, MF_BYCOMMAND |

                    MF_UNCHECKED);

            }

            fbAttributes = IDM_REGULAR;

            return fbAttributes;

        case IDM_BOLD:

        case IDM_ITALIC:

        case IDM_ULINE:

            /*

             * Toggle the check mark for the selected menu item and

             * set the font attribute flags appropriately.

             */

            fdwMenu = GetMenuState(hmenu, (UINT) bMenuItemID,

                MF_BYCOMMAND);

            if (!(fdwMenu & MF_CHECKED)) {

                CheckMenuItem(hmenu, (UINT) bMenuItemID,

                    MF_BYCOMMAND | MF_CHECKED);

                fbAttributes |= bMenuItemID;

            } else {

                CheckMenuItem(hmenu, (UINT) bMenuItemID,

                    MF_BYCOMMAND | MF_UNCHECKED);

                fbAttributes ^= bMenuItemID;

            }

            /*

             * If any font attributes are currently selected,

             * remove the check mark from the Regular menu item;

             * if no attributes are selected, add a check mark

             * to the Regular menu item.

             */

            if (fbAttributes & ATTRIBMASK) {

                CheckMenuItem(hmenu, IDM_REGULAR,

                    MF_BYCOMMAND | MF_UNCHECKED);

                fbAttributes &= (BYTE) ~IDM_REGULAR;

            } else {

                CheckMenuItem(hmenu, IDM_REGULAR,

                    MF_BYCOMMAND | MF_CHECKED);

                fbAttributes = IDM_REGULAR;

            }

            return fbAttributes;

    }

}


Functions

Functions

AppendMenu

ChangeMenu

CheckMenuItem

CreateMenu

CreatePopupMenu

DeleteMenu

DestroyMenu

DrawMenuBar

EnableMenuItem

GetMenu

GetMenuCheckMarkDimensions

GetMenuItemCount

GetMenuItemID

GetMenuState

GetMenuString

GetSubMenu

GetSystemMenu

HiliteMenuItem

InsertMenu

LoadMenu

LoadMenuIndirect

ModifyMenu

RemoveMenu

SetMenu

SetMenuItemBitmaps

TrackPopupMenu

Messages

WM_COMMAND

WM_DRAWITEM

WM_ENTERIDLE

WM_ENTERMENULOOP

WM_EXITMENULOOP

WM_INITMENU

WM_INITMENUPOPUP

WM_MEASUREITEM

WM_MENUCHAR

WM_MENUSELECT

WM_NCHITTEST

WM_SYSCOMMAND


Keyboard Accelerators Overview

About Keyboard Accelerators

In Microsoft® Windows™, a keyboard accelerator (or, simply, accelerator) is a keystroke or combination of keystrokes that generates a WM_COMMAND or WM_SYSCOMMAND message for an application. Accelerators are closely related to menus--both provide the user with access to an application's command set. Typically, users rely on an application's menus to learn the command set and then switch over to using accelerators as they become more proficient with the application. Accelerators provide faster, more direct access to commands than menus do. At a minimum, an application should provide accelerators for the more commonly used commands. Although accelerators typically generate commands that exist as menu items, they can also generate commands that have no equivalent menu items.

The following topics discuss Win32 keyboard accelerators:

Terms

Accelerator Tables

Accelerator-Table Creation

Accelerator Keystroke Assignments

Accelerators and Menus

Example: Accelerators for Font Attributes

Using an Accelerator Table Created at Run Time

Example: User-Editable Accelerators

Functions and Messages


Accelerator Tables

An accelerator table consists of an array of ACCEL structures, each defining an individual accelerator. Each ACCEL structure includes the following information:

The accelerator's keystroke combination

The accelerator's identifier

Various flags. This includes one that specifies whether Windows is to provide visual feedback by highlighting the corresponding menu item, if any, when the accelerator is used

To process accelerator keystrokes for a given thread, the developer must call the TranslateAccelerator function in the message loop associated with the thread's message queue. The TranslateAccelerator function monitors keyboard input to the message queue, checking for key combinations that match an entry in the accelerator table. When TranslateAccelerator finds a match, it translates the keyboard input (that is, the WM_KEYUP and WM_KEYDOWN messages) into a WM_COMMAND or WM_SYSCOMMAND message and then sends the message to the window procedure of the specified window. The following illustration shows how accelerators are processed.

The WM_COMMAND message includes the identifier of the accelerator that caused TranslateAccelerator to generate the message. The window procedure examines the identifier to determine the source of the message and then processes the message accordingly.

Accelerator tables exist at two different levels in Windows. Windows maintains a single, system-wide accelerator table that applies to all applications. An application cannot modify the system accelerator table. For a description of the accelerators provided by the system accelerator table, see Accelerator Keystroke Assignments.

Windows also maintains accelerator tables for each application. An application can define any number of accelerator tables for use with its own windows. A unique 32-bit handle (HACCEL) identifies each table. However, only one accelerator table can be active at a time for a given thread. The handle of the accelerator table passed to the TranslateAccelerator function determines which accelerator table is active for a thread. The active accelerator table can be changed at any time by passing a different accelerator-table handle to TranslateAccelerator.


Accelerator-Table Creation

Several steps are required to create an accelerator table for an application. First, a resource compiler is used to create accelerator-table resources and to add them to the application's executable file. At run time, the LoadAccelerators function is used to load the accelerator table into memory and retrieve the handle of the accelerator table. This handle is passed to the TranslateAccelerator function to activate the accelerator table.

An accelerator table can also be created for an application at run time by passing an array of ACCEL structures to the CreateAcceleratorTable function. This method supports user-defined accelerators in the application. Like the LoadAccelerators function, CreateAcceleratorTable returns an accelerator-table handle that can be passed to TranslateAccelerator to activate the accelerator table.

Windows automatically destroys accelerator tables loaded by the LoadAccelerators function. An accelerator table created by the CreateAcceleratorTable function must be destroyed before an application closes; otherwise, the table continues to exist in memory after the application has closed. An accelerator table is destroyed by calling the DestroyAcceleratorTable function.

An existing accelerator table can be copied and modified. The existing accelerator table is copied by using the CopyAcceleratorTable function. After the copy is modified, a handle of the new accelerator table is retrieved by calling CreateAcceleratorTable. Finally, the handle is passed to the TranslateAccelerator function to activate the new table.


Accelerator Keystroke Assignments

An ASCII character code or a virtual-key code can be used to define the accelerator. An ASCII character code makes the accelerator case sensitive. The ASCII "C" character can define the accelerator as ALT+c rather than ALT + C. Case-sensitive accelerators can, however, be confusing to use. For example, the ALT+C accelerator will be generated if the CAPS LOCK key is down or if the SHIFT key is down, but not if both are down.

Typically, accelerators don't need to be case sensitive, so most applications use virtual-key codes for accelerators rather than ASCII character codes. For a list of virtual-key codes, see Virtual-Key Codes.

Avoid accelerators that conflict with an application's menu mnemonics because the accelerator overrides the mnemonic, and this can confuse the user. For more information about menu mnemonics, see Menus.

If an application defines an accelerator that is also defined in the system accelerator table, the application-defined accelerator overrides the system accelerator, but only within the context of the application. Avoid this practice, however, because it prevents the system accelerator from performing its standard role in the Windows user interface. The system-wide accelerators are described in the following list:

Accelerator	Description

ALT+ESC	Switches to the next application.

ALT+F4	Closes an application or a window.

ALT+HYPHEN	Opens the System menu for a document window.

ALT+PRINT SCREEN	Copies an image in the active window onto the Clipboard.

ALT+SPACEBAR	Opens the System menu for an application window.

ALT+TAB	Switches to the next application.

CTRL+ESC	Switches to Windows Task List.

CTRL+F4	Closes the active group or document window.

F1	Starts Help if the application has Help.

PRINT SCREEN	Copies an image on the screen onto the Clipboard.

SHIFT+ALT+TAB	Switches to the previous application. The user must press and hold down ALT+SHIFT while pressing TAB.


Accelerators and Menus

Using an accelerator is the same as choosing a menu item: both actions cause Windows to send a WM_COMMAND or WM_SYSCOMMAND message to the corresponding window procedure. The WM_COMMAND message includes an identifier that the window procedure examines to determine the source of the message. If an accelerator generated the WM_COMMAND message, the identifier is that of the accelerator. Similarly, if a menu item generated the WM_COMMAND message, the identifier is that of the menu item. Because an accelerator provides a shortcut for choosing a command from a menu, an application usually assigns the same identifier to the accelerator and the corresponding menu item.

An application processes an accelerator WM_COMMAND message in exactly the same way as the corresponding menu item WM_COMMAND message. However, the WM_COMMAND message contains a flag that specifies whether the message originated from an accelerator or a menu item, in case accelerators need to be processed differently from their corresponding menu items. The WM_SYSCOMMAND message does not contain this flag.

The identifier determines whether an accelerator generates a WM_COMMAND or WM_SYSCOMMAND message. If the identifier has the same value as a menu item in the System menu, the accelerator generates a WM_SYSCOMMAND message. Otherwise, the accelerator generates a WM_COMMAND message.

If an accelerator has the same identifier as a menu item and the menu item is grayed or disabled, the accelerator is disabled and does not generate a WM_COMMAND or WM_SYSCOMMAND message. Also, an accelerator does not generate a command message if the corresponding window is minimized.

When the user uses an accelerator that corresponds to a menu item, the window procedure receives the WM_INITMENU and WM_INITMENUPOPUP messages as though the user had selected the menu item. For information on how to process these messages, see Menus.

An accelerator that corresponds to an item in a menu should be included in the text of the menu item. For example, the Windows Write includes accelerators in the text of the first four items in its Edit menu:


Using an Accelerator-Table Resource

The most common way to add accelerator support to a Windows-based application is to include an accelerator-table resource with the application's executable file and then load the resource at run time. The steps involved in using an accelerator-table resource are as follows:

Create an accelerator table in a resource-definition file. Then compile it and add the resulting resource to your application's executable file.

Include a call to the LoadAccelerators function to load the accelerator-table resource and receive a handle of the accelerator table.

Add the TranslateAccelerator function to the message loop associated with the accelerator table.

Process the WM_COMMAND messages generated when the user uses the accelerator.

Creating the Accelerator-Table Resource

You create an accelerator-table resource by using the ACCELERATORS statement in your application's resource-definition file. You must assign a name or resource identifier to the accelerator table, preferably unlike that of any other resource. Windows uses this identifier to load the resource at run time.

Each accelerator that you define requires a separate entry in the accelerator table. In each entry, you define the keystroke (either an ASCII character code or virtual-key code) that generates the accelerator and the accelerator's identifier. You also need to specify whether the keystroke must be used in some combination with the ALT, SHIFT, or CTRL keys. For more information about virtual keys, see Keyboard Input.

An ASCII keystroke is specified either by enclosing the ASCII character in double quotation marks or by using the integer value of the character in combination with the ASCII flag. The following examples show how to define ASCII accelerators.

"A", ID_ACCEL1         ; SHIFT+A

65,  ID_ACCEL2, ASCII  ; SHIFT+A

A virtual-key code keystroke is specified differently depending on whether the keystroke is an alphanumeric key or a non-alphanumeric key. For an alphanumeric key, the key's letter or number, enclosed in double quotation marks, is combined with the VIRTKEY flag. For a non-alphanumeric key, the Windows virtual-key code for the specific key is combined with the VIRTKEY flag. The following examples show how to define virtual-key code accelerators.

"a",       ID_ACCEL3, VIRTKEY   ; A (caps-lock on) or a

VK_INSERT, ID_ACCEL4, VIRTKEY   ; INSERT key

The following example shows an accelerator-table resource that defines accelerators for file operations. The name of the resource is FileAccel.

FileAccel ACCELERATORS

BEGIN

    VK_F12, IDM_OPEN, CONTROL, VIRTKEY  ; CTRL+F12

    VK_F4,  IDM_CLOSE, ALT, VIRTKEY     ; ALT+F4

    VK_F12, IDM_SAVE, SHIFT, VIRTKEY    ; SHIFT+F12

    VK_F12, IDM_SAVEAS, VIRTKEY         ; F12

END

If you want the user to press the ALT, SHIFT, or CTRL keys in some combination with the accelerator keystroke, specify the ALT, SHIFT, and CONTROL flags in the accelerator's definition. Following are some examples.

"B",   ID_ACCEL5, ALT                   ; ALT_SHIFT+B

"I",   ID_ACCEL6, CONTROL, VIRTKEY      ; CTRL+I

VK_F5, ID_ACCEL7, CONTROL, ALT, VIRTKEY ; CTRL+ALT+F5

By default, when an accelerator key corresponds to a menu item, Windows highlights the menu item. You can use the NOINVERT flag to prevent highlighting for an individual accelerator. The following example shows how to use the NOINVERT flag.

VK_DELETE, ID_ACCEL8, VIRTKEY, SHIFT, NOINVERT  ; SHIFT+DELETE

To define accelerators that correspond to menu items in your application, include the accelerators in the text of the menu items. The following example shows how to include accelerators in menu-item text in a resource-definition file.

FilePopup MENU

BEGIN

    POPUP   "&File"

    BEGIN

        MENUITEM    "&New..",           IDM_NEW

        MENUITEM    "&Open\tCtrl+F12",  IDM_OPEN

        MENUITEM    "&Close\tAlt+F4"    IDM_CLOSE

        MENUITEM    "&Save\tShift+F12", IDM_SAVE

        MENUITEM    "Save &As...\tF12", IDM_SAVEAS

    END

END

Loading the Accelerator-Table Resource

An application loads an accelerator-table resource by calling the LoadAccelerators function and specifying the instance handle of the application whose executable file contains the resource and the name or identifier of the resource. LoadAccelerators loads the specified accelerator table into memory and returns the handle of the accelerator table.

An application can load an accelerator-table resource at any time. Usually, a single-threaded application loads its accelerator table before entering its main message loop. An application that uses multiple threads typically loads the accelerator-table resource for a thread before entering the message loop for the thread. An application or thread might also use multiple accelerator tables, each associated with a particular window in the application. Such an application would load the accelerator table for the window each time the user activated the window. For more information about threads, see Processes and Threads.

Calling the TranslateAccelerator Function

To process accelerators, an application's (or thread's) message loop must contain a call to the TranslateAccelerator function. TranslateAccelerator compares keystrokes to an accelerator table and, if it finds a match, translates the keystrokes into a WM_COMMAND (or WM_SYSCOMMAND) message and then sends the message to a window procedure. The parameters of the TranslateAccelerator function include the handle of the window that is to receive the WM_COMMAND messages, the handle of the accelerator table used to translate accelerators, and a pointer to an MSG structure containing a message from the queue. The following example shows how to call TranslateAccelerator from within a message loop.

while (GetMessage(&msg, (HWND) NULL, 0, 0)) {

    /* Check for accelerator keystrokes. */

    if (!TranslateAccelerator(

            hwndMain,      /* handle of receiving window    */

            haccel,        /* handle of active accel. table */

            &msg)) {       /* address of message data       */

        TranslateMessage(&msg);

        DispatchMessage(&msg);

    }

}

Processing WM_COMMAND Messages

When an accelerator is used, the window specified in the TranslateAccelerator function receives a WM_COMMAND or WM_SYSCOMMAND message. The low-order word of the wParam parameter contains the identifier of the accelerator. The window procedure examines the identifier to determine the source of the WM_COMMAND message and process the message accordingly.

Typically, if an accelerator corresponds to a menu-item in the application, the accelerator and menu item are assigned the same identifier. If you need to know whether a given WM_COMMAND message was generated by an accelerator or by a menu item, you can examine the high-order word of the wParam parameter. If an accelerator generated the message, the high-order word is 1, but if a menu item generated the message, it is 0.

Destroying the Accelerator-Table Resource

Windows automatically destroys accelerator-table resources loaded by the LoadAccelerators function, removing the resource from memory after the application closes.


Example: Accelerators for Font Attributes

Creating Accelerators for Font Attributes

The example in this section shows how to perform the following tasks:

Create an accelerator-table resource.

Load the accelerator table at run time.

Translate accelerators in a message loop.

Process WM_COMMAND messages generated by the accelerators.

These tasks are demonstrated in the context of an application that includes a Character menu and corresponding accelerators that allow the user to select attributes of the current font.

The following portion of a resource-definition file defines the Character menu and the associated accelerator table. Note that the menu items show the accelerator keystrokes and that each accelerator has the same identifier as its associated menu item.

#include <windows.h>

#include "acc.h"

MainMenu MENU

BEGIN

    POPUP   "&Character"

    BEGIN

        MENUITEM    "&Regular\tF5",         IDM_REGULAR

        MENUITEM    "&Bold\tCtrl+B",        IDM_BOLD

        MENUITEM    "&Italic\tCtrl+I",      IDM_ITALIC

        MENUITEM    "&Underline\tCtrl+U",   IDM_ULINE

    END

END

FontAccel ACCELERATORS

BEGIN

    VK_F5,  IDM_REGULAR,    VIRTKEY

    "B",    IDM_BOLD,       CONTROL, VIRTKEY

    "I",    IDM_ITALIC,     CONTROL, VIRTKEY

    "U",    IDM_ULINE,      CONTROL, VIRTKEY

END

The following sections from the application's source file show how to implement the accelerators.

HWND hwndMain;      /* handle of main window          */

HANDLE hinstAcc;    /* handle of application instance */

int WINAPI WinMain(hinst, hinstPrev, lpCmdLine, nCmdShow)

HINSTANCE hinst;

HINSTANCE hinstPrev;

LPSTR lpCmdLine;

int nCmdShow;

{

    MSG msg;            /* application messages              */

    HACCEL haccel;      /* handle of accelerator table       */

    .

    . /* Perform the initialization procedure. */

    .

    /* Create a main window for this application instance. */

    hwndMain = CreateWindowEx(0L, "MainWindowClass",

        "Sample Application", WS_OVERLAPPEDWINDOW, CW_USEDEFAULT,

        CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, NULL, NULL,

        hinst, NULL );

    /* If a window cannot be created, return "failure." */

    if (!hwndMain)

        return FALSE;

    /* Make the window visible and update its client area. */

    ShowWindow(hwndMain, nCmdShow);

    UpdateWindow(hwndMain);

    /* Load the accelerator table. */

    haccel = LoadAccelerators(hinstAcc, "FontAccel");

    if (haccel == NULL)

        HandleAccelErr(ERR_LOADING);     /* application defined */

    /*

     * Get and dispatch messages until a WM_QUIT message is

     * received.

     */

    while (GetMessage(&msg, NULL, NULL, NULL)) {

        /* Check for accelerator keystrokes. */

        if (!TranslateAccelerator(

                hwndMain,      /* handle of receiving window    */

                haccel,        /* handle of active accel. table */

                &msg)) {       /* address of message data       */

            TranslateMessage(&msg);

            DispatchMessage(&msg);

        }

    }

    return msg.wParam;

}

LRESULT APIENTRY MainWndProc(hwndMain, uMsg, wParam, lParam)

HWND hwndMain;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    BYTE fbFontAttrib;        /* array of font-attribute flags  */

    static HMENU hmenu;       /* handle of main menu            */

    switch (uMsg) {

        case WM_CREATE:

            /*

             * Add a check mark to the Regular menu item to

             * indicate that it is the default.

             */

            hmenu = GetMenu(hwndMain);

            CheckMenuItem(hmenu, IDM_REGULAR, MF_BYCOMMAND |

                MF_CHECKED);

            return 0;

        case WM_COMMAND:

            switch (LOWORD(wParam)) {

                /* Process the accelerator and menu commands. */

                case IDM_REGULAR:

                case IDM_BOLD:

                case IDM_ITALIC:

                case IDM_ULINE:

                    /*

                     * GetFontAttributes is an application-defined

                     * function that sets the menu-item check marks

                     * and returns the user-selected font attributes.

                     */

                    fbFontAttrib = GetFontAttributes(

                        (BYTE) LOWORD(wParam), hmenu);

                     /*

                     * SetFontAttributes is an application-defined

                     * function that creates a font with the

                     * user-specified attributes the font with

                     * the main window's device context.

                     */

                    SetFontAttributes(fbFontAttrib);

                    break;

                default:

                    break;

            }

            break;

            .

            . /* Process other messages. */

            .

        default:

            return DefWindowProc(hwndMain, uMsg, wParam, lParam);

    }

    return NULL;

}


Using an Accelerator Table Created at Run Time

The Win32 application programming interface (API) allows you to create accelerator tables at run time. The steps involved in creating and using an accelerator table at run time are as follows:

Define the accelerators by filling an array of ACCEL structures and then create an accelerator table by passing the array to the CreateAcceleratorTable function.

Activate the accelerator table and process WM_COMMAND messages generated by the accelerators.

Destroy the accelerator table before the application closes.

Creating the Accelerator Table

The first step in creating an accelerator table at run time is filling an array of ACCEL structures. Each structure in the array defines an accelerator in the table. An accelerator's definition includes its flags, its key, and its identifier. The ACCEL structure has the following form.

typedef struct tagACCEL { /* accl */

    BYTE   fVirt;

    WORD   key;

    WORD   cmd;

} ACCEL;

You define an accelerator's keystroke by specifying an ASCII character code or a virtual-key code in the key member of the ACCEL structure. If you specify a virtual-key code, you must first include the FVIRTKEY flag in the fVirt member; otherwise, Windows interprets the code as an ASCII character code. You can include the FCONTROL, FALT, or FSHIFT flag, or all three, to combine the CTRL, ALT, or SHIFT key with the keystroke.

To create the accelerator table, pass the address of the array of ACCEL structures to the CreateAcceleratorTable function. CreateAcceleratorTable creates the accelerator table and returns the handle of the table.

Processing Accelerators

The process of loading and calling accelerators provided by an accelerator table created at run time is the same as processing those provided by an accelerator table resource. For more information, see Loading the Accelerator-Table Resource through Processing WM_COMMAND Messages

Destroying the Accelerator Table

Before an application closes, it must destroy accelerator tables created at run time. You can destroy an accelerator table and remove it from memory by passing the table's handle to the DestroyAcceleratorTable function.


Example: User-Editable Accelerators

Creating User-Editable Accelerators

This example shows how to construct a dialog box that allows the user to change the accelerator associated with a menu item. The dialog box consists of a combo box containing menu items, a combo box containing the names of keys, and check boxes for selecting the CTRL, ALT, and SHIFT keys. The following illustration shows the dialog box.

The following example shows how the dialog box is defined in the resource-definition file.

EdAccelBox DIALOG 5, 17, 193, 114

STYLE DS_MODALFRAME | WS_POPUP | WS_VISIBLE | WS_CAPTION

CAPTION "Edit Accelerators"

BEGIN

    COMBOBOX        IDD_MENUITEMS, 10, 22, 52, 53,

                        CBS_SIMPLE | CBS_SORT | WS_VSCROLL |

                        WS_TABSTOP

    CONTROL         "Control", IDD_CNTRL, "Button",

                        BS_AUTOCHECKBOX | WS_TABSTOP,

                        76, 35, 40, 10

    CONTROL         "Alt", IDD_ALT, "Button",

                        BS_AUTOCHECKBOX | WS_TABSTOP,

                        76, 48, 40, 10

    CONTROL         "Shift", IDD_SHIFT, "Button",

                        BS_AUTOCHECKBOX | WS_TABSTOP,

                        76, 61, 40, 10

    COMBOBOX        IDD_KEYSTROKES, 124, 22, 58, 58,

                        CBS_SIMPLE | CBS_SORT | WS_VSCROLL |

                        WS_TABSTOP

    PUSHBUTTON      "Ok", IDOK, 43, 92, 40, 14

    PUSHBUTTON      "Cancel", IDCANCEL, 103, 92, 40, 14

    LTEXT           "Select Item:", 101, 10, 12, 43, 8

    LTEXT           "Select Keystroke:", 102, 123, 12, 60, 8

END

The dialog box uses an array of application-defined VKEY structures, each containing a keystroke-text string and an accelerator-text string. When the dialog box is created, it parses the array and adds each keystroke-text string to the Select Keystroke combo box. When the user clicks the Ok button, the dialog box looks up the selected keystroke-text string and retrieves the corresponding accelerator-text string. The dialog box appends the accelerator-text string to the text of the menu item that the user selected. The following example shows the array of VKEY structures:

/* VKey Lookup Support */

#define MAXKEYS 26

typedef struct _VKEYS {

    char *pKeyName;

    char *pKeyString;

} VKEYS;

VKEYS vkeys[MAXKEYS] = {

    "BkSp",     "Back Space",

    "PgUp",     "Page Up",

    "PgDn",     "Page Down",

    "End",      "End",

    "Home",     "Home",

    "Lft",      "Left",

    "Up",       "Up",

    "Rgt",      "Right",

    "Dn",       "Down",

    "Ins",      "Insert",

    "Del",      "Delete",

    "Mult",     "Multiply",

    "Add",      "Add",

    "Sub",      "Subtract",

    "DecPt",    "Decimal Point",

    "Div",      "Divide",

    "F2",       "F2",

    "F3",       "F3",

    "F5",       "F5",

    "F6",       "F6",

    "F7",       "F7",

    "F8",       "F8",

    "F9",       "F9",

    "F11",      "F11",

    "F12",      "F12"

};

The dialog box's initialization procedure fills the Select Item and Select Keystroke combo boxes. After the user selects a menu item and associated accelerator, the dialog box examines the controls in the dialog box to get the user's selection, updates the text of the menu item, and then creates a new accelerator table that contains the user-defined new accelerator. The following example shows the dialog-box procedure.

/* Global variables */

HWND hwndMain;      /* handle of main window          */

HANDLE hinstAcc;    /* handle of application instance */

HACCEL haccel;      /* handle of accelerator table    */

.

.

.

/* Dialog-box procedure */

LRESULT CALLBACK EdAccelProc(hwndDlg, uMsg, wParam, lParam)

HWND hwndDlg;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    int nCurSel;            /* index of list box item          */

    UINT idItem;            /* menu-item identifier            */

    UINT uItemPos;          /* menu-item position              */

    UINT i, j = 0;          /* loop counters                   */

    static UINT cItems;     /* count of items in menu          */

    char szTemp[32];        /* temporary buffer                */

    char szAccelText[32];   /* buffer for accelerator text     */

    char szKeyStroke[16];   /* buffer for keystroke text       */

    static char szItem[32]; /* buffer for menu-item text       */

    HWND hwndCtl;           /* handle of control window        */

    static HMENU hmenu;     /* handle of "Character" menu      */

    PCHAR pch, pch2;        /* pointers for string copying     */

    WORD wVKCode;           /* accelerator virtual-key code    */

    BYTE fAccelFlags;       /* fVirt flags for ACCEL structure */

    LPACCEL lpaccelNew;     /* address of new accel. table     */

    HACCEL haccelOld;       /* handle of old accel. table      */

    int cAccelerators;      /* number of accelerators in table */

    static BOOL fItemSelected = FALSE; /* item selection flag  */

    static BOOL fKeySelected = FALSE;  /* key selection flag   */

    switch (uMsg) {

        case WM_INITDIALOG:

            /* Get the handle of the menu-item combo box. */

            hwndCtl = GetDlgItem(hwndDlg, IDD_MENUITEMS);

            /*

             * The application's menu bar contains a "Character"

             * submenu whose items have accelerators associated

             * with them. Get the handle of the "Character"

             * submenu (its position within the main menu is 2),

             * and count the number of items it has.

             */

            hmenu = GetSubMenu(GetMenu(hwndMain), 2);

            cItems = GetMenuItemCount(hmenu);

            /*

             * Get the text of each item, strip out the '&' and

             * the accelerator text, and add the text to the

             * menu-item combo box.

             */

            for (i = 0; i < cItems; i++) {

                if (!(GetMenuString(hmenu, i, szTemp,

                        sizeof(szTemp), MF_BYPOSITION)))

                    continue;

                for (pch = szTemp, pch2 = szItem;

                       *pch != '\0'; ) {

                    if (*pch != '&') {

                        if (*pch == '\t') {

                            *pch = '\0';

                            *pch2 = '\0';

                        }

                        else

                            *pch2++ = *pch++;

                    }

                    else

                        pch++;

                }

                SendMessage(hwndCtl, CB_ADDSTRING, 0,

                    (LONG) (LPSTR) szItem);

            }

            /*

             * Now fill the keystroke combo box with the list of

             * keystrokes that will be allowed for accelerators.

             * The list of keystrokes is in the application-defined

             * structure called "vkeys".

             */

            hwndCtl = GetDlgItem(hwndDlg, IDD_KEYSTROKES);

            for (i = 0; i < MAXKEYS; i++)

                SendMessage(hwndCtl, CB_ADDSTRING, 0,

                    (LONG) (LPSTR) vkeys[i].pKeyString);

            return TRUE;

        case WM_COMMAND:

            switch (LOWORD(wParam)) {

                case IDD_MENUITEMS:

                    /*

                     * The user must select an item from the menu-

                     * item combo box. This flag is checked during

                     * IDOK processing to be sure a selection was made.

                     */

                    fItemSelected = TRUE;

                    return 0;

                case IDD_KEYSTROKES:

                    /*

                     * The user must select an item from the menu-

                     * item combo box. This flag is checked during

                     * IDOK processing to be sure a selection was made.

                     */

                    fKeySelected = TRUE;

                    return 0;

                case IDOK:

                    /*

                     * If the user has not selected a menu item

                     * and a keystroke, display a reminder in a

                     * message box.

                     */

                    if (!fItemSelected || !fKeySelected) {

                        MessageBox(hwndDlg,

                            "Item or key not selected.", NULL,

                            MB_OK);

                        return 0;

                    }

                    /*

                     * Determine whether the CTRL, ALT, and SHIFT

                     * keys are selected. Concatenate the

                     * appropriate strings to the accelerator-

                     * text buffer, and set the appropriate

                     * accelerator flags.

                     */

                    szAccelText[0] = '\0';

                    hwndCtl = GetDlgItem(hwndDlg, IDD_CNTRL);

                    if (SendMessage(hwndCtl, BM_GETCHECK, 0, 0)

                            == 1) {

                        lstrcat(szAccelText, "Ctl+");

                        fAccelFlags |= FCONTROL;

                    }

                    hwndCtl = GetDlgItem(hwndDlg, IDD_ALT);

                    if (SendMessage(hwndCtl, BM_GETCHECK, 0, 0)

                            == 1) {

                        lstrcat(szAccelText, "Alt+");

                        fAccelFlags |= FALT;

                    }

                    hwndCtl = GetDlgItem(hwndDlg, IDD_SHIFT);

                    if (SendMessage(hwndCtl, BM_GETCHECK, 0, 0)

                            == 1) {

                        lstrcat(szAccelText, "Shft+");

                        fAccelFlags |= FSHIFT;

                    }

                    /*

                     * Get the selected keystroke, and look up the

                     * accelerator text and the virtual-key code

                     * for the keystroke in the vkeys structure.

                     */

                    hwndCtl = GetDlgItem(hwndDlg, IDD_KEYSTROKES);

                    nCurSel = (int) SendMessage(hwndCtl,

                        CB_GETCURSEL, 0, 0);

                    SendMessage(hwndCtl, CB_GETLBTEXT,

                        nCurSel, (LONG) (LPSTR) szKeyStroke);

                    for (i = 0; i < MAXKEYS; i++) {

                        if(lstrcmp(vkeys[i].pKeyString,

                                szKeyStroke) == 0) {

                            lstrcpy(szKeyStroke,

                                vkeys[i].pKeyName);

                            break;

                        }

                    }

                    /*

                     * Concatenate the keystroke text to the

                     * "Ctl+","Alt+", or "Shft+" string.

                     */

                    lstrcat(szAccelText, szKeyStroke);

                    /*

                     * Determine the position in the menu of the

                     * selected menu item. Menu items in the

                     * "Character" menu have positions 0,2,3, and 4.

                     */

                    if (lstrcmp(szItem, "Regular") == 0)

                        uItemPos = 0;

                    else if (lstrcmp(szItem, "Bold") == 0)

                        uItemPos = 2;

                    else if (lstrcmp(szItem, "Italic") == 0)

                        uItemPos = 3;

                    else if (lstrcmp(szItem, "Underline") == 0)

                        uItemPos = 4;

                    /*

                     * Get the string that corresponds to the

                     * selected item.

                     */

                    GetMenuString(hmenu, uItemPos, szItem,

                        sizeof(szItem), MF_BYPOSITION);

                    /*

                     * Append the new accelerator text to the

                     * menu-item text.

                     */

                    for (pch = szItem; *pch != '\t'; pch++);

                    ++pch;

                    for (pch2 = szAccelText; *pch2 != '\0';

                            pch2++)

                        *pch++ = *pch2;

                    *pch = '\0';

                    /*

                     * Modify the menu item to reflect the new

                     * accelerator text.

                     */

                    idItem = GetMenuItemID(hmenu, uItemPos);

                    ModifyMenu(hmenu, idItem, MF_BYCOMMAND |

                        MF_STRING, idItem, szItem);

                    /* Reset the selection flags. */

                    fItemSelected = FALSE;

                    fKeySelected = FALSE;

                    /* Save the current accelerator table. */

                    haccelOld = haccel;

                    /*

                     * Count the number of entries in the current

                     * table, allocate a buffer for the table, and

                     * then copy the table into the buffer.

                     */

                    cAccelerators = CopyAcceleratorTable(

                        haccelOld, NULL, 0);

                    lpaccelNew = (LPACCEL) LocalAlloc(LPTR,

                        cAccelerators * sizeof(ACCEL));

                    if (lpaccelNew != NULL)

                        CopyAcceleratorTable(haccel, lpaccelNew,

                            cAccelerators);

                    /*

                     * Find the accelerator that the user modified

                     * and change its flags and virtual-key code

                     * as appropriate.

                     */

                    for (i = 0; (lpaccelNew[i].cmd ==

                                (WORD) idItem)

                            && (i < (UINT) cAccelerators); i++) {

                        lpaccelNew[i].fVirt = fAccelFlags;

                        lpaccelNew[i].key = wVKCode;

                    }

                    /*

                     * Create the new accelerator table, and

                     * destroy the old one.

                     */

                    DestroyAcceleratorTable(haccelOld);

                    haccel = CreateAcceleratorTable(lpaccelNew,

                        cAccelerators);

                    /* Destroy the dialog box. */

                    EndDialog(hwndDlg, TRUE);

                    return 0;

                case IDCANCEL:

                    EndDialog(hwndDlg, TRUE);

                    return TRUE;

                default:

                    break;

            }

        default:

            break;

    }

    return FALSE;

}


Functions and Messages

Following are the functions and messages used with accelerators.

Functions

CopyAcceleratorTable

CreateAcceleratorTable

DestroyAcceleratorTable

LoadAccelerators

TranslateAccelerator

Messages

WM_COMMAND

WM_INITMENU

WM_INITMENUPOPUP

WM_MENUCHAR

WM_MENUSELECT

WM_SYSCHAR

WM_SYSCOMMAND


Dialog Boxes Overview

About Dialog Boxes

In Microsoft® Windows™, a dialog box is a temporary window an application creates to retrieve user input. An application typically uses dialog boxes to prompt the user for additional information for commands. A dialog box usually contains one or more controls (child windows) with which the user enters text, chooses options, or directs the action of the command.

Windows provides many functions, messages, and predefined controls to help create and manage dialog boxes, thus making it easier to develop the user interface for an application. This topic describes the dialog box functions and messages and explains how to use them create and use dialog boxes.

Windows also provides many predefined or "common" dialog boxes that support commands, such as File Open and File Print. Applications that use these commands should use the common dialog boxes to prompt for the same user input, regardless of the type of application carrying out the commands.

The following topics discuss Win32 dialog boxes:

Terms

When To Use a Dialog Box

Owner Window

Message Boxes

Modal Dialog Boxes

Modeless Dialog Boxes

Dialog Box Template

Dialog Box Procedure

Dialog Box Keyboard Interface

Dialog Box Settings

Custom Dialog Boxes

Using Dialog Boxes

Displaying a Message Box

Creating a Modal Dialog Box

Creating a Modeless Dialog Box

Initializing a Dialog Box

Creating a Template in Memory

Functions, Messages, and Structures


When to Use a Dialog Box

Most applications use dialog boxes to prompt for additional information for commands that require user input. Using a dialog box is the only recommended way for an application to retrieve the input. For example, the File Open command requires the name of a file to open, so an application should use a dialog box to prompt the user for the name. In such cases, the application creates the dialog box when the user chooses the command and destroys the dialog box immediately after the user supplies the information.

Many applications also use dialog boxes to display information or options while the user works in another window. For example, word processing applications often use a dialog box with a text search command. While the application searches for the text, the dialog box remains on the screen. The user can then return to the dialog box and search for the same word again, or change the entry in the dialog box and search for a new word. Applications that use dialog boxes in this way typically create one when the user chooses a command and continue to display it for as long as the application runs or until the user explicitly closes the dialog box.

To support the different ways applications use dialog boxes, Windows provides two types of dialog box: modal and modeless. A modal dialog box requires the user to supply information or cancel the dialog box before allowing the application to continue. Applications use modal dialog boxes in conjunction with commands that require additional information before they can proceed. A modeless dialog box allows the user to supply information and return to the previous task without closing the dialog box. Modal dialog boxes are simpler to manage than modeless dialog boxes because they are created, perform their task, and are destroyed by calling a single function.

To create either a modal or modeless dialog box, an application must supply a dialog box template to describe the dialog box style and content and a dialog box procedure to carry out tasks. The dialog box template is a binary description of the dialog box and the controls it contains. The developer can create this template as a resource to be loaded from the application's executable file, or created in memory while the application runs. The dialog box procedure is an application-defined callback function that Windows calls when it has input for the dialog box or tasks for the dialog box to carry out. Although a dialog box procedure is similar to a window procedure, it does not have the same responsibilities.

An application typically creates a dialog box by using either the DialogBox or CreateDialog function. DialogBox creates a modal dialog box; CreateDialog creates a modeless dialog box. These functions load a dialog box template from the application's executable file and create a pop-up window that matches the template's specifications. There are other functions that create dialog boxes by using templates in memory and pass additional information to the dialog box procedure as the dialog box is created.

Dialog boxes usually belong to a predefined, exclusive window class. Windows uses this window class and its corresponding window procedure for both modal and modeless dialog boxes. When the function is called, it creates the window for the dialog box, as well as the windows for all controls in the dialog box, then sends selected messages to the dialog box procedure. While the dialog box is visible, the predefined window procedure manages all messages, processing some messages and passing others to the dialog box procedure so that the procedure can carry out tasks. Applications do not have direct access to the predefined window class or window procedure, but they can use the dialog box template and dialog box procedure to modify the style and behavior of a dialog box.


Owner Window

Most dialog boxes have an owner window (or more simply, an owner). When creating the dialog box, the application sets the owner by specifying the owner's window handle. Windows uses the owner to determine the position of the dialog box in the Z order so that a dialog box is always positioned above its owner. Also, Windows can send messages to the window procedure of the owner, notifying it of events in the dialog box.

Windows automatically hides or destroys the dialog box whenever its owner is hidden or destroyed. This means the dialog box procedure requires no special processing to detect changes to the state of the owner window.

Because the typical dialog box is used in conjunction with a command in a menu, the owner window is usually the window containing the menu. Although it is possible to create a dialog box that has no owner, it is not recommended. For example, when a modal dialog box has no owner, Windows does not disable any of the application's other windows and allows the user to continue to carry out work in the other windows, defeating the purpose of the modal dialog box.

When a modeless dialog box has no owner, Windows neither hides nor destroys the dialog box when other windows in the application are hidden or destroyed. Although this does not defeat the purpose of the modeless dialog box, it requires that the application carry out special processing to ensure the dialog box is hidden and destroyed at appropriate times.


Message Boxes

A message box is a special dialog box that an application can use to display messages and prompt for simple input. A message box typically contains a text message and one or more push buttons. An application creates the message box by using the MessageBox function, specifying the text and the number and types of buttons to display.

Although the message box is a dialog box, Windows takes complete control of the creation and management of the message box. This means the application does not provide a dialog box template and dialog box procedure. Windows creates its own template based on the text and buttons specified for the message box and supplies its own dialog box procedure.

A message box is a modal dialog box and Windows creates it by using the same internal functions that the DialogBox function uses. If the application specifies an owner window when calling MessageBox, Windows disables the owner. An application can also direct Windows to disable all top-level windows belonging to the current task by specifying the MB_TASKMODAL value when creating the dialog box.

Windows can send messages to the owner, such as the WM_CANCELMODE and WM_ENABLE, just as it does when creating a modal dialog box. The owner window should carry out any actions requested by these messages.


Modal Dialog Boxes

A modal dialog box should be a pop-up window having a System menu, a title bar, and a thick border; that is, the dialog box template should specify the WS_POPUP, WS_SYSMENU, WS_CAPTION, and DS_MODALFRAME styles. Although an application can designate the WS_VISIBLE style, Windows always displays a modal dialog box regardless of whether the dialog box template specifies the WS_VISIBLE style. An application must not create a modal dialog box having the WS_CHILD style. A modal dialog box with this style disables itself, preventing any subsequent input from reaching the application.

An application creates a modal dialog box by using the DialogBox or DialogBoxIndirect function. DialogBox requires the name or identifier of a resource containing a dialog box template; DialogBoxIndirect requires the handle of a memory object containing a dialog box template. The DialogBoxParam and DialogBoxIndirectParam functions also create modal dialog boxes; they are identical to the previously mentioned functions but pass a specified parameter to the dialog box procedure when the dialog box is created.

When creating the modal dialog box, Windows makes it the active window. The dialog box remains active until the dialog box procedure calls the EndDialog function or Windows activates a window in another application. Neither the user nor the application can make the owner window active until the modal dialog box is destroyed.

When the owner window is not already disabled, Windows automatically disables the window and any child windows belonging to it when it creates the modal dialog box. The owner window remains disabled until the dialog box is destroyed. Although a dialog box procedure could potentially enable the owner window at any time, enabling the owner defeats the purpose of the modal dialog box and is not recommended. When the dialog box procedure is destroyed, Windows enables the owner window again, but only if the modal dialog box caused the owner to be disabled.

As Windows creates the modal dialog box, it sends the WM_CANCELMODE message to the window (if any) currently capturing mouse input. An application that receives this message should release the mouse capture so that the user can move the mouse in the modal dialog box. Because Windows disables the owner window, all mouse input is lost if the owner fails to release the mouse upon receiving this message.

To process messages for the modal dialog box, Windows starts its own message loop, taking temporary control of the message queue for the entire application. When Windows retrieves a message that is not explicitly for the dialog box, it dispatches the message to the appropriate window. If it retrieves a WM_QUIT message, it posts the message back to the application message queue so that the application's main message loop can eventually retrieve the message.

Windows sends the WM_ENTERIDLE message to the owner window whenever the application message queue is empty. The application can use this message to carry out a background task while the dialog box remains on the screen. When an application uses the message in this way, the application must frequently yield control (for example, by using the PeekMessage function) so that the modal dialog box can receive any user input. An application can prevent the modal dialog box from sending the WM_ENTERIDLE messages by specifying the DS_NOIDLEMSG style when creating the dialog box.

An application destroys a modal dialog box by using the EndDialog function. In most cases, the dialog box procedure calls EndDialog when the user chooses the Close command from the dialog box's System menu or presses the OK or Cancel button in the dialog box. The dialog box can return a value through the DialogBox function (or other creation function) by specifying a value when it calls the EndDialog function. Windows returns this value after destroying the dialog box. Most applications use this return value to determine whether the dialog box completed its task successfully or was canceled by the user. Windows does not return control from the function that creates the dialog box until the dialog box procedure has called the EndDialog function.


Modeless Dialog Boxes

A modeless dialog box should be a pop-up window having a System menu, a title bar, and a thin border; that is, the dialog box template should specify the WS_POPUP, WS_CAPTION, WS_BORDER, and WS_SYSMENU styles. Windows does not automatically display the dialog box unless the template specifies the WS_VISIBLE style.

An application creates a modeless dialog box using the CreateDialog or CreateDialogIndirect function. CreateDialog requires the name or identifier of a resource containing a dialog box template; CreateDialogIndirect requires the handle of a memory object containing a dialog box template. The CreateDialogParam and CreateDialogIndirectParam functions also create modeless dialog boxes; they pass a specified parameter to the dialog box procedure when the dialog box is created.

CreateDialog and other creation functions return a window handle for the dialog box. The application and the dialog box procedure can use this handle to manage the dialog box. For example, if WS_VISIBLE is not given in the dialog box template, the application can display the dialog box by passing the window handle to the ShowWindow function.

A modeless dialog box neither disables the owner window nor sends messages to it. When creating the dialog box, Windows makes it the active window, but the user or the application can change the active window at any time. If the dialog box becomes inactive, it remains above the owner window in the Z order, even if the owner window is active.

The application is responsible for retrieving and dispatching input messages to the dialog box. Most applications use the main message loop for this. However, to permit the user to move to and select controls by using the keyboard, the application must call the IsDialogMessage function. For more information about this function, see Dialog Box Keyboard Interface.

A modeless dialog box cannot return a value to the application as a modal dialog box does, but the dialog box procedure can send information to the owner window by using the SendMessage function.

An application must destroy all modeless dialog boxes before terminating. It can destroy a modeless dialog box by using the DestroyWindow function. In most cases, the dialog box procedure calls DestroyWindow in response to user input, such as clicking the Cancel button. If the user never closes the dialog box in this way, the application must call DestroyWindow.

The DestroyWindow function invalidates the window handle for the dialog box, so any subsequent calls to functions that use the handle return error values. To prevent errors, the dialog box procedure should notify the owner that the dialog box has been destroyed. Many applications maintain a global variable containing the handle for the dialog box . When the dialog box procedure destroys the dialog box, it also sets the global variable to NULL, indicating that the dialog box is no longer valid.

The dialog box procedure must not call the EndDialog function to destroy a modeless dialog box.


Dialog Box Template

A dialog box template is binary data that describes the dialog box, defining its height, width, style, and the controls it contains. To create a dialog box, Windows either loads a dialog box template from the resources in the application's executable file or uses the template passed to it in global memory by the application. In either case, the application is responsible for supplying a template when it creates a dialog box.

A developer creates template resources by using a resource compiler or a dialog box editor. A resource compiler converts a text description into a binary resource, and a dialog box editor saves an interactively constructed dialog box as a binary resource.

Note:	An explanation of how to create template resources and add them to the application's executable file is beyond the scope of this book. For more information, see the documentation provided with your application development tools.

Applications that create dialog boxes without using template resources must create templates in memory and pass the templates to the DialogBoxIndirect or CreateDialogIndirect function. An application creates a memory template by allocating a global memory object and filling it with a DLGTEMPLATE structure and one or more DLGITEMTEMPLATE structures. A memory template is identical in form and content to a template resource. Many applications that use memory templates first load a template resource into memory by using the the LoadResource function, then modify the loaded resource to create a new memory template.

The following sections describe the styles, measurements, and other values used in a dialog box template.

Styles

Every dialog box template specifies a combination of style values that define the appearance and features of the dialog box. The style values can be window styles, such as WS_POPUP and WS_SYSMENU, and dialog box styles, such as DS_MODALFRAME. The number and type of styles for a template depends on the type and purpose of the dialog box.

Windows passes all window styles given in the template to the CreateWindowEx function when it creates the dialog box. Windows may pass one or more extended styles depending on the given dialog box styles. For example, when the template specifies the DS_MODALFRAME style, Windows uses the WS_EX_DLGMODALFRAME style when creating the dialog box. When the template specifies the DS_SYSMODAL style, Windows uses the WS_EX_TOPMOST style. All other dialog box styles affect how Windows manages the dialog box.

Most dialog boxes are pop-up windows that have a system menu and a title bar. Therefore, the typical template specifies the WS_POPUP, WS_SYSMENU, and WS_CAPTION styles. The template also specifies a border style: DS_MODALFRAME for modal dialog boxes, and WS_BORDER for modeless dialog boxes. A template may specify a window type other than pop-up (such as WS_OVERLAPPED) if it creates a customized window instead of a dialog box.

Windows always displays a modal dialog box regardless of whether the WS_VISIBLE style is given. When the template for a modeless dialog box specifies the WS_VISIBLE style, Windows automatically displays the dialog box when it is created. Otherwise, the application is responsible for displaying the dialog box by using the ShowWindow function.

The template can specify the DS_SETFOREGROUND style to force Windows to bring the dialog box to the foreground. This is especially useful for modal dialog boxes that require immediate attention from the user regardless of whether the owner window is the foreground window. This style is available in Windows NT only.

The DS_ABSALIGN style causes Windows to interpret dialog box measurements as screen coordinates; DS_SETFONT causes Windows to use a given font, instead of the system font, to draw text in the dialog box client area and in the controls in the dialog box; and DS_NOIDLEMSG prevents a modal dialog box from sending WM_ENTERIDLE messages to the owner window. These styles are described in more detail in later sections in this topic.

The DS_SYSMODAL and DS_LOCALEDIT styles apply to applications written for Windows 3.x. Windows NT does not allow system modal dialog boxes but does ensure that dialog boxes with this style receive the WS_EX_TOPMOST style. Windows NT ignores the DS_LOCALEDIT style.

Portability Issue:	Windows NT does not support system modal dialog boxes. When creating modal dialog boxes, Windows NT ignores the DS_SYSMODAL style if it is given in the dialog box template. Applications should not depend on the behavior of a system modal dialog box.

Dialog Box Measurements

Every dialog box template contains measurements that specify the position, width, and height of the dialog box and the controls it contains. These measurements are device independent, so an application can use a single template to create the same dialog box for all types of display devices. This ensures that a dialog box will have the same proportions and appearance on all screens despite differing resolutions and aspect ratios between screens.

Dialog box measurements are given in dialog base units. One horizontal unit is equal to one-fourth of the average character width for the system font. One vertical unit is equal to one-eighth of the average character height for the system font. An application can retrieve the number of pixels per base unit for the current display by using the GetDialogBaseUnits function. An application can convert measurements from dialog base units to pixels by using the MapDialogRect function.

The template must specify the initial coordinates of the upper left corner of the dialog box. Usually the coordinates are relative to the upper left corner of the owner window's client area. When the template specifies the DS_ABSALIGN style or the dialog box has no owner, the position is relative to the upper left corner of the screen. Windows sets this initial position when it creates the dialog box, but permits an application to adjust the position before displaying the dialog box. For example, an application can retrieve the dimensions of the owner window, calculate a new position that centers the dialog box in the owner window, then set the position by using the SetWindowPos function.

The template should specify a dialog box width and height that does not exceed the width and height of the screen and ensures that all controls and are within the client area of the dialog box. Although Windows permits a dialog box to be any size, creating one that is too small or too large can prevent the user from providing input, defeating the purpose of the dialog box. Many applications use more than one dialog box when there are a large number of controls. In such cases, the initial dialog box usually contains one or more push buttons that the user can click to display the next dialog box.

Controls

The template specifies the position, width, height, style, identifier, and window class for each control in the dialog box. Windows creates each control by passing this data to the CreateWindowEx function. Controls are created in the order they are given in the template. The template should specify the appropriate number, type, and order of controls to ensure that the user can enter the input needed to complete the command associated with the dialog box.

For each control, the template specifies style values that define the appearance and operation of the control. Every control is a child window and therefore must have the WS_CHILD style. To ensure that the control is visible when the dialog box is displayed, each control must also have the WS_VISIBLE style. Other commonly used window styles are WS_BORDER for controls that have optional borders, WS_DISABLED for controls that should be disabled when the dialog box is initially created, and WS_TABSTOP and WS_GROUP for controls that can be accessed using the keyboard. The WS_TABSTOP and WS_GROUP styles are used in conjunction with the dialog keyboard interface described later in this topic.

The template may also specify control style values that are specific to the control's window class. For example, a template that specifies a button control must give a button control style such as BS_PUSHBUTTON or BS_CHECKBOX. Windows passes the control styles to the control window procedure through the WM_CREATE message, allowing the procedure to adapt the appearance and operation of the control.

Windows converts the position coordinates and the width and height measurements from dialog base units to pixels, before passing these to the CreateWindowEx function. When Windows creates a control, it specifies the dialog box as the parent window. This means Windows always interprets the position coordinates of the control as client coordinates, relative to the upper left corner of the dialog box's client area.

The template specifies the window class for each control. A typical dialog box contains controls belonging to the predefined control window classes, such as the button and edit control window classes. In this case, the template specifies window classes by giving the corresponding predefined atom values for the classes. When a dialog box contains a control belonging a custom control window class, the template gives the name of that registered window class or the atom value currently associated with the name.

Each control in a dialog box must have a unique identifier to distinguish it from other controls. Controls send information to the dialog box procedure through WM_COMMAND messages, so the control identifiers are essential for the procedure to determine which control sent a given message. The only exception to this rule are control identifiers for static controls. Static controls do not require unique identifiers because they send no WM_COMMAND messages.

To permit the user to close the dialog box, the template should specify at least one push button and give it the control identifier IDCANCEL. To permit the user to choose between completing or canceling the command associated with the dialog box, the template should specify two push buttons, labeled OK and Cancel. In this case, the control identifier for the OK button should be IDOK and, for the Cancel button, IDCANCEL.

A template also specifies optional text and creation data for a control. The text typically provides labels for button controls or specifies the initial content of a static text control. The creation data is one or more bytes of data that Windows passes to the control window procedure when creating the control. Creation data is useful for controls that require more information about their initial content or style than is given by other data. For example, an application can use creation data to set the initial setting and range for a scroll bar control.

System Menu

Windows gives a dialog box a System menu when the template specifies the WS_SYSMENU style. To prevent inappropriate command input, Windows automatically disables all commands in the menu except the Move and Close commands. The user can use the Move command to move the dialog box. When the user chooses the Close command, Windows sends a WM_COMMAND message to the dialog box procedure with the wParam parameter set to IDCANCEL. This is identical to the message sent by the Cancel button when the user chooses it. The recommended action for this message is to close the dialog box and cancel the requested command or task.

Although other menus in dialog boxes are not recommended, a dialog box template can specify a menu by supplying the identifier or the name of a menu resource. In this case, Windows loads the resource and creates the menu for the dialog box. Applications typically use menu identifiers or names in templates when using the templates to create custom windows rather than dialog boxes.

Fonts

Windows draws all text in dialog box using the system font by default. An application can direct Windows to use another font by setting the DS_SETFONT style for the dialog box and specifying a point size and typeface name. Although a dialog box template can specify a font, Windows always uses the system font for the title and menus of the dialog box; the DS_SETFONT style does not change this.

When the DS_SETFONT style is specified, the system sends a WM_SETFONT message to the dialog box procedure and to each control as it creates the control. The dialog box procedure is responsible for saving the font handle passed with the WM_SETFONT message and selecting the handle into the display device context whenever it writes text to the window. Predefined controls do this by default.

When the DS_SETFONT style is given, Windows uses the average character width of the font to calculate the position and dimensions of the dialog box. Otherwise, it uses the average character width of the system font.

Templates in Memory

A template in memory consists of a DLGTEMPLATE structure and related data followed by one or more DLGITEMTEMPLATE structures and related data. There is one DLGITEMTEMPLATE structure for each control in the dialog box.

The DLGTEMPLATE structure specifies the position, width, height, style, and number of controls in the dialog box. Additional data following the structure specifies the optional menu, class, title, and font for the dialog box. The DLGTEMPLATE structure has the following form.

typedef struct { /* dltt */

    DWORD style;

    DWORD dwExtendedStyle;

    WORD  cdit;

    WORD  x;

    WORD  y;

    WORD  cx;

    WORD  cy;

} DLGTEMPLATE;

The style member specifies the window and dialog box styles for the dialog box. Windows does not use the dwExtendedStyle member when creating a dialog box. An application that uses templates to create other types of windows can use this member to specify extended window styles for the other windows. The x and y members specify the dialog box position; cx and cy specify the width and height. The cdit member specifies the number of controls in the dialog box and is the same as the number of DLGITEMTEMPLATE structures in the template.

The DLGTEMPLATE structure is immediately followed by a 16-bit value that specifies whether the dialog box has a menu. When the value is 0x0000, the dialog box has no menu. When the value is 0xFFFF, the subsequent 16-bit value specifies the identifier of the menu resource that describes the dialog box's menu. When the initial value is neither 0x0000 nor 0xFFFF, Windows assumes it is the start of a null-terminated string specifying the name of the menu resource that describes the dialog box's menu.

The first 16-bit value following the menu identifier or name specifies the window class to which the dialog box belongs. When the value is 0x0000, Windows uses the predefined dialog box class for the dialog box. When the value is 0xFFFF, the subsequent 16-bit value is an atom value identifying a registered window class. When the initial value is neither 0x0000 nor 0xFFFF, Windows assumes it is the start of a null-terminated string identifying a registered window class.

The dialog box title immediately follows the class atom or name. The title is a null-terminated string. When the string is empty, Windows leaves the title bar for the dialog box blank. When the dialog box does not have the WS_CAPTION style, Windows sets the title to the given string but does not display it.

When the dialog box has the DS_SETFONT style, the dialog box title is immediately followed by a 16-bit value specifying the point size and by a null-terminated string specifying the typeface for the font. Windows uses this data to create a font for use when writing text in the dialog box client area and in each control. When the dialog box does not have the DS_SETFONT style, the 16-bit value and string are not part of the template.

Each DLGITEMTEMPLATE structure in the template contains data specifying the position, width, height, style, and identifier of the control. Additional information follows each structure, specifying the window class to which the control belongs, the initial text for the control, and any other creation data needed to create the control. A DLGITEMTEMPLATE structure has the following form:

typedef struct { /* dlit */

    DWORD style;

    DWORD dwExtendedStyle;

    WORD  x;

    WORD  y;

    WORD  cx;

    WORD  cy;

    WORD  id;

} DLGITEMTEMPLATE;

The style member specifies the control style. This member is a combination of window-style flags, such as BS_PUSHBUTTON and WS_VISIBLE. Windows does not use the dwExtendedStyle member to create controls for dialog boxes. Applications that use templates to create other types of windows can use this member to specify extended window styles for those controls. The x and y members specify the coordinates of the upper-left corner of the control; cx and cy specify the width and height of the control. The id member is the control identifier.

The control's window class is specified by an atom or name immediately following the DLGITEMTEMPLATE structure. When the first 16-bit value after the structure is 0xFFFF, the subsequent 16-bit value is an atom value identifying a registered window class. Otherwise, the first value is the start of a null-terminated string specifying the name of a registered window class.

The control text starts on the first 16-bit boundary after the class atom or name. This text is either two 16-bit values specifying a resource identifier or a null- terminated string specifying the initial text for the control. If this member is a resource identifier, the first 16-bit value is 0xFFFF and the second is the identifier. Resource identifiers are usually given for controls, such as static icon controls, that load and display icons or other resources rather than displaying text.

Any additional creation data required by the control follows the control text. Windows passes this data to the control as the creation parameters when it calls the CreateWindowEx function.


Dialog Box Procedure

A dialog box procedure is similar to a window procedure in that Windows sends messages to the procedure when it has information to give or tasks to carry out. Unlike a window procedure, a dialog box procedure never calls the DefWindowProc function. Instead, it returns the Boolean value TRUE if it processes a message or FALSE if it does not.

Every dialog box procedure has the following form:

BOOL APIENTRY DlgProc(hwndDlg, message, wParam, lParam)

HWND hwndDlg;

UINT message;

WPARAM wParam;

LPARAM lParam;

{

    switch (message) {

        /* Place message cases here. */

        default:

            return FALSE;

    }

}

The procedure parameters serve the same purpose as in a window procedure, with the hwndDlg parameter receiving the window handle of the dialog box.

Most dialog box procedures process the WM_INITDIALOG message and the WM_COMMAND messages sent by the controls, but process few if any other messages. If a dialog box procedure does not process a message, it must return FALSE to direct Windows to process the messages internally. The only exception to this rule is the WM_INITDIALOG message. The dialog box procedure must return TRUE to direct Windows to further process the WM_INITDIALOG message. In any case, the procedure must not call DefWindowProc.

The WM_INITDIALOG Message

Windows does not send a WM_CREATE message to the dialog box procedure. Instead it sends a WM_INITDIALOG message when it creates the dialog box and all its controls, but before it displays the dialog box. The procedure should carry out any initialization required to ensure that the dialog box displays the current settings associated with the command or task. For example, when a dialog box contains a control to show the current drive and directory, the procedure must determine the current drive and directory and set the control to that value.

The procedure can initialize controls by using functions such as SetDlgItemText and CheckDlgButton. Because controls are windows, the procedure can also manipulate them by using window-management functions such as EnableWindow and SetFocus. The procedure can retrieve the window handle for a control by using the GetDlgItem function.

The dialog box procedure can change the contents, state, and position of any control as needed. For example, in a dialog box that contains a list box of filenames and an Open button, the procedure can disable the Open button until the user selects a file from the list. In this example, the dialog box template specifies the WS_DISABLED style for the Open button and Windows automatically disables the button when creating it. When the dialog box procedure receives a notification message from the list box indicating that the user has selected a file, the procedure calls the EnableWindow function to enable the Open button.

If the application creates the dialog box by using the DialogBoxParam, DialogBoxIndirectParam, CreateDialogParam, or CreateDialogIndirectParam function, the lParam parameter for the WM_INITDIALOG message contains the extra parameter passed to the function. Applications typically use this extra parameter to pass the address of additional initialization information to the dialog box procedure, but the dialog box procedure must determine the meaning of the parameter. If the application uses another function to create the dialog box, Windows sets the lParam parameter to NULL.

Before returning from the WM_INITDIALOG message, the procedure should determine whether it should set the input focus to a given control. If the dialog box procedure returns TRUE, Windows automatically sets the input focus to the control whose window handle is in the wParam parameter. If the control receiving the default focus is not appropriate, it can set the focus to the appropriate control by using the SetFocus function. If the procedure sets the input focus, it must return FALSE to prevent Windows from setting the default focus. The control receiving the default input focus is always the first control given in the template that is visible, not disabled, and has the WS_TABSTOP style. If no such control exists, Windows sets the default input focus to the first control in the template.

The WM_COMMAND Message

A control can send a WM_COMMAND message to the dialog box procedure when the user carries out an action in the control. These messages, called notification messages, inform the procedure of user input and permit it to carry out appropriate responses.

All predefined controls, except static controls, send notification messages for selected user actions. For example, a push button sends the BN_CLICKED notification message whenever the user chooses the button. In all cases, the low word of the wParam parameter contains the control identifier, the high word of wParam contains the notification code, and the lParam parameter contains the control window handle.

Portability Issue:	In Windows NT, the placement of the notification code has moved from the lParam parameter to the wParam parameter. When porting your Windows 3.x-applications to Windows NT, modify the code that processes notification messages to accommodate this change in placement.

The dialog box procedure should monitor and process notification messages. In particular, the procedure must process messages having the IDOK or IDCANCEL identifiers; these messages represent a request by the user to close the dialog box. The procedure should close the dialog box by using the EndDialog function for modal dialog boxes and the DestroyWindow function for modeless dialog boxes.

Windows also sends WM_COMMAND messages to the dialog box procedure if the dialog box has a menu, such as the System menu, and the user chooses a command. In particular, Windows sends a WM_COMMAND message with the wParam parameter set to IDCANCEL whenever the user chooses the Close command in the dialog box's System menu. The message is nearly identical to the notification message sent by the Cancel button and should be processed in exactly the same way.

The WM_NOTIFYPARENT Message

A control sends a WM_PARENTNOTIFY message whenever the user presses a mouse button while pointing to the control. Some applications interpret this message as a signal to carry out an action related to the control, such as displaying a line of text describing to purpose of the control.

Ordinarily, Windows also sends WM_PARENTNOTIFY messages when it creates and destroys a window, but not for controls created from a dialog box template. Windows prevents these messages by specifying the WS_EX_NOPARENTNOTIFY style when creating the controls. An application cannot override this default behavior unless it creates its own controls for the dialog box.

The Control-Color Messages

Controls and Windows can send control-color messages when they want the dialog box procedure to paint the background of a control or other window by using a specific brush and colors. This can be useful when applications override the default colors used in dialog boxes and their controls. Following are the control-color messages.

WM_CTLCOLORBTN

WM_CTLCOLORDLG

WM_CTLCOLOREDIT

WM_CTLCOLORLISTBOX

WM_CTLCOLORSCROLLBAR

WM_CTLCOLORSTATIC

A control sends a control-color message to the dialog box procedure just before it paints its own background. The message allows the procedure to specify which brush to use and to set the background and foreground colors. The procedure specifies a brush by returning the brush handle. To set the background and foreground colors, the procedure uses the SetBkColor and SetTextColor functions with the control's display device context. The control-color message passes a handle of the display device context to the procedure in the message's wParam parameter.

Windows sends a WM_CTLCOLORDLG message to the dialog box procedure if the dialog procedure does not process the WM_ERASEBKGND message. The predefined dialog box class does not have a class background brush, so this message lets the procedure define its own background without having to include the code to carry out the work.

In any case, when a dialog box procedure does not process a control-color message, Windows uses a brush with the default window color to paint the background for all controls and windows except scroll bars. An application can retrieve the default window color by passing the COLOR_WINDOW value to the GetSysColor function. While the background is painted, the foreground color for the display device context is set to the default text color (COLOR_WINDOWTEXT). For scroll bars, Windows uses a brush having the default scroll bar color (COLOR_SCROLLBAR). In this case, the background and foreground colors for the display device context are set to white and black, respectively.

Portability Issue:	In Windows NT, the WM_CTLCOLOR message has been replaced by the set of control-color messages. When porting your Windows 3.x-based application to Windows NT, remember to modify the code to accommodate this change.

Default Message Processing

The window procedure for the predefined dialog box class carries out default processing for all messages that the dialog box procedure does not process. When the dialog box procedure returns FALSE for any message, the predefined window procedure checks the messages and carries out the following default actions:

Message	Default action

DM_GETDEFID	Returns the control identifier of the default push button if it exists. Otherwise, return zero.

DM_SETDEFID	Sets the control specified by the control identifier in the wParam parameter to the default push button.

WM_ACTIVATE	Restores the input focus to the control identified by the previously saved handle if the dialog box is activated. Otherwise, the procedure saves the handle of the control having the input focus.

WM_CHARTOITEM	Returns zero.

WM_CLOSE	Posts the BN_CLICKED notification message to the dialog box, specifying IDCANCEL as the control identifier. If the dialog box has an IDCANCEL control identifier and the control is currently disabled, the procedure sounds a warning and does not post the message.

WM_COMPAREITEM	Returns zero.

WM_ERASEBKGND	Fills the dialog box client area using the brush returned from the WM_CTLCOLORDLG message or with the default window color.

WM_GETFONT	Returns the handle of the application-defined dialog box font.

WM_INITDIALOG	Returns zero.

WM_LBUTTONDOWN	Sends a CB_SHOWDROPDOWN message to the combo box having the input focus, directing the control to hide its dropdown list box. The procedure calls the DefWindowProc function to complete the default action.

WM_NCDESTROY	Releases global memory allocated for edit controls in the dialog box (applies to dialog boxes in Windows 3.x applications that specify the DS_LOCALEDIT style) and frees any application-defined font (applies to dialog boxes that specify the DS_SETFONT style). The procedure calls the DefWindowProc function to complete the default action.

WM_NCLBUTTONDOWN	Sends a CB_SHOWDROPDOWN message to the combo box having the input focus, directing the control to hide its dropdown list box. The procedure calls the DefWindowProc function to complete the default action.

WM_NEXTDLGCTL	Sets the input focus to the next or previous control in the dialog box, or sets the focus to the control identified by the handle in the wParam parameter, or sets the focus to the first control in the dialog box that is visible, not disabled, and has the WS_TABSTOP style. The procedure ignores this message if the current window with the input focus is not a control.

WM_SETFOCUS	Sets the input focus to the control identified by a previously saved control window handle. If no such handle exists, the procedure sets the input focus to the first control in the dialog box template that is visible, not disabled, and has the WS_TABSTOP style. If no such control exists, the procedure sets the input focus to the first control in the template.

WM_SHOWWINDOW	Saves the handle of the control having the input focus if the dialog box is being hidden, then calls the DefWindowProc function to complete the default action.

WM_SYSCOMMAND	Saves the handle of the control having the input focus if the dialog box is being minimized, then calls the DefWindowProc function to complete the default action.

WM_VKEYTOITEM	Returns zero.

The predefined window procedure passes all other messages to the DefWindowProc function for default processing.


Dialog Box Keyboard Interface

Windows provides a special keyboard interface for dialog boxes that carries out special processing for several keys. The interface generates messages that correspond to certain buttons in the dialog box or changes the input focus from one control to another. Following are the keys used in this interface and the respective actions.

Key	Action

ALT+mnemonic	Moves the input focus to the first control (having the WS_TABSTOP style) after the static control containing the given mnemonic.

DOWN	Moves the input focus to the next control in the group.

ENTER	Sends a WM_COMMAND message to the dialog box procedure. The wParam parameter is set to IDOK or control identifier of the default push button.

ESC	Sends a WM_COMMAND message to the dialog box procedure. The wParam parameter is set to IDCANCEL.

LEFT	Moves the input focus to the previous control in the group.

mnemonic	Moves the input focus to the first control (having the WS_TABSTOP style) after the static control containing the given mnemonic.

RIGHT	Moves the input focus to the next control in the group.

SHIFT+TAB	Moves the input focus to the previous control that has the WS_TABSTOP style.

TAB	Moves the input focus to the next control that has the WS_TABSTOP style.

UP	Moves the input focus to the previous control in the group.

The Win32 application programming interface (API) automatically provides the keyboard interface for all modal dialog boxes. It does not provide the interface for modeless dialog boxes unless the application calls the IsDialogMessage function to filter messages in its main message loop. This means that the application must pass the message to IsDialogMessage immediately after retrieving the message from the message queue. The function processes the messages if it is for the dialog box and returns a nonzero value to indicate that the message has been processed and must not be passed to the TranslateMessage or DispatchMessage function.

Because the dialog box keyboard interface uses direction keys to move between controls in a dialog box, an application cannot use these keys to scroll the contents of any modal dialog box or any modeless dialog box for which the IsDialogMessage function is called. When a dialog box has scroll bars, the application must provide an alternate keyboard interface for the scroll bars. Note that the mouse interface for scrolling is available when the system includes a mouse.

The WS_TABSTOP Style

The TAB key and SHIFT+TAB keys have no effect when the controls in the dialog box do not have the WS_TABSTOP style. Windows looks for these styles as it searches for the next control in the dialog box to receive the input focus.

When the user presses TAB or SHIFT+TAB, Windows first determines whether the control having the input focus processes these keys. It sends a WM_GETDLGCODE message to the control, and if the control returns the DLGC_WANTTAB value, Windows passes the keys to the control. Otherwise, Windows uses the GetNextDlgTabItem function to locate the next control that is visible, not disabled, and has the WS_TABSTOP style. The search starts with the control currently having the input focus and proceeds in the order in which the controls were created--that is, the order in which they are defined in the dialog box template. When the system locates a control having the required characteristics, Windows moves the input focus to it.

An application can also use GetNextDlgTabItem to locate controls having the WS_TABSTOP style. The function retrieves the window handle of the next or previous control having the WS_TABSTOP style without moving the input focus.

The WS_GROUP Style

By default, Windows moves the input focus to the next or previous control whenever the user presses a direction key. As long as the current control with the input focus does not process these keys and the next or previous control is not a static control, Windows continues to move the input focus through all controls in the dialog box as the user continues to press the direction keys.

An application can use the WS_GROUP style to modify this default behavior. The style marks the beginning of a group of controls. If a control in the group has the input focus when the user begins pressing direction keys, the focus remains in the group. In general, the first control in a group must have the WS_GROUP style and all other controls in the group must not have this style. All controls in the group must be contiguous; that is, they must have been created consecutively with no intervening controls.

When the user presses a direction key, Windows first determines whether the current control having the input focus processes the direction keys. Windows sends a WM_GETDLGCODE message to the control and if the control returns the DLGC_WANTARROWS value, passes the key to the control. Otherwise, Windows uses the GetNextDlgGroupItem function to determine the next control in the group.

The GetNextDlgGroupItem function searches controls in the order (or reverse order) they were created. If the user presses the RIGHT or DOWN keys, GetNextDlgGroupItem returns the next control if that control does not have WS_GROUP style. Otherwise, the function reverses the order of the search and returns the first control that has the WS_GROUP style. If the user presses the LEFT or UP keys, GetNextDlgGroupItem returns the previous control unless the current control already has the WS_GROUP style. If the current control has this style, the function reverses the order of the search, locates the first control having the WS_GROUP style, and returns the control that immediately precedes the located control.

Once Windows has the next or previous control, it sends a WM_GETDLGCODE message to the control to determine the control type. Windows then moves the input focus to control if it is not a static control. If the control is an automatic radio button, Windows sends a BM_CLICK message to it. An application can also use the GetNextDlgGroupItem function to locate controls in a group.

Generally, the first control in the group combines the WS_GROUP and WS_TABSTOP styles so that the user can move from group to group by using the TAB key. If the group contains radio buttons, the application should apply the WS_TABSTOP style only to the first control in the group. Windows automatically moves the style when the user moves between controls in the group. This ensures that the input focus will always be on the most recently selected control when the user moves to the group using the TAB key.

Mnemonics

A mnemonic is a selected letter or digit in the label of a button or in the text of a static control. Windows moves the input focus to the control associated with the mnemonic whenever the user either presses the key that corresponds to the mnemonic or presses this key and the ALT key in combination. Mnemonics provide a quick way for the user to move to a given control by using the keyboard.

An application creates a mnemonic for a control by inserting the ampersand (&) immediately before the selected letter or digit in the label or text for the control. In most cases, the null-terminated string provided with the control in the dialog box template contains the ampersand. However, an application can create a mnemonic at any time by replacing a control's existing label or text by using the SetDlgItemText function. Only one mnemonic can be given for each control. Although it is recommended, mnemonics in a dialog box need not be unique.

When the user presses a letter or digit key, Windows first determines whether the current control having the input focus processes the key. Windows sends a WM_GETDLGCODE message to the control, and if the control returns the DLGC_WANTALLKEYS or DLG_WANTMESSAGE values, Windows passes the key to the control. Otherwise, it searches for a control whose mnemonic matches the given letter or digit. It continues to search until it locates a control or has examined all controls. During the search, it skips any static controls that have the SS_NOPREFIX style.

If Windows locates a static control and the control is not disabled, Windows moves the input focus to the first control after the static control that is visible, not disabled, and that has the WS_TABSTOP style. If Windows locates some other control that has a matching mnemonic, it moves the input focus to that control. If the control is a default push button, Windows sends a BN_CLICKED notification message to the dialog box procedure. If the control is another style of button and there is no other control in the dialog box having the same mnemonic, Windows sends the BM_CLICK message to the control.


Dialog Box Settings

The dialog box settings are the current selections and values for the controls in the dialog box. The dialog box procedure is responsible for initializing the controls to these settings when creating the dialog box. It is also responsible for retrieving the current settings from the controls before destroying the dialog box. The methods used to initialize and retrieve settings depend on the type of control.

Radio Buttons and Check Boxes

Dialog boxes use radio buttons and check boxes to let the user choose from a list of options. Radio buttons let the user choose from mutually exclusive options; check boxes let the user pick a combination of options.

The dialog box procedure can set the initial state of a check box by using the CheckDlgButton function, which sets or clears the check box. For radio buttons in a group of mutually exclusive radio buttons, the dialog box procedure can use the CheckRadioButton function to set the appropriate radio button and automatically clear any other radio button.

Before a dialog box terminates, the dialog box procedure can check the state of each radio button and check box by using the IsDlgButtonChecked function, which returns the current state of the button. A dialog box typically saves this information to initialize the buttons the next time it creates the dialog box.

Edit Controls

Many dialog boxes have edit controls that let the user supply text as input. Most dialog box procedures initialize an edit control when the dialog box first starts. For example, the dialog box procedure may place a proposed filename in the control that the user can then select, modify, or replace. The dialog box procedure can set the text in an edit control by using the SetDlgItemText function, which copies text from a given buffer to the edit control. When the edit control receives the input focus, it automatically selects the complete text for editing.

Because edit controls do not automatically return their text to the dialog box, the dialog box procedure must retrieve the text before it terminates. It can retrieve the text by using the GetDlgItemText function, which copies the edit control text to a buffer. The dialog box procedure typically saves this text to initialize the edit control later or passes it on to the parent window for processing.

Some dialog boxes use edit controls that let the user enter numbers. The dialog box procedure can retrieve a number from an edit control by using the GetDlgItemInt function, which retrieves the text from the edit control and converts the text to a decimal value. The user types the number in decimal digits. It can be either signed or unsigned. The dialog box procedure can display an integer by using the SetDlgItemInt function. SetDlgItemInt converts a signed or unsigned integer to a string of decimal digits.

List Boxes, Combo Boxes, and Directory Listings

Some dialog boxes display lists of names from which the user can select one or more names. To display a list of filenames, for example, a dialog box typically uses a list box and the DlgDirList and DlgDirSelect functions. The DlgDirList function automatically fills a list box with the filenames in the current directory. The DlgDirSelect function retrieves the selected filename from the list box. Together, these two functions provide a convenient way for a dialog box to display a directory listing so the user can select a file without having to type the location and name of the file.

A dialog box can also use a combo box to display a list of filenames. The DlgDirListComboBox function automatically fills a list box portion of the combo box with the filenames in the current directory. The DlgDirSelectComboBox function retrieves the selected filename from the list box portion.

Control Messages

Many controls recognize predefined messages that, when received by controls, cause them to carry out some action. For example, the BM_SETCHECK message sets the check in a check box and the EM_GETSEL message retrieves the portion of the control's text that is currently selected. The control messages give a dialog procedure greater and more flexible access to the controls than the standard functions, so they are often used when the dialog box requires complex interactions with the user.

A dialog box procedure can send a message to a control by supplying the control identifier and using the SendDlgItemMessage function, which is identical to the SendMessage function, except that it uses a control identifier instead of a window handle to identify the control that is to receive the message. A given message may require that the dialog procedure send parameters with the message and the message may have corresponding return values. The operation and requirements of each control message depends on the purpose of the message and the control that processes it.


Custom Dialog Boxes

An application can create custom dialog boxes by using an application-defined window class for the dialog boxes instead of the predefined dialog box class. Applications typically use this method when a dialog box is their main window, but it is also useful for creating modal and modeless dialog boxes for applications that have standard overlapping windows.

The application-defined window class allows the application to define a window procedure for the dialog box and process messages before sending them to the dialog box procedure. It also lets the application define a class icon, class background brush, and a class menu for the dialog box. The application must register the window class before attempting to create a dialog box and must provide the dialog box template with the atom value or name of the window class.

Many applications create a new dialog box class by first retrieving the class information for the predefined dialog box class, and passing it to the GetClassInfo function, which fills a WNDCLASS structure with the information. The application modifies individual members of the structure, such as the class name, brush, and icon, then registers the new class by using the RegisterClass function. If an application fills the WNDCLASS structure on its own, it must set the cbWndExtra member to the value DLGWINDOWEXTRA, which is the number of extra bytes Windows requires for each dialog box. If an application also uses extra bytes for each dialog box, they must be beyond the extra bytes required by Windows.

The window procedure for the custom dialog box has the same parameters and requirements as any other window procedure. Unlike other window procedures, however, the window procedure for this dialog box should call the DefDlgProc function instead of the DefWindowProc function for any messages it does not process. DefDlgProc carries out the same default message processing as the window procedure for the predefined dialog box, which includes calling the dialog box procedure.

An application can also create custom dialog boxes by subclassing the window procedure of the predefined dialog box. The SetWindowLong function lets an application set the address of the window procedure for a given window. The application may also attempt to subclass by using the SetClassLong function, but doing so affects all dialog boxes in the system, not just those belonging to the application.

Applications that create custom dialog boxes sometimes provide an alternate keyboard interface for the dialog boxes. For modeless dialog boxes, this may mean the application does not call the IsDialogMessage function and instead processes all keyboard input in the custom window procedure. In such cases, the application can use the WM_NEXTDLGCTL message to minimize the code needed to move the input focus from one control to another. This message, when passed to the DefDlgProc function, moves the input focus to a specified control and updates the appearance of the controls, such as moving the default push button border or setting an automatic radio button.


Using Dialog Boxes

You use dialog boxes to display information and prompt for input from the user. Your application loads and initializes the dialog box, processes user input, and destroys the dialog box when the user finishes the task. The process for handling dialog boxes varies, depending on whether the dialog box is modal or modeless. A modal dialog box requires the user to close the dialog box before activating another window in the application. However, the user can activate windows in different applications. A modeless dialog box does not require an immediate response from the user. It is similar to a main window containing controls. The following sections discuss how to use both types of dialog boxes.


Displaying a Message Box

The simplest form of modal dialog box is the message box. Most applications use message boxes to warn the user of errors and to prompt for directions on how to proceed after an error. You create a message box by using the MessageBox function, specifying the message and the number and type of buttons to display. Windows creates a modal dialog box, providing its own dialog box template and procedure. After the user closes the message box, MessageBox returns a value identifying the button chosen by the user to close the message box.

In the following example, the application displays a message box if the fError variable is TRUE. The message box displays the message describing the error. The MB_OKCANCEL style directs MessageBox to provide two buttons with which the user can choose how to proceed.

if (fError) {

    if (MessageBox(hwndDlg, SZNOTFOUND, SZDELETEITEM,

        MB_OKCANCEL)==IDOK)

        .

        . /* Prompt for a new item name and repeat the command. */

        .

    else

        .

        . /* Cancel the command. */

        .

}

In this example, SZNOTFOUND and SZDELETEITEM are application-defined, null-terminated strings that represent the message text and the title for the message box.


Creating a Modal Dialog Box

You create a modal dialog box by using the DialogBox function. You must specify the identifier or name of a dialog box template resource and the address of the dialog box procedure. The DialogBox function loads the template, displays the dialog box, and processes all user input until the user closes the dialog box.

In the following example, the application displays a modal dialog box when the user chooses a Delete Item command from an application menu. The dialog box contains an edit control (in which the user enters the name of an item) and OK and Cancel buttons. The control identifiers for these controls are ID_ITEMNAME, IDOK, and IDCANCEL, respectively.

The first part of the example consists of the statements that create the modal dialog box. These statements, in the window procedure for the application's main window, create the dialog box when the system receives a WM_COMMAND message having the IDM_DELETEITEM command identifier. The second part of the example is the dialog box procedure. The procedure retrieves the contents of the edit control and closes the dialog box upon receiving a WM_COMMAND message.

The following statements create the modal dialog box. The dialog box template is a resource in the application's executable file and has the resource identifier DLG_DELETEITEM.

case WM_COMMAND:

    switch (LOWORD(wParam)) {

        case IDM_DELETEITEM:

            if (DialogBox(hinst, MAKEINTRESOURCE(DLG_DELETEITEM),

                 hwnd, (DLGPROC)DeleteItemProc)==IDOK)

                .

                . /*

                . * Complete the command; szItemName contains

                . * the name of the item to delete.

                . */

                .

             else

                .

                . /* Cancel the command. */

                .

        break;

    }

    return 0L;

In this example, the application identifies its main window as the owner window for the dialog box. When Windows initially displays the dialog box, its position is relative to the upper left corner of the owner window's client area. The application uses the return value from DialogBox to determine whether to proceed with the command or cancel it. The following statements define the dialog box procedure.

char szItemName[80]; /* receives name of item to delete. */

BOOL CALLBACK DeleteItemProc(hwndDlg, message, wParam, lParam)

HWND hwndDlg;

UINT message;

WPARAM wParam;

LPARAM lParam;

{

    switch (message) {

        case WM_COMMAND:

            switch (LOWORD(wParam)) {

                case IDOK:

                    if (!GetDlgItemText(hwndDlg, ID_ITEMNAME,

                             szItemName, 80))

                         *szItemName=0;

                    /* Fall through. */

                case IDCANCEL:

                    EndDialog(hwndDlg, wParam);

                    return TRUE;

            }

    }

    return FALSE;

}

In this example, the procedure uses the GetDlgItemText function to retrieve the current text from the edit control identified by ID_ITEMNAME. The procedure then calls the EndDialog function to set the dialog box's return value to either IDOK or IDCANCEL depending on message received and to begin the process of closing the dialog box. The IDOK and IDCANCEL identifiers correspond to the OK and Cancel buttons. After the procedure calls EndDialog, Windows sends additional messages to the procedure to destroy the dialog box and returns the dialog box's return value back to the function that created the dialog box.


Creating a Modeless Dialog Box

You create a modeless dialog box by using the CreateDialog function, specifying the identifier or name of a dialog box template resource and the address of the dialog box procedure. CreateDialog loads the loads the template, creates the dialog box, and optionally displays it. Your application is responsible for retrieving and dispatching user input messages to the dialog box procedure.

In the following example, the application displays a modeless dialog box--if it is not already displayed--when the user chooses a Go To command from an application menu. The dialog box contains an edit control, a check box, and OK and Cancel buttons. The dialog box template is a resource in the application's executable file and has the resource identifier DLG_GOTO. The user enters a line number in the edit control and checks the check box to specify that the line number is relative to the current line. The control identifiers are ID_LINE, ID_ABSREL, IDOK, and IDCANCEL.

The statements in the first part of the example create the modeless dialog box. These statements, in the window procedure for the application's main window, create the dialog box when the window procedure receives a WM_COMMAND message having the IDM_GOTO command identifier, but only if the global variable hwndGoto does not already contain a valid handle. The second part of the example is the application's main message loop. The loop includes the IsDialogMessage function to ensure that the user can use the dialog box keyboard interface in this modeless dialog box. The third part of the example is the dialog box procedure. The procedure retrieves the contents of the edit control and check box when the user chooses the OK button. The procedure destroys the dialog box when the user chooses the Cancel button.

HWND hwndGoto = NULL;  /* window handle of dialog box */

    .

    .

    .

    case WM_COMMAND:

        switch (LOWORD(wParam)) {

            case IDM_GOTO:

                if (!IsWindow(hwndGoto)) {

                    hwndGoto = CreateDialog(hinst,

                         MAKEINTRESOURCE(DLG_GOTO),

                         hwnd, (DLGPROC) GoToProc);

                    ShowWindow(hwndGoto, SW_SHOW);

                }

                break;

        }

        return 0L;

In the preceding statements, the CreateDialog function is called only if the hwndGoto variable does not contain a valid window handle. This ensures that the application does not display two dialog boxes at the same time. To support this method of checking, the dialog procedure must set the hwndGoto variable to NULL when it destroys the dialog box.

The message loop for an application consists of the following statements.

while (GetMessage(&msg, NULL, NULL, NULL)) {

    if (!IsWindow(hwndGoto) || !IsDialogMessage(hwndGoto, &msg)) {

        TranslateMessage(&msg);

        DispatchMessage(&msg);

    }

}

The loop checks the validity of the window handle for the dialog box and only calls the IsDialogMessage function if the handle is valid. IsDialogMessage only processes the message if it belongs to the dialog box. Otherwise, it returns FALSE and the loop dispatches the message to the appropriate window.

The following statements define the dialog box procedure.

int iLine;             /* receives line number      */

BOOL fRelative;        /* receives check box status */

    .

    .

    .

BOOL CALLBACK GoToProc(hwndDlg, message, wParam, lParam)

HWND hwndDlg;

UINT message;

WPARAM wParam;

LPARAM lParam;

{

    BOOL fError;

    switch (message) {

        case WM_INITDIALOG:

            CheckDlgButton(hwndDlg, ID_ABSREL, fRelative);

            return TRUE;

        case WM_COMMAND:

            switch (LOWORD(wParam)) {

                case IDOK:

                    fRelative = IsDlgButtonChecked(hwndDlg, ID_ABSREL);

                    iLine = GetDlgItemInt(hwndDlg, ID_LINE, &fError,

                        fRelative);

                    if (fError) {

                        MessageBox(hwndDlg, SZINVALIDNUMBER,

                            SZGOTOERR, MB_OK);

                        SendDlgItemMessage(hwndDlg, ID_LINE,

                            EM_SETSEL, 0, -1L);

                    } else

                        .

                        . /*

                        . * Notify the owner window to carry out the

                        . * command.

                        . */

                        .

                    return TRUE;

                case IDCANCEL:

                    DestroyWindow(hwndDlg);

                    hwndGoto = NULL;

                    return TRUE;

            }

    }

    return FALSE;

}

In the preceding statements, the procedure processes the WM_INITDIALOG and WM_COMMAND messages. During WM_INITDIALOG processing, the procedure initializes the check box by passing the current value of the global variable fRelative to the CheckDlgButton function. The procedure then returns TRUE to direct Windows to set the default input focus.

During WM_COMMAND processing, the procedure closes the dialog box only if the user chooses the Cancel button--that is, the button having the IDCANCEL identifier. The procedure must call the DestroyWindow function to close a modeless dialog box. Notice that the procedure also sets the hwndGoto variable to NULL to ensure that other statements that depend on this variable operate correctly.

If the user chooses the OK button, the procedure retrieves the current state of the check box and assigns it to the fRelative variable. It then uses the variable to retrieve the line number from the edit control. The GetDlgItemInt function translates the text in the edit control into a integer number. The value of fRelative determines whether the function interprets the number as a signed or unsigned value. If the edit control text is not a valid number, GetDlgItemInt sets the value of the fError variable to nonzero. The procedure checks this value to determine whether to display an error message or carry out the command. Notice that on an error, the dialog box procedure sends a message to the edit control, directing it to select the text in the control so that the user can easily replace it. If the GetDlgItemInt function does not return an error, the procedure can either carry out the requested command itself or send a message to the owner window, directing it to carry out the command.


Initializing a Dialog Box

You initialize the dialog box and its contents while processing the WM_INITDIALOG message. The most common task is to initialize the controls to reflect the current dialog box settings. Another common task is to center a dialog box on the screen or within its owner window. Finally, a useful task for some dialog boxes is to set the input focus to a given control rather than accept the default input focus.

In the following example, the dialog box procedure centers the dialog box and sets the input focus while processing the WM_INITDIALOG message. To center the dialog box, the procedure retrieves the window rectangles for the dialog box and the owner window and calculates a new position for the dialog box. To set the input focus, the procedure checks the wParam parameter to determine the identifier of the default input focus:

HWND hwndOwner;

RECT rc, rcDlg, rcOwner;

    case WM_INITDIALOG:

        /* Get the owner window and dialog box rectangles. */

        if ((hwndOwner = GetParent(hwndDlg)) == NULL)

            hwndOwner = GetDesktopWindow();

        GetWindowRect(hwndOwner, &rcOwner);

        GetWindowRect(hwndDlg, &rcDlg);

        CopyRect(&rc, &rcOwner);

        /*

         * Offset the owner and dialog box rectangles so that

         * right and bottom values represent the width and

         * height, and then offset the owner again to discard

         * space taken up by the dialog box.

         */

        OffsetRect(&rcDlg, -rcDlg.left, -rcDlg.top);

        OffsetRect(&rc, -rc.left, -rc.top);

        OffsetRect(&rc, -rcDlg.right, -rcDlg.bottom);

        /*

         * The new position is the sum of half the remaining

         * space and the owner's original position.

         */

        SetWindowPos(hwndDlg,

            HWND_TOP,

            rcOwner.left + (rc.right / 2),

            rcOwner.top + (rc.bottom / 2),

            0, 0,          /* ignores size arguments */

            SWP_NOSIZE);

        if (GetDlgCtrlID((HWND) wParam) != ID_ITEMNAME) {

            SetFocus(GetDlgItem(hwndDlg, ID_ITEMNAME));

            return FALSE;

        }

        return TRUE;

In the preceding statements, the procedure uses the GetParent function to retrieve the owner window handle for a dialog box. The function returns the owner window handle for dialog boxes, and the parent window handle for child windows. Because an application can create a dialog box that has no owner, the procedure checks the returned handle and uses the GetDesktopWindow function to retrieve the desktop window handle, if necessary. After calculating the new position, the procedure uses the SetWindowPos function to move the dialog box, specifying the HWND_TOP value to ensure that the dialog box remains on top of the owner window.

Before setting the input focus, the procedure checks the control identifier of the default input focus. Windows passes the window handle of the default input focus in the wParam parameter. The GetDlgCtrlID function returns the control identifier for the control identified by the window handle. If the identifier does not match the correct identifier, the procedure uses the SetFocus function to set the input focus. The GetDlgItem function is required to retrieve the window handle of the desired control.


Creating a Template in Memory

Applications sometimes adapt or modify the content of dialog boxes depending on the current state of the data being processed. In such cases, it is not practical to provide all possible dialog box templates as resources in the application's executable file. But creating templates in memory gives the application more flexibility to adapt to any circumstances.

In the following example, the application creates a template in memory for a modal dialog box that contains a message and OK and Help buttons:

LRESULT DisplayMyMessage(HINSTANCE hinst, HWND hwndOwner, LPSTR lpszMessage)

{

    HGLOBAL hgbl;

    LPDLGTEMPLATE lpdt;

    LPDLGITEMTEMPLATE lpdit;

    LPWORD lpw;

    LPWSTR lpwsz;

    LRESULT ret;

    hgbl = GlobalAlloc(GMEM_ZEROINIT, 1024);

    if (!hgbl)

        return -1;

    lpdt = (LPDLGTEMPLATE)GlobalLock(hgbl);

    /* Define a dialog box. */

    lpdt->style = WS_POPUP | WS_BORDER | WS_SYSMENU

        | DS_MODALFRAME | WS_CAPTION;

    lpdt->cdit = 3; /* number of controls */

    lpdt->cdit = 1;

    lpdt->x  = 10;  lpdt->y  = 10;

    lpdt->cx = 100; lpdt->cy = 100;

    lpw = (LPWORD) (lpdt + 1);

    *lpw++ = 0;   /* no menu */

    *lpw++ = 0;   /* predefined dialog box class (by default) */

    lpwsz = (LPWSTR)  lpw;

    lstrcpyW(lpwsz, L"My Message"); /* dialog box title (Unicode) */

    lpw = (LPWORD) (lpwsz + lstrlenW(lpwsz) + 1);

    /* Define an OK button. */

    lpdit = (LPDLGITEMTEMPLATE) lpw;

    lpdit->x  = 10; lpdit->y  = 10;

    lpdit->cx = 40; lpdit->cy = 20;

    lpdit->id = IDOK;  /* OK button identifier */

    lpdit->style = WS_CHILD | WS_VISIBLE | BS_DEFPUSHBUTTON;

    lpw = (LPWORD) (lpdit + 1);

    *lpw++ = 0xFFFF;

    *lpw++ = 0x0080;    /* button class */

    lpwsz = (LPWSTR) lpw;

    lstrcpyW(lpwsz, L"OK"); /* button label (Unicode) */

    lpw = (LPWORD) (lpwsz + lstrlenW(lpwsz) + 1);

    *lpw++ = 0;             /* no creation data */

    /* Define a Help button. */

    lpdit = (LPDLGITEMTEMPLATE) lpw;

    lpdit->x  = 55; lpdit->y  = 10;

    lpdit->cx = 40; lpdit->cy = 20;

    lpdit->id = ID_HELP;    /* help button identifier */

    lpdit->style = WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON;

    lpw = (LPWORD) (lpdit + 1);

    *lpw++ = 0xFFFF;

    *lpw++ = 0x0080;                 /* button class atom */

    lpwsz = (LPWSTR) lpw;

    lstrcpyW(lpwsz, L"Help");        /* button label (Unicode) */

    lpw = (LPWORD) (lpwsz + lstrlenW(lpwsz) + 1);

    *lpw++ = 0;                      /* no creation data */

    /* Define a static text control. */

    lpdit = (LPDLGITEMTEMPLATE) lpw;

    lpdit->x  = 55; lpdit->y  = 10;

    lpdit->cx = 40; lpdit->cy = 20;

    lpdit->id = ID_TEXT;  /* text identifier */

    lpdit->style = WS_CHILD | WS_VISIBLE | SS_LEFT;

    lpw = (LPWORD) (lpdit + 1);

    *lpw++ = 0xFFFF;

    *lpw++ = 0x0082;                        /* static class */

    for (lpwsz = (LPWSTR) lpw;

         *lpwsz++ = (WCHAR) *lpszMessage++;  /* message (Unicode) */

         );

    lpw = (LPWORD) lpwsz;

    *lpw++ = 0;                             /* no creation data */

    GlobalUnlock(hgbl);

    ret = DialogBoxIndirect(hinst, (LPDLGTEMPLATE) hgbl,

        hwndOwner, (DLGPROC) DialogProc);

    GlobalFree(hgbl);

    return ret;

}


Functions and Messages

Following are the functions and messages used to create and manage dialog boxes and controls within dialog boxes.

CreateDialog

CreateDialogIndirect

CreateDialogIndirectParam

CreateDialogParam

DefDlgProc

DialogBox

DialogBoxIndirect

DialogBoxIndirectParam

DialogBoxParam

DialogProc

EndDialog

GetDialogBaseUnits

GetDlgCtrlID

GetDlgItem

GetDlgItemInt

GetDlgItemText

GetNextDlgGroupItem

GetNextDlgTabItem

IsDialogMessage

MapDialogRect

MessageBox

MessageBoxEx

SendDlgItemMessage

SetDlgItemInt

SetDlgItemText

WM_CTLCOLORMSGBOX

WM_ENTERIDLE

WM_GETDLGCODE

WM_INITDIALOG

WM_NEXTDLGCTL


Rectangles Overview

About Rectangles

Applications written for Microsoft® Windows™ use rectangles to specify rectangular areas on the screen or in a window. Rectangles are used for the cursor clipping region, the invalid portion of the client area, an area for displaying formatted text, or the scroll area. Your applications can also use rectangles to fill, frame, or invert a portion of the client area with a given brush, and to retrieve the coordinates of a window or a window's client area.

The following topics discuss rectangles in Win32:

Rectangle Coordinates

Rectangle Operations

Using Rectangles

Functions


Rectangle Coordinates

An application must use a RECT structure to define a rectangle. The structure specifies the coordinates of two points: the upper left and lower right corners of the rectangle. The sides of the rectangle extend from these two points and are parallel to the x- and y-axes.

The coordinate values for a rectangle are expressed as signed integers. The coordinate value of a rectangle's right side must be greater than that of its left side. Likewise, the coordinate value of the bottom must be greater than that of the top.

Because applications can use rectangles for many different purposes, the Windows rectangle functions do not use an explicit unit of measure. Instead, all rectangle coordinates and dimensions are given in signed, logical values. The mapping mode and the function in which the rectangle is used determine the units of measure.


Rectangle Operations

The Microsoft Win32™ application programming interface (API) provides several functions for working with rectangles.

The SetRect function creates a rectangle, the CopyRect function makes a copy of a given rectangle, and the SetRectEmpty function creates an empty rectangle. An empty rectangle is any rectangle that has zero width, zero height, or both. The IsRectEmpty function determines whether a given rectangle is empty. The EqualRect function determines whether two rectangles are identical--that is, whether they have the same coordinates.

The InflateRect function increases or decreases the width or height of a rectangle, or both. It can add or remove width from both ends of the rectangle; it can add or remove height from both the top and bottom of the rectangle.

The OffsetRect function moves a rectangle by a given amount. It moves the rectangle by adding the given x-amount, y-amount, or x- and y-amounts to the corner coordinates.

The PtInRect function determines whether a given point lies within a given rectangle. The point is in the rectangle if it lies on the left or top side or is completely within the rectangle. The point is not in the rectangle if it lies on the right or bottom side.

The IntersectRect function creates a new rectangle that is the intersection of two existing rectangles, as shown in the following figure.

The UnionRect function creates a new rectangle that is the union of two existing rectangles, as shown in the following figure.


Using Rectangles

The example in this section illustrates how to use the rectangle functions. It consists of the main window procedure from an application that enables the user to move and size a bitmap.

When the application starts, it draws a 32-pixel by 32-pixel bitmap in the upper left corner of the screen. The user can move the bitmap by dragging it. To size the bitmap, the user creates a target rectangle by dragging the mouse, then drags the bitmap and "drops" it on the target rectangle. The application responds by copying the bitmap into the target rectangle.

The following illustration shows the target rectangle as it is being drawn.

The following illustration shows the bitmap being dragged to the target rectangle.

Finally, the following illustration shows the bitmap after it has been dropped on the target rectangle.

The window procedure that allows the user to move and size the bitmap is given in the following example.

LRESULT CALLBACK MainWndProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;      /* handle of window         */

UINT uMsg;      /* message                  */

WPARAM wParam;  /* first message parameter  */

LPARAM lParam;  /* second message parameter */

{

    HDC hdc;                 /* device context (DC) for window   */

    RECT rcTmp;              /* temporary rectangle              */

    PAINTSTRUCT ps;          /* paint data for Begin/EndPaint    */

    POINT ptClientUL;        /* client area upper left corner    */

    POINT ptClientLR;        /* client area lower right corner   */

    static HDC hdcCompat;    /* DC for copying bitmap            */

    static POINT pt;         /* x and y coordinates of cursor    */

    static RECT rcBmp;       /* rectangle that encloses bitmap   */

    static RECT rcTarget;    /* rectangle to receive bitmap      */

    static RECT rcClient;    /* client-area rectangle            */

    static BOOL fDragRect;   /* TRUE if bitmap rect. is dragged  */

    static HBITMAP hbmp;     /* handle of bitmap to display      */

    static HBRUSH hbrBkgnd;  /* handle of background-color brush */

    static COLORREF crBkgnd; /* color of client-area background  */

    static HPEN hpenDot;     /* handle of dotted pen             */

    switch (uMsg) {

        case WM_CREATE:

            /* Load the bitmap resource. */

            hbmp = LoadBitmap(hinst, MAKEINTRESOURCE(1));

            /*

             * Create a device context (DC) to hold the bitmap.

             * The bitmap is copied from this DC to the window's DC

             * whenever it must be drawn.

             */

            hdc = GetDC(hwnd);

            hdcCompat = CreateCompatibleDC(hdc);

            SelectObject(hdcCompat, hbmp);

            /*

             * Create a brush of the same color as the background

             * of the client area. The brush is used later to erase

             * the old bitmap before copying the bitmap into the

             * target rectangle.

             */

            crBkgnd = GetBkColor(hdc);

            hbrBkgnd = CreateSolidBrush(crBkgnd);

            ReleaseDC(hwnd, hdc);

            /*

             * Create a dotted pen. The pen is used to draw the

             * bitmap rectangle as the user drags it.

             */

            hpenDot = CreatePen(PS_DOT, 1, RGB(0, 0, 0));

            /*

             * Set the initial rectangle for the bitmap. Note that

             * this application supports only a 32- by 32-pixel

             * bitmap. The rectangle is slightly larger than the

             * bitmap.

             */

            SetRect(&rcBmp, 1, 1, 34, 34);

            return 0;

        case WM_PAINT:

            /*

             * Draw the bitmap rectangle and copy the bitmap into

             * it. The 32-pixel by 32-pixel bitmap is centered

             * in the rectangle by adding 1 to the left and top

             * coordinates of the bitmap rectangle, and subtracting

             * 2 from the right and bottom coordinates.

             */

            BeginPaint(hwnd, &ps);

            Rectangle(ps.hdc, rcBmp.left, rcBmp.top,

                rcBmp.right, rcBmp.bottom);

            StretchBlt(ps.hdc, rcBmp.left + 1, rcBmp.top + 1,

                (rcBmp.right - rcBmp.left) - 2,

                (rcBmp.bottom - rcBmp.top) - 2, hdcCompat,

                0, 0, 32, 32, SRCCOPY);

            EndPaint(hwnd, &ps);

            break;

        case WM_MOVE:

        case WM_SIZE:

            /*

             * Convert the client coordinates of the client-area

             * rectangle to screen coordinates and save them in a

             * rectangle. The rectangle is passed to the ClipCursor

             * function during WM_LBUTTONDOWN processing.

             */

            GetClientRect(hwnd, &rcClient);

            ptClientUL.x = rcClient.left;

            ptClientUL.y = rcClient.top;

            ptClientLR.x = rcClient.right;

            ptClientLR.y = rcClient.bottom;

            ClientToScreen(hwnd, &ptClientUL);

            ClientToScreen(hwnd, &ptClientLR);

            SetRect(&rcClient, ptClientUL.x, ptClientUL.y,

                ptClientLR.x, ptClientLR.y);

            return 0;

        case WM_LBUTTONDOWN:

            /*

             * Restrict the mouse cursor to the client area. This

             * ensures that the window receives a matching

             * WM_LBUTTONUP message.

             */

            ClipCursor(&rcClient);

            /* Save the coordinates of the mouse cursor. */

            pt.x = (LONG) LOWORD(lParam);

            pt.y = (LONG) HIWORD(lParam);

            /*

             * If the user has clicked the bitmap rectangle, redraw

             * it using the dotted pen. Set the fDragRect flag to

             * indicate that the user is about to drag the

             * rectangle.

             */

            if (PtInRect(&rcBmp, pt)) {

                hdc = GetDC(hwnd);

                SelectObject(hdc, hpenDot);

                Rectangle(hdc, rcBmp.left, rcBmp.top, rcBmp.right,

                    rcBmp.bottom);

                fDragRect = TRUE;

                ReleaseDC(hwnd, hdc);

            }

            return 0;

        case WM_MOUSEMOVE:

            /*

             * Draw a target rectangle or drag the bitmap

             * rectangle, depending on the status of the fDragRect

             * flag.

             */

            if ((wParam && MK_LBUTTON)

                    && !fDragRect) {  /* draw a target rectangle */

                /*

                 * Set the mix mode so that the pen color is the

                 * inverse of the background color. The previous

                 * rectangle can then be erased by drawing

                 * another rectangle on top of it.

                 */

                hdc = GetDC(hwnd);

                SetROP2(hdc, R2_NOTXORPEN);

                /*

                 * If a previous target rectangle exists, erase

                 * it by drawing another rectangle on top of it.

                 */

                if (!IsRectEmpty(&rcTarget))

                    Rectangle(hdc, rcTarget.left, rcTarget.top,

                        rcTarget.right, rcTarget.bottom);

                /*

                 * Save the coordinates of the target rectangle.

                 * Avoid invalid rectangles by ensuring that the

                 * value of the left coordinate is greater than

                 * that of the right coordinate, and that the

                 * value of the bottom coordinate is greater than

                 * that of the top.

                 */

                if ((pt.x < (LONG) LOWORD(lParam)) &&

                        (pt.y > (LONG) HIWORD(lParam)))

                    SetRect(&rcTarget, pt.x, HIWORD(lParam),

                        LOWORD(lParam), pt.y);

                else if ((pt.x > (LONG) LOWORD(lParam)) &&

                        (pt.y > (LONG) HIWORD(lParam)))

                    SetRect(&rcTarget, LOWORD(lParam),

                        HIWORD(lParam), pt.x, pt.y);

                else if ((pt.x > (LONG) LOWORD(lParam)) &&

                        (pt.y < (LONG) HIWORD(lParam)))

                    SetRect(&rcTarget, LOWORD(lParam), pt.y,

                        pt.x, HIWORD(lParam));

                else

                    SetRect(&rcTarget, pt.x, pt.y, LOWORD(lParam),

                        HIWORD(lParam));

                /* Draw the new target rectangle. */

                Rectangle(hdc, rcTarget.left, rcTarget.top,

                    rcTarget.right, rcTarget.bottom);

                ReleaseDC(hwnd, hdc);

            }

            else if ((wParam && MK_LBUTTON)

                    && fDragRect) { /* drag the bitmap rectangle */

                /*

                 * Set the mix mode so that the pen color is the

                 * inverse of the background color.

                 */

                hdc = GetDC(hwnd);

                SetROP2(hdc, R2_NOTXORPEN);

                /*

                 * Select the dotted pen into the DC and erase

                 * the previous bitmap rectangle by drawing

                 * another rectangle on top of it.

                 */

                SelectObject(hdc, hpenDot);

                Rectangle(hdc, rcBmp.left, rcBmp.top,

                    rcBmp.right, rcBmp.bottom);

                /*

                 * Set the new coordinates of the bitmap

                 * rectangle, then redraw it.

                 */

                OffsetRect(&rcBmp, LOWORD(lParam) - pt.x,

                    HIWORD(lParam) - pt.y);

                Rectangle(hdc, rcBmp.left, rcBmp.top,

                    rcBmp.right, rcBmp.bottom);

                ReleaseDC(hwnd, hdc);

                /* Save the coordinates of the mouse cursor. */

                pt.x = (LONG) LOWORD(lParam);

                pt.y = (LONG) HIWORD(lParam);

            }

            return 0;

        case WM_LBUTTONUP:

            /*

             * If the bitmap rectangle and target rectangle

             * intersect, copy the bitmap into the target

             * rectangle. Otherwise, copy the bitmap into the

             * rectangle bitmap at its new location.

             */

            if (IntersectRect(&rcTmp, &rcBmp, &rcTarget)) {

                /*

                 * Erase the bitmap rectangle by filling it with

                 * the background color.

                 */

                hdc = GetDC(hwnd);

                FillRect(hdc, &rcBmp, hbrBkgnd);

                /*

                 * Redraw the target rectangle because the part

                 * that intersected with the bitmap rectangle was

                 * erased by the call to FillRect.

                 */

                Rectangle(hdc, rcTarget.left, rcTarget.top,

                    rcTarget.right, rcTarget.bottom);

                /* Copy the bitmap into the target rectangle. */

                StretchBlt(hdc, rcTarget.left + 1, rcTarget.top + 1,

                    (rcTarget.right - rcTarget.left) - 2,

                    (rcTarget.bottom - rcTarget.top) - 2, hdcCompat,

                    0, 0, 32, 32, SRCCOPY);

                /*

                 * Copy the target rectangle to the bitmap

                 * rectangle, set the coordinates of the target

                 * rectangle to 0, then reset the fDragRect flag.

                 */

                CopyRect(&rcBmp, &rcTarget);

                SetRectEmpty(&rcTarget);

                ReleaseDC(hwnd, hdc);

                fDragRect = FALSE;

            }

            else if (fDragRect) {

                /*

                 * Draw the bitmap rectangle, copy the bitmap into

                 * it, and reset the fDragRect flag.

                 */

                hdc = GetDC(hwnd);

                Rectangle(hdc, rcBmp.left, rcBmp.top,

                    rcBmp.right, rcBmp.bottom);

                StretchBlt(hdc, rcBmp.left + 1, rcBmp.top + 1,

                    (rcBmp.right - rcBmp.left) - 2,

                    (rcBmp.bottom - rcBmp.top) - 2, hdcCompat,

                    0, 0, 32, 32, SRCCOPY);

                ReleaseDC(hwnd, hdc);

                fDragRect = FALSE;

            }

            /* Release the mouse cursor. */

            ClipCursor((LPRECT) NULL);

            return 0;

        case WM_DESTROY:

            /*

             * Destroy the background brush, compatible bitmap,

             * and the bitmap.

             */

            DeleteObject(hbrBkgnd);

            DeleteDC(hdcCompat);

            DeleteObject(hbmp);

            PostQuitMessage(0);

            break;

        default:

            return DefWindowProc(hwnd, uMsg, wParam, lParam);

    }

    return (LRESULT) NULL;

}


Functions

Following are the functions used with rectangles.

CopyRect

EqualRect

InflateRect

IntersectRect

IsRectEmpty

OffsetRect

PtInRect

SetRect

SetRectEmpty

UnionRect


Painting and Drawing Overview

About Painting and Drawing

Nearly all applications use the screen to display the data they manipulate. An application paints images, draws figures, and writes text so that the user can view data as it is created, edited, and printed. Microsoft® Windows™ provides a rich environment for painting and drawing, but, because Windows is a multitasking operating system, applications must cooperate with one another when accessing the screen.

To keep all applications functioning smoothly and cooperatively, Windows manages all output to the screen. Applications use windows as their primary output device rather than the screen itself. Windows supplies display device contexts (or, more simply, display DCs) that uniquely correspond to the windows. Applications use display DCs to direct their output to the given windows. Drawing in a window (directing output to it) prevents an application from interfering with the output of other applications and allows applications to coexist with one another while still taking full advantage of the graphics capabilities of Windows.

This topic describes how Windows manages output to the screen and explains what applications must do to draw in a window. In particular, this topic describes display DCs and how to prepare and use them. This topic does not explain how to use graphics device interface (GDI) functions to generate output, nor does it explain how to print. For information on these topics, see other chapters in this book.

The following topics discuss painting and drawing:

Terms

When to Draw in a Window

The WM_PAINT Message

Drawing Without the WM_PAINT Message

Window Coordinate System

Window Regions

Window Background

Minimized Window

Window Size

Nonclient Area

Child Windows

Display Device Contexts

Window Update Lock

Accumulated Bounding Rectangle

Using the WM_PAINT Message

Drawing in the Client Area

Redrawing the Entire Client Area

Redrawing in the Update Area

Invalidating the Client Area

Drawing a Minimized Window

Drawing a Custom Window Background

Using the GetDC Function

Drawing With the Mouse

Drawing at Timed Intervals

Functions and Messages


When to Draw in a Window

An application draws in a window at a variety of times: when first creating a window, when changing the size of the window, when moving the window from behind another window, when minimizing or maximizing the window, when displaying data from an opened file, and when scrolling, changing, or selecting a portion of the displayed data.

Windows manages actions such as moving and sizing a window. If an action affects the content of the window, Windows marks the affected portion of the window as ready for updating and, at the next opportunity, sends a WM_PAINT message to the window procedure corresponding to the window. The message is a signal to the application to determine what must be updated and to carry out the drawing that is necessary.

Some actions are managed by the application, such as displaying open files and selecting displayed data. For these actions, an application can mark for updating the portion of the window affected by the action, causing a WM_PAINT message to be sent at the next opportunity. If an action requires immediate feedback, the application can draw while the action takes place, without waiting for a WM_PAINT message. For example, a typical application applies highlight to the area the user selects rather than waiting for the next WM_PAINT message.

In all cases, an application can draw in a window as soon as it is created. To draw in the window, the application must first retrieve a handle of a display DC for the window. Ideally, an application carries out most of its drawing operations during the processing of WM_PAINT messages. In this case, the application retrieves a display DC by calling the BeginPaint function. If an application draws at any other time, such as from within the WinMain function or during processing of keyboard or mouse messages, it calls the GetDC or GetDCEx function to retrieve the display DC.


The WM_PAINT Message

The WM_PAINT Message

Typically, an application draws in a window in response to a WM_PAINT message. Windows sends this message to a window procedure when changes to the window have altered the content of the client area. Windows sends the message only if there are no other messages in the application message queue.

Upon receiving a WM_PAINT message, an application can call BeginPaint to retrieve the display DC for the client area and use it in calls to GDI functions to carry out whatever drawing operations are necessary to update the client area. After completing the drawing operations, the application calls the EndPaint function to release the display DC.

Before BeginPaint returns the display DC, Windows prepares the DC for the given window. In particular, it sets the clipping region for the DC to be equal to the intersection of the portion of the window that needs updating and the portion that is visible to the user. Only those portions of the window that have changed are redrawn. Attempts to draw outside this region are clipped and do not appear on the screen.

Windows may also send WM_NCPAINT and WM_ERASEBKGND messages to the window procedure before BeginPaint returns. These messages direct the application to draw the nonclient area and window background. The nonclient area is the part of a window that is outside of the client area. The area includes features such as the title bar, System menu (also known as the Control menu), and scroll bars. Most applications rely on the default window function, DefWindowProc, to draw this area and therefore pass the WM_NCPAINT message to this function. The window background is the color or pattern a window is filled with before other drawing operations begin. The background covers any images previously in the window or on the screen under the window. If a window belongs to a window class having a class background brush, the DefWindowProc function draws the window background automatically.

BeginPaint fills a PAINTSTRUCT structure with information such as the dimensions of the portion of the window to be updated and a flag indicating whether the window background has been drawn. The application can use this information to optimize drawing. For example, it can use the dimensions of the update region, specified by the rcPaint member, to limit drawing to only those portions of the window that need updating. If an application has very simple output, it can ignore the update region and draw in the entire window, relying on Windows to clip any unneeded output. Because the system discards (clips) drawing that extends outside the clipping region, only drawing that is in the update region is visible.

BeginPaint sets the update region of a window to NULL. This clears the region, preventing it from generating subsequent WM_PAINT messages. If an application processes a WM_PAINT message but does not call BeginPaint or otherwise clear the update region, the application continues to receive WM_PAINT messages as long as the region is not empty. In all cases, an application must clear the update region before returning from the WM_PAINT message.

After the application finishes drawing, it should call EndPaint. For most windows, EndPaint releases the display DC, making it available to other windows. EndPaint also shows the caret, if it was previously hidden by BeginPaint. BeginPaint hides the caret to prevent drawing operations from corrupting it.

The Update Region

The update region identifies the portion of a window that is out of date or invalid and in need of redrawing. Windows uses the update region to generate WM_PAINT messages for applications and to minimize the time applications spend bringing the contents of their windows up to date. Windows adds only the invalid portion of the window to the update region, requiring only that portion to be drawn.

When Windows determines that a window needs updating, it sets the dimensions of the update region to the invalid portion of the window. Setting the update region does not immediately cause the application to draw. Instead, the application continues retrieving messages from the application message queue until no messages remain. At this point, Windows checks the update region, and if the region is not empty (non-NULL), it sends a WM_PAINT message to the window procedure.

An application can use the update region to generate its WM_PAINT messages. For example, an application that loads data from open files typically sets the update region while loading so that new data is drawn during processing of the next WM_PAINT message. In general, an application should not draw at the time its data changes but route all drawing operations through the WM_PAINT message.

Invalidating and Validating the Update Region

An application invalidates a portion of a window and sets the update region by using the InvalidateRect or InvalidateRgn function. These functions add the specified rectangle or region (given in client coordinates) to the update region, combining the rectangle or region with anything Windows or the application may have previously added to the update region.

The InvalidateRect and InvalidateRgn functions do not generate WM_PAINT messages. Instead, Windows accumulates the changes made by these functions and its own changes while a window processes other messages in its message queue. By accumulating changes, a window processes all changes at once instead of updating bits and pieces one step at a time.

The ValidateRect and ValidateRgn functions validate a portion of the window by removing a specified rectangle or region from the update region. These functions are typically used when the window has updated a specific part of the screen in the update region before receiving the WM_PAINT message.

Retrieving the Update Region

The GetUpdateRect and GetUpdateRgn functions retrieve the current update region for the window. GetUpdateRect retrieves the smallest rectangle (in client coordinates) that encloses the entire update region. GetUpdateRgn retrieves the update region itself. These functions can be used to calculate the current size of the update region to determine where to carry out a drawing operation.

BeginPaint also retrieves the dimensions of the smallest rectangle enclosing the current update region, copying the dimensions to the rcPaint member in the PAINTSTRUCT structure. Because BeginPaint validates the update region, any call to GetUpdateRect and GetUpdateRgn immediately after a call to BeginPaint returns an empty update region.

Excluding the Update Region

The ExcludeUpdateRgn function excludes the update region from the clipping region for the display DC. This function is useful when drawing in a window other than when a WM_PAINT message is processing. It prevents drawing in the areas that will be updated during the next WM_PAINT message.

Synchronous and Asynchronous Drawing

Most drawing carried out during processing of the WM_PAINT message is asynchronous. That is, there is a delay between the time a portion of the window is invalidated and the time the WM_PAINT message is sent. During the delay, the application typically retrieves messages from the queue and carries out other tasks. The reason for the delay is that Windows generally treats drawing in a window as a low-priority operation and works as though user-input messages and messages that may affect the position or size of a window will be processed before a WM_PAINT message.

In some cases, it is necessary for an application to draw synchronously--that is, draw in the window immediately after invalidating a portion of the window. A typical application draws its main window immediately after creating the window to signal the user that the application has started successfully. Windows synchronously draws some control windows, such as buttons, because such windows serve as the focus for user input. Although any window with a simple drawing routine can be drawn synchronously, all such drawing should be done quickly and should not interfere with the application's ability to respond to user input.

The UpdateWindow and RedrawWindow functions allow for synchronous drawing. UpdateWindow sends a WM_PAINT message directly to the window if the update region is not empty. RedrawWindow also sends a WM_PAINT message, but gives the application greater control over how to draw the window, such as whether to draw the nonclient area and window background or whether to send the message regardless of whether the update region is empty. These functions send the WM_PAINT message directly to the window, regardless of the number of other messages in the application message queue.

Any window requiring time-consuming drawing operations should be drawn asynchronously to prevent pending messages from being blocked as the window is drawn. Also, any application that frequently invalidates small portions of a window should usually allow these invalid portions to consolidate into a single asynchronous WM_PAINT message, rather than a series of synchronous WM_PAINT messages.


Drawing Without the WM_PAINT Message

Although applications carry out most drawing operations as the WM_PAINT message is processing, it is sometimes more efficient for an application to draw directly in a window without relying on the WM_PAINT message. This can be useful when the user needs immediate feedback, such as when selecting text and dragging or sizing an object. In such cases, the application usually draws while processing keyboard or mouse messages.

To draw in a window without using a WM_PAINT message, the application uses the GetDC or GetDCEx function to retrieve a display DC for the window. With the display DC, the application can draw in the window and avoid intruding into other windows. When the application has finished drawing, it calls the ReleaseDC function to release the display DC for use by other applications.

When drawing without using a WM_PAINT message, the application usually does not invalidate the window. Instead, it draws in such a fashion that it can easily restore the window and remove the drawing. For example, when the user selects text or an object, the application typically draws the selection by inverting whatever is already in the window. The application can remove the selection and restore the original contents of the window by simply inverting again.

The application is responsible for carefully managing any changes it makes to the window. In particular, if an application draws a selection and an intervening WM_PAINT message occurs, the application must ensure that any drawing done during the message does not corrupt the selection. To avoid this, many applications remove the selection, carry out usual drawing operations, and then restore the selection when complete.


Window Coordinate System

The coordinate system for a window is based on the coordinate system of the display device. The basic unit of measure is the device unit (typically, the pixel). Points on the screen are described by x- and y-coordinate pairs. The x-coordinates increase to the right; y-coordinates increase from top to bottom. The origin (0,0) for the system depends on the type of coordinates being used.

Windows and applications specify the position of a window on the screen in screen coordinates. For screen coordinates, the origin is the upper-left corner of the screen. The full position of a window is often described by a RECT structure containing the screen coordinates of two points that define the upper-left and lower-right corners of the window.

Windows and applications specify the position of points in a window by using client coordinates. The origin in this case is the upper-left corner of the window or client area. Client coordinates ensure that an application can use consistent coordinate values while drawing in the window, regardless of the position of the window on the screen.

The dimensions of the client area are also described by a RECT structure containing client coordinates for the area. In all cases, the upper-left coordinate of the rectangle is included in the window or client area, while the lower-right coordinate is excluded. Graphics operations in a window or client area are excluded from the right and lower edges of the enclosing rectangle.

Occasionally, applications may be required to map coordinates in one window to those of another window. An application can map coordinates by using the MapWindowPoints function. If one of the windows is the desktop window, the function effectively converts screen coordinates to client coordinates and vice versa; the desktop window is always specified in screen coordinates.


Window Regions

In addition to the update region, every window has a visible region that defines the window portion visible to the user. The system changes the visible region for the window whenever the window changes size or whenever another window is moved such that it obscures or exposes a portion of the window. Applications cannot change the visible region directly, but Windows automatically uses the visible region to create the clipping region for any display DC retrieved for the window.

The clipping region determines where the system permits drawing. When the application retrieves a display DC using the BeginPaint, GetDC, or GetDCEx function, the system sets the clipping region for the DC to the intersection of the visible region and the update region. Applications can change the clipping region by using functions such as SelectClipPath and SelectClipRgn, to further limit drawing to a particular portion of the update area.

The WS_CLIPCHILDREN and WS_CLIPSIBLINGS styles further specify how Windows calculates the visible region for a window. If a window has one or both of these styles, the visible region excludes any child window or sibling windows (windows having the same parent window). Therefore, drawing that would otherwise intrude in these windows will always be clipped.


Window Background

The window background is the color or pattern used to fill the client area before a window begins drawing. The window background covers whatever was on the screen before the window was moved there, erasing existing images and preventing the application's new output from being mixed with unrelated information.

Windows paints the background for a window or gives the window the opportunity to do so by sending it a WM_ERASEBKGND message when the application calls BeginPaint. If an application does not process the message but passes it to the DefWindowProc function, Windows erases the background by filling it with the pattern in the background brush specified by the window's class. If the class has no background brush or the brush is not valid, Windows sets the fErase member in the PAINTSTRUCT structure returned by BeginPaint, but carries out no other action. This gives the application a second chance to draw the window background, if necessary.

If it processes the WM_ERASEBKGND message, the application should use the message's wParam parameter to draw the background. This parameter contains the handle of the display DC for the window. After drawing the background, the application should return a nonzero value. This ensures that BeginPaint does not erroneously set the fErase member of the PAINTSTRUCT structure to a nonzero value (indicating the background should be erased) when the application processes the subsequent WM_PAINT message.

An application can define a class background brush by assigning a brush handle or a system color value to the hbrBackground member of the WNDCLASS structure when registering the class with the RegisterClass function. The GetStockObject or CreateSolidBrush function can be used to create a brush handle; a system color value can be one of those defined for the SetSysColors function. (The value must be increased by one before it is assigned to the member.)

An application can process the WM_ERASEBKGND message even though a class background brush is defined. This is typical in applications that enable the user to change the window background color or pattern for a given window without affecting other windows in the class. In such cases, the application must not pass the message to DefWindowProc.

In Windows 3.x, the origin of the screen is the point of reference for drawing brushes. The pattern in a window background can become misaligned if the window is moved to a new location. To prevent misalignment when running with Windows 3.x, applications that use pattern brushes for the window background must use the SetBrushOrg and UnrealizeObject functions to align the brush with the window before drawing.

In Windows NT™, it is not necessary for an application to align brushes, because the system draws the brush using the window origin as the point of reference. Given this, the user can move the window without affecting the alignment of pattern brushes.


Minimized Windows

Windows reduces an application's main window (overlapping style) to a minimized window when the user chooses the Minimize command from the System menu or the application calls the ShowWindow function and specifies a value such as SW_MINIMIZE. Minimizing a window speeds up system performance by reducing the amount of work an application must do when updating its main window.

For a typical application, Windows draws an icon, called the class icon, when the window is minimized, labeling the icon with the name of the window. The class icon, a static image that represents the application, is specified by the application when it registers the window class. The application assigns the handle of the class icon to the hIcon member of the WNDCLASS structure before calling RegisterClass. The application can use the LoadIcon function to retrieve the icon handle.

Before drawing the class icon, Windows sends a WM_ICONERASEBKGND message to the window procedure, enabling the application to prepare the background for drawing the icon and by setting the best possible background colors for the icon. This is useful for applications that combine the icon with the current background colors. If the application processes the message, it should use the display DC provided with the message to draw the background (the wParam parameter contains the handle of the display DC). If the application does not process the WM_ICONERASEBKGND message, it should pass the message to DefWindowProc; the function fills the icon area with the current desktop color and pattern. After sending WM_ICONERASEBKGND, Windows sends the WM_PAINTICON message to the window procedure. The application should immediately forward this internal message to DefWindowProc.

Windows does not require that a window class have a class icon. If an application sets the hIcon member of the WNDCLASS structure to NULL, a class icon is not defined. In this case, Windows sends the WM_ERASEBKGND message (instead of the WM_ICONERASEBKGND message) to a window of the class whenever the window must paint the icon background. Windows then sends a WM_PAINT message and the application draws an icon or another image representing the minimized window. In such cases, the application must determine when the window is minimized and draw accordingly. It can do so by calling the IsIconic function. If the function returns TRUE, the window is minimized. If an application has no class icon and fails to process the WM_ERASEBKGND and WM_PAINT messages, the area that Windows reserves for the application's icon will contain whatever was previously on the screen.


Window Size

Windows changes the size of a window when the user chooses System menu commands, such as Size and Maximize, or when the application calls functions, such as the SetWindowPos function. When a window changes size, Windows assumes that the contents of the previously exposed portion of the window are not affected and need not be redrawn. Windows invalidates only the newly exposed portion of the window, which saves time when the eventual WM_PAINT message is processed by the application. In this case, WM_PAINT message is not generated when the size of the window is reduced.

For some windows, however, any change to the size of the window invalidates the contents. For example, a clock application that adapts the face of the clock to fit neatly within its window must redraw the clock anytime the window changes size. To force Windows to invalidate the entire client area of the window when a vertical, horizontal, or both vertical and horizontal change is made, an application must specify the CS_VREDRAW or CS_HREDRAW style, or both, when registering the window class. Any window belonging to a window class having these styles is invalidated each time the user or the application changes the size of the window.


Nonclient Area

Windows sends a WM_NCPAINT message to the window whenever a part of the nonclient area of the window, such as the title bar, menu bar, or window frame, must be updated. Windows may also send other messages to direct a window to update a portion of its client area; for example, when a window becomes active or inactive it sends the WM_NCACTIVATE message to update its title bar. In general, processing these messages for standard windows is not recommended, because the application must be able to draw all the required parts of the nonclient area for the window. For this reason, most applications pass these messages to DefWindowProc for default processing.

An application that creates custom nonclient areas for its windows must process these messages. When doing so, the application must use a window DC to carry out drawing in the window. The window DC enables the application to draw in all portions of the window, including the nonclient area. An application retrieves a window DC by using the GetWindowDC or GetDCEx function and must release the window DC by using the ReleaseDC function when drawing is complete.

Windows maintains an update region for the nonclient area. When an application receives a WM_NCPAINT message, the wParam parameter contains the handle of a region defining the dimensions of the update region. The application can use the handle to combine the update region with the clipping region for the window DC. Windows does not automatically combine the update region when retrieving the window DC unless the application uses GetDCEx and specifies both the region handle and the DCX_INTERSECTRGN flag. If the application does not combine the update region, only drawing operations that would otherwise extend outside the window are clipped. The application is not responsible for clearing the update region, regardless of whether it uses the region.

If an application processes the WM_NCACTIVATE message, it must return TRUE after processing the message to direct Windows to complete the change of active window. If the window is minimized when the application receives the WM_NCACTIVATE message, it should pass the message to DefWindowProc. In such cases, the default function redraws the label for the icon.


Child Windows

A child window is a window having the WS_CHILD or WS_CHILDWINDOW style. Like other window styles, child windows receive WM_PAINT messages to prompt updating. Each child window has an update region, which either Windows or the application can set to generate eventual WM_PAINT messages.

A child window's update and visible regions are affected by the child's parent window; this is not true for windows of other styles. Windows often sets the child window's update region when it sets the parent window's update region, causing the child window to receive WM_PAINT messages when the parent window receives them. Also, Windows limits the location of the child window's visible region to within the client area of the parent window. Windows clips any portion of the child window moved outside the parent window.

Windows sets the update region for a child window whenever part of the parent window's update region includes a portion of the child window. In such cases, Windows first sends a WM_PAINT message to the parent window and then sends a message to the child window, allowing the child to restore any portions of the window that the parent may have drawn over.

Windows does not set the parent's update region when the child's is set. An application cannot generate a WM_PAINT message for the parent window by invalidating the child window. Similarly, an application cannot generate a WM_PAINT message for the child by invalidating a portion of the parent's client area that lies entirely under the child window. In such cases, neither window receives a WM_PAINT message.

An application can prevent a child window's update region from being set when the parent window's is set by specifying the WS_CLIPCHILDREN style when creating the parent window. When this style is set, Windows excludes the child windows from the parent's visible region and therefore ignores any portion of the update region that may contain the child windows. When the application paints in the parent window, any drawing that would cover the child window is clipped, making a subsequent WM_PAINT message to the child window unnecessary.

The update and visible regions of a child window are also affected by the child window's siblings. Sibling windows are any windows that have a common parent window. If sibling windows overlap, then setting the update region for one affects the update region of another, causing WM_PAINT messages to be sent to both windows. Sibling windows receive WM_PAINT messages in the reverse order of their position in the Z order. Given this, the window highest in the Z order (on the top) receives its WM_PAINT message last, and vice versa.

Sibling windows are not automatically clipped. One sibling can draw over another overlapping sibling even if the window that is drawing has a position in the Z order that is lower. An application can prevent this by specifying the WS_CLIPSIBLINGS style when creating the windows. When this style is set, Windows excludes all portions of an overlapping sibling window from a window's visible region if the overlapping sibling window has a higher position in the Z order.

Note:	The update and visible regions for windows that have the WS_POPUP or WS_POPUPWINDOW style are not affected by their parent windows.


Display Device Contexts

A display DC is a device context, created by Windows, that an application uses to paint and draw a window. Windows prepares each display DC for output to a window, setting the drawing objects, colors, and modes for the window instead of for the display device. When the application supplies the display DC in calls to GDI functions, GDI uses the information in the context to generate output in the given window without intruding on other windows or other parts of the screen.

Windows provides five kinds of display device context: common, class, parent, private, and window. The common, class, and private DCs permit drawing in the client area of a given window. The parent and window DCs permit drawing anywhere in the window. Although the parent DC also permits drawing in the parent window, it is not intended to be used in this way.

Windows supplies a common, class, parent, or private DC to a window based on the type of display DC specified in that window's class style. Windows supplies a window DC only when the application explicitly requests one; for example, by calling the GetWindowDC or GetDCEx function. In all cases, an application can determine which window a display DC currently represents by using the WindowFromDC function.

Display Device Context Cache

Windows maintains a cache of display DCs that it uses for common, parent, and window DCs. Windows retrieves a DC from the cache whenever an application calls the GetDC or BeginPaint function; Windows returns the DC to the cache when the application subsequently calls the ReleaseDC or EndPaint function.

In Windows 3.x, the cache contains five display DCs, but only five DCs from the cache can be active at a time. To ensure that other applications have access to these DCs, an application must release a device context immediately after using it. Failure to do so eventually causes the application to fail.

In Windows NT, there is no predetermined limit on the amount of DCs that a cache can hold; Windows NT creates a new display DC for the cache if none is available. Given this, an application designed for Windows NT can have more than five active DCs from the cache at a time. However, an application must continue to release these DCs after use. Because new display DCs for the cache are allocated in the application's heap space, failing to release the DCs eventually consumes all available heap space. Windows NT indicates this failure by returning an error when it cannot allocate space for the new DC. Other functions unrelated to the cache may also return errors.

Portability:	To minimize porting efforts, applications that use common DCs should be limited to no more than five and ensure that a common DC is released as soon as possible after it is used.

Display Device Context Defaults

Upon first creating a display DC, Windows assigns default values for the attributes (that is, drawing objects, colors, and modes) that comprise the DC. The following table shows the default values for the attributes of a display DC.

Attribute	Default value

Background color	Background color setting from Windows Control Panel (typically, white).

Background mode	OPAQUE.

Bitmap	None.

Brush	WHITE_BRUSH.

Brush origin	(0,0).

Clipping region	Entire window or client area with the update region clipped as appropriate. Child and pop-up windows in the client area may also be clipped.

Palette	DEFAULT_PALETTE.

Current pen position	(0,0).

Device origin	Upper-left corner of the window or the client area.

Drawing mode	R2_COPYPEN.

Font	SYSTEM_FONT (SYSTEM_FIXED_FONT for applications written to run with Windows versions 3.0 and earlier).

Intercharacter spacing	0.

Mapping mode	MM_TEXT.

Pen	BLACK_PEN.

Polygon-fill mode	ALTERNATE.

Stretch mode	BLACKONWHITE.

Text color	Text color setting from Windows Control Panel (typically, black).

Viewport extent	(1,1).

Viewport origin	(0,0).

Window extent	(1,1).

Window origin	(0,0).

An application can modify the values of the display DC attributes by using selection and attribute functions, such as SelectObject, SetMapMode, and SetTextColor. For example, an application can modify the default units of measure in the coordinate system by using SetMapMode to change the mapping mode.

Changes to the attribute values of a common, parent, or window DC are not permanent. When an application releases these DCs, the current selections, such as mapping mode and clipping region, are lost as the context is returned to the cache. Changes to a class or private DC persist indefinitely. To restore these DCs to the original defaults, an application must explicitly set each attribute.

Common Display Device Contexts

A common DC is used for drawing in the client area of the window. Windows provides a common DC by default for any window whose window class does not explicitly specify a display DC style. Common DCs are typically used with windows that can be drawn without extensive changes to the DC attributes. Common DCs are convenient because they do not require additional memory or system resources, but they can be inconvenient if the application must set up many attributes before using it.

Windows retrieves all common DCs from the display DC cache. An application can retrieve a common DC immediately after the window is created. Because the common DC is from the cache, the application must always release the DC as soon as possible after drawing. After the common DC is released, it is no longer valid and the application must not attempt to draw with it. To draw again, the application must retrieve a new common DC, and continue to retrieve and release a common DC each time it draws in the window. If the application retrieves the DC handle by using the GetDC function, it must use the ReleaseDC function to release the handle. Similarly, for each BeginPaint function, the application must use a corresponding EndPaint function.

When the application retrieves the DC, Windows adjusts the origin so that it aligns with the upper-left corner of the client area. It also sets the clipping region so that output to the DC is clipped to the client area. Any output that would otherwise appear outside the client area is clipped. If the application retrieves the common DC by using BeginPaint, Windows also includes the update region in the clipping region to further restrict the output.

When an application releases a common DC, Windows restores the default values for the attributes of the DC. An application that modifies attribute values must do so each time it retrieves a common DC. Releasing the DC releases any drawing objects the application may have selected into the DC, so the application need not release these objects before releasing the DC. In all cases, an application must never assume that the common DC retains nondefault selections after being released.

Private Display Device Contexts

A private DC enables an application to avoid retrieving and initializing a display DC each time the application must draw in a window. Private DCs are useful for windows that require many changes to the values of the attributes of the DC to prepare it for drawing. Private DCs reduce the time required to prepare the DC and therefore the time needed to carry out drawing in the window.

An application directs Windows to create a private DC for a window by specifying the CS_OWNDC style in the window class. Windows creates a unique private DC each time it creates a new window belonging to the class. Initially, the private DC has the same default values for attributes as a common DC, but the application can modify these at any time. Windows preserves changes to the DC for the life of the window or until the application makes additional changes.

An application can retrieve the handle of the private DC by using the GetDC function any time after the window is created. The application must retrieve the handle only once. Thereafter, it can keep and use the handle any number of times. Because a private DC is not part of the display DC cache, an application never needs to release the DC by using the ReleaseDC function.

Windows automatically adjusts the DC to reflect changes to the window, such as moving or sizing. This ensures that any overlapping windows are always properly clipped; that is, no action is required by the application to ensure clipping. However, Windows does not revise the DC to include the update region. Therefore, when processing a WM_PAINT message, the application must incorporate the update region either by calling BeginPaint or by retrieving the update region and intersecting it with the current clipping region. If the application does not call BeginPaint, it must explicitly validate the update region by using the ValidateRect or ValidateRgn function. If the application does not validate the update region, the window receives an endless series of WM_PAINT messages.

Because BeginPaint hides the caret if a window is showing it, an application that calls BeginPaint should also call the EndPaint function to restore the caret. EndPaint has no other effect on a private DC.

Although a private DC is convenient to use, it is expensive in terms of system resources, requiring 800 or more bytes to store. Private DCs are recommended when performance considerations outweigh storage costs.

Windows includes the private DC when sending the WM_ERASEBKGND message to the application. The current selections of the private DC, including mapping mode, are in effect when the application or Windows processes these messages. To avoid undesirable effects, Windows uses logical coordinates when erasing the background; for example, it uses the GetClipBox function to retrieve the logical coordinates of the area to erase and passes these coordinates to the FillRect function. Applications that process these messages can use similar techniques. Windows supplies a window DC with the WM_ICONERASEBKGND message regardless of whether the corresponding window has a private DC.

An application can use the GetDCEx function to force Windows to return a common DC for the window that has a private DC. This is useful for carrying out quick touch-ups to a window without changing the current values of the attributes of the private DC.

Class Display Device Contexts

By using a class DC, an application can use a single display DC for every window belonging to a given class. Class DCs are often used with control windows that are drawn using the same attribute values. Like private DCs, class DCs minimize the time required to prepare a DC for drawing.

Windows supplies a class DC for a window if it belongs to a window class having the CS_CLASSDC style. Windows creates the DC when creating the first window belonging to the class and then uses the same DC for all subsequently created windows in the class. Initially, the class DC has the same default values for attributes as a common DC, but the application can modify these at any time. Windows preserves all changes, except for the clipping region and device origin, until the last window in the class has been destroyed. A change made for one window applies to all windows in that class.

An application can retrieve the handle for the class DC by using the GetDC function any time after the first window has been created. The application can keep and use the handle without releasing it because the class DC is not part of the display DC cache. If the application creates another window in the same window class, the application must retrieve the class DC again. Retrieving the DC sets the correct device origin and clipping region for the new window. After the application retrieves the class DC for a new window in the class, the DC can no longer be used to draw in the original window without again retrieving it for that window. In general, each time it must draw in a window, an application must explicitly retrieve the class DC for the window.

Applications that use class DCs should always call BeginPaint when processing a WM_PAINT message. The function sets the correct device origin and clipping region for the window, and incorporates the update region. The application should also call EndPaint to restore the caret if BeginPaint hid it. EndPaint has no other effect on a class DC.

Windows passes the class DC when sending the WM_ERASEBKGND message to the application, permitting the current attribute values to affect any drawing carried out by the application or Windows when processing this message. Windows supplies a window DC with the WM_ICONERASEBKGND message regardless of whether the corresponding window has a class DC. As it could with a window having a private DC, an application can use GetDCEx to force Windows to return a common DC for the window that has a class DC.

In Windows 3.x, class DCs are intended to be used with windows created by a single application. This ensures that drawing objects, such as pens and brushes, selected into the class DC are created and maintained by a single application. Errors can occur if several applications attempt to create and select drawing objects into a single class DC. In particular, assumptions made about the validity of handles returned by the SelectObject function can be wrong. In Windows NT, using class DCs is not recommended.

Window Display Device Contexts

A window DC enables an application to draw anywhere in a window, including the nonclient area. Window DCs are typically used by applications that process the WM_NCPAINT and WM_NCACTIVATE messages for windows with custom nonclient areas. Using a window DC is not recommended for any other purpose.

An application can retrieve a window DC by using the GetWindowDC or GetDCEx function with the DCX_WINDOW option specified. The function retrieves a window DC from the display DC cache. A window that uses a window DC must release it after drawing by using the ReleaseDC function as soon as possible. Window DCs are always from the cache; the CS_OWNDC and CS_CLASSDC class styles do not affect the DC.

When an application retrieves a window DC, Windows sets the device origin to the upper-left corner of the window instead of the upper-left corner of the client area. It also sets the clipping region to include the entire window, not just the client area. Windows sets the current attribute values of a window DC to the same default values as a common DC. An application can change the attribute values, but Windows does not preserve any changes when the DC is released.

Parent Display Device Contexts

A parent DC enables an application to minimize the time necessary to set up the clipping region for a window. An application typically uses parent DCs to speed up drawing for control windows without requiring a private or class DC. For example, Windows uses parent DCs for push button and edit controls. Parent DCs are intended for use with child windows only, never with top-level or pop-up windows.

Windows supplies a parent DC for any window belonging to a window class specifying the CS_PARENTDC style. An application can retrieve the parent DC by using GetDC immediately after the window is created. Windows always retrieves the parent DC from the display DC cache even if the parent uses a private or class DC, so the application must release the DC by using ReleaseDC as soon as possible after drawing. When processing a WM_PAINT message, the application must retrieve the parent DC by using BeginPaint and release it by using EndPaint.

When a parent DC is retrieved, Windows searches the cache for the display DC previously used by the parent window. In most cases, the parent window retrieves and releases a display DC before the child window attempts to retrieve one, so the parent DC is usually in the cache. If Windows finds the display DC, Windows uses it and its corresponding clipping region, which was previously calculated for the parent DC. The time saved is in skipping the calculation required to define the clipping region. If Windows does not find the parent DC, it retrieves a common DC for the window and calculates the clipping region for the window rather than for the parent window.

Windows sets the device origin for the parent DC to the upper-left corner of the child window. Attribute values set by the parent window are not preserved for the child window; for example, the parent window cannot set the brush for its child windows. The only property preserved is the clipping region. The window is responsible for clipping its own output to the limits of the window. Because the clipping region for the parent DC is identical to the parent window, the child window can potentially draw over the entire parent window, but the parent DC must not be used in this way.

Windows ignores the CS_PARENTDC style if the parent window uses a private or class DC, if the parent window clips its child windows, or if the child window clips its child windows or sibling windows. In these cases, Windows always retrieves a common DC for the window.


Window Update Lock

A window update lock is a temporary suspension of drawing in a window. Windows uses the lock to prevent other windows from drawing over the tracking rectangle whenever the user moves or sizes a window. Applications can use the lock to prevent drawing if they carry out similar moving or sizing operations with their own windows.

An application sets and clears the window update lock by using the LockWindowUpdate function, specifying the window to lock. The lock applies to the given window and all of its child windows. When the lock is set, the GetDC and BeginPaint functions return a display DC whose visible region is empty. Given this, the application can continue to draw in the window, but all output is clipped. The lock continues until the application clears it by calling LockWindowUpdate, specifying NULL for the window. Although LockWindowUpdate forces a window's visible region to be empty, the function does not make the given window invisible and does not clear the WS_VISIBLE style bit.

After the lock is set, the application can use the GetDCEx function, with the DCX_LOCKWINDOWUPDATE value, to retrieve a display DC to draw over the locked window. This allows the application to draw a tracking rectangle when processing keyboard or mouse messages. Windows uses this method when the user moves and sizes windows. GetDCEx retrieves the display DC from the display DC cache, so the application must release the DC as soon as possible after drawing.

While a window update lock is set, the system creates an accumulated bounding rectangle for each locked window. When the lock is cleared, Windows uses this bounding rectangle to set the update region for the window and its child windows, forcing an eventual WM_PAINT message. If the accumulated bounding rectangle is empty (that is, if no drawing has occurred while the lock was set), the update region is not set.


Accumulated Bounding Rectangle

The accumulated bounding rectangle is the smallest rectangle enclosing the portion of a window or client area affected by recent drawing operations. An application can use this rectangle to conveniently determine the extent of changes caused by drawing operations. It is sometimes used in conjunction with LockWindowUpdate to determine which portion of the client area must be redrawn after the update lock is cleared.

An application starts accumulating the bounding rectangle by using the SetBoundsRect function, specifying the DCB_ENABLE value. Windows subsequently accumulates points for the bounding rectangle as the application uses the specified display DC. The application can retrieve the current bounding rectangle at any time by using the GetBoundsRect function. The application stops the accumulation by calling SetBoundsRect again, specifying DCB_DISABLE.


Using the WM_PAINT Message

You can use the WM_PAINT message to carry out the drawing necessary for displaying information. Because Windows sends WM_PAINT messages to your application when your window must be updated or when you explicitly request an update, you can consolidate the code for drawing in your application's window procedure. You can then use this code whenever your application must draw either new or existing information.

The following sections show a variety of ways to use the WM_PAINT message to draw in a window.


Drawing in the Client Area

You use the BeginPaint and EndPaint functions to prepare for and complete the drawing in the client area. BeginPaint returns a handle of the display DC used for drawing in the client area, and EndPaint ends the paint request and releases the display DC.

In the following code sample, the window procedure writes the message "Hello, Windows!" in the client area. To make sure the string is visible when the window is first created, the WinMain function calls the UpdateWindow function immediately after creating and showing the window. This causes a WM_PAINT message to be sent immediately to the window procedure.

LRESULT APIENTRY WndProc(hwnd, message, wParam, lParam)

HWND hwnd;

UINT message;

WPARAM wParam;

LPARAM lParam;

{

    PAINTSTRUCT ps;

    HDC hdc;

    switch (message) {

        case WM_PAINT:

            hdc = BeginPaint(hwnd, &ps);

            TextOut(hdc, 0, 0, "Hello, Windows!", 15);

            EndPaint(hwnd, &ps);

            return 0L;

        .

        .

        .

    }

}

int APIENTRY WinMain(hInstance, hPrevInstance, lpCmdLine, nCmdShow)

HINSTANCE hInstance;         /* handle of current instance   */

HINSTANCE hPrevInstance;     /* handle of previous instance  */

LPSTR lpCmdLine;             /* address of command line      */

int nCmdShow;                /* show-window type (open/icon) */

{

    HWND hwnd;

    hwnd = CreateWindowEx( /* parameters */ );

    ShowWindow(hwnd, SW_SHOW);

    UpdateWindow(hwnd);

    .

    .

    .

    return msg.wParam;

}


Redrawing the Entire Client Area

You can have your application redraw the entire contents of the client area whenever the window changes size by setting the CS_HREDRAW and CS_VREDRAW styles for the window class. Applications that adjust the size of the drawing based on the size of the window use these styles to ensure that they start with a completely empty client area when drawing.

In the following code, the window procedure draws a five-pointed star that fits neatly in the client area. It uses a common DC and must set the mapping mode and window and viewport extents each time the WM_PAINT message is processed.

LRESULT APIENTRY WndProc(hwnd, message, wParam, lParam)

HWND hwnd;

UINT message;

WPARAM wParam;

LPARAM lParam;

{

    PAINTSTRUCT ps;

    HDC hdc;

    RECT rc;

    POINT aptStar[6] = {50,2, 2,98, 98,33, 2,33, 98,98, 50,2};

    .

    .

    .

        case WM_PAINT:

            hdc = BeginPaint(hwnd, &ps);

            GetClientRect(hwnd, &rc);

            SetMapMode(hdc, MM_ANISOTROPIC);

            SetWindowExtEx(hdc, 100, 100, NULL);

            SetViewportExtEx(hdc, rc.right, rc.bottom, NULL);

            Polyline(hdc, aptStar, 6);

            EndPaint(hwnd, &ps);

            return 0L;

        .

        .

        .

}

int APIENTRY WinMain(hInstance, hPrevInstance, lpCmdLine, nCmdShow)

HINSTANCE hInstance;         /* handle of current instance   */

HINSTANCE hPrevInstance;     /* handle of previous instance  */

LPSTR lpCmdLine;             /* address of command line      */

int nCmdShow;                /* show-window type (open/icon) */

{

    WNDCLASS wc;

    .

    .

    .

        wc.style = CS_HREDRAW | CS_VREDRAW;

        wc.lpfnWndProc = (WNDPROC) WndProc;

    .

    .

    .

        RegisterClass(&wc);

    .

    .

    .

    return msg.wParam;

}


Redrawing in the Update Region

You can limit the amount of drawing your application carries out when processing the WM_PAINT message by determining the size and location of the update region. Because Windows uses the update region when creating the clipping region for the window's display DC, you can indirectly determine the update region by examining the clipping region.

In the following code sample, the window procedure draws a triangle, a rectangle, a pentagon, and a hexagon, but only if all or a portion of each figure lies within the update region. The window procedure uses the RectVisible function and a 100-by-100 rectangle to determine whether a figure is within the clipping region (and therefore the update region) for the common DC retrieved by the BeginPaint function.

POINT aptTriangle[4]  = {50,2, 98,86,  2,86, 50,2},

      aptRectangle[5] = { 2,2, 98,2,  98,98,  2,98, 2,2},

      aptPentagon[6]  = {50,2, 98,35, 79,90, 21,90, 2,35, 50,2},

      aptHexagon[7]   = {50,2, 93,25, 93,75, 50,98, 7,75, 7,25, 50,2};

  .

  .

  .

        case WM_PAINT:

            hdc = BeginPaint(hwnd, &ps);

            SetRect(&rc, 0, 0, 100, 100);

            if (RectVisible(hdc, &rc))

                Polyline(hdc, aptTriangle, 4);

            SetViewportOrgEx(hdc, 100, 0, NULL);

            if (RectVisible(hdc, &rc))

                Polyline(hdc, aptRectangle, 5);

            SetViewportOrgEx(hdc, 0, 100, NULL);

            if (RectVisible(hdc, &rc))

                Polyline(hdc, aptPentagon, 6);

            SetViewportOrgEx(hdc, 100, 100, NULL);

            if (RectVisible(hdc, &rc))

                Polyline(hdc, aptHexagon, 7);

            EndPaint(hwnd, &ps);

            return 0L;

  .

  .

  .

In this example, the coordinates of each figure lie within the same 100-by-100 rectangle. Before drawing a figure, the window procedure uses the SetViewportOrgEx function to set the viewport origin to a different part of the client area. This prevents the figures from being drawn one on top of the other. Changing the viewport origin does not affect the clipping region but does affect how the coordinates of the rectangle passed to RectVisible are interpreted. Changing the origin also allows you to use a single rectangle to check the update region rather than individual rectangles for each figure.


Invalidating the Client Area

Windows is not the only source of WM_PAINT messages. The InvalidateRect or InvalidateRgn function can indirectly generate WM_PAINT messages for your windows. These functions mark all or part of a client area as invalid (that must be redrawn).

In the following code sample, the window procedure invalidates the entire client area when processing WM_CHAR messages. This allows the user to change the figure by typing a number and view the results, which are drawn as soon as there are no other messages in the application's message queue.

POINT aptPentagon[6] = {50,2, 98,35, 79,90, 21,90, 2,35, 50,2},

      aptHexagon[7]  = {50,2, 93,25, 93,75, 50,98, 7,75, 7,25, 50,2};

POINT *ppt = aptPentagon;

int cpt = 6;

  .

  .

  .

case WM_CHAR:

    switch (wParam) {

    case '5':

        ppt = aptPentagon;

        cpt = 6;

        break;

    case '6':

        ppt = aptHexagon;

        cpt = 7;

        break;

    }

    InvalidateRect(hwnd, NULL, TRUE);

    return 0L;

case WM_PAINT:

    hdc = BeginPaint(hwnd, &ps);

    GetClientRect(hwnd, &rc);

    SetMapMode(hdc, MM_ANISOTROPIC);

    SetWindowExtEx(hdc, 100, 100, NULL);

    SetViewportExtEx(hdc, rc.right, rc.bottom, NULL);

    Polyline(hdc, ppt, cpt);

    EndPaint(hwnd, &ps);

    return 0L;

In this example, the NULL argument used in InvalidateRect specifies the entire client area; the TRUE argument causes the background to be erased. If you do not want the application to wait until the application's message queue has no other messages, use the UpdateWindow function to force the WM_PAINT message to be sent immediately. If there is any invalid part of the client area, UpdateWindow sends the WM_PAINT message for the given window directly to the window procedure.


Drawing a Minimized Window

You can draw your own minimized windows rather than having Windows draw them for you. Most applications define a class icon when registering the window class for the window, and Windows draws the icon when the window is minimized. If you set the class icon to NULL, however, Windows sends a WM_PAINT message to your window procedure whenever the window is minimized, enabling the window procedure to draw in the minimized window.

In the following code sample, the window procedure draws a star in the minimized window. The procedure uses the IsIconic function to determine when the window is minimized. This ensures that the star is drawn only when the window is minimized.

POINT aptStar[6] = {50,2, 2,98, 98,33, 2,33, 98,98, 50,2};

  .

  .

  .

case WM_PAINT:

    hdc = BeginPaint(hwnd, &ps);

    /* Determine whether the window is minimized. */

    if (IsIconic(hwnd)) {

        GetClientRect(hwnd, &rc);

        SetMapMode(hdc, MM_ANISOTROPIC);

        SetWindowExtEx(hdc, 100, 100, NULL);

        SetViewportExtEx(hdc, rc.right, rc.bottom, NULL);

        Polyline(hdc, aptStar, 6);

    } else {

        TextOut(hdc, 0,0, "Hello, Windows!", 15);

    }

    EndPaint(hwnd, &ps);

    return 0L;

You set the class icon to NULL by setting the hIcon member of the WNDCLASS structure to NULL before calling the RegisterClass function for the window class.


Drawing a Custom Window Background

You can draw your own window background rather than having Windows draw it for you. Most applications specify a brush handle or system color value for the class background brush when registering the window class; Windows uses the brush or color to draw the background. If you set the class background brush to NULL, however, Windows sends a WM_ERASEBKGND message to your window procedure whenever the window background must be drawn, letting you draw a custom background.

In the following code sample, the window procedure draws a large checkerboard pattern that fits neatly in the window. The procedure fills the client area with a white brush and then draws thirteen 20-by-20 rectangles using a gray brush. The display DC to use when drawing the background is in the wParam parameter for the message.

HBRUSH hbrWhite, hbrGray;

  .

  .

  .

case WM_CREATE:

    hbrWhite = GetStockObject(WHITE_BRUSH);

    hbrGray  = GetStockObject(GRAY_BRUSH);

    return 0L;

case WM_ERASEBKGND:

    hdc = (HDC) wParam;

    GetClientRect(hwnd, &rc);

    SetMapMode(hdc, MM_ANISOTROPIC);

    SetWindowExtEx(hdc, 100, 100, NULL);

    SetViewportExtEx(hdc, rc.right, rc.bottom, NULL);

    FillRect(hdc, &rc, hbrWhite);

    for (i = 0; i < 13; i++) {

        x = (i * 40) % 100;

        y = ((i * 40) / 100) * 20;

        SetRect(&rc, x, y, x + 20, y + 20);

        FillRect(hdc, &rc, hbrGray);

    }

  return 1L;

If the application draws its own minimized window, Windows also sends the WM_ERASEBKGND message to the window procedure to draw the background for the minimized window. You can use the same technique used with the WM_PAINT message to determine whether the window is minimized--that is, call the IsIconic function and check for the return value TRUE.


Using the GetDC Function

You use the GetDC function to carry out drawing that must occur instantly rather than when a WM_PAINT message is processing. Such drawing is usually in response to an action by the user, such as making a selection or drawing with the mouse. In such cases, the user should receive instant feedback and must not be forced to stop selecting or drawing in order for the application to display the result. The following sections show how to use GetDC to draw in a window.


Drawing With the Mouse

Drawing with the Mouse

You can permit the user to draw lines with the mouse by having your window procedure draw while processing the WM_MOUSEMOVE message. Windows sends the WM_MOUSEMOVE message to the window procedure whenever the user moves the cursor within the window. To draw lines, the window procedure can retrieve a display DC and draw a line in the window between the current and previous cursor positions.

In the following code sample, the window procedure prepares for drawing when the user presses and holds the left mouse button (the WM_LBUTTONDOWN message). As the user moves the cursor within the window, the window procedure receives a series of WM_MOUSEMOVE messages. For each message, the window procedure draws a line connecting the previous position and the current position. To draw the line, the procedure uses GetDC to retrieve a display DC; then, as soon as drawing is complete and before returning from the message, the procedure uses the ReleaseDC function to release the display DC. As soon as the user releases the mouse button, the window procedure clears the flag, and the drawing stops (the WM_LBUTTONUP message).

BOOL fDraw = FALSE;

POINT ptPrevious;

  .

  .

  .

case WM_LBUTTONDOWN:

    fDraw = TRUE;

    ptPrevious.x = LOWORD(lParam);

    ptPrevious.y = HIWORD(lParam);

    return 0L;

case WM_LBUTTONUP:

    if (fDraw) {

        hdc = GetDC(hwnd);

        MoveToEx(hdc, ptPrevious.x, ptPrevious.y, NULL);

        LineTo(hdc, LOWORD(lParam), HIWORD(lParam));

        ReleaseDC(hwnd, hdc);

    }

    fDraw = FALSE;

    return 0L;

case WM_MOUSEMOVE:

    if (fDraw) {

        hdc = GetDC(hwnd);

        MoveToEx(hdc, ptPrevious.x, ptPrevious.y, NULL);

        LineTo(hdc, ptPrevious.x = LOWORD(lParam),

          ptPrevious.y = HIWORD(lParam));

        ReleaseDC(hwnd, hdc);

    }

  return 0L;

An application that enables drawing, as in this example, typically records either the points or lines so that the lines can be redrawn whenever the window is updated. Drawing applications often use a memory DC and an associated bitmap to store lines that were drawn by using a mouse.


Drawing at Timed Intervals

You can draw at timed intervals by creating a timer with the SetTimer function. By using a timer to send WM_TIMER messages to the window procedure at regular intervals, an application can carry out simple animation in the client area while other applications continue running.

In the following code sample, the application bounces a star from side to side in the client area. Each time the window procedure receives a WM_TIMER message, the procedure erases the star at the current position, calculates a new position, and draws the star at the new position. The procedure starts the timer by calling SetTimer while processing the WM_CREATE message.

RECT rcCurrent = {0,0,20,20};

POINT aptStar[6] = {10,1, 1,19, 19,6, 1,6, 19,19, 10,1};

int X = 2, Y = -1, idTimer = -1;

BOOL fVisible = FALSE;

HDC hdc;

LRESULT APIENTRY WndProc(hwnd, message, wParam, lParam)

HWND hwnd;

UINT message;

WPARAM wParam;

LPARAM lParam;

{

    PAINTSTRUCT ps;

    RECT rc;

    switch (message) {

        case WM_CREATE:

            /* Calculate the starting point. */

            GetClientRect(hwnd, &rc);

            OffsetRect(&rcCurrent, rc.right / 2, rc.bottom / 2);

            /* Initialize the private DC. */

            hdc = GetDC(hwnd);

            SetViewportOrgEx(hdc, rcCurrent.left,

                rcCurrent.top, NULL);

            SetROP2(hdc, R2_NOT);

            /* Start the timer. */

            SetTimer(hwnd, idTimer = 1, 10, NULL);

            return 0L;

        case WM_DESTROY:

            KillTimer(hwnd, 1);

            PostQuitMessage(0);

            return 0L;

        case WM_SIZE:

            switch (wParam) {

                case SIZE_MINIMIZED:

                    /* Stop the timer if the window is minimized. */

                    KillTimer(hwnd, 1);

                    idTimer = -1;

                    break;

                case SIZE_RESTORED:

                    /*

                     * Move the star back into the client area

                     * if necessary.

                     */

                    if (rcCurrent.right > (int) LOWORD(lParam))

                        rcCurrent.left =

                            (rcCurrent.right =

                                (int) LOWORD(lParam)) - 20;

                    if (rcCurrent.bottom > (int) HIWORD(lParam))

                        rcCurrent.top =

                            (rcCurrent.bottom =

                                (int) HIWORD(lParam)) - 20;

                    /* Fall through to the next case. */

                case SIZE_MAXIMIZED:

                    /* Start the timer if it had been stopped. */

                    if (idTimer == -1)

                        SetTimer(hwnd, idTimer = 1, 10, NULL);

                    break;

            }

            return 0L;

        case WM_TIMER:

            /* Hide the star if it is visible. */

            if (fVisible)

                Polyline(hdc, aptStar, 6);

            /* Bounce the star off a side if necessary. */

            GetClientRect(hwnd, &rc);

            if (rcCurrent.left + X < rc.left ||

                rcCurrent.right + X > rc.right)

                X = -X;

            if (rcCurrent.top + Y < rc.top ||

                rcCurrent.bottom + Y > rc.bottom)

                Y = -Y;

            /* Show the star in its new position. */

            OffsetRect(&rcCurrent, X, Y);

            SetViewportOrgEx(hdc, rcCurrent.left,

                rcCurrent.top, NULL);

            fVisible = Polyline(hdc, aptStar, 6);

            return 0L;

        case WM_ERASEBKGND:

            /* Erase the star. */

            fVisible = FALSE;

            return DefWindowProc(hwnd, message, wParam, lParam);

        case WM_PAINT:

            /*

             * Show the star if it is not visible. Use BeginPaint

             * to clear the update region.

             */

            BeginPaint(hwnd, &ps);

            if (!fVisible)

                fVisible = Polyline(hdc, aptStar, 6);

            EndPaint(hwnd, &ps);

            return 0L;

    }

    return DefWindowProc(hwnd, message, wParam, lParam);

}

This application uses a private DC to minimize the time required to prepare the DC for drawing. The window procedure retrieves and initializes the private DC when processing the WM_CREATE message, setting the binary raster operation mode to allow the star to be erased and drawn using the same call to the Polyline function. The window procedure also sets the viewport origin to allow the star to be drawn using the same set of points regardless of the star's position in the client area.

The application uses the WM_PAINT message to draw the star whenever the window must be updated. The window procedure draws the star only if it is not visible; that is, only if it has been erased by the WM_ERASEBKGND message. The window procedure intercepts the WM_ERASEBKGND message to set the fVisible variable, but passes the message to the DefWindowProc function so that Windows can draw the window background.

The application uses the WM_SIZE message to stop the timer when the window is minimized and to restart the timer when the minimized window is restored. The window procedure also uses the message to update the current position of the star if the size of the window has been reduced so that the star is no longer in the client area. The application keeps track of the star's current position by using the rcCurrent structure, which defines the bounding rectangle for the star. Keeping all corners of the rectangle in the client area keeps the star in the area. The window procedure initially centers the star in the client area when processing the WM_CREATE message.


Functions and Messages

Use the following functions and messages for painting and drawing in windows.

Functions

BeginPaint

EndPaint

ExcludeUpdateRgn

GdiFlush

GdiGetBatchLimit

GdiSetBatchLimit

GetBoundsRect

GetUpdateRect

GetUpdateRgn

GetWindowDC

InvalidateRect

InvalidateRgn

LockWindowUpdate

RedrawWindow

SetBoundsRect

SetRectRgn

UpdateWindow

ValidateRect

ValidateRgn

WindowFromDC

Messages

WM_ERASEBKGND

WM_ICONERASEBKGND

WM_NCPAINT

WM_PAINT

WM_PAINTICON


Cursors Overview

About Cursors

A cursor is a small bitmap whose location on the screen is controlled by a pointing device, such as a mouse, pen, or trackball. (In the remainder of this topic, the term mouse refers to any pointing device.) When the user moves the mouse, Microsoft® Windows™ moves the cursor accordingly. Win32™ cursor functions enable applications to create, load, display, move, confine, and destroy cursors.

The following topics discuss Win32 cursors:

Terms

The Hot Spot

The Pointing Device and the Cursor

Cursor Creation

Cursor Location and Appearance

Cursor Confinement

Cursor Destruction

Cursor Duplication

Creating a Cursor

Displaying a Cursor

Confining a Cursor

Creating a Mousetrap

Using the Keyboard to Move the Cursor

Functions

Windows supports two kinds of cursors: standard and custom. Standard cursors are predefined cursors that Windows displays automatically as the user moves windows or icons, resizes windows, or pauses while a process is underway. Win32 display driver files provide 13 standard cursors, such as the arrow, hourglass, and crosshair. Windows and Windows-based applications can use these cursors. The following illustration shows these standard cursors and their identifiers.

Custom cursors are designed for use in a specific application and can be any design the developer defines. The following illustration shows several custom cursors.


The Hot Spot

In the cursor, a pixel called the hot spot marks the exact screen location that is affected by a mouse event, such as clicking a mouse button. Typically, the hot spot is the focal point of the cursor. The system tracks and recognizes this point as the position of the cursor. For example, typical hot spots are the pixel at the tip of an arrow-shaped cursor and the pixel in the middle of a crosshair-shaped cursor.

When a mouse input event occurs, the Windows mouse driver translates the event into an appropriate mouse message that includes the coordinates of the hot spot. Windows sends the mouse message to the window that contains the hot spot or to the window that is capturing mouse input.


The Pointing Device and the Cursor

The Mouse and the Cursor

If the system includes a mouse, Windows reflects the movement of the mouse by moving the cursor on the screen accordingly. As the cursor moves over different parts of windows or into different windows, Windows changes the appearance of the cursor. For example, when the cursor crosses a window border, Windows changes the cursor into a two-headed arrow.

If the system does not have a mouse, Windows displays and moves the cursor only when the user chooses certain system commands, such as those used to size or move a window. To provide the user with a method of displaying and moving the cursor when a mouse isn't available, an application can use the cursor functions to simulate mouse movement. Given this, the user can use the arrow keys to move the cursor.


Cursor Creation

Because standard cursors are predefined, it is not necessary to create them. To use a standard cursor, an application retrieves a cursor handle by using the LoadCursor function. A cursor handle is a unique value of the HCURSOR type that identifies a standard or custom cursor.

To create a custom cursor for an application, developers typically use a graphics application and include the cursor as a resource in the application's resource-definition file. At run time, an application calls LoadCursor to retrieve the cursor handle. Cursor resources contain data for several different display devices. LoadCursor automatically selects the most appropriate data for the current display device.

An application can also create a custom cursor at run time by using the CreateCursor function. This function creates a cursor having the specified size, design, and hot spot.

Applications should implement custom cursors as resources and use LoadCursor rather than create the cursor at run time. Using cursor resources avoids device dependence, simplifies localization, and enables applications to share cursor designs.

Alternative Cursor Creation

Two other functions create cursors at run time: CreateIconFromResource and CreateIconIndirect. These functions enable an application to browse through the system's resources and create icons and cursors based on resource data. CreateIconFromResource creates a cursor based on binary resource data from other executable files or dynamic-link libraries. It must be preceded by calls to the LookupIconIDFromDirectory function, as well as several resource functions. LookupIconIDFromDirectory identifies the most appropriate cursor data for the current display device.

CreateIconIndirect creates a cursor based on the contents of an ICONINFO structure. The GetIconInfo function fills this structure with hot spot coordinates and information concerning the associated bitmask and color.


Cursor Location and Appearance

If the system includes a mouse, Windows automatically displays a cursor and updates its position on the screen. Applications can obtain current screen coordinates of the cursor and move the cursor to any location on the screen by using the GetCursorPos and SetCursorPos functions, respectively.

Applications can also retrieve the handle of the current cursor by using the GetCursor function and can set the cursor by using the SetCursor function. After an application uses SetCursor, the appearance of the cursor does not change until the mouse moves, until the cursor is explicitly set to a different cursor, or until a system command is executed.

When the user moves the mouse, the system redraws the cursor at the new location as designated by the mouse. The system automatically redraws the cursor design associated with the window to which the cursor is pointing.

Applications can hide and redisplay the cursor, without changing the cursor design, by using the ShowCursor function. This function uses an internal counter to determine when to hide or display the cursor. An attempt to show the cursor increments the counter; an attempt to hide the cursor decrements the counter. The cursor is visible only if this counter is greater than or equal to zero.

The Window Class Cursor

When registering a window class, an application can assign it a default cursor, known as the class cursor. After the application registers the window class, each window of that class will have the specified class cursor.

To override the class cursor, an application can process the WM_SETCURSOR message. Applications can also replace a class cursor by using the SetClassLong function. This function changes the default window settings for all windows of a given class.


Cursor Confinement

Applications can confine the cursor to a rectangular area on the screen by using the ClipCursor function. This can be useful when the user must respond to a certain event within the confined area of the rectangle. For example, an application might use ClipCursor to confine the cursor to a modal dialog box, preventing the user from interacting with other windows until the dialog box is closed.

The GetClipCursor function retrieves the screen coordinates of the rectangular area to which the cursor is temporarily confined. When it is necessary to confine the cursor, the application can also use this function to save the coordinates of the original area in which the cursor can move. Then, the application can restore the cursor to the original area when the new confinement is no longer necessary.


Cursor Destruction

When an application no longer needs a cursor it created by using the CreateCursor function, it should destroy the cursor. The DestroyCursor function destroys the cursor handle and frees any memory that it used. Applications should use this function only on cursors that were created with CreateCursor; it is not necessary to destroy other cursors.


Cursor Duplication

The CopyCursor function copies a cursor handle. This enables an application or dynamic-link library to retrieve the handle of a cursor owned by another module. Then, if the other module is freed, the application that copied the cursor will still be able to use the cursor design.


Creating a Cursor

The following code sample creates two cursor handles: one for the standard hourglass cursor and one for a custom cursor included as a resource in the application's resource-definition file.

HINSTANCE hinst;            /* handle of current instance */

HCURSOR hCurs1, hCurs2;     /* cursor handles             */

/* Create a standard hourglass cursor. */

hCurs1 = LoadCursor(NULL, IDC_WAIT);

/* Create a custom cursor based on a resource. */

hCurs2 = LoadCursor(hinst, MAKEINTRESOURCE(240));

An application should implement custom cursors as resources. Rather than create the cursors at run time, use the LoadCursor function to avoid device dependence, to simplify localization, and to enable applications to share cursor designs.

The following example is included to illustrate how the system interprets cursor bitmasks. Use the CreateCursor function to create a custom cursor at run time, based on cursor bitmasks.

HINSTANCE hinst;            /* handle of current instance */

HCURSOR hCurs1, hCurs2;     /* cursor handles             */

HCURSOR hCurs3;             /* cursor handle              */

/* Yin cursor AND bitmask */

BYTE ANDmaskCursor[] = {0xFF, 0xFC, 0x3F, 0xFF,   /* line 1 */

                        0xFF, 0xC0, 0x1F, 0xFF,   /* line 2 */

                        0xFF, 0x00, 0x3F, 0xFF,   /* line 3 */

                        0xFE, 0x00, 0xFF, 0xFF,   /* line 4 */

                        0xF7, 0x01, 0xFF, 0xFF,   /* line 5 */

                        0xF0, 0x03, 0xFF, 0xFF,   /* line 6 */

                        0xF0, 0x03, 0xFF, 0xFF,   /* line 7 */

                        0xE0, 0x07, 0xFF, 0xFF,   /* line 8 */

                        0xC0, 0x07, 0xFF, 0xFF,   /* line 9 */

                        0xC0, 0x0F, 0xFF, 0xFF,   /* line 10 */

                        0x80, 0x0F, 0xFF, 0xFF,   /* line 11 */

                        0x80, 0x0F, 0xFF, 0xFF,   /* line 12 */

                        0x80, 0x07, 0xFF, 0xFF,   /* line 13 */

                        0x00, 0x07, 0xFF, 0xFF,   /* line 14 */

                        0x00, 0x03, 0xFF, 0xFF,   /* line 15 */

                        0x00, 0x00, 0xFF, 0xFF,   /* line 16 */

                        0x00, 0x00, 0x7F, 0xFF,   /* line 17 */

                        0x00, 0x00, 0x1F, 0xFF,   /* line 18 */

                        0x00, 0x00, 0x0F, 0xFF,   /* line 19 */

                        0x80, 0x00, 0x0F, 0xFF,   /* line 20 */

                        0x80, 0x00, 0x07, 0xFF,   /* line 21 */

                        0x80, 0x00, 0x07, 0xFF,   /* line 22 */

                        0xC0, 0x00, 0x07, 0xFF,   /* line 23 */

                        0xC0, 0x00, 0x0F, 0xFF,   /* line 24 */

                        0xE0, 0x00, 0x0F, 0xFF,   /* line 25 */

                        0xF0, 0x00, 0x1F, 0xFF,   /* line 26 */

                        0xF0, 0x00, 0x1F, 0xFF,   /* line 27 */

                        0xF8, 0x00, 0x3F, 0xFF,   /* line 28 */

                        0xFE, 0x00, 0x7F, 0xFF,   /* line 29 */

                        0xFF, 0x00, 0xFF, 0xFF,   /* line 30 */

                        0xFF, 0xC3, 0xFF, 0xFF,   /* line 31 */

                        0xFF, 0xFF, 0xFF, 0xFF};  /* line 32 */

/* Yin cursor XOR bitmask */

BYTE XORmaskCursor[] = {0x00, 0x00, 0x00, 0x00,   /* line 1 */

                        0x00, 0x03, 0xC0, 0x00,   /* line 2 */

                        0x00, 0x3F, 0x00, 0x00,   /* line 3 */

                        0x00, 0xFE, 0x00, 0x00,   /* line 4 */

                        0x0E, 0xFC, 0x00, 0x00,   /* line 5 */

                        0x07, 0xF8, 0x00, 0x00,   /* line 6 */

                        0x07, 0xF8, 0x00, 0x00,   /* line 7 */

                        0x0F, 0xF0, 0x00, 0x00,   /* line 8 */

                        0x1F, 0xF0, 0x00, 0x00,   /* line 9 */

                        0x1F, 0xE0, 0x00, 0x00,   /* line 10 */

                        0x3F, 0xE0, 0x00, 0x00,   /* line 11 */

                        0x3F, 0xE0, 0x00, 0x00,   /* line 12 */

                        0x3F, 0xF0, 0x00, 0x00,   /* line 13 */

                        0x7F, 0xF0, 0x00, 0x00,   /* line 14 */

                        0x7F, 0xF8, 0x00, 0x00,   /* line 15 */

                        0x7F, 0xFC, 0x00, 0x00,   /* line 16 */

                        0x7F, 0xFF, 0x00, 0x00,   /* line 17 */

                        0x7F, 0xFF, 0x80, 0x00,   /* line 18 */

                        0x7F, 0xFF, 0xE0, 0x00,   /* line 19 */

                        0x3F, 0xFF, 0xE0, 0x00,   /* line 20 */

                        0x3F, 0xC7, 0xF0, 0x00,   /* line 21 */

                        0x3F, 0x83, 0xF0, 0x00,   /* line 22 */

                        0x1F, 0x83, 0xF0, 0x00,   /* line 23 */

                        0x1F, 0x83, 0xE0, 0x00,   /* line 24 */

                        0x0F, 0xC7, 0xE0, 0x00,   /* line 25 */

                        0x07, 0xFF, 0xC0, 0x00,   /* line 26 */

                        0x07, 0xFF, 0xC0, 0x00,   /* line 27 */

                        0x01, 0xFF, 0x80, 0x00,   /* line 28 */

                        0x00, 0xFF, 0x00, 0x00,   /* line 29 */

                        0x00, 0x3C, 0x00, 0x00,   /* line 30 */

                        0x00, 0x00, 0x00, 0x00,   /* line 31 */

                        0x00, 0x00, 0x00, 0x00};  /* line 32 */

/* Create a custom cursor at run time. */

hCurs3 = CreateCursor(hinst,  /* app instance */

             19,     /* horiz pos of hot spot */

             2,      /* vert pos of hot spot  */

             32,     /* cursor width          */

             32,     /* cursor height         */

             ANDmaskCursor,    /* AND bitmask */

             XORmaskCursor);   /* XOR bitmask */

To create the cursor, CreateCursor applies the following truth table to the AND and XOR bitmasks.

AND	XOR	Display

0	0	Black

0	1	White

1	0	Screen

1	1	Reverse screen

Before closing, your application must use the DestroyCursor function to destroy any cursors it created with CreateCursor. It is not necessary to destroy cursors created by other functions.


Displaying a Cursor

If the system includes a mouse, Windows automatically displays the class cursor (the cursor associated with the window to which the cursor is pointing). Your application can assign a class cursor while registering a window class. The following example illustrates this by assigning a cursor handle to the hCursor member of the WNDCLASS structure identified by the wc parameter.

WNDCLASS  wc;

/*

 * Fill the window class structure with parameters that describe

 * the main window.

 */

wc.style = NULL;                        /* class style(s)   */

wc.lpfnWndProc = (WNDPROC) MainWndProc; /* window procedure */

wc.cbClsExtra = 0;             /* no per-class extra data   */

wc.cbWndExtra = 0;             /* no per-window extra data  */

wc.hInstance = hinstance;      /* app that owns the class   */

wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);   /* class icon */

wc.hCursor = LoadCursor(hinstance, MAKEINTRESOURCE(230));

                                            /* class cursor */

wc.hbrBackground = GetStockObject(WHITE_BRUSH);

                                        /* class background */

wc.lpszMenuName =  "GenericMenu";             /* class menu */

wc.lpszClassName = "GenericWClass";           /* class name */

/* Register the window class. */

return RegisterClass(&wc);

When the window class is registered, the cursor identified by 230 in the application's resource-definition file will be the default cursor for all windows based on the class.

Your application can change the design of the cursor by using the SetCursor function and specifying a different cursor handle. However, when the cursor moves, Windows redraws the class cursor at the new location. To prevent the class cursor from being redrawn, your application must process the WM_SETCURSOR message. Each time the cursor moves and mouse input is not captured, Windows sends this message to the window in which the cursor is moving.

You can specify different cursors for different conditions while processing WM_SETCURSOR. For example, the following code shows how to display the hCurs3 cursor whenever the cursor moves over the icon of a minimized application.

case WM_SETCURSOR:

    /*

     * If the window is minimized, draw the hCurs3 cursor.

     * If the window is not minimized, draw the default

     * cursor (class cursor).

     */

    if (IsIconic(hwnd)) {

        SetCursor(hCurs3);

        break;

    }

When the window is not minimized, Windows displays the class cursor.

Your application can replace a class cursor by using the SetClassLong function. This function changes the default window settings for all windows of a given class. The following example replaces the existing class cursor with the hCurs2 cursor.

/* Change the cursor for hwnd's window class. */

SetClassLong(hwnd,    /* window handle */

    GCL_HCURSOR,      /* change cursor */

    (LONG) hCurs2);   /* new cursor    */


Confining a Cursor

The following example confines the cursor to the application's window and then restores the cursor to its previous window. The example uses the GetClipCursor function to record the area in which the cursor can move and the ClipCursor function to confine and restore the cursor.

RECT rcClip;           /* new ClipCursor area      */

RECT rcOldClip;        /* previous ClipCursor area */

/* Record the area in which the cursor can move. */

GetClipCursor(&rcOldClip);

/* Get the dimensions of the application's window. */

GetWindowRect(hwnd, &rcClip);

/* Confine the cursor to the application's window. */

ClipCursor(&rcClip);

    .

    . /* Process input from the confined cursor. */

    .

/* Restore the cursor to its previous area. */

ClipCursor(&rcOldClip);

Because there is only one cursor at a time available in the system, an application that confines the cursor must restore the cursor before relinquishing control to another window.


Creating a Mousetrap

The following example uses the  SetCursorPos, GetCursorPos, CreateCursor, LoadCursor, and SetCursor functions to create a simple mousetrap. It also uses cursor and timer functions to monitor the cursor's position every 10 seconds. If the cursor position has not changed in the last 10 seconds and the application's main window is minimized, the application changes the cursor and moves it to the mousetrap icon.

HICON hIcon1;               /* icon handles             */

POINT ptOld;                /* previous cursor location */

HCURSOR hCurs1;             /* cursor handle            */

/*

 * The following cursor bitmasks are defined in a code example

 * that appears earlier in this chapter.

 */

/* Yin cursor AND and XOR bitmasks */

BYTE ANDmaskCursor[] = ...

BYTE XORmaskCursor[] = ...

/* Yang icon AND bitmask */

BYTE ANDmaskIcon[] = {0xFF, 0xFF, 0xFF, 0xFF,   /* line 1 */

                      0xFF, 0xFF, 0xC3, 0xFF,   /* line 2 */

                      0xFF, 0xFF, 0x00, 0xFF,   /* line 3 */

                      0xFF, 0xFE, 0x00, 0x7F,   /* line 4 */

                      0xFF, 0xFC, 0x00, 0x1F,   /* line 5 */

                      0xFF, 0xF8, 0x00, 0x0F,   /* line 6 */

                      0xFF, 0xF8, 0x00, 0x0F,   /* line 7 */

                      0xFF, 0xF0, 0x00, 0x07,   /* line 8 */

                      0xFF, 0xF0, 0x00, 0x03,   /* line 9 */

                      0xFF, 0xE0, 0x00, 0x03,   /* line 10 */

                      0xFF, 0xE0, 0x00, 0x01,   /* line 11 */

                      0xFF, 0xE0, 0x00, 0x01,   /* line 12 */

                      0xFF, 0xF0, 0x00, 0x01,   /* line 13 */

                      0xFF, 0xF0, 0x00, 0x00,   /* line 14 */

                      0xFF, 0xF8, 0x00, 0x00,   /* line 15 */

                      0xFF, 0xFC, 0x00, 0x00,   /* line 16 */

                      0xFF, 0xFF, 0x00, 0x00,   /* line 17 */

                      0xFF, 0xFF, 0x80, 0x00,   /* line 18 */

                      0xFF, 0xFF, 0xE0, 0x00,   /* line 19 */

                      0xFF, 0xFF, 0xE0, 0x01,   /* line 20 */

                      0xFF, 0xFF, 0xF0, 0x01,   /* line 21 */

                      0xFF, 0xFF, 0xF0, 0x01,   /* line 22 */

                      0xFF, 0xFF, 0xF0, 0x03,   /* line 23 */

                      0xFF, 0xFF, 0xE0, 0x03,   /* line 24 */

                      0xFF, 0xFF, 0xE0, 0x07,   /* line 25 */

                      0xFF, 0xFF, 0xC0, 0x0F,   /* line 26 */

                      0xFF, 0xFF, 0xC0, 0x0F,   /* line 27 */

                      0xFF, 0xFF, 0x80, 0x1F,   /* line 28 */

                      0xFF, 0xFF, 0x00, 0x7F,   /* line 29 */

                      0xFF, 0xFC, 0x00, 0xFF,   /* line 30 */

                      0xFF, 0xF8, 0x03, 0xFF,   /* line 31 */

                      0xFF, 0xFC, 0x3F, 0xFF};  /* line 32 */

/* Yang icon XOR bitmask */

BYTE XORmaskIcon[] = {0x00, 0x00, 0x00, 0x00,   /* line 1 */

                      0x00, 0x00, 0x00, 0x00,   /* line 2 */

                      0x00, 0x00, 0x00, 0x00,   /* line 3 */

                      0x00, 0x00, 0x00, 0x00,   /* line 4 */

                      0x00, 0x00, 0x00, 0x00,   /* line 5 */

                      0x00, 0x00, 0x00, 0x00,   /* line 6 */

                      0x00, 0x00, 0x00, 0x00,   /* line 7 */

                      0x00, 0x00, 0x38, 0x00,   /* line 8 */

                      0x00, 0x00, 0x7C, 0x00,   /* line 9 */

                      0x00, 0x00, 0x7C, 0x00,   /* line 10 */

                      0x00, 0x00, 0x7C, 0x00,   /* line 11 */

                      0x00, 0x00, 0x38, 0x00,   /* line 12 */

                      0x00, 0x00, 0x00, 0x00,   /* line 13 */

                      0x00, 0x00, 0x00, 0x00,   /* line 14 */

                      0x00, 0x00, 0x00, 0x00,   /* line 15 */

                      0x00, 0x00, 0x00, 0x00,   /* line 16 */

                      0x00, 0x00, 0x00, 0x00,   /* line 17 */

                      0x00, 0x00, 0x00, 0x00,   /* line 18 */

                      0x00, 0x00, 0x00, 0x00,   /* line 19 */

                      0x00, 0x00, 0x00, 0x00,   /* line 20 */

                      0x00, 0x00, 0x00, 0x00,   /* line 21 */

                      0x00, 0x00, 0x00, 0x00,   /* line 22 */

                      0x00, 0x00, 0x00, 0x00,   /* line 23 */

                      0x00, 0x00, 0x00, 0x00,   /* line 24 */

                      0x00, 0x00, 0x00, 0x00,   /* line 25 */

                      0x00, 0x00, 0x00, 0x00,   /* line 26 */

                      0x00, 0x00, 0x00, 0x00,   /* line 27 */

                      0x00, 0x00, 0x00, 0x00,   /* line 28 */

                      0x00, 0x00, 0x00, 0x00,   /* line 29 */

                      0x00, 0x00, 0x00, 0x00,   /* line 30 */

                      0x00, 0x00, 0x00, 0x00,   /* line 31 */

                      0x00, 0x00, 0x00, 0x00};  /* line 32 */

hIcon1 = CreateIcon(hinstance, /* handle of app instance   */

             32,           /* icon width                   */

             32,           /* icon height                  */

             1,            /* number of XOR planes         */

             1,            /* number of bits per pixel     */

             ANDmaskIcon,  /* AND bitmask                  */

             XORmaskIcon); /* XOR bitmask                  */

hCurs1 = CreateCursor(hinstance, /* handle of app instance */

             19,         /* horiz. position of hot spot    */

             2,          /* vert. position of hot spot     */

             32,         /* cursor width                   */

             32,         /* cursor height                  */

             ANDmaskCursor,            /* AND bitmask      */

             XORmaskCursor);           /* XOR bitmask      */

.

. /* Fill in the window class structure. */

.

WNDCLASS  wc;

wc.hIcon = hIcon1;                        /* class icon   */

wc.hCursor = LoadCursor(NULL, IDC_ARROW); /* class cursor */

.

. /*

. * Register the window class and perform

. * other application initialization.

. */

.

/* Set a timer for the mousetrap. */

GetCursorPos(&ptOld);

SetTimer(hwnd, IDT_CURSOR, 10000, (TIMERPROC) NULL);

LONG APIENTRY MainWndProc(

    HWND hwnd,          /* window handle          */

    UINT message,       /* type of message        */

    UINT wParam,        /* additional information */

    LONG lParam)        /* additional information */

{

    HDC hdc;              /* handle of device context */

    POINT pt;             /* current cursor location  */

    RECT rc;              /* iconized window location */

    switch (message) {

         .

         . /* Process other messages. */

         .

        case WM_TIMER:

            /*

             * If the window is minimized, compare the current

             * cursor position with the one 10 seconds before.

             * If the cursor position has not changed, move the

             * cursor to the icon.

             */

            if (IsIconic(hwnd)) {

                GetCursorPos(&pt);

                if ((pt.x == ptOld.x) && (pt.y == ptOld.y)) {

                    GetWindowRect(hwnd, &rc);

                    SetCursorPos(rc.left + 20, rc.top + 4);

                    /*

                     * Note that the additional constants

                     * (20 and 4) are application-specific

                     * values to align the yin-shaped cursor

                     * and the yang-shaped icon.

                     */

                }

                else {

                    ptOld.x = pt.x;

                    ptOld.y = pt.y;

                }

            }

            return 0;

        case WM_SETCURSOR:

            /*

             * If the window is minimized, draw hCurs1.

             * If the window is not minimized, draw the default

             * cursor (class cursor).

             */

            if (IsIconic(hwnd)) {

                SetCursor(hCurs1);

                break;

            }

        case WM_DESTROY:

            /* Destroy timer. */

            KillTimer(hwnd, IDT_CURSOR);

            PostQuitMessage(0);

            break;

                .

                . /* Process other messages. */

                .

    }             /* ends switch (message) */


Moving the Cursor With the Keyboard

Using the Keyboard to Move the Cursor

Because Windows does not require a mouse, an application should be able to simulate mouse actions with the keyboard. The following example shows how to achieve this, by using the GetCursorPos and SetCursorPos functions, and by processing input from the arrow keys.

HCURSOR hCurs1, hCurs2;    /* cursor handles        */

POINT pt;                  /* cursor location         */

RECT rc;                   /* client area coordinates */

static int repeat = 1;     /* repeat key counter      */

.

. /* Other declarations and initialization. */

.

switch (message) {

.

. /* Process other messages. */

.

    case WM_KEYDOWN:

        if (wParam != VK_LEFT && wParam != VK_RIGHT &&

        wParam != VK_UP && wParam != VK_DOWN) {

            break;

        }

        GetCursorPos(&pt);

        /* Convert screen coordinates to client coordinates. */

        ScreenToClient(hwnd, &pt);

        switch (wParam) {

            /*

             * Move the cursor to reflect which

             * arrow keys are pressed.

             */

            case VK_LEFT: /* left arrow */

                pt.x -= repeat;

                break;

            case VK_RIGHT: /* right arrow */

                pt.x += repeat;

                break;

            case VK_UP: /* up arrow */

                pt.y -= repeat;

                break;

            case VK_DOWN: /* down arrow */

                pt.y += repeat;

                break;

            default:

                return NULL;

        }

        repeat++;           /* increments repeat count */

        /* Keep the cursor in the client area. */

        GetClientRect(hwnd, &rc);

        if (pt.x >= rc.right) {

            pt.x = rc.right - 1;

        }

        else {

            if (pt.x < rc.left) {

                pt.x = rc.left;

            }

        }

        if (pt.y >= rc.bottom) {

            pt.y = rc.bottom - 1;

        }

        else {

            if (pt.y < rc.top) {

                pt.y = rc.top;

            }

        }

        /* Convert client coordinates to screen coordinates. */

        ClientToScreen(hwnd, &pt);

        SetCursorPos(pt.x, pt.y);

        break;

    case WM_KEYUP:

        repeat = 1;            /* clears repeat count */

        break;

        .

        .

        .

    }               /* ends switch (message) */


Functions

Functions and Messages

The following functions and messages are used with cursors.

Functions

ClipCursor

CopyCursor

CreateCursor

DestroyCursor

GetClipCursor

GetCursor

GetCursorPos

LoadCursor

SetCursor

SetCursorPos

ShowCursor

Messages

WM_SETCURSOR


Carets Overview

About Carets

A caret is a flashing line, block, or bitmap in the client area of a window; the caret typically indicates the place at which text or graphics will be inserted. The following illustration shows some common variations in the appearance of the caret.

The following topics discuss Win32 carets:

Terms

Creating and Displaying a Caret

Hiding a Caret

Destroying the Caret

Adjusting the Blink Time

Processing Keyboard Input

Functions

Because only one window at a time can have the keyboard focus or be active, there is only one caret in the system. Generally, each window that accepts keyboard input must create the caret when it receives the keyboard focus and destroy the caret when it loses the keyboard focus.

An application written for Microsoft® Windows™ can create a caret, display or hide it, relocate the caret, and change its blink time.

An application uses the CreateCaret function to specify the parameters for a caret. Microsoft Windows forms a caret by inverting the pixel color within the rectangle specified by the caret's position, width, and height. The width and height are specified in logical units; therefore, the appearance of a caret is subject to the window's mapping mode.

After the caret is defined, an application uses the ShowCaret function to make the caret visible. When the caret appears, it automatically begins flashing. To display a solid caret, Windows inverts every pixel in the rectangle; to display a gray caret, Windows inverts every other pixel; to display a bitmap caret, Windows inverts only the white bits of the bitmap.

The elapsed time, in milliseconds, required to invert the caret is called the blink time. An application can determine the caret's blink time by using the GetCaretBlinkTime function. If it is necessary to define a specific blink time, use the SetCaretBlinkTime function to set the rate of the blink time to a specified number of milliseconds. The flash time is the elapsed time, in milliseconds, required to display, invert, and restore the caret's display. The flash time of a caret is twice as much as the blink time.

An application can determine the caret's position by using the GetCaretPos function. The position, in client coordinates, is copied to a POINT structure specified by a parameter in GetCaretPos. An application can move a caret in a window by using the SetCaretPos function. A window can move a caret only if it already owns the caret. SetCaretPos can move the caret whether it is visible or not.

An application can use the HideCaret function to remove the caret from the screen. This is useful when your application must redraw the screen while processing a message but must keep the caret out of the way. When the application finishes drawing, it can display the caret again by using the ShowCaret function. Hiding the caret does not destroy its shape or invalidate the insertion point. Hiding the caret is cumulative; that is, if the application calls HideCaret five times, it must also call ShowCaret five times before the caret will reappear.

An application can remove the caret from the screen and destroy its shape by using the DestroyCaret function. DestroyCaret destroys the caret only if the window involved in the current task owns the caret.


Creating and Displaying a Caret

Upon receiving the keyboard focus, the window should create and display the caret. Use the CreateCaret function to create a caret in the given window. Then call SetCaretPos to set the current position of the caret and ShowCaret to make the caret visible.

The system sends the WM_SETFOCUS message to the window receiving keyboard focus; therefore, an application should create and display the caret while processing this message.

HWND hwnd,   /* window handle                   */

int x;       /* horizontal coordinate of cursor */

int y;       /* vertical coordinate of cursor   */

int nWidth;      /* width of cursor             */

int nHeight;     /* height of cursor            */

char *lpszChar;  /* pointer to character        */

    case WM_SETFOCUS:

        /* Create a solid black caret. */

        CreateCaret(hwnd, (HBITMAP) NULL, nWidth, nHeight);

        /* Adjust the caret position, in client coordinates. */

        SetCaretPos(x, y);

        /* Display the caret. */

        ShowCaret(hwnd);

        break;

To create a caret based on a bitmap, you must specify a bitmap handle when using CreateCaret. You can use a graphics application to create the bitmap and a resource compiler to add the bitmap to your application's resources. Your application can then use the LoadBitmap function to load the bitmap handle. For example, you could replace the CreateCaret line in the preceding example with the following lines to create a bitmap caret.

/* Load the application-defined caret resource. */

hCaret = LoadBitmap(hinst, MAKEINTRESOURCE(120));

/* Create a bitmap caret. */

CreateCaret(hwnd, hCaret, 0, 0);

Alternatively, you can use the CreateBitmap or CreateDIBitmap function to retrieve the handle of the caret bitmap.

If your application specifies a bitmap handle, CreateCaret ignores the width and height parameters. The bitmap defines the size of the caret.


Hiding a Caret

Whenever your application redraws a screen while processing a message other than WM_PAINT, it must make the caret invisible by using the HideCaret function. When your application is finished drawing, redisplay the caret by using the ShowCaret function. If your application processes the WM_PAINT message, it is not necessary to hide and redisplay the caret, because this function does this automatically.

The following code sample shows how to have your application hide the caret while drawing a character on the screen and while processing the WM_CHAR message.

HWND hwnd,   /* window handle                   */

HDC hdc;     /* device context                  */

    case WM_CHAR:

        switch (wParam) {

            case 0x08:

                break;

            case 0x09:

                break;

            case 0x0D:

                break;

            case 0x1B:

                break;

            case 0x0A:

                break;

            default:

                /* Process all other characters. */

                /* Hide the caret. */

                HideCaret(hwnd);

                /* Draw the character on the screen. */

                hdc = GetDC(hwnd);

                SelectObject(hdc,

                    GetStockObject(SYSTEM_FIXED_FONT));

                TextOut(hdc, x, y, lpszChar, 1);

                ReleaseDC(hwnd, hdc);

                /* Display the caret. */

                ShowCaret(hwnd);

        }

If your application calls the HideCaret function several times without calling ShowCaret, the caret will not be displayed until the application also calls ShowCaret the same number of times.


Destroying the Caret

Destroying a Caret

When a window loses the keyboard focus, the system sends the WM_KILLFOCUS message to the window. Your application should destroy the caret while processing this message by using the DestroyCaret function. The following code shows how to destroy a caret in a window that no longer has the keyboard focus.

case WM_KILLFOCUS:

    /*

     * The window is losing the keyboard focus,

     * so destroy the caret.

     */

    DestroyCaret();

    break;


Adjusting the Blink Time

Because there is only one caret in the system, use caution when your application must adjust the rate of the blink time, so as not to disrupt subsequent windows that may receive the keyboard focus. If your application changes the blink time, it must restore the blink time to its original value upon losing the keyboard focus. The GetCaretBlinkTime function returns the current blink time, in milliseconds, and the SetCaretBlinkTime function sets the blink time to the specified number of milliseconds.

If you anticipate that your application will adjust the blink time, add the following line to the WM_SETFOCUS message processing:

uOldBlink = GetCaretBlinkTime();

Then, you can restore the blink time to its original rate by including the following line in the WM_KILLFOCUS message processing:

SetCaretBlinkTime(uOldBlink);


Processing Keyboard Input

The following code sample demonstrates how to use a caret in a simple text editor. The code updates the caret position as the user types printable characters and uses various keys to move through the client area.

#define TEXTMATRIX(x, y) *(pTextMatrix + (y * nWindowCharsX) + x)

HINSTANCE hinst;           /* current instance                 */

HBITMAP hCaret;            /* caret bitmap                     */

HDC hdc;                   /* device context                   */

PAINTSTRUCT ps;            /* client area paint info           */

static char *pTextMatrix = NULL;   /* pointer to text matrix   */

static int  nCharX,        /* width of char. in logical units  */

            nCharY,        /* height of char. in logical units */

            nWindowX,      /* width of client area             */

            nWindowY,      /* height of client area            */

            nWindowCharsX, /* width of client area in char.s   */

            nWindowCharsY, /* height of client area in char.s  */

            nCaretPosX,    /* x-position of caret in matrix    */

            nCaretPosY;    /* y-position of caret in matrix    */

static UINT uOldBlink;     /* holds previous blink rate        */

int x, y;       /* x and y coordinates to use in text matrix   */

TEXTMETRIC tm;             /* font information                 */

LONG APIENTRY MainWndProc(

    HWND hwnd,            /* window handle              */

    UINT message,         /* type of message            */

    UINT wParam,          /* additional information     */

    LONG lParam)          /* additional information     */

{

switch (message) {

    case WM_CREATE:

        /*

         * Select a fixed-width system font,

         * and get the text metrics of the font.

         */

        hdc = GetDC(hwnd);

        SelectObject(hdc, GetStockObject(SYSTEM_FIXED_FONT));

        GetTextMetrics(hdc, &tm);

        ReleaseDC(hwnd, hdc);

        /* Save the avg. width and height of the characters. */

        nCharX = tm.tmAveCharWidth;

        nCharY = tm.tmHeight;

        return 0;

    case WM_SIZE:

        /*

         * Determine the width of the client area, in pixels

         * and in number of characters.

         */

        nWindowX = LOWORD(lParam);

        nWindowCharsX = max(1, nWindowX/nCharX);

        /*

         * Determine the height of the client area, in pixels

         * and in number of characters.

         */

        nWindowY = HIWORD(lParam);

        nWindowCharsY = max(1, nWindowY/nCharY);

        /* Clear the buffer that holds the text input. */

        if (pTextMatrix != NULL) {

            free(pTextMatrix);

        }

        /*

         * If there is enough memory, allocate space for the

         * text input buffer.

         */

        pTextMatrix = malloc(nWindowCharsX * nWindowCharsY);

        if (pTextMatrix == NULL) {

            ErrorHandler("Not enough memory.");

        }

        else {

            for (y = 0; y < nWindowCharsY; y++)

                for (x = 0; x < nWindowCharsX; x++)

                    TEXTMATRIX(x, y) = ' ';

        }

        /* Move the caret to the origin. */

        SetCaretPos(0, 0);

        return 0;

    case WM_KEYDOWN:

        switch (wParam) {

            case VK_HOME: /* Home */

                nCaretPosX = 0;

                break;

            case VK_END: /* End */

                nCaretPosX = nWindowCharsX - 1;

                break;

            case VK_PRIOR: /* Page Up */

                nCaretPosY = 0;

                break;

            case VK_NEXT: /* Page Down */

                nCaretPosY = nWindowCharsY -1;

                break;

            case VK_LEFT: /* Left arrow */

                nCaretPosX = max(nCaretPosX - 1, 0);

                break;

            case VK_RIGHT: /* Right arrow */

                nCaretPosX = min(nCaretPosX + 1,

                    nWindowCharsX - 1);

                break;

            case VK_UP: /* Up arrow */

                nCaretPosY = max(nCaretPosY - 1, 0);

                break;

            case VK_DOWN: /* Down arrow */

                nCaretPosY = min(nCaretPosY + 1,

                    nWindowCharsY - 1);

                break;

            case VK_DELETE: /* Delete */

                /*

                 * Move all the characters that followed the

                 * deleted character (on the same line) one

                 * space back (to the left) in the matrix.

                 */

                for (x = nCaretPosX; x < nWindowCharsX; x++)

                    TEXTMATRIX(x, nCaretPosY) =

                        TEXTMATRIX(x + 1, nCaretPosY);

                /*

                 * Replace the last character on the

                 * line with a space.

                 */

                TEXTMATRIX(nWindowCharsX - 1,

                    nCaretPosY) = ' ';

                /*

                 * The application will draw outside the

                 * WM_PAINT message processing, so hide the

                 * caret.

                 */

                HideCaret(hwnd);

                /*

                 * Redraw the line, adjusted for the

                 * deleted character.

                 */

                hdc = GetDC(hwnd);

                SelectObject(hdc,

                    GetStockObject(SYSTEM_FIXED_FONT));

                TextOut(hdc,

                    nCaretPosX * nCharX, nCaretPosY * nCharY,

                    &TEXTMATRIX(nCaretPosX, nCaretPosY),

                    nWindowCharsX - nCaretPosX);

                ReleaseDC(hwnd, hdc);

                /* Display the caret. */

                ShowCaret(hwnd);

                break;

        }

        /*

         * Adjust the caret position based on the

         * virtual-key processing.

         */

        SetCaretPos(nCaretPosX * nCharX, nCaretPosY * nCharY);

        return 0;

    case WM_CHAR:

        switch (wParam) {

            case 0x08: /* Backspace */

                /*

                 * Move the caret back one space, and then process

                 * this like the DEL key.

                 */

                if (nCaretPosX > 0) {

                    nCaretPosX--;

                    SendMessage(hwnd, WM_KEYDOWN,

                        VK_DELETE, 1L);

                }

                break;

            case 0x09: /* Tab */

                /*

                 * Tab stops exist every four spaces, so add

                 * spaces until the user hits the next tab stop.

                 */

                do {

                    SendMessage(hwnd, WM_CHAR, ' ', 1L);

                } while (nCaretPosX % 4 != 0);

                break;

            case 0x0D: /* Carriage return */

                /*

                 * Go to the beginning of the next line.

                 * The bottom line wraps around to the top.

                 */

                nCaretPosX = 0;

                if (++nCaretPosY == nWindowCharsY) {

                    nCaretPosY = 0;

                }

                break;

            case 0x1B: /* Escape */

            case 0x0A: /* Linefeed */

                /* No processing. */

                MessageBeep((UINT) -1);

                break;

            default: /* all other characters */

                /* Add the character to the text buffer. */

                TEXTMATRIX(nCaretPosX, nCaretPosY) =

                    (char) wParam;

                /*

                 * The application will draw outside the

                 * WM_PAINT message processing, so hide the

                 * caret.

                 */

                HideCaret(hwnd);

                /* Draw the character on the screen. */

                hdc = GetDC(hwnd);

                SelectObject(hdc,

                    GetStockObject(SYSTEM_FIXED_FONT));

                TextOut(hdc, nCaretPosX * nCharX,

                    nCaretPosY * nCharY,

                    &TEXTMATRIX(nCaretPosX, nCaretPosY), 1);

                ReleaseDC(hwnd, hdc);

                /* Display the caret. */

                ShowCaret(hwnd);

                /*

                 * Prepare to wrap around if you reached the

                 * end of the line.

                 */

                if (++nCaretPosX == nWindowCharsX) {

                    nCaretPosX = 0;

                    if (++nCaretPosY == nWindowCharsY) {

                        nCaretPosY = 0;

                    }

                }

                break;

        }

        /*

         * Adjust the caret position based on the

         * character processing.

         */

        SetCaretPos(nCaretPosX * nCharX, nCaretPosY * nCharY);

        return 0;

    case WM_PAINT:

        /* Draw all the characters in the buffer, line by line. */

        hdc = BeginPaint(hwnd, &ps);

        SelectObject(hdc, GetStockObject(SYSTEM_FIXED_FONT));

        for (y = 0; y < nWindowCharsY; y++)

            TextOut(hdc, 0, y * nCharY, &TEXTMATRIX(0, y),

                nWindowCharsX);

        EndPaint(hwnd, &ps);

    case WM_SETFOCUS:

        /*

         * The window has the input focus. Load the

         * application-defined caret resource.

         */

        hCaret = LoadBitmap(hinst, MAKEINTRESOURCE(120));

        /* Create the caret. */

        CreateCaret(hwnd, hCaret, 0, 0);

        /* Adjust the caret position. */

        SetCaretPos(nCaretPosX * nCharX, nCaretPosY * nCharY);

        /* Display the caret. */

        ShowCaret(hwnd);

        break;

    case WM_KILLFOCUS:

        /*

         * The window is losing the input focus,

         * so destroy the caret.

         */

        DestroyCaret();

        break;

    default: /* passes it on if unprocessed */

        return DefWindowProc(hwnd, message, wParam, lParam);

}                       /* ends switch (message)      */

    return NULL;

}                       /* ends main window procedure */


Functions

The following functions are used with carets.

CreateCaret

DestroyCaret

GetCaretBlinkTime

GetCaretPos

HideCaret

SetCaretBlinkTime

SetCaretPos

ShowCaret


Icons Overview

About Icons

An icon is a small bitmap that usually represents a minimized application, but can also illustrate a warning message or other window. If an icon represents a minimized application, the user can move the icon or size the window by using the mouse or other pointing device. Icons that do not represent minimized applications cannot be moved by the mouse. The icon functions in Microsoft® Windows™ enable applications to create, load, display, arrange, destroy, and retrieve information about icons.

The following topics discuss Win32 icons:

Terms

The Hot Spot

Icon Creation

Icon Display

Icon Destruction

Icon Duplication

Creating an Icon

Displaying an Icon

Creating a Mousetrap

Sharing Icon Resources

Functions

Windows supports two kinds of icons: standard and custom. Standard icons are predefined icons that Windows displays in system message boxes. The Windows display driver files provide five standard icons, such as the stop sign, for use by the operating system or by any Windows-based application. The following illustration shows the standard icons and their identifiers.

Custom icons are designed to represent a particular application and can be any design the developer defines. Following are several custom icons.


The Hot Spot

In the center of an icon, one pixel called the hot spot is the point the system tracks and recognizes as the position of the icon. Unlike the cursor's hot spot, which can be any pixel in the cursor bitmap, the icon hot spot is always in the center of the icon bitmap.


Icon Creation

Standard icons are predefined by Windows, so it is not necessary to create them. To use a standard icon, an application can obtain its handle by using the LoadIcon function. An icon handle is a unique value of the HICON type that identifies a standard or custom icon.

To create a custom icon for an application, developers typically use a graphics application and include the icon as a resource in the application's resource-definition file. At run time, an application can call LoadIcon to retrieve the handle of the icon. An icon resource contains data for several different display devices. LoadIcon automatically selects the most appropriate data for the current display device.

An application can also create a custom icon at run time by using the CreateIcon function. This function creates an icon of the specified size, colors, and bit patterns.

Applications should implement custom icons as resources and should use LoadIcon, rather than create the icon at run time. Using icon resources avoids device dependence, simplifies localization, and enables applications to share icon shapes.

Alternative Icon Creation

Two other functions can create icons at run time: CreateIconFromResource and CreateIconIndirect. These functions enable an application to browse through the system's resources and create icons and cursors based on resource data. CreateIconFromResource creates an icon based on binary resource data from other executable files or dynamic-link libraries. An application must precede this function with calls to the LookupIconIDFromDirectory function and several of the resource functions. LookupIconIDFromDirectory returns the identifier of the most appropriate icon data for the current display device.

CreateIconIndirect creates an icon based on the contents of an ICONINFO structure. The GetIconInfo function fills this structure with the hot spot coordinates and information about the bitmask bitmap and color bitmap for the icon.


Icon Display

The Win32 application programming interface (API) provides several functions that display and manipulate icons. Once an application has loaded an icon, it can use DrawIcon to draw the icon at a specified location in a window's client area. ArrangeIconicWindows arranges all of the minimized child windows in a parent window. OpenIcon activates and restores a minimized window to its previous size and location. IsIconic tests to see whether a window is minimized.

DrawIcon requires that the icon be loaded; the other functions do not. ArrangeIconicWindows, OpenIcon, and IsIconic operate on minimized windows, which may or may not have an icon drawn on top.

The Window Class Icon

While registering a window class, applications can assign a default icon, known as the class icon, to the class. After the application registers the window class, each window of that class will have that class icon when it is minimized. When the user minimizes a window, Windows uses the DrawIcon function to paint the class icon.

To override a class icon, an application can process the WM_PAINTICON message. Applications can also replace the class icon by using the SetClassLong function. This function changes the default window settings for all windows of a given class.


Icon Destruction

When an application no longer needs an icon it created by using CreateIcon, it should destroy the icon. The DestroyIcon function destroys the icon handle and frees any memory used by the icon. Applications should use this function only for icons created with CreateIcon; it is not necessary to destroy other icons.


Icon Duplication

The CopyIcon function copies an icon handle. This enables an application or dynamic-link library to get its own handle for an icon owned by another module. Then, if the other module is freed, the application that copied the icon will still be able to use the icon.


Creating an Icon

To use an icon, your application must get the handle of the icon. The following example shows how to create two different icon handles: one for the standard exclamation icon and one for a custom icon included as a resource in the application's resource-definition file.

HICON hIcon1;   /* icon handle            */

HICON hIcon2;   /* icon handle            */

/* Create a standard question icon. */

hIcon1 = LoadIcon(NULL, IDI_QUESTION);

/* Create a custom icon based on a resource. */

hIcon2 = LoadIcon(hinst, MAKEINTRESOURCE(460));

/* Create a custom icon at run time. */

An application should implement custom icons as resources and should use LoadIcon, rather than create the icons at run time. This approach avoids device dependence, simplies localization, and enables applications to share icon bitmaps. However, the following code uses CreateIcon to create a custom icon at run time, based on bitmap bitmasks. It is included to illustrate how the system interprets icon bitmap bitmasks.

HICON hIcon3;               /* icon handle        */

/* Yang icon AND bitmask */

BYTE ANDmaskIcon[] = {0xFF, 0xFF, 0xFF, 0xFF,   /* line 1 */

                      0xFF, 0xFF, 0xC3, 0xFF,   /* line 2 */

                      0xFF, 0xFF, 0x00, 0xFF,   /* line 3 */

                      0xFF, 0xFE, 0x00, 0x7F,   /* line 4 */

                      0xFF, 0xFC, 0x00, 0x1F,   /* line 5 */

                      0xFF, 0xF8, 0x00, 0x0F,   /* line 6 */

                      0xFF, 0xF8, 0x00, 0x0F,   /* line 7 */

                      0xFF, 0xF0, 0x00, 0x07,   /* line 8 */

                      0xFF, 0xF0, 0x00, 0x03,   /* line 9 */

                      0xFF, 0xE0, 0x00, 0x03,   /* line 10 */

                      0xFF, 0xE0, 0x00, 0x01,   /* line 11 */

                      0xFF, 0xE0, 0x00, 0x01,   /* line 12 */

                      0xFF, 0xF0, 0x00, 0x01,   /* line 13 */

                      0xFF, 0xF0, 0x00, 0x00,   /* line 14 */

                      0xFF, 0xF8, 0x00, 0x00,   /* line 15 */

                      0xFF, 0xFC, 0x00, 0x00,   /* line 16 */

                      0xFF, 0xFF, 0x00, 0x00,   /* line 17 */

                      0xFF, 0xFF, 0x80, 0x00,   /* line 18 */

                      0xFF, 0xFF, 0xE0, 0x00,   /* line 19 */

                      0xFF, 0xFF, 0xE0, 0x01,   /* line 20 */

                      0xFF, 0xFF, 0xF0, 0x01,   /* line 21 */

                      0xFF, 0xFF, 0xF0, 0x01,   /* line 22 */

                      0xFF, 0xFF, 0xF0, 0x03,   /* line 23 */

                      0xFF, 0xFF, 0xE0, 0x03,   /* line 24 */

                      0xFF, 0xFF, 0xE0, 0x07,   /* line 25 */

                      0xFF, 0xFF, 0xC0, 0x0F,   /* line 26 */

                      0xFF, 0xFF, 0xC0, 0x0F,   /* line 27 */

                      0xFF, 0xFF, 0x80, 0x1F,   /* line 28 */

                      0xFF, 0xFF, 0x00, 0x7F,   /* line 29 */

                      0xFF, 0xFC, 0x00, 0xFF,   /* line 30 */

                      0xFF, 0xF8, 0x03, 0xFF,   /* line 31 */

                      0xFF, 0xFC, 0x3F, 0xFF};  /* line 32 */

/* Yang icon XOR bitmask */

BYTE XORmaskIcon[] = {0x00, 0x00, 0x00, 0x00,   /* line 1 */

                      0x00, 0x00, 0x00, 0x00,   /* line 2 */

                      0x00, 0x00, 0x00, 0x00,   /* line 3 */

                      0x00, 0x00, 0x00, 0x00,   /* line 4 */

                      0x00, 0x00, 0x00, 0x00,   /* line 5 */

                      0x00, 0x00, 0x00, 0x00,   /* line 6 */

                      0x00, 0x00, 0x00, 0x00,   /* line 7 */

                      0x00, 0x00, 0x38, 0x00,   /* line 8 */

                      0x00, 0x00, 0x7C, 0x00,   /* line 9 */

                      0x00, 0x00, 0x7C, 0x00,   /* line 10 */

                      0x00, 0x00, 0x7C, 0x00,   /* line 11 */

                      0x00, 0x00, 0x38, 0x00,   /* line 12 */

                      0x00, 0x00, 0x00, 0x00,   /* line 13 */

                      0x00, 0x00, 0x00, 0x00,   /* line 14 */

                      0x00, 0x00, 0x00, 0x00,   /* line 15 */

                      0x00, 0x00, 0x00, 0x00,   /* line 16 */

                      0x00, 0x00, 0x00, 0x00,   /* line 17 */

                      0x00, 0x00, 0x00, 0x00,   /* line 18 */

                      0x00, 0x00, 0x00, 0x00,   /* line 19 */

                      0x00, 0x00, 0x00, 0x00,   /* line 20 */

                      0x00, 0x00, 0x00, 0x00,   /* line 21 */

                      0x00, 0x00, 0x00, 0x00,   /* line 22 */

                      0x00, 0x00, 0x00, 0x00,   /* line 23 */

                      0x00, 0x00, 0x00, 0x00,   /* line 24 */

                      0x00, 0x00, 0x00, 0x00,   /* line 25 */

                      0x00, 0x00, 0x00, 0x00,   /* line 26 */

                      0x00, 0x00, 0x00, 0x00,   /* line 27 */

                      0x00, 0x00, 0x00, 0x00,   /* line 28 */

                      0x00, 0x00, 0x00, 0x00,   /* line 29 */

                      0x00, 0x00, 0x00, 0x00,   /* line 30 */

                      0x00, 0x00, 0x00, 0x00,   /* line 31 */

                      0x00, 0x00, 0x00, 0x00};  /* line 32 */

hIcon3 = CreateIcon(hinst,    /* application instance     */

             32,              /* icon width               */

             32,              /* icon height              */

             1,               /* number of XOR planes     */

             1,               /* number of bits per pixel */

             ANDmaskIcon,     /* AND bitmask              */

             XORmaskIcon);    /* XOR bitmask              */

To create the icon, 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

Before closing, your application must use DestroyIcon to destroy any icon it created by using CreateIcon. It is not necessary to destroy icons created by other functions.


Displaying an Icon

Your application can load and create icons to display in the application's client area or child windows. The following code demonstrates how to draw an icon in the client area of the window whose display context is identified by hdc.

HICON hIcon1;   /* icon handle               */

HDC hdc;        /* handle of display context */

DrawIcon(hdc, 10, 20, hIcon1);

Windows automatically displays the class icon--the icon associated with the window--when the window is minimized. Your application can assign a class icon while registering a window class. The following example assigns an icon handle to the hIcon member of the WNDCLASS structure identified by wc.

wc.hIcon = LoadIcon(hinstance, MAKEINTRESOURCE(430));

When the window class is registered, the icon identified by 430 in the application's resource-definition file will be the default icon for all windows based on the class.

Your application can replace a class icon by using SetClassLong. This function changes the default window settings for all windows of a given class. The following example replaces the existing class icon with the icon whose resource identifier is 480.

HINSTANCE hinst;            /* handle of current instance */

HWND hwnd;                  /* main window handle         */

/* Change the icon for hwnd's window class. */

SetClassLong(hwnd,         /* window handle */

    GCL_HICON,             /* changes icon  */

    (LONG) LoadIcon(hinst, MAKEINTRESOURCE(480))); /* new */

Managing the Icon Background

If your application assigns a class icon, Windows automatically repaints the icon's background whenever it repaints the icon. Your application can prevent Windows from painting the background by processing the WM_ICONERASEBKGND message.

If your application sets the class icon to NULL, there is no icon associated with the window class. In this situation, Windows sends the WM_ERASEBKGND message to the window whenever it paints the icon. If the window does not process this message, Windows draws part of the window's client area onto the iconic window.


Creating a Mousetrap

The following code sample uses IsIconic, LoadIcon, and several cursor and timer functions to create a simple mousetrap. The example uses the cursor and timer functions to monitor the location of the cursor at 10-second intervals. If the cursor location has not changed in the last 10 seconds and the application's main window is minimized, the application changes the cursor shape and moves the cursor to the icon.

HICON hIcon1;              /* icon handle                */

POINT ptOld;               /* previous cursor location   */

HCURSOR hCurs1;            /* cursor handle              */

HINSTANCE hinstance;       /* handle of current instance */

hCurs1 = LoadCursor(hinstance, MAKEINTRESOURCE(220));

.

. /* Fill in the window class structure. */

.

WNDCLASS  wc;

wc.hIcon = LoadIcon(hinstance, MAKEINTRESOURCE(470));

wc.hCursor = LoadCursor(hinstance, MAKEINTRESOURCE(240));

.

. /*

. * Register the window class and perform

. * other application initialization.

. */

.

/* Set a timer for the mousetrap. */

GetCursorPos(&ptOld);

SetTimer(hwnd, IDT_CURSOR, 10000, (TIMERPROC) NULL);

LONG APIENTRY MainWndProc(

    HWND hwnd,          /* window handle            */

    UINT message,       /* type of message          */

    UINT wParam,        /* additional information   */

    LONG lParam)        /* additional information   */

{

    HDC hdc;            /* device context handle    */

    POINT pt;           /* current cursor location  */

    RECT rc;            /* iconized window location */

    switch (message) {

         .

         . /* Process other messages here. */

         .

        case WM_TIMER:

            /*

             * If the window is minimized, compare the current

             * cursor position with the one from 10 seconds

             * earlier. If the cursor position has not changed,

             * move the cursor to the icon.

             */

            if (IsIconic(hwnd)) {

                GetCursorPos(&pt);

                if ((pt.x == ptOld.x) && (pt.y == ptOld.y)) {

                    GetWindowRect(hwnd, &rc);

                    SetCursorPos(rc.left, rc.top);

                }

                else {

                    ptOld.x = pt.x;

                    ptOld.y = pt.y;

                }

            }

            return 0;

        case WM_SETCURSOR:

            /*

             * If the window is minimized, draw hCurs1.

             * If the window is not minimized, draw the default

             * cursor (class cursor).

             */

            if (IsIconic(hwnd)) {

                SetCursor(hCurs1);

                break;

            }

        case WM_DESTROY:

            /* Destroy the timer. */

            KillTimer(hwnd, IDT_CURSOR);

            PostQuitMessage(0);

            break;

                .

                . /* Process other messages here. */

                .

    }             /* ends switch (message) */


Sharing Icon Resources

The following code uses CreateIconFromResource, LookupIconIdFromDirectory, DrawIcon, and several of the resource functions to create an icon handle based on icon data from another executable file. Then, it displays the icon in a window.

HICON hIcon1;       /* icon handle                */

HINSTANCE hExe;     /* handle to loaded .EXE file */

HRSRC hResource;    /* handle for FindResource    */

HRSRC hMem;         /* handle for LoadResource    */

BYTE *lpResource;   /* address of resource data   */

int nID;            /* ID of resource that best

                       fits current screen        */

HDC hdc;        /* handle of display context */

/* Load the file from which to copy the icon. */

hExe = LoadLibrary("myapp.exe");

/* Find the icon directory whose identifier is 440. */

hResource = FindResource(hExe,

    MAKEINTRESOURCE(440),

    RT_GROUP_ICON);

/* Load and lock the icon directory. */

hMem = LoadResource(hExe, hResource);

lpResource = LockResource(hMem);

/*

 * Get the identifier of the icon that is most appropriate

 * for the video display.

 */

nID = LookupIconIdFromDirectory(

    (PBYTE) lpResource, TRUE);

/* Find the bits for the nID icon. */

hResource = FindResource(hExe,

    MAKEINTRESOURCE(nID),

    MAKEINTRESOURCE(RT_ICON));

/* Load and lock the icon. */

hMem = LoadResource(hExe, hResource);

lpResource = LockResource(hMem);

/* Create a handle to the icon. */

hIcon1 = CreateIconFromResource(

    (PBYTE) lpResource,

    SizeofResource(hExe, hResource),

    TRUE,

    0x00030000);

/* Draw the icon in the client area. */

DrawIcon(hdc, 10, 20, hIcon1);


Functions

Functions and Messages

Following are the functions and messages used with icons.

Functions

ArrangeIconicWindows

CopyIcon

CreateIcon

CreateIconFromResource

CreateIconIndirect

DestroyIcon

DrawIcon

GetIconInfo

IsIconic

LoadIcon

LookupIconIdFromDirectory

OpenIcon

Messages

WM_ICONERASEBKGND

WM_PAINTICON


Window Properties Overview

About Window Properties

A window property is any data assigned to a window by the SetProp function. A window property is usually a handle of the window-specific data, but it may be any 32-bit value. Each window property is identified by a string name.

Window properties are typically used to associate data with a subclassed window or a window in a multiple document interface (MDI) application. In either case, it is not convenient to use the extra bytes specified in the CreateWindow function or class structure for the following two reasons:

An application might not know how many extra bytes are available or how the space is being used. By using window properties, the application can associate data with a window without accessing the extra bytes.

An application must access the extra bytes by using offsets. Window properties, however, are accessed by their string identifiers, not by offsets.

The Microsoft® Win32™ application programming interface (API) provides several functions that enable applications to use window properties. The SetProp function assigns a window property and its string identifier to a window. The GetProp function retrieves the window property identified by a given string. The RemoveProp function destroys the association between a window and a window property but does not destroy the data itself. The EnumProps and EnumPropsEx functions enumerate all of a window's properties by using an application-defined callback function. EnumPropsEx includes an extra parameter for application-defined data used by the callback function.

The following topics discuss window properties:

Adding a Window Property

Retrieving a Window Property

Listing Window Properties for a Given Window

Deleting a Window Property

Functions


Adding a Window Property

The following example loads an icon and then a cursor and allocates memory for a buffer. The example then uses the SetProp function to assign the resulting icon, cursor, and memory handles as window properties for the window identified by the hwndSubclass value. The properties are identified by the strings PROP_ICON, PROP_CURSOR, and PROP_BUFFER.

#define BUFFER 4096

HINSTANCE hinst;       /* handle of current instance     */

HWND hwndSubclass;     /* handle of a subclassed window */

HANDLE hIcon, hCursor;

HGLOBAL hMem;

char *lpMem;

TCHAR tchPath[] = "c:\\winnt\\samples\\winprop.c";

/* Load resources. */

hIcon = LoadIcon(hinst, MAKEINTRESOURCE(400));

hCursor = LoadCursor(hinst, MAKEINTRESOURCE(220));

/* Allocate and fill a memory buffer. */

hMem = GlobalAlloc(GPTR, BUFFER);

lpMem = GlobalLock(hMem);

lstrcpy(lpMem, tchPath);

GlobalUnlock(hMem);

/* Set the window properties for hwndSubclass. */

SetProp(hwndSubclass, "PROP_ICON", hIcon);

SetProp(hwndSubclass, "PROP_CURSOR", hCursor);

SetProp(hwndSubclass, "PROP_BUFFER", hMem);


Retrieving a Window Property

A window can create handles to its window property data and use the data for any purpose. The following example uses the GetProp function to obtain handles to the window properties identified by PROP_ICON, PROP_CURSOR, and PROP_BUFFER. The example then displays the contents of the newly obtained memory buffer, cursor, and icon in the window's client area.

#define PATHLENGTH 256

HWND hwndSubclass;     /* handle of a subclassed window */

HANDLE hIconProp, hCursProp;

HGLOBAL hMemProp;

char *lpFilename;

TCHAR tchBuffer[PATHLENGTH];

int nSize;

HDC hdc;

/* Get the window properties, then use the data. */

hIconProp = (HICON) GetProp(hwndSubclass, "PROP_ICON");

TextOut(hdc, 10, 40, "PROP_ICON", 9);

DrawIcon(hdc, 90, 40, hIconProp);

hCursProp = (HCURSOR) GetProp(hwndSubclass, "PROP_CURSOR");

TextOut(hdc, 10, 85, "PROP_CURSOR", 9);

DrawIcon(hdc, 110, 85, hCursProp);

hMemProp = (HGLOBAL) GetProp(hwndSubclass, "PROP_BUFFER");

lpFilename = GlobalLock(hMemProp);

nSize = sprintf(tchBuffer,

    "Path to file: %s", lpFilename);

TextOut(hdc, 10, 10, tchBuffer, nSize);


Listing Window Properties for a Given Window

In the following example, the EnumPropsEx function lists the string identifiers of the window properties for the window identified by the hwndSubclass value. This function relies on the application-defined callback function WinPropProc to display the strings in the window's client area.

EnumPropsEx(hwndSubclass, WinPropProc, NULL);

/*

 * WinPropProc is an application-defined callback function that

 * lists a window property.

 */

BOOL CALLBACK WinPropProc(

    HWND hwndSubclass,         /* handle of window with property */

    LPCSTR lpszString,         /* property string or atom        */

    HANDLE hData)              /* data handle                    */

{

    static int nProp = 1;    /* property counter           */

    TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */

    int nSize;               /* size of string in buffer   */

    HDC hdc;                 /* device-context handle      */

    hdc = GetDC(hwndSubclass);

    /* Display the window property string in the client area. */

    nSize = sprintf(tchBuffer, "WinProp %d: %s", nProp++,

        lpszString);

    TextOut(hdc, 10, nProp * 20, tchBuffer, nSize);

    ReleaseDC(hwndSubclass, hdc);

    return TRUE;

}


Deleting a Window Property

When a window is destroyed, it must destroy any window properties it set. The following example uses the EnumPropsEx function and the application-defined callback function DelPropProc to destroy the properties associated with the hwndSubclass window. The callback function, which uses the RemoveProp function, is also shown.

case WM_DESTROY:

    EnumPropsEx(hwndSubclass, DelPropProc, NULL);

    PostQuitMessage(0);

    break;

    .

    .

    .

/*

 * DelPropProc is an application-defined callback function that

 * deletes a window property.

 */

BOOL CALLBACK DelPropProc(

    HWND hwndSubclass,         /* handle of window with property */

    LPCSTR lpszString,         /* property string or atom        */

    HANDLE hData)              /* data handle                    */

{

    RemoveProp(hwndSubclass, lpszString);

    return TRUE;

}


Functions

Following are the functions used with window properties.

EnumProps

EnumPropsEx

GetProp

PropEnumProc

PropEnumProcEx

RemoveProp

SetProp


Clipboard Overview

About the Clipboard

The clipboard is a set of functions and messages that enable applications designed for the Microsoft® Win32™ application programming interface (API) to transfer data. Because all applications have access to the clipboard, data can be easily transferred between applications or within an application.

A memory object on the clipboard can be in any data format, called a clipboard format. Each format is identified by an unsigned integer value. For standard (predefined) clipboard formats, this value is a constant defined by the Win32 API; for registered clipboard formats, it is the return value of the RegisterClipboardFormat function.

Except for registering clipboard formats, individual windows carry out most clipboard operations. Typically, a window procedure transfers information to or from the clipboard in response to the WM_COMMAND message.

The clipboard is user-driven. A window should transfer data to or from the clipboard only in response to a command from the user. A window must not use the clipboard to transfer data without the user's knowledge.

This topic does not describe how to copy and paste linked or embedded objects. For information on these subjects, see the object linking and embedding (OLE) documentation.

The following topics discuss Win32 API clipboard support:

Terms

Clipboard Formats

Clipboard Operations

Clipboard Viewers

Clipboard Commands

Implementing the Cut, Copy, and Paste Commands

Creating a Clipboard Viewer

Example of a Clipboard Viewer

Functions and Messages


Clipboard Formats

A window can place more than one memory object on the clipboard, each representing the same information in a different clipboard format. Users need not be aware of the clipboard formats used for an object on the clipboard.

Registered Clipboard Formats

Many applications work with data that cannot be translated into a standard clipboard format without loss of information. Such applications can register new clipboard formats by using the RegisterClipboardFormat function. For example, if a word processing application copied formatted text to the clipboard using a standard text format, the formatting information would be lost. The solution would be to register a new clipboard format, such as rich-text format (RTF).

If more than one application registers a clipboard format with exactly the same name, the clipboard format is registered only once. Both calls to the RegisterClipboardFormat function return the same value. In this way, two different applications can share data by using a registered clipboard format.

For a list of standard clipboard formats, see the SetClipboardData function.

Private Clipboard Formats

An application can identify a private clipboard format by defining a value in the range CF_PRIVATEFIRST through CF_PRIVATELAST. An application can use a private clipboard format for an application-defined data format that does not need to be registered with the system.

Data handles associated with private clipboard formats are not automatically freed by the system when a window empties the clipboard. Windows that use private clipboard formats should process the WM_DESTROYCLIPBOARD message to free clipboard data when the data is no longer needed.

For more information about the WM_DESTROYCLIPBOARD message, see Clipboard Ownership.

Multiple Clipboard Formats

A window can place more than one clipboard object on the clipboard, each representing the same information in a different clipboard format. When placing information on the clipboard, the window should provide data in as many formats as possible.

Clipboard formats that contain the most information should be placed on the clipboard first, followed by less descriptive formats. A window pasting information from the clipboard typically retrieves a clipboard object in the first format it recognizes. Because clipboard formats are enumerated in the order they are placed on the clipboard, the first recognized format is also the most descriptive.

For example, suppose a user copies styled text from a word-processing document. The window containing the document might first place data on the clipboard in a registered format such as RTF. Afterwards, the window would place data on the clipboard in a less descriptive format such as text (CF_TEXT).

When the contents of the clipboard are pasted into another window, the window retrieves data in the most descriptive format it recognizes. If the window recognizes RTF, the corresponding data is pasted into the document. Otherwise, the text data is pasted into the document and the formatting information is lost.

Synthesized Clipboard Formats

Adding some formats to the clipboard implicitly creates other formats. When an application places any of the three text formats on the clipboard, the other two text formats are added implicitly. Similarly, when the application places either of the two metafile formats on the clipboard, the other metafile format is added implicitly.

When one of the implicit formats is requested by an application, the system synthesizes it by converting from an available format. For example, if an application places data on the clipboard using the CF_TEXT format, the CF_OEMTEXT and CF_UNICODETEXT clipboard formats are added implicitly. If another application requests data in the CF_UNICODETEXT clipboard format, the system synthesizes the data by converting it from the CF_TEXT format.

Synthesized clipboard formats are not added until the clipboard is closed. This enables an application to place more than one text format or both metafile formats on the clipboard.


Clipboard Operations

A window should use the clipboard when cutting, copying, or pasting data. A window places data on the clipboard for cut and copy operations and retrieves data from the clipboard for paste operations. The following sections describe these operations and related issues.

To place data on or retrieve data from the clipboard, a window must first open the clipboard by using the OpenClipboard function. Only one window can have the clipboard open at a time. When it has finished, the window must close the clipboard by calling the CloseClipboard function.

Cut and Copy Operations

To place information on the clipboard, a window first clears any previous clipboard contents by using the EmptyClipboard function. This function sends the WM_DESTROYCLIPBOARD message to the previous clipboard owner, frees resources associated with data on the clipboard, and assigns clipboard ownership to the window that has the clipboard open.

After emptying the clipboard, a window places data on the clipboard in as many clipboard formats as possible. For each format, the window calls the SetClipboardData function, specifying the format identifier and a global memory handle. The memory handle can be NULL, indicating that the window renders the data on request. (For more information, see Delayed Rendering.) A window should place data on the clipboard in order from the most descriptive clipboard format to the least descriptive.

Paste Operations

To retrieve paste information from the clipboard, a window first determines the clipboard format to retrieve. Typically, a window enumerates the available clipboard formats by using the EnumClipboardFormats function and uses the first format it recognizes. This method selects the best available format according to the priority set when the data was placed on the clipboard.

Alternatively, a window can use the GetPriorityClipboardFormat function. This function identifies the best available clipboard format according to a specified priority. A window that recognizes only one clipboard format can simply determine whether that format is available by using the IsClipboardFormatAvailable function.

After determining the clipboard format to use, a window calls the GetClipboardData function. This function returns the handle of a global memory object containing data in the specified format. A window can briefly lock the memory object in order to examine or copy the data. However, a window should not free the object or leave it locked for a long period of time.

Clipboard Ownership

The clipboard owner is the window associated with the information on the clipboard. A window becomes the clipboard owner when it places data on the clipboard--specifically, when it calls the EmptyClipboard function. The window remains the clipboard owner until it is closed or another window empties the clipboard.

When the clipboard is emptied, the clipboard owner receives a WM_DESTROYCLIPBOARD message. Following are some reasons why a window might process this message:

The window delayed rendering of one or more clipboard formats. In response to the WM_DESTROYCLIPBOARD message, the window might free resources it had allocated in order to render data on request. For more information, see Delayed Rendering.

The window placed data on the clipboard in a private clipboard format. The data for private clipboard formats is not freed by the system when the clipboard is emptied. Therefore, the clipboard owner should free the data upon receiving the WM_DESTROYCLIPBOARD message. For more information, see Private Clipboard Formats.

The window placed data on the clipboard using the CF_OWNERDISPLAY clipboard format. In response to the WM_DESTROYCLIPBOARD message, the window might free resources it had used to display information in the clipboard viewer window. For more information, see Owner-Display Format.

Delayed Rendering

When placing a clipboard format on the clipboard, a window can delay rendering the data in that format until the data is needed. To do so, an application can specify NULL for the hData parameter of the SetClipboardData function. This is useful if the application supports several clipboard formats, some or all of which are time-consuming to render. By passing a NULL handle, a window renders complex clipboard formats only when and if they are needed.

If a window delays rendering a clipboard format, it must be prepared to render the format on request for as long as it is the clipboard owner. The system sends the clipboard owner a WM_RENDERFORMAT message when a request is received for a specific format that has not been rendered. Upon receiving this message, the window should call the SetClipboardData function to place a global memory handle on the clipboard in the requested format.

If the clipboard owner is destroyed and has delayed rendering some or all clipboard formats, it receives the WM_RENDERALLFORMATS message. Upon receiving this message, the window should place valid memory handles on the clipboard for all clipboard formats that it provides. This ensures that these formats remain available after the clipboard owner is destroyed.

An application should not open the clipboard before calling SetClipboardData in response to the WM_RENDERFORMAT or WM_RENDERALLFORMATS message.

Any clipboard formats that are not rendered in response to the WM_RENDERALLFORMATS message cease to be available to other applications and are no longer enumerated by the clipboard functions.

Memory and the Clipboard

A memory object that is to be placed on the clipboard should be allocated by using the GlobalAlloc function with the GMEM_DDESHARE and GMEM_MOVEABLE flags.

Once a memory object is placed on the clipboard, ownership of that memory handle is transferred to the system. When the clipboard is emptied and the memory object has one of the following clipboard formats, the system frees the memory object by calling the indicated Win32 function:

clipboard format	function called to free object

CF_BITMAP	DeleteObject

CF_DSPBITMAP	DeleteObject

CF_PALETTE	DeleteObject

CF_METAFILEPICT	DeleteMetafile

CF_DSPMETAFILEPICT	DeleteMetafile

CF_ENHMETAFILE	DeleteMetafile

CF_DSPENHMETAFILE	DeleteMetafile

CF_TEXT	GlobalFree

CF_OEMTEXT	GlobalFree

CF_UNICODETEXT	GlobalFree

CF_DSPTEXT	GlobalFree

CF_DIB	GlobalFree

When the clipboard is emptied of a memory object whose clipboard format is not shown in the preceding list, the application itself must free the memory object.


Clipboard Viewers

A clipboard viewer is a window that displays the current contents of the clipboard. The clipboard viewer is a convenience for the user and does not affect the data-transaction functions of the clipboard.

Typically, a clipboard viewer window can display at least the three most common formats: CF_TEXT, CF_BITMAP, and CF_METAFILEPICT. If a window does not make data available in any of these three formats, it should provide data in a display format, or use the owner-display format.

Clipboard Viewer Windows

A window adds itself to the clipboard viewer chain by calling the SetClipboardViewer function. The return value is the handle of the next window in the chain. Each clipboard viewer window must keep track of the next window in the clipboard viewer chain. When the contents of the clipboard change, the system sends a WM_DRAWCLIPBOARD message to the first window in the chain. After updating its display, each clipboard viewer window must pass this message on to the next window in the chain.

Before closing, a clipboard viewer window must remove itself from the clipboard viewer chain by calling the ChangeClipboardChain function. The system then sends a WM_CHANGECBCHAIN message to the first window in the chain.

For more information about processing the WM_DRAWCLIPBOARD and WM_CHANGECBCHAIN messages, see Creating a Clipboard Viewer.

Display Formats

A display format is a clipboard format used to display information in a clipboard viewer window. A clipboard owner that uses a private or registered clipboard format, and none of the most common standard formats, must provide data in a display format for viewing in a clipboard viewer window. The display formats are intended for viewing only and must not be pasted into a document.

The four display formats CF_DSPBITMAP, CF_DSPMETAFILEPICT, CF_DSPTEXT, and CF_DSPENHMETAFILE are rendered in the same way as the standard CF_BITMAP, CF_TEXT, CF_METAFILEPICT, and CF_ENHMETAFILE formats.

Owner-Display Format

For a clipboard owner that does not use any of the common standard clipboard formats, an alternative to providing a display format is to use the owner-display (CF_OWNERDISPLAY) clipboard format.

By using the owner-display format, a clipboard owner can avoid the overhead of rendering data in an additional format by taking direct control over painting the clipboard viewer window. The clipboard viewer window sends messages to the clipboard owner whenever a portion of the window must be repainted or when the window is scrolled or resized.


Clipboard Commands

A user typically carries out clipboard operations by choosing commands in an application's Edit menu. Following is a brief description of the standard clipboard commands.

Command	Description

Cut	Places a copy of the current selection on the clipboard and deletes the selection from the document. The previous contents of the clipboard are destroyed.

Copy	Places a copy of the current selection on the clipboard. The document remains unchanged. The previous contents of the clipboard are destroyed.

Paste	Replaces the current selection with the contents of the clipboard. The contents of the clipboard are not changed.

Delete	Deletes the current selection from the document. The contents of the clipboard are not changed. This command does not involve the clipboard, but it should appear with the clipboard commands on the Edit menu.


Implementing the Cut, Copy, and Paste Commands

This section describes how standard Cut, Copy, and Paste commands are implemented in an application. The example in this section uses these methods to place data on the clipboard using a registered clipboard format, the CF_OWNERDISPLAY format, and the CF_TEXT format. The registered format is used to represent rectangular or elliptical text windows, called labels.

Selecting Data

Before information can be copied to the clipboard, the user must select specific information to be copied or cut. An application should provide a means for the user to select information within a document, and some kind of visual feedback to indicate selected data.

The following illustration shows selected data in the example application Label. In one window, an inverted rectangle indicates a selected range of text within a label; in the other window, sizing boxes indicate a label that is itself selected.

Creating an Edit Menu

The following illustration shows a typical Edit menu.

An application should load an accelerator table containing the standard keyboard accelerators for the Edit menu commands. The TranslateAccelerator function must be added to the applications message loop for the accelerators to take effect.

Processing the WM_INITMENUPOPUP Message

Not all clipboard commands are available to the user at any given time. An application should process the WM_INITMENUPOPUP message to enable the menu items for available commands and disable unavailable commands.

Following is the WM_INITMENUPOPUP case for the Label application.

case WM_INITMENUPOPUP:

    InitMenu((HMENU) wParam);

    break;

The InitMenu function is defined as follows.

void PASCAL InitMenu(HMENU hmenu)

{

    int  cMenuItems = GetMenuItemCount(hmenu);

    int  nPos;

    UINT id;

    UINT fuFlags;

    PLABELBOX pbox = (hwndSelected == NULL) ? NULL :

        (PLABELBOX) GetWindowLong(hwndSelected, 0);

    for (nPos = 0; nPos < cMenuItems; nPos++) {

        id = GetMenuItemID(hmenu, nPos);

        switch (id) {

            case IDM_CUT:

            case IDM_COPY:

            case IDM_DELETE:

                if (pbox == NULL || !pbox->fSelected)

                    fuFlags = MF_BYCOMMAND | MF_GRAYED;

                else if (pbox->fEdit)

                    fuFlags = (id != IDM_DELETE && pbox->ichSel

                            == pbox->ichCaret) ?

                        MF_BYCOMMAND | MF_GRAYED :

                        MF_BYCOMMAND | MF_ENABLED;

                else

                    fuFlags = MF_BYCOMMAND | MF_ENABLED;

                EnableMenuItem(hmenu, id, fuFlags);

                break;

            case IDM_PASTE:

                if (pbox != NULL && pbox->fEdit)

                    EnableMenuItem(hmenu, id,

                        IsClipboardFormatAvailable(CF_TEXT) ?

                            MF_BYCOMMAND | MF_ENABLED :

                            MF_BYCOMMAND | MF_GRAYED

                    );

                else

                    EnableMenuItem(hmenu, id,

                        IsClipboardFormatAvailable(

                                uLabelFormat) ?

                            MF_BYCOMMAND | MF_ENABLED :

                            MF_BYCOMMAND | MF_GRAYED

                    );

        }

    }

}

Processing the WM_COMMAND Message

To process menu commands, add the WM_COMMAND case to your application's main window procedure. Following is the WM_COMMAND case for the Label application's window procedure.

case WM_COMMAND:

    switch (LOWORD(wParam)) {

        case IDM_CUT:

            if (EditCopy())

                EditDelete();

            break;

        case IDM_COPY:

            EditCopy();

            break;

        case IDM_PASTE:

            EditPaste();

            break;

        case IDM_DELETE:

            EditDelete();

            break;

        case IDM_EXIT:

            DestroyWindow(hwnd);

    }

    break;

To carry out the Copy and Cut commands, the window procedure calls the application-defined EditCopy function. For more information, see Copying Information to the Clipboard. To carry out the Paste command, the window procedure calls the application-defined EditPaste function. For more information, see Pasting Information from the Clipboard.

Copying Information to the Clipboard

In the Label application, the application-defined EditCopy function copies the current selection to the clipboard. This function does the following:

1	Opens the clipboard by calling the OpenClipboard function.

2	Empties the clipboard by calling the EmptyClipboard function.

3	Calls the SetClipboardData function once for each clipboard format the application provides.

4	Closes the clipboard by calling the CloseClipboard function.

Depending on the current selection, the EditCopy function either copies a range of text or copies an application-defined structure representing an entire label. The structure, call LABELBOX, is defined as follows.

#define BOX_ELLIPSE  0

#define BOX_RECT     1

#define CCH_MAXLABEL 80

#define CX_MARGIN    12

typedef struct tagLABELBOX {  /* box */

    RECT rcText;    /* coordinates of rectangle containing text  */

    BOOL fSelected; /* TRUE if the label is selected             */

    BOOL fEdit;     /* TRUE if text is selected                  */

    int nType;      /* rectangular or elliptical                 */

    int ichCaret;   /* caret position                            */

    int ichSel;     /* with ichCaret, delimits selection         */

    int nXCaret;    /* window position corresponding to ichCaret */

    int nXSel;      /* window position corresponding to ichSel   */

    int cchLabel;   /* length of text in atchLabel               */

    TCHAR atchLabel[CCH_MAXLABEL];

} LABELBOX, *PLABELBOX;

Following is the EditCopy function.

BOOL PASCAL EditCopy(VOID)

{

    PLABELBOX pbox;

    LPTSTR  lptstrCopy;

    HGLOBAL hglbCopy;

    int ich1, ich2, cch;

    if (hwndSelected == NULL)

        return FALSE;

    /* Open the clipboard, and empty it. */

    if (!OpenClipboard(hwndMain))

        return FALSE;

    EmptyClipboard();

    /* Get a pointer to the structure for the selected label. */

    pbox = (PLABELBOX) GetWindowLong(hwndSelected, 0);

    /* If text is selected, copy it using the CF_TEXT format. */

    if (pbox->fEdit) {

        if (pbox->ichSel == pbox->ichCaret) {   /* zero-length */

            CloseClipboard();                   /* selection   */

            return FALSE;

        }

        if (pbox->ichSel < pbox->ichCaret) {

            ich1 = pbox->ichSel;

            ich2 = pbox->ichCaret;

        }

        else {

            ich1 = pbox->ichCaret;

            ich2 = pbox->ichSel;

        }

        cch = ich2 - ich1;

        /* Allocate a global memory object for the text. */

        hglbCopy = GlobalAlloc(GMEM_DDESHARE,

            (cch + 1) * sizeof(TCHAR));

        if (hglbCopy == NULL) {

            CloseClipboard();

            return FALSE;

        }

        /* Lock the handle and copy the text to the buffer. */

        lptstrCopy = GlobalLock(hglbCopy);

        memcpy(lptstrCopy, &pbox->atchLabel[ich1],

            cch * sizeof(TCHAR));

        lptstrCopy[cch] = (TCHAR) 0;    /* null character */

        GlobalUnlock(hglbCopy);

        /* Place the handle on the clipboard. */

        SetClipboardData(CF_TEXT, hglbCopy);

    }

    /* If no text is selected, the label as a whole is copied. */

    else {

        /*

         * Save a copy of the selected label as a local memory

         * object. This copy is used to render data on request.

         * It is freed in response to the WM_DESTROYCLIPBOARD

         * message.

         */

        pboxLocalClip = (PLABELBOX) LocalAlloc(

            LMEM_FIXED,

            sizeof(LABELBOX)

        );

        if (pboxLocalClip == NULL) {

            CloseClipboard();

            return FALSE;

        }

        memcpy(pboxLocalClip, pbox, sizeof(LABELBOX));

        pboxLocalClip->fSelected = FALSE;

        pboxLocalClip->fEdit = FALSE;

        /*

         * Place a registered clipboard format, the owner-display

         * format, and the CF_TEXT format on the clipboard using

         * delayed rendering.

         */

        SetClipboardData(uLabelFormat, NULL);

        SetClipboardData(CF_OWNERDISPLAY, NULL);

        SetClipboardData(CF_TEXT, NULL);

    }

    /* Close the clipboard. */

    CloseClipboard();

    return TRUE;

}

Pasting Information from the Clipboard

In the Label application, the application-defined EditPaste function pastes the contents of the clipboard. This function does the following:

1	Opens the clipboard by calling the OpenClipboard function.

2	Determines which of the available clipboard formats to retrieve.

3	Retrieves the handle of the data in the selected format by calling the GetClipboardData function.

4	Inserts a copy of the data into the document.

The handle returned by GetClipboardData is still owned by the clipboard, so an application must not free it or leave it locked.

5	Closes the clipboard by calling the CloseClipboard function.

If a label is selected and contains an insertion point, the EditPaste function inserts the text from the clipboard at the insertion point. If there is no selection or if a label is selected, the function creates a new label, using the application-defined LABELBOX structure on the clipboard. The LABELBOX structure is placed on the clipboard by using a registered clipboard format.

Following is the EditPaste function.

VOID PASCAL EditPaste(VOID)

{

    PLABELBOX pbox;

    HGLOBAL   hglb;

    LPTSTR    lptstr;

    PLABELBOX pboxCopy;

    int cx, cy;

    HWND hwnd;

    pbox = hwndSelected == NULL ? NULL :

        (PLABELBOX) GetWindowLong(hwndSelected, 0);

    /*

     * If the application is in edit mode,

     * get the clipboard text.

     */

    if (pbox != NULL && pbox->fEdit) {

        if (!IsClipboardFormatAvailable(CF_TEXT))

            return;

        if (!OpenClipboard(hwndMain))

            return;

        hglb = GetClipboardData(CF_TEXT);

        if (hglb != NULL) {

            lptstr = GlobalLock(hglb);

            if (lptstr != NULL) {

                /*

                 * Call the application-defined ReplaceSelection

                 * function to insert the text and repaint the

                 * window.

                 */

                ReplaceSelection(hwndSelected, pbox, lptstr);

                GlobalUnlock(hglb);

            }

        }

        CloseClipboard();

        return;

    }

    /*

     * If the application is not in edit mode,

     * create a label window.

     */

    if (!IsClipboardFormatAvailable(uLabelFormat))

        return;

    if (!OpenClipboard(hwndMain))

        return;

    hglb = GetClipboardData(uLabelFormat);

    if (hglb != NULL) {

        pboxCopy = GlobalLock(hglb);

        if (pboxCopy != NULL) {

            cx = pboxCopy->rcText.right + CX_MARGIN;

            cy = pboxCopy->rcText.top * 2 + cyText;

            hwnd = CreateWindowEx(

                WS_EX_NOPARENTNOTIFY | WS_EX_TRANSPARENT,

                atchClassChild, NULL, WS_CHILD, 0, 0, cx, cy,

                hwndMain, NULL, hinst, NULL

            );

            if (hwnd != NULL) {

                pbox = (PLABELBOX) GetWindowLong(hwnd, 0);

                memcpy(pbox, pboxCopy, sizeof(LABELBOX));

                ShowWindow(hwnd, SW_SHOWNORMAL);

                SetFocus(hwnd);

            }

            GlobalUnlock(hglb);

        }

    }

    CloseClipboard();

}

Registering a Clipboard Format

To register a clipboard format, add a call to the RegisterClipboardFormat function to your application's instance initialization function, as follows.

/* Register a clipboard format. */

LoadString(hinstCurrent, IDS_FORMATNAME, atchTemp,

    sizeof(atchTemp));

uLabelFormat = RegisterClipboardFormat(atchTemp);

if (uLabelFormat == 0)

    return FALSE;

Processing the WM_RENDERFORMAT and WM_RENDERALLFORMATS Messages

If a window passes a NULL handle to the SetClipboardData function, it must process the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages to render data on request.

The WM_RENDERFORMAT message is sent to the clipboard owner if it delayed rendering a specific format and an application requested data in that format. The WM_RENDERALLFORMATS message is sent to the clipboard owner before it is destroyed if it has delayed rendering one or more clipboard formats.

To render a clipboard format, the window procedure must place a data handle on the clipboard by using the SetClipboardData function. It must not open the clipboard before calling SetClipboardData.

The Label application processes the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages as follows.

case WM_RENDERFORMAT:

    RenderFormat((UINT) wParam);

    break;

case WM_RENDERALLFORMATS:

    RenderFormat(uLabelFormat);

    RenderFormat(CF_TEXT);

    break;

In both cases, the window procedure calls the application-defined RenderFormat function, defined as follows.

void PASCAL RenderFormat(UINT uFormat)

{

    HGLOBAL hglb;

    PLABELBOX pbox;

    LPTSTR  lptstr;

    int cch;

    if (pboxLocalClip == NULL)

        return;

    if (uFormat == CF_TEXT) {

        /* Allocate a buffer for the text. */

        cch = pboxLocalClip->cchLabel;

        hglb = GlobalAlloc(GMEM_DDESHARE,

            (cch + 1) * sizeof(TCHAR));

        if (hglb == NULL)

            return;

        /* Copy the text from pboxLocalClip. */

        lptstr = GlobalLock(hglb);

        memcpy(lptstr, pboxLocalClip->atchLabel,

            cch * sizeof(TCHAR));

        lptstr[cch] = (TCHAR) 0;

        GlobalUnlock(hglb);

        /* Place the handle on the clipboard. */

        SetClipboardData(CF_TEXT, hglb);

    }

    else if (uFormat == uLabelFormat) {

        hglb = GlobalAlloc(GMEM_DDESHARE, sizeof(LABELBOX));

        if (hglb == NULL)

            return;

        pbox = GlobalLock(hglb);

        memcpy(pbox, pboxLocalClip, sizeof(LABELBOX));

        GlobalUnlock(hglb);

        SetClipboardData(uLabelFormat, hglb);

    }

}

Processing the WM_DESTROYCLIPBOARD Message

A window can process the WM_DESTROYCLIPBOARD message in order to free any resources it set aside to support delayed rendering. For example, the Label application, when copying a label to the clipboard, allocates a local memory object. It then frees this object in response to the WM_DESTROYCLIPBOARD message, as follows.

case WM_DESTROYCLIPBOARD:

    if (pboxLocalClip != NULL) {

        LocalFree(pboxLocalClip);

        pboxLocalClip = NULL;

    }

    break;

Using the Owner-Display Clipboard Format

If a window places information on the clipboard by using the CF_OWNERDISPLAY clipboard format, it must do the following:

Process the WM_PAINTCLIPBOARD message. This message is sent to the clipboard owner when a portion of the clipboard viewer window must be repainted.

Process the WM_SIZECLIPBOARD message. This message is sent to the clipboard owner when the clipboard viewer has been resized or its contents have changed.

Typically, a window responds to this message by setting the scroll positions and ranges for the clipboard viewer window. In response to this message, the Label application also updates a SIZE structure for the clipboard viewer window.

Process the WM_HSCROLLCLIPBOARD and WM_VSCROLLCLIPBOARD messages. These messages are sent to the clipboard owner when a scroll bar event occurs in the clipboard-viewer window.

Process the WM_ASKCBFORMATNAME message. The clipboard viewer sends this message to an application to retrieve the name of the owner-display format.

The window procedure for the Label application processes these messages, as follows.

LRESULT CALLBACK MainWindowProc(hwnd, msg, wParam, lParam)

HWND hwnd;

UINT msg;

WPARAM wParam;

LPARAM lParam;

{

    static RECT rcViewer;

    RECT rc;

    LPRECT lprc;

    LPPAINTSTRUCT lpps;

    .

    .

    .

    switch (msg) {

        .

        .

        .

        case WM_PAINTCLIPBOARD:

            /* Determine the dimensions of the label. */

            SetRect(&rc, 0, 0,

                pboxLocalClip->rcText.right + CX_MARGIN,

                pboxLocalClip->rcText.top * 2 + cyText

            );

            /* Center the image in the viewer window. */

            if (rc.right < rcViewer.right) {

                rc.left = (rcViewer.right - rc.right) / 2;

                rc.right += rc.left;

            }

            if (rc.bottom < rcViewer.bottom) {

                rc.top = (rcViewer.bottom - rc.bottom) / 2;

                rc.bottom += rc.top;

            }

            /*

             * Paint the image, using the specified PAINTSTRUCT

             * structure, by calling the application-defined

             * PaintLabel function.

             */

            lpps = (LPPAINTSTRUCT) GlobalLock((HGLOBAL) lParam);

            PaintLabel(lpps, pboxLocalClip, &rc);

            GlobalUnlock((HGLOBAL) lParam);

            break;

        case WM_SIZECLIPBOARD:

            /*

             * Save the dimensions of the window in a static

             * RECT structure.

             */

            lprc = (LPRECT) GlobalLock((HGLOBAL) lParam);

            memcpy(&rcViewer, lprc, sizeof(RECT));

            GlobalUnlock((HGLOBAL) lParam);

            /*

             * Set the scroll ranges to zero (thus eliminating

             * the need to process the WM_HSCROLLCLIPBOARD and

             * WM_VSCROLLCLIPBOARD messages).

             */

            SetScrollRange((HWND) wParam, SB_HORZ, 0, 0, TRUE);

            SetScrollRange((HWND) wParam, SB_VERT, 0, 0, TRUE);

            break;

        case WM_ASKCBFORMATNAME:

            LoadString(hinst, IDS_OWNERDISPLAY,

                (LPSTR) lParam, wParam);

            break;

            .

            .

            .

        default:

            return DefWindowProc(hwnd, msg, wParam, lParam);

    }

    return 0;

}


Creating a Clipboard Viewer

Creating a Clipboard Viewer Window

A clipboard viewer window displays the current contents of the clipboard, and receives messages when the clipboard contents change. To create a clipboard viewer window, your application must do the following:

Add the window to the clipboard viewer chain.

Process the WM_CHANGECBCHAIN message.

Process the WM_DRAWCLIPBOARD message.

Remove the window from the clipboard viewer chain before it is destroyed.

Adding a Window to the Clipboard Viewer Chain

A window adds itself to the clipboard viewer chain by calling the SetClipboardViewer function. The return value is the handle of the next window in the chain. A window must keep track of this value--for example, by saving it in a static variable named hwndNextViewer.

The following example adds a window to the clipboard viewer chain in response to the WM_CREATE message.

case WM_CREATE:

    /* Add the window to the clipboard viewer chain. */

    hwndNextViewer = SetClipboardViewer(hwnd);

    break;

Processing the WM_CHANGECBCHAIN Message

A clipboard viewer window receives the WM_CHANGECBCHAIN message when another window is removing itself from the clipboard viewer chain. If the window being removed is the next window in the chain, the window receiving the message must unlink the next window from the chain. Otherwise, this message should be passed to the next window in the chain.

The following example shows the processing of the WM_CHANGECBCHAIN message.

case WM_CHANGECBCHAIN:

    /* If the next window is closing, repair the chain. */

    if ((HWND) wParam == hwndNextViewer)

        hwndNextViewer = (HWND) lParam;

    /* Otherwise, pass the message to the next link. */

    else if (hwndNextViewer != NULL)

        SendMessage(hwndNextViewer, uMsg, wParam, lParam);

    break;

Removing a Window from the Clipboard Viewer Chain

To remove itself from the clipboard viewer chain, a window calls the ChangeClipboardChain function. The following example removes a window from the clipboard viewer chain in response to the WM_DESTROY message.

case WM_DESTROY:

    ChangeClipboardChain(hwnd, hwndNextViewer);

    PostQuitMessage(0);

    break;

Processing the WM_DRAWCLIPBOARD Message

The WM_DRAWCLIPBOARD message notifies a clipboard viewer window that the contents of the clipboard have changed. A window should do the following when processing the WM_DRAWCLIPBOARD message:

1	Determine which of the available clipboard formats to display.

2	Retrieve the clipboard data and display it in the window. Or, if the clipboard format is CF_OWNERDISPLAY, send a WM_PAINTCLIPBOARD message to the clipboard owner.

3	Send the message to the next window in the clipboard viewer chain.

For an example of processing the WM_DRAWCLIPBOARD message, see the listing in Example: Clipboard Viewer.


Example: Clipboard Viewer

Example of a Clipboard Viewer

The following example shows a simple clipboard viewer application.

HINSTANCE hinst;

UINT uFormat = (UINT)(-1);

BOOL fAuto = TRUE;

LRESULT APIENTRY MainWndProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;

UINT uMsg;

WPARAM wParam;

LPARAM lParam;

{

    static HWND hwndNextViewer;

    HDC hdc;

    HDC hdcMem;

    PAINTSTRUCT ps;

    LPPAINTSTRUCT lpps;

    RECT rc;

    LPRECT lprc;

    HGLOBAL hglb;

    LPSTR lpstr;

    HBITMAP hbm;

    HENHMETAFILE hemf;

    HWND hwndOwner;

    switch (uMsg) {

        case WM_PAINT:

            hdc = BeginPaint(hwnd, &ps);

            /* Branch depending on the clipboard format. */

            switch (uFormat) {

                case CF_OWNERDISPLAY:

                    hwndOwner = GetClipboardOwner();

                    hglb = GlobalAlloc(GMEM_DDESHARE,

                        sizeof(PAINTSTRUCT));

                    lpps = GlobalLock(hglb);

                    memcpy(lpps, &ps, sizeof(PAINTSTRUCT));

                    GlobalUnlock(hglb);

                    SendMessage(hwndOwner, WM_PAINTCLIPBOARD,

                        (WPARAM) hwnd, (LPARAM) hglb);

                    GlobalFree(hglb);

                    break;

                case CF_BITMAP:

                    hdcMem = CreateCompatibleDC(hdc);

                    if (hdcMem != NULL) {

                        if (OpenClipboard(hwnd)) {

                            hbm = (HBITMAP)

                                GetClipboardData(uFormat);

                            SelectObject(hdcMem, hbm);

                            GetClientRect(hwnd, &rc);

                            BitBlt(hdc, 0, 0, rc.right, rc.bottom,

                                hdcMem, 0, 0, SRCCOPY);

                            CloseClipboard();

                        }

                        DeleteDC(hdcMem);

                    }

                    break;

                case CF_TEXT:

                    if (OpenClipboard(hwnd)) {

                        hglb = GetClipboardData(uFormat);

                        lpstr = GlobalLock(hglb);

                        GetClientRect(hwnd, &rc);

                        DrawText(hdc, lpstr, -1, &rc, DT_LEFT);

                        GlobalUnlock(hglb);

                        CloseClipboard();

                    }

                    break;

                case CF_ENHMETAFILE:

                    if (OpenClipboard(hwnd)) {

                        hemf = GetClipboardData(uFormat);

                        GetClientRect(hwnd, &rc);

                        PlayEnhMetaFile(hdc, hemf, &rc);

                        CloseClipboard();

                    }

                    break;

                case 0:

                    GetClientRect(hwnd, &rc);

                    DrawText(hdc, "The clipboard is empty.", -1,

                        &rc, DT_CENTER | DT_SINGLELINE |

                        DT_VCENTER);

                    break;

                default:

                    GetClientRect(hwnd, &rc);

                    DrawText(hdc, "Unable to display format.", -1,

                        &rc, DT_CENTER | DT_SINGLELINE |

                        DT_VCENTER);

            }

            EndPaint(hwnd, &ps);

            break;

        case WM_SIZE:

            if (uFormat == CF_OWNERDISPLAY) {

                hwndOwner = GetClipboardOwner();

                hglb = GlobalAlloc(GMEM_DDESHARE, sizeof(RECT));

                lprc = GlobalLock(hglb);

                GetClientRect(hwnd, lprc);

                GlobalUnlock(hglb);

                SendMessage(hwndOwner, WM_SIZECLIPBOARD,

                    (WPARAM) hwnd, (LPARAM) hglb);

                GlobalFree(hglb);

            }

            break;

        case WM_CREATE:

            /* Add the window to the clipboard viewer chain. */

            hwndNextViewer = SetClipboardViewer(hwnd);

            break;

        case WM_CHANGECBCHAIN:

            /* If the next window is closing, repair the chain. */

            if ((HWND) wParam == hwndNextViewer)

                hwndNextViewer = (HWND) lParam;

            /* Otherwise, pass the message to the next link. */

            else if (hwndNextViewer != NULL)

                SendMessage(hwndNextViewer, uMsg, wParam, lParam);

            break;

        case WM_DESTROY:

            ChangeClipboardChain(hwnd, hwndNextViewer);

            PostQuitMessage(0);

            break;

        case WM_DRAWCLIPBOARD: /* clipboard contents changed. */

            /* Update the window by using Auto clipboard format. */

            SetAutoView(hwnd);

            /* Pass the message to the next window in viewer chain. */

            SendMessage(hwndNextViewer, uMsg, wParam, lParam);

            break;

        case WM_INITMENUPOPUP:

            if (!HIWORD(lParam))

                InitMenu(hwnd, (HMENU) wParam);

            break;

        case WM_COMMAND:

            switch (LOWORD(wParam)) {

                case IDM_EXIT:

                    DestroyWindow(hwnd);

                    break;

                case IDM_AUTO:

                    SetAutoView(hwnd);

                    break;

                default:

                    fAuto = FALSE;

                    uFormat = LOWORD(wParam);

                    InvalidateRect(hwnd, NULL, TRUE);

            }

            break;

        default:

            return DefWindowProc(hwnd, uMsg, wParam, lParam);

    }

    return (LRESULT) NULL;

}

void PASCAL SetAutoView(HWND hwnd)

{

    static UINT auPriorityList[] = {

        CF_OWNERDISPLAY,

        CF_TEXT,

        CF_ENHMETAFILE,

        CF_BITMAP

    };

    uFormat = GetPriorityClipboardFormat(auPriorityList, 4);

    fAuto = TRUE;

    InvalidateRect(hwnd, NULL, TRUE);

    UpdateWindow(hwnd);

}

void PASCAL InitMenu(HWND hwnd, HMENU hmenu)

{

    UINT uFormat;

    char szFormatName[80];

    LPCSTR lpFormatName;

    UINT fuFlags;

    UINT idMenuItem;

    /*

     * If a menu is not the display menu, no initialization is necessary. */

     */

    if (GetMenuItemID(hmenu, 0) != IDM_AUTO)

        return;

    /* Delete all menu items except the first. */

    while (GetMenuItemCount(hmenu) > 1)

        DeleteMenu(hmenu, 1, MF_BYPOSITION);

    /* Check or uncheck the Auto menu item. */

    fuFlags = fAuto ? MF_BYCOMMAND | MF_CHECKED :

        MF_BYCOMMAND | MF_UNCHECKED;

    CheckMenuItem(hmenu, IDM_AUTO, fuFlags);

    /* If there are no clipboard formats, return. */

    if (CountClipboardFormats() == 0)

        return;

    /* Open the clipboard. */

    if (!OpenClipboard(hwnd))

        return;

    /* Add a separator and then a menu item for each format. */

    AppendMenu(hmenu, MF_SEPARATOR, 0, NULL);

    uFormat = EnumClipboardFormats(0);

    while (uFormat) {

        /*

         * Call an application-defined function to get the name

         * of the clipboard format.

         */

        lpFormatName = GetPredefinedClipboardFormatName(uFormat);

        /* For registered formats, get the registered name. */

        if (lpFormatName == NULL) {

            if (GetClipboardFormatName(uFormat, szFormatName,

                    sizeof(szFormatName)))

                lpFormatName = szFormatName;

            else

                lpFormatName = "(unknown)";

        }

        /*

         * Add a menu item for the format. For displayable

         * formats, use the format ID for the menu ID.

         */

        if (IsDisplayableFormat(uFormat)) {

            fuFlags = MF_STRING;

            idMenuItem = uFormat;

        }

        else {

            fuFlags = MF_STRING | MF_GRAYED;

            idMenuItem = 0;

        }

        AppendMenu(hmenu, fuFlags, idMenuItem, lpFormatName);

        uFormat = EnumClipboardFormats(uFormat);

    }

    CloseClipboard();

}

BOOL PASCAL IsDisplayableFormat(UINT uFormat)

{

    switch (uFormat) {

        case CF_OWNERDISPLAY:

        case CF_TEXT:

        case CF_ENHMETAFILE:

        case CF_BITMAP:

            return TRUE;

    }

    return FALSE;

}


Functions and Messages

Following are the functions and messages used with the clipboard.

Functions

ChangeClipboardChain

CloseClipboard

CountClipboardFormats

EmptyClipboard

EnumClipboardFormats

GetClipboardData

GetClipboardFormatName

GetClipboardOwner

GetClipboardViewer

GetOpenClipboardWindow

GetPriorityClipboardFormat

IsClipboardFormatAvailable

OpenClipboard

RegisterClipboardFormat

SetClipboardData

SetClipboardViewer

Messages

WM_ASKCBFORMATNAME

WM_CHANGECBCHAIN

WM_COPY

WM_CUT

WM_DESTROYCLIPBOARD

WM_DRAWCLIPBOARD

WM_HSCROLLCLIPBOARD

WM_PAINTCLIPBOARD

WM_PASTE

WM_RENDERALLFORMATS

WM_RENDERFORMAT

WM_SIZECLIPBOARD

WM_VSCROLLCLIPBOARD


Dynamic Data Exchange Overview

About Dynamic Data Exchange

The Microsoft® Windows™ operating system provides several methods for transferring data between applications. One way to transfer data is to use the Windows dynamic data exchange (DDE) protocol. The DDE protocol is a set of messages and guidelines. It sends messages between applications that share data and uses shared memory to exchange data between applications. Applications can use the DDE protocol for one-time data transfers and for continuous exchanges in which applications send updates to one another as new data becomes available.

Windows also includes the Dynamic Data Exchange Management Library (DDEML). The DDEML is a dynamic-link library (DLL) that applications running with Windows can use to share data. The DDEML provides an application programming interface (API) that simplifies the task of adding DDE capability to a Windows-based application. Instead of sending, posting, and processing DDE messages directly, an application uses the DDEML functions to manage DDE conversations. (A DDE conversation is the interaction between client and server applications.)

The DDEML also provides a facility for managing the strings and data that DDE applications share. Instead of using atoms and pointers to shared memory objects, DDE applications create and exchange string handles, which identify strings, and data handles, which identify memory objects. The DDEML also makes it possible for a server application to register the service names it supports. The names are broadcast to other applications in the system, which can then use the names to connect to the server. Moreover, the DDEML ensures compatibility among DDE applications by forcing them to implement the DDE protocol in a consistent manner.

Existing applications that use the message-based DDE protocol are fully compatible with those that use the DDEML. That is, an application that uses message-based DDE can establish conversations and perform transactions with applications that use the DDEML. Because of the many advantages of the DDEML, new applications should use it rather than the DDE messages. To use the API elements of the DDE management library, you must include the DDEML.H header file in your source files, link with DDEML.LIB, and ensure that DDEML.DLL is in the system's path.

This topic provides guidelines for implementing dynamic data exchange for applications that cannot use the DDEML.

The following topics discuss Win32 DDE:

DDE Protocol

Uses for Windows Dynamic Data Exchange

Dynamic Data Exchange from the User's Point of View

Dynamic Data Exchange Concepts

Dynamic Data Exchange Messages

Dynamic Data Exchange Message Flow

Parameter-Packing Functions

Using Dynamic Data Exchange

Initiating a Conversation

Transferring a Single Item

Establishing a Permanent Data Link

Carrying Out Commands in a Server Application

Terminating a Conversation

Functions and Messages


DDE Protocol

Dynamic Data Exchange Protocol

Because Windows has a message-based architecture, passing messages is the most appropriate method for automatically transferring information between applications. However, Windows messages contain only two parameters (wParam and lParam) for passing data. As a result, these parameters must refer indirectly to other pieces of data when more than a few words of information pass between applications. The DDE protocol defines exactly how applications should use the wParam and lParam parameters to pass larger pieces of data by means of global atoms and shared memory handles. The DDE protocol has specific rules for allocating and deleting global atoms and shared memory objects.

A global atom is a reference to a character string. In the DDE protocol, atoms identify the applications exchanging data, the nature of the data being exchanged, and the data items themselves. A shared memory handle is a handle to a memory object allocated by GlobalAlloc, using the GMEM_DDESHARE flag. In the DDE protocol, shared memory objects store data items passed between applications, protocol options, and remote command execution strings.


Uses for Windows Dynamic Data Exchange

DDE is most appropriate for data exchanges that do not require ongoing user interaction. Usually, an application provides a method for the user to establish the link between the applications exchanging data. Once that link is established, however, the applications exchange data without further user involvement.

DDE can be used to implement a broad range of application features--for example:

Linking to real-time data, such as to stock market updates, scientific instruments, or process control.

Creating compound documents, such as a word processing document that includes a chart produced by a graphics application. Using DDE, the chart will change when the source data is changed, while the rest of the document remains the same.

Performing data queries between applications, such as a spreadsheet querying a database application for accounts past due.


Dynamic Data Exchange From the User's Point of View

Dynamic Data Exchange from the User's Point of View

The following example illustrates illustrates how two DDE applications can cooperate, as seen from the user's point of view.

A spreadsheet user wants to use Microsoft® Excel to track the price of a particular stock on the New York Stock Exchange. The user has a Windows-based application called Quote that in turn has access to NYSE data. The DDE conversation between Microsoft Excel and Quote takes place as follows:

The user initiates the conversation by supplying the name of the application (Quote) that will supply the data and the particular topic of interest (NYSE). The resulting DDE conversation is used to request quotes on specific stocks.

Microsoft Excel broadcasts the application and topic names to all DDE applications currently running in the system. Quote responds, establishing a conversation with Microsoft Excel about the NYSE topic.

The user can then create a spreadsheet formula in a cell that requests that the spreadsheet be automatically updated whenever a particular stock quotation changes. For example, the user could request an automatic update whenever a change occurs in the selling price of ZAXX stock by specifying the following Microsoft Excel formula:

='Quote'|'NYSE'!ZAXX

The user can terminate the automatic updating of the ZAXX stock quotation at any time. Other data links that were established separately (such as for quotations for other stocks) still will remain active under the same NYSE conversation.

The user can also terminate the entire conversation between Microsoft Excel and Quote on the NYSE topic, so that no specific data links on that topic can be established without initiating a new conversation.


Dynamic Data Exchange Concepts

The following sections explain the important concepts and terminology that are key to understanding dynamic data exchange.

Client, Server, and Conversation

Two applications participating in dynamic data exchange are said to be engaged in a DDE conversation. The application that initiates the conversation is the client application; the application that responds to the client is the server application. An application can engage in several conversations at the same time, acting as the client in some and as the server in others.

A DDE conversation takes place between two windows, one for each of the participating applications. A window may be the main window of the application; a window associated with a specific document, as in a multiple document interface (MDI) application; or a hidden (invisible) window whose only purpose is to process DDE messages.

Since a DDE conversation is identified by the pair of handles of the windows engaged in the conversation, no window should be engaged in more than one conversation with another window. Either the client application or the server application must provide a different window for each of its conversations with a particular server or client application.

An application can ensure a pair of client and server windows is never involved in more than one conversation by creating a hidden window for each conversation. The sole purpose of this window is to process DDE messages.

Application, Topic, and Item Names

The DDE protocol identifies the units of data passed between the client and server with a three-level hierarchy of application, topic, and item names.

Each DDE conversation is uniquely defined by the application name and topic. At the beginning of a DDE conversation, the client and server determine the application name and topic. The application name is usually the name of the server application. For example, when Microsoft Excel acts as the server in a conversation, the application name is Excel.

The DDE topic is a general classification of data within which multiple data items may be "discussed" (exchanged) during the conversation. For applications that operate on file-based documents, the topic is usually a filename. For other applications, the topic is an application-specific name.

Because the client and server window handles together identify a DDE conversation, the application name and topic that define a conversation cannot be changed during the course of the conversation.

A DDE data item is information related to the conversation topic exchanged between the applications. Values for the data item can be passed from the server to the client, or from the client to the server. Data can be passed with any of the standard clipboard formats or with a registered clipboard format. A special, registered format named Link identifies an item in a DDE conversation.

The System Topic

Applications should support the System topic at all times. This topic provides a context for information that may be of general interest to another application.

Data-item values must be rendered in the CF_TEXT clipboard format. Individual elements of item values for a System topic must be delimited by tab characters. The following table suggests some items for the System topic.

Item	Description

Formats	Tab-delimited list of clipboard formats the application can render. Typically, the CF_ formats are listed with the "CF_" portion of the names removed (for example, CF_TEXT is listed as "TEXT").

Help	Text that briefly explains how to use the DDE server.

ReturnMessage	Supporting detail for the most recently used WM_DDE_ACK message. This item is useful when more than eight bits of application-specific return data are required.

Status	Indication of the current status of the application. When a server receives a WM_DDE_REQUEST message for this System-topic item, it should respond by posting a WM_DDE_DATA message with a string containing either Busy or Ready, as appropriate.

SysItems	List of System-topic items the application supports.

TopicItemList	Similar to the SysItems item, except that TopicItemList should be supported for each topic other than the System topic. This allows browsing of the items supported under any topic. If the items cannot be enumerated, this item should contain only "TopicItemList".

Topics	List of topics the application supports at the current time; this list can vary from moment to moment.

Permanent Data Links

Once a DDE conversation has begun, the client can establish one or more permanent data links with the server. A data link is a communications mechanism by which the server notifies the client whenever the value of a given data item changes. The data link is permanent in the sense that this notification process continues until the data link or the DDE conversation itself is terminated.

There are two kinds of permanent DDE data links: warm and hot. In a warm data link, the server notifies the client that the value of the data item has changed, but the server does not send the data value to the client until the client requests it. In a hot data link, the server immediately sends the changed data value to the client.

Applications that support warm or hot data links typically provide a Copy or Paste Link command in their Edit menu to enable the user to establish links between applications. For more information, see Initiating a Data Link with the Paste Link Command.

Atoms and Shared Memory Objects

Certain arguments of DDE messages are global atoms or shared memory objects. Applications using these arguments must follow explicit rules about when to allocate and delete them. In all cases, the message sender must delete any atom or shared memory object that the intended receiver will not receive because of an error condition, such as failure of the PostMessage function.

DDE uses shared memory objects for three purposes:

To carry a data-item value to be exchanged. This is an item referenced by the hData parameter in the WM_DDE_DATA and WM_DDE_POKE messages.

To carry options in a message. This is an item referenced by the hOptions parameter in a WM_DDE_ADVISE message.

To carry a command execution string. This is an item referenced by the hCommands parameter in the WM_DDE_EXECUTE message and its corresponding WM_DDE_ACK message.

An application that receives a DDE shared memory object must treat it as read only. The application must not use the object as a mutual read-write area for the free exchange of data.

As it does with a DDE atom, an application should free a shared memory object to manage memory effectively. The application should also lock and unlock memory objects.


Dynamic Data Exchange Messages

Because DDE is a message-based protocol, it employs no special Windows functions or libraries. All DDE transactions are conducted by passing certain defined DDE messages between the client and server windows.

There are nine DDE messages; the symbolic constants for these messages are defined in the Microsoft® Win32™ Software Development Kit (SDK) header file DDE.H. Certain structures for the various DDE messages are also defined in DDE.H.

The following table summarizes the nine DDE messages.

Message	Description

WM_DDE_ACK	Acknowledges receiving or not receiving a message.

WM_DDE_ADVISE	Requests the server application to supply an update or notification for a data item whenever it changes. This establishes a permanent data link.

WM_DDE_DATA	Sends a data-item value to the client application.

WM_DDE_EXECUTE	Sends a string to the server application, which is expected to process the string as a series of commands.

WM_DDE_INITIATE	Initiates a conversation between the client and server applications.

WM_DDE_POKE	Sends a data-item value to the server application.

WM_DDE_REQUEST	Requests the server application to provide the value of a data item.

WM_DDE_TERMINATE	Terminates a conversation.

WM_DDE_UNADVISE	Terminates a permanent data link.

An application calls the SendMessage function to issue the WM_DDE_INITIATE message or a WM_DDE_ACK message sent in response to WM_DDE_INITIATE. All other messages are sent by the PostMessage function. The first parameter of these calls is the handle of the receiving window. The second parameter contains the message to be sent; the third parameter identifies the sending window; and the fourth parameter contains the message-specific arguments.


Dynamic Data Exchange Message Flow

A typical DDE conversation consists of the following events:

1	The client application initiates the conversation, and the server application responds.

2	The applications exchange data by any or all of the following methods:

The server application sends data to the client at the client's request.

The client application sends unsolicited data to the server application.

The client application requests the server application to notify the client whenever a data item changes (warm data link).

The client application requests the server application to send data whenever the data changes (hot data link).

The server application carries out a command at the client's request.

3	Either the client or server application terminates the conversation.

An application window that processes requests from a client or server must process them strictly in the order they are received.

A client can establish conversations with more than one server; a server can have conversations with more than one client. When handling messages from more than one source, a client or server must process the messages of a given conversation synchronously, but need not process all messages synchronously. In other words, it can shift from one conversation to another as needed.

If an application is unable to process an incoming request because it is waiting for a DDE response, it must prevent deadlock by posting a WM_DDE_ACK message with the fBusy member of the DDEACK structure set to 1. An application can also send a busy WM_DDE_ACK message if, for any reason, it cannot process an incoming request within a reasonable amount of time.

An application should be able to handle the failure of a client or server to respond to a message within a certain time. Since the length of the time-out interval may vary depending on the nature of the application and the configuration of the user's system (including whether it is connected to a network), the application should provide a way for the user to specify the interval.


Parameter-Packing Functions

The lParam parameter of many DDE messages contains two pieces of data. For example, the lParam of the WM_DDE_DATA message contains a data handle and an atom. In previous versions of Windows, an application could use the MAKELONG macro to prepare an lParam parameter, and the LOWORD and HIWORD macros to remove the low-order and high-order values from lParam. Because a Win32 data handle is a 32-bit value, a Win32 application must use the PackDDElParam function to pack the handle and atom into an lParam parameter, and the UnpackDDElParam function to remove the values. DDE applications must use PackDDElParam and UnpackDDElParam for all messages posted during a DDE conversation.

The Win32 API also includes the ReuseDDElParam and FreeDDElParam functions. ReuseDDElParam allows a DDE application to reuse a packed lParam parameter, helping reduce the number of memory reallocations the application must perform during a conversation. An application can use the FreeDDElParam to free the memory associated with a data handle received during a DDE conversation.


Using Dynamic Data Exchange

The section describes how to perform the following tasks:

Initiate a DDE conversation.

Transfer a single data item.

Establish a permanent data link.

Carry out commands in a server application.

Terminate a DDE conversation.


Initiating a Conversation

To initiate a DDE conversation, the client sends a WM_DDE_INITIATE message. Usually, the client broadcasts this message by calling the SendMessage function, with -1 as the first parameter. If the application already has the window handle of the server application, it can send the message directly to that window. The client prepares atoms for the application name and topic name by calling the GlobalAddAtom function. The client can request conversations with any potential server application and for any potential topic by supplying NULL (wildcard) atoms for the application and topic.

The following example illustrates how the client initiates a conversation, where both the application and topic are specified.

/* Global variable */

static BOOL fInInitiate = FALSE;

    char *szApplication;

    char *szTopic;

    atomApplication = *szApplication == 0 ?

        NULL : GlobalAddAtom((LPSTR) szApplication);

    atomTopic = *szTopic == 0 ?

        NULL : GlobalAddAtom((LPSTR) szTopic);

    fInInitiate = TRUE;

    SendMessage((HWND) -1,        /* broadcasts message          */

        WM_DDE_INITIATE,          /* initiates conversation      */

        (WPARAM) hwndClientDDE,   /* handle of client DDE window */

        MAKELONG(atomApplication, /* application-name atom       */

            atomTopic));          /* topic-name atom             */

    fInInitiate = FALSE;

    if (atomApplication != NULL)

        GlobalDeleteAtom(atomApplication);

    if (atomTopic != NULL)

        GlobalDeleteAtom(atomTopic);

Note that if your application uses NULL atoms, you need not use the GlobalAddAtom and GlobalDeleteAtom functions. In this example, the client application creates two global atoms containing the name of the server and the name of the topic, respectively.

The client application sends a WM_DDE_INITIATE message with these two atoms in the lParam parameter of the message. In the call to the SendMessage function, the special window handle -1 directs Windows to send this message to all other active applications. SendMessage does not return to the client application until all applications that receive the message have, in turn, returned control to Windows. This means that all WM_DDE_ACK messages sent in reply by the server applications are guaranteed to have been processed by the client by the time the SendMessage call has returned.

After SendMessage returns, the client application deletes the global atoms.

Server applications respond according to the logic illustrated in the following diagram.

To acknowledge one or more topics, the server must create atoms for each conversation (requiring duplicate application-name atoms if there are multiple topics) and send a WM_DDE_ACK message for each conversation, as illustrated in the following example.

if ((atomApplication = GlobalAddAtom("Server")) != 0) {

    if ((atomTopic = GlobalAddAtom(szTopic)) != 0) {

        SendMessage(hwndClientDDE,

            WM_DDE_ACK,

            (WPARAM) hwndServerDDE,

            MAKELONG(atomApplication, atomTopic));

        GlobalDeleteAtom(atomApplication);

    }

    GlobalDeleteAtom(atomTopic);

}

if ((atomApplication == 0) || (atomTopic == 0)) {

     .

     . /* error handling */

     .

}

When a server responds with a WM_DDE_ACK message, the client application should save the handle of the server window. The client receiving the handle as the wParam parameter of the WM_DDE_ACK message, then sends all subsequent DDE messages to the server window this handle identifies.

If your client application uses NULL atoms for the application name or topic name, you should expect the application to receive acknowledgments from more than one server application. Multiple acknowledgements can also come from multiple instances of a DDE server, even if your client application does not use NULL atoms. A server should always use a unique window for each conversation. The window procedure in the client application can use the handle of the server window (provided as the lParam parameter of WM_DDE_INITIATE) to track the status of multiple conversations. This allows a single client window to process several conversations without needing to terminate and reconnect with a new client window for each conversation.


Transferring a Single Item

Once a DDE conversation has been established, the client can retrieve the value of a data item from the server by issuing the WM_DDE_REQUEST message, or the client can submit a data-item value to the server by issuing the WM_DDE_POKE message.

Retrieving an Item from the Server

To retrieve an item from the server, the client sends the server a WM_DDE_REQUEST message specifying the item and format to retrieve, as shown in the following example.

if ((atomItem = GlobalAddAtom(szItemName)) != 0) {

    if (!PostMessage(hwndServerDDE,

            WM_DDE_REQUEST,

            (WPARAM) hwndClientDDE,

            PackDDElParam(WM_DDE_REQUEST, CF_TEXT, atomItem)))

        GlobalDeleteAtom(atomItem);

}

if (atomItem == 0) {

     .

     . /* error handling */

     .

}

In this example, the client specifies the clipboard format CF_TEXT as the preferred format for the requested data item.

The receiver (server) of the WM_DDE_REQUEST message typically must delete the item atom, but if the PostMessage call itself fails, the client must delete the atom.

If the server has access to the requested item and can render it in the requested format, the server copies the item value as a shared memory object and sends the client a WM_DDE_DATA message, as illustrated in the following example.

/*

 * Allocate the size of the DDE data header, plus the data: a

 * string,<CR><LF><NULL>. The byte for the string's terminating

 * null character is counted by DDEDATA.Value[1].

 */

if (!(hData = GlobalAlloc(GMEM_MOVEABLE | GMEM_DDESHARE,

        (LONG) sizeof(DDEDATA) + lstrlen(szItemValue) + 2)))

    return;

if (!(lpData = (DDEDATA FAR*) GlobalLock(hData)))  {

    GlobalFree(hData);

    return;

}

   .

   .

   .

lpData->cfFormat = CF_TEXT;

lstrcpy((LPSTR) lpData->Value, (LPSTR) szItemValue);

/* Each line of CF_TEXT data is terminated by CR/LF. */

lstrcat((LPSTR) lpData->Value, (LPSTR) "\r\n");

GlobalUnlock(hData);

if ((atomItem = GlobalAddAtom((LPSTR) szItemName)) != 0) {

    lParam = PackDDElParam(WM_DDE_ACK, (UINT) hData, atomItem);

    if (!PostMessage(hwndClientDDE,

            WM_DDE_DATA,

            (WPARAM) hwndServerDDE,

            lParam)) {

        GlobalFree(hData);

        GlobalDeleteAtom(atomItem);

        FreeDDElParam(WM_DDE_ACK, lParam);

    }

}

if (atomItem == 0) {

     .

     . /* error handling */

     .

}

In this example, the server application allocates a memory object to contain the data item. The memory is allocated with the GMEM_DDESHARE option, so that the server and client applications can share the memory. After allocating the memory object, the server application locks the object so it can obtain the object's address. The data object is initialized as a DDEDATA structure.

The server application then sets the cfFormat member of the structure to CF_TEXT to inform the client application that the data is in text format. In response, the client copies the value of the requested data into the Value member of the DDEDATA structure.

After the server has filled the data object, the server unlocks the data and creates a global atom containing the name of the data item.

Finally, the server issues the WM_DDE_DATA message by calling the PostMessage function. The handle of the data object and the atom containing the item name are packed into the lParam parameter of the message by the PackDDElParam function.

If PostMessage fails, the server must use the FreeDDElParam function to free the packed lParam parameter. The server must also free the packed lParam parameter for the WM_DDE_REQUEST message it received.

If the server cannot satisfy the request, it sends the client a negative WM_DDE_ACK message, as shown in the following example.

/* negative acknowledgment */

PostMessage(hwndClientDDE,

    WM_DDE_ACK,

    (WPARAM) hwndServerDDE,

    PackDDElParam(WM_DDE_ACK, 0, atomItem));

Upon receiving a WM_DDE_DATA message, the client processes the data-item value as appropriate. Then, if the fAckReq member specified in the WM_DDE_DATA message is 1, the client must send the server a positive WM_DDE_ACK message, as shown in the following example.

UnpackDDElParam(WM_DDE_DATA, lParam, (PUINT) &hData,

    (PUINT) &atomItem);

if (!(lpDDEData = (DDEDATA FAR*) GlobalLock(hData))

        || (lpDDEData->cfFormat != CF_TEXT)) {

    PostMessage(hwndServerDDE,

        WM_DDE_ACK,

        (WPARAM) hwndClientDDE,

        PackDDElParam(WM_DDE_ACK, 0, atomItem)); /* negative ACK */

}

/* Copy data from lpDDEData here.*/

if (lpDDEData->fAckReq) {

    PostMessage(hwndServerDDE,

        WM_DDE_ACK,

        (WPARAM) hwndClientDDE,

        PackDDElParam(WM_DDE_ACK, 0x8000,

            atomItem)); /* positive ACK */

}

bRelease = lpDDEData->fRelease;

GlobalUnlock(hData);

if (bRelease)

    GlobalFree(hData);

In this example, the client examines the format of the data. If the format is not CF_TEXT (or if the client cannot lock the memory for the data), the client sends a negative WM_DDE_ACK message to indicate that it cannot process the data. If the client cannot lock a data handle because the handle contains the fAckReq member, the client should not send a negative WM_DDE_ACK message. Instead, the client should terminate the conversation.

If a client sends a negative acknowledgement in response to a WM_DDE_DATA message, the server is responsible for freeing the memory (but not the lParam parameter) referenced by the WM_DDE_DATA message associated with the negative acknowledgement.

If it can process the data, the client examines the fAckReq member of the DDEDATA structure to determine whether the server requested that it be informed that the client received and processed the data successfully. If the server did request this information, the client sends the server a positive WM_DDE_ACK message.

Because unlocking data invalidates the pointer to the data, the client saves the value of the fRelease member before unlocking the data object. After saving the value, the client then examines it to determine whether the server application requested the client to free the memory containing the data; the client acts accordingly.

Upon receiving a negative WM_DDE_ACK message, the client can ask for the same item value again, specifying a different clipboard format. Typically, a client will first ask for the most complex format it can support, then step down if necessary through progressively simpler formats until it finds one the server can provide.

If the server supports the Formats item of the System topic, the client can determine once what clipboard formats the server supports, instead of determining them each time the client requests an item. For more information about the System topic, see The System Topic.

Submitting an Item to the Server

The client may send an item value to the server by using the WM_DDE_POKE message. The client renders the item to be sent and sends the WM_DDE_POKE message, as illustrated in the following example.

if (!(hPokeData = GlobalAlloc(GMEM_MOVEABLE | GMEM_DDESHARE,

        (LONG) sizeof(DDEPOKE) + lstrlen(szValue) + 2)))

    return;

if (!(lpPokeData = (DDEPOKE FAR*) GlobalLock(hPokeData))) {

    GlobalFree(hPokeData);

    return;

}

lpPokeData->fRelease = TRUE;

lpPokeData->cfFormat = CF_TEXT;

lstrcpy((LPSTR) lpPokeData->Value, (LPSTR) szValue);

/* Each line of CF_TEXT data is terminated by CR/LF. */

lstrcat((LPSTR) lpPokeData->Value, (LPSTR) "\r\n");

GlobalUnlock(hPokeData);

if ((atomItem = GlobalAddAtom((LPSTR) szItem)) != 0) {

       .

       .

       .

        if (!PostMessage(hwndServerDDE,

                WM_DDE_POKE,

                (WPARAM) hwndClientDDE,

                PackDDElParam(WM_DDE_POKE, (UINT) hPokeData,

                    atomItem))) {

           GlobalDeleteAtom(atomItem);

           GlobalFree(hPokeData);

        }

}

if (atomItem == 0) {

     .

     . /* error handling */

     .

}

Note that sending data by using a WM_DDE_POKE message is essentially the same as sending it by using a WM_DDE_DATA message, except that WM_DDE_POKE is sent from the client to the server.

If the server is able to accept the data-item value in the format rendered by the client, the server processes the item value as appropriate and sends the client a positive WM_DDE_ACK message. If it is unable to process the item value, because of its format or for other reasons, the server sends the client a negative WM_DDE_ACK message.

UnpackDDElParam(WM_DDE_POKE, lParam, (PUINT) &hPokeData,

    (PUINT) &atomItem);

GlobalGetAtomName(atomItem, szItemName, ITEM_NAME_MAX_SIZE);

if (!(lpPokeData = (DDEPOKE FAR*) GlobalLock(hPokeData))

        || lpPokeData->cfFormat != CF_TEXT

        || !IsItemSupportedByServer(szItemName)) {

    PostMessage(hwndClientDDE,

        WM_DDE_ACK,

        (WPARAM) hwndServerDDE,

        PackDDElParam(WM_DDE_ACK, 0, atomItem)); /* negative ACK */

}

lstrcpy(szItemValue, lpPokeData->Value); /* copies value */

bRelease = lpPokeData->fRelease;

GlobalUnlock(hPokeData);

if (bRelease) {

    GlobalFree(hPokeData);

}

PostMessage(hwndClientDDE,

    WM_DDE_ACK,

    (WPARAM) hwndServerDDE,

    PackDDElParam(WM_DDE_ACK,

         0x8000, atomItem));    /* positive ACK */

In this example, the server calls the GlobalGetAtomName function to retrieve the name of the item the client sent. The server then determines whether it supports the item and whether the item is rendered in the correct format (that is, CF_TEXT). If the item is not supported and not rendered in the correct format, or if the server cannot lock the memory for the data, the server sends a negative acknowledgment back to the client application. Note that in this case, sending a negative acknowledgement is correct because WM_DDE_POKE messages are always assumed to have the fAckReq member set. The server should ignore the member.

If a server sends a negative acknowledgement in response to a WM_DDE_POKE message, the client is responsible for freeing the memory (but not the lParam parameter) referenced by the WM_DDE_POKE message associated with the negative acknowledgement.


Establishing a Permanent Data Link

A client application can use DDE to establish a link to an item in a server application. Once such a link is established, the server sends periodic updates of the linked item to the client, typically, whenever the value of the item changes. Thus, a permanent data stream is established between the two applications; this data stream remains in place until it is explicitly disconnected.

Initiating a Data Link

The client initiates a data link by posting a WM_DDE_ADVISE message, as shown in the following example.

if (!(hOptions = GlobalAlloc(GMEM_MOVEABLE | GMEM_DDESHARE,

        sizeof(DDEADVISE))))

    return;

if (!(lpOptions = (DDEADVISE FAR*) GlobalLock(hOptions))) {

    GlobalFree(hOptions);

    return;

}

lpOptions->cfFormat = CF_TEXT;

lpOptions->fAckReq = TRUE;

lpOptions->fDeferUpd = FALSE;

GlobalUnlock(hOptions);

if ((atomItem = GlobalAddAtom(szItemName)) != 0) {

    if (!(PostMessage(hwndServerDDE,

            WM_DDE_ADVISE,

            (WPARAM) hwndClientDDE,

            PackDDElParam(WM_DDE_ADVISE, (UINT) hOptions,

                atomItem)))) {

        GlobalDeleteAtom(atomItem);

        GlobalFree(hOptions);

        FreeDDElParam(WM_DDE_ADVISE, lParam);

    }

}

if (atomItem == 0) {

    .

    . /* error handling */

    .

}

In this example, the client application sets the fDeferUpd member of the WM_DDE_ADVISE message to FALSE. This directs the server application to send the data to the client whenever the data changes.

If the server has access to the item and can render it in the requested format, the server notes the new link (recalling the flags specified in the hOptions parameter) and sends the client a positive WM_DDE_ACK message. From then on, until the client issues a matching WM_DDE_UNADVISE message, the server sends the new data to the client every time the value of the item changes in the server application.

If the server is unable to service the WM_DDE_ADVISE request, it sends the client a negative WM_DDE_ACK message.

The WM_DDE_ADVISE message establishes the format of the data to be exchanged during the link. If the client attempts to establish another link with the same item but is using a different data format, the server can choose to either reject the second data format or attempt to support it. If a warm link has been established for any data item, the server can support only one data format at a time. This is because the WM_DDE_DATA message for a warm link has a NULL data handle, which otherwise contains the format information. Thus, a server must reject all warm links for an item already linked, and it must reject all links for an item that has any warm links.

Another interpretation may be that the server changes the format and the hot/warm state of a link when a second link is requested for the same data item.

In general, client applications should not attempt to establish more than one link at a time for a data item.

Initiating a Data Link with the Paste Link Command

Applications that support hot or warm data links typically support a registered clipboard format named Link. When associated with the application's Copy and Paste Link commands, this clipboard format enables the user to establish DDE conversations between applications simply by copying a data item in the server application and pasting it into the client application.

A server application supports the Link clipboard format by placing in the clipboard a string containing the application, topic, and item names when the user chooses the Copy command from the Edit menu. Following is the standard Link format:

application\0topic\0item\0\0

A single null character separates the names, and two null characters terminate the entire string.

Both the client and server applications must register the Link clipboard format, as shown:

cfLink = RegisterClipboardFormat("Link");

A client application supports the Link clipboard format by means of a Paste Link command on its Edit menu. When the user chooses this command, the client application parses the application, topic, and item names from the Link-format clipboard data. Using these names, the client application initiates a conversation for the application and topic, if such a conversation does not already exist. The client application then sends a WM_DDE_ADVISE message to the server application, specifying the item name contained in the Link-format clipboard data.

Following is an example of a client application's response when the user chooses the Paste Link command.

void DoPasteLink(hwndClientDDE)

HWND hwndClientDDE;

{

    HANDLE hData;

    LPSTR lpData;

    HWND hwndServerDDE;

    CHAR szApplication[APP_MAX_SIZE + 1];

    CHAR szTopic[TOPIC_MAX_SIZE + 1];

    CHAR szItem[ITEM_MAX_SIZE + 1];

    int nBufLen;

    if (OpenClipboard(hwndClientDDE)) {

        if (!(hData = GetClipboardData(cfLink)) ||

                !(lpData = GlobalLock(hData))) {

            CloseClipboard();

            return;

        }

        /* Parse the clipboard data. */

        if ((nBufLen = lstrlen(lpData)) >= APP_MAX_SIZE) {

            CloseClipboard();

            GlobalUnlock(hData);

            return;

        }

        lstrcpy(szApplication, lpData);

        lpData += (nBufLen + 1); /* skips over null */

        if ((nBufLen = lstrlen(lpData)) >= TOPIC_MAX_SIZE) {

            CloseClipboard();

            GlobalUnlock(hData);

            return;

        }

        lstrcpy(szTopic, lpData);

        lpData += (nBufLen + 1); /* skips over null */

        if ((nBufLen = lstrlen(lpData)) >= ITEM_MAX_SIZE) {

            CloseClipboard();

            GlobalUnlock(hData);

            return;

        }

        lstrcpy(szItem, lpData);

        GlobalUnlock(hData);

        CloseClipboard();

        if (hwndServerDDE =

                FindServerGivenAppTopic(szApplication, szTopic)) {

            /* App/topic conversation is already started. */

            if (DoesAdviseAlreadyExist(hwndServerDDE, szItem))

                MessageBox(hwndMain,

                    "Advisory already established",

                    "Client", MB_ICONEXCLAMATION | MB_OK);

            else

                SendAdvise(hwndClientDDE, hwndServerDDE, szItem);

        }

        else {

            /* Client must initiate a new conversation first. */

            SendInitiate(szApplication, szTopic);

            if (hwndServerDDE =

                    FindServerGivenAppTopic(szApplication,

                        szTopic))

                SendAdvise(hwndClientDDE, hwndServerDDE, szItem);

        }

    }

    return;

}

In this example, the client application opens the clipboard and determines whether it contains data in the Link format (that is, cfLink) it had previously registered. If not, or if it cannot lock the data in the clipboard, the client returns.

After the client application retrieves a pointer to the clipboard data, it parses the data to extract the application, topic, and item names.

The client application determines whether a conversation on the topic already exists between it and the server application. If a conversation does exist, the client application checks whether a link already exists for the data item. If such a link exists, the client displays a message box to the user; otherwise, it calls its own SendAdvise function to send a WM_DDE_ADVISE message to the server for the item.

If a conversation on the topic does not already exist between the client and the server, the client first calls its own SendInitiate function to broadcast the WM_DDE_INITIATE message to request a conversation and, second, calls its own FindServerGivenAppTopic function to establish the conversation with the window that responds on behalf of the server application. Once the conversation has begun, the client application calls SendAdvise to request the link.

Notifying the Client that Data Has Changed

When the client establishes a link by using the WM_DDE_ADVISE message, with the fDeferUpd member not set (that is, equal to zero), the client has requested the server send the data item each time the item's value changes. In such cases, the server renders the new value of the data item in the previously specified format and sends the client a WM_DDE_DATA message, as shown in the following example.

/*

 * Allocate the size of a DDE data header, plus data (a string),

 * plus a <CR><LF><NULL>

 */

if (!(hData = GlobalAlloc(GMEM_MOVEABLE | GMEM_DDESHARE,

        sizeof(DDEDATA) + lstrlen(szItemValue) + 3)))

    return;

if (!(lpData = (DDEDATA FAR*) GlobalLock(hData))) {

    GlobalFree(hData);

    return;

}

lpData->fAckReq = bAckRequest;  /* as specified in original     */

                                /* WM_DDE_ADVISE message        */

lpData->cfFormat = CF_TEXT;

lstrcpy(lpData->Value, szItemValue); /* copies value to be sent */

lstrcat(lpData->Value, "\r\n"); /* CR/LF for CF_TEXT format     */

GlobalUnlock(hData);

if ((atomItem = GlobalAddAtom(szItemName)) != 0) {

    if (!PostMessage(hwndClientDDE,

            WM_DDE_DATA,

            (WPARAM) hwndServerDDE,

            PackDDElParam(WM_DDE_DATA, (UINT) hData, atomItem))) {

        GlobalFree(hData);

        GlobalDeleteAtom(atomItem);

        FreeDDElParam(WM_DDE_DATA, lParam);

    }

}

if (atomItem == 0) {

     .

     . /* error handling */

     .

}

In this example, the client processes the item value as appropriate. If the fAckReq flag for the item is set, the client sends the server a positive WM_DDE_ACK message.

When the client establishes the link, with the fDeferUpd member set (that is, equal to 1), the client has requested that only a notification, not the data itself, be sent each time the data changes. In such cases, when the item value changes, the server does not render the value but simply sends the client a WM_DDE_DATA message with a null data handle, as illustrated in the following example.

if (bDeferUpd) {     /* checking whether the flag was originally */

                     /* set in the WM_DDE_ADVISE message         */

    if ((atomItem = GlobalAddAtom(szItemName)) != 0) {

        if (!PostMessage(hwndClientDDE,

                WM_DDE_DATA,

                (WPARAM) hwndServerDDE,

                PackDDElParam(WM_DDE_DATA, 0,

                    atomItem))) {                   /* NULL data */

            GlobalDeleteAtom(atomItem);

            FreeDDElParam(WM_DDE_DATA, lParam);

        }

    }

}

if (atomItem == 0) {

     .

     . /* error handling */

     .

}

As necessary, the client can request the latest value of the data item by issuing a normal WM_DDE_REQUEST message, or it can simply ignore the notice from the server that the data has changed. In either case, if fAckReq is equal to 1, the client is expected to send a positive WM_DDE_ACK message to the server.

Terminating a Data Link

If the client requests that a specific data link be terminated, the client sends the server a WM_DDE_UNADVISE message, as shown in the following example.

if ((atomItem = GlobalAddAtom(szItemName)) != 0) {

    if (!PostMessage(hwndServerDDE,

            WM_DDE_UNADVISE,

            (WPARAM) hwndClientDDE,

            PackDDElParam(WM_DDE_UNADVISE, 0, atomItem))) {

        GlobalDeleteAtom(atomItem);

        FreeDDElParam(WM_DDE_UNADVISE, lParam);

    }

}

if (atomItem == 0) {

     .

     . /* error handling */

     .

}

The server checks whether the client currently has a link to the specific item in this conversation. If a link exists, the server sends the client a positive WM_DDE_ACK message; the server is then no longer required to send updates about the item. If no link exists, the server sends the client a negative WM_DDE_ACK message.

The WM_DDE_UNADVISE message specifies a data format. A format of zero informs the server to stop all links for the specified item, even if several hot links are established and each uses a different format.

To terminate all links for a conversation, the client sends the server a WM_DDE_UNADVISE message with a null item atom. The server determines whether the conversation has at least one link currently established. If a link exists, the server sends the client a positive WM_DDE_ACK message; the server then no longer has to send any updates in the conversation. If no link exists, the server sends the client a negative WM_DDE_ACK message.


Carrying Out Commands in a Server Application

A Windows-based application can use the WM_DDE_EXECUTE message to cause a certain command or series of commands to be carried out in another application. To do this, the client sends the server a WM_DDE_EXECUTE message containing a handle of a command string, as shown in the following example.

if (!(hCommand = GlobalAlloc(GMEM_MOVEABLE | GMEM_DDESHARE,

        sizeof(szCommandString) + 1)))

    return;

if (!(lpCommand = GlobalLock(hCommand))) {

    GlobalFree(hCommand);

    return;

}

lstrcpy(lpCommand, szCommandString);

GlobalUnlock(hCommand);

if (!PostMessage(hwndServerDDE,

        WM_DDE_EXECUTE,

        (WPARAM) hwndClientDDE,

        PackDDElParam(WM_DDE_EXECUTE, 0, (UINT) hCommand))) {

    GlobalFree(hCommand);

    FreeDDElParam(WM_DDE_EXECUTE, lParam);

}

In this example, the server attempts to carry out the specified command string. If it succeeds, the server sends the client a positive WM_DDE_ACK message; otherwise, it sends a negative WM_DDE_ACK message. This WM_DDE_ACK message reuses the hCommand handle passed in the original WM_DDE_EXECUTE message.

If the client's command execution string requests that the server terminate, the server should respond by sending a positive WM_DDE_ACK message and then post a WM_DDE_TERMINATE message before terminating. All other commands sent with a WM_DDE_EXECUTE message should be executed synchronously; that is, the server should send a WM_DDE_ACK message only after successfully completing the command.


Terminating a Conversation

Either the client or the server can issue a WM_DDE_TERMINATE message to terminate a conversation at any time. Similarly, both the client and server applications should be prepared to receive this message at any time. An application must terminate all of its conversations before shutting down.

In the following example, the application terminating the conversation posts a WM_DDE_TERMINATE message.

PostMessage(hwndServerDDE, WM_DDE_TERMINATE,

    PackDDElParam(WM_DDE_TERMINATE, (UINT) hwndClientDDE, 0), 0);

This informs the other application that the sending application will send no further messages and the recipient can close its window. The recipient is expected in all cases to respond promptly by sending a WM_DDE_TERMINATE message. The recipient must not send a negative, busy, or positive WM_DDE_ACK message.

After an application has sent the WM_DDE_TERMINATE message to the partner in a DDE conversation, it must not respond to any messages from that partner, since the partner might already have destroyed the window to which the response would be sent.

If a DDE application receives a DDE message other than WM_DDE_TERMINATE after it has posted a WM_DDE_TERMINATE message, it should free all objects associated with the received messages except the data handles for WM_DDE_DATA or WM_DDE_POKE messages that do not have the fRelease member set.

When an application is about to terminate, it should end all active DDE conversations before completing processing of the WM_DESTROY message. However, if an application does not end its active DDE conversations, the system will properly terminate any DDE conversations associated with a window when the window is destroyed. The following example shows how a server application terminates all DDE conversations.

void TerminateConversations(hwndServerDDE)

HWND hwndServerDDE;

{

    HWND hwndClientDDE;

    /* Terminate each active conversation. */

    while (hwndClientDDE = GetNextLink(hwndClientDDE)) {

        SendTerminate(hwndServerDDE, hwndClientDDE);

    }

    return;

}

BOOL AtLeastOneLinkActive(VOID)

{

    return TRUE;

}

HWND GetNextLink(hwndDummy)

    HWND hwndDummy;

{

    return (HWND) 1;

}

VOID SendTerminate(HWND hwndServerDDE, HWND hwndClientDDE)

{

    return;

}


Functions and Messages

Following are the functions and messages used with DDE.

Functions

DdeSetQualityOfService

FreeDDElParam

PackDDElParam

ReuseDDElParam

UnpackDDElParam

Messages

WM_DDE_ACK

WM_DDE_ADVISE

WM_DDE_DATA

WM_DDE_EXECUTE

WM_DDE_INITIATE

WM_DDE_POKE

WM_DDE_REQUEST

WM_DDE_TERMINATE

WM_DDE_UNADVISE


Multiple Document Interface Overview

About the Multiple Document Interface

The multiple document interface (MDI) is a specification that defines the standard user interface for applications written for Microsoft® Windows™. An MDI application enables the user to work with more than one document at the same time. Each document is displayed in a separate child window within the client area of the application's main window. Typical MDI applications include word processing applications that allow the user to work with multiple text documents, and spreadsheet applications that allow the user to work with multiple charts and spreadsheets.

Windows provides extensive support for MDI applications. This topic describes the structure of an MDI application and how to take advantage of the built-in MDI support found in the Win32 application program interface (API).

The following topics discuss the Win32 multiple document interface:

Terms

Frame, Client, and Child Windows

Child Window Creation

Child Window Activation

Menus

Accelerators

Child Window Size and Arrangement

Icon Title Windows

Child Window Data

Registering the Child and Frame Window Classes

Creating the Frame and Child Windows

Writing the Main Message Loop

Writing the Frame Window Procedure

Writing the Child Window Procedure

Creating a Child Window

Functions and Messages


Frame, Client, and Child Windows

An MDI application has three kinds of windows: a frame window, a client window, as well as a number of child windows. The frame window is like the main window of the application: it has a sizing border, a title bar, a System menu, a Minimize button, and a Maximize button. The application must register a window class for the frame window and provide a window procedure to support it.

An MDI application does not display output in the client area of the frame window. Instead, it displays the MDI client window. An MDI client window is a special type of child window belonging to the preregistered window class MDICLIENT. The client window is a child of the frame window; it serves as the background for child windows. It also provides support for creating and manipulating child windows. For example, an MDI application can create, activate, or maximize child windows by sending messages to the MDI client window.

When the user opens or creates a document, the client window creates a child window for the document. The client window is the parent window of all MDI child windows in a given application. Each child window has a sizing border, a title bar, a System menu (also known as the Control menu), a Minimize button, and a Maximize button. Because a child window is clipped, it is confined to the client window and cannot appear outside it.

An MDI application can support more than one kind of document. For example, a typical spreadsheet application enables the user to work with both charts and spreadsheets. For each type of document that it supports, an MDI application must register a child window class and provide a window procedure to support the windows belonging to that class.

Following is a typical MDI application. It is named Multipad.


Child Window Creation

To create a child window, an MDI application either calls the CreateMDIWindow function or sends the WM_MDICREATE message to the MDI client window. A thread in an MDI application can use CreateMDIWindow to create a child window in a different thread. The WM_MDICREATE message is used only in the context of the same thread.

To destroy a child window, an MDI application sends a WM_MDIDESTROY message to the MDI client window.


Child Window Activation

Any number of child windows can appear in the client window at any one time, but only one can be active. The active child window is positioned in front of all other child windows, and its border is highlighted.

The user can activate an inactive child window by clicking it. An MDI application activates a child window by sending a WM_MDIACTIVATE message to the MDI client window. As the client window processes this message, it sends a WM_MDIACTIVATE message to the window procedure of the child window to be activated and to the window procedure of the child window being deactivated.

Windows keeps track of each child window's position in the stack of overlapping windows. This stacking is known as the Z order. The user can activate the next child window in the Z order by choosing the Next command from the System menu in the active window. An application activates the next (or previous) child window in the Z order by sending a WM_MDINEXT message to the client window.

To retrieve the handle of the active child window, the MDI application sends a WM_MDIGETACTIVE message to the client window.


Menus

The frame window of an MDI application should include a menu bar with a Window menu item and its corresponding pop-up menu. The Window pop-up menu should include command items that arrange the child windows within the client window or that close all child windows. The Window menu of a typical MDI application might include the items in the following table.

Menu item	Purpose

Tile	Arranges child windows in a tile format so that each appears in its entirety in the client window.

Cascade	Arranges child windows in a cascade format. The child windows overlap one another, but the title bar of each is visible.

Arrange Icons	Arranges the icons of minimized child windows along the bottom of the client window.

Close All	Closes all child windows.

Whenever a child window is created, Windows automatically appends a new menu item to the Window menu. The text of the menu item is the same as the text on the menu bar of the new child window. By choosing the menu item, the user can activate the corresponding child window. When a child window is destroyed, Windows automatically removes the corresponding menu item from the Window menu.

Windows can add up to ten menu items to the Window menu. When the tenth child window is created, Windows adds the More Windows item to the Window menu. Choosing this item causes the Select Window dialog box to appear. The dialog box contains a list box with the titles of all MDI child windows currently available. The user can activate a child window by choosing its title from the list box.

If your MDI application supports several types of child windows, tailor the menu bar to reflect the operations associated with the active window. To do this, provide separate menu resources for each type of child window the application supports. When a new type of child window is activated, the application should send a WM_MDISETMENU message to the client window, passing to it the handle of the corresponding menu.

When no child window exists, the menu bar should contain only items used to create or open a document.

When the user is navigating through an MDI application's menus by using cursor keys, the keys behave differently than when the user is navigating through a typical application's menus. In an MDI application, control passes from the application's System menu to the System menu of the active child window, and then to the first item on the menu bar.


Accelerators

To receive and process accelerator keys for its child windows, an MDI application must include the TranslateMDISysAccel function in its message loop. The loop must call TranslateMDISysAccel before calling the TranslateAccelerator or DispatchMessage function.

Accelerator keys on the System menu for an MDI child window are different from those for a non-MDI child window. In an MDI child window, the ALT+ - (minus) key combination opens the System menu, the CTRL+F4 key combination closes the active child window, and the CTRL+F6 key combination activates the next child window.


Child Window Size and Arrangement

An MDI application controls the size and position of its child windows by sending messages to the MDI client window. To maximize the active child window, the application sends the WM_MDIMAXIMIZE message to the client window. When a child window is maximized, its client area completely fills the MDI client window. In addition, Windows automatically hides the child window's title bar, and adds the child window's System menu icon and restore icon to the MDI application's menu bar. The application can restore the client window to its original (pre-maximized) size and position by sending the client window a WM_MDIRESTORE message.

An MDI application can arrange its child windows in either a cascade or tile format. When the child windows are cascaded, the windows appear in a stack. The window on the bottom of the stack occupies the upper-left corner of the screen, and the remaining windows are offset vertically and horizontally so that the left border and title bar of each child window is visible. To arrange child windows in the cascade format, an MDI application sends the WM_MDICASCADE message. Typically, the application sends this message when the user chooses the Cascade command from the Window menu.

When the child windows are tiled, Windows displays each child window in its entirety--overlapping none of the windows. All of the windows are sized, as necessary, to fit within the client window. To arrange child windows in the tile format, an MDI application sends a WM_MDITILE message to the client window. Typically, the application sends this message when the user chooses the Tile command from the Window menu.

An MDI application should provide a different icon for each type of child window it supports. The application specifies an icon when registering the child window class. Windows automatically displays a child window's icon in the lower portion of the client window when the child window is minimized. An MDI application directs Windows to arrange child window icons by sending a WM_MDIICONARRANGE message to the client window. Typically, the application sends this message when the user chooses the Arrange Icons command from the Window menu.


Icon Title Windows

Because MDI child windows may be minimized, an MDI application must avoid manipulating icon title windows as if they were normal MDI child windows. Icon title windows appear when the application enumerates child windows of the MDI client window. Icon title windows differ from other child windows, however, in that they are owned by an MDI child window.

To determine whether a child window is an icon title window, use the GetWindow function with the GW_OWNER index. Non-title windows return NULL. Note that this test is insufficient for top-level windows, because menus and dialog boxes are owned windows.


Child Window Data

Because the number of child windows varies depending on how many documents the user opens, an MDI application must be able to associate data (for example, the name of the current file) with each child window. There are two ways to do this:

Store child window data in the window structure.

Use window properties.

Data in the Window Structure

When an MDI application registers a window class, it may reserve extra space in the window structure for application data specific to this particular class of windows. To store and retrieve data in this extra space, the application uses the GetWindowWord, SetWindowWord, GetWindowLong, and SetWindowLong functions.

To maintain a large amount of data for a child window, an application can allocate memory for a data structure and then store the handle of the memory containing the structure in the extra space associated with the child window.

Window Properties

An MDI application can also store per-document data by using window properties. (Per-document data is data specific to the type of document contained in a particular child window.) Properties are different from extra space in the window structure in that you need not allocate extra space when registering the window class. A window can have any number of properties. Also, where offsets are used to access the extra space in window structures, properties are referred to by string names.

To illustrate these tasks, this section includes sample code from Multipad, a typical MDI application.


Registering Child and Frame Window Classes

A typical MDI application must register two window classes: one for its frame window and one for its child windows. If an application supports more than one type of document (for example, a spreadsheet and a chart), it must register a window class for each type.

The class structure for the frame window is similar to the class structure for the main window in non-MDI applications. The class structure for the MDI child windows differs slightly from the structure for child windows in non-MDI applications as follows:

The class structure should have an icon, because the user can minimize an MDI child window as if it were a normal application window.

The menu name should be NULL, because an MDI child window cannot have its own menu.

The class structure should reserve extra space in the window structure. With this space, the application can associate data, such as a filename, with a particular child window.

The following code shows how Multipad registers its frame and child window classes.

BOOL APIENTRY InitializeApplication()

{

    WNDCLASS wc;

    /* Register the frame window class. */

    wc.style         = 0;

    wc.lpfnWndProc   = (WNDPROC) MPFrameWndProc;

    wc.cbClsExtra    = 0;

    wc.cbWndExtra    = 0;

    wc.hInstance     = hInst;

    wc.hIcon         = LoadIcon(hInst, IDMULTIPAD);

    wc.hCursor       = LoadCursor((HANDLE) NULL, IDC_ARROW);

    wc.hbrBackground = (HBRUSH) (COLOR_APPWORKSPACE + 1);

    wc.lpszMenuName  = IDMULTIPAD;

    wc.lpszClassName = szFrame;

    if (!RegisterClass (&wc) )

        return FALSE;

    /* Register the MDI child window class. */

    wc.lpfnWndProc   = (WNDPROC) MPMDIChildWndProc;

    wc.hIcon         = LoadIcon(hInst, IDNOTE);

    wc.lpszMenuName  = (LPCTSTR) NULL;

    wc.cbWndExtra    = CBWNDEXTRA;

    wc.lpszClassName = szChild;

    if (!RegisterClass(&wc))

        return FALSE;

    return TRUE;

}


Creating Frame and Child Windows

After registering its window classes, an MDI application can create its windows. First, it creates its frame window by using the CreateWindow or CreateWindowEx function. After creating its frame window, the application creates its client window, again by using CreateWindow or CreateWindowEx. The application should specify MDICLIENT as the client window's class name; MDICLIENT is a preregistered window class defined by Windows. The lpvParam parameter of CreateWindow or CreateWindowEx should point to a CLIENTCREATESTRUCT structure. This structure contains the members described in the following table.

Member	Description

hWindowMenu	Identifies the Window menu used for controlling MDI child windows. As child windows are created, the application adds their titles to the Window menu as menu items. The user can then activate a child window by choosing its title from the Window menu.

idFirstChild	Specifies the identifier of the first MDI child window. The first MDI child window created is assigned this identifier. Additional windows are created with incremented window identifiers. When a child window is destroyed, Windows immediately reassigns the window identifiers to keep their range contiguous.

When a child window's title is added to the Window menu, Windows assigns an identifier to the child window. When the user chooses a child window's title, the frame window receives a WM_COMMAND message with the identifier in the wParam parameter. You should specify a value for the idFirstChild member that does not conflict with menu-item identifiers in the frame window's menu.

Multipad's frame window procedure creates the MDI client window while processing the WM_CREATE message. The following example shows how the client window is created.

.

. /* Process other messages here. */

.

case WM_CREATE:

    {

    CLIENTCREATESTRUCT ccs;

    /*

     * Retrieve the handle of the Window menu and assign the

     * first child window identifier.

     */

    ccs.hWindowMenu = GetSubMenu(GetMenu(hwnd), WINDOWMENU);

    ccs.idFirstChild = IDM_WINDOWCHILD;

    /* Create the MDI client window. */

    hwndMDIClient = CreateWindow( "MDICLIENT", (LPCTSTR) NULL,

        WS_CHILD | WS_CLIPCHILDREN | WS_VSCROLL | WS_HSCROLL,

        0, 0, 0, 0, hwnd, (HMENU) 0xCAC, hInst, (LPSTR) &ccs);

    ShowWindow(hwndMDIClient, SW_SHOW);

    }

    break;

}

.

. /* Process other messages here. */

.

Titles of child windows are added to the bottom of the Window menu. If the application adds strings to the Window menu by using the AppendMenu function, these strings can be overwritten by the titles of the child windows when the Window menu is repainted. (The Window menu is repainted whenever a child window is created or destroyed.) An MDI application that adds strings to its Window menu should use the InsertMenu function and verify that the titles of child windows have not overwritten these new strings.

Use the WS_CLIPCHILDREN style to create the MDI client window to prevent the window from painting over its child windows.


Writing the Main Message Loop

The main message loop of an MDI application is similar to that of a non-MDI application handling accelerator keys. The difference is that the MDI message loop calls the TranslateMDISysAccel function before checking for application-defined accelerator keys or before dispatching the message.

The following example shows the message loop of a typical MDI application.

while (GetMessage(&msg, (HWND) NULL, 0, 0)) {

    if (!TranslateMDISysAccel(hwndMDIClient, &msg) &&

            !TranslateAccelerator(hwndFrame, hAccel, &msg)){

        TranslateMessage(&msg);

        DispatchMessage(&msg);

    }

}

The TranslateMDISysAccel function translates WM_KEYDOWN messages into WM_SYSCOMMAND messages and sends them to the active MDI child window. If the message is not an MDI accelerator message, the function returns FALSE, in which case the application uses the TranslateAccelerator function to determine whether any of the application-defined accelerator keys were pressed. If not, the loop dispatches the message to the appropriate window procedure.


Writing the Frame Window Procedure

The window procedure for an MDI frame window is similar to that of a non-MDI application's main window. The difference is that a frame window procedure passes all messages it does not handle to the DefFrameProc function rather than to the DefWindowProc function. In addition, the frame window procedure must also pass some messages that it does handle, including those listed in the following table.

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

The frame window procedure in Multipad is called MPFrameWndProc. The handling of other messages by MPFrameWndProc is similar to that of non-MDI applications. WM_COMMAND messages in Multipad are handled by the locally defined CommandHandler function. For command messages Multipad does not handle, CommandHandler calls the DefFrameProc function. If Multipad doesn't use DefFrameProc by default, the user can't activate a child window from the Window menu, because the WM_COMMAND message sent by choosing the window's menu item (command) would be lost.


Writing the Child Window Procedure

Like the frame window procedure, an MDI child window procedure uses a special function for processing messages by default. All messages that the child window procedure does not handle must be passed to the DefMDIChildProc function rather than to the DefWindowProc function. In addition, some window-management messages must be passed to DefMDIChildProc, even if the application handles the message, in order for MDI to function correctly. Following are the messages the application must pass to DefMDIChildProc.

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 System menu commands: SC_NEXTWINDOW, SC_PREVWINDOW, SC_MOVE, SC_SIZE, and SC_MAXIMIZE.


Creating a Child Window

To create an MDI child window, an application can either call the CreateMDIWindow function or send a WM_MDICREATE message to the MDI client window. (The application must not use the CreateWindow function to create MDI child windows.) A single-threaded MDI application can use either method to create a child window. A thread in a multithreaded MDI application must use the CreateMDIWindow function to create a child window in a different thread.

The lParam parameter of a WM_MDICREATE message is a far pointer to an MDICREATESTRUCT structure. The structure includes four dimension members: x and y, which indicate the horizontal and vertical positions of the window, and cx and cy, which indicate the horizontal and vertical extents of the window. Any of these members may be assigned explicitly by the application, or they may be set to CW_USEDEFAULT, in which case Windows selects a position, size, or both, according to a cascading algorithm. In any case, all four members must be initialized. Multipad uses CW_USEDEFAULT for all dimensions.

The last member of the MDICREATESTRUCT structure is the style member, which may contain style bits for the window. To create an MDI child window that can have any combination of window styles, specify the MDIS_ALLCHILDSTYLES window style. When this style is not specified, an MDI child window has the WS_MINIMIZE, WS_MAXIMIZE, WS_HSCROLL, and WS_VSCROLL styles as default settings.

Multipad creates its MDI child windows by using its locally defined AddFile function (located in the source file MPFILE.C). The AddFile function sets the title of the child window by assigning the szTitle member of the window's MDICREATESTRUCT structure to either the name of the file being edited or to "Untitled." The szClass member is set to the name of the MDI child window class registered in Multipad's InitializeApplication function. The hOwner member is set to the application's instance handle.

The following code sample shows the AddFile function in Multipad.

HWND APIENTRY AddFile(pName)

CHAR * pName;

{

    HWND hwnd;

    CHAR sz[160];

    MDICREATESTRUCT mcs;

    if (!pName) {

        /*

         * If the pName parameter is NULL, load the "Untitled"

         * string from the STRINGTABLE resource and set the szTitle

         * member of MDICREATESTRUCT.

         */

        LoadString(hInst, IDS_UNTITLED, sz, sizeof(sz));

        mcs.szTitle = (LPCTSTR) sz;

    }

    else

        /*

         * Title the window with the full path and filename,

         * obtained by calling the OpenFile function with the

         * OF_PARSE flag, which is called before AddFile().

         */

        mcs.szTitle = of.szPathName;

    mcs.szClass = szChild;

    mcs.hOwner  = hInst;

    /* Use the default size for the child window. */

    mcs.x = mcs.cx = CW_USEDEFAULT;

    mcs.y = mcs.cy = CW_USEDEFAULT;

    /*

     * Give the child window the default style. The styleDefault

     * variable is defined in MULTIPAD.C.

     */

    mcs.style = styleDefault;

    /* Tell the MDI client window to create the child window. */

    hwnd = (HWND) SendMessage (hwndMDIClient, WM_MDICREATE, 0,

        (LONG) (LPMDICREATESTRUCT) &mcs);

    /*

     * If the file is found, read its contents into the child

     * window's client area.

     */

    if (pName) {

        if (!LoadFile(hwnd, pName)) {

            /* Cannot load the file; close the window. */

            SendMessage(hwndMDIClient, WM_MDIDESTROY,

                (DWORD) hwnd, 0L);

        }

    }

    return hwnd;

}

The pointer passed in the lParam parameter of the WM_MDICREATE message is passed to the CreateWindow function and appears as the first member in the CREATESTRUCT structure, passed in the WM_CREATE message. In Multipad, the child window initializes itself during WM_CREATE message processing by initializing document variables in its extra data and by creating the edit control's child window.


Functions and Messages

The following functions and messages are used in MDI applications.

Functions

CreateMDIWindow

DefFrameProc

DefMDIChildProc

TranslateMDISysAccel

Messages

WM_MDIACTIVATE

WM_MDICASCADE

WM_MDICREATE

WM_MDIDESTROY

WM_MDIGETACTIVE

WM_MDIICONARRANGE

WM_MDIMAXIMIZE

WM_MDINEXT

WM_MDIREFRESHMENU

WM_MDIRESTORE

WM_MDISETMENU

WM_MDITILE


Device Contexts Overview

About Device Contexts

One of the chief features of the Microsoft® Win32™ application programming interface (API) is device independence. Applications written for Microsoft® Windows™ can draw and print output on a variety of devices. The software that supports this device independence is contained in two dynamic-link libraries. The first library (GDI.DLL) is referred to as the graphics device interface (GDI); the second library is referred to as a device driver. The name of the second depends on the device where the application draws output. For example, if the application draws output in the client area of its window on a VGA display, this library is VGA.DLL; if the application prints output on an Epson® FX-80 printer, this library is EPSON9.DLL.

An application must inform GDI to load a particular device driver; and, once the driver is loaded, prepare the device for drawing operations (such as selecting a line color and width, a brush pattern and color, a font typeface, a clipping region, and so on). These tasks are accomplished by creating and maintaining a device context. A device context is a structure that defines a set of graphic objects and their associated attributes, and the graphic modes that affect output. The graphic objects include a pen for line drawing, a brush for painting and filling, a bitmap for copying or scrolling parts of the screen, a palette for defining the set of available colors, a region for clipping and other operations, and a path for painting and drawing operations. Unlike most of the Win32 structures, an application never has direct access to the device context; instead, it operates on the structure indirectly by calling various functions.

The following topics discuss Win32 device contexts:

Terms

Graphic Objects and Graphic-Object Attributes

Graphic Modes

Device Context Types

Device Context Operations

Obtaining a Private Display Device Context

Creating a Printer Device Context

Retrieving a Printer's Capabilities

Retrieving Graphic-Object Attributes and Selecting New Graphic Objects

Functions and Message


Graphic Objects

The pen, brush, bitmap, palette, region, and path associated with a device context are referred to as the device context's graphic objects. Following are the attributes associated with each of these objects.

Graphic object	Associated attributes

Bitmap	Size, in bytes; dimensions, in pixels; color-format; compression scheme; and so on

Brush	Style, color, pattern, and origin

Palette	Colors and size (or number of colors)

Font	Typeface name, width, height, weight, character set, and so on

Path	Shape

Pen	Style, width, and color

Region	Location and dimensions

When an application creates a device context, Windows automatically stores a set of default objects in it. (There is, however, no default bitmap or path.) An application can examine the attributes of the default objects by calling the GetCurrentObject and GetObject functions. The application can change these defaults by creating a new object and selecting it into the device context. An object is selected into a device context by calling the SelectObject function. For more information about operations with graphic objects, see Operations on Graphic Objects.


Graphic Modes

Windows supports five graphic modes that allow an application to specify how colors are mixed, where output appears, how the output is scaled, and so on. These modes, stored in a device context, are described in the following table.

Mode	Description

Background mode	Defines how background colors are mixed with existing window or screen colors for bitmap and text operations.

Drawing mode	Defines how foreground colors are mixed with existing window or screen colors for pen, brush, bitmap, and text operations.

Mapping mode	Defines how graphics output is mapped from logical (or world) space onto the window, screen, or printer paper.

Polygon-fill mode	Defines how the brush pattern is used to fill the interior of complex regions.

Stretching mode	Defines how bitmap colors are mixed with existing window or screen colors when the bitmap is compressed (or scaled down).

As it does with graphic objects, Windows initializes a device context with default graphic modes. An application can retrieve and examine these default modes by calling the following functions.

Graphic mode	Function

Background mode	GetBkMode

Drawing mode	GetROP2

Mapping mode	GetMapMode

Polygon-fill mode	GetPolyFillMode

Stretching mode	GetStretchBltMode

An application can change the default modes by calling one of the following functions.

Graphic mode	Function

Background mode	SetBkMode

Drawing mode	SetROP2

Mapping mode	SetMapMode

Polygon-fill mode	SetPolyFillMode

Stretching mode	SetStretchBltMode


Device Context Types

Windows provides four types of device contexts: display, printer, memory (or compatible), and information. Each type serves a specific purpose, as described in the following table.

Device context	Purpose

Display	Supports drawing operations on a video display.

Printer	Supports drawing operations on a printer or plotter.

Memory	Supports drawing operations on a bitmap.

Information	Supports the retrieval of device data.

Display Device Contexts

Windows provides three types of device contexts for video displays: class, common and private. Class and private device contexts are used in applications that perform numerous drawing operations such as CAD applications, desktop-publishing applications, drawing and painting applications, and so on. Common device contexts are used in applications that perform infrequent drawing operations.

An application obtains a display device context by calling either the BeginPaint or GetDC function and identifying the window in which the corresponding output will appear. (The type of device context Windows returns is dependent on how the application registered its window class.) Typically, an application should obtain a display device context only when it must draw in the client area. When the application is finished drawing, it must release the device context by calling the EndPaint or ReleaseDC functions.

Class Device Contexts

Class device contexts are supported strictly for compatibility with previous versions of Windows. When writing a Win32 application, avoid using the class device context. Use a private device context instead.

Common Device Contexts

Common device contexts are display device contexts maintained in a special cache by the window management component of the Win32 API. An application obtains a handle identifying one of the available common device contexts by calling the GetDC, GetDCEx, or BeginPaint function. Before returning this device context handle, Windows initializes a common device context with default objects, attributes, and modes. Any drawing operations performed by the application use these defaults unless one of the GDI functions is called to select a new object, change the attributes of an existing object, or select a new mode.

Because only a limited number of common device contexts exist in the window manager's heap, an application should release these device contexts after it has finished drawing. An application releases a common device context by calling the ReleaseDC or EndPaint function. When the application releases a common device context, any changes to the default data are lost.

Private Device Contexts

Private device contexts are display device contexts that, unlike common device contexts, retain any changes to the default data--even after an application calls the ReleaseDC or EndPaint function. Private device contexts are not part of the window manager's cache and therefore need not be released after use. The window manager automatically removes a private device context after the last window of that class has been destroyed.

An application creates a private device context by first specifying the CS_OWNDC window-class style when it initializes the style member of the WNDCLASS structure and calls the RegisterClass function. (For more information about window classes, see Window Classes).) After creating a window with the CS_OWNDC style, an application can call the GetDC, GetDCEx, or BeginPaint function once to obtain a handle identifying a private device context. The application can continue using this handle (and the associated device context) until it deletes the window created with this class. Any changes to graphic objects and their attributes, or graphic modes are retained by Windows until the window is deleted.

Printer Device Contexts

Windows provides a single type of printer device context that can be used when printing on a dot-matrix printer, ink-jet printer, laser printer, or plotter. An application creates a printer device context by calling the CreateDC function and supplying the appropriate arguments (the name of the printer driver, the name of the printer, the file or device name for the physical output medium, and other initialization data). When an application has finished printing, it deletes the printer device context by calling the DeleteDC function. An application must delete (rather than release) a printer device context, because the ReleaseDC function fails when an application attempts to use it to release a printer device context.

Memory Device Contexts

Windows supports a memory device context that stores bitmapped images for a particular device. An application creates a memory device context by calling the CreateCompatibleDC function and supplying a handle that identifies a device context for a particular device. When Windows processes this call, it creates a bitmap having a color format compatible with the original device. Because the bitmap is compatible with the given device, a memory device context is also sometimes referred to as a compatible device context.

The original bitmap in a memory device context is simply a placeholder. Its dimensions are one pixel by one pixel. Before an application can begin drawing, it must select a bitmap with the appropriate width and height into the device context by calling the SelectObject function. Once the new bitmap is selected into the memory device context, an application can begin using the device context to store images. For more information about bitmaps and bitmap operations, see Bitmaps.

Information Device Contexts

Windows supports an information device context used to retrieve default device data. For example, an application can call the CreateIC function to create an information device context for a particular model of printer and then call the GetCurrentObject and GetObject functions to retrieve the default pen or brush attributes. Because Windows can retrieve device information without creating the structures normally associated with the other types of device contexts, an information device context involves far less overhead and is created significantly faster than any of the other types. After an application finishes retrieving data by using an information device context, it must call the DeleteDC function.


Device Context Operations

An application can perform the following operations on a device context:

Enumerate existing graphic objects.

Select new graphic objects.

Delete existing graphic objects.

Save the current graphic objects, their attributes, and the graphic modes.

Restore previously saved graphic objects, their attributes, and the graphic modes.

In addition, an application can use a device context to determine how graphics output is translated, cancel lengthy drawing operations (begun by a thread in a multithreaded application), or reset a printer to a particular state.

Operations on Graphic Objects

Once an application creates a display or printer device context, it can begin drawing on the associated device or, in the case of the memory device context, it can begin drawing on the bitmap stored in memory. However, before drawing begins and sometimes while drawing is in progress, it is often necessary to replace the default objects with new objects.

An application can examine a default object's attributes by calling the GetCurrentObject and GetObject functions. The GetCurrentObject function returns a handle identifying the current pen, brush, palette, bitmap, or font, and the GetObject function initializes a structure containing that object's attributes.

Some printers provide resident pens, brushes, and fonts that can be used to improve drawing speed in an application. Two functions can be used to enumerate these objects: EnumObjects and EnumFonts. If the application must enumerate resident pens or brushes, it can call the EnumObjects function to examine the corresponding attributes. If the application must enumerate resident fonts, it can call the EnumFonts function (which can also enumerate GDI fonts).

Once an application determines that a default object needs replacing, it creates a new object by calling one of the following creation functions.

Graphic object	Function

Bitmap	CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDiscardableBitmap, CreateDIBitmap

Brush	CreateBrushIndirect, CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush

Color Palette	CreatePalette

Font	CreateFont, CreateFontIndirect

Pen	CreatePen, CreatePenIndirect, ExtCreatePen

Region	CreateEllipticRgn, CreateEllipticRgnIndirect, CreatePolygonRgn, CreatePolyPolygonRgn, CreateRectRgn, CreateRectRgnIndirect, CreateRoundRectRgn

Each of the functions returns a handle identifying a new object. After an application retrieves a handle, it must call the SelectObject function to replace the default object. However, the application should save the handle identifying the default object and use this handle to replace the new object when it is no longer needed. When the application finishes drawing with the new object, it must restore the default object by calling the SelectObject function and delete the new object by calling the DeleteObject function. Not deleting objects causes serious performance problems.

Cancellation of Drawing Operations

When complex drawing applications perform lengthy graphic operations, they consume valuable system resources. By taking advantage of Win32 multitasking features, an application can use threads and the CancelDC function to manage these operations. For example, if the graphic operation performed by thread A is consuming needed resources, thread B can call the CancelDC function to halt that operation.

Retrieving Device Data

Windows supports two functions, GetDeviceCaps and DeviceCapabilities, that applications can use to retrieve device data using a device context. GetDeviceCaps retrieves general device data for the following devices:

Raster displays

Dot-matrix printers

Ink-jet printers

Laser printers

Vector plotters

Raster cameras

The data includes the supported capabilities of the device, including device resolution (for video displays), color format (for video displays and color printers), number of graphic objects, raster capabilities, curve drawing, line drawing, polygon drawing, and text drawing. An application retrieves this data by supplying a handle identifying the appropriate device context as well as an index specifying the type of data the function retrieves.

The DeviceCapabilities function retrieves data specific to printers, including the number of available paper bins, the duplex capabilities of the printer, the resolutions supported by the printer, the maximum and minimum supported paper size, and so on. An application retrieves this data by supplying strings specifying a printer device and port, as well as an index specifying the type of data that the function should retrieve.

Saving, Restoring, and Resetting a Device Context

Windows supports three functions that an application can use to save, restore, and reset a device context: SaveDC, RestoreDC, and ResetDC. The SaveDC function records on a special GDI stack the current device context's graphic objects and their attributes, and graphic modes. A drawing application can call this function before a user begins drawing and save the application's original state--providing a "clean slate" for the user. To return to this original state, the application calls the RestoreDC function.

The ResetDC function is provided to reset printer device context data. An application calls this function to reset the paper orientation, paper size, output scaling factor, number of copies to be printed, paper source (or bin), duplex mode, and so on. Typically, an application calls this function after a user has changed one of the printer options and Windows has issued a WM_DEVMODECHANGE message.


Obtaining a Private Display Device Context

An application performing numerous drawing operations in the client area of its window must use a private display device context. To create this type of device context, the application must specify the CS_OWNDC constant for the style member of the WNDCLASS structure when registering the window class. After registering the window class, the application obtains a handle identifying a private display device context by calling the GetDC function.

The following example shows how to create a private display device context.

#include <windows.h>    /* required for all Windows-based applications */

#include <stdio.h>

#include <string.h>     /* strtok                                */

#include "dc.h"         /* specific to this program              */

/* Function prototypes */

BOOL InitApplication(HINSTANCE);

long FAR PASCAL MainWndProc(HWND, UINT, UINT, LONG);

/* Global variables */

HINSTANCE hinst;            /* handle of current instance        */

HDC hdc;                     /* display device context handle         */

    .

    .

    .

BOOL InitApplication(HINSTANCE hinstance)

{

    WNDCLASS  wc;

    /*

     * Fill in the window class structure with parameters describing

     * the main window.

     */

    wc.style = CS_OWNDC;                 /* Private-DC constant */

    wc.lpfnWndProc = (WNDPROC) MainWndProc;

    wc.cbClsExtra = 0;

    wc.cbWndExtra = 0;

    wc.hInstance = hinstance;

    wc.hIcon = LoadIcon((HINSTANCE) NULL,

        MAKEINTRESOURCE(IDI_APPLICATION));

    wc.hCursor = LoadCursor((HINSTANCE) NULL,

        MAKEINTRESOURCE(IDC_ARROW));

    wc.hbrBackground = GetStockObject(WHITE_BRUSH);

    wc.lpszMenuName =  "GenericMenu";

    wc.lpszClassName = "GenericWClass";

    /* Register the window class and return the resultant code. */

    return RegisterClass(&wc);

}

LRESULT APIENTRY MainWndProc(

        HWND hwnd,                /* window handle          */

        UINT message,             /* type of message        */

        WPARAM wParam,            /* additional information */

        LPARAM lParam)            /* additional information */

{

PAINTSTRUCT ps;             /* paint structure              */

    /* Retrieve a handle identifying the private display DC.*/

    hdc = GetDC(hwnd);

    switch (message) {

        case WM_PAINT:

              BeginPaint(hwnd, &ps);

        .

        . /* Perform drawing and painting using private DC. */

        .


Creating a Printer Device Context

An application can create a printer device context in one of two ways:

Calling the PrintDlg function to display a common dialog box that allows the user to specify printer options; then creating a printer device context by using those options.

Creating a printer device context by using the default printer data from the WIN.INI file.

This section contains code demonstrating the latter method.

To use the default printer, retrieve and parse the appropriate string from the WIN.INI file. This string is retrieved by calling the GetProfileString function and specifying the appropriate section and entry names. In the case of the default printer, this data is stored in the [windows] section and identified by the entry named device. The sixth line in the following excerpt from a WIN.INI file shows an entry for a Kodak® Diconix™ printer.

[windows]

    load=

    run=

    Beep=yes

    Spooler=yes

    NullPort=None

    device=Diconix,winspool,LPT1:

    CoolSwitch=1

    BorderWidth=3

    KeyboardSpeed=31

    InitialKeyboardIndicators=2

    CursorBlinkRate=530

    DoubleClickSpeed=686

    Programs=com exe bat pif cmd

    Documents=

    DeviceNotSelectedTimeout=15

    TransmissionRetryTimeout=45

    swapdisk=

    NetWarn=1

    fPromptOnVerbose=FALSE

    fPromptOnWarning=FALSE

    fPromptOnError=TRUE

    fPrintVerbose=FALSE

    fPrintFileLine=FALSE

    shell=

    ScreenSaveTimeOut=300

    ScreenSaveActive=0

    DebugOptions=2048

The following example shows how a printer device context was created by using the data from WIN.INI.

HDC hdcPrint;               /* printer device context handle        */

char szDevString[120];      /* array that receives WIN.INI data     */

char *szPrinter, *szDriver; /* pointers to printer and driver names */

char *szPort;               /* pointer to port name                 */

    .

    .

    .

    /*

     * Retrieve the printer, printer-driver, and

     * output-port names from WIN.INI.

     */

    GetProfileString("windows", "device", ",,,",

        szDevString, 120);

    /*

     * Parse the string of names, setting ptrs

     * as required. If the string contains the

     * required names, use them to create a

     * device context.

     */

    if ((szPrinter = strtok(szDevString,

               (const char *) ","))

            && (szDriver = strtok ((char *) NULL,

               (const char *) ", "))

            && (szPort = strtok ((char *) NULL,

               (const char *) ", ")))

        hdcPrint = CreateDC(szDriver, szPrinter,

            szPort, NULL);

    /*

     * Print a test page that contains the string

     * "PRINTER TEST" in the upper left corner.

     */

    Escape(hdcPrint, STARTDOC, 8, "Test-Doc", NULL);

    TextOut(hdcPrint, 50, 50, "PRINTER TEST", 12);

    Escape(hdcPrint, NEWFRAME, 0, NULL, NULL);

    Escape(hdcPrint, ENDDOC, 0, NULL, NULL);

    /* Delete the printer DC. */

     DeleteDC(hdcPrint);


Retrieving the Capabilities of a Printer

Not every output device supports the entire set of Win32 graphics functions. For example, because of hardware limitations, most vector plotters do not support bit-block transfers. An application can determine whether a device supports a particular Win32 graphics function by calling the GetDeviceCaps function, specifying the appropriate index, and examining the return value.

The following example shows how an application tests a printer to determine whether it supports bit-block transfers.

/*

 * Examine the raster capabilities of the device

 * identified by hdcPrint to verify that it supports

 * the BitBlt function.

 */

if ((GetDeviceCaps(hdcPrint, RASTERCAPS)

       & RC_BITBLT) == 0) {

    DeleteDC(hdcPrint);

    break;

}

else

 .

 . /* Print the bitmap using the printer DC. */

 .


Retrieving Graphic-Object Attributes and Selecting New Graphic Objects

An application can retrieve the attributes for a pen, brush, palette, font, or bitmap by calling the GetCurrentObject and GetObject functions. The GetCurrentObject function returns a handle identifying the object currently selected into the device context; the GetObject function returns a structure that describes the object's attributes.

The following example shows how an application can retrieve the current brush attributes and use the retrieved data to determine whether it is necessary to select a new brush.

HDC hdc;                     /* display device context handle         */

HBRUSH hbrushNew, hbrushOld; /* brush handles                         */

HBRUSH hbrush;               /* brush handle                          */

LOGBRUSH lb;                 /* logical-brush structure               */

    /*

     * Retrieve a handle identifying the current brush.

     */

    hbrush = GetCurrentObject(hdc, OBJ_BRUSH);

    /*

     * Retrieve a LOGBRUSH structure that contains the

     * current brush attributes.

     */

    GetObject(hbrush, sizeof(LOGBRUSH), &lb);

    /*

     * If the current brush is not a solid-black brush,

     * replace it with the solid-black stock brush.

     */

     if ((lb.lbStyle != BS_SOLID)

            || (lb.lbColor != 0x000000)) {

         hbrushNew = GetStockObject(BLACK_BRUSH);

         hbrushOld = SelectObject(hdc, hbrushNew);

     }

    .

    . /* Perform painting operations with the white brush. */

    .

    /*

     * After completing the last painting operation

     * with the new brush, the application should

     * select the original brush back into the

     * device context and delete the new brush.

     */

     SelectObject(hdc, hbrushOld);

     DeleteObject(hbrushNew);

Note that the application saved the original brush handle when calling the SelectObject function the first time. This handle is saved so that the original brush can be selected back into the device context after the last painting operation has been completed with the new brush. After the original brush is selected back into the device context, the new brush is deleted--freeing memory in the GDI heap.


Functions and Message

Following are the functions and the message used with device contexts.

Functions

CancelDC

CreateCompatibleDC

CreateDC

CreateIC

DeleteDC

DeleteObject

DeviceCapabilities

EnumObjects

EnumObjectsProc

GetCurrentObject

GetDC

GetDCEx

GetDCOrgEx

GetDeviceCaps

GetGraphicsMode

GetObject

GetObjectType

ReleaseDC

ResetDC

RestoreDC

SaveDC

SelectObject

SetGraphicsMode

Message

WM_DEVMODECHANGE


Bitmaps Overview

About Bitmaps

A bitmap is a powerful graphics object used to create, manipulate (scale, scroll, rotate, and paint), and store images as files on a disk.

A bitmap is one of seven objects that can be selected into a device context. The other six objects are the pen, brush, font, region, logical palette, and drawing surface. (For more information about device contexts and related objects, see Device Contexts.)

The following topics discuss Win32 bitmaps:

Terms

Bitmaps and Device Contexts

Two Types of Bitmaps

Bitmap Rotation

Bitmap Scaling

Bitmaps as Brushes

Bitmap Storage

Using a Bitmap to Capture an Image

Using a Bitmap to Scale an Image

Using a Bitmap to Store an Image

Functions

In Microsoft® Windows™, Control Panel is an example of an application that uses bitmaps. When a user selects wallpaper for the desktop, the user actually selects a bitmap, which Windows uses to paint the desktop background.

The following illustration shows a desktop painted with a red-brick wallpaper pattern:

Windows creates this pattern by repeatedly drawing a 32- by 32-pixel pattern on the desktop. This pattern is stored as a bitmap in the file REDBRICK.BMP.

From the user's point of view, a bitmap is a rectangle of pixels that form a visual image. However, from the developer's perspective, a bitmap is a collection of structures that specify or contain the following elements:

A header that describes the resolution of the device on which the rectangle of pixels was created, the dimensions of the rectangle, the size of the array of bits, and so on.

A logical palette.

An array of bits that define the relationship between pixels in the bitmapped image and entries in the logical palette.

The next illustration shows the developer's perspective of the bitmap found in the file REDBRICK.BMP. It shows a palette array, a 32- by 32-pixel rectangle, and the index array that maps colors from the palette to pixels in the rectangle.

In the preceding example, the rectangle of pixels was created on a VGA display device using a palette of 16 colors. A 16-color palette requires 4-bit indices; therefore, the array that maps palette colors to pixel colors is composed of 4-bit indices as well. (For more information about logical color-palettes, see Colors.)

It is important to note that Windows maps indices to pixels beginning with the bottom scan line of the rectangular region and ending with the top scan line. (A scan line is a single row of adjacent pixels on a video display.) In the preceding example, the first row of the array (row 0) corresponds to the bottom row of pixels, scan line 31.


Two Types of Bitmaps

Bitmap Types

There are two types of bitmaps: device-dependent (DDBs) and device-independent (DIBs). DDBs were common in early (pre-3.0) versions of Windows. In fact, they were the only bitmaps available to developers. However, as display technology improved and as the variety of display devices increased among Windows users, certain inherent problems surfaced. For example, there was no method of storing (or retrieving) the resolution of the display type on which a bitmap was created, so a drawing application could not quickly determine whether a bitmap was suitable for the type of video display device on which the application was running. To solve this problem, Microsoft created DIBs.

Device-Independent Bitmaps

A DIB contains the following color and dimension information:

The color format of the device on which the rectangular image was created.

The resolution of the device on which the rectangular image was created.

The palette for the device on which the image was created.

An array of bits that maps red, green, blue (RGB) triplets to pixels in the rectangular image.

A data-compression identifier that indicates the data compression scheme (if any) used to reduce the size of the array of bits.

This information is stored in a BITMAPINFO structure consisting of a BITMAPINFOHEADER structure followed by two or more RGBQUAD structures. The BITMAPINFOHEADER specifies the dimensions of the pixel rectangle, describes the device's color technology, and identifies the compression schemes used to reduce the bitmap's size. The RGBQUAD structures identify the colors that appear in the pixel rectangle.

The color format is specified in terms of a count of color planes and color bits. The count of color planes is always 1; the count of color bits is 1 for monochrome bitmaps, 4 for VGA bitmaps, and 8, 16, 24, or 32 for bitmaps on other color devices. An application retrieves the number of color bits a particular display (or printer) uses by calling the GetDeviceCaps function, specifying BITSPIXEL as the second argument.

The resolution of a display device is specified in pixels per meter. An application can retrieve the horizontal resolution for a video display, or printer, by following a three-step process:

1	Call the GetDeviceCaps function, specifying HORZRES as the second argument.

2	Call GetDeviceCaps a second time, specifying HORZSIZE as the second argument.

3	Divide the first return value by the second return value.

The application can retrieve the vertical resolution by using the same three-step process with different parameters: VERTRES in place of HORZRES, and VERTSIZE in place of HORZSIZE.

The palette is represented by an array of RGBQUAD structures that specify the red, green, and blue intensity components for each color in a display device's color palette. Each color index in the palette array maps to a specific pixel in the rectangular region associated with the bitmap. The size of this array, in bits, is equivalent to the width of the rectangle, in pixels, multiplied by the height of the rectangle, in pixels, multiplied by the count of color bits for the device. An application can retrieve the size of the device's palette by calling the GetDeviceCaps function, specifying the NUMCOLORS constant as the second argument.

Windows supports the compression of the palette array for 8-bit-per-pixel and 4-bit-per-pixel DIBs. These arrays can be compressed by using the run-length encoding (RLE) scheme. The RLE scheme uses 2-byte values, the first byte specifying the number of consecutive pixels that use a color index and the second byte specifying the index. For more information about bitmap compression, see the description of the BITMAPINFOHEADER structure.

An application can create a DIB by initializing the required structures and calling the CreateDIBitmap function. Then it can initialize the array of indices by calling the SetDIBits function. To determine whether a device supports this function, call the GetDeviceCaps function, specifying RC_DI_BITMAP as the RASTERCAPS flag.

An application can use a DIB to set pixels on the display device by calling the SetDIBitsToDevice or the BitBlt function. To determine whether a device supports the SetDIBitsToDevice function, call the GetDeviceCaps function, specifying RC_DIBTODEV as the RASTERCAPS flag.

An application that simply needs to display a preexisting DIB can use the SetDIBitsToDevice function. For example, a spreadsheet application can open existing charts and display them in a window by using the SetDIBitsToDevice function. To repeatedly redraw a bitmap in a window, however, the application should use the BitBlt function. For example, a multimedia application that combines animated graphics with sound would benefit from calling the BitBlt function because it executes faster than SetDIBitsToDevice.

Device-Dependent Bitmaps

Device-dependent bitmaps are supported only for compatibility with applications written for Windows versions earlier than 3.0. A developer writing a new application or porting an application written for a previous version of Windows to the Win32 platform should use DIBs.

DDBs are described by using a single structure, the BITMAP structure. The members of this structure specify the width and height of a rectangular region, in pixels; the width of the array that maps entries from the device palette to pixels; and the device's color format, in terms of color planes and bits per pixel. An application can retrieve the color format of a device by calling the GetDeviceCaps function and specifying the appropriate constants.

There are two types of DDBs: discardable and nondiscardable. A discardable DDB is a bitmap that Windows discards if the bitmap is not selected into a DC and if system memory is low. The CreateDiscardableBitmap function creates discardable bitmaps. The CreateBitmap, CreateCompatibleBitmap, and CreateBitmapIndirect functions create nondiscardable bitmaps.


Bitmaps and Device Contexts

Bitmaps, Device Contexts, and Drawing Surfaces

A device context (DC) is a data structure defining the graphics objects, their associated attributes, and the graphics modes affecting output on a device. An application creates a DC by calling the CreateDC function; it retrieves a window manager device context by calling the GetDC function.

The Drawing Surface

Before returning a handle that identifies that DC, the window manager selects a drawing surface into the DC. If the application called the CreateDC function to create a device context for a VGA display, the dimensions of this drawing surface are 640- by 480-pixels. If the application called the GetDC function, the dimensions reflect the size of the client area.

When an application passes the handle returned by CreateDC or GetDC to one of the graphics device interface (GDI) drawing functions, the requested output appears on the drawing surface selected into the device context.

Compatible Device Contexts

To enable applications to place output in memory rather than sending it to an actual device, Windows provides a special device context for bitmap operations called a compatible device context. A compatible DC enables Windows to treat a portion of memory as a virtual device. It is an array of bits in memory that an application can use to temporarily store the color data for bitmaps created on a normal drawing surface.

An application creates a compatible DC by calling the CreateCompatibleDC function and receives a handle that identifies a normal device context. Windows creates a temporary 1-bit placeholder for the array. Before performing drawing operations using the compatible DC handle, the application must increase the size of this array. To do this, the application can call the CreateBitmap, CreateBitmapIndirect, or CreateCompatibleBitmap function to create a bitmap of the appropriate dimensions and then call the SelectObject function to select the bitmap into the DC. After the bitmap is selected into the compatible DC, Windows replaces the single-bit array with an array large enough to store color information for the specified rectangle of pixels.

When an application passes the handle returned by CreateCompatibleDC to one of the GDI drawing functions, the requested output does not appear on a device's drawing surface. Instead, Windows stores the color information for the resultant line, curve, text or region in the array of bits. The application can copy the image stored in memory back onto a drawing surface by calling the BitBlt function, identifying the compatible DC as the source device context and a window or screen DC as the target device context.


Bitmap Rotation

Windows provides a function to copy a bitmap into a parallelogram; this function, PlgBlt, performs a bit-block transfer from a rectangle in a source device context into a parallelogram in a destination device context. In order to rotate the bitmap, an application must provide the coordinates, in world units, to be used for the corners of the parallelogram. (For more information about rotation and world units see Coordinate Spaces and Transformations.)


Bitmap Scaling

Windows also provides a function to scale a bitmap; this function, StretchBlt, performs a bit-block transfer from a rectangle in a source device context into a rectangle in a destination device context. However, unlike the BitBlt function, which duplicates the source rectangle dimensions in the destination rectangle, StretchBlt allows an application to specify the dimensions of both the source and the destination rectangles. When the destination bitmap is smaller than the source bitmap, Windows combines rows or columns of color data (or both) in the bitmap before rendering the corresponding image on the display device. Windows combines the color data according to the specified stretch mode, which the application defines by calling the SetStretchBltMode function. When the destination bitmap is larger than the source bitmap, Windows scales or magnifies each pixel in the resultant image accordingly.

The following illustration shows the client area of an application that captures the entire contents of the desktop and then stores the corresponding color data in a bitmap. The window on the left displays the original bitmap; the window on the right displays the bitmap after it was scaled to twice its original size.


Bitmaps as Brushes

Windows provides a number of functions that use the brush currently selected into a device context to perform bitmap operations. For example, the PatBlt function replicates the brush in a rectangular region within a window, and the FloodFill function replicates the brush inside an area in a window bounded by the specified color (unlike PatBlt, FloodFill does fill nonrectangular shapes).

The PatBlt function name (an abbreviation for pattern block transfer) implies that the function simply replicates the brush (or pattern) until it fills a specified rectangle. However, the function is actually much more powerful. Before replicating the brush, it combines the color data for the pattern with the color data for the existing pixels on the video display by using a raster operation (ROP). An ROP is a bitwise operation that is applied to the bits of color data for the replicated brush and the bits of color data for the target rectangle on the display device. There are 256 ROPs in Windows; however, the PatBlt function recognizes only those that require a pattern and a destination (not those that require a source). The following table identifies the five most common ROPs.

ROP	Description

PATCOPY	Copies the pattern to the destination bitmap.

PATINVERT	Combines the destination bitmap with the pattern by using the Boolean OR operator.

DSTINVERT	Inverts the destination bitmap.

BLACKNESS	Turns all output to binary zeroes.

WHITENESS	Turns all output to binary ones.

The FloodFill function replicates the brush within a region bounded by a specified color. However, unlike the PatBlt function, FloodFill does not combine the color data for the brush with the color data for the pixels on the display; it simply sets the color of all pixels within the enclosed region on the display to the color of the brush that is currently selected into the device context.

The following illustration shows the result of calling the FloodFill function in the Windows Paintbrush application to paint the interior of a nonrectangular region. The window on the left shows the region before FloodFill was called; the window on the right shows the region after the call was made.


Bitmap Storage

Bitmaps should be saved in a file that uses the established Windows format and assigned a name with the three-character .BMP extension. The Windows format is shown in the following illustration.

The members of the BITMAPFILEHEADER structure identify the file; specify the size of the file, in bytes; and specify the offset from the first byte in the header to the first byte of bitmap data. The members of the BITMAPINFOHEADER structure specify the bitmap's width and height, in pixels; the color format (count of color planes and color bits per pixel) of the display device on which the bitmap was created; whether the bitmap data was compressed before storage and the type of compression used; the number of bytes of bitmap data; the resolution of the display device on which the bitmap was created; and the number of colors represented in the data. The RGBQUAD structures specify the RGB intensity values for each of the colors in the device's palette. The color-index array maps indices values from the RGBQUAD array to pixels in a rectangular region on the display.

The following hexadecimal output shows the contents of the file REDBRICK.BMP.

0000    42 4d 76 02 00 00 00 00  00 00 76 00 00 00 28 00

0010    00 00 20 00 00 00 20 00  00 00 01 00 04 00 00 00

0020    00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00

0030    00 00 00 00 00 00 00 00  00 00 00 00 80 00 00 80

0040    00 00 00 80 80 00 80 00  00 00 80 00 80 00 80 80

0050    00 00 80 80 80 00 c0 c0  c0 00 00 00 ff 00 00 ff

0060    00 00 00 ff ff 00 ff 00  00 00 ff 00 ff 00 ff ff

0070    00 00 ff ff ff 00 00 00  00 00 00 00 00 00 00 00

0080    00 00 00 00 00 00 00 00  00 00 00 00 00 00 09 00

0090    00 00 00 00 00 00 11 11  01 19 11 01 10 10 09 09

00a0    01 09 11 11 01 90 11 01  19 09 09 91 11 10 09 11

00b0    09 11 19 10 90 11 19 01  19 19 10 10 11 10 09 01

00c0    91 10 91 09 10 10 90 99  11 11 11 11 19 00 09 01

00d0    91 01 01 19 00 99 11 10  11 91 99 11 09 90 09 91

00e0    01 11 11 11 91 10 09 19  01 00 11 90 91 10 09 01

00f0    11 99 10 01 11 11 91 11  11 19 10 11 99 10 09 10

0100    01 11 11 11 19 10 11 09  09 10 19 10 10 10 09 01

0110    11 19 00 01 10 19 10 11  11 01 99 01 11 90 09 19

0120    11 91 11 91 01 11 19 10  99 00 01 19 09 10 09 19

0130    10 91 11 01 11 11 91 01  91 19 11 00 99 90 09 01

0140    01 99 19 01 91 10 19 91  91 09 11 99 11 10 09 91

0150    11 10 11 91 99 10 90 11  01 11 11 19 11 90 09 11

0160    00 19 10 11 01 11 99 99  99 99 99 99 99 99 09 99

0170    99 99 99 99 99 99 00 00  00 00 00 00 00 00 00 00

0180    00 00 00 00 00 00 90 00  00 00 00 00 00 00 00 00

0190    00 00 00 00 00 00 99 11  11 11 19 10 19 19 11 09

01a0    10 90 91 90 91 00 91 19  19 09 01 10 09 01 11 11

01b0    91 11 11 11 10 00 91 11  01 19 10 11 10 01 01 11

01c0    90 11 11 11 91 00 99 09  19 10 11 90 09 90 91 01

01d0    19 09 91 11 01 00 90 10  19 11 00 11 11 00 10 11

01e0    01 10 11 19 11 00 90 19  10 91 01 90 19 99 00 11

01f0    91 01 11 01 91 00 99 09  09 01 10 11 91 01 10 91

0200    99 11 10 90 91 00 91 11  00 10 11 01 10 19 19 09

0210    10 00 99 01 01 00 91 01  19 91 19 91 11 09 10 11

0220    00 91 00 10 90 00 99 01  11 10 09 10 10 19 09 01

0230    91 90 11 09 11 00 90 99  11 11 11 90 19 01 19 01

0240    91 01 01 19 09 00 91 10  11 91 99 09 09 90 11 91

0250    01 19 11 11 91 00 91 19  01 00 11 00 91 10 11 01

0260    11 11 10 01 11 00 99 99  99 99 99 99 99 99 99 99

0270    99 99 99 99 99 90

The following table shows the data bytes associated with the structures in a bitmap file.

Structure	Corresponding bytes

BITMAPFILEHEADER	0x00 - 0x0D

BITMAPINFOHEADER	0x0E - 0x31

RGBQUAD array	0x32 - 0x75

Color-index array	0x76 - 0x275


Using a Bitmap to Capture an Image

Capturing an Image

You can use a bitmap to capture an image, and you can store the captured image in memory, display it at a different location in your application's window, or display it in another window.

In some cases, you may want your application to capture images and store them only temporarily. For example, when you scale or "zoom" a picture created in a drawing application, the application must temporarily save the normal view of the image and display the zoomed view. Later, when the user selects the normal view, the application must replace the zoomed image with a copy of the normal view that it temporarily saved.

If your application must store an image temporarily, you must create a DC that is compatible with the current window DC. You do this by calling the CreateCompatibleDC function. After you create a compatible DC, you create a bitmap with the appropriate dimensions by calling the CreateCompatibleBitmap function and then select it into this device context by calling the SelectObject function.

After the compatible device context is created and the appropriate bitmap has been selected into it, you can capture the image. Windows provides the BitBlt function to capture images. This function performs a bit block transfer--that is, it copies data from a source bitmap into a destination bitmap. Because it copies data from bitmaps, you'd expect that two arguments to this function would be bitmap handles; however, this is not the case. Instead, the BitBlt function receives handles that identify two device contexts and copies the bitmap data from a bitmap selected into the source DC into a bitmap selected into the target DC. In this case, the target DC is the compatible DC, so when the BitBlt function completes the transfer, the image has been stored in memory. To redisplay the image, call the BitBlt function a second time, specifying the compatible device context as the source DC and a window (or printer) device context as the target DC.

The following example code, from an application that captures an image of the entire desktop, creates a compatible device context and a bitmap with the appropriate dimensions, selects the bitmap into the compatible DC, and then copies the image using the BitBlt function.

/*

 * Create a normal DC and a memory DC for the entire screen. The

 * normal DC provides a "snapshot" of the screen contents. The

 * memory DC keeps a copy of this "snapshot" in the associated

 * bitmap.

 */

hdcScreen = CreateDC("DISPLAY", NULL, NULL, NULL);

hdcCompatible = CreateCompatibleDC(hdcScreen);

/* Create a compatible bitmap for hdcScreen. */

hbmScreen = CreateCompatibleBitmap(hdcScreen,

                     GetDeviceCaps(hdcScreen, HORZRES),

                     GetDeviceCaps(hdcScreen, VERTRES));

if (hbmScreen == 0)

    errhandler("hbmScreen", hwnd);

/* Select the bitmaps into the compatible DC. */

if (!SelectObject(hdcCompatible, hbmScreen))

    errhandler("Compatible Bitmap Selection", hwnd);

        /* Hide the application window. */

        ShowWindow(hwnd, SW_HIDE);

        /*

         * Copy color data for the entire display into a

         * bitmap that is selected into a compatible DC.

         */

        if (!BitBlt(hdcCompatible,

               0,0,

               bmp.bmWidth, bmp.bmHeight,

               hdcScreen,

               0,0,

               SRCCOPY))

        errhandler("Screen to Compat Blt Failed", hwnd);

        /* Redraw the application window. */

        ShowWindow(hwnd, SW_SHOW);


Using a Bitmap to Scale an Image

Scaling an Image

Some applications scale images--that is, they display zoomed or reduced views of an image. For example, a drawing application may provide a zoom feature that enables the user to view and edit a drawing on a pixel-by-pixel basis.

Applications scale images by calling the StretchBlt function. Like the BitBlt function, StretchBlt copies bitmap data from a bitmap in a source DC into a bitmap in a target DC. However, unlike the BitBlt function, StretchBlt scales the image based on the specified dimensions of the source and target rectangles. If the source rectangle is larger than the target rectangle, the resultant image will appear to have shrunk; if the source rectangle is smaller than the target rectangle, the resultant image will appear to have expanded.

If the target rectangle is smaller than the source rectangle, StretchBlt removes color data from the image according to a specified stretch mode as shown in the following table.

Stretch Mode	Method

BLACKONWHITE	Performs a logical AND operation on the color data for the eliminated pixels and the color data for the remaining pixels.

WHITEONBLACK	Performs a logical OR operation on the color data for the eliminated pixels and the color data for the remaining pixels.

COLORONCOLOR	Eliminates the color data of the deleted pixels completely.

HALFTONE	Approximates the original (source) color data in the destination.

You set the stretch-mode by calling the SetStretchBltMode function.

The following example code is taken from an application that displays an image either at its original size or a twice the original size. (This application uses the default stretch mode.).

    hdcScaled = CreateCompatibleDC(hdcScreen);

    hbmScaled = CreateCompatibleBitmap(hdcScreen,

                    GetDeviceCaps(hdcScreen, HORZRES) * 2,

                    GetDeviceCaps(hdcScreen, VERTRES) * 2);

    if (hbmScaled == 0)

        errhandler("hbmScaled", hwnd);

    /* Select the bitmaps into the compatible DC. */

    if (!SelectObject(hdcScaled, hbmScaled))

        errhandler("Scaled Bitmap Selection", hwnd);

case WM_COMMAND: /* message: command from application menu */

    switch(wParam) {

        case IDM_SCALEX1:

            if (fBlt){

                 fScaled = FALSE;

                 hdcWin = GetDC(hwnd);

                 BitBlt(hdcWin,

                    0,0,

                    bmp.bmWidth, bmp.bmHeight,

                    hdcCompatible,

                    0,0,

                    SRCCOPY);

                 ReleaseDC(hwnd, hdcWin);

            }

            break;

        case IDM_SCALEX2:

            if (fBlt){

                 fScaled = TRUE;

                 StretchBlt(hdcScaled,

                     0, 0,

                     bmp.bmWidth * 2, bmp.bmHeight * 2,

                     hdcCompatible,

                     0, 0,

                     bmp.bmWidth, bmp.bmHeight,

                     SRCCOPY);

                 hdcWin = GetDC(hwnd);

                 BitBlt(hdcWin,

                    0,0,

                    bmp.bmWidth, bmp.bmHeight,

                    hdcScaled,

                    0,0,

                    SRCCOPY);

                 ReleaseDC(hwnd, hdcWin);

            }

            break;


Using a Bitmap to Store an Image

Storing an Image

Many applications store images permanently as files. For example, drawing applications store pictures, spreadsheet applications store charts, CAD applications store drawings, and so on.

If you are writing an application that will store a bitmapped image in a file, you should use the Windows file format described in Bitmap Storage. In order to store a bitmap in this format, you must initialize a BITMAPINFO structure (consisting of a BITMAPFILEHEADER structure and an array of RGBQUAD structures), as well as an array of palette indices.

The following example code defines a function that allocates memory for and initializes members within a BITMAPINFOHEADER data structure.

PBITMAPINFO CreateBitmapInfoStruct(HWND hwnd, HBITMAP hBmp) {

    BITMAP bmp;

    PBITMAPINFO pbmi;

    WORD    cClrBits;

    /* Retrieve the bitmap's color format, width, and height. */

    if (!GetObject(hBmp, sizeof(BITMAP), (LPSTR)&bmp))

        errhandler("GetObject", hwnd);

    /* Convert the color format to a count of bits. */

    cClrBits = (WORD)(bmp.bmPlanes * bmp.bmBitsPixel);

    if (cClrBits == 1)

        cClrBits = 1;

    else if (cClrBits <= 4)

        cClrBits = 4;

    else if (cClrBits <= 8)

        cClrBits = 8;

    else if (cClrBits <= 16)

        cClrBits = 16;

    else if (cClrBits <= 24)

        cClrBits = 24;

    else

        cClrBits = 32;

    /*

     * Allocate memory for the BITMAPINFO structure. (This structure

     * contains a BITMAPINFOHEADER structure and an array of RGBQUAD data

     * structures.)

     */

    if (cClrBits != 24)

         pbmi = (PBITMAPINFO) LocalAlloc(LPTR,

                    sizeof(BITMAPINFOHEADER) +

                    sizeof(RGBQUAD) * cClrBits);

    /*

     * There is no RGBQUAD array for the 24-bit-per-pixel format.

     */

    else

         pbmi = (PBITMAPINFO) LocalAlloc(LPTR,

                    sizeof(BITMAPINFOHEADER));

    /* Initialize the fields in the BITMAPINFO structure. */

    pbmi->bmiHeader.biSize = sizeof(BITMAPINFOHEADER);

    pbmi->bmiHeader.biWidth = bmp.bmWidth;

    pbmi->bmiHeader.biHeight = bmp.bmHeight;

    pbmi->bmiHeader.biPlanes = bmp.bmPlanes;

    pbmi->bmiHeader.biBitCount = bmp.bmBitsPixel;

    /* If the bitmap is not compressed, set the BI_RGB flag. */

    pbmi->bmiHeader.biCompression = BI_RGB;

    /*

     * Compute the number of bytes in the array of color

     * indices and store the result in biSizeImage.

     */

    pbmi->bmiHeader.biSizeImage = (pbmi->bmiHeader.biWidth + 7) /8

                                  * pbmi->bmiHeader.biHeight

                                  * cClrBits;

    /*

     * Set biClrImportant to 0, indicating that all of the

     * device colors are important.

     */

    pbmi->bmiHeader.biClrImportant = 0;

    return pbmi;

}

The following example code defines a function that initializes the remaining structures, retrieves the array of palette indices, opens the file, copies the data, and closes the file.

void CreateBMPFile(HWND hwnd, LPTSTR pszFile, PBITMAPINFO pbi,

                  HBITMAP hBMP, HDC hDC)

 {

    HANDLE hf;                  /* file handle */

    BITMAPFILEHEADER hdr;       /* bitmap file-header */

    PBITMAPINFOHEADER pbih;     /* bitmap info-header */

    HANDLE hmem;                /* memory handle */

    LPBYTE lpBits;              /* memory pointer */

    DWORD dwTotal;              /* total count of bytes */

    DWORD cb;                   /* incremental count of bytes */

    BYTE *hp;                   /* byte pointer */

    DWORD dwTmp;

    pbih = (PBITMAPINFOHEADER) pbi;

    lpBits = (LPBYTE) GlobalAlloc(GMEM_FIXED, pbih->biSizeImage);

    if (!lpBits)

         errhandler("GlobalAlloc", hwnd);

    /*

     * Retrieve the color table (RGBQUAD array) and the bits

     * (array of palette indices) from the DIB.

     */

    if (!GetDIBits(hDC, hBMP, 0, (WORD) pbih->biHeight,

                   lpBits, pbi, DIB_RGB_COLORS))

        errhandler("GetDIBits", hwnd);

    /* Create the .BMP file. */

    hf = CreateFile(pszFile,

                   GENERIC_READ | GENERIC_WRITE,

                   (DWORD) 0,

                   (LPSECURITY_ATTRIBUTES) NULL,

                   CREATE_ALWAYS,

                   FILE_ATTRIBUTE_NORMAL,

                   (HANDLE) NULL);

    if (hf == INVALID_HANDLE_VALUE)

        errhandler("CreateFile", hwnd);

    hdr.bfType = 0x4d42;        /* 0x42 = "B" 0x4d = "M" */

    /* Compute the size of the entire file. */

    hdr.bfSize = (DWORD) (sizeof(BITMAPFILEHEADER) +

                 pbih->biSize + pbih->biClrImportant

                 * sizeof(RGBQUAD) + pbih->biSizeImage);

    hdr.bfReserved1 = 0;

    hdr.bfReserved2 = 0;

    /* Compute the offset to the array of color indices. */

    hdr.bfOffBits = (DWORD) sizeof(BITMAPFILEHEADER) +

                    pbih->biSize + pbih->biClrImportant

                    * sizeof (RGBQUAD);

    /* Copy the BITMAPFILEHEADER into the .BMP file. */

    if (!WriteFile(hf, (LPVOID) &hdr, sizeof(BITMAPFILEHEADER),

       (LPDWORD) &dwTmp, (LPOVERLAPPED) NULL))

       errhandler("WriteFile", hwnd);

    /* Copy the BITMAPINFOHEADER and RGBQUAD array into the file. */

    if (!WriteFile(hf, (LPVOID) pbih, sizeof(BITMAPINFOHEADER)

                  + pbih->biClrImportant * sizeof (RGBQUAD),

                  (LPDWORD) &dwTmp, (LPOVERLAPPED) NULL))

       errhandler("WriteFile", hwnd);

    /* Copy the array of color indices into the .BMP file. */

    dwTotal = cb = pbih->biSizeImage;

    hp = lpBits;

    while (cb > MAXWRITE)  {

            if (!WriteFile(hf, (LPSTR) hp, (int) MAXWRITE,

                          (LPDWORD) &dwTmp, (LPOVERLAPPED) NULL))

                errhandler("WriteFile", hwnd);

            cb-= MAXWRITE;

            hp += MAXWRITE;

    }

    if (!WriteFile(hf, (LPSTR) hp, (int) cb,

         (LPDWORD) &dwTmp, (LPOVERLAPPED) NULL))

           errhandler("WriteFile", hwnd);

    /* Close the .BMP file. */

    if (!CloseHandle(hf))

           errhandler("CloseHandle", hwnd);

    /* Unlock and free memory. */

    GlobalUnlock(hmem);

    GlobalFree(hmem);

}


Functions

Following are the functions used with bitmaps.

BitBlt

CreateBitmap

CreateBitmapIndirect

CreateCompatibleBitmap

CreateDiscardableBitmap

CreateDIBitmap

CreateDIBSection

ExtFloodFill

FloodFill

GetBitmapBits

GetBitmapDimensionEx

GetDIBits

GetPixel

GetStretchBltMode

LoadBitmap

MaskBlt

PatBlt

PlgBlt

SetBitmapBits

SetBitmapDimensionEx

SetDIBits

SetDIBitsToDevice

SetPixel

SetPixelV

StretchBlt

StretchDIBits

SetStretchBltMode


Brushes Overview

About Brushes

A brush is a graphics tool that an application written for Microsoft® Windows™ uses to paint the interior of polygons, ellipses, and paths. Drawing applications use brushes to paint shapes; word processing applications use brushes to paint rules; computer-aided design (CAD) applications use brushes to paint the interiors of cross-section views; and spreadsheet applications use brushes to paint the sections of pie charts and the bars in bar graphs.

There are two types of brushes: logical and physical. A logical brush is a description of the ideal bitmap that an application would use to paint shapes. A physical brush is the actual bitmap that a device driver creates based on an application's logical-brush definition.

When an application calls one of the functions that create a brush, it retrieves a handle that identifies a logical brush. When the application passes this handle to the SelectObject function, the device driver for the corresponding display or printer creates the physical brush.

The following topics discuss brushes:

Terms

Brush Origin

Logical Brush Types

Using Brushes

Functions


Brush Origin

When an application calls a drawing function to paint a shape, Windows positions a brush at the start of the paint operation and maps a pixel in the brush bitmap to the window origin of the client area. (The window origin is the upper-left corner of the  window's client area.) The coordinates of the pixel that Windows maps are called the brush origin. The default brush origin is located in the upper-left corner of the brush bitmap, at the coordinates (0,0). Windows then copies the brush across the client area, forming a pattern that is as tall as the bitmap. The copy operation continues, row by row, until the entire client area is filled. However, the brush pattern is visible only within the boundaries of the specified shape.

There are instances when the default brush origin should not be used. For example, it may be necessary for an application to use the same brush to paint the backgrounds of its parent and child windows and blend a child window's background with that of the parent window. To do this, the application should reset the brush origin by calling the SetBrushOrgEx function and shifting the origin the required number of pixels. (An application can retrieve the current brush origin by calling the GetBrushOrgEx function.)

The following illustration shows a five-pointed star filled by using an application-defined brush. The illustration shows a zoomed image of the brush, as well as the location to which it was mapped at the beginning of the paint operation.


Logical Brush Types

There are four types of logical brushes (solid, stock, hatch, and pattern) as shown in the following illustration.

The stock and hatch types each have several predefined brushes, as described in Hatch Brush.

Solid Brush

A solid brush is a logical brush that contains 64 pixels of the same color. An application can create a solid logical brush by calling the CreateSolidBrush function, specifying the color of the brush required. After creating the solid brush, the application can select it into its device context and use it to paint filled shapes.

Stock Brush

There are seven predefined logical stock brushes maintained by the graphics device interface (GDI). The following rectangles were painted by using the seven predefined stock brushes.

An application can retrieve a handle identifying one of the seven stock brushes by calling the GetStockObject function, specifying the brush type.

Hatch Brush

There are six predefined logical hatch brushes maintained by GDI. The following rectangles were painted by using the six predefined hatch brushes.

An application can create a hatch brush by calling the CreateHatchBrush function, specifying one of the six hatch styles.

Pattern Brush

A pattern (or custom) brush is created from an application-defined bitmap or device-independent bitmap (DIB). The following rectangles were painted by using different pattern brushes.

To create a logical pattern brush, an application must first create a bitmap. After creating the bitmap, the application can create the logical pattern brush by calling the CreatePatternBrush or CreateDIBPatternBrush function, supplying a handle that identifies the bitmap (or DIB). The brushes that appear in the preceding illustration were created from monochrome bitmaps.


Using Brushes

You can use a brush to paint the interior of virtually any shape by using a GDI function. This includes the interiors of rectangles, ellipses, polygons, and paths. Depending on the requirements of your application, you can use a solid brush of a specified color, a stock brush, a hatch brush, or a pattern brush.

This section contains code samples that demonstrate the creation of a custom brush dialog box. The dialog box contains a grid that represents the bitmap Windows uses as a brush. A user can use this grid to create a pattern-brush bitmap and then view the custom pattern by clicking the Test Pattern button.

The following illustration shows a pattern created by using the Custom Brush dialog box.

To display a dialog box, you must first create a dialog box template. The following dialog box template defines the Custom Brush dialog box.

CustBrush DIALOG 6, 18, 160, 118

STYLE WS_DLGFRAME | WS_POPUP | WS_VISIBLE | WS_CAPTION

CAPTION "Custom Brush"

FONT 8, "MS Sans Serif"

BEGIN

    CONTROL         "", IDD_GRID, "Static", SS_BLACKFRAME |

                    WS_CHILD, 3, 2, 83, 79

    CONTROL         "", IDD_RECT, "Static", SS_BLACKFRAME |

                    WS_CHILD, 96, 11, 57, 28

    PUSHBUTTON      "Test Pattern", IDD_PAINTRECT, 96, 47, 57, 14

    PUSHBUTTON      "OK", IDD_OK, 29, 98, 40, 14

    PUSHBUTTON      "Cancel", IDD_CANCEL, 92, 98, 40, 14

END

The Custom Brush dialog box contains five controls: a bitmap-grid window, a pattern-viewing window, and three push buttons, labeled Test Pattern, OK and Cancel. The Test Pattern push button enables the user to view the pattern. The dialog box template specifies the overall dimensions of the dialog box window, assigns a value to each control, specifies the location of each control, and so forth.

The control values in the dialog box template are constants that have been defined as follows in the application's header file.

#define IDD_GRID  120

#define IDD_RECT  121

#define IDD_PAINTRECT 122

#define IDD_OK  123

#define IDD_CANCEL 124

After you create a dialog box template and include it in the application's resource-definition file, you must write a dialog procedure. This procedure processes messages that Windows sends to the dialog box. The following excerpt from an application's source code shows the dialog box procedure for the Custom Brush dialog box and the two application-defined functions it calls.

int APIENTRY BrushDlgProc(HWND hdlg, WORD message, LONG wParam,

                         LONG lParam)

{

    static HWND hwndGrid;       /* grid-window control     */

    static HWND hwndBrush;      /* pattern-brush control   */

    static RECT rctGrid;        /* grid-window rectangle   */

    static RECT rctBrush;       /* pattern-brush rectangle */

    static UINT bBrushBits[8];  /* bitmap bits             */

    static RECT rect[64];       /* grid-cell array         */

    static HBITMAP hbm;         /* bitmap handle           */

    HBRUSH hbrush;              /* current brush           */

    HBRUSH hbrushOld;           /* default brush           */

    HRGN hrgnCell;              /* test-region handle      */

    HDC hdc;                    /* DC handle               */

    int x, y, deltaX, deltaY;   /* drawing coordinates     */

    POINTS ptlHit;              /* mouse coordinates       */

    int i;                      /* count variable          */

    switch (message)

        {

        case WM_INITDIALOG:

            /*

             * Retrieve a window handle for the grid-window and

             * pattern-brush controls

             */

            hwndGrid = GetDlgItem(hdlg, IDD_GRID);

            hwndBrush = GetDlgItem(hdlg, IDD_RECT);

            /* Initialize the array of bits that define the

             * custom brush pattern with the value 1 to produce a

             * solid white brush).

             */

            for (i=0; i<8; i++)

                bBrushBits[i] = 0xFF;

            /*

             * Retrieve dimensions for the grid-window and pattern-brush

             * controls.

             */

            GetClientRect(hwndGrid, &rctGrid);

            GetClientRect(hwndBrush, &rctBrush);

            /* Determine the width and height of a single cell. */

            deltaX = (rctGrid.right - rctGrid.left)/8;

            deltaY = (rctGrid.bottom - rctGrid.top)/8;

            /* Initialize the array of cell rectangles. */

            for (y=rctGrid.top, i=0; y < rctGrid.bottom; y += deltaY){

                for (x=rctGrid.left; x < (rctGrid.right - 8) && i < 64;

                        x += deltaX, i++) {

                    rect[i].left = x; rect[i].top = y;

                    rect[i].right = x + deltaX;

                    rect[i].bottom = y + deltaY;

                }

            }

            return FALSE;

        case WM_PAINT:

            /* Draw the grid. */

            hdc = GetDC(hwndGrid);

            for (i=rctGrid.left; i<rctGrid.right;

                 i+=(rctGrid.right - rctGrid.left)/8){

                 MoveToEx(hdc, i, rctGrid.top, NULL);

                 LineTo(hdc, i, rctGrid.bottom);

            }

            for (i=rctGrid.top; i<rctGrid.bottom;

                 i+=(rctGrid.bottom - rctGrid.top)/8){

                 MoveToEx(hdc, rctGrid.left, i, NULL);

                 LineTo(hdc, rctGrid.right, i);

            }

            ReleaseDC(hwndGrid, hdc);

            return FALSE;

        case WM_LBUTTONDOWN:

            /* Store the mouse coordinates in a POINT structure. */

            ptlHit = MAKEPOINTS((POINTS FAR *)lParam);

            /*

             * Create a rectangular region with dimensions and

             * coordinates that correspond to those of the grid

             * window.

             */

            hrgnCell = CreateRectRgn(rctGrid.left, rctGrid.top,

                        rctGrid.right, rctGrid.bottom);

            /* Retrieve a window DC for the grid window. */

            hdc = GetDC(hwndGrid);

            /* Select the region into the DC. */

            SelectObject(hdc, hrgnCell);

            /* Test for a button click in the grid-window rectangle. */

            if (PtInRegion(hrgnCell, ptlHit.x, ptlHit.y)){

                /*

                 * A button click occurred in the grid-window rectangle;

                 * isolate the cell in which it occurred.

                 */

                for(i=0; i<64; i++){

                    DeleteObject(hrgnCell);

                    hrgnCell = CreateRectRgn(rect[i].left, rect[i].top,

                               rect[i].right, rect[i].bottom);

                    if (PtInRegion(hrgnCell, ptlHit.x, ptlHit.y)){

                         InvertRgn(hdc, hrgnCell);

                         /* Set the appropriate brush bits. */

                         if (i % 8 == 0)

                            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x80;

                         else if (i % 8 == 1)

                            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x40;

                         else if (i % 8 == 2)

                            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x20;

                         else if (i % 8 == 3)

                            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x10;

                         else if (i % 8 == 4)

                            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x08;

                         else if (i % 8 == 5)

                            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x04;

                         else if (i % 8 == 6)

                            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x02;

                         else if (i % 8 == 7)

                            bBrushBits[i/8] = bBrushBits[i/8] ^ 0x01;

                      /* Exit the "for" loop after the bit is set. */

                         break;

                    } /* end if */

                } /* end for */

            } /* end if */

            /* Release the DC for the control. */

            ReleaseDC(hwndGrid, hdc);

            return TRUE;

        case WM_COMMAND:

            switch (wParam){

               case IDD_PAINTRECT:

                    hdc = GetDC(hwndBrush);

                    /* Create a monochrome bitmap. */

                    hbm = CreateBitmap(8, 8, 1, 1,

                          (LPBYTE)bBrushBits);

                    /* Select the custom brush into the DC. */

                    hbrush = CreatePatternBrush(hbm);

                    hbrushOld = SelectObject(hdc, hbrush);

                    /* Use the custom brush to fill the rectangle. */

                    Rectangle(hdc, rctBrush.left, rctBrush.top,

                              rctBrush.right, rctBrush.bottom);

                    /* Clean up memory. */

                    SelectObject(hdc, hbrushOld);

                    DeleteObject(hbrush);

                    DeleteObject(hbm);

                    ReleaseDC(hwndBrush, hdc);

                  return TRUE;

                case IDD_OK:

                case IDD_CANCEL:

                    EndDialog(hdlg, TRUE);

                    return TRUE;

            } /* end switch */

            break;

        default:

            return FALSE;

        }

}

int GetStrLngth(LPTSTR cArray)

{

    int i = 0;

    while (cArray[i++] != 0);

    return i-1;

}

DWORD RetrieveWidth(LPTSTR cArray, int iLength)

{

    int i, iTmp;

    double dVal, dCount;

    dVal = 0.0;

    dCount = (double)(iLength-1);

    for (i=0; i<iLength; i++){

        iTmp = cArray[i] - 0x30;

        dVal = dVal + (((double)iTmp) * pow(10.0, dCount--));

    }

    return (DWORD)dVal;

}

The dialog box procedure for the Custom Brush dialog box processes four messages, as described in the following table.

Message	Action

WM_INITDIALOG	Retrieves a window handle and dimensions for the grid-window and pattern-brush controls, computes the dimensions of a single cell in the grid-window control, and initializes an array of grid-cell coordinates.

WM_PAINT	Draws the grid pattern in the grid-window control.

WM_LBUTTONDOWN	Determines whether the cursor is within the grid-window control when the user presses the left mouse button. If so, the dialog box procedure inverts the appropriate grid cell and records the state of that cell in an array of bits that is used to create the bitmap for the custom brush.

WM_COMMAND	Processes input for the three push button controls. If the user presses the Test Pattern button, the dialog box procedure paints the Test Pattern control with the new custom brush pattern. If the user presses the OK or Cancel button, the dialog box procedure performs actions accordingly.

After you write the dialog box procedure, export it in the module-definition file, include the function definition for the procedure in the application's header file, and then call the dialog box procedure at the appropriate point in the application.

The following excerpt from the module-definition file shows how the dialog box procedure for the Custom Brush is exported.

; Export all functions that are called by a Windows routine.

EXPORTS

        MainWndProc   @1   ; name of window processing function

        BrushDlgProc  @2   ; name of custom-brush processing function

The following excerpt from the application's header file shows the function definition for the dialog box procedure and the two functions it calls.

int APIENTRY BrushDlgProc(HWND hdlg, WORD message, LONG wParam,

             LONG lParam);

int GetStrLngth(LPTSTR cArray);

DWORD RetrieveWidth(LPTSTR cArray, int iLength);

Finally, the following code shows how the dialog box procedure is called from the application's source-code file. In this example, the dialog box procedure is called when the user chooses an option from the application's menu.

switch (message) {

    case WM_CREATE:

        break;

    case WM_COMMAND: /* message: command from application menu */

        switch(wParam) {

            case IDM_CUSTOMBRUSH:

                    DialogBox((HANDLE)GetModuleHandle(NULL),

                    (LPTSTR)"CustBrush", hWnd,

                    (DLGPROC)BrushDlgProc);

                break;


Functions

Following are the functions that can be used with brushes.

CreateBrushIndirect

CreateDIBPatternBrush

CreateDIBPatternBrushPt

CreateHatchBrush

CreatePatternBrush

CreateSolidBrush

GetBrushOrgEx

GetStockObject

SetBrushOrgEx


Pens Overview

About Pens

A pen is a graphics tools that an application for Microsoft® Windows™ uses to draw lines and curves. Drawing applications use pens to draw freehand lines, straight lines, and curves. Computer-aided design (CAD) applications use pens to draw visible lines, hidden lines, section lines, center lines, and so on. Word processing and desktop publishing applications use pens to draw borders and rules. Spreadsheet applications use pens to designate trends in graphs and to outline bar graphs and pie charts.

There are two types of pens: cosmetic and geometric. A cosmetic pen is used with applications requiring lines of fixed width and lines that are quickly drawn. A CAD application, for example, uses a cosmetic pen to generate hidden, section, center, and dimension lines that are between .015 and .022 inches wide--regardless of the scale factor. A geometric pen is used with applications requiring scalable lines, lines with unique end or join styles, and lines that are wider than a single pixel. A spreadsheet application, for example, uses a geometric pen to define each of the bars in a bar graph as a wide line.

The following topics discuss pens:

Terms

Cosmetic Pens

Geometric Pens

Pen Attributes

Using Pens

Modifying the Dialog Box Template

Processing Dialog Box Input

Functions


Cosmetic Pens

The dimensions of a cosmetic pen are specified in device units. Therefore, lines drawn with a cosmetic pen always have a fixed width. Lines drawn with a cosmetic pen are generally drawn three to ten times faster than lines drawn with a geometric pen. Cosmetic pens have three attributes: width, style, and color.

To create a cosmetic pen, an application uses the CreatePen, CreatePenIndirect, or ExtCreatePen function. To retrieve one of the three stock cosmetic pens managed by window manager, the application uses the GetStockObject function.

After a pen is created (or a handle identifying one of the stock pens is obtained), the pen is selected into the application's device context by calling the SelectObject function. From this point on, the application uses this pen for any line-drawing operations in its client area.


Geometric Pens

The dimensions of a geometric pen are specified in logical units. Therefore, lines drawn with a geometric pen can be scaled--that is, they may appear wider or narrower, depending on the current world transformation.

In addition to the three attributes shared with cosmetic pens (width, style, and color), geometric pens possess the following four attributes: pattern, optional hatch, end style, and join style.

To create a geometric pen, an application uses the ExtCreatePen function. As with cosmetic pens, the SelectObject function selects a geometric pen into the application's device context.


Pen Attributes

There are seven pen attributes that define the type of pen and its characteristics: width, style, color, pattern, hatch, end style, and join style. Both cosmetic and geometric pens have the width, style, and color attributes. Only geometric pens have the pattern, hatch, end style, and join style attributes. The pattern and optional hatch attribute are usually associated with a brush, but can also be used with geometric pens.

Width

The width attribute specifies a cosmetic pen width in device units. When used with a geometric pen, however, it specifies the pen's width in logical units.

Currently, Windows limits the width of cosmetic pens to a single pixel; however, future versions may remove this limitation.

Style

The style attribute specifies the line pattern that appears when a particular cosmetic or geometric pen is used. There are eight predefined pen styles. The following illustration shows the seven of these styles that are defined by Windows.

The inside-frame style is identical to the solid style for cosmetic pens. However, it operates differently when used with a geometric pen. If the geometric pen is wider than a single pixel and a drawing function uses the pen to draw a border around a filled object, Windows draws the border inside the object's frame. By using the inside-frame style, an application can ensure that an object appears entirely within the specified dimensions, regardless of the geometric pen width.

In addition to the seven styles defined by Windows, there is an eighth style that is user (or application) defined. A user-defined style generates lines with a customized series of dashes and dots.

Use the CreatePen, CreatePenIndirect, or ExtCreatePenfunction to create a pen that has the Windows-defined styles. Use the ExtCreatePen function to create a pen that has a user-defined style.

Color

The color attribute specifies the pen's color. An application can create a cosmetic pen with a unique color by storing the red, green, blue (RGB) triplet that specifies the desired color in a COLORREF structure and passing this structure's address to the CreatePen, CreatePenIndirect, or ExtCreatePen function. (The stock pens are limited to black, white, and invisible.)

Pattern

The pattern attribute specifies the pattern of a geometric pen.

The following illustration shows lines drawn with different geometric pens. Each pen was created using a different pattern attribute.

The first line in the previous illustration is drawn using one of the six available hatch patterns. The next line is drawn using the hollow pattern, identical to the null pattern. The third line is drawn using a custom pattern created from an 8- by 8-pixel bitmap. The last line is drawn using a solid pattern. Creating a brush and passing its handle to the ExtCreatePen function creates a pattern.

Hatch

The hatch attribute specifies the hatch type of a geometric pen with the hatch pattern attribute. There are six patterns available. The following illustration shows lines drawn using different hatch patterns.

End Cap

The end cap attribute specifies the shape of a geometric pen: round, square, or flat. The following illustration shows parallel lines drawn using each type of end cap.

The round and square end caps extend past the starting and ending points of a line drawn with a geometric pen; the flat end cap does not.

Join

The join attribute specifies how the ends of two geometric lines are joined: beveled, mitered, or round. The following illustration shows pairs of connected lines drawn using each type of join.


Using Pens

This section contains example code that demonstrates how to create and use a simple pen selection dialog box. The dialog box is a modified Color common dialog box that enables the user to select a pen color, width, style, and join.

The following illustration shows the modified dialog box.


Modifying the Dialog Box Template

To modify the Color common dialog box, it is necessary to modify the dialog box template stored in the file COLOR.DLG. The modifications include changing the coordinates of the custom-colors box and custom-colors button (so that they are drawn outside the dialog box window and are therefore invisible) and adding three new controls. Two of these new controls are list boxes that enable the user to select a style and a join. The third control is an edit box in which the user can specify a pen width (in the range 1 through 99). The following excerpt from the application's resource file shows part of the modified dialog box template.

DLGINCLUDE RCDATA DISCARDABLE

BEGIN

    "colordlg.h\0"

END

CHOOSECOLOR DIALOG 2, 0, 298, 184

STYLE DS_MODALFRAME | WS_POPUP | WS_CAPTION | WS_SYSMENU

CAPTION "Standard Pen"

FONT 8, "Helv"

BEGIN

    LTEXT           "Pen Color:", -1, 4, 4, 140, 9

    CONTROL         "", COLOR_BOX1, "Static", SS_SIMPLE | WS_GROUP |

                    WS_TABSTOP, 4, 14, 140, 86

    LTEXT           "&Custom Colors:", -1, 4, 806, 140, 9

    CONTROL         "", COLOR_CUSTOM1, "Static", SS_SIMPLE | WS_GROUP |

                    WS_TABSTOP, 4, 816, 140, 28

    PUSHBUTTON      "&Define Custom Colors...", COLOR_MIX, 4, 850, 140, 14,

                    WS_GROUP

    DEFPUSHBUTTON   "OK", IDOK, 4, 166, 44, 14, WS_GROUP

    PUSHBUTTON      "Cancel", IDCANCEL, 52, 166, 44, 14, WS_GROUP

    PUSHBUTTON      "&Help", 1038, 100, 166, 44, 14, WS_GROUP

    CONTROL         "", COLOR_RAINBOW, "Static", SS_BLACKFRAME, 152, 4, 118,

                    116

    CONTROL         "", COLOR_LUMSCROLL, "Static", SS_SIMPLE, 280, 4, 8, 116

    CONTROL         "", COLOR_CURRENT, "Static", SS_BLACKFRAME, 152, 124,

                    40, 26

    RTEXT           "Color|", -1, 152, 151, 20, 9

    LTEXT           "S&olid", -1, 172, 151, 20, 9

    PUSHBUTTON      "&o", COLOR_SOLID, 300, 200, 4, 14, WS_GROUP

    RTEXT           "&Hue:", COLOR_HUEACCEL, 194, 126, 20, 9

    EDITTEXT        COLOR_HUE, 216, 124, 18, 12, WS_GROUP

    RTEXT           "&Sat:", COLOR_SATACCEL, 194, 140, 20, 9

    EDITTEXT        COLOR_SAT, 216, 138, 18, 12, WS_GROUP

    RTEXT           "&Lum:", COLOR_LUMACCEL, 194, 154, 20, 9

    EDITTEXT        COLOR_LUM, 216, 152, 18, 12, WS_GROUP

    RTEXT           "&Red:", COLOR_REDACCEL, 243, 126, 24, 9

    EDITTEXT        COLOR_RED, 269, 124, 18, 12, WS_GROUP

    RTEXT           "&Green:", COLOR_GREENACCEL, 243, 140, 24, 9

    EDITTEXT        COLOR_GREEN, 269, 138, 18, 12, WS_GROUP

    RTEXT           "Bl&ue:", COLOR_BLUEACCEL, 243, 154, 24, 9

    EDITTEXT        COLOR_BLUE, 269, 152, 18, 12, WS_GROUP

    PUSHBUTTON      "&Add to Custom Colors", COLOR_ADD, 152, 166, 142, 14,

                    WS_GROUP

    LISTBOX         101, 3, 113, 80, 52, LBS_SORT | WS_VSCROLL | WS_TABSTOP

    LTEXT           "Pen Style", 102, 3, 102, 57, 10

    LTEXT           "Pen Width", 103, 93, 103, 37, 8

    EDITTEXT        104, 94, 113, 32, 12, ES_AUTOHSCROLL

    LTEXT           "Join Style", 105, 93, 129, 40, 8

    LISTBOX         106, 94, 138, 48, 24, LBS_SORT | WS_VSCROLL | WS_TABSTOP

END


Processing Dialog Box Input

After the dialog box template is modified, it is necessary to provide a callback function that initializes the new controls in the dialog box and processes the corresponding input. The following excerpt from the application's source file shows the callback function.

DWORD dwPenStyle;

DWORD dwJoinStyle;

DWORD dwWidth;

UINT FAR PASCAL SetPenAttr(HWND hwndDlg, UINT uMsg, UINT wParam,

                          LONG lParam)

{

    static HWND hwndLineStyles;

    static HWND hwndJoinStyles;

    static HWND hwndWidth;

    DWORD adwPenStyle[] = {

                            PS_DASH,

                            PS_DASHDOT,

                            PS_DOT,

                            PS_INSIDEFRAME,

                            PS_NULL,

                            PS_SOLID

                          };

    DWORD adwJoinStyle[] = {

                            PS_JOIN_BEVEL,

                            PS_JOIN_MITER,

                            PS_JOIN_ROUND

                           };

    CHAR  chWidth[3];

    int iCount;

    int  index;

    switch(uMsg){

        case WM_INITDIALOG:

            /* Initialize each custom control with the required data. */

            hwndLineStyles = GetDlgItem(hwndDlg, IDD_PEN_STYLE);

            /* Use the PenStyle constants as indices. */

            SendMessage(hwndLineStyles, LB_ADDSTRING, 0,

                        (LONG) "DASH");

            SendMessage(hwndLineStyles, LB_ADDSTRING, 0,

                        (LONG) "DASHDOT");

            SendMessage(hwndLineStyles, LB_ADDSTRING, 0,

                        (LONG) "DOT");

            SendMessage(hwndLineStyles, LB_ADDSTRING, 0,

                        (LONG) "INSIDEFRAME");

            SendMessage(hwndLineStyles, LB_ADDSTRING, 0,

                        (LONG) "NULL");

            SendMessage(hwndLineStyles, LB_ADDSTRING, 0,

                        (LONG) "SOLID");

            hwndJoinStyles = GetDlgItem(hwndDlg, IDD_JOIN_STYLE);

            /* Use the JoinStyle constants as indices. */

            SendMessage(hwndJoinStyles, LB_ADDSTRING, PS_JOIN_BEVEL,

                        (LONG) "BEVEL");

            SendMessage(hwndJoinStyles, LB_ADDSTRING, PS_JOIN_MITER,

                        (LONG) "MITER");

            SendMessage(hwndJoinStyles, LB_ADDSTRING, PS_JOIN_ROUND,

                        (LONG) "ROUND");

            hwndWidth = GetDlgItem(hwndDlg, IDD_PEN_WIDTH);

            SetWindowText(hwndWidth, (LPTSTR)"1");

        return TRUE;

        case WM_COMMAND:

            /* Retrieve the requested pen style. */

            index = SendMessage(hwndLineStyles, LB_GETCURSEL, 0, 0L);

            dwPenStyle = adwPenStyle[index];

            /* Retrieve the requested join style. */

            index = SendMessage(hwndJoinStyles, LB_GETCURSEL, 0, 0L);

            dwJoinStyle = adwJoinStyle[index];

            /* Retrieve the requested width. */

            GetDlgItemText(hwndDlg, IDD_PEN_WIDTH, chWidth, 3);

            dwWidth = RetrieveWidth(chWidth, GetStrLngth(chWidth));

        return FALSE;

    }

    return FALSE;

    UNREFERENCED_PARAMETER(wParam);

    UNREFERENCED_PARAMETER(lParam);

    UNREFERENCED_PARAMETER(iCount);

}

You must register the callback function with the common dialog box procedure by initializing the appropriate members of a CHOOSECOLOR structure, which is passed to the ChooseColor function. The following excerpt from the application's source file shows how this can be done.

static CHOOSECOLOR cc; /* structure required for Color dialog box */

static COLORREF clr;

static COLORREF aclrCust[256];

                    /*

                     * Initialize the necessary CHOOSECOLOR

                     * members.

                     */

                    cc.lStructSize = sizeof(CHOOSECOLOR);

                    cc.hwndOwner = hwnd;

                    cc.hInstance = (HWND)hInst;

                    cc.rgbResult = clr;

                    cc.lpCustColors = aclrCust;

                    cc.Flags =  CC_ENABLEHOOK | CC_ENABLETEMPLATE;

                    cc.lpfnHook = (LPCCHOOKPROC)SetPenAttr;

                    cc.lpTemplateName = "CHOOSECOLOR";

After the ChooseColor function executes, the rgbResult member of the CHOOSECOLOR structure contains the user-requested color, the dwPenStyle parameter specifies the requested pen style, the dwJoinStyle parameter specifies the requested join, and the dwWidth parameter specifies the requested width. These values are passed to the ExtCreatePen function and used to create a geometric pen, which is selected into a device context and used for various line-drawing operations.

if (ChooseColor(&cc)){

    hdc = GetDC(hwnd);

    /* Initialize the pen's "brush." */

    logbrush.lbStyle = BS_SOLID;

    logbrush.lbColor = cc.rgbResult;

    logbrush.lbHatch = 0;

    /* Create a pen and select it into the DC. */

    hpenOld = SelectObject(hdc,

              ExtCreatePen(PS_GEOMETRIC | dwPenStyle

                           | dwJoinStyle, dwWidth,

                           &logbrush, (DWORD) NULL,

                           (LPDWORD) NULL));

    /* Perform drawing operations. */

    MoveToEx(hdc, 100, 100, NULL);

    LineTo(hdc, 100, 200);

    LineTo(hdc, 200, 200);

    LineTo(hdc, 200, 100);

    LineTo(hdc, 100, 100);

    ReleaseDC(hwnd, hdc);

    }


Functions

Following are the functions that support the pen interface.

CreatePen

CreatePenIndirect

ExtCreatePen

GetStockObject


Regions Overview

About Regions

In Microsoft® Windows™, a region is a rectangle, polygon, or ellipse (or a combination of two or more of these shapes) that can be filled, painted, inverted, framed, and used to perform hit testing (testing for the cursor location).

The following topics discuss regions:

Terms

Region Creation and Selection

Region Operations

Using Regions to Clip Output

Using Regions to Perform Hit-Testing

Functions

Following are three types of regions that have been filled and framed.


Region Creation and Selection

An application creates a region by calling a function associated with a specific shape. The following table shows the function(s) associated with each of the standard shapes.

Shape	Function

Rectangular region	CreateRectRgn, CreateRectRgnIndirect

Rectangular region with rounded corners	CreateRoundRectRgn

Elliptical region	CreateEllipticRgn, CreateEllipticRgnIndirect

Polygonal region	CreatePolygonRgn, CreatePolyPolygonRgn

Each region-creation function returns a handle that identifies the new region. An application can use this handle of select the region into a device context by calling the SelectObject function and supplying this handle as the second argument. After a region is selected into a device context, an application can perform various operations on it.


Region Operations

Applications can combine regions, compare them, paint or invert their interiors, draw a frame around them, retrieve their dimensions, and test to see whether the cursor lies within their boundaries.

Combining

An application combines two regions by calling the CombineRgn function. Using this function, an application can combine the intersecting parts of two regions, all but the intersecting parts of two regions, the two original regions in their entirety, and so on. Following are the five region combinations.

Value	Description

RGN_AND	The intersecting parts of two original regions define a new region.

RGN_COPY	A copy of the first (of the two original regions) defines a new region.

RGN_DIFF	The part of the first region that does not intersect the second defines a new region.

RGN_OR	The two original regions define a new region.

RGN_XOR	Those parts of the two original regions that do not overlap define a new region.

The following illustration shows the five possible combinations of a square and a circular region resulting from a call to the CombineRgn function.

Comparing

An application compares two regions to determine whether or not they are identical by calling the EqualRgn function. EqualRgn considers two regions identical if they are equal in size and shape.

Filling

An application fills the interior of a region by calling the FillRgn function and supplying a handle that identifies a specific brush. When an application calls FillRgn, Windows fills the region with the brush by using the current fill mode for the specified device context. There are two fill modes: alternate and winding. The application can set the fill mode for a device context by calling the SetPolyFillMode function. An application can retrieve the current fill mode for a device context by calling the GetPolyFillMode function.

The following illustration shows two identical regions: one filled using alternate mode, the other filled using winding mode.

Alternate Mode

To determine which pixels Windows highlights when alternate mode is specified, perform the following test:

1	Select a pixel within the region's interior.

2	Draw an imaginary ray, in the positive x-direction, from that pixel towards infinity.

3	Each time the ray intersects a boundary line, increment a count value.

Windows highlights the pixel if the count value is an odd number.

Winding Mode

To determine which pixels Windows highlights when winding mode is specified, perform the following test:

1	Determine the direction in which each boundary line is drawn.

2	Select a pixel within the region's interior.

3	Draw an imaginary ray, in the positive x-direction, from the pixel toward infinity.

4	Each time the ray intersects a boundary line with a positive y-component, increment a count value; each time the ray intersects a boundary line with a negative y-component, decrement the count value.

Windows highlights the pixel if the count value is nonzero.

Painting

An application fills the interior of a region by using the brush currently selected into a device context by the PaintRgn function. This function uses the current polygon fill modes (alternate and winding).

Inverting

An application inverts the colors that appear within a region by calling the InvertRgn function. On monochrome displays, 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.

Framing

An application draws a border around a region by calling the FrameRgn function and specifying the border width and brush pattern that Windows uses when drawing the frame.

Retrieving a Bounding Rectangle

An application retrieves the dimensions of a region's bounding rectangle by calling the GetRgnBox function. If the region is rectangular, GetRgnBox returns the dimensions of the region. If the region is elliptical, the function returns the dimensions of the smallest rectangle that can be drawn around the ellipse. The long sides of the rectangle are the same length as the ellipse's major axis; the short sides of the rectangle are the same length as the ellipse's minor axis. If the region is polygonal, GetRgnBox returns the dimensions of the smallest rectangle that can be drawn around the entire polygon.

Moving

An application moves a region by calling the OffsetRgn function. The given offsets along the x-axis and y-axis determine the number of logical units to move left or right and up or down.

Hit Testing

An application performs hit testing on regions to determine the coordinates of the current cursor position. It then passes these coordinates--as well as a handle identifying the region--to the PtInRegion function. The cursor coordinates can be retrieved by processing the various mouse messages such as WM_LBUTTONDOWN, WM_LBUTTONUP, WM_RBUTTONDOWN, WM_RBUTTONUP. The PtInRegion return value indicates whether the cursor position is within the given region.


Using Regions to Clip Output

This section contains a single example that demonstrates how you can use regions to enable the user to define how a part of the client area output can appear. Regions used for this purpose are called clipping regions.

The example for this section is taken from a Windows-based application that enables a user to capture the entire desktop as a bitmap and then isolate and save a part of this image as a .BMP file. The following illustration shows the application's window and client area immediately after the user has captured the desktop contents.

By selecting the Define Clip Region option from the application's menu, the user is able to select a clipping region by clicking the left mouse button and dragging the mouse. As the user drags the mouse, the application draws a rectangle that corresponds to the new clipping region. The following illustration shows the application's window, client area, and the rectangle created by the user.

By selecting the Clip option, the user is able to redraw the isolated part of the image within the boundaries of the specified rectangle. The following illustration shows the application's window, the client area, and the clipped output.

Defining the Clipping Region

When the user selects the Define Clip Region option, Windows issues a WM_COMMAND message. The wParam parameter of this message contains an application-defined constant, IDM_DEFINE, that indicates that the user selected this option from the menu. The application processes this input by setting a Boolean flag, fDefineRegion, as shown in the following code.

case WM_COMMAND:

    switch (wParam) {

case IDM_DEFINE:

    fDefineRegion = TRUE;

break;

After selecting the Define Clipping Region option, the user can begin drawing the rectangle by clicking and dragging the mouse while the cursor is in the application's client area.

When the user presses the left button, Windows issues a WM_LBUTTONDOWN message. The lParam parameter of this message contains the cursor coordinates, which correspond to the upper left corner of a rectangle used to define the clipping region. The application processes the WM_LBUTTONDOWN message as follows:

/* These variables are required for clipping. */

static POINT ptUpperLeft;

static POINT ptLowerRight;

static POINT aptRect[5];

static POINT ptTmp;

static POINTS ptsTmp;

static BOOL fDefineRegion;

static BOOL fRegionExists;

static HRGN hrgn;

static RECT rctTmp;

int i;

switch (message) {

case WM_LBUTTONDOWN:

    if (fDefineRegion) {

        /* Retrieve the new upper left corner. */

        ptsTmp = MAKEPOINTS(lParam);

        ptUpperLeft.x = (LONG) ptsTmp.x;

        ptUpperLeft.y = (LONG) ptsTmp.y;

    }

    if (fRegionExists) {

        /* Erase the previous rectangle. */

        hdc = GetDC(hwnd);

        SetROP2(hdc, R2_NOTXORPEN);

        if (!Polyline(hdc, (CONST POINT *) aptRect, 5))

            errhandler("Polyline Failed", hwnd);

        ReleaseDC(hwnd, hdc);

        /* Clear the rectangle coordinates. */

        for (i = 0; i < 4; i++) {

               aptRect[i].x = 0;

               aptRect[i].y = 0;

        }

        /* Clear the temporary point structure. */

        ptTmp.x = 0;

        ptTmp.y = 0;

        /* Clear the lower right coordinates. */

        ptLowerRight.x = 0;

        ptLowerRight.y = 0;

        /* Reset the flag. */

        fRegionExists = FALSE;

        fDefineRegion = TRUE;

        /* Retrieve the new upper left corner. */

        ptsTmp = MAKEPOINTS(lParam);

        ptUpperLeft.x = (LONG) ptsTmp.x;

        ptUpperLeft.y = (LONG) ptsTmp.y;

    }

break;

As the user drags the mouse, Windows issues WM_MOUSEMOVE messages and stores the new cursor coordinates in the lParam parameter. Each time the application receives a new WM_MOUSEMOVE message, it erases the previous rectangle (if one exists) and draws the new rectangle by calling the Polyline function and passing the coordinates of the four corners of the rectangle. The application performs these tasks as shown in the following example.

/* These variables are required for clipping. */

static POINT ptUpperLeft;

static POINT ptLowerRight;

static POINT aptRect[5];

static POINT ptTmp;

static POINTS ptsTmp;

static BOOL fDefineRegion;

static BOOL fRegionExists;

static HRGN hrgn;

static RECT rctTmp;

int i;

switch (message) {

case WM_MOUSEMOVE:

    if (wParam & MK_LBUTTON && fDefineRegion) {

        /* Get a window DC. */

        hdc = GetDC(hwnd);

        if (!SetROP2(hdc, R2_NOTXORPEN))

            errhandler("SetROP2 Failed", hwnd);

        /*

         * If previous mouse movement occurred, store the original

         * lower right corner coordinates in a temporary structure.

         */

        if (ptLowerRight.x) {

            ptTmp.x = ptLowerRight.x;

            ptTmp.y = ptLowerRight.y;

        }

        /*

         * Get the new coordinates of the clipping region's lower

         * right corner.

         */

        ptsTmp = MAKEPOINTS(lParam);

        ptLowerRight.x = (LONG) ptsTmp.x;

        ptLowerRight.y = (LONG) ptsTmp.y;

        /*

         * If previous mouse movement occurred, erase the original

         * rectangle.

         */

        if (ptTmp.x) {

            aptRect[0].x = ptUpperLeft.x;

            aptRect[0].y = ptUpperLeft.y;

            aptRect[1].x = ptTmp.x;

            aptRect[1].y = ptUpperLeft.y;

            aptRect[2].x = ptTmp.x;

            aptRect[2].y = ptTmp.y;

            aptRect[3].x = ptUpperLeft.x;

            aptRect[3].y = ptTmp.y;

            aptRect[4].x = aptRect[0].x;

            aptRect[4].y = aptRect[0].y;

            if (!Polyline(hdc, (CONST POINT *) aptRect, 5))

                errhandler("Polyline Failed", hwnd);

        }

        aptRect[0].x = ptUpperLeft.x;

        aptRect[0].y = ptUpperLeft.y;

        aptRect[1].x = ptLowerRight.x;

        aptRect[1].y = ptUpperLeft.y;

        aptRect[2].x = ptLowerRight.x;

        aptRect[2].y = ptLowerRight.y;

        aptRect[3].x = ptUpperLeft.x;

        aptRect[3].y = ptLowerRight.y;

        aptRect[4].x = aptRect[0].x;

        aptRect[4].y = aptRect[0].y;

        if (!Polyline(hdc, (CONST POINT *) aptRect, 5))

             errhandler("Polyline Failed", hwnd);

        ReleaseDC(hwnd, hdc);

    }

    break;

Clipping Output

After the user chooses the Clip option from the menu, the application uses the coordinates of the rectangle the user created to define a clipping region. After defining the clipping region and selecting it into the application's device context, the application redraws the bitmapped image. The application performs these tasks as shown in the following example.

/* These variables are required for clipping. */

static POINT ptUpperLeft;

static POINT ptLowerRight;

static POINT aptRect[5];

static POINT ptTmp;

static POINTS ptsTmp;

static BOOL fDefineRegion;

static BOOL fRegionExists;

static HRGN hrgn;

static RECT rctTmp;

int i;

case WM_COMMAND:

    switch (wParam) {

case IDM_CLIP:

    hdc = GetDC(hwnd);

    /*

     * Retrieve the application's client rectangle and paint

     * with the default (white) brush.

     */

    GetClientRect(hwnd, &rctTmp);

    FillRect(hdc, &rctTmp, GetStockObject(WHITE_BRUSH));

    /* Use the rectangle coordinates to define a clipping region. */

    hrgn = CreateRectRgn(aptRect[0].x, aptRect[0].y,

        aptRect[2].x, aptRect[2].y);

    SelectClipRgn(hdc, hrgn);

    /* Transfer (draw) the bitmap into the clipped rectangle. */

    BitBlt(hdc,

       0, 0,

       bmp.bmWidth, bmp.bmHeight,

       hdcCompatible,

       0, 0,

       SRCCOPY);

    ReleaseDC(hwnd, hdc);

break;


Using Regions to Perform Hit Testing

The example in Brushes uses regions to simulate a "zoomed" view of an 8- by 8-pixel monochrome bitmap. By clicking on the pixels in this bitmap, the user creates a custom brush suitable for drawing operations. This example shows how to use the PtInRegion function to perform hit testing and the InvertRgn function to invert the colors in a region.


Functions

Following are the functions used with regions.

CombineRgn

CreateEllipticRgn

CreateEllipticRgnIndirect

CreatePolygonRgn

CreatePolyPolygonRgn

CreateRectRgn

CreateRectRgnIndirect

CreateRoundRectRgn

EqualRgn

ExtCreateRegion

FillRgn

FrameRgn

GetPolyFillMode

GetRgnBox

GetRegionData

InvertRgn

OffsetRgn

PaintRgn

PtInRegion

RectInRegion

SetPolyFillMode


Lines and Curves Overview

About Lines and Curves

All types of applications written for Microsoft® Windows™ use lines and curves to draw graphics output on raster devices. Computer-aided design (CAD) and drawing applications use lines and curves to outline objects, specify the centers of objects, the dimensions of objects, and so on. Spreadsheet applications use lines and curves to draw grids, charts, and graphs. Word processing applications use lines to create rules and borders on a page of text.

The following topics discuss lines and curves:

Terms

Lines

Curves

Combined Lines and Curves

Line and Curve Attributes

Using Lines and Curves

Using the Line Functions to Draw Markers

Using Lines and Curves to Draw a Pie Chart

Functions


Lines

A line is a set of highlighted pixels on a raster display (or a set of dots on a printed page) identified by two points: a starting point and an ending point. In Windows, the pixel located at the starting point is always included in the line, and the pixel located at the ending point is always excluded (these lines are sometimes called inclusive-exclusive).

When an application calls one of the Windows line-drawing functions, the graphics device interface (GDI), or in some cases a device driver, determines which pixels should be highlighted. GDI is a dynamic-link library that processes graphics function calls from a Windows-based application and passes those calls to a device driver. A device driver is a dynamic-link library that receives input from GDI, converts the input to device commands, and passes these commands to the appropriate device. GDI uses a digital differential analyzer (DDA) to determine the set of pixels that define a line. A DDA determines the set of pixels by examining each point on the line and identifying those pixels on the display surface (or dots on a printed page) that correspond to these points. The following illustration shows a line, its starting point, its ending point, and the pixels highlighted by using a simple DDA.

The simplest and most common DDA is the Bresenham, or incremental DDA. A modified version of this algorithm draws lines in Windows versions 3.x. The incremental DDA is noted for its simplicity, but it is also noted for its inaccuracy; because it rounds off to the nearest integer value, it sometimes fails to represent the original line requested by the application. The DDA used by the new GDI does not round off to the nearest integer. As a result, it produces output that is sometimes much closer in appearance to the original line requested by the application.

Note:	If an application requires line output that cannot be achieved with the new Win32 DDA, it can draw its own lines by calling the LineDDA function and supplying a private DDA. However, the LineDDA function draws lines much slower than the Windows line-drawing functions; do not use this function within an application if speed is a primary concern.

An application can use the new Win32 DDA to draw single lines and multiple, connected line segments. An application can draw a single line by calling the LineTo function. This function draws a line from a device context's current position to a specified ending point. An application can draw a series of connected line segments by calling the Polyline function, supplying an array of points that specify the ending point of each line segment. An application can draw multiple, disjointed series of connected line segments by calling the PolyPolyline function, supplying the required ending points.

The following illustration shows line output created by calling the LineTo, Polyline, and PolyPolyline functions.


Curves

A regular curve is a set of highlighted pixels on a raster display (or dots on a printed page) that define the perimeter (or part of the perimeter) of a conic section. An irregular curve is a set of pixels that define a curve that does not fit the perimeter of a conic section. In Windows, the ending point is excluded from a curve just as it is excluded from a line.

When an application calls one of the Windows curve-drawing functions, GDI breaks the curve into a number of extremely small, discrete line segments. After determining the ending points for each of these line segments, GDI determines which pixels (or dots) define each line by applying its DDA.

An application can draw an ellipse or part of an ellipse by calling the Arc function. This function draws the curve within the perimeter of an invisible rectangle called a bounding rectangle. The size of the ellipse is specified by two invisible radials extending from the center of the rectangle to the sides of the rectangle. The following illustration shows an arc (part of an ellipse) drawn using the Arc function.

When calling the Arc function, an application specifies the coordinates of the bounding rectangle and radials. The preceding illustration shows the rectangle and radials with dashed lines while the actual arc was drawn using a solid line.

When drawing the arc of another object, the application can call the SetArcDirection and GetArcDirection functions to control the direction (clockwise, counterclockwise) in which the object is drawn. The default direction for drawing arcs and other objects is counterclockwise.

In addition to drawing ellipses or parts of ellipses, Windows-based applications can draw irregular curves called Bézier splines. Originally, the term spline referred to a tool used by draftsmen to draw irregular curves. With the development of graphical interfaces, however, the term has come to refer to the curve itself. A Bézier spline is an irregular curve with the following characteristics: The curvature of the spline is defined by four control points (p1, p2, p3, and p4). The control points p1 and p4 define the starting and ending points of the curve; the control points p2 and p3 define the shape of the curve by marking points where the curve reverses orientation. The following illustration shows two Bézier splines, their starting and ending points, and control points.

An application can draw irregular curves by calling the PolyBezier function, supplying the appropriate control points.


Combined Lines and Curves

In addition to drawing lines or curves, Windows-based applications can draw combinations of line and curve output by calling a single function. For example, an application can draw the outline of a pie chart by calling the AngleArc function, as shown in the following illustration.

The AngleArc function draws an arc along a circle's perimeter and draws a line connecting the starting point of the arc to the circle's center. The pie chart in the preceding illustration was created by calling the AngleArc function five consecutive times. In addition to using the AngleArc function, a Windows-based application could also combine line and irregular curve output by using the PolyDraw function.


Line and Curve Attributes

A device context contains attributes that affect line and curve output. These attributes include current position, brush style, brush color, pen style, pen color, transformation, and so on.

The default current position for any device context is located at the point (0,0) in logical (or world) space. You can set these coordinates to a new position by calling the MoveToEx function and passing a new set of coordinates.

Note:	Windows provides two sets of line- and curve-drawing functions: the first set retains the current position in a device context; the second set alters the position. You can identify the functions that alter the current position by examining the function name. If the function name ends with the preposition "To", the function sets the current position to the ending point of the last line drawn (LineTo, ArcTo, PolylineTo, or PolyBezierTo). If the function name does not end with this preposition, it leaves the current position intact (Arc, Polyline, PolyBezier).

The default brush is a solid white brush. An application can create a new brush by calling the CreateBrushIndirect function. After creating a brush, your application can select it into its device context by calling the SelectObject function. Windows provides a complete set of functions to create, select, and alter the brush in your application's device context.

The default pen is a cosmetic, solid black pen that is one pixel wide. The application can create a pen by using the ExtCreatePen function. After creating a pen, your application can select it into its device context by calling the SelectObject function. Windows provides a complete set of functions to create, select, and alter the pen in your application's device context.

The default transformation is the unity transformation (specified by the identity matrix). An application can specify a new transformation by calling the SetWorldTransform function. Windows provides a complete set of functions to transform lines and curves by altering their width, location, and general appearance.


Using Lines and Curves

You can use the line and curve functions to draw virtually any shape or object in the client area of the application window. This section contains two code samples that illustrate how these functions might be used.


Drawing Markers

You can use the line functions to draw markers. A marker is a symbol centered over a point. Drawing applications use markers to designate starting points, ending points, and control points. Spreadsheet applications use markers to designate points of interest on a chart or graph. The following illustration shows a screen from a drawing application that uses markers to designate the ending points and control points for a Bézier spline.

In the following code sample, the application-defined Marker function creates a marker by using the MoveToEx and LineTo functions. These functions draw two intersecting lines, 20 pixels in length, centered over the cursor coordinates.

void Marker(LONG x, LONG y, HWND hwnd)

{

    HDC hdc;

    hdc = GetDC(hwnd);

        MoveToEx(hdc, (int) x - 10, (int) y, (LPPOINT) NULL);

        LineTo(hdc, (int) x + 10, (int) y);

        MoveToEx(hdc, (int) x, (int) y - 10, (LPPOINT) NULL);

        LineTo(hdc, (int) x, (int) y + 10);

    ReleaseDC(hwnd, hdc);

}

Windows stores the coordinates of the cursor in the lParam parameter of the WM_LBUTTONDOWN message when the user presses the left mouse button. The following code demonstrates how an application gets these coordinates, determines whether they lie within its client area, and passes them to the Marker function to draw the marker.

/* Line- and arc-drawing variables */

static BOOL bCollectPoints;

static POINT ptMouseDown[32];

static int index;

POINTS ptTmp;

RECT rc;

    case WM_LBUTTONDOWN:

        if (bCollectPoints && index < 32){

            /* Create the region from the client area. */

            GetClientRect(hwnd, &rc);

            hrgn = CreateRectRgn(rc.left, rc.top,

                rc.right, rc.bottom);

            ptTmp = MAKEPOINTS((POINTS FAR *) lParam);

            ptMouseDown[index].x = (LONG) ptTmp.x;

            ptMouseDown[index].y = (LONG) ptTmp.y;

            /* Test for a hit in the client rectangle. */

            if (PtInRegion(hrgn, ptMouseDown[index].x,

                    ptMouseDown[index].y)) {

                /* If a hit occurs, record the mouse coordinates. */

                Marker(ptMouseDown[index].x, ptMouseDown[index].y,

                    hwnd);

                index++;

            }

        }

        break;


Drawing a Pie Chart

You can use the line and curve functions to draw a pie chart. The primary function used to draw pie charts is the AngleArc function, which requires you to supply the coordinates of the center of the pie, the radius of the pie, a start angle, and a sweep angle. Following is a dialog box that the user can use to enter these values.

The following example shows the dialog box template found in the application's resource script (.RC) file. This template specifies characteristics of the preceding dialog box (its height, the controls it contains, and its style).

AngleArc DIALOG 6, 18, 160, 100

STYLE WS_DLGFRAME | WS_POPUP | WS_VISIBLE | WS_CAPTION

CAPTION "Pie Chart"

FONT 8, "MS Sans Serif"

BEGIN

    EDITTEXT        IDD_X, 18, 22, 25, 12, ES_AUTOHSCROLL

    LTEXT           "X", 102, 4, 24, 9, 8

    EDITTEXT        IDD_Y, 18, 39, 25, 12, ES_AUTOHSCROLL

    LTEXT           "Y", 104, 5, 42, 12, 8

    LTEXT           "Center", 105, 19, 11, 23, 8

    EDITTEXT        IDD_RADIUS, 103, 9, 32, 12, ES_AUTOHSCROLL

    EDITTEXT        IDD_STARTANGLE, 103, 31, 32, 12, ES_AUTOHSCROLL

    EDITTEXT        IDD_SWEEPANGLE, 103, 53, 32, 12, ES_AUTOHSCROLL

    LTEXT           "Radius", 109, 73, 11, 25, 8

    LTEXT           "Start Angle", 110, 59, 33, 42, 8

    LTEXT           "Sweep Angle", 111, 55, 55, 43, 8

    PUSHBUTTON      "OK", IDD_OK, 9, 82, 40, 14

    PUSHBUTTON      "Cancel", IDD_CANCEL, 110, 82, 40, 14

END

The following example shows the dialog box procedure, found in the application's source file. This procedure retrieves data (center coordinates, arc radius, and start and sweep angles) by following these steps:

1	The application-defined ClearBits function initializes the array receiving the user-input to zero.

2	The application-defined GetStrLngth function retrieves the length of the string entered by the user.

3	The application-defined RetrieveInput function retrieves the value entered by the user.

BOOL CALLBACK ArcDlgProc(HWND hdlg, UINT uMsg, WPARAM wParam,

                       LPARAM lParam)

{

    CHAR chInput[4];    /* receives control-window input  */

    int cch;            /* array-size and count variable  */

    switch (uMsg) {

        case WM_INITDIALOG:

            return FALSE;

        case WM_COMMAND:

            switch (wParam){

                /*

                 * If the user pressed the OK button, retrieve the

                 * data that was entered in the various AngleArc

                 * controls.

                 */

                case IDD_OK:

                    /*

                     * Retrieve the x-coordinate of the arc's

                     * center.

                     */

                    ClearBits(chInput, sizeof(chInput));

                    GetDlgItemText(hdlg, IDD_X, chInput,

                        sizeof(chInput));

                    cch = GetStrLngth(chInput);

                    nX = (int)RetrieveInput(chInput, cch);

                    /*

                     * Retrieve the y-coordinate of the arc's

                     * center.

                     */

                    ClearBits(chInput, sizeof(chInput));

                    GetDlgItemText(hdlg, IDD_Y, chInput,

                        sizeof(chInput));

                    cch = GetStrLngth(chInput);

                    nY = (int)RetrieveInput(chInput, cch);

                    /* Retrieve the radius of the arc. */

                    ClearBits(chInput, sizeof(chInput));

                    GetDlgItemText(hdlg, IDD_RADIUS, chInput,

                        sizeof(chInput));

                    cch = GetStrLngth(chInput);

                    dwRadius = (DWORD) RetrieveInput(chInput, cch);

                    /* Retrieve the start angle. */

                    ClearBits(chInput, sizeof(chInput));

                    GetDlgItemText(hdlg, IDD_STARTANGLE, chInput,

                        sizeof(chInput));

                    cch = GetStrLngth(chInput);

                    xStartAngle = (float) RetrieveInput(chInput, cch);

                    /* Retrieve the sweep angle. */

                    ClearBits(chInput, sizeof(chInput));

                    GetDlgItemText(hdlg, IDD_SWEEPANGLE, chInput,

                        sizeof(chInput));

                    cch = GetStrLngth(chInput);

                    xSweepAngle = (float) RetrieveInput(chInput, cch);

                    EndDialog(hdlg, FALSE);

                    return TRUE;

                /*

                 * If user presses the CANCEL button, close the

                 * dialog box.

                 */

                case IDD_CANCEL:

                    EndDialog(hdlg, FALSE);

                    return TRUE;

            } /* end switch (wParam) */

            break;

        default:

            return FALSE;

    } /* end switch (message) */

    UNREFERENCED_PARAMETER(lParam);

}

void ClearBits(LPTSTR cArray, int iLength)

{

    int i;

    for (i = 0; i < iLength; i++)

        cArray[i] = 0;

}

int GetStrLngth(LPTSTR cArray)

{

    int i = 0;

    while (cArray[i++] != 0);

        return i - 1;

}

DWORD RetrieveInput(LPTSTR cArray, int iLength)

{

    int i, iTmp;

    double dVal, dCount;

    dVal = 0.0;

    dCount = (double) (iLength - 1);

    /* Convert ASCII input to a floating-point value. */

    for (i = 0; i < iLength; i++) {

        iTmp = cArray[i] - 0x30;

        dVal = dVal + (((double)iTmp) * pow(10.0, dCount--));

    }

    return (DWORD) dVal;

}

To draw each section of the pie chart, pass the values entered by the user to the AngleArc function. To fill the pie chart using the current brush, embed the call to the AngleArc function in a path bracket. The following example shows the defined path bracket and the AngleArc function call.

int nX;

int nY;

DWORD dwRadius;

float xStartAngle;

float xSweepAngle;

                    case (IDM_ANGLEARC):

                       DialogBox((HINSTANCE) GetModuleHandle (NULL),

                                 (LPTSTR) "AngleArc",

                                 hwnd, (DLGPROC) ArcDlgProc);

                        hdc = GetDC(hwnd);

                            BeginPath(hdc);

                                SelectObject(hdc,

                                    GetStockObject(GRAY_BRUSH));

                                MoveToEx(hdc, nX, nY, (LPPOINT) NULL);

                                AngleArc(hdc, nX, nY, dwRadius,

                                    xStartAngle, xSweepAngle);

                                LineTo(hdc, nX, nY);

                            EndPath(hdc);

                        StrokeAndFillPath(hdc);

                        ReleaseDC(hwnd, hdc);

                        break;


Functions

Following are the functions used with lines and curves.

AngleArc

Arc

ArcTo

GetArcDirection

LineDDA

LineDDAProc

LineTo

MoveToEx

PolyBezier

PolyBezierTo

PolyDraw

Polyline

PolylineTo

PolyPolyline

SetArcDirection


Filled Shapes Overview

About Filled Shapes

Filled shapes are geometric shapes that are outlined by using the current pen and filled by using the current brush. There are five filled shapes: ellipse, chord, pie, polygon, and rectangle. An application written for Microsoft® Windows™ uses filled shapes in a variety of ways. Spreadsheet applications, for example, use filled shapes to construct charts and graphs; drawing and painting applications use filled shapes to allow the user to draw figures and illustrations.

The following topics discuss filled shapes:

Terms

Ellipse

Chord

Pie

Polygon

Rectangle

Using Filled Shapes

Functions


Ellipse

An ellipse is a closed curve defined by two fixed points (f1 and f2) such that the sum of the distances (d1 + d2) from any point on the curve to the two fixed points is constant. The following illustration shows an ellipse drawn by using the Ellipse function.

When calling the Ellipse function, an application supplies the coordinates of the upper-left and lower-right corners of the ellipse's bounding rectangle. A bounding rectangle is the smallest rectangle completely surrounding the ellipse. When Windows draws the ellipse, it excludes the right and lower sides if no world transformations are set. Therefore, for any rectangle measuring x units wide by y units high, the associated ellipse measures x-1 units wide by y-1 units high. If the application set a world transformation by calling the SetWorldTransform or ModifyWorldTransform function, Windows includes the right and lower sides.


Chord

A chord is a region bounded by the intersection of an ellipse and a line segment called a secant. The following illustration shows a chord drawn by using the Chord function.

When calling the Chord function, an application supplies the coordinates of the upper-left and lower-right corners of the ellipse's bounding rectangle, as well as the coordinates of two points defining two radials. A radial is a line drawn from the center of an ellipse's bounding rectangle to a point on the ellipse.

When Windows draws the curved part of the chord, it does so by using the current arc direction for the specified device context. The default arc direction is counterclockwise. You can have your application reset the arc direction by calling the SetArcDirection function.


Pie

A pie is a region bounded by the intersection of an ellipse curve and two radials. The following illustration shows a pie drawn by using the Pie function.

When calling the Pie function, an application supplies the coordinates of the upper-left and lower-right corners of the ellipse's bounding rectangle, as well as the coordinates of two points defining two radials.

When Windows draws the curved part of the pie, it uses the current arc direction for the given device context. The default arc direction is counterclockwise. An application can reset the arc direction by calling the SetArcDirection function.


Polygon

A polygon is a filled shape with straight sides. The sides of a polygon are drawn by using the current pen. When Windows fills a polygon, it uses the current brush and the current polygon fill mode. The two fill modes--alternate (the default) and winding--determine whether regions within a complex polygon are filled or left unpainted. An application can select either mode by calling the SetPolyFillMode function.

The following illustration shows a polygon drawn by using the Polygon function.

In addition to drawing a single polygon with the Polygon function, an application can draw multiple polygons by using the PolyPolygon function.


Rectangle

A rectangle is a four-sided polygon whose opposing sides are parallel and equal in length. Although an application can draw a rectangle by calling the Polygon function, supplying the coordinates of each corner, Windows provides a simpler method: the Rectangle function. This function requires only the coordinates for the upper-left and the lower-right corners. When an application calls the Rectangle function, Windows draws the rectangle, excluding the right and lower sides if no world transformation is set for the given device context.

If a world transformation has been set by using the SetWorldTransform or the ModifyWorldTransform functions, Windows includes the right and lower edges.

In addition to drawing a normal rectangle, the Win32 application programming interface (API) provides a function that applications can use to draw rectangles with rounded corners. This function, RoundRect, requires that the application supply the coordinates of the lower-left and upper-right corners, as well as the width and height of the ellipse used to round each corner.

The Win32 API also provides three functions that applications can use to manipulate rectangles as described in the following table.

Function	Description

FillRect	Repaints the interior of a rectangle.

FrameRect	Redraws the sides of a rectangle.

InvertRect	Inverts the colors that appear within the interior of a rectangle.


Using Filled Shapes

This section contains a code sample that illustrates how to use filled shape functions. The example uses the main window procedure from an application that enables the user to draw ellipses, rectangles, and rectangles with rounded corners.

The user draws a filled shape by selecting a particular shape from the menu, positioning the cursor at the upper-left corner of the shape (or the shape's bounding rectangle in the case of an ellipse), and then dragging the mouse until the desired dimensions are obtained.

The following illustration shows three filled shapes drawn using the code that follows.

To enable the user to draw filled shapes, include the following code in your application.

LRESULT APIENTRY MainWndProc(hwnd, uMsg, wParam, lParam)

HWND hwnd;      /* handle of window         */

UINT uMsg;      /* message                  */

WPARAM wParam;  /* first message parameter  */

LPARAM lParam;  /* second message parameter */

{

    HDC hdc;                    /* handle of device context (DC)        */

    PAINTSTRUCT ps;             /* paint data for Begin/EndPaint        */

    POINT ptClientUL;           /* client area upper-left corner        */

    POINT ptClientLR;           /* client area lower-right corner       */

    static HDC hdcCompat;       /* handle of DC for copying bitmap      */

    static POINT pt;            /* x- and y-coordinates of cursor       */

    static RECT rcTarget;       /* rectangle to receive filled shape    */

    static RECT rcClient;       /* client area rectangle                */

    static BOOL fSizeEllipse;   /* TRUE if ellipse is being sized       */

    static BOOL fDrawEllipse;   /* TRUE if ellipse is being drawn       */

    static BOOL fDrawRectangle; /* TRUE if rectangle is being drawn     */

    static BOOL fSizeRectangle; /* TRUE if rectangle is being sized     */

    static BOOL fSizeRoundRect; /* TRUE if rounded rect. is being sized */

    static BOOL fDrawRoundRect; /* TRUE if rounded rect. is being drawn */

    static int nEllipseWidth;   /* ellipse width for round corners      */

    static int nEllipseHeight;  /* ellipse height for round corners     */

    switch (uMsg) {

        case WM_COMMAND:

            switch (wParam) {

                /*

                 * Set the appropriate flag to indicate which

                 * filled shape the user is drawing.

                 */

                case IDM_ELLIPSE:

                    fSizeEllipse = TRUE;

                break;

                case IDM_RECTANGLE:

                    fSizeRectangle = TRUE;

                break;

                case IDM_ROUNDRECT:

                    fSizeRoundRect = TRUE;

                break;

                default:

                    return DefWindowProc(hwnd, uMsg, wParam, lParam);

            }

            break;

        case WM_CREATE:

            nEllipseWidth = 20;

            nEllipseHeight = 20;

            return 0;

        case WM_PAINT:

            BeginPaint(hwnd, &ps);

            /*

             * Because the default brush is white, select

             * a different brush into the device context

             * to demonstrate the painting of filled shapes.

             */

            SelectObject(ps.hdc, GetStockObject(GRAY_BRUSH));

            /*

             * If one of the filled shape "draw" flags is TRUE,

             * draw the corresponding shape.

             */

            if (fDrawEllipse) { /* draws ellipse */

                Ellipse(ps.hdc, rcTarget.left, rcTarget.top,

                    rcTarget.right, rcTarget.bottom);

                    fDrawEllipse = FALSE;

                    rcTarget.left = rcTarget.right = 0;

                    rcTarget.top = rcTarget.bottom = 0;

                    }

            if (fDrawRectangle) { /* Draws rectangle */

                Rectangle(ps.hdc, rcTarget.left, rcTarget.top,

                    rcTarget.right, rcTarget.bottom);

                    fDrawRectangle = FALSE;

                    rcTarget.left = rcTarget.right = 0;

                    rcTarget.top = rcTarget.bottom = 0;

                    }

            if (fDrawRoundRect) { /* Draws rounded rectangle */

                RoundRect(ps.hdc, rcTarget.left, rcTarget.top,

                    rcTarget.right, rcTarget.bottom,

                    nEllipseWidth, nEllipseHeight);

                    fDrawRectangle = FALSE;

                    rcTarget.left = rcTarget.right = 0;

                    rcTarget.top = rcTarget.bottom = 0;

                    }

            EndPaint(hwnd, &ps);

            break;

        case WM_SIZE:

            /*

             * Convert the client coordinates of the client area

             * rectangle to screen coordinates and save them in a

             * rectangle. The rectangle is passed to the ClipCursor

             * function during WM_LBUTTONDOWN processing.

             */

            GetClientRect(hwnd, &rcClient);

            ptClientUL.x = rcClient.left;

            ptClientUL.y = rcClient.top;

            ptClientLR.x = rcClient.right;

            ptClientLR.y = rcClient.bottom;

            ClientToScreen(hwnd, &ptClientUL);

            ClientToScreen(hwnd, &ptClientLR);

            SetRect(&rcClient, ptClientUL.x, ptClientUL.y,

                ptClientLR.x, ptClientLR.y);

            return 0;

        case WM_LBUTTONDOWN:

            /*

             * Restrict the cursor to the client area.

             * This ensures that the window receives a matching

             * WM_LBUTTONUP message.

             */

            ClipCursor(&rcClient);

            /* Save the coordinates of the cursor. */

            pt.x = (LONG) LOWORD(lParam);

            pt.y = (LONG) HIWORD(lParam);

            /*

             * If the user chooses one of the filled shapes,

             * set the appropriate flag to indicate that the

             * shape is being sized.

             */

             if (fDrawEllipse)

                fSizeEllipse = TRUE;

            return 0;

        case WM_MOUSEMOVE:

            /*

             *

             * If one of the "size" flags is set, draw

             * the target rectangle as the user drags

             * the mouse.

             */

            if ((wParam && MK_LBUTTON)

                    && (fSizeEllipse || fSizeRectangle

                    || fSizeRoundRect)) {  /* draws target rect. */

                /*

                 * Set the mixing mode so that the pen color is the

                 * inverse of the background color. The previous

                 * rectangle can then be erased by drawing

                 * another rectangle on top of it.

                 */

                hdc = GetDC(hwnd);

                SetROP2(hdc, R2_NOTXORPEN);

                /*

                 * If a previous target rectangle exists, erase

                 * it by drawing another rectangle on top.

                 */

                 if (!IsRectEmpty(&rcTarget))

                     Rectangle(hdc, rcTarget.left, rcTarget.top,

                         rcTarget.right, rcTarget.bottom);

                /*

                 * Save the coordinates of the target rectangle.

                 * Avoid invalid rectangles by ensuring that the

                 * value of the left coordinate is greater than

                 * that of the right, and that the value of the

                 * bottom coordinate is greater than that of

                 * the top.

                 */

                if ((pt.x < (LONG) LOWORD(lParam)) &&

                        (pt.y > (LONG) HIWORD(lParam)))

                    SetRect(&rcTarget, pt.x, HIWORD(lParam),

                        LOWORD(lParam), pt.y);

                else if ((pt.x > (LONG) LOWORD(lParam)) &&

                        (pt.y > (LONG) HIWORD(lParam)))

                    SetRect(&rcTarget, LOWORD(lParam),

                        HIWORD(lParam), pt.x, pt.y);

                else if ((pt.x > (LONG) LOWORD(lParam)) &&

                        (pt.y < (LONG) HIWORD(lParam)))

                    SetRect(&rcTarget, LOWORD(lParam), pt.y,

                        pt.x, HIWORD(lParam));

                else

                    SetRect(&rcTarget, pt.x, pt.y, LOWORD(lParam),

                        HIWORD(lParam));

                /* Draw the new target rectangle. */

                Rectangle(hdc, rcTarget.left, rcTarget.top,

                    rcTarget.right, rcTarget.bottom);

                ReleaseDC(hwnd, hdc);

            }

            return 0;

        case WM_LBUTTONUP:

            /*

             * If one of the "size" flags is TRUE, reset

             * it to FALSE, and then set the corresponding "draw" flag.

             * Invalidate the appropriate rectangle and issue

             * a WM_PAINT message.

             */

             if (fSizeEllipse) {

                 fSizeEllipse = FALSE;

                 fDrawEllipse = TRUE;

                }

             if (fSizeRectangle) {

                 fSizeRectangle = FALSE;

                 fDrawRectangle = TRUE;

                }

             if (fSizeRoundRect) {

                 fSizeRoundRect = FALSE;

                 fDrawRoundRect = TRUE;

                }

             if (fDrawEllipse || fDrawRectangle || fDrawRoundRect) {

                 InvalidateRect(hwnd, &rcTarget, TRUE);

                 UpdateWindow(hwnd);

                }

            /* Release the cursor. */

            ClipCursor((LPRECT) NULL);

            return 0;

        case WM_DESTROY:

            /*

             * Destroy the background brush, compatible bitmap,

             * and bitmap.

             */

            DeleteDC(hdcCompat);

            PostQuitMessage(0);

            break;

        default:

            return DefWindowProc(hwnd, uMsg, wParam, lParam);

    }

    return (LRESULT) NULL;

}


Functions

The following functions are used with filled shapes.

Chord

Ellipse

FillRect

FrameRect

InvertRect

Pie

Polygon

PolyPolygon

Rectangle

RoundRect


Fonts and Text Overview

About Fonts

Fonts are used to draw text on video displays and other output devices. Microsoft® Windows™ provides a set of functions that developers can use to install, select, and query different fonts.

The following topics discuss fonts:

Terms

Font Families

Raster, Vector, and TrueType Fonts

Character Sets Used by Fonts

Font Installation and Deletion

Font Creation and Selection

Embedded Fonts

About Text Output

Formatting Text

Drawing Text

Using the Font and Text-Output Functions

Using a Stock Font to Draw Text

Creating a Logical Font

Enumerating the Installed Fonts

Checking the Text Capabilities of a Device

Setting the Text Alignment

Drawing Text From Different Fonts on the Same Line

Rotating Lines of Text

Retrieving Character Outlines

Using Portable TrueType Metrics

Using PANOSE Numbers

Creating Customized Fonts

Font and Text Functions

To a person trained in the mechanics of manuscript composition or familiar with standard typography, some of the typographic terms used in Windows may be unusual. Most of the differences between standard typography and Windows reflect changes in technology. The original typographic terms were based on hot-metal composition, whereas the terms used in Windows, which appear as member names for the font and text output structures, reflect a new technology based on laser-printer output and composition performed on a personal computer using desktop publishing software.

Fonts

In Windows, a font is a collection of characters and symbols that share a common design. The three major elements of this design are referred to as typeface, style, and size.

Typeface

The term typeface refers to specific characteristics of characters and symbols in the font such as the width of the thick and thin strokes that compose the characters and the presence or absence of serifs. A serif is the short cross line at the ends of an unconnected stroke. A font or typeface without serifs is usually called a sans-serif font.

Style

The term style refers to the weight and slant of a font. Font weights can range from thin to black. The following list identifies possible weights for Windows fonts (beginning with the lightest and ending with the heaviest).

Thin

Extralight

Light

Normal

Medium

Semibold

Bold

Extrabold

Heavy

Three terms categorize the slant of a Windows font: roman, oblique, and italic.

The characters in a roman font are upright. The characters in an oblique font are artificially slanted. The slant is achieved by performing a shear transformation on the characters from a roman font. The characters in an italic font are truly slanted and appear as they were designed.

Size

In Windows, the size of a font is an imprecise value. It can generally be determined by measuring the distance from the bottom of a lowercase "g" to the top of an adjacent uppercase "M," as shown in the following illustration.

A font's size is specified in units called points. A point is .013837 of an inch. Following the point system devised by Pierre Simon Fournier, it is common practice to approximate a point as 1/72 inch.

The following illustration shows characters drawn using two different fonts. The first font, from the Century Gothic® typeface, measures 20 points and the second font, from the Bookman Old Style® typeface, measures 20 points. One distinguishing characteristic of the two typefaces is the stroke width: The vertical and horizontal strokes of the Century typeface are of equal width while the vertical strokes of the Bookman typeface are wider than the horizontal strokes. Another distinguishing characteristic is the absence or presence of serifs: the Century typeface does not contain serifs while the Bookman typeface does.


Font Families

Windows organizes fonts by family; a family is a set of fonts having common stroke width and serif characteristics. Windows categorizes families with five family names. A sixth name ("Dontcare") allows an application to use the default font. The following table describes the font-family names.

Font-family name	Description

Decorative	Specifies a novelty font. An example is Old English.

Dontcare	Specifies a generic family name. This name is used when information about a font does not exist or does not matter.

Modern	Specifies a font that is fixed-pitch with or without serifs. Fixed-pitch fonts are usually modern; examples include Pica, Elite, and Courier New®.

Roman	Specifies a font that is variable pitch, with serifs. An example is Times New Roman.

Script	Specifies a font that is designed to look like handwriting; examples include Script and Cursive.

Swiss	Specifies a font that is fixed-pitch, without serifs. An example is Arial.

These family names correspond to constants found in the WINGDI.H file: FF_DECORATIVE, FF_DONTCARE, FF_MODERN, FF_ROMAN, FF_SCRIPT, and FF_SWISS. An application uses these constants when it creates a font, selects a font, or retrieves information about a font.

Fonts within a family are distinguished by size (10 point, 24 point, etc.) and style (regular, italic, etc.).


Raster, Vector, and TrueType Fonts

Windows-based applications can use three different kinds of font technologies to display and print text: raster, vector, and TrueType. The differences between these fonts reflect the way that the glyph for each character or symbol is stored in the respective font-resource file. In raster fonts, a glyph is a bitmap that Windows uses to draw a character or symbol in the font. In vector fonts, a glyph is a collection of line endpoints that define the line segments Windows uses to draw a character or symbol in the font. In TrueType fonts, a glyph is a collection of line and curve commands as well as a collection of hints. Windows uses the line and curve commands to define the outline of the bitmap for a character or symbol in the TrueType font. Windows uses the hints to adjust the length of the lines and shapes of the curves used to draw the character or symbol. These hints and the respective adjustments are based on the amount of scaling used to reduce or increase the size of the bitmap.

Because the bitmaps for each glyph in a raster font are designed for a specific resolution of device, raster fonts are generally considered to be device dependent. Vector fonts, on the other hand, are not device dependent, because each glyph is stored as a collection of scalable lines. However, vector fonts are generally drawn more slowly than raster or TrueType fonts. TrueType fonts provide both relatively fast drawing speed and true device independence. By using the hints associated with a glyph, a developer can scale the characters from a TrueType font up or down and still maintain their original shape.

As previously mentioned, the glyphs for a font are stored in a font-resource file. A font-resource file is actually a Windows library that contains only data--there is no code. For raster and vector fonts, this data is divided into two parts: a header describing the font's metrics and the glyph data. A font-resource file for a raster or vector font is identified by the .FON filename extension. For TrueType fonts, there are two files for each font: the first file contains a relatively short header and the second contains the actual font data. The first file is identified by a .FOT extension and the second is identified by a .TTF extension.


Character Sets Used by Fonts

All fonts use a character set. A character set contains punctuation marks, numerals, uppercase and lowercase letters, and all other printable characters. Each element of a character set is identified by a number.

Most character sets used in Windows are supersets of the U.S. ASCII character set, which defines characters for the 96 numeric values from 32 through 127. There are five major groups of character sets:

Windows

Unicode™

OEM (original equipment manufacturer)

Symbol

Vendor-specific

Windows Character Set

The Windows character set is the most commonly used character set in Windows programming. It is essentially equivalent to the ANSI character set. The blank character is the first character in the Windows character set. It has a hexadecimal value of 0x20 (decimal 32). The last character in the Windows character set has a hexadecimal value of 0xFF (decimal 255).

Many fonts specify a default character. Whenever a request is made for a character that is not in the font, Windows provides this default character. Many fonts using the Windows character set specify the period (.) as the default character. TrueType fonts typically use an open box as the default character.

Fonts use a break character called a quad to separate words and justify text. Most fonts using the Windows character set specify that the blank character will serve as the break character.

Windows version 3.1 added 24 characters to the Windows code page, as shown in the following table.

Character	Name	Windows character code

base line single quote	130

å	florin	131

„	base line double quote	132

…	ellipsis	133

†	dagger	134

‡	double dagger	135

ˆ	circumflex	136

‰	permille	137

Š	S Hacek	138

‹	left single guillemet	139

Œ	OE ligature	140

‘	left single quote	145

’	right single quote	146

“	left double quote	147

”	right double quote	148

•	bullet	149

–	en dash	150

—	em dash	151

˜	tilde	152

œ	trademark ligature	153

š	s Hacek	154

›	right single guillemet	155

œ	oe ligature	156

Ÿ	Y Dieresis	159

It should be noted that the characters for left and right single quote were first added to the character set for the release of Windows version 3.0.

Unicode Character Set

The Windows ANSI character uses 8 bits to represent each character; therefore, the maximum number of characters that can be expressed using 8 bits is 256 (2^ 8). This is usually sufficient for Western languages, including the diacritical marks used in French, German, Spanish, and other languages. However, Eastern languages employ thousands of separate characters, which cannot be encoded by using a single-byte coding scheme. With the proliferation of computer commerce, double-byte coding schemes were developed so that characters could be represented in 8-bit, 16-bit, 24-bit, or 32-bit sequences. This requires complicated passing algorithms; even so, using different code sets could yield entirely different results on two different computers.

To address the problem of multiple coding schemes, the Unicode standard for data representation was developed. A 16-bit character coding scheme, Unicode can represent 65,536 (2^ 16) characters, which is enough to include all languages in computer commerce today, as well as punctuation marks, mathematical symbols, and room for future expansion. Unicode establishes a unique code for every character to ensure that character translation is always accurate.

OEM Character Set

The OEM character set is typically used in full-screen MS-DOS® sessions for screen display. Characters 32 through 127 are usually the same in the OEM, U.S. ASCII, and Windows character sets. The other characters in the OEM character set (0 through 31 and 128 through 255) correspond to the characters that can be displayed in a full-screen MS-DOS session. These characters are generally different from the Windows characters.

Symbol Character Set

The Symbol character set contains special characters typically used to represent mathematical and scientific formulas.

Vendor-Specific Character Sets

Many printers and other output devices provide fonts based on character sets that differ from the Windows and OEM sets--for example, the Extended Binary Coded Decimal Interchange Code (EBCDIC) character set. To use one of these character sets, the printer driver translates from the Windows character set to the vendor-specific character set.


Font Installation and Deletion

A font must already be resident on a given device or installed in the Windows font table in order for an application to draw text using glyphs from that font. The Windows font table is an internal array that identifies all nondevice fonts that are available to a Windows-based application. An application can retrieve the names of fonts currently installed on a device and stored in the internal font table by calling the EnumFonts or ChooseFont function.

An application can install a font by calling the font installation function AddFontResource. The AddFontResource function loads a font that is stored in a font-resource file.

In the case of TrueType fonts, an additional step is sometimes necessary before the font can be installed in the font table. Some font manufacturers ship only the TrueType font-data files (identified by the .TTF extension). Before Windows can load these fonts, it requires a corresponding header file (identified by the .FOT extension). To create this header file, an application must call the CreateScalableFontResource function and pass the name of the font-data file as the third parameter. When this header file is created, an application can install the font by calling the AddFontResource function and passing the name of the new header file.

When an application finishes using an installed font, it must remove that font by calling the RemoveFontResource function.

Whenever an application calls the functions that add and delete font resources, it should also call the SendMessage function and send a WM_FONTCHANGE message to all top-level windows in the system. This message notifies other applications that the internal font table has been altered by an application that added or removed a font.


Font Creation and Selection

Previous versions of Windows required that the application developer provide source code and a dialog box template to support an interface that displayed the available fonts from which the user could choose. The new Font common dialog box simplifies the creation and selection process. By initializing the CHOOSEFONT structure and calling the ChooseFont function, an application can support the same font-selection interface that previously required many lines of code. The following illustration shows the dialog box displayed when an application calls the ChooseFont function.

Selection by the User

Most font creation and selection operations involve the user. For example, word processing applications let the user select unique fonts for headings, footnotes, and body text. After the user selects a font by using the Font dialog box and presses the OK button, the ChooseFont function initializes the members of a LOGFONT structure with the attributes of the requested font. To use this font for text-output operations, an application must first create a logical font and then select that font into its device context. A logical font is an application-supplied description of an ideal font. A developer can create a logical font by calling the CreateFont or the CreateFontIndirect functions. In this case, the application would call CreateFontIndirect and supply a pointer to the LOGFONT structure initialized by ChooseFont. In general, it is more efficient to call CreateFontIndirect because CreateFont requires 4 parameters while CreateFontIndirect requires only 1, a pointer to LOGFONT.

Before an application can actually begin drawing text with a logical font, it must find the closest match from the fonts stored internally on the device and the fonts whose resources have been loaded into the operating system. The fonts stored on the device or in the operating system are called physical fonts. The process of finding the physical font that most closely matches a specified logical font is referred to as font mapping. This process occurs when an application calls the SelectObject function and supplies a handle identifying a logical font. Font mapping is performed by using an internal algorithm that compares the attributes of the requested logical font against the attributes of available physical fonts. When the font mapper algorithm completes its search and determines the closest possible match, the SelectObject function returns and the application can begin drawing text with the new font.

The SetMapperFlags function specifies whether or not the font mapper algorithm searches only for physical fonts with aspect ratios that match the physical device. The aspect ratio for a device is the ratio formed by the width and the height of a pixel on that device.

Special Font Selection Considerations

Although most font selection operations involve the user, there are some instances where this is not true. For example, a developer may want to use a unique font in an application to draw text in a control window. To select an appropriate font, the application must be able to determine what fonts are available, create a logical font that describes one of these available fonts, and then select that font into the appropriate device context.

An application can enumerate the available fonts by using the EnumFontFamilies function. This can be useful when an application must determine which fonts are available from a given family. (The EnumFonts function is an obsolete version of the EnumFontFamilies function.)

Once an application has enumerated the available fonts and located an appropriate match, it should use the values returned by the font enumeration function to initialize the members of a LOGFONT structure and call the CreateFontIndirect function, passing a pointer to the initialized LOGFONT structure. If the CreateFontIndirect function is successful, the application can select the logical font by calling the SelectObject function.


Embedded Fonts

Embedding a font is the technique of bundling a document and the fonts it contains into a file for transmission to another computer. Embedding a font guarantees that a font specified in a transmitted file will be present on the computer receiving the file. Not all fonts can be moved from computer to computer, however, since most fonts are licensed to only one computer at a time. In Windows, only TrueType fonts can be embedded.

Applications should embed a font in a document only when requested by a user. An application cannot be distributed along with documents that contain embedded fonts, nor can an application itself contain an embedded font. Whenever an application distributes a font, in any format, the proprietary rights of the owner of the font must be acknowledged.

It may be a violation of a font vendor's proprietary rights and/or user license agreement to embed any fonts where embedding is not permitted or to fail to observe the following guidelines on embedding fonts. A font's license may give only read-write permission for a font to be installed and used on the destination computer; or it may give read-only permission. Read-only permission allows a document to be viewed and printed (but not modified) by the destination computer; documents with read-only embedded fonts are themselves read-only. Read-only embedded fonts may not be unbundled from the document and installed on the destination computer.

An application can determine the license status, and thus whether or not a font can be embedded in a document, by calling the GetOutlineTextMetrics function and examining 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.

To determine if a font can be embedded, an application can use the GetFontData function to read the font file. Setting the dwTable and dwOffset parameters of GetFontData to 0L and the cbData parameter to -1L ensures that the application reads the entire font file from the beginning.

After an application retrieves the font data, it can store the data with the document by using any applicable format. Most applications build a font directory in the document, listing the embedded fonts and whether the embedding is read-write or read-only. An application can use the otmpStyleName and otmFamilyName members of the OUTLINETEXTMETRIC structure to identify the font.

If the read-only bit is set for the embedded font, applications must encrypt the font data before storing it with the document. The encryption method need not be complicated; for example, using the XOR operator to combine the font data with an application-specified constant is adequate and fast.


About Text Output

Text output is the most common type of graphic output found within the client area of Windows-based applications. It is used by Windows-based applications in different ways. Word processing and desktop publishing applications create documents with formatted text; spreadsheet applications use text, numbers, and symbols to specify formulas, label columns, and list values; database applications create records and display queries with text, and CAD applications use text to label objects and display dimensions.

The Win32 application programming interface (API) provides a complete set of functions to format and draw text in an application's client area and on a page of printer paper. These functions can be divided into two categories: those that format the text (or prepare it for output) and those that actually draw the text. The formatting functions align text, set the intercharacter spacing, set the text and text-background colors, and justify text. The drawing functions draw individual characters (or symbols) or entire strings of text.


Formatting Text

The formatting functions can be divided into three categories: those that retrieve or set the text-formatting attributes for a device context, those that retrieve character widths, and those that retrieve string widths and heights.

Text-Formatting Attributes

An application can use six functions to set the text-formatting attributes for a device context: SetBKColor, SetBKMode, SetTextAlign, SetTextCharacterExtra, SetTextColor, and SetTextJustification. These functions affect the text alignment, the intercharacter spacing, the text justification, and text and background colors. In addition to these six functions, six other functions can be used to retrieve the current text formatting attributes for any device context: GetBkColor, GetBkMode, GetTextAlign, GetTextCharacterExtra, GetTextColor, and GetTextExtentPoint.

Text Alignment

Applications can use the SetTextAlign function to specify how Windows should position the characters in a string of text when they call one of the drawing functions. This function can be used to position headings, page numbers, callouts, and so on. Windows positions a string of text by aligning a reference point on an imaginary rectangle that surrounds the string, with the current cursor position or with a point passed as an argument to one of the text drawing functions. The SetTextAlign function lets the application specify the location of this reference point. The list below identifies the possible reference point locations.

Location	Description

left/bottom	The reference point is located at the bottom-left corner of the rectangle.

left/base line	The reference point is located at the intersection of the character-cell base line and the left edge of the rectangle.

left/top	The reference point is located at the top-left corner of the rectangle.

center/bottom	The reference point is located at the center of the bottom of the rectangle.

center/base line	The reference point is located at the intersection of the character-cell base line and the center of the rectangle.

center/top	The reference point is located at the center of the top of the rectangle.

right/bottom	The reference point is located at the bottom-right corner of the rectangle.

right/base line	The reference point is located at the intersection of the character-cell base line and the right edge of the rectangle.

right/top	The reference point is located at the top-right corner of the rectangle.

(For a description of the character-cell base line, see About Fonts.)

The following illustration shows a string of text drawn by calling the TextOut function. Before drawing the text, the SetTextAlign function was called to relocate the reference point at each one of the nine possible locations.

The default text alignment for a device context is the upper left corner of the imaginary rectangle that surrounds the text. An application can retrieve the current text alignment setting for any device context by calling the GetTextAlign function.

Intercharacter Spacing

Applications can use the SetTextCharacterExtra function to alter the intercharacter spacing for all text output operations in a given device context. The following illustration shows a string of text drawn twice by calling the TextOut function. Before drawing the text the second time, the SetTextCharacterExtra function was called to increment the intercharacter spacing.

The default intercharacter spacing value for any device context is zero. An application can retrieve the current intercharacter spacing value for a device context by calling the GetTextCharacterExtra function.

Text Justification

Applications can use the GetTextExtentPoint and SetTextJustification functions to justify a line of text. Text justification is a common operation in any desktop publishing and in most word processing applications. The GetTextExtentPoint function computes the width and height of a string of text. After the width is computed, the application can call the SetTextJustification function to distribute extra spacing between each of the words in a line of text. The following illustration shows a paragraph of text printed twice: in the first paragraph, the text was not justified; in the second paragraph, the text was justified by calling the GetTextExtentPoint and SetTextJustification functions.

Text and Background Color

Applications can use the SetTextColor function to set the color of text drawn in the client-area of their windows, as well as the color of text drawn on a color printer. An application can use the SetBkColor function to set the color that appears behind each character and the SetBkMode function to specify how Windows should blend the selected background color with the current color(s) on the video display.

The default text color for a display device context is black; the default background color is white; and the default background mode is opaque. An application can retrieve the current text color for a device context by calling the GetTextColor function. An application can retrieve the current background color for a device context by calling the GetBkColor function and the current background mode by calling the GetBkMode function.

Character Widths

Applications need to retrieve character-width data when they fit strings of text to page or column widths as they prepare to alter the appearance of a string of text, and so forth. There are four functions that an application can use to retrieve character-width data. Two of these functions retrieve the character-advance width and two of these functions retrieve actual character-width data.

An application can use the GetCharWidth and GetCharWidthFloat functions to retrieve the advance width for individual characters or symbols in a string of text. The advance width is the distance that the cursor on a video display or the print-head on a printer must advance before printing the next character in a string of text. The GetCharWidth function returns the advance width as an integer value. If greater precision is required, an application can use the GetCharWidthFloat function to retrieve fractional advance-width values.

An application can retrieve actual character-width data by using the GetCharABCWidths and GetCharABCWidthsFloat functions. To retrieve character widths for characters in a string of text that will be printed using a TrueType font, an application can call the GetCharABCWidths function; however, for any other font, the application should call the GetCharABCWidthsFloat function. (For more information about TrueType fonts, see About Fonts). The following illustration shows the three components of the ABC width:

The "A" spacing is the width to add to the current position before placing the character. The "B" spacing is the width of the character itself. The "C" spacing is the white space to the right of the character. The total advance width is determined by calculating the sum of A+B+C. The character cell is an imaginary rectangle that surrounds each character or symbol in a Windows font. Because characters can overhang or underhang the character cell, either or both of the A and C increments can be a negative number.

String Widths and Heights

In addition to retrieving character-width data for individual characters, applications also need to compute the width and height of entire strings. Two functions retrieve string-width and height measurements: GetTextExtentPoint, and GetTabbedTextExtent. If the string does not contain tab characters, an application can use the GetTextExtentPoint function to retrieve the width and height of a specified string. If the string contains tab characters, an application should call the GetTabbedTextExtent function.

Windows also supports a special function that applications can use for word-wrapping operations called GetTextExtentExPoint. This function returns the number of characters from a specified string that fit within a given space.

Font Ascenders and Descenders

Some applications determine the line spacing between text lines of different sizes by using a font's maximum ascender and descender. An application can retrieve these values by calling the GetTextMetrics function and then checking the tmAscent and tmDescent members of the TEXTMETRIC or NEWTEXTMETRIC structure. (The TEXTMETRIC structure is returned for raster fonts; the NEWTEXTMETRIC structure is returned for TrueType fonts).

The maximum ascent and descent are different from the typographic ascent and descent; in TrueType fonts, the typographic ascent and descent are typically the top of the "f" glyph and bottom of the "g" glyph. An application can retrieve the typographic ascender and descender for a TrueType font by calling the GetOutlineTextMetrics function and checking the values in the otmMacAscent and otmMacDescent members of the OUTLINETEXTMETRIC structure. It is important to note that TrueType font metrics do not correspond exactly to the metrics for Windows raster fonts, because TrueType font metrics have been designed by Apple Computer, Inc. for consistency across a variety of display and output devices.

The following figure shows the difference between the vertical text metric values returned in the NEWTEXTMETRIC and OUTLINETEXTMETRIC structures. (The names beginning with otm are members of the OUTLINETEXTMETRIC structure.)

Font Dimensions

An application can retrieve the physical dimensions of a TrueType font by calling the GetOutlineTextMetrics function. An application can retrieve the physical dimensions of any other font by calling the GetTextMetrics function. To determine the dimensions of an output device, an application can call the GetDeviceCaps function. GetDeviceCaps returns both physical and logical dimensions.

A logical inch is a measure Windows uses to present legible fonts on the screen and is approximately 30 to 40 percent larger than a physical inch. The use of logical inches precludes an exact match between the output of the screen and printer. Developers should be aware that the text on a screen is not simply a scaled version of the text that will appear on the page, particularly if graphics are incorporated into the text.


Drawing Text

After an application selects the appropriate font, sets the required text-formatting options, and computes the necessary character width and height values for a string of text, it can begin drawing characters and symbols by calling any of the four text-output functions. Two of these functions, DrawText and TabbedTextOut, are part of Window Manager and found in the library USER.DLL; the remaining two functions are part of GDI and found in the library GDI.DLL. When an application calls one of these functions, the operating system passes the call to the graphics engine, which in turn passes the call to the appropriate device driver. At the device driver level, all of these calls are supported by one or more calls to the driver's own ExtTextOut or TextOut function. An application will achieve the fastest execution by calling the ExtTextOut function, which is quickly converted into an ExtTextOut call for the device. However, there are instances when an application should call one of the other three functions; for example, to draw multiple lines of text within the borders of a specified rectangular region, it is more efficient to call the DrawText function. To create a multicolumn table with justified columns of text, it is more efficient to call the TabbedTextOut function.


Using the Font and Text-Output Functions

This section describes how you can use the font and text-output functions to draw normal text, draw text from different fonts on the same line, rotate lines of text, display the font-selection common dialog-box, enumerate fonts, and so on.


Using a Stock Font to Draw Text

Windows provides six stock fonts. A stock font is a logical font that an application can obtain by calling the GetStockObject function and passing a value that identifies the requested font. The following list contains the six values that you can specify to obtain a stock font.

Value	Meaning

ANSI_FIXED_FONT	Specifies a fixed-pitch font based on the Windows character set. A Courier font is typically used.

ANSI_VAR_FONT	Specifies a variable-pitch font based on the Windows character set. MS Sans Serif is typically used.

DEVICE_DEFAULT_FONT	Specifies the preferred font for the given device. This is typically the System font for display devices; however, for some dot-matrix printers this is a font that is resident on the device. (Printing with this font is usually faster than printing with a downloaded, bitmapped font).

OEM_FIXED_FONT	Specifies a fixed-pitch font based on an OEM character set. For IBM® computers and compatibles, the OEM font is based on the IBM PC character set.

SYSTEM_FONT	Specifies the System font. This is a variable-pitch font based on the Windows character set, and is used by the operating system to display window titles, menu names, and text in dialog boxes. The System font is always available. Other fonts are available only if they have been installed.

SYSTEM_FIXED_FONT	Specifies a fixed-pitch font compatible with the System font in Windows versions earlier than 3.0.

The following example retrieves a handle of the Windows variable stock font, selects it into a device context, and then writes a string using that font:

HFONT hfnt, hOldFont;

    hfnt = GetStockObject(ANSI_VAR_FONT);

    if (hOldFont = SelectObject(hdc, hfnt)) {

        TextOut(hdc, 10, 50, "Sample ANSI_VAR_FONT text.", 26);

        SelectObject(hdc, hOldFont);

    }

If other stock fonts are not available, GetStockObject returns a handle to the System font (SYSTEM_FONT). You should use stock fonts only if the mapping mode for your application's device context is MM_TEXT.


Creating a Logical Font

You can use the Font common dialog box to display available fonts. The ChooseFont dialog box is displayed after an application initializes the members of a CHOOSEFONT structure and calls the ChooseFont function. After the user chooses one of the available fonts and presses the OK button, the ChooseFont function initializes a LOGFONT structure with the relevant data. Your application can then call the CreateLogFont function and create a logical font based on the user's request. The following example demonstrates how this is done.

HFONT FAR PASCAL MyCreateFont( void )

{

CHOOSEFONT cf;

LOGFONT lf;

HFONT hfont;

    /* Initialize members of the CHOOSEFONT structure. */

    cf.lStructSize = sizeof(CHOOSEFONT);

    cf.hwndOwner = (HWND)NULL;

    cf.hDC = (HDC)NULL;

    cf.lpLogFont = &lf;

    cf.iPointSize = 0;

    cf.Flags = CF_SCREENFONTS;

    cf.rgbColors = RGB(0,0,0);

    cf.lCustData = 0L;

    cf.lpfnHook = (LPCFHOOKPROC)NULL;

    cf.lpTemplateName = (LPSTR)NULL;

    cf.hInstance = (HINSTANCE) NULL;

    cf.lpszStyle = (LPSTR)NULL;

    cf.nFontType = SCREEN_FONTTYPE;

    cf.nSizeMin = 0;

    cf.nSizeMax = 0;

    /* Display the CHOOSEFONT common-dialog box. */

    ChooseFont(&cf);

    /* Create a logical font based on the user's   */

    /* selection and return a handle identifying   */

    /* that font. */

    hfont = CreateFontIndirect(cf.lpLogFont);

    return (hfont);

}


Enumerating the Installed Fonts

In some instances, an application must be able to enumerate the available fonts and select the one most appropriate for a particular operation. An application can enumerate the available fonts by calling the EnumFonts or EnumFontFamilies function. These functions send information about the available fonts to a callback function that the application supplies. The callback function receives information in LOGFONT and NEWTEXTMETRIC structures. (The NEWTEXTMETRIC structure contains information about a TrueType font. When the callback function receives information about a non-TrueType font, the information is contained in a TEXTMETRIC structure.) By using this information, an application can limit the user's choices to only those fonts that are available.

The EnumFontFamilies function is similar to the EnumFonts function but includes some extra functionality. EnumFontFamilies allows an application to take advantage of styles available with TrueType fonts. New and upgraded applications should use EnumFontFamilies instead of EnumFonts.

In previous versions of Windows, the only style attributes were weight and italic; any other styles were specified in the family name for the font. For example, when an application used the EnumFonts function to query the available Courier fonts, EnumFonts might return information for Courier, Courier Bold, Courier Bold Italic, and Courier Italic. It would not return information about any other Courier fonts that might be installed, because any other Courier fonts would typically have a different family name.

TrueType fonts are organized around a family name (for example, Courier New) and style names (for example, italic, bold, and extra-bold). The EnumFontFamilies function enumerates all the styles associated with a given family name, not simply the bold and italic attributes; when the system includes a TrueType font called Courier New Extra-Bold, EnumFontFamilies lists it with the other Courier New fonts. The capabilities of EnumFontFamilies are helpful for fonts with many or unusual styles and for fonts that cross international borders.

If an application does not supply a typeface name, the EnumFonts and EnumFontFamilies functions supply information about one font in each available family. To enumerate all the fonts in a device context, the application can specify NULL for the typeface name, compile a list of the available typefaces, and then list each font in each typeface.

The following example uses the EnumFontFamilies function to retrieve the number of available raster, vector, and TrueType font families.

    UINT uAlignPrev;

    int aFontCount[] = { 0, 0, 0 };

    char szCount[8];

    EnumFontFamilies(hdc, (LPCTSTR) NULL,

        (FONTENUMPROC) EnumFamCallBack, (LPARAM) aFontCount);

    uAlignPrev = SetTextAlign(hdc, TA_UPDATECP);

    MoveToEx(hdc, 10, 50, (LPPOINT)NULL);

    TextOut(hdc, 0, 0, "Number of raster fonts: ", 24);

    itoa(aFontCount[0], szCount, 10);

    TextOut(hdc, 0, 0, szCount, strlen(szCount));

    MoveToEx(hdc, 10, 75, (LPPOINT)NULL);

    TextOut(hdc, 0, 0, "Number of vector fonts: ", 24);

    itoa(aFontCount[1], szCount, 10);

    TextOut(hdc, 0, 0, szCount, strlen(szCount));

    MoveToEx(hdc, 10, 100, (LPPOINT)NULL);

    TextOut(hdc, 0, 0, "Number of TrueType fonts: ", 26);

    itoa(aFontCount[2], szCount, 10);

    TextOut(hdc, 0, 0, szCount, strlen(szCount));

    SetTextAlign(hdc, uAlignPrev);

        .

        .

        .

BOOL FAR PASCAL EnumFamCallBack(lplf, lpntm, FontType, aFontCount)

LPLOGFONT lplf;

LPNEWTEXTMETRIC lpntm;

DWORD FontType;

LPVOID aFontCount;

{

    int far * aiFontCount = (int far *) aFontCount;

    /*

     * Record the number of raster, TrueType, and vector

     * fonts in the font-count array.

     */

    if (FontType & RASTER_FONTTYPE)

        aiFontCount[0]++;

    else if (FontType & TRUETYPE_FONTTYPE)

        aiFontCount[2]++;

    else

        aiFontCount[1]++;

    if (aiFontCount[0] || aiFontCount[1] || aiFontCount[2])

        return TRUE;

    else

        return FALSE;

    UNREFERENCED_PARAMETER( lplf );

    UNREFERENCED_PARAMETER( lpntm );

}

This example uses two masks, RASTER_FONTTYPE and TRUETYPE_FONTTYPE, to determine the type of font being enumerated. 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. A third mask, DEVICE_FONTTYPE, is set when a device (for example, a laser printer) supports downloading TrueType fonts; it is zero if the device is a display adapter, dot-matrix printer, or other raster device. An application can also use the DEVICE_FONTTYPE mask to distinguish GDI-supplied raster fonts from device-supplied fonts. Windows can simulate bold, italic, underline, and strikeout attributes for GDI-supplied raster fonts, but not for device-supplied fonts.

An application can also check bits 1 and 2 in the tmPitchAndFamily member of the NEWTEXTMETRIC structure to identify a TrueType font. If bit 1 is 0 and bit 2 is 1, the font is a TrueType font.

Vector fonts are categorized as OEM_CHARSET instead of ANSI_CHARSET. Some applications identify vector fonts by using this information, checking the tmCharSet member of the NEWTEXTMETRIC structure. This categorization usually prevents the font mapper from choosing vector fonts unless they are specifically requested. (Most applications no longer use vector fonts, because their strokes are single lines and they take longer to draw than TrueType fonts, which offer many of the same scaling and rotation features that required vector fonts in earlier versions of Windows.)


Checking the Text Capabilities of a Device

You can use the EnumFonts and EnumFontFamilies functions to enumerate the fonts that are available in a printer-compatible memory device context. You can also use the GetDeviceCaps function to retrieve information about the text capabilities of a device. By calling the GetDeviceCaps function with the NUMFONTS index, you can determine the minimum number of fonts supported by a printer. (An individual printer may support more fonts than specified in the return value from GetDeviceCaps with the NUMFONTS index.) By using the TEXTCAPS index, you can identify many of the text capabilities of the specified device.


Setting the Text Alignment

You can query and set the text alignment for a device context by using the GetTextAlign and SetTextAlign functions. The text-alignment settings determine how text is positioned relative to a given location. Text can be aligned to the right or left of the position or centered over it; it can also be aligned above or below the point.

The following example shows a method for determining which horizontal alignment flag is set:

switch ((TA_LEFT | TA_RIGHT | TA_CENTER) & GetTextAlign(hdc))

{

case TA_LEFT:

   .

   .

   .

case TA_RIGHT:

   .

   .

   .

case TA_CENTER:

   .

   .

   .

}

You can also use the SetTextAlign function to update the current position when a text-output function is called. For instance, the following example uses the SetTextAlign function to update the current position when the TextOut function is called. In this example, the cArial parameter is an integer that specifies the number of Arial fonts.

UINT uAlignPrev;

char szCount[8];

uAlignPrev = SetTextAlign(hdc, TA_UPDATECP);

MoveToEx(hdc, 10, 50, (LPPOINT) NULL);

TextOut(hdc, 0, 0, "Number of Arial fonts: ", 23);

itoa(cArial, szCount, 10);

TextOut(hdc, 0, 0, (LPSTR) szCount, strlen(szCount));

SetTextAlign(hdc, uAlignPrev);


Drawing Text From Different Fonts on the Same Line

Different type styles within a font family can have different widths. For example, bold and italic styles of a family are always wider than the roman style for a given point size. When you display or print several type styles on a single line, you must keep track of the width of the line to avoid having characters displayed or printed on top of one another.

You can use two functions to retrieve the width (or extent) of text in the current font. 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 a specified array of tab-stop positions. The GetTextExtent function computes the width and height of a line of text.

When necessary, Windows synthesizes a font by changing the character bitmaps. To synthesize a character in a bold font, Windows draws the character twice: once at the starting point, and again one pixel to the right of the starting point. To synthesize a character in an italic font, Windows draws two rows of pixels at the bottom of the character cell, moves the starting point one pixel to the right, draws the next two rows, and continues until the character has been drawn. By shifting pixels, each character appears to be sheared to the right. The amount of shear is a function of the height of the character.

One way to write a line of text that contains multiple fonts is to use the GetTextExtent function after each call to TextOut and add the length to a current position. The following example writes the line "This is a sample string." using bold characters for "This is a", switches to italic characters for "sample", then returns to bold characters for "string." After printing all the strings, it restores the system default characters.

int XIncrement;

int YStart;

TEXTMETRIC tm;

HFONT hfntDefault, hfntItalic, hfntBold;

SIZE sz;

LPSTR lpszString1 = "This is a ";

LPSTR lpszString2 = "sample ";

LPSTR lpszString3 = "string.";

/* Create a bold and an italic logical font. */

hfntItalic = MyCreateFont();

hfntBold = MyCreateFont();

/* Select the bold font and draw the first string         */

/* beginning at the specified point (XIncrement, YStart). */

XIncrement = 10;

YStart = 50;

hfntDefault = SelectObject(hdc, hfntBold);

TextOut(hdc, XIncrement, YStart, lpszString1,

        lstrlen(lpszString1));

/*

 * Compute the length of the first string and add

 * this value to the x-increment that is used for the

 * text-output operation.

 */

GetTextExtentPoint(hdc, lpszString1,

                   lstrlen(lpszString1), &sz);

XIncrement += sz.cx;

/*

 * Retrieve the overhang value from the TEXTMETRIC

 * structure and subtract it from the x-increment.

 * (This is only necessary for non-TrueType raster

 * fonts.)

 */

GetTextMetrics(hdc, &tm);

XIncrement -= tm.tmOverhang;

/*

 * Select an italic font and draw the second string

 * beginning at the point (XIncrement, YStart).

 */

hfntBold = SelectObject(hdc, hfntItalic);

GetTextMetrics(hdc, &tm);

XIncrement -= tm.tmOverhang;

TextOut(hdc, XIncrement, YStart, lpszString2,

        lstrlen(lpszString2));

/*

 * Compute the length of the second string and add

 * this value to the x-increment that is used for the

 * text-output operation.

 */

GetTextExtentPoint(hdc, lpszString2, lstrlen(lpszString2), &sz);

XIncrement += sz.cx;

/*

 * Re-select the bold font and draw the third string

 * beginning at the point (XIncrement, YStart).

 */

SelectObject(hdc, hfntBold);

TextOut(hdc, XIncrement - tm.tmOverhang, YStart, lpszString3,

            lstrlen(lpszString3));

/* Re-select the original font. */

SelectObject(hdc, hfntDefault);

/* Delete the bold and italic fonts. */

DeleteObject(hfntItalic);

DeleteObject(hfntBold);

In this example, the GetTextExtentPoint function initializes the members of a SIZE structure with the length and height of the specified string. The GetTextMetrics function retrieves the overhang for the current font. Because the overhang is zero if the font is a TrueType font, the overhang value does not change the string placement. For raster fonts, however, it is important to use the overhang value.

The overhang is subtracted from the bold string once, to bring subsequent characters closer to the end of the string if the font is a raster font. Because overhang affects both the beginning and end of the italic string in a raster font, the glyphs start at the right of the specified location and end at the left of the endpoint of the last character cell. (The GetTextExtent function retrieves the extent of the character cells, not the extent of the glyphs.) To account for the overhang in the raster italic string, the example subtracts the overhang before placing the string and subtracts it again before placing subsequent characters.

The SetTextJustification function adds extra space to the break characters in a line of text. You can use the GetTextExtent function to determine the extent of a string, then subtract that extent from the total amount of space the line should occupy, and use the SetTextJustification function to distribute the extra space among the break characters in the string. The SetTextCharacterExtra function adds extra space to every character cell in the selected font, including the break character. (You can use the GetTextCharacterExtra function to determine the current amount of extra space being added to the character cells; the default setting is zero.)

You can place characters with greater precision by using the GetCharWidth or GetCharABCWidths function to retrieve the widths of individual characters in a font. The GetCharABCWidths function is more accurate than the GetCharWidth function, but only when it is used with TrueType fonts; when you use GetCharABCWidths with non-TrueType fonts, it retrieves the same information as GetCharWidth.

ABC spacing also allows an application to perform very accurate text alignment. For example, when the application right aligns a raster roman font without using ABC spacing, the advance width is calculated as the character width. This means the white space to the right of the glyph in the bitmap is aligned, not the glyph itself. By using ABC widths, applications have more flexibility in the placement and removal of white space when aligning text, because they have information that allows them to finely control intercharacter spacing.


Rotating Lines of Text

You can rotate TrueType fonts at any angle. This is useful for labeling charts and other illustrations. The following example rotates a string in 10-degree increments around the center of the client area by changing the value of the lfEscapement and lfOrientation members of the LOGFONT structure used to create the font.

RECT rc;

int angle;

HFONT hfnt, hfntPrev;

LPSTR lpszRotate = "String to be rotated.";

/* Allocate memory for a LOGFONT structure. */

PLOGFONT plf = (PLOGFONT) LocalAlloc(LPTR, sizeof(LOGFONT));

/* Specify a font typeface name and weight. */

lstrcpy(plf->lfFaceName, "Arial");

plf->lfWeight = FW_NORMAL;

/* Retrieve the client-rectangle dimensions. */

GetClientRect(hwnd, &rc);

/*

 * Set the background mode to transparent for the

 * text-output operation.

 */

SetBkMode(hdc, TRANSPARENT);

/*

 * Draw the string 36 times, rotating 10 degrees

 * counter-clockwise each time.

 */

for (angle = 0; angle < 3600; angle += 100) {

    plf->lfEscapement = angle;

    hfnt = CreateFontIndirect(plf);

    hfntPrev = SelectObject(hdc, hfnt);

    TextOut(hdc, rc.right / 2, rc.bottom / 2,

        lpszRotate, lstrlen(lpszRotate));

    SelectObject(hdc, hfntPrev);

    DeleteObject(hfnt);

}

/* Reset the background mode to its default. */

SetBkMode(hdc, OPAQUE);

/* Free the memory allocated for the LOGFONT structure. */

LocalFree((LOCALHANDLE) plf);


Retrieving Character Outlines

You can use the GetGlyphOutline function to retrieve the outline of a glyph from a TrueType font. The glyph outline returned by the GetGlyphOutline function is for a grid-fitted glyph. (A grid-fitted glyph has been modified so that its bitmap image conforms as closely as possible to the original design of the glyph.) If your application requires an unmodified glyph outline, request the glyph outline for a character in a font whose size is equal to the font's em units. (To create a font with this size, set the lfHeight member of the LOGFONT structure to the negative of the value of the ntmSizeEM member of the NEWTEXTMETRIC structure.)

GetGlyphOutline returns the outline as a bitmap or as a series of polylines and splines. When an application retrieves a glyph outline as a series of polylines and splines, the information is returned in a TTPOLYGONHEADER structure followed by as many TTPOLYCURVE structures as 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 where the outline for a contour begins. The TTPOLYCURVE structures that follow can be either polyline records or spline records.

To render a TrueType character outline in Windows, you must use both the polyline and the spline records. Windows can render both polylines and splines easily. Each polyline and spline record contains as many sequential points as possible, to minimize the number of records returned.

The starting point given in the TTPOLYGONHEADER structure is always on the outline of the glyph. The specified point serves as both the starting and ending points for the contour.

Polyline Records

Polyline records are a series of points; lines drawn between the points describe the outline of the character. A polyline record begins with the last point in the previous record (or, for the first record in the contour, the starting point). Each point in the record is on the glyph outline and can be connected simply by using straight lines.

Spline Records

Spline records represent the quadratic curves (that is, quadratic b-splines) used by TrueType. A spline record begins with the last point in the previous record (or for the first record in the contour, with the starting point). For the first spline record, the starting point and the last point in the record are on the glyph outline. For all other spline records, only the last point is on the glyph outline. All other points in the spline records are off the glyph outline and must be rendered as the control points of b-splines.

The last spline or polyline record in a contour always ends with the contour's starting point. This arrangement ensures that every contour is closed.

Because b-splines require three points (one point off the glyph outline between two points that are on the outline), you must perform some calculations when a spline record contains more than one off-curve point.

For example, if a spline record contains three points (A, B, and C) and it is not the first record, points A and B are off the glyph outline. To interpret point A, use the current position (which is always on the glyph outline) and the point on the glyph outline between points A and B. To find the midpoint (M) between A and B, you can perform the following calculation.

M = A + (B - A)/2

The midpoint between consecutive off-outline points in a spline record is a point on the glyph outline, according to the definition of the spline format used in TrueType fonts.

If the current position is designated by P, the two quadratic splines defined by this spline record are (P, A, M) and (M, B, C).


Using Portable TrueType Metrics

Applications that use the TrueType text metrics can achieve a high degree of printer and document portability; even applications that must maintain compatibility with earlier versions of Windows can use the TrueType metrics.

Design widths overcome most of the problems of device-dependent text introduced by physical devices. Design widths are a kind of logical width. Independent of any rasterization problems or scaling transformations, each glyph has a logical width and height. Composed to a logical page, each character in a string has a place that is independent of the physical device widths. Although a logical width implies that widths can be scaled linearly at all point sizes, this is not necessarily true for either nonportable or most TrueType fonts. At smaller point sizes, some glyphs are made wider relative to their height for better readability.

The characters in TrueType core fonts are designed against a 2048 by 2048 grid. The design width is the width of a character in these grid units. (TrueType supports any integer grid size up to 16,384 by 16,384; grid sizes that are integer powers of 2 scale faster than other grid sizes.)

The font outline is designed in notional units. The em square is the notional grid against which the font outline is fitted. (You can use the otmEMSquare member of OUTLINETEXTMETRIC and the ntmSizeEM member of NEWTEXTMETRIC to retrieve the size of the em square in notional units.) When a font is created that has a point size (in device units) equal to the size of its em square, the ABC widths for this font are the desired design widths. For example, assume the size of an em square is 1000 and the ABC widths of a character in the font are 150, 400, and 150. A character in this font that is 10 device units high would have ABC widths of 1.5, 4, and 1.5, respectively. Since the MM_TEXT mapping mode is most commonly used with fonts (and MM_TEXT is equivalent to device units), this is a simple calculation.

Because of the high resolution of TrueType design widths, applications that use them must take into account the large numeric values that can be created.

Device vs. Design Units

An application can retrieve font metrics for a physical font only after the font has been selected into a device context. When a font is selected into a device context, it is scaled for the device. The font metrics specific to the device are known as device units.

Portable metrics in fonts are known as design units. To apply to a given device, design units must be converted to device units. Use the following formula to convert design units to device units.

DeviceUnits = (DesignUnits/unitsPerEm) * (PointSize/72) * DeviceResolution

The variables in this formula have the following meanings.

Variable	Description

DeviceUnits	Specifies the DesignUnits font metric converted to device units. This value is in the same units as the value given for DeviceResolution.

DesignUnits	Specifies the font metric to be converted to device units. This value can be any font metric, including the width of a character or the ascender value for an entire font.

unitsPerEm	Specifies the em square size for the font.

PointSize	Specifies size of the font, in points. (One point equals 1/72 of an inch.)

DeviceResolution	Specifies number of device units (pixels) per inch. Typical values might be 300 for a laser printer or 96 for a VGA screen.

This formula should not be used to convert device units back to design units. Device units are always rounded to the nearest pixel. The propagated round-off error can become very large, especially when an application is working with screen sizes.

To request design units, you should create a logical font whose height is specified as -unitsPerEm. Your applications can retrieve the value for unitsPerEm by calling the EnumFontFamilies function and checking the ntmSizeEM member of the NEWTEXTMETRIC structure.

Metrics for Portable Documents

The following table specifies the most important font metrics for applications that require portable documents and the functions that allow an application to retrieve them.

Function	Metric	Use

EnumFontFamilies	ntmSizeEM	Retrieval of design metrics; conversion to device metrics

GetCharABCWidths	ABCWidths	Accurate placement of characters at the start and end of margins, picture boundaries, and other text breaks

GetCharWidth	AdvanceWidths	Placement of characters on a line

GetOutlineTextMetrics	otmfsType	Font-embedding bits

otmsCharSlopeRise	Y-component for slope of cursor for italic fonts

otmsCharSlopeRun	X-component for slope of cursor for italic fonts

otmAscent	Line spacing

otmDescent	Line spacing

otmLineGap	Line spacing

otmpFamilyName	Font identification

otmpStyleName	Font identification

otmpFullName	Font identification (typically, family and style name)

The otmsCharSlopeRise, otmsCharSlopeRun, otmAscent, otmDescent, and otmLineGap members of the OUTLINETEXTMETRIC structure are scaled or transformed to correspond to the current device mode and physical height (as given in the tmHeight member of the NEWTEXTMETRIC structure).

Font identification is important in those instances when an application must select the same font--for example, when a document is reopened or moved to a different operating system. The font mapper always selects the correct font when an application requests a font by full name. The family and style names provide input to the standard font dialog box, which ensures that the selection bars are properly placed.

The otmsCharSlopeRise and otmsCharSlopeRun values are used to produce a close approximation of the main italic angle of the font. For typical roman fonts, otmsCharSlopeRise is 1 and otmsCharSlopeRun is 0. For italic fonts, the values attempt to approximate the sine and cosine of the main italic angle of the font (in counterclockwise degrees past vertical); note that the italic angle for upright fonts is 0. Because these values are not expressed in design units, they should not be converted into device units.

The character placement and line spacing metrics enable an application to compute device-independent line breaks that are portable across screens, printers, typesetters, and even platforms.

Device-independent page layout requires the following seven basic steps:

1	Normalize all design metrics to a common ultra-high resolution (UHR) value (for example, 65,536 DPI); this prevents round-off errors.

2	Compute line breaks based on UHR metrics and physical page width; this yields a starting point and an ending point of a line within the text stream.

3	Compute the device page width in device units (for example, pixels).

4	Fit each line of text into the device page width, using the line breaks computed in step 2.

5	Compute page breaks by using UHR metrics and the physical page length; this yields the number of lines per page.

6	Compute the line heights in device units.

7	Fit the lines of text onto the page, using the lines per page from step 5 and the line heights from step 6.

If all applications adopt these techniques, developers can virtually guarantee that documents moved from one application to another will retain their original appearance and format.


Using PANOSE Numbers

TrueType font files include PANOSE numbers, which applications can use to choose a font that closely matches their specifications. The PANOSE system classifies faces by 10 different attributes. For more information about these attributes, see the PANOSE structure. A PANOSE structure is part of the OUTLINETEXTMETRIC structure (whose values are filled in by calling the GetOutlineTextMetrics function).

The PANOSE attributes are rated individually on a scale. The resulting values are concatenated to produce a number. Given this number for a font and a mathematical metric to measure distances in the PANOSE space, an application can determine the nearest neighbors.


Creating Customized Fonts

Windows keeps a operating system font table containing all the fonts that applications can use. Windows chooses a font from this table when an application calls the CreateFont or CreateFontIndirect function. There can be up to 253 entries in the table.

A font resource is a group of individual fonts representing characters in a given character set that have various combinations of heights, widths, and pitches. You can load font resources and add the fonts in each resource to the operating system font table by using the AddFontResource function. To remove a font resource from the font table, you can use the RemoveFontResource function.

After you add a font resource to the operating system font table, you can use the individual fonts in the resource. In other words, the CreateFont function takes the fonts into account when it tries to match a physical font to the specified logical font. (Fonts in the table are never directly accessible to an application. They are available only through the CreateFontIndirect and CreateFont functions, which return the handles of the fonts, not their memory addresses.)

Whenever your application adds or removes a font resource, it should inform all other applications of the change by sending a WM_FONTCHANGE message to them. Use the following call to the SendMessage function to send the message to all windows.

SendMessage(HWND_BROADCAST, WM_FONTCHANGE, 0, 0);

You can use the GetProfileString function to search the [Fonts] section of the WIN.INI file for the list of fonts that the user has used Control Panel to install.

Creating Font Resources

A font resource file is an empty Windows dynamic-link library; it contains no code or data, but it does contain resources. You can create font resources by creating font files and adding them as resources to a font resource file. To create a font resource file, your application should follow these steps:

1	Create the font files.

2	Create a resource-definition file for the font.

3	Create a dummy code module.

4	Create a module-definition file that describes the fonts and the devices that use the fonts.

5	Compile and link the source files.

You can add a font file to an empty library, along with such resources as icons, cursors, and menus, by using resource compiler.

Note:	A complete explanation of how to create a font resource file is beyond the scope of this book. For more information on this topic, see the documentation provided with your application development tools.

Installing and Using an Embedded Font

You must separate an embedded font from the containing document and install it in the user's operating system before Windows can use it. Although the exact procedure for separating the font from the document depends on the method used to embed it, your application should always perform these steps:

1	Resolve name conflicts before installing the font.

2	Write the font data to a file, decoding read-only fonts as necessary.

3	Use the CreateScalableFontResource function to create a font resource file for the unembedded font.

Only a TrueType font can be embedded in Windows.

Your application should avoid installing a font with the same name as a font that is already on the system. To determine whether there are duplicate style names, an application can compare the information returned by EnumFontFamilies against the family name and style name stored with the embedded font.

Read-Write Permission

Embedded fonts that have read-write permission (and that therefore can be permanently installed on the user's system) should be written to a file that has the .TTF filename extension.

Most applications put the files for embedded fonts that have read-write permission into either the SYSTEM subdirectory of the user's Windows directory or into the application's working directory. Files for read-only embedded fonts are typically put into a temporary directory.

Before installing an embedded font, you must use the CreateScalableFontResource function to create a font resource file. Because Windows cannot directly interpret the native TrueType font file format, it requires a file that mimics the standard .FON file (called a .FOT file) to make internal bookkeeping and enumeration easier. The CreateScalableFontResource function produces a .FOT file that points to the TrueType font file. Once this .FOT file is produced, Windows applications can use TrueType fonts transparently by using the AddFontResource and RemoveFontResource functions. You can also use the CreateScalableFontResource function to install special fonts for logos, icons, and other graphics. Font resource files for read-only fonts should use a different extension (for example, .FOR) and should be hidden from other applications in the system by specifying 1 for the first parameter of CreateScalableFontResource.

Your application should offer users the option of permanently installing embedded fonts that have read-write permission. To permanently install a font, applications should concatenate the family and style names and then use the WriteProfileString function to insert this string along with the .FOT file name in the [Fonts] section of the WIN.INI file. A typical font entry in the [Fonts] section looks like the following example.

Times New Roman Bold (TrueType)=TIMESBD.FOT

Read-Only Permission

Embedded fonts with read-only permission should not use the .TTF extension and should avoid the .FOT and .FON extensions. A typical filename extension for read-only embedded fonts is .TTR. Files for read-only embedded fonts must be removed from the operating system and from both physical and logical memory as soon as the containing document is closed, so their names do not need to be meaningful except to the application.

If a document contains one or more read-only embedded fonts, the user must not be permitted to edit the document. If the user is allowed to edit the document in any way, your application must first strip away and delete the read-only embedded fonts. As mentioned earlier, read-only embedded fonts must be removed from the operating system and memory immediately when the document in which they are bundled is closed.

To delete read-only embedded fonts, your application should follow these steps:

1	Call the RemoveFontResource function for each font to be deleted.

2	Delete the font resource file for each font.

3	Delete each TrueType font file for each font.

When an application creates a file for a read-only embedded font and specifies 1 for the first parameter of the CreateScalableFontResource function, the EnumFonts and EnumFontFamilies functions will not enumerate this font. Hiding read-only embedded fonts in this manner makes it unlikely that another application can use them, even though Windows resources are theoretically available to all processes in Windows. The RemoveFontResource function does not delete a font currently in use. If your application uses a read-only embedded font installed by another application, it can be difficult for the installing application to delete the font. In this case, your application should delete the resource file and the TrueType font file when the user closes the document containing the read-only fonts.

It is very important that applications delete the TrueType font file for read-only embedded fonts. If the delete operation fails when the user closes the document, the application should periodically attempt to delete the file as the application runs, when it closes, and the next time it starts.

In some cases, an application is unable to delete a TrueType font file for a read-only embedded font because of external events (such as a system failure). There is no legal liability for events that are out of the control of the application.


Font and Text Functions

The following list identifies the font and text functions:

AddFontResource

CreateFont

CreateFontIndirect

CreateScalableFontResource

DrawText

EnumFontFamilies

EnumFontFamProc

EnumFonts

EnumFontsProc

ExtTextOut

GetAspectRatioFilter

GetAspectRatioFilterEx

GetCharABCWidths

GetCharABCWidthsFloat

GetCharWidth

GetCharWidthFloat

GetFontData

GetGlyphOutline

GetKerningPairs

GetOutlineTextMetrics

GetRasterizerCaps

GetTabbedTextExtent

GetTextAlign

GetTextCharacterExtra

GetTextColor

GetTextExtent

GetTextExtentExPoint

GetTextExtentPoint

GetTextFace

GetTextMetrics

MulDiv

PolyTextOut

RemoveFontResource

SetMapperFlags

SetTextAlign

SetTextCharacterExtra

SetTextColor

SetTextJustification

TabbedTextOut

TextOut


Colors Overview

About Color

Color functions, messages, and structures enable applications written for Microsoft® Windows™ to take advantage of recent improvements in display-adapter and printer technology. Colors are used by Windows-based applications in a variety of ways. Word-processing applications display and print text by using a variety of foreground and background colors, spreadsheet applications display and print charts and graphs that have been outlined and filled with a variety of pen and brush colors, and image-editing applications display and print bitmapped pictures by using a rich set of colors that give the images a realistic appearance. This topic focuses on the use of colors on video displays.

The following topics discuss Win32 color support:

Terms

Colors and Light

Colors and Video-Display Technology

Color Operations

Creating a Colored Pen

Functions

Messages


Colors and Light

Light is a form of electromagnetic radiation consisting of millions of small particles called photons. Although light consists of particles, it is analyzed as a wave form. It can be divided into three color groups, each characterized by a specific wavelength. The first group with the shortest wavelength is blue, the second with medium wavelength is green, and the third group with the longest wavelength is red. The RGB format uses these groups (red,green, and blue) to identify a color.

Three different elements characterize human perception of color: hue, luminosity, and saturation. Each of these elements loosely corresponds to one of the physical characteristics of light: hue corresponds to wavelength, luminosity corresponds to intensity, and saturation corresponds to purity. The HLS format uses these elements (hue, luminosity, and saturation) to identify a color.

The HLS format is supported in the Color common dialog box, shown in the following illustration. The Color common dialog box enables users to specify an HLS triplet that identifies a specific color.

Note:	Although colors can be specified in the Color common dialog box by using the HLS format Windows stores colors internally by using the RGB format.

For more information about the Color common dialog box, see Common Dialog Box Library


Colors and Video-Display Technology

Colors and Video Display Technology

The 8514, Video Graphics Adapter (VGA), and super-VGA video adapters are significant improvements over the early video displays such as the Color Graphics Adapter (CGA) and the Enhanced Graphics Adapter (EGA). The CGA is capable of producing a maximum of 4 colors with a resolution of 320 by 200 pixels. The EGA is capable of producing a maximum of 16 simultaneous colors from an array of 64 total available colors with a resolution of 640 by 350 pixels. The more recent VGA is capable of producing 16 simultaneous colors from an array of 262,144 colors with a resolution of 640 by 480 pixels. The 8514 and super VGA displays offer resolutions and color capabilities beyond that of the standard VGA. Some super VGA displays are capable of displaying over 16 million colors at a resolution of 1024 by 768 pixels. The improvements in color capabilities and resolution have finally made it possible to display realistic bitmapped images in the client area of an application's window without dithering or mixing colors to produce shades.

A color video display is normally a raster device that treats the display surface as a coordinate space and draws lines, curves, text, and filled objects by repeatedly scanning rows of picture elements called pixels from left to right and from top to bottom. A pixel becomes visible when one or more electron guns in the back of the display fire an electron beam onto a phosphor coating on the back of the display surface. When struck by the electron beam, the phosphor emits visible light. In the simplest case, a single pixel is created by combining the light produced by three electron guns. When the beam of each gun strikes the phosphor coating, it generates red, green, or blue light of varying intensity. When viewed by the human eye, the three dots produced by the three guns appear to merge and form a single color. The point at which the three dots merge is a pixel.

Color video technology is often called an additive technology because the color of each pixel on a display is specified by adding the intensity values for each of the primaries: red, green, and blue. For example, if the minimum intensity on a given display was specified as 0 and maximum intensity was specified as 255, a white pixel would be identified by the RGB triplet (255, 255, 255), a black pixel would be identified by the RGB triplet (0, 0, 0), and a cyan pixel would be identified by the RGB triplet (0, 255, 255).


Color Operations

Most of the 8514 and super VGA display adapters impose a limit on the number of colors that can appear simultaneously on the screen. This limit is a function of the resolution of the display and the amount of memory on the adapter card. For example, an adapter with 512 kilobytes (K) of video memory could display as many as 256 colors simultaneously on a display with a resolution of 640 by 480 pixels. If the display resolution were increased to 1024 by 768 pixels, the memory limitations of the adapter card would prevent the simultaneous display of 256 colors--instead, only 16 different colors could appear at the same time. This problem is fairly common on a number of displays--only a subset of the total number of colors can appear simultaneously. The array which identifies this subset is called the system palette. Windows adds entries from another palette, the logical palette, to the system palette when an application realizes its logical palette. The two palettes are described in the following sections.

System Palette

The system palette is an array identifying a subset of the total number of colors that can appear simultaneously on a display. It is shared by all Windows-based applications. Windows provides a set of palette-manager functions that are used to alter the colors in the system palette. These functions are designed for applications that require realistic colors when displaying bitmapped images.The code supporting these functions is part of a dynamic-link library (DLL) called the display driver. A display driver is a Windows DLL that converts graphics device interface (GDI) function calls to corresponding device commands. Not all display drivers support the palette-manager functions. For example, standard VGA display drivers do not support the palette-manager functions, super-VGA display drivers do. You can determine whether or not a device supports a system palette by calling the GetDeviceCaps function and specifying the RASTERCAPS constant. If a device supports a system palette, you can retrieve the system palette size by calling the GetDeviceCaps function and specifying the NUMCOLORS constant as the second argument.

The palette-manager functions are powerful but potentially problematic; by altering colors in the system palette can could also change the colors in every window on the desktop. In order to prevent this from happening, Windows provides the following:

An object called a logical palette that is associated with each application's device context. For more information about the logical palette, see Logical Palette

A set of messages that informs an application that changes have been made to the system palette.

A set of functions used to create, alter, and remove a logical palette.

Logical Palette

A logical palette is an array of colors that an application can use when drawing graphics output using the device context. Each device context has a default logical palette containing 20 entries. Of these 20 entries, 16 of the colors correspond to the colors found on a standard VGA display while the remaining 4 correspond to unique colors used by Window Manager. The following table shows the default logical palette and the RGB triplets found in each entry:

Index value	Red	Green	Blue

0	0x00	0x00	0x00

1	0x80	0x00	0x00

2	0x00	0x80	0x00

3	0x80	0x80	0x00

4	0x00	0x00	0x80

5	0x80	0x00	0x80

6	0x00	0x80	0x80

7	0xC0	0xC0	0xC0

8	0xC0	0xDC	0xC0

9	0xA6	0xCA	0xF0

10	0xFF	0xFB	0xF0

11	0xA0	0xA0	0xA4

12	0x80	0x80	0x80

13	0xFF	0x00	0x00

14	0x00	0xFF	0x00

15	0xFF	0xFF	0x00

16	0x00	0x00	0xFF

17	0xFF	0x00	0xFF

18	0x00	0xFF	0xFF

19	0xFF	0xFF	0xFF

The 16 standard VGA colors are found at locations 0-7 and locations 12-19; the nonstandard colors are found at locations 8-11.

Custom Logical Palette

If an application creates or displays bitmapped images, it may be necessary to use more than the 20 default colors. It may also be necessary to replace the 20 default colors with colors that are better suited to the image that is created or displayed. Before creating a custom logical palette, an application must determine the number of colors that are supported by the device. This is done by calling the GetDeviceCaps function and passing the NUMCOLORS constant as the second argument.

The colors requested in the logical palette are mapped to the system palette when the application's window is the active window on the desktop and when the application realizes its logical palette by calling the RealizePalette function. If an application replaces the entire system palette with new colors, it must call the SetSystemPaletteUse function before to realizing its logical palette.

In order to prevent one application from altering the colors in other application's windows, three messages are supported by window manager. If the currently active application realizes a custom palette by calling the RealizePalette function, Windows sends the WM_PALETTEISCHANGING message to all top-level and overlapped windows, indicating the system palette is about to change. If the function executes successfully, Windows sends the WM_PALETTECHANGED message to the windows, indicating the system palette has changed. When one of the top-level or overlapped windows is about to be activated, Windows sends the WM_QUERYNEWPALETTE message. Upon receiving this message, the corresponding application must call the RealizePalette function to realize its own logical palette.

To create a custom logical palette, an application first needs to create a LOGPALETTE structure, call the CreatePalette function, and pass a pointer to the structure. An application can select a logical palette into the application device context by calling the SelectPalette function. However, before you can draw in the client area of your application's window by using the colors specified in the custom logical palette, you'll need to call the RealizePalette function. If your application's window is currently the active window, the colors requested in your logical palette are stored in the system palette, and you can begin drawing. If the application's window is not the active window, the colors requested in the custom logical palette may not be matched to the system palette. Whether or not a match occurs depends on such things as the size of the system palette, the size of the custom palette, the size of the logical palette associated with the active window, and the colors specified in both logical palettes.

Once a logical palette is created, an application can change or update its colors by calling the AnimatePalette or SetPaletteEntries function. If the application's window is active, the application can update the colors on the screen immediately by calling the AnimatePalette function. To update the logical-palette colors but continue displaying the current colors for a period of time, it can call the SetPaletteEntries function to alter the logical palette and then later call the RealizePalette function when it is appropriate to actually update the image on the screen.

Colored Pens, Brushes, and Text

Applications can use the palette manager and the Color common dialog box to let a user select a custom color. The dialog box is displayed by calling the ChooseColor function, which returns an RGB triplet for the requested color. To retrieve the logical-palette index for the closest color in the logical palette, call the GetNearestPaletteIndex function. Use this index to create a pen, brush, or text output with the closest match to the requested color.

When creating color pens, brushes, and text, it is actually faster to use an RGB triplet (instead of a Palette index) to set the colors of objects in a device context. Once the ChooseColor function returns an RGB triplet, determine the closest match by calling the GetNearestColor function. Use the triplet returned by GetNearestColor to create a colored pen by calling the CreatePenIndirect function, create a colored brush by calling the CreateBrushIndirect function, or create colored text by calling the SetTextColor function.


Creating a Colored Pen

You can use the Color common dialog box to let the user choose pen, brush, and text colors. This dialog box is displayed by initializing a CHOOSECOLOR structure and calling the ChooseColor function. Upon executing successfully, the ChooseColor function stores an RGB triplet corresponding to the user's selection in the rgbResult member of the CHOOSECOLOR structure. You can use this member to specify a pen, brush, or text color by calling the CreatePenIndirect, CreateBrushIndirect, or SetTextColor function and copying the RGB data from this member to the appropriate argument.

In the following example, the data contained in the rgbResult member is copied into the lopnColor member of a LOGPEN structure and is used to create a new pen.

case IDM_PENCOLOR:

    /* Retrieve the default logical palette entries. */

    iRet = GetPaletteEntries(hpal, 0, 20, ape);

    /* Set the custom color controls to white. */

    for (i = 0; i < 16; i++)

        aclrCust[i] = RGB(255, 255, 255);

    /* Initialize clr to black. */

    clr = RGB(0, 0, 0);

    /* Set all structure members to zero. */

    memset(&cc, 0, sizeof(CHOOSECOLOR));

    /* Initialize the necessary CHOOSECOLOR members. */

    cc.lStructSize = sizeof(CHOOSECOLOR);

    cc.hwndOwner = hWnd;

    cc.rgbResult = clr;

    cc.lpCustColors = aclrCust;

    cc.Flags = CC_PREVENTFULLOPEN;

    if (ChooseColor(&cc)) {

        /* Initialize the LOGPEN structure. */

        lp.lopnStyle = PS_SOLID;

        lp.lopnWidth.x = 1;

        lp.lopnColor = cc.rgbResult;

        /* Select the new pen and draw. */

        hdc = GetDC(hWnd);

        hpenOld = SelectObject(hdc, CreatePenIndirect(&lp));

        MoveToEx(hdc, 100, 100, NULL);

        LineTo(hdc, 100, 200);

        /*   . */

        /*   . */

        /*   . */

        ReleaseDC(hWnd, hdc);

    }

    break;


Functions

Functions and Messages

Following are the functions and messages that support the use of color in a Win32 application.

Functions

AnimatePalette

CreateHalftonePalette

CreatePalette

GetColorAdjustment

GetNearestColor

GetNearestPaletteIndex

GetPaletteEntries

GetSystemPaletteEntries

GetSystemPaletteUse

RealizePalette

ResizePalette

SelectPalette

SetColorAdjustment

SetPaletteEntries

SetSystemPaletteUse

UpdateColors


Messages

Messages

WM_PALETTECHANGED

WM_PALETTEISCHANGING

WM_QUERYNEWPALETTE

WM_SYSCOLORCHANGE


Paths Overview

About Paths

A path is one or more figures (or shapes) that are filled, outlined, or both filled and outlined. Applications written for Microsoft® Windows™ use paths in many ways. Paths are used in drawing and painting applications. Computer-aided design (CAD) applications use paths to create unique clipping regions, to draw outlines of irregular shapes, and to fill the interiors of irregular shapes. An irregular shape is a shape composed of Bézier curves and straight lines. (A regular shape is an ellipse, a circle, a rectangle, or a polygon.)

The following topics discuss paths:

Terms

Outlined and Filled Paths

Transformation of Paths

Clip Paths

Conversion of Paths to Regions

Curved Paths

Using Paths

Functions

A path is one of the objects associated with a device context (DC). However, unlike the default objects (the pen, the brush, and the font) that are part of any new DC, there is no default path. For more information about device contexts, see Device Contexts.

To create a path and select it into a device context, it is first necessary to define the points that describe it. This is done by calling the BeginPath function, specifying the appropriate drawing functions, and then by calling the EndPath function. This combination of functions (BeginPath, drawing functions, and EndPath) constitute a path bracket. The following functions can be used in a path bracket:

AngleArc	LineTo	Polyline

Arc	MoveToEx	PolylineTo

ArcTo	Pie	PolyPolygon

Chord	PolyBezier	PolyPolyline

CloseFigure	PolyBezierTo	Rectangle

Ellipse	PolyDraw	RoundRect

ExtTextOut	Polygon	TextOut

When an application calls the EndPath function, Windows selects the associated path into the specified DC. (If another path had previously been selected into the DC, Windows deletes that path without saving it.) After Windows selects the path into the DC, an application can operate on the path in one of the following ways:

Draw the outline of the path (using the current pen).

Paint the interior of the path (using the current brush).

Draw the outline and fill the interior of the path.

Modify the path (by converting curves to line segments).

Convert the path into a clip path.

Convert the path into a region.

Flatten the path by converting each curve in the path into a series of line segments.

Retrieve the coordinates of the lines and curves that compose a path.


Outlined and Filled Paths

An application can draw the outline of a path by calling the StrokePath function; it can fill the interior of a path by calling the FillPath function; and it can both outline and fill the path by calling the StrokeAndFillPath function.

Whenever an application fills a path, Windows uses the device context's current fill mode. An application can retrieve this mode by calling the GetPolyFillMode function and, it can set a new fill mode by calling the SetPolyFillMode function. For a description of the two fill modes, see Regions.

The following illustration shows the cross-section of an object created by a computer-aided design (CAD) application using paths that were both outlined and filled.


Transformations of Paths

Paths are defined by using logical units and current transformations. (If the SetWorldTransform function has been called, the logical units are world units; if this function has not been called, the logical units are page units.) An application can use world transformations to scale, rotate, shear, translate, and reflect the lines and Bézier curves which define a path.

Note:	A world transformation within a path bracket only affects those lines and curves drawn after the transformation was set. It will have no affect on those lines and curves that were drawn before setting the transformation. For a description of world transformation, see Coordinate Spaces and Transformations.

An application can also use the SetWorldTransform function to outline the shape of the pen used to outline a path if the pen is a geometric pen. For a description of geometric pens, see Pens.


Clip Paths

An application can use clipping and paths to create special graphic effects. The following illustration shows a string of text drawn by using a large Arial font.

The next illustration shows the result of selecting the text as a clip path and drawing radial lines for a circle whose center is located above and left of the string.

Note:	Before GDI adds text created with a bitmapped font to a path, it converts the font to an outline or vector font.

An application creates a clip path by generating a path bracket and then by calling the SelectClipPath function. After a clip path is selected into a DC, output only appears within the borders of the path.

In addition to creating special graphic effects, clip paths are also useful in applications that save images as enhanced metafiles. By using a clip path, an application is able to ensure device independence because the units used to specify a path are logical units (as opposed to device units that are used to specify a region).


Conversion of Paths to Regions

An application can convert a path into a region by calling the PathToRegion function. Like the SelectClipPath function, PathToRegion is useful in the creation of special graphic effects. For example, there are no functions that allow an application to offset a path; however, there is a function that enables an application to offset a region (OffsetRgn). Using PathToRegion, an application can create the effect of animating a complex shape by creating a path that defines the shape, converting the path into a region (by calling PathToRegion), and then repeatedly painting, moving, and erasing the region (by calling functions in a sequence such as FillRgn, OffsetRgn, FillRgn).


Curved Paths

An application can flatten the curves in a path by calling the FlattenPath function. This function is especially useful in applications that fit text onto the contour of a path which contains curves. To fit the text, the application must perform the following steps:

1	Create the path where the text appears.

2	Call the FlattenPath function to convert the curves in a path into line segments.

3	Call the GetPath function to retrieve these line segments.

4	Calculate the length of each line and the width of each character in the string.

5	Use the line-width and character-width data to position each character along the curve.


Using Paths

This section contains a code sample that enables the user to select a font of a particular point size (by using the Choose Font dialog box), select a clip path (by using text drawn with this font), and then view the result of clipping to the text.

This code was used to create the illustrations that appear in Clip Paths.

CHOOSEFONT cf;          /* common dialog box font structure */

LOGFONT lf;             /* logical font structure */

HFONT hfont;            /* new logical font handle */

HFONT hfontOld;         /* original logical font handle */

HDC hdc;                /* display DC handle */

int nXStart, nYStart;   /* drawing coordinates */

RECT rc;                /* rectangle structure for painting window */

SIZE sz;                /* size structure that receives text extents */

double aflSin[90];      /* sine of 0-90 degrees in 1 degree increments */

double aflCos[90];      /* cosine of 0-90 degrees in 1 degree increments */

double flRadius,a;      /* radius of circle */

int iMode;              /* clipping mode */

HRGN hrgn;              /* clip region handle */

LRESULT APIENTRY MainWndProc(

    HWND hwnd,                /* window handle                   */

    UINT message,             /* type of message                 */

    WPARAM wParam,            /* additional information          */

    LPARAM lParam)            /* additional information          */

{

    PAINTSTRUCT ps;

    switch (message) {

        case WM_PAINT:

            hdc = BeginPaint(hwnd, &ps);

            EndPaint(hwnd, &ps);

            break;

        case WM_COMMAND: /* message: command from application menu */

            switch (wParam) {

                case IDM_VANISH: /* erases client area */

                    hdc = GetDC(hwnd);

                    GetClientRect(hwnd, &rc);

                    FillRect(hdc, &rc, GetStockObject(WHITE_BRUSH));

                    ReleaseDC(hwnd, hdc);

                    break;

                case IDM_AND: /* sets clip mode to RGN_AND */

                    iMode = RGN_AND;

                    break;

                case IDM_COPY: /* sets clip mode to RGN_COPY */

                    iMode = RGN_COPY;

                    break;

                case IDM_DIFF: /* sets clip mode to RGN_DIFF */

                    iMode = RGN_DIFF;

                    break;

                case IDM_OR: /* sets clip mode to RGN_OR */

                    iMode = RGN_OR;

                    break;

                case IDM_XOR: /* sets clip mode to RGN_XOR */

                    iMode = RGN_XOR;

                    break;

                case IDM_CLIP_PATH:

                    /* Retrieve a cached DC for the window. */

                    hdc = GetDC(hwnd);

                    /*

                     * Use the font requested by the user in the

                     * Choose Font dialog box to create a logical font, and then

                     * select that font into the device context.

                     */

                    hfont = CreateFontIndirect(cf.lpLogFont);

                    hfontOld = SelectObject(hdc, hfont);

                    /*

                     * Retrieve the dimensions of the rectangle

                     * that surrounds the text.

                     */

                     GetTextExtentPoint(hdc, "Clip Path", 9, &sz);

                    /*

                     * Set a clipping region using the rectangle that

                     * surrounds the text.

                     */

                     hrgn = CreateRectRgn(nXStart, nYStart,

                         nXStart + sz.cx,

                         nYStart + sz.cy);

                     SelectClipRgn(hdc, hrgn);

                    /*

                     * Create a clip path using text drawn with

                     * the user's requested font.

                     */

                    BeginPath(hdc);

                        TextOut(hdc, nXStart, nYStart, "Clip Path", 9);

                    EndPath(hdc);

                    SelectClipPath(hdc, iMode);

                    /* Compute the sine of 0, 1, 2, ... 90 degrees. */

                    for (i = 0; i < 90; i++) {

                        aflSin[i] = sin( (((double)i) / 180.0) * 3.14159);

                        }

                    /* Compute the cosine of 0, 1, 2, ... 90 degrees. */

                    for (i = 0; i < 90; i++) {

                        aflCos[i] = cos( (((double)i) / 180.0) * 3.14159);

                        }

                    /* Set the radius value. */

                    flRadius = (double)(2 * sz.cx);

                    /*

                     * Draw the 90 rays extending from the

                     * radius to the edge of the circle.

                     */

                    for (i = 0; i < 90; i++) {

                        MoveToEx(hdc, nXStart, nYStart, (LPPOINT) NULL);

                        LineTo(hdc, nXStart + ((int) (flRadius * aflCos[i])),

                               nYStart + ((int) (flRadius * aflSin[i])));

                        }

                    /* Reselect the original font into the DC. */

                     SelectObject(hdc, hfontOld);

                    /* Delete the user's font. */

                     DeleteObject(hfont);

                    /* Release the DC. */

                    ReleaseDC(hwnd, hdc);

                    break;

                case IDM_FONT:

                    /* Initialize necessary members. */

                    cf.lStructSize = sizeof (CHOOSEFONT);

                    cf.hwndOwner = hwnd;

                    cf.lpLogFont = &lf;

                    cf.Flags = CF_SCREENFONTS | CF_EFFECTS;

                    cf.rgbColors = RGB(0, 255, 255);

                    cf.nFontType = SCREEN_FONTTYPE;

                    /*

                     * Display the Font dialog box, allow the user to

                     * choose a font, and render text in the

                     * window with that selection.

                     */

                    if (ChooseFont(&cf)) {

                        hdc = GetDC(hwnd);

                        hfont = CreateFontIndirect(cf.lpLogFont);

                        hfontOld = SelectObject(hdc, hfont);

                        crOld = SetTextColor(hdc, cf.rgbColors);

                        TextOut(hdc, nXStart, nYStart,

                            "Clip Path", 9);

                        SetTextColor(hdc, crOld);

                        SelectObject(hdc, hfontOld);

                        DeleteObject(hfont);

                        ReleaseDC(hwnd, hdc);

                    }

                    break;

                default:

                    return DefWindowProc(hwnd, message, wParam, lParam);

            }

            break;

        case WM_DESTROY: /* message: window being destroyed    */

            PostQuitMessage(0);

            break;

        default: /* passes it on if unprocessed        */

            return DefWindowProc(hwnd, message, wParam, lParam);

    }

    return 0;

}


Functions

Use the following functions to create, alter, or draw paths.

AbortPath

BeginPath

CloseFigure

EndPath

FillPath

FlattenPath

GetMiterLimit

GetPath

PathToRegion

SelectClipPath

SetMiterLimit

StrokeAndFillPath

StrokePath

WidenPath


Clipping Overview

About Clipping

Clipping is the process of limiting output to a region or path within the client area of an application's window. Clipping is used by applications written for Microsoft® Windows™ in a variety of ways. Word processing and spreadsheet applications clip keyboard input to keep it from appearing in the margins of a page or spreadsheet. Computer-aided design (CAD) and drawing applications clip graphics output to keep it from overwriting the edges of a drawing or picture.

A clipping region is a region with edges that are either straight lines or curves. A clip path is a region with edges that are straight lines, Bézier curves, or combinations of both.

The following topics discuss clipping:

Terms

Clip Regions

Clip Paths

Using Clipping

Functions


Clip Regions

Clipping Regions

A clipping region is one of the graphic objects that an application can select into a device context (DC). It is typically rectangular. Some device contexts provide a predefined or default clipping region while others do not. For example, if you obtain a device context handle from the BeginPaint function, the DC contains a predefined, rectangular clipping region that corresponds to the invalid rectangle that requires repainting. However, if you obtain a device context handle by calling the CreateDC or GetDC function, the DC does not contain a default clipping region.

Applications can perform a variety of operations on clipping regions. Some of these operations require a handle identifying the region and some do not. For example, an application can perform the following operations directly on a device context's clipping region:

Determine whether graphics output appears within the region's borders by passing coordinates of the corresponding line, arc, bitmap, text, or filled shape to the PtVisible function.

Determine whether part of the client area intersects a region by calling the RectVisible function.

Move the existing region by a specified offset by calling the OffsetClipRgn function.

Exclude a rectangular part of the client area from the current clipping region by calling the ExcludeClipRect function.

Combine a rectangular part of the client area with the current clipping region by calling the IntersectClipRect function.

After obtaining a handle identifying the region, an application can perform any operation that is common with regions; for example:

Combining a copy of the current clipping region with a second region by calling the CombineRgn function.

Compare a copy of the current clipping region to a second region by calling the EqualRgn function.

Determine whether a point lies within the interior of a copy of the current clipping region by calling the PtInRegion function.


Clip Paths

Like a clipping region, a clip path is another graphics object an application can select into a device context. Unlike a clipping region, a clip path is always created by an application and it is used for clipping to one or more irregular shapes. For example, an application can use the lines and curves that form the outlines of characters in a string of text to define a clip path.

To create a clip path, it's first necessary to create a path that describes the required irregular shape. Paths are created by calling the appropriate GDI drawing functions after calling the BeginPath function and before calling the EndPath function. This collection of functions is called a path bracket.

After the path is created, it can be converted to a clip path by calling the SelectClipPath function, identifying a device context, and specifying a usage mode. The usage mode determines how Windows combines the new clip path with the device context's original clipping region. The following table describes the usage modes.

Mode	Description

RGN_AND	The clip path includes the intersection (overlapping areas) of the device context's clipping region and the current path.

RGN_COPY	The clip path is the current path.

RGN_DIFF	The clip path includes the device context's clipping region with any intersecting parts of the current path excluded.

RGN_OR	The clip path includes the union (combined areas) of the device context's clipping region and the current path.

RGN_XOR	The clip path includes the union of the device context's clipping region and the current path but excludes the intersection.


Using Clipping

This section contains a code example that demonstrates how an application can generate a clip path consisting of the characters "ABC" drawn by using a font specified by the user.

The following illustration shows the string of text drawn in the usual fashion by using a brush with the current text color.

The next illustration shows the string of text selected as a clip path and filled by drawing horizontal and vertical lines.

CHOOSEFONT cf;      /* common dialog box font structure          */

LOGFONT lf;         /* logical font structure                    */

HFONT hfont;        /* new logical font handle                   */

HFONT hfontOld;     /* original logical font handle              */

HDC hdc;            /* display DC handle                         */

int nXStart, nYStart; /* drawing coordinates                     */

RECT rc;            /* rectangle structure for painting window   */

SIZE sz;            /* size structure that receives text extents */

    /* Retrieve a cached DC for the window. */

    hdc = GetDC(hwnd);

    /* Erase the current window contents. */

    GetClientRect(hwnd, &rc);

    FillRect(hdc, &rc, GetStockObject(WHITE_BRUSH));

    /*

     * Use the font requested by the user in the

     * Font dialog box to create a logical font, and

     * then select that font into the DC.

     */

    hfont = CreateFontIndirect(cf.lpLogFont);

    hfontOld = SelectObject(hdc, hfont);

    /*

     * Create a clip path using text drawn with

     * the user's requested font.

     */

    BeginPath(hdc);

        TextOut(hdc, nXStart, nYStart, "ABC", 3);

    EndPath(hdc);

    SelectClipPath(hdc, RGN_DIFF);

    /*

     * Retrieve the dimensions of the rectangle

     *that surrounds the text.

     */

     GetTextExtentPoint(hdc, "ABC", 3, &sz);

    /*

     *Draw horizontal lines through the clip

     * path.

     */

     for (i = nYStart + 1; i < (nYStart + sz.cy); i+=3) {

        MoveToEx(hdc, nXStart, i, (LPPOINT) NULL);

        LineTo(hdc, (nXStart + sz.cx), i);

    }

    /* Draw vertical lines through the clip path. */

     for (i = nXStart + 1; i < (nXStart + sz.cx); i+=3){

        MoveToEx(hdc, i, nYStart, (LPPOINT) NULL);

        LineTo(hdc, i, (nYStart + sz.cy));

    }

    /* Reselect the original font into the DC. */

     SelectObject(hdc, hfontOld);

    /* Delete the user's font. */

     DeleteObject(hfont);

    /* Release the DC. */

     ReleaseDC(hwnd, hdc);


API Elements

Functions

Following are the functions used with clipping:

ExcludeClipRect

ExtSelectClipRgn

GetClipBox

GetClipRgn

GetMetaRgn

IntersectClipRect

OffsetClipRgn

PtVisible

RectVisible

SelectClipPath

SelectClipRgn

SetMetaRgn


Coordinate Spaces and Transformations Overview

About Coordinate Spaces and Transformations

Applications written for Microsoft® Windows™ use coordinate spaces and transformations to scale, rotate, translate, shear, and reflect graphics output. For example, desktop publishing applications use coordinate spaces and transformations to "zoom" parts of a page or to display adjacent pages in a window; computer-aided design (CAD) applications use them to rotate objects, scale drawings, or to create perspective views; and spreadsheet applications use them to move and size graphs.

The following topics discuss Win32 coordinate spaces and trasnformations:

Terms

Transformation of Coordinate Spaces

World- to Page-Space Transformations

Page- to Device-Space Transformations

Device-Space to Physical-Device Transformation

Default Transformations

Using Coordinates Spaces and Transformations

Functions

The following illustrations show successive views of an object created in a drawing application. The first illustration shows the object as it appears in the original drawing; the five remaining illustrations show the effects of applying various transformations.


Transformation of Coordinate Spaces

A coordinate space is a planar space based on the Cartesian coordinate system. This system provides a means of specifying the location of each point on a plane. It requires two axes that are perpendicular and equal in length. The following illustration shows a coordinate space.

The Win32 application programming interface (API) uses four coordinate spaces: world, page, device, and physical device. Applications use world space to rotate, shear, or reflect graphics output. World space measures 2^ 32 units high by 2^ 32 units wide. Page space (referred to as logical space in earlier versions of Windows) also measures 2^ 32 units high by 2^ 32 units wide. Device space measures 2^ 27 units high by 2^ 27 units wide. Page space works with device space to provide applications with device-independent units, such as millimeters and inches. The Win32 API refers to both world space and page space as logical space. The final coordinate space, physical device, usually refers to the client area of the application's window; however, it can also include the entire desktop, a complete window (including the frame, title bar, and menu bar), or a page of printer or plotter paper. Physical device dimensions vary according to the dimensions set by the display, printer, or plotter technology.

To depict output on a physical device, Windows copies (or maps) a rectangular region from one coordinate space into the next coordinate space until finally the output appears in its entirety on the physical device. Mapping begins in the application's world space if the application has called the SetWorldTransform function; otherwise, mapping occurs in page space. As Windows copies each point within the rectangular region from one space into another, it applies an algorithm called a transformation. A transformation alters (or transforms) the size, orientation, and shape of objects that are copied from one coordinate space into another. Although a transformation affects an object as a whole, it is applied to each point, or to each line, in the object.

The following illustration shows a typical transformation performed by using the SetWorldTransform function.


World-Space to Page-Space Transformations

World-space to page-space transformations are new to Windows. They support translation and scaling that were available in previous versions of Windows. In addition, they support rotation, shear, and reflection capabilities. The following sections describe these transformations, illustrate their effects, and provide the algorithms used to achieve them.

Translation

Some applications translate (or shift) objects drawn in the client area. If your application features this capability, use the SetWorldTransform function to set the appropriate world-space to page-space transformation. This function receives a pointer to an XFORM structure containing the appropriate values. The eDx and eDy members of XFORM specify the horizontal and vertical translation components, respectively.

When translation occurs, each point in an object is shifted vertically, horizontally, or both, by a specified amount. The following illustration shows a 20- by 20-unit rectangle that was translated to the right by 10 units when copied from world coordinate space to page coordinate space.

In the preceding illustration, the x-coordinate of each point in the rectangle is 10 units greater than the original x-coordinate.

Horizontal translation can be represented by the following algorithm.

x' = x + Dx

Where x' is the new x-coordinate, x is the original x-coordinate, and Dx is the horizontal distance moved.

Vertical translation can be represented by the following algorithm.

y' = y + Dy

Where y' is the new y-coordinate, y is the original y-coordinate, and Dy is the vertical distance moved.

The horizontal and vertical translation transformations can be combined into a single operation by using a 3-by-3 matrix.

                      |1   0   0|

|x' y' 1| = |x y 1| * |0   1   0|

                      |Dx  Dy  1|

(The rules of matrix multiplication state that the number of rows in one matrix must equal the number of columns in the other. The integer 1 in the matrix |x y 1| is a placeholder that was added to meet this requirement.)

The 3-by-3 matrix that produced the illustrated translation transformation contains the following values.

|1  0  0|

|0  1  0|

|10 0  1|

Scaling

Most CAD and drawing applications provide features that scale output created by the user. If your application features scaling (or "zoom") capabilities, use the SetWorldTransform function to set the appropriate world-space to page-space transformation. This function receives a pointer to an XFORM structure containing the appropriate values. The eM11 and eM22 members of XFORM specify the horizontal and vertical scaling components, respectively.

When scaling occurs, the vertical and horizontal lines (or vectors) that constitute an object are stretched or compressed with respect to the x-axis or the y-axis. The following illustration shows a 20- by 20-unit rectangle scaled vertically to twice its original height when copied from world coordinate space to page coordinate space.

In the preceding illustration, the vertical lines that define the original rectangle's side measure 20 units, while the vertical lines that define the scaled rectangle's sides measure 40 units.

Vertical scaling can be represented by the following algorithm.

y' = y * Dy

Where y' is the new length, y is the original length, and Dy is the vertical scaling factor.

Horizontal scaling can be represented by the following algorithm.

x' = x * Dx

Where x' is the new length, x is the original length, and Dx is the horizontal scaling factor.

The vertical and horizontal scaling transformations can be combined into a single operation by using a 2-by-2 matrix.

|x' y'|  =  |Dx   0|  *  |x y|

            |0   Dy|

The 2-by-2 matrix that produced the illustrated scaling transformation contains the following values.

|1    0|

|0    2|

Rotation

Many CAD applications provide features that rotate objects drawn in the client area. If your application features rotation capabilities, use the SetWorldTransform function to set the appropriate world-space to page-space transformation. This function receives a pointer to an XFORM structure containing the appropriate values. The eM11, eM12, eM21, and eM22 members of XFORM specify, respectively, the cosine, sine, negative cosine, and cosine of the angle of rotation.

When rotation occurs, the points that constitute an object are rotated with respect to the coordinate-space origin. The following illustration shows a 20- by 20-unit rectangle rotated 30 degrees when copied from world coordinate space to page coordinate space.

In the preceding illustration, each point in the rectangle was rotated 30 degrees with respect to the coordinate-space origin.

The following algorithm computes the new x-coordinate (x') for a point (x,y) that is rotated by angle A with respect to the coordinate-space origin.

x' = (x * cos A) - (y * sin A)

The following algorithm computes the y-coordinate (y') for a point (x,y) that is rotated by the angle A with respect to the origin.

y' = (x * sin A) - (y * cos A)

The two rotation transformations can be combined in a 2-by-2 matrix as follows.

|x' y'| == |x y| * | cos A   sin A|

                   |-sin A   cos A|

The 2-by-2 matrix that produced the rotation contained the following values.

| .8660    .5000|

|-.5000    .8660|

The Rotation Algorithm Derivation

Rotation algorithms are based on trigonometry's addition theorem stating that the trigonometric function of a sum of two angles (A1 and A2) can be expressed in terms of the trigonometric functions of the two angles.

sin(A1 + A2) = (sin A1 * cos A2) + (cos A1 * sin A2)

cos(A1 + A2) = (cos A1 * cos A2) - (sin A1 * sin A2)

The following illustration shows a point p rotated counterclockwise to a new position p'. In addition, it shows two triangles formed by a line drawn from the coordinate-space origin to each point and a line drawn from each point through the x-axis.

Using trigonometry, the x-coordinate of point p can be obtained by multiplying the length of the hypotenuse h by the cosine of A1.

x = h * cos A1

The y-coordinate of point p can be obtained by multiplying the length of the hypotenuse h by the sine of A1.

y = h * sin A1

Likewise, the x-coordinate of point p' can be obtained by multiplying the length of the hypotenuse h by the cosine of (A1 + A2).

x' = h * cos (A1 + A2)

Finally, the y-coordinate of point p' can be obtained by multiplying the length of the hypotenuse h by the sine of (A1 + A2).

y' = h * sin (A1 + A2)

Using the addition theorem, the preceding algorithms become the following.

x' = (h * cos A1 * cos A2) - (h * sin A1 * sin A2)

y' = (h * cos A1 * sin A2) - (h * sin A1 * cos A2)

The rotation algorithms for a given point rotated by angle A2 can be obtained by substituting x for each occurrence of (h * cos A1) and substituting y for each occurrence of (h * sin A1).

x' = (x * cos A2) - (y * sin A2)

y' = (x * sin A2) - (y * cos A2)

Shear

Some applications provide features that shear objects drawn in the client area. If your application features shear capabilities, use the SetWorldTransform function to set appropriate values in the world-space to page-space transformation. This function receives a pointer to an XFORM structure containing the appropriate values. The eM12 and eM21 members of XFORM specify the horizontal and vertical proportionality constants, respectively.

There are two components of the shear transformation: The first alters the vertical lines in an object; the second alters the horizontal lines. The following example shows a 20- by 20-unit rectangle sheared horizontally when copied from world-space to page-space.

A horizontal shear can be represented by the following algorithm.

x' = x + (Sx * y)

Where x is the original x-coordinate, Sx is the proportionality constant, and x' is the result of the shear transformation.

A vertical shear can be represented by the following algorithm.

y' = y + (Sy * x)

Where y is the original y-coordinate, Sy is the proportionality constant, and y' is the result of the shear transformation.

The horizontal-shear and vertical-shear transformations can be combined into a single operation using a 2-by-2 matrix.

|x' y'| == |x y| * |  1   Sx|

                   | Sy    1|

The 2-by-2 matrix that produced the shear contains the following values.

|1    1|

|0    1|

Reflection

Some applications provide features that reflect (or mirror) objects drawn in the client area. If your application features reflection capabilities, use the SetWorldTransform function to set the appropriate values in the world-space to page-space transformation. This function receives a pointer to an XFORM structure containing the appropriate values. The eM11 and eM22 members of XFORM specify the horizontal and vertical reflection components, respectively.

The reflection transformation creates a "mirror" image of an object with respect to either the x-axis or the y-axis. The following illustration shows a 20- by 20-unit rectangle reflected horizontally and vertically upon being copied from world coordinate space to page coordinate space.

Horizontal reflection can be represented by the following algorithm.

x' = x * Rx

Where x is the x-coordinate, Rx is negative one (-1), and x' is the result of the reflection.

Vertical reflection is represented by the following algorithm.

y' = y * Ry

Where y is the y-coordinate, Ry is negative one (-1), and y' is the result of the reflection.

The horizontal-reflection and vertical-reflection operations can be combined into a single operation using a 2-by-2 matrix.

|x' y'| == |x y| * |Rx    0|

                   |0    Ry|

The 2-by-2 matrix that produced the illustrated reflection contains the following values.

|-1    0|

|0     1|

Combined World-to-Page Space Transformations

You can combine the five world-to-page transformations into a single 3-by-3 matrix. Use these combined transformations to alter output associated with a particular device context by calling the SetWorldTransform function and supplying the elements for this matrix. When an application calls the SetWorldTransform function, it stores the elements of the 3-by-3 matrix in an XFORM structure. The members of this structure correspond to the first two columns of a 3-by-3 matrix; the last column of the matrix is not required, because its values are constant.

You can retrieve the elements of the current world transformation matrix by calling the GetWorldTransform function and supplying a pointer to an XFORM structure.


Page-Space to Device-Space Transformations

The page-space to device-space transformation was part of the original Windows interface. This transformation determines the mapping mode for all graphics output associated with a particular device context. A mapping mode is a scaling transformation that specifies the size of the units used for drawing operations. In some cases, the mapping mode alters the orientation of the x-axis and the y-axis in device space. The mapping modes are described in the following table.

Mapping mode	Description

MM_ANISOTROPIC	Each unit in page space is mapped to an application-specified unit in device space. The axis may or may not be equally scaled (for example, a circle drawn in world space may appear to be an ellipse when depicted on a given device). The orientation of the axis is also specified by the application.

MM_HIENGLISH	Each unit in page space is mapped to 0.001 inch in device space. Increasing values of x occur as you move to the right; increasing values of y occur as you move up.

MM_HIMETRIC	Each unit in page space is mapped to 0.01 millimeter in device space. Increasing values of x occur as you move to the right; increasing values of y occur as you move up.

MM_ISOTROPIC	Each unit in page space is mapped to an application-defined unit in device space. The axes are always equally scaled. The orientation of the axes may be specified by the application.

MM_LOENGLISH	Each unit in page space is mapped to 0.01 inch in device space. Increasing values of x occur as you move to the right; increasing values of y occur as you move up.

MM_LOMETRIC	Each unit in page space is mapped to 0.1 millimeter in device space. Increasing values of x occur as you move to the right; increasing values of y occur as you move up.

MM_TEXT	Each unit in page space is mapped to one pixel. Increasing values of x occur as you move to the right; increasing values of y occur as you move down.

MM_TWIPS	Each unit in page space is mapped to one twentieth of a printer's point (1/1440 inch). Increasing values of x occur as you move to the right; increasing values of y occur as you move down.

You set a mapping mode by calling the SetMapMode function. You retrieve the current mapping mode for a device context by calling the GetMapMode function.

Unlike the world-space to page-space transformations that use a 3-by-3 matrix, the page-space to device-space transformations use the width and height ratios of two rectangles: the rectangle in page space is called a window and the rectangle in device space is called a viewport. The transformation occurs when Windows maps the window origin to the viewport origin and the window extents to the viewport extents, as shown in the following figure.

For the six predefined mapping modes (MM_HIENGLISH, MM_LOENGLISH, MM_HIMETRIC, MM_LOMETRIC, MM_TEXT, and MM_TWIPS), the width and height of these rectangles are set by Windows when you call SetMapMode. They cannot be changed. The other two mapping modes (MM_ISOTROPIC and MM_ANISOTROPIC) require that you specify the width and height of these rectangles. This is done by calling SetMapMode to set the appropriate mode and then calling SetViewportExtEx and SetWindowExtEx to specify the width and height of each rectangle.

Predefined Mapping Modes

Of the six predefined mapping modes, one is device dependent (MM_TEXT), while the remaining five (MM_HIENGLISH, MM_LOENGLISH, MM_HIMETRIC, MM_LOMETRIC, and MM_TWIPS) are device independent.

The device-dependent mapping mode is provided for text-output operations that use device-specific fonts. Device-specific fonts are fonts created for a device with a specific aspect ratio. The aspect ratio of a device is the ratio formed by the width and height of a single pixel. You can retrieve a device's aspect ratio and the total number of device-specific fonts by calling the GetDeviceCaps function. You can limit the user's selection of fonts to only device-specific fonts by calling the ChooseFont function and setting the CF_PRINTERFONTS or CF_SCREENFONTS constants.

The device-independent mapping modes are provided for non-text drawing operations. If your application displays geometric shapes (circles, squares, polygons, and so on), choose one of the device-independent mapping modes. For example, if you are writing code to provide charting capabilities for a spreadsheet application and want to can guarantee that the diameter of each pie chart is 2 inches, you can choose the MM_LOENGLISH mapping mode and call the appropriate functions to draw and fill the charts. By specifying MM_LOENGLISH, you guarantee that the diameter of the charts are consistent on any display or printer. (If you were to choose MM_TEXT instead of MM_LOENGLISH, a chart that appears circular on a VGA display would appear elliptical on an EGA display and would appear very small on a 300 dpi laser printer.)

Application-Defined Mapping Modes

The two application-defined mapping modes (MM_ISOTROPIC and MM_ANISOTROPIC) are provided for application-specific mapping modes. The MM_ISOTROPIC mode guarantees that logical units in the x-direction and in the y-direction are equal, while the MM_ANISOTROPIC mode allows the units to differ. A CAD or drawing application can benefit from the MM_ISOTROPIC mapping mode but may need to specify logical units that correspond to the increments on an engineer's scale (1/64 inch). These units would be difficult to obtain with the predefined mapping modes (MM_HIENGLISH or MM_HIMETRIC); however, they can easily be obtained by selecting the MM_ISOTROPIC mode, setting the window extents to the width and height of the display (expressed in units of 1/64 inch) and setting the viewport width and height to the width and height of the display in pixels.


Device-Space to Physical-Device Transformation

The device-space to physical-device transformation is unique in several respects: It is limited to translation and is controlled by the window manager component of Windows. The sole purpose of this transformation is to ensure that the origin of device space is mapped to the proper point on the physical device. There are no functions to set this transformation, nor are there any functions to retrieve related data.


Default Transformations

Whenever an application creates a device context and immediately begins calling GDI drawing or output functions, it takes advantage of the default page-space to device-space, and device-space to client-area transformations. (World-to-page space transformation cannot happen until the application calls the SetWorldTransform function.)

The default page-space to device-space transformation results in a one-to-one mapping; that is, a given point in page space maps to the same point in device space. As previously mentioned, this transformation is not specified by a matrix. Instead, it is obtained by dividing the width of the viewport by the width of the window and the height of the viewport by the height of the window. In the default case, the viewport dimensions are 1-pixel by 1-pixel and the window dimensions are 1-page unit by 1-page unit.

The device-space to physical-device (client area, desktop, or printer paper) transformation always results in a one-to-one mapping; that is, one unit in device space is always equivalent to one unit in the client area, on the desktop, or on a page. The sole purpose of this transformation is translation; it ensures that output appears correctly in an application's window no matter where that window is moved on the desktop.

The one unique aspect of the default transformation is the orientation of the y-axis in device space and the application's window. In the default case, the positive y-axis extends downward and the negative y-axis extends upward.


Using Coordinates Spaces and Transformations

This section contains an example that demonstrates the following tasks.

Drawing graphics with predefined units

Centering graphics in the application's client area

Scaling graphics output to half its original size

Translating graphics output 3/4 of an inch to the right

Rotating graphics 30 degrees

Shearing graphics output along the x-axis

Reflecting graphics output about an imaginary horizontal axis drawn through its midpoint

The following example was used to create the illustrations that appear earlier in this topic.

void TransformAndDraw(int iTransform, HWND hWnd)

{

HDC hDC;

XFORM xForm;

RECT rect;

/* Retrieve a DC handle for the application's window. */

hDC = GetDC(hWnd);

/*

 * Set the mapping mode to LOENGLISH. This moves the

 * client-area origin from the upper-left corner of the

 * window to the lower-left corner (this also reorients

 * the y-axis so that drawing operations occur in a true

 * Cartesian space). It guarantees portability so that

 * the object drawn retains its dimensions on any

 * display running Windows.

 */

SetMapMode(hDC, MM_LOENGLISH);

/*

 * Set the appropriate world transformation (based on the

 * user's menu selection).

 */

switch (iTransform) {

        case SCALE: /* Scale to 1/2 of the original size. */

            xForm.eM11 = (FLOAT) 0.5;

            xForm.eM12 = (FLOAT) 0.0;

            xForm.eM21 = (FLOAT) 0.0;

            xForm.eM22 = (FLOAT) 0.5;

            xForm.eDx  = (FLOAT) 0.0;

            xForm.eDy  = (FLOAT) 0.0;

            SetWorldTransform(hDC, &xForm);

            break;

        case TRANSLATE: /* Translate right by 3/4 inch. */

            xForm.eM11 = (FLOAT) 1.0;

            xForm.eM12 = (FLOAT) 0.0;

            xForm.eM21 = (FLOAT) 0.0;

            xForm.eM22 = (FLOAT) 1.0;

            xForm.eDx  = (FLOAT) 75.0;

            xForm.eDy  = (FLOAT) 0.0;

            SetWorldTransform(hDC, &xForm);

            break;

        case ROTATE: /* Rotate 30 degrees counterclockwise. */

            xForm.eM11 = (FLOAT) 0.8660;

            xForm.eM12 = (FLOAT) 0.5000;

            xForm.eM21 = (FLOAT) -0.5000;

            xForm.eM22 = (FLOAT) 0.8660;

            xForm.eDx  = (FLOAT) 0.0;

            xForm.eDy  = (FLOAT) 0.0;

            SetWorldTransform(hDC, &xForm);

            break;

        case SHEAR: /* Shear along the x-axis with a    */

                          /* proportionality constant of 1.0. */

            xForm.eM11 = (FLOAT) 1.0;

            xForm.eM12 = (FLOAT) 1.0;

            xForm.eM21 = (FLOAT) 0.0;

            xForm.eM22 = (FLOAT) 1.0;

            xForm.eDx  = (FLOAT) 0.0;

            xForm.eDy  = (FLOAT) 0.0;

            SetWorldTransform(hDC, &xForm);

            break;

        case REFLECT: /* Reflect about a horizontal axis. */

            xForm.eM11 = (FLOAT) 1.0;

            xForm.eM12 = (FLOAT) 0.0;

            xForm.eM21 = (FLOAT) 0.0;

            xForm.eM22 = (FLOAT) -1.0;

            xForm.eDx  = (FLOAT) 0.0;

            xForm.eDy  = (FLOAT) 0.0;

            SetWorldTransform(hDC, &xForm);

            break;

        case NORMAL: /* Set the unity transformation. */

            xForm.eM11 = (FLOAT) 1.0;

            xForm.eM12 = (FLOAT) 0.0;

            xForm.eM21 = (FLOAT) 0.0;

            xForm.eM22 = (FLOAT) 1.0;

            xForm.eDx  = (FLOAT) 0.0;

            xForm.eDy  = (FLOAT) 0.0;

            SetWorldTransform(hDC, &xForm);

            break;

    }

/* Find the midpoint of the client area. */

GetClientRect(hWnd, (LPRECT) &rect);

DPtoLP(hDC, (LPPOINT) &rect, 2);

/* Select a hollow brush. */

SelectObject(hDC, GetStockObject(HOLLOW_BRUSH));

/* Draw the exterior circle. */

Ellipse(hDC, (rect.right / 2 - 100), (rect.bottom / 2 + 100),

    (rect.right / 2 + 100), (rect.bottom / 2 - 100));

/* Draw the interior circle. */

Ellipse(hDC, (rect.right / 2 -94), (rect.bottom / 2 + 94),

    (rect.right / 2 + 94), (rect.bottom / 2 - 94));

/* Draw the key. */

Rectangle(hDC, (rect.right / 2 - 13), (rect.bottom / 2 + 113),

    (rect.right / 2 + 13), (rect.bottom / 2 + 50));

Rectangle(hDC, (rect.right / 2 - 13), (rect.bottom / 2 + 96),

    (rect.right / 2 + 13), (rect.bottom / 2 + 50));

/* Draw the horizontal lines. */

MoveToEx(hDC, (rect.right / 2 - 150), (rect.bottom / 2 + 0), NULL);

LineTo(hDC, (rect.right / 2 - 16), (rect.bottom / 2 + 0));

MoveToEx(hDC, (rect.right / 2 - 13), (rect.bottom / 2 + 0), NULL);

LineTo(hDC, (rect.right / 2 + 13), (rect.bottom / 2 + 0));

MoveToEx(hDC, (rect.right / 2 + 16), (rect.bottom / 2 + 0), NULL);

LineTo(hDC, (rect.right / 2 + 150), (rect.bottom / 2 + 0));

/* Draw the vertical lines. */

MoveToEx(hDC, (rect.right / 2 + 0), (rect.bottom / 2 - 150), NULL);

LineTo(hDC, (rect.right / 2 + 0), (rect.bottom / 2 - 16));

MoveToEx(hDC, (rect.right / 2 + 0), (rect.bottom / 2 - 13), NULL);

LineTo(hDC, (rect.right / 2 + 0), (rect.bottom / 2 + 13));

MoveToEx(hDC, (rect.right / 2 + 0), (rect.bottom / 2 + 16), NULL);

LineTo(hDC, (rect.right / 2 + 0), (rect.bottom / 2 + 150));

ReleaseDC(hWnd, hDC);

}


Functions

Following are the functions used with coordinate spaces and transformations.

ClientToScreen

CombineTransform

DPtoLP

GetCurrentPositionEx

GetMapMode

GetViewportExtEx

GetViewportOrgEx

GetWindowExtEx

GetWindowOrgEx

GetWorldTransform

LPtoDP

ModifyWorldTransform

OffsetViewportOrgEx

OffsetWindowOrgEx

ScaleViewportExtEx

ScaleWindowExtEx

ScreenToClient

SetMapMode

SetViewportExtEx

SetViewportOrgEx

SetWindowExtEx

SetWindowOrgEx

SetWorldTransform


Metafiles Overview

About Metafiles

Applications written for Microsoft® Windows™ use two graphics tools to store pictures: metafiles and bitmaps. For information about bitmaps, see Bitmaps. This topic describes metafiles.

A metafile is a collection of structures that store a picture in a device-independent format. Device independence is the one feature that sets metafiles apart from bitmaps: Unlike a bitmap, a metafile guarantees device independence. For example, when an application creates a picture measuring 2 by 2 inches on a VGA display and stores that picture in a metafile, the picture maintains its original dimensions when printed on a 300 dpi laser printer or copied over a network and displayed in another application that is running on an 8514/A video display. There is a drawback to metafiles, however: they are generally drawn more slowly than bitmaps. Therefore, if an application requires fast drawing and device independence is not an issue, it should use bitmaps instead of metafiles.

The following topics discuss Win32 metafiles:

Terms

Enhanced-Format Metafiles

Enhanced Metafile Records

Enhanced Metafile Operations

Windows-Format Metafiles

Creating an Enhanced Metafile

Displaying a Picture and Storing it in an Enhanced Metafile

Opening an Enhanced Metafile and Displaying its Contents

Editing an Enhanced Metafile

Functions

Internally, a metafile is an array of variable-length structures called metafile records. The first records in the metafile specify general information such as the resolution of the device on which the picture was created, the dimensions of the picture, and so on. The remaining records, which constitute the bulk of any metafile, correspond to the graphics device interface (GDI) functions required to draw the picture. These records are stored in the metafile after a special metafile device context (DC) is created. This DC is then used for all drawing operations required to create the picture. When Windows processes a GDI function associated with a metafile DC, it converts the function into the appropriate data and stores this data in a record appended to the metafile.

After a picture is complete and the last record is stored in the metafile, the metafile can be passed to another application by means of the clipboard, embedded within another file, stored on disk, or played repeatedly. A metafile is played when its records are converted to device commands and processed by the appropriate device.

There are two types of metafiles: enhanced and Windows. An enhanced metafile is used in applications written using the Win32 application programming interface (API). The enhanced format consists of a header, a table of handles to GDI objects, a private palette, and an array of metafile records. Enhanced metafiles provide true device independence. (You can think of the picture stored in an enhanced metafile as a "snapshot" of the video display taken at a particular moment. This "snapshot" maintains its dimensions no matter where it appears: on a printer, a plotter, or the desktop, or in the client area of any Win32 application.)

A Windows metafile is used for applications written using the Windows version 3.x application programming interface (API). The Windows format consists of a header and an array of metafile records. Windows-format metafiles are limited in their capabilities and should rarely be used--the Windows-metafile API is supported to maintain backward compatibility with applications that were written to run with Windows version 3.x.


Enhanced-Format Metafiles

A developer can use enhanced metafiles to store a picture created by using the Win32 GDI functions (including new path and transformation functions). Because the enhanced metafile format is standardized for the Win32 application programming interface (API), pictures that are stored in this format can be copied from one Win32 application to another; and, because the pictures are truly device independent, they are guaranteed to maintain their shape and proportion on any output device.


Enhanced Metafile Records

Enhanced Metafile Records

An enhanced metafile is an array of records. A metafile record is a variable-length ENHMETARECORD structure. This structure identifies the record type, specifies the record length, and contains additional data that is dependent on the record type.

The first record in an enhanced metafile is always the enhanced-metafile header. The header specifies the following information:

Size of the metafile, in bytes

Dimensions of the picture frame, in device units

Dimensions of the picture frame, in .01-millimeter units

Number of records in the metafile

Offset to an optional text description

Size of the optional palette

Resolution of the original device, in pixels

Resolution of the original device, in millimeters

An optional text description can follow the header record. The text description describes the picture and the author's name. The optional palette specifies the colors used to create the enhanced metafile. The remaining records identify the GDI functions used to create the picture. The following hexadecimal output corresponds to a record generated for a call to the SetMapMode function.

00000011 0000000C 00000004

The value 0x00000011 specifies the record type (corresponds to the EMR_SETMAPMODE constant defined in the file WINGDI.H). The value 0x0000000C specifies the length of the record, in bytes. The value 0x00000004 identifies the mapping mode (corresponds to the MM_LOENGLISH constant defined in the file WINGDI.H).


Enhanced Metafile Operations

Enhanced Metafile Operations

A developer creates an enhanced metafile by using the CreateEnhMetaFile function and supplying the appropriate arguments. The Win32 API uses these arguments to maintain picture dimensions, to determine whether the metafile should be stored on a disk or in memory, and so on.

To maintain picture dimensions across output devices, the Win32 API requires the resolution of the reference device. This reference device is the device on which the picture first appeared, and the reference DC is the device context (DC) associated with the reference device. When calling the CreateEnhMetaFile function, the application must supply a handle that identifies this DC. The application can get this handle by calling the GetDC or CreateDC function.

Most applications store pictures permanently and therefore create an enhanced metafile that is stored on a disk; however, there are some instances when this is not necessary. For example, a word processing application that provides chart-drawing capabilities could store a user-defined chart in memory as an enhanced metafile and then copy the enhanced metafile bits from memory into the user's document file. An application that requires a metafile that is stored permanently on a disk must supply the filename when it calls the CreateEnhMetaFile function. If the developer does not supply a filename, Windows automatically treats the metafile as a temporary file and stores it in memory.

The developer can add an optional text description to a metafile containing information about the picture and the author. An application can display these strings in the File Open dialog box to provide the user with information about metafile contents that will help in selecting the appropriate file. If an application includes the text description, the application must supply a pointer to the string when it calls the CreateEnhMetaFile function.

When the CreateEnhMetaFile function is successful, it returns a handle that identifies a special metafile device context. A metafile DC is unique in that it is associated with a file rather than with an output device. When Windows processes a GDI function that received a handle to a metafile DC, it converts the GDI function into an enhanced-metafile record and appends the record to the end of the enhanced metafile.

After a picture is complete and the last record is appended to the enhanced metafile, the application can close the file by calling the CloseEnhMetaFile function. This function closes and deletes the special metafile DC and returns a handle identifying the enhanced metafile. The application can use this handle to accomplish the following tasks:

Display the picture stored in the enhanced metafile

Create copies of the enhanced metafile

Enumerate, edit, or copy the individual records in the enhanced metafile

Retrieve the optional description that is stored in the enhanced metafile

Retrieve a copy of the enhanced-metafile header

Retrieve a binary version of the enhanced metafile

Enumerate the colors in the optional palette

Convert an enhanced-format metafile into a Windows-format metafile

Some applications create temporary backup (or duplicate) copies of a file before enabling the user to alter the original. An application can create a backup copy of an enhanced metafile by calling the CopyEnhMetaFile function, supplying a handle that identifies the enhanced metafile, and supplying a pointer to the name of the new file.

Most drawing, illustration, and computer-aided design (CAD) applications require a means of editing a picture stored in an enhanced metafile. Although editing an enhanced metafile is a complex task, a developer can use the EnumEnhMetaFile function in combination with other Win32 functions to provide this capability in your application. The EnumEnhMetaFile function and its associated callback function enable the application to process individual records in an enhanced metafile.

Some applications display the text description of an enhanced metafile with the corresponding filename in the File Open dialog box. An application can determine whether this string exists in an enhanced metafile by retrieving the metafile header and examining one of its members. The GetEnhMetaFileHeader function can retrieve the metafile header. If the string exists, the application retrieves it by calling the GetEnhMetaFileDescription function.

Some applications retrieve the contents of a metafile by calling the GetEnhMetaFileBits function; however, before retrieving the contents, the application must specify the size of the file. To get the size, the application can use the GetEnhMetaFileHeader function and examine the appropriate member.

To achieve consistent colors when a picture is displayed on various output devices, an application can call the CreatePalette function and store a logical palette in an enhanced metafile. Other applications that display the picture stored in the enhanced metafile retrieve this palette and call the RealizePalette function before displaying the picture. To determine whether a palette is stored in an enhanced metafile, an application can retrieve the metafile header and examine the appropriate member. If a palette exists, the application can call the GetEnhMetaFilePaletteEntries function to retrieve the logical palette.


Windows-Format Metafiles

The Win32 API supports the Windows metafile format to maintain compatibility with applications written for Windows version 3.x. Following are the limitations of this format:

A Windows-format metafile is application and device dependent. Changes in the application's mapping modes or the device resolution affect the appearance of metafiles created in this format.

A Windows-format metafile does not contain a comprehensive header that describes the original picture dimensions, the resolution of the device on which the picture was created, an optional text description, or an optional palette.

A Windows-format metafile does not support the new curve, path, and transformation functions.

Some Windows-format metafile records cannot be scaled.

The metafile device context associated with a Windows-format metafile cannot be queried (that is, an application cannot retrieve device-resolution data, font metrics, and so on).

To convert a Windows-format metafile to an enhanced-format metafile, an application can call the GetMetaFileBitsEx function to retrieve the data from the Windows-format metafile and then call the SetWinMetaFileBits function to convert this data into an enhanced-format metafile.

A developer writing a Win32 application should avoid using the Windows-format functions and use the enhanced-format functions instead.


Creating an Enhanced Metafile

This section contains an example that demonstrates the creation of an enhanced metafile that is stored on a disk, using a filename specified by the user.

The example uses a device context for the application window as the reference DC. (Windows stores the resolution data for this device in the enhanced-metafile's header.) The application retrieves a handle identifying this DC by calling the GetDC function.

The example uses the dimensions of the application's client area to define the dimensions of the picture frame. Using the rectangle dimensions returned by the GetClientRect function, the application converts the device units to .01-millimeter units and passes the converted values to the CreateEnhMetaFile function.

The example displays a Save As common dialog box that enables the user to specify the filename of the new enhanced metafile. The system appends the three-character .EMF extension to this filename and passes the name to the CreateEnhMetaFile function.

The example also embeds a text description of the picture in the enhanced-metafile header. This description is specified as a resource in the string table of the application's resource file. However, in a working application, this string would be retrieved from a custom control in a common dialog box or from a separate dialog box displayed solely for this purpose.

/* Obtain a handle to a reference DC. */

hdcRef = GetDC(hWnd);

/*

 * Determine the picture frame dimensions.

 * iWidthMM is the display width in millimeters.

 * iHeightMM is the display height in millimeters.

 * iWidthPels is the display width in pixels.

 * iHeightPels is the display height in pixels

 */

iWidthMM = GetDeviceCaps(hdcRef, HORZSIZE);

iHeightMM = GetDeviceCaps(hdcRef, VERTSIZE);

iWidthPels = GetDeviceCaps(hdcRef, HORZRES);

iHeightPels = GetDeviceCaps(hdcRef, VERTRES);

/*

 * Use iWidthMM, iWidthPels, iHeightMM, and

 * iHeightPels to determine the number of

 * .01-millimeter units per pixel in the x-

 *  and y-directions.

 */

iMMPerPelX = (iWidthMM * 100)/iWidthPels;

iMMPerPelY = (iHeightMM * 100)/iHeightPels;

/*

 * Retrieve the coordinates of the client

 * rectangle, in pixels.

 */

GetClientRect(hWnd, &rect);

/* Convert client coordinates to .01-mm units. */

rect.left = rect.left * iMMPerPelX;

rect.top = rect.top * iMMPerPelY;

rect.right = rect.right * iMMPerPelX;

rect.bottom = rect.bottom * iMMPerPelY;

/* Load the filename filter from the string table. */

LoadString(hInst, IDS_FILTERSTRING,

     (LPSTR)szFilter, sizeof(szFilter));

/*

 * Replace the '%' separators that are embedded

 * between the strings in the string-table entry

 * with '\0'.

 */

for (i=0; szFilter[i]!='\0'; i++)

    if (szFilter[i] == '%')

            szFilter[i] = '\0';

/* Load the dialog title string from the table. */

LoadString(hInst, IDS_TITLESTRING,

     (LPSTR)szTitle, sizeof(szTitle));

/* Initialize the OPENFILENAME members. */

szFile[0] = '\0';

Ofn.lStructSize = sizeof(OPENFILENAME);

Ofn.hwndOwner = hWnd;

Ofn.lpstrFilter = szFilter;

Ofn.lpstrFile= szFile;

Ofn.nMaxFile = sizeof(szFile);

Ofn.lpstrFileTitle = szFileTitle;

Ofn.nMaxFileTitle = sizeof(szFileTitle);

Ofn.lpstrInitialDir = (LPSTR)NULL;

Ofn.Flags = OFN_SHOWHELP | OFN_OVERWRITEPROMPT;

Ofn.lpstrTitle = szTitle;

/*

 * Display the Filename common dialog box. The

 * filename specified by the user is passed

 * to the CreateEnhMetaFile function and used to

 * store the metafile on disk.

 */

GetSaveFileName(&Ofn);

/* Load the description from the string table. */

LoadString(hInst, IDS_DESCRIPTIONSTRING,

     (LPSTR)szDescription, sizeof(szDescription));

/*

 * Replace the '%' string separators that are

 * embedded between strings in the string-table

 * entry with '\0'.

 */

for (i=0; szDescription[i]!='\0'; i++)

    if (szDescription[i] == '%')

            szDescription[i] = '\0';

/* Create the metafile DC. */

hdcMeta = CreateEnhMetaFile(hdcRef,

          (LPTSTR) Ofn.lpstrFile,

          &rect, (LPSTR)szDescription);

if (!hdcMeta)

    errhandler("CreateEnhMetaFile", hWnd);

/* Release the reference DC. */

ReleaseDC(hWnd, hdcRef);


Displaying a Picture and Storing It in an Enhanced Metafile

This section contains a code sample demonstrating the creation of a picture and the process of storing the corresponding records in a metafile. The code draws a picture to the display or stores it in a metafile. If a display DC handle is given, it draws a picture to the screen using various GDI functions. If an enhanced metafile DC is given, it stores the same picture in the enhanced metafile.

void DrawOrStore(HWND hwnd, HDC hdcMeta, HDC hdcDisplay)

{

RECT rect;

HDC hDC;

int fnMapModeOld;

HBRUSH hbrOld;

/* Draw it to the display DC or store it in the metafile DC. */

if (hdcMeta)

    hDC = hdcMeta;

else

    hDC = hdcDisplay;

/* Set the mapping mode in the DC. */

fnMapModeOld = SetMapMode(hDC, MM_LOENGLISH);

/* Find the midpoint of the client area. */

GetClientRect(hwnd, (LPRECT)&rect);

DPtoLP(hDC, (LPPOINT)&rect, 2);

/* Select a gray brush. */

hbrOld = SelectObject(hDC, GetStockObject(GRAY_BRUSH));

/* Draw an circle with an one inch raduis. */

Ellipse(hDC, (rect.right/2 - 100), (rect.bottom/2 + 100),

       (rect.right/2 + 100), (rect.bottom/2 - 100));

    .

    . /* Perform remaining drawing and clean-up operations. */

    .

}


Opening an Enhanced Metafile and Displaying its Contents

Opening an Enhanced Metafile and Displaying Its Contents

This section contains a code sample demonstrating how an application opens an enhanced metafile stored on disk and displays the associated picture in the client area.

The example uses the Open common dialog box to enable the user to select an enhanced metafile from a list of existing files. It then passes the name of the selected file to the GetEnhMetaFile function, which returns a handle identifying the file. This handle is passed to the PlayEnhMetaFile function in order to display the picture.

LoadString(hInst, IDS_FILTERSTRING,

     (LPSTR)szFilter, sizeof(szFilter));

/*

 * Replace occurrences of '%' string separator

 * with '\0'.

 */

for (i=0; szFilter[i]!='\0'; i++)

    if (szFilter[i] == '%')

            szFilter[i] = '\0';

LoadString(hInst, IDS_DEFEXTSTRING,

     (LPSTR)szDefExt, sizeof(szFilter));

/*

 * Use the OpenFilename common dialog box

 * to obtain the desired filename.

 */

 szFile[0] = '\0';

 Ofn.lStructSize = sizeof(OPENFILENAME);

 Ofn.hwndOwner = hWnd;

 Ofn.lpstrFilter = szFilter;

 Ofn.lpstrCustomFilter = (LPSTR)NULL;

 Ofn.nMaxCustFilter = 0L;

 Ofn.nFilterIndex = 1L;

 Ofn.lpstrFile = szFile;

 Ofn.nMaxFile = sizeof(szFile);

 Ofn.lpstrFileTitle = szFileTitle;

 Ofn.nMaxFileTitle = sizeof(szFileTitle);

 Ofn.lpstrInitialDir = (LPSTR) NULL;

 Ofn.lpstrTitle = (LPSTR)NULL;

 Ofn.Flags = OFN_SHOWHELP | OFN_PATHMUSTEXIST | OFN_FILEMUSTEXIST;

 Ofn.nFileOffset = 0;

 Ofn.nFileExtension = 0;

 Ofn.lpstrDefExt = szDefExt;

 GetOpenFileName(&Ofn);

/* Open the metafile. */

hemf = GetEnhMetaFile(Ofn.lpstrFile);

/* Retrieve a handle to a window DC. */

hDC = GetDC(hWnd);

/* Retrieve the client rectangle dimensions. */

GetClientRect(hWnd, &rct);

/* Draw the picture. */

PlayEnhMetaFile(hDC, hemf, &rct);

/* Release the metafile handle. */

DeleteEnhMetaFile(hemf);

/* Release the window DC. */

ReleaseDC(hWnd, hDC);


Editing an Enhanced Metafile

To edit a picture stored in an enhanced metafile, an application must perform the following tasks:

1	Use hit-testing to capture the cursor coordinates and retrieve the position of the object (line, arc, rectangle, ellipse, polygon, or irregular shape) that the user wants to alter.

2	Convert these coordinates to logical (or world) units.

3	Call the EnumEnhMetaFile function and examine each metafile record.

4	Determine whether a given record corresponds to a GDI drawing function.

5	If it does, determine whether the coordinates stored in the record correspond to the line, arc, ellipse, or other graphics element that intersects the coordinates specified by the user.

6	Upon finding the record that corresponds to the output that the user wants to alter, erase the object on the screen that corresponds to the original record.

7	Delete the corresponding record from the metafile, saving a pointer to its location.

8	Permit the user to redraw or replace the object.

9	Convert the GDI functions used to draw the new object into one or more enhanced-metafile records.

10	Store these records in the enhanced metafile.


Functions

Following are the functions used with enhanced format metafiles.

CloseEnhMetaFile

CopyEnhMetaFile

CreateEnhMetaFile

DeleteEnhMetaFile

EnhMetaFileProc

EnumEnhMetaFile

GdiComment

GetEnhMetaFile

GetEnhMetaFileBits

GetEnhMetaFileDescription

GetEnhMetaFileHeader

GetEnhMetaFilePaletteEntries

GetWinMetaFileBits

PlayEnhMetaFile

PlayEnhMetaFileRecord

SetEnhMetaFileBits

SetWinMetaFileBits

The following functions are provided for compatibility with Windows-format metafiles:

CloseMetaFile

CopyMetaFile

CreateMetaFile

DeleteMetaFile

EnumMetaFile

EnumMetaFileProc

GetMetaFile

GetMetaFileBitsEx

PlayMetaFile

PlayMetaFileRecord

SetMetaFileBitsEx


Printing and Print Spooler Overview

About Printing

Microsoft® Windows™ provides a complete set of functions that allow applications to print on a variety of devices: laser printers, vector plotters, raster printers, and fax machines. One of the chief features of these functions is their support of device independence; instead of issuing device-specific commands to draw output on a particular printer or plotter, an application calls high-level functions from the graphics device interface (GDI). For example, to print a bitmapped image, an application would call the BitBlt function, supplying the coordinates for the bitmap as well as handles identifying the source and destination device contexts. The BitBlt function call would then be converted to raw device commands by a printer device driver. The device driver is a Windows dynamic-link library (DLL) that supports the Windows device-driver interface (DDI). A device driver generates raw device commands when it processes the DDI function calls made by the graphics engine. The graphics engine is a Windows DLL that converts print-processor output into device-driver function calls. These commands are processed by the printer when it prints the image. The syntax, number, and type of these commands vary from device to device.

The following topics discuss printing:

Terms

Default Printing Interface

Printer Device Contexts

Printer Escapes

WYSIWYG Display and Output

Opening and Displaying a .BMP File

Displaying a Print Dialog Box and Retrieving a Printer Device Context

Preparing to Print

Printing a Document

Functions


Default Printing Interface

In addition to GDI and the device driver, the default in the Win32 API printing interface consists of several other components that process output before it arrives at the printer. These components are the print spooler, the print processor, the graphics engine, and the monitor.

Print Spooler

The primary component of the printing interface is the print spooler. The print spooler is a Windows executable file that manages the printing process. This includes retrieving the location of the correct printer driver, loading that driver, converting high-level-function calls to journal records, storing those journal records on disk as a print job, and so on.

The spooler is loaded at startup and continues to run until the operating system is shut down. Windows Print Manager provides a graphic interface that the user or system administrator can use to access and configure the spooler; however, if Print Manager is disabled or shut down, the spooler continues to run.

Applications that print create a printer device context (DC). When an application creates a printer DC, the spooler performs necessary tasks such as determining the location of the required printer driver, then loading the appropriate printer driver. It also determines the data type used to record the print job. The supported data types include: journal records, ASCII text, and PostScript. A print job is a document stored internally (by using one of the supported data types) that may contain one or more pages of output. It may consist of multiple forms; for example, a job may consist of one envelope and three pages of A4 paper. A print job is defined (or bracketed) by two functions: StartDoc and EndDoc.

The default data type for a print job is the journal record. A journal record is a compact data structure used to store text-output commands, raster-graphics commands, and so on. When an application calls the StartDoc function, the spooler creates a journal file and a data file, and begins storing journal records in the journal file. Each time the application calls one of the GDI drawing functions, one or more new journal records are created and stored in the journal file. The journal and data files are created in an operating-system directory. The spooler uses the journal file to store journal records, and uses the data file to record the type of form, the print-job data type, the target printer, and so on. These files are deleted by the spooler when the job has successfully printed.

Print Processor

The spooler monitors the current print jobs and the target printer to determine the appropriate time to print a job. Once the spooler determines that a job should be printed, it calls the print processor. The print processor is a Windows DLL that reads and converts journal records into DDI calls.

Graphics Engine

The graphics engine converts the print processor output into device-driver function calls. The device driver, in turn, processes these calls and converts them into raw device commands that the device can process.

Monitor

Once a device driver has converted an entire journal file into raw device commands, the file of converted commands is passed back to the spooler. The spooler sends these low-level commands to a monitor. A monitor is a Windows DLL that passes the raw device commands over the network, through a parallel port, or through a serial port and to the device.


Printer Device Contexts

Just as an application requires a display DC before it can begin drawing in the client area of a window, it needs a special printer DC before it can begin sending output to a printer. A printer DC is similar to a display DC in that it is an internal data structure that defines a set of graphic objects and their associated attributes, and the graphic modes that affect output. The graphic objects include a pen (for line drawing), a brush (for painting and filling), and a font (for text output).

Unlike a display DC, printer DCs are not owned by the window manager component and cannot be obtained by calling the GetDC function. Instead, an application must call the CreateDC or PrintDlg function. When an application calls the CreateDC function, it must supply a driver and port name. This data is stored in one of the operating system initialization (.INI) files. It can be retrieved by calling the EnumPrinters function.

When an application calls the PrintDlg function and sets the PD_RETURNDC constant in the Flags member of the PRINTDLG structure, Windows automatically returns a handle identifying the user's selected printer device context. For an example of code that demonstrates this task, see Displaying a Print Dialog Box and Retrieving a Printer Device Context.


Printer Escapes

Windows version 3.x supported as many as 64 special functions called printer escapes that applications used to access special device features. An application calls these functions by specifying one of 64 predefined constants as the second argument to the Escape function. For example, one of these application printing on a PostScript printer could draw a PostScript graphics object called a path by calling the Escape function and supplying the BEGIN_PATH and END_PATH constants. Improvements to GDI in the Win32 API have made many of these escapes obsolete. As a case in point, the Win32 version of GDI supports a complete set of path functions that applications can use to draw paths on any device; thus, these new functions render the previous printer escapes obsolete.

Of the 64 original printer escapes, only 11 are supported in the Win32 API. However, of these 11, only 2 (QUERYESCSUPPORT and PASSTHROUGH) should be called by applications developed for the Win32 API. The remaining 9 are supported strictly for compatibility with applications written for Windows 3.x.

Following are the 11 supported escapes:

ABORTDOC

ENDDOC

GETPHYSPAGESIZE

GETPRINTINGOFFSET

GETSCALINGFACTOR

NEWFRAME

NEXTBAND

PASSTHROUGH

QUERYESCSUPPORT

SETABORTPROC

In addition to supporting the original Escape function, the Win32 API supports a new extended escape function ExtEscape. This function allows applications to access capabilities of a particular device not directly available through GDI.


WYSIWYG Display and Output

Most applications attempt to support what you see is what you get (WYSIWYG) output. This means that text drawn with a 10-point Helvetica Bold font in the application's window should have a similar appearance when it is printed. Obtaining true WYSIWYG output is virtually impossible and even undesirable in most cases. This is due, in part, to the differences in video and printer technologies; a pixel on a screen is generally larger than a dot on a common laser printer. Viewing distances are different as well; a computer user typically sits about two feet away from the screen, but a reader's eyes are usually one foot or less from the printed page.

To compensate for legibility differences between screens and the printed page, Windows supports a unit called the logical inch that is always specified in pixels. For a video display, the logical inch is always greater than the physical inch, to compensate for the longer viewing distance and the (generally) coarser resolution. For printers, the logical inch is always equal to the physical inch.

To obtain WYSIWYG effects when drawing text, applications can use the CreateFont function to specify the typeface name and point size of an ideal (or logical) font, then call the SelectObject function to identify the display or printer DC. When the application calls the SelectObject function, Windows selects a physical font that is the closest possible match to the specified logical font. When Windows selects the display font, it chooses a physical font that is larger than the actual point size. From the user's perspective, however, it appears to be very close to the correct height. When Windows selects the font for the printer, it chooses a physical font that is actually the requested point size.

To obtain WYSIWYG effects when drawing bitmapped graphics, applications can retrieve the width and height, in logical inches, of the screen and the printed page. Using these values, the application can create horizontal and vertical scaling factors to maintain the proportion of bitmapped images when they are drawn on a printer.


Using the Printing Functions

This section contains code examples that demonstrate how to print text and graphics. The code was taken from an application that allows a user to open and display a 16-color bitmapped image stored as a .BMP file. The following illustration shows the application's window after the user opened the file WINLOGO.BMP.

In addition to displaying the bitmapped image, the application allows the user to configure the printer and then print the image, as well as a string of text specifying the location of the file which contained the image. The application prints the text at the top of the page and the image in the center of the page.


Opening and Displaying a .BMP File

In the sample application, a user is able to open a .BMP file that contains a bitmapped image and display that image in the client area of the application's window. The user selects the file to be opened when the application displays the Open dialog box.

After the user selects a file and closes the dialog box, the file and path names are stored in members of the OPENFILENAME structure. The application uses this data to open the appropriate file and retrieve the bitmap header and data. The following example shows the code required to retrieve this data:

 /* Retrieve a handle identifying the file. */

 hfbm = CreateFile(ofn.lpstrFile, GENERIC_READ,

        FILE_SHARE_READ, (LPSECURITY_ATTRIBUTES) NULL,

        OPEN_EXISTING, FILE_ATTRIBUTE_READONLY,

        (HANDLE) NULL);

 /* Retrieve the BITMAPFILEHEADER structure. */

 ReadFile(hfbm, &bmfh, sizeof(BITMAPFILEHEADER),

     &dwRead, (LPOVERLAPPED)NULL);

 /* Retrieve the BITMAPFILEHEADER structure. */

 ReadFile(hfbm, &bmih, sizeof(BITMAPINFOHEADER),

     &dwRead, (LPOVERLAPPED)NULL);

 /* Allocate memory for the BITMAPINFO structure. */

 hmem1 = GlobalAlloc(GHND,

     sizeof(BITMAPINFOHEADER) +

     ((1<<bmih.biBitCount) * sizeof(RGBQUAD)));

 lpbmi = GlobalLock(hmem1);

 /*

  * Load BITMAPINFOHEADER into the BITMAPINFO

  * structure.

  */

 lpbmi->bmiHeader.biSize = bmih.biSize;

 lpbmi->bmiHeader.biWidth = bmih.biWidth;

 lpbmi->bmiHeader.biHeight = bmih.biHeight;

 lpbmi->bmiHeader.biPlanes = bmih.biPlanes;

 lpbmi->bmiHeader.biBitCount = bmih.biBitCount;

 lpbmi->bmiHeader.biCompression = bmih.biCompression;

 lpbmi->bmiHeader.biSizeImage = bmih.biSizeImage;

 lpbmi->bmiHeader.biXPelsPerMeter = bmih.biXPelsPerMeter;

 lpbmi->bmiHeader.biYPelsPerMeter = bmih.biYPelsPerMeter;

 lpbmi->bmiHeader.biClrUsed = bmih.biClrUsed;

 lpbmi->bmiHeader.biClrImportant = bmih.biClrImportant;

 /*

  * Retrieve the color table.

  * 1 << bmih.biBitCount == 2 ^ bmih.biBitCount

  */

 ReadFile(hfbm, lpbmi->bmiColors,

     ((1<<bmih.biBitCount) * sizeof(RGBQUAD)),

     &dwRead, (LPOVERLAPPED) NULL);

 /*

  * Allocate memory for the required number of

  * bytes.

  */

 hmem2 = GlobalAlloc(GHND,

     (bmfh.bfSize - bmfh.bfOffBits));

 lpvBits = GlobalLock(hmem2);

 /* Retrieve the bitmap data. */

 ReadFile(hfbm, lpvBits,

     (bmfh.bfSize - bmfh.bfOffBits),

     &dwRead, (LPOVERLAPPED) NULL);

 /*

  * Create a bitmap from the data stored in the

  * .BMP file.

  */

 hbm = CreateDIBitmap(hdc, &bmih,

     CBM_INIT, lpvBits,

     lpbmi, DIB_RGB_COLORS);

/*

 * Unlock the global memory objects and

 * close the .BMP file.

 */

 GlobalUnlock(hmem1);

 GlobalUnlock(hmem2);

 CloseHandle(hfbm);

 /* Set the fDisplayBitmap flag. */

 if (hbm)

     fDisplayBitmap = TRUE;

 else

     TextOut(hdc, 100, 100, "LoadBitmap Failed", 17);

 /* Paint the window (and draw the bitmap). */

 GetClientRect(hwnd, &rect);

 InvalidateRect(hwnd, &rect, TRUE);

 UpdateWindow(hwnd);

Once the bitmap data is retrieved, the bitmapped image can be drawn in the application's client area. The following example shows the code required to draw the bitmap.

case WM_PAINT:

    BeginPaint(hwnd, &ps);

        if (fDisplayBitmap) {

            hdcMem = CreateCompatibleDC(hdc);

            SelectObject(hdcMem, hbm);

            GetObject(hbm, sizeof(BITMAP), (LPSTR) &bm);

            BitBlt(hdc, 0, 0, bmih.biWidth, bmih.biHeight,

                hdcMem, 0, 0, SRCCOPY);

            DeleteDC(hdcMem);

        }

    EndPaint(hwnd, &ps);

    break;


Displaying a Print Dialog Box and Retrieving a Printer Device Context

The first step in printing involves setting up the printer and obtaining a printer device context. In the sample application, the File menu contains two options: Print and Print Setup. By selecting either option, the user can configure the printer. When the user selects the Print Setup option, the Print Setup dialog box is displayed and the user can select a printer, a page orientation, a paper size, and so on. When the user selects the Print option, the Print dialog box is displayed and the user can select a range of pages, a print quality, a number of copies, and so on. The user can also display the Print Setup dialog box by clicking the Setup push button. The following illustration shows the Print dialog box that appears when the user selects the Print option.

The Print and the Print Setup dialog boxes are both displayed by initializing the members of a PRINTDLG structure and calling the PrintDlg function. In addition to retrieving user-specified data, the PrintDlg function can be used to obtain a printer device context by setting the Flags member of PRINTDLG to PD_RETURNDC. The following example code shows how this can be done.

/* Initialize the PRINTDLG members. */

pd.lStructSize = sizeof(PRINTDLG);

pd.hDevMode = (HANDLE) NULL;

pd.hDevNames = (HANDLE) NULL;

pd.Flags = PD_RETURNDC;

pd.hwndOwner = hwnd;

pd.hDC = (HDC) NULL;

pd.nFromPage = 1;

pd.nToPage = 1;

pd.nMinPage = 0;

pd.nMaxPage = 0;

pd.nCopies = 1;

pd.hInstance = (HANDLE) NULL;

pd.lCustData = 0L;

pd.lpfnPrintHook = (LPPRINTHOOKPROC) NULL;

pd.lpfnSetupHook = (LPSETUPHOOKPROC) NULL;

pd.lpPrintTemplateName = (LPSTR) NULL;

pd.lpSetupTemplateName = (LPSTR)  NULL;

pd.hPrintTemplate = (HANDLE) NULL;

pd.hSetupTemplate = (HANDLE) NULL;

/* Display the PRINT dialog box. */

PrintDlg(&pd);


Preparing to Print

The following code sample determines whether the selected printer is capable of printing bitmaps by calling the GetDeviceCaps function and specifying the RASTERCAPS flag. By examining this function's return value, the application can determine whether it should print a document or inform the user that the device does not support raster output.

/*

 * Examine the raster capabilities of the device

 * identified by pd.hDC to verify that it supports

 * the BitBlt function.

 */

if (!(GetDeviceCaps(pd.hDC, RASTERCAPS)

    & RC_BITBLT)) {

    DeleteDC(pd.hDC);

    MessageBox(hwnd,

        "Printer cannot display bitmaps.",

        "Device Error",

        MB_OK);

    break;

}

After the sample application determines that the selected printer is capable of printing bitmaps, it follows these steps:

1	Sets a Boolean flag that the application's abort procedure can examine to determine whether to allow printing to continue.

2	Registers the application's print-job abort function.

3	Displays a modeless Cancel dialog box.

4	Disables the application's window while the dialog box is displayed.

/*

 * Set the flag used by the AbortPrintJob

 * dialog procedure.

 */

 bPrint = TRUE;

/*

 * Register the application's AbortProc

 * function with GDI.

 */

 SetAbortProc(pd.hDC, AbortProc);

/* Display the modeless Cancel dialog box. */

 hdlgCancel = CreateDialog(hinst, (LPTSTR) "AbortDlg",

    hwnd, (DLGPROC) AbortPrintJob);

/* Disable the application's window. */

 EnableWindow(hwnd, FALSE);

Once the application registers its abort procedure with Windows, GDI calls the procedure repeatedly during the printing process to determine whether to cancel a job. In the current version of the Win32 API, GDI calls this function approximately every 2 seconds until the entire job has been spooled.

If the user does choose to cancel the job, GDI notifies the spooler that it should delete the corresponding journal file from the print queue and reset the printer to its default state.

The Abort Procedure

Any application written for Windows that supports printing should provide an abort procedure and a modeless dialog that allow a user to cancel a print job. The abort procedure for the sample application contains a message loop that retrieves messages for the modeless dialog box.

BOOL CALLBACK AbortProc(HDC hdc, int nCode)

{

    MSG msg;

    /*

     * Retrieve and remove messages from the thread's message

     * queue.

     */

    while (PeekMessage((LPMSG) &msg, (HWND) NULL,

            0, 0, PM_REMOVE)) {

        /* Process any messages for the Cancel dialog box. */

        if (!IsDialogMessage(hdlgCancel, (LPMSG) &msg)) {

            TranslateMessage((LPMSG) &msg);

            DispatchMessage((LPMSG) &msg);

         }

    }

    /*

     * Return the global bPrint flag (which is set to FALSE

     * if the user presses the Cancel button).

     */

     return bPrint;

}

This procedure must be exported in the application's module-definition file.

The Cancel Dialog Box

The Cancel dialog box typically contains a single push button that allows the user to cancel a print job. The following template for the Cancel dialog box was taken from the application's resource file.

AbortDlg DIALOG LOADONCALL MOVEABLE DISCARDABLE 33, 32, 160, 70

CAPTION "Sample Printing App"

STYLE WS_BORDER | WS_CAPTION | WS_DLGFRAME | WS_VISIBLE |

      WS_POPUP | WS_SYSMENU

BEGIN

    CONTROL "Now Printing: ", IDD_TEXT, "static",

        SS_CENTER | WS_CHILD, 0, 10, 160, 8

    CONTROL "", IDD_FILE, "static",

        SS_CENTER | WS_CHILD, 0, 25, 160, 8

    CONTROL "Cancel", IDD_CANCEL, "button",

        BS_DEFPUSHBUTTON | WS_TABSTOP | WS_CHILD,

        60, 45, 45, 15

END

The example code that follows shows the dialog box procedure for the sample application.

LRESULT CALLBACK AbortPrintJob(

        HWND hwndDlg,             /* window handle of dialog box     */

        UINT message,             /* type of message                 */

        WPARAM wParam,            /* message-specific information    */

        LPARAM lParam)            /* message-specific information    */

{

    switch (message) {

        case WM_INITDIALOG: /* message: initialize dialog box  */

            /* Initialize the static text control. */

            SetDlgItemText(hwndDlg, IDD_FILE, ofn.lpstrFile);

            return TRUE;

        case WM_COMMAND: /* message: received a command */

            /* User pressed "Cancel" button--stop print job. */

            MessageBox(hwndDlg, "Incoming", "WM_COMMAND", MB_OK);

            bPrint = FALSE;

            return TRUE;

        default:

            return FALSE;              /* didn't process a message   */

    }

        UNREFERENCED_PARAMETER(lParam);

        UNREFERENCED_PARAMETER(wParam);

        UNREFERENCED_PARAMETER(message);

}


Printing a Document

Once the application initializes the necessary variables, registers its abort procedure, and displays its modeless Cancel dialog box, it can start the print job by calling the StartDoc function.

After the application begins a print job, it can define individual pages in the document by calling the StartPage and EndPage functions and embedding the appropriate GDI drawing function calls within this bracket. After the application has defined the last page, it can close the document and end the print job by calling the EndDoc function.

The following example shows the code required to print a string of text and a bitmapped image. The string of text, centered at the top of the page, identifies the path and file name for the file that contains the bitmapped image. The bitmapped image, centered vertically and horizontally on the page, is drawn while maintaining the same proportions used to draw the image in the application's client area.

                /*

                 * Initialize the members of a DOCINFO

                 * structure.

                 */

                 di.cbSize = sizeof(DOCINFO);

                 di.lpszDocName = "Bitmap Printing Test";

                 di.lpszOutput = (LPTSTR) NULL;

                /*

                 * Begin a print job by calling the StartDoc

                 * function.

                 */

                 nError = StartDoc(pd.hDC, &di);

                 if (nError == SP_ERROR) {

                     errhandler("StartDoc", hwnd);

                     goto Error;

                    }

                /*

                 * Inform the driver that the application is

                 * about to begin sending data.

                 */

                 nError = StartPage(pd.hDC);

                 if (nError <= 0) {

                     errhandler("StartPage", hwnd);

                     goto Error;

                    }

                /*

                 * Retrieve the number of pixels-per-logical-inch

                 * in the horizontal and vertical directions

                 * for the display upon which the bitmap

                 * was created.

                 */

                 fLogPelsX1 = (float) GetDeviceCaps(hdc, LOGPIXELSX);

                 fLogPelsY1 = (float) GetDeviceCaps(hdc, LOGPIXELSY);

                /*

                 * Retrieve the number of pixels-per-logical-inch

                 * in the horizontal and vertical directions

                 * for the printer upon which the bitmap

                 * will be printed.

                 */

                 fLogPelsX2 = (float) GetDeviceCaps(pd.hDC, LOGPIXELSX);

                 fLogPelsY2 = (float) GetDeviceCaps(pd.hDC, LOGPIXELSY);

                /*

                 * Determine the scaling factors required to

                 * print the bitmap and retain its original

                 * proportions.

                 */

                 if (fLogPelsX1 > fLogPelsX2)

                    fScaleX = (fLogPelsX1 / fLogPelsX2);

                 else

                    fScaleX = (fLogPelsX2 / fLogPelsX1);

                 if (fLogPelsY1 > fLogPelsY2)

                    fScaleY = (fLogPelsY1 / fLogPelsY2);

                 else

                    fScaleY = (fLogPelsY2 / fLogPelsY1);

                /*

                 * Compute the coordinate of the upper left

                 * corner of the centered bitmap.

                 */

                 cWidthPels = GetDeviceCaps(pd.hDC, HORZRES);

                 xLeft = ((cWidthPels / 2) -

                            ((int) (((float) bmih.biWidth) * fScaleX)) / 2);

                 cHeightPels = GetDeviceCaps(pd.hDC, VERTRES);

                 yTop = ((cHeightPels / 2) -

                            ((int) (((float) bmih.biHeight) * fScaleY)) / 2);

                /*

                 * Create a memory DC that is compatible with

                 * the printer and select the bitmap (which

                 * the user requested) into this DC.

                 */

                 hdcMem = CreateCompatibleDC(pd.hDC);

                 if (!SelectObject(hdcMem, hbm))

                    errhandler("SelectObject Failed", hwnd);

                /*

                 * Use the StretchBlt function to scale the

                 * bitmap and maintain its original proportions

                 * (that is, if the bitmap was square when it

                 * appeared in the application's client area,

                 * it should also appear square on the page).

                 */

                 if (!StretchBlt(pd.hDC, xLeft, yTop,

                         (int) ((float) bmih.biWidth * fScaleX),

                         (int) ((float) bmih.biHeight * fScaleY),

                         hdcMem, 0, 0,

                         bmih.biWidth, bmih.biHeight,

                         SRCCOPY))

                     errhandler("StretchBlt Failed", hwnd);

                /* Delete the memory DC. */

                 DeleteDC(hdcMem);

                /*

                 * Retrieve the width of the string that

                 * specifies the full path and filename for the

                 * file that contains the bitmap.

                 */

                 GetTextExtentPoint(pd.hDC, ofn.lpstrFile,

                     ofn.nFileExtension + 3,

                     &szMetric);

                /*

                 * Compute the starting point for the

                 * text-output operation. The string will

                 * be centered horizontally and positioned

                 * three-lines down from the top of the page.

                 */

                 xLeft = ((cWidthPels / 2) - (szMetric.cx / 2));

                 yTop = (szMetric.cy * 3);

                /*

                 * Print the path and filename for the bitmap,

                 * centered at the top of the page.

                 */

                 TextOut(pd.hDC, xLeft, yTop, ofn.lpstrFile,

                     ofn.nFileExtension + 3);

                /*

                 * Determine whether the user has pressed

                 * the Cancel button in the AbortPrintJob

                 * dialog box; if the button has been pressed,

                 * call the AbortDoc function. Otherwise, inform

                 * the spooler that the page is complete.

                 */

                 nError = EndPage(pd.hDC);

                 if (nError <= 0) {

                    errhandler("EndPage", hwnd);

                    goto Error;

                 }

                /* Inform the driver that the document has ended. */

                 nError = EndDoc(pd.hDC);

                 if (nError <= 0) {

                    errhandler("EndDoc", hwnd);

                 }

Error:

                /* Enable the application's window. */

                EnableWindow(hwnd, TRUE);

                /* Remove the AbortPrintJob dialog box. */

                DestroyWindow(hdlgCancel);

                /* Delete the printer DC. */

                DeleteDC(pd.hDC);

Because the pixels on a screen typically have different dimensions than the dots on a printer, it is necessary to scale bitmapped images to obtain WYSIWYG output. This is done by first obtaining horizontal and vertical scaling factors, then applying these factors to the width and height values passed to the bitmap drawing function StretchBlt. In the sample application, these scaling factors were obtained by retrieving the horizontal and vertical logical-pixel count for the two devices. Once the scaling factors were obtained, they were used to adjust the bitmap width and height.

To center the bitmap on the page, the application first computed the width and height of the scaled bitmap. (The bitmap was scaled in order to maintain the original proportions of the image.) These values were divided by two and then subtracted from half of the width and height of the page. The results define the coordinates of the upper left corner of the bitmap.

To center the text at the top of the page, the application retrieved the width and height of the string specifying the path names and filenames by calling the GetTextExtentPoint function. Once these values were obtained, the application used the height to position the string three lines down the page and the width to position the string horizontally centered on the page.


Functions

Functions and Messages

Following are the functions used to print.

Functions

AbortDoc

CancelDC

DeviceCapabilities

EndDoc

EndPage

Escape

ExtEscape

SetAbortProc

StartDoc

StartPage

Following are the functions used to access the print spooler.

AbortPrinter

AbortProc

AddForm

AddJob

AddMonitor

AddPort

AddPrinter

AddPrinterDriver

AddPrintProcessor

AddPrintProvidor

AdvancedDocumentProperties

ClosePrinter

ConfigurePort

DeleteForm

DeleteMonitor

DeletePort

DeletePrinter

DeletePrinterDriver

DeletePrintProcessor

DeletePrintProvidor

DocumentProperties

EndDocPrinter

EndPagePrinter

EnumForms

EnumJobs

EnumMonitors

EnumPorts

EnumPrinterDrivers

EnumPrinters

EnumPrintProcessors

GetForm

GetJob

GetPrinter

GetPrinterData

GetPrinterDriver

GetPrinterDriverDirectory

GetPrintProcessorDirectory

OpenPrinter

PrinterProperties

ReadPrinter

ScheduleJob

SetForm

SetJob

SetPrinter

SetPrinterData

StartDocPrinter

StartPagePrinter

WritePrinter

Messages

WM_SPOOLERSTATUS


Memory Management Overview

About Memory Management

In the Microsoft® Win32™ application programming interface (API), each process has its own 32-bit virtual address space that enables addressing up to 4 gigabytes (GB) of memory. The 2 GB in low memory (0x00 to 0x7FFFFFFF) are available to the user, and the 2 GB in high memory (0x80000000 to 0xFFFFFFFF) are reserved for the kernel. The virtual addresses used by a process do not represent the actual physical location of an object in memory. Instead, for each process the kernel maintains a page map, a data structure used to translate virtual addresses into corresponding physical addresses.

This topic describes Win32 memory management. It also explains how to allocate and use memory.

The following topics Win32 memory management:

Terms

Virtual Address Space and Physical Storage

Global and Local Functions

Standard C Library Functions

Virtual Memory Functions

Heap Functions

Shared Memory

Using the Virtual Memory Functions

Functions


Virtual Address Space and Physical Storage

The virtual address space of each process is much larger than the total physical memory, random-access memory (RAM), available to all processes. To increase the size of physical storage, the kernel uses the disk for additional storage. The total amount of storage available to all executing processes is the sum of physical memory, RAM, and the free space on disk available to the paging file, a disk file used to increase the amount of physical storage. Physical storage and the virtual (logical) address space of each process are organized into pages, units of memory, whose size depends on the host computer. For example, on x86 computers the host page size is 4 kilobytes.

To maximize its flexibility in managing memory, the kernel can move the pages of physical memory to and from a paging file on disk. When a page is moved in physical memory, the kernel updates the page maps of the affected processes. When the kernel needs space in physical memory, it moves the least recently used pages of physical memory to the paging file. Manipulation of physical memory by the kernel is completely transparent to applications, which operate only in their virtual address spaces.

The pages of a process's virtual address space can be in one of the following states.

State	Description

Free	A free page is not currently accessible, but it is available to be committed or reserved.

Reserved	A reserved page is a block of the process's virtual address space that has been set aside for future use. The process cannot access a reserved page, and there is no physical storage associated with it. A reserved page reserves a range of virtual addresses that cannot be used subsequently by other allocation operations (that is, by malloc, LocalAlloc, and so on). A process can use the VirtualAlloc function to reserve pages of its address space and later to commit the reserved pages. It can use the VirtualFree function to release them.

Committed	A committed page is one for which physical storage (in memory or on disk) has been allocated. It can be protected to allow either no access or read-only access, or it can have read and write access. A process can use the VirtualAlloc function to allocate committed pages. The GlobalAlloc and LocalAlloc functions allocate committed pages with read-write access. A committed page allocated by VirtualAlloc can be decomitted by the VirtualFree function, which releases the page's storage and changes the state of the page to reserved.


Global and Local Functions

A process can use the GlobalAlloc and LocalAlloc functions to allocate memory. In the linear 32-bit environment of the Win32 API, the local heap and the global heap are not distinguished. As a result, there is no difference between the memory objects allocated by these functions.

Memory objects allocated by GlobalAlloc and LocalAlloc are in private, committed pages with read-write access. Private memory cannot be accessed by other processes. Memory allocated by using GlobalAlloc with the GMEM_DDESHARE flag is not actually shared globally as it is in Windows version 3.x. However, this flag is available for compatibility purposes and can be used by some implementations to enhance the performance of dynamic data exchange (DDE) operations. Applications requiring shared memory for other purposes must use file-mapping objects. Multiple processes can map a view of the same file-mapping object to provide named shared memory. For more information about file mapping, see File Mapping, and Shared Memory.

By using GlobalAlloc and LocalAlloc, you can allocate a block of memory of any size that can be represented by 32 bits. You are limited only by the available physical memory, including storage in the paging file on disk. These functions, along with the other global and local functions that manipulate global and local memory objects, are included in the Win32 API for compatibility with 16-bit versions of Windows. However, the change from a 16-bit segmented memory model to a 32-bit virtual memory model has made some of the functions and their options unnecessary or meaningless. For example, there are no longer near and far pointers, because both local and global allocations return 32-bit virtual addresses.

Both GlobalAlloc and LocalAlloc can allocate fixed or movable memory objects. Movable objects can also be marked as discardable. In earlier versions of Windows, movable memory objects were important for memory management. They enabled the system to compact the heap when necessary to make space available for other memory allocations. By using virtual memory, the system is able to manage memory by moving pages of physical memory without affecting the virtual addresses of the processes using the pages. When the system moves a page of physical memory, it simply maps the process's virtual page to the new location of the physical page. Movable memory is still useful for allocating discardable memory. When the system needs additional physical storage, it can use a "least recently used" algorithm to free discardable memory that is not locked. Use discardable memory for data you need infrequently and can regenerate easily.

When allocating a fixed memory object, GlobalAlloc and LocalAlloc return a 32-bit pointer that the calling process can immediately use to access the memory. For movable memory, the return value is a handle. To get a pointer to a movable memory object, the calling process uses the GlobalLock and LocalLock functions. These functions lock the memory so that it cannot be moved or discarded. The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, GlobalLock and LocalLock increment this count by one, and the GlobalUnlock and LocalUnlock functions decrement the count by one. Locked memory is not moved or discarded, unless the memory object is reallocated by using the GlobalReAlloc or LocalReAlloc function. The memory block of a locked memory object remains locked in memory until its lock count is decreased to zero, at which time it can be moved or discarded.

The actual size of the memory allocated by GlobalAlloc or LocalAlloc can be larger than the requested size. To determine the actual number of bytes allocated, use the GlobalSize or LocalSize function. If the amount allocated is greater than the amount requested, the process can use the entire amount.

The GlobalReAlloc and LocalReAlloc functions change the size, in bytes, or the attributes of a memory object allocated by GlobalAlloc and LocalAlloc. The size can increase or decrease.

The GlobalFree and LocalFree functions release memory allocated by GlobalAlloc, LocalAlloc, GlobalReAlloc, or LocalReAlloc.

Other global and local functions include the GlobalDiscard, LocalDiscard, GlobalFlags, LocalFlags, GlobalHandle, and LocalHandle functions. To discard a specified discardable memory object without invalidating the handle, use GlobalDiscard or LocalDiscard. The handle can be used later by GlobalReAlloc or LocalReAlloc to allocate a new block of memory associated with the same handle. To return information about a specified memory object, use GlobalFlags or LocalFlags. The information includes the object's lock count and indicates whether the object is discardable or has already been discarded. To return the handle of the memory object associated with a specified pointer, use GlobalHandle or LocalHandle.


Standard C Library Functions

Win32 processes can safely use the standard C library functions (malloc, free, and so on) to manipulate memory. When used with previous versions of Windows, these functions had potential problems that no longer apply to applications using the Win32 API. For example, malloc allocates a fixed pointer that does not take advantage of movable memory. This is no longer a problem because the system is free to manage memory by moving pages of physical memory without affecting the virtual addresses. Similarly, the distinction between near and far pointers is no longer relevant. So, unless you want to allocate discardable memory, it is now reasonable to use the standard C library functions for memory management.


Virtual Memory Functions

The Win32 API provides a set of virtual memory functions that enable a process to manipulate or determine the status of pages in its virtual address space. Many applications are able to satisfy their memory needs by using the standard allocation functions (GlobalAlloc, LocalAlloc, malloc, and so on). However, virtual memory functions provide some functionality not available in the standard allocation functions. They can perform the following operations:

Reserve a range of a process's virtual address space. Reserving address space does not allocate any physical storage, but it prevents other allocation operations from using the specified range. It does not affect the virtual address spaces of other processes. Reserving pages prevents needless consumption of physical storage, while enabling a process to reserve a range of its address space into which a dynamic data structure can grow. The process can allocate physical storage for this space, as needed.

Commit a range of reserved pages in a process's virtual address space so that physical storage (either in RAM or on disk) is accessible only to the allocating process.

Specify read-write, read-only, or no access for a range of committed pages. This differs from the standard allocation functions that always allocate pages with read-write access.

Free a range of reserved pages, making the range of virtual addresses available for subsequent allocation operations by the calling process.

Decommit a range of committed pages, releasing their physical storage. Decommitting a range makes their storage available for subsequent allocation by any process.

Lock one or more pages of committed memory into physical memory (RAM), so the system cannot swap the pages out to the paging file.

Query information about a range of pages in the virtual address space of the calling process or of a specified process.

Change the access protection for a specified range of committed pages in the virtual address space of the calling process or a specified process.

The virtual memory functions manipulate pages of memory. The functions use the size of a page on the current computer to round off specified sizes and addresses.

To determine the size of a page on the current computer, use the GetSystemInfo function.

The VirtualAlloc function performs one of the following operations:

Reserves one or more free pages.

Commits one or more reserved pages.

Reserves and commits one or more free pages.

You can specify the starting address of the pages to be reserved or committed, or you can allow the system to determine the address. The function rounds the specified address to the appropriate page boundary. Reserved pages are not accessible, but committed pages can be allocated with the PAGE_READWRITE, PAGE_READONLY, or PAGE_NOACCESS flag. When pages are committed, storage is allocated in the paging file, but each page is initialized and loaded into physical memory only at the first attempt to read from or write to that page. You can use normal pointer references to access memory committed by the VirtualAlloc function.

The VirtualFree function performs one of the following operations:

Decommits one or more committed pages, changing the state of the pages to reserved. Decommitting pages releases the physical storage associated with the pages, making it available to be allocated by any process. Any block of committed pages can be decommitted.

Releases a block of one or more reserved pages, changing the state of the pages to free. Releasing a block of pages makes the range of reserved addresses available to be allocated by the process. Reserved pages can be released only by releasing the entire block that was initially reserved by VirtualAlloc.

Decommits and releases a block of one or more committed pages simultaneously, changing the state of the pages to free. The specified block must include the entire block initially reserved by VirtualAlloc, and all of the pages must be currently committed.

The VirtualLock function enables a process to lock one or more pages of committed memory into physical memory, RAM. Locking pages prevents the system from swapping the pages out to the paging file. It can be useful when it is necessary to ensure that critical data is accessible without disk access. Locking pages in memory is dangerous because it restricts the system's ability to manage memory. Excessive use of VirtualLock can degrade system performance by causing executable code to be swapped out to the paging file. The VirtualUnlock function unlocks memory locked by VirtualLock.

The VirtualQuery and VirtualQueryEx functions return information about a region of consecutive pages beginning at any specified address in the address space of a process. VirtualQuery returns information about memory in the calling process. VirtualQueryEx returns information about memory in a specified process and is intended to support debuggers that need information about a process being debugged. The region of pages is bounded by the specified address rounded down to the nearest page boundary. It extends through all subsequent pages with the following attributes in common:

The state of all pages is the same: either committed, reserved, or free.

If the initial page is not free, all pages in the region are part of the same initial allocation of pages that were reserved by a call to the VirtualAlloc function.

The access protection of all pages is the same (that is, the PAGE_READONLY, PAGE_READWRITE, or PAGE_NOACCESS flag).

The VirtualProtect function enables a process to modify the access protection of any committed page in the address space of a process. For example, a process can allocate read-write pages to store sensitive data, and then it can change the access to read only or no access to protect against accidental overwriting. VirtualProtect is typically used with pages allocated by VirtualAlloc, but it also works with pages committed by any of the other allocation functions. However, VirtualProtect changes the protection of entire pages, and pointers returned by the other functions are not necessarily aligned on page boundaries. The VirtualProtectEx function is similar to VirtualProtect except that it changes the protection of memory in a specified process. Changing the protection is useful to debuggers in accessing the memory of a process being debugged.


Heap Functions

The heap functions enable a process to create a private heap, a block of one or more pages in the address space of the calling process. The process can then use a separate set of functions to manage the memory in that heap. There is no difference between memory allocated from a private heap and that allocated by using the standard allocation functions (GlobalAlloc, LocalAlloc, malloc, and so on).

The HeapCreate function creates a private heap object from which the calling process can allocate memory blocks by using the HeapAlloc function. HeapCreate specifies both an initial size and a maximum size for the heap. The initial size determines the number of committed, read-write pages initially allocated for the heap. The maximum size determines the total number of reserved pages. These pages create a contiguous block of the process's virtual address space into which the heap can grow. Additional pages are automatically committed from this reserved space if requests by HeapAlloc exceed the current size of committed pages, assuming that the physical storage for it is available. Once the pages are committed, they are not decommitted until the process is terminated or the heap is destroyed by calling the HeapDestroy function.

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, it does so in the address space of the process that invoked the DLL. It is accessible only to that process.

The HeapAlloc function allocates a specified number of bytes from a private heap and returns a pointer to the allocated block. The pointer identifies the block for the HeapFree function to release or for the HeapSize function to determine the size.

Memory allocated by HeapAlloc is not movable. Because the system cannot compact a private heap, the heap can become fragmented.

A possible use for the heap functions is to create a private heap when a process starts up, specifying an initial size sufficient to satisfy the memory requirements of the process. If the call to the HeapCreate function fails, the process can terminate or notify the user of the memory shortage; if it succeeds, however, the process is assured of having the memory it needs.


Shared Memory

In the Win32 API, shared memory is implemented by file mapping. All memory allocated by the other allocation methods (the GlobalAlloc, LocalAlloc, HeapAlloc, or VirtualAlloc function) is accessible only to the calling process. Memory allocated by a DLL, however, is in the address space of the process that invoked the DLL and is not accessible to other processes using the same DLL.

Named file mapping provides an easy way to create a block of shared memory. One process specifies a name when it uses the CreateFileMapping function to create a file-mapping object. Other processes specify the same name to either the CreateFileMapping or OpenFileMapping function to obtain a handle of the mapping object. The names of event objects, semaphore objects, mutex objects, and file-mapping objects share the same name space. If a specified name matches the name of an existing object of a different type, an error occurs. When creating named objects, try to use unique names and check the function return values for duplicate name errors.

Each process specifies its handle of the file-mapping object in the MapViewOfFile function to map a view of the file into its own address space. The views of all processes for a single file-mapping object are mapped into the same sharable pages of physical storage. However, the virtual addresses of the mapped views can vary from one process to another, unless the MapViewOfFileEx function is used to map the view at a specified address. Although sharable, the pages of physical storage used for a mapped file view are not global; they are not accessible to processes that have not mapped a view of the file.

A file-mapping object is associated with a disk file the system uses when the mapped view is swapped out of physical memory and onto the disk. This disk swap file can be the system's paging file or it can be some other file that was specified when the file-mapping object was created. In that case, the memory is initialized along with the contents of the file. Mapping a specified file in the file system is useful for processes that need to share the data in an existing file or that want to use the file to save the data generated by the sharing processes. If you map a specified file, you should open it for exclusive access and keep the handle open until you are finished with the shared memory. This will prevent other processes from opening another handle on the file to use ReadFile or WriteFile or to create additional mapping objects for the same file, any of which actions can lead to unpredictable results.

Any pages committed by mapping a view of a file are released when the last process with a view of the mapping object either terminates or unmaps its view by calling the UnmapViewOfFile function. At this time, the specified file (if any) associated with the mapping object is updated. A specified file can also be forced to update by calling the FlushViewOfFile function.

For more information about file mapping, see File Mapping. For an example of shared memory in a DLL, see Dynamic-Link Libraries.

If multiple processes have write access to shared memory, access to the memory should be synchronized. For more information about interprocess synchronization, see Synchronization.

Access Validation

The Win32 API provides a set of functions that a process can use to verify whether it has a specified type of access to a given memory address or range of addresses. The following access validation functions are available.

Function	Description

IsBadCodePtr

Determines whether the calling process has read access to the memory at the specified address.

IsBadReadPtr

Determines whether the calling process has read access to the memory at a specified range of addresses.

IsBadStringPtr

Determines whether the calling process has read access to the memory pointed to by a null-terminated string pointer. The function validates access for a specified number of characters or until it encounters the string's terminating null character.

IsBadWritePtr

Determines whether the calling process has write access to the memory at a specified range of addresses.

The IsBadHugeReadPtr and IsBadHugeWritePtr functions are also available for compatibility with earlier versions of Windows that distinguished between normal memory allocations and huge allocations occupying multiple segments. In the Win32 API, these functions are equivalent to IsBadReadPtr and IsBadWritePtr.

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 one of these functions indicates that the process has the desired 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. For more information about structured exception handling, see Structured Exception Handling.


Using the Virtual Memory functions

Using the Virtual Memory Functions

This section explains how to use the virtual memory functions for dynamic allocation.

The following example illustrates the use of the VirtualAlloc and VirtualFree functions in reserving and committing memory as needed for a dynamic array. First, VirtualAlloc is called to reserve a block of pages, and NULL is specified as the base address parameter, forcing the kernel to determine the location of the block. Later, VirtualAlloc is called whenever it is necessary to commit a page from this reserved region, and the base address of the next page to be committed is specified.

The example uses the try-except structured exception-handling syntax to commit pages from the reserved region. Whenever a page fault exception occurs during execution of the try block, the filter function in the expression preceding the except block is executed. If the filter function can allocate another page, execution continues in the try block at the point where the exception occurred. Otherwise, the exception handler in the except block is executed. For more information about structured exception handling, see Structured Exception Handling.

As an alternative to this dynamic allocation, the process can simply commit the entire region instead of only reserving it. However, this consumes physical storage that might not be needed, making it unavailable for use by other processes.

The example uses VirtualFree to free the reserved and committed pages when it is finished with them. The function is called twice: first to decommit the committed pages and again to release the entire region of reserved pages.

#define PAGELIMIT 80

#define PAGESIZE 0x1000

INT PageFaultExceptionFilter(DWORD);

VOID MyErrorExit(LPTSTR);

LPTSTR lpNxtPage;

DWORD dwPages = 0;

VOID UseDynamicVirtualAlloc(VOID) {

  LPVOID lpvBase;

  LPTSTR lpPtr;

  BOOL bSuccess;

  DWORD i;

  /* Reserve pages in the process's virtual address space. */

  lpvBase = VirtualAlloc(

         NULL,               /* system selects address   */

         PAGELIMIT*PAGESIZE, /* size of allocation       */

         MEM_RESERVE,        /* allocates reserved pages */

         PAGE_NOACCESS);     /* protection = no access   */

  if (lpvBase == NULL )

      MyErrorExit("VirtualAlloc reserve");

  lpPtr = lpNxtPage = (LPTSTR) lpvBase;

  /*

   * Use try-except structured exception handling when

   * accessing the pages. If a page fault occurs, the

   * exception filter is executed to commit another page

   * from the reserved block of pages.

   */

  for (i=0; i < PAGELIMIT*PAGESIZE; i++) {

      try {

          /* Write to memory. */

          lpPtr[i] = 'a';

      }

      /*

       * If there is a page fault, commit another page

       * and try again.

       */

      except ( PageFaultExceptionFilter(

                   GetExceptionCode() ) ) {

          /*

           * This is executed only if the filter function is

           * unsuccessful in committing the next page.

           */

          ExitProcess( GetLastError() );

      }

  }

  /* Release the block of pages when you are finished using them. */

  /* First, decommit the committed pages. */

  bSuccess = VirtualFree(

            lpvBase,          /* base address of block    */

            dwPages*PAGESIZE, /* bytes of committed pages */

            MEM_DECOMMIT);    /* decommit the pages       */

  /* Release the entire block. */

  if (bSuccess)

      bSuccess = VirtualFree(

            lpvBase,        /* base address of block     */

            0,              /* releases the entire block */

            MEM_RELEASE);   /* releases the pages        */

}

INT PageFaultExceptionFilter(DWORD dwCode) {

LPVOID lpvResult;

  /* If the exception is not a page fault, exit. */

  if (dwCode != EXCEPTION_ACCESS_VIOLATION) {

      printf("exception code = %d\n", dwCode);

      return EXCEPTION_EXECUTE_HANDLER;

  }

  printf("page fault\n");

  /* If the reserved pages are used up, exit. */

  if (dwPages >= PAGELIMIT) {

      printf("out of pages\n");

      return EXCEPTION_EXECUTE_HANDLER;

  }

  /* Otherwise, commit another page. */

  lpvResult = VirtualAlloc(

      (LPVOID) lpNxtPage, /* next page to commit  */

      PAGESIZE,           /* page size, in bytes  */

      MEM_COMMIT,         /* alloc committed page */

      PAGE_READWRITE);    /* read-write access    */

  if (lpvResult == NULL ) {

      printf("VirtualAlloc failed\n");

      return EXCEPTION_EXECUTE_HANDLER;

  }

  /*

   * Increment the page count, and advance lpNxtPage

   * to the next page.

   */

  dwPages++;

  lpNxtPage += PAGESIZE;

  /* Continue execution where the page fault occurred. */

  return EXCEPTION_CONTINUE_EXECUTION;

}


Functions

Following are the Win32 functions used in memory management.

GetProcessHeap

GlobalAlloc

GlobalDiscard

GlobalFlags

GlobalFree

GlobalHandle

GlobalLock

GlobalMemoryStatus

GlobalReAlloc

GlobalSize

GlobalUnlock

HeapAlloc

HeapCreate

HeapDestroy

HeapFree

HeapReAlloc

HeapSize

IsBadCodePtr

IsBadHugeReadPtr

IsBadHugeWritePtr

IsBadReadPtr

IsBadStringPtr

IsBadWritePtr

LocalAlloc

LocalDiscard

LocalFlags

LocalFree

LocalHandle

LocalLock

LocalReAlloc

LocalSize

LocalUnlock

VirtualAlloc

VirtualFree

VirtualLock

VirtualProtect

VirtualProtectEx

VirtualQuery

VirtualQueryEx

VirtualUnlock


Processes and Threads Overview

About Processes and Threads

A Microsoft® Windows™ application can consist of more than one process, and a process can consist of more than one thread. The Microsoft Win32™ application program interface (API) supports multitasking, which creates the effect of simultaneous execution of multiple processes and threads. This topic describes processes and threads, and explains how to create and use them.

The following topics discuss processes and threads:

Terms

Multitasking

Scheduling

Scheduling Priorities

Creating Threads

Suspending Thread Execution

Synchronizing Execution of Multiple Threads

Thread Local Storage

Terminating a Thread

Multiple Threads and GDI Objects

Creating Processes

Inheritance

Environment Variables

StartupInfo

Terminating a Process

Process and Thread Handles and IDs

Example: Multithreaded MDI Application

Example: Child Process With Redirected I/O

Changing Environment Variables

Using Thread Local Storage

Functions


Multitasking

A process is a program that is loaded into memory and prepared for execution. Each process has a private virtual address space. A process consists of the code, data, and other system resources--such as files, pipes, and synchronization objects--that are accessible to the threads of the process. Each process is started with a single thread, but additional independently executing threads can be created.

A thread can execute any part of the program's code, including a part executed by another thread. Threads are the basic entity to which the operating system allocates CPU time. Each thread maintains a set of structures for saving its context while waiting to be scheduled for processing time. The context includes the thread's set of machine registers, the kernel stack, a thread environment block, and a user stack in the address space of the thread's process. All threads of a process share the virtual address space and can access the global variables and system resources of the process.

A multitasking operating system divides the available CPU time among the threads that need it. In Windows, the Win32 API is designed for preemptive multitasking, which means that the system allocates small slices of CPU time among the competing threads. The currently executing thread is suspended when its timeslice elapses, allowing another thread to run. When the system switches from one thread to another, it saves the context of the suspended thread and restores the saved context of the next thread in the queue.

Because each timeslice is small (on the order of 20 milliseconds), it appears that multiple threads are executing at the same time. This is actually the case on multiprocessor systems, where the executable threads are distributed among the available processors. On a single processor system, however, using multiple threads does not result in more instructions being executed. In fact, the system can slow down if it is forced to keep track of too many threads.

To the user, the advantage of multitasking is the ability to have several applications open and working at the same time. For example, a user can edit a file with one application while another application is printing or recalculating a spreadsheet.

To the application developer, the advantage of multitasking is the ability to create applications that use more than one process, and to create processes that use more than one thread of execution. For example, you can have one thread that handles interactions with the user (keyboard and mouse input), while other threads with lower priority perform the other work of the process. The higher priority of the input thread makes the program nicely responsive to the user, while the other threads ensure that the processor can be used efficiently during the slices of time between keystrokes.

When to Use Multitasking

Any thread of any process can use the CreateThread and CreateProcess functions to create additional threads or processes. An application might use multiple processes for functions that require a private address space and private resources, to protect them from the activities of other threads. Functions that are to be distributed as separate executable modules but that can be integrated to form a single application can benefit from the multi-process approach.

It is useful for a process to have multiple threads in situations where the application has several tasks to run concurrently. For example, an application that opens more than one window can have a separate thread perform the work of the application in each window. Multiple threads can be a convenient way to structure a program that performs several similar or identical tasks. For example, a named pipe server can create a thread to handle communications with each client process that attaches to the pipe. Other examples of using multiple threads are processes that do the following:

Handle input for multiple windows.

Manage input from several communications devices.

Need to distinguish among tasks of varying priority. For example, a high A priority thread handles time-critical tasks and a low-priority thread performs other tasks.

It is typically more efficient for an application to implement multitasking by distributing tasks among the threads of a single process, rather than by creating multiple processes, for the following reasons:

The system can create and execute threads more quickly than it can create processes, primarily because the code for threads has already been mapped into the address space of the process, while the code for a new process must be loaded.

All threads of a process share the same address space and can access the process's global variables, which can simplify communications between threads.

All threads of a process can use open handles to resources such as files and pipes.

For both multiple threads and multiple processes, there are costs and dangers to be considered. The system consumes memory for the structures required by both processes and threads. Keeping track of a large number of threads consumes CPU time. With multiple threads accessing the same resources, you must synchronize the threads to avoid conflicts. This is true for system resources (such as communications ports or disk drives), handles to resources shared by multiple processes (such as file or pipe handles), or the resources of a single process (such as global variables accessed by multiple threads). Failure to synchronize multiple threads properly (in the same or in different processes) can lead to program bugs such as deadlock and race conditions. The Win32 API provides a set of synchronization objects and functions you can use to coordinate multiple threads. For more information about synchronization, see Synchronizing Execution of Multiple Threads, and Synchronization.

The Win32 API also provides alternative ways to execute multiple tasks that, in some cases, make multithreaded processes unnecessary. The most significant of these are overlapped I/O and the ability to wait for multiple events.

Overlapped I/O enables a single thread to initiate multiple time consuming I/O requests that can run concurrently. This asynchronous I/O can be performed on files, pipes, serial communications devices, or tape devices. For more information about files, see Files. For more information about pipes, see Pipes. For more information about serial communication devices, see Communications. For more information about tape devices, see Tape Backup.

Waiting for multiple events enables a single thread to block its execution while waiting for any one of several events to occur. This is much more efficient than using multiple threads, each waiting for a single event, or using a single thread that consumes CPU time by continually checking for an event of interest. For more information about waiting for multiple events, see Synchronization.


Scheduling

The system scheduler controls multitasking by determining which of the competing threads receives the next slice of the processor's time. Each timeslice consists of a fixed number of clock ticks. The Windows scheduler is preemptive, gaining control whenever a clock interrupt occurs, and decrementing the count of clock ticks remaining in the timeslice of the currently executing thread. If the count goes to zero, the scheduler determines which thread runs next. The scheduler maintains a queue of executable threads at each priority level. When the highest priority is shared by more than one executable thread, the next timeslice goes to the thread at the head of the priority queue. The thread that just finished executing is placed at the end of the queue of threads with its priority. Threads that are suspended or blocked (for example, waiting for a semaphore object or waiting for input) are not executable, so until they become unblocked, the scheduler does not allocate any processor time to them, regardless of their priority. When the scheduler awards the next timeslice to a different thread, the context of the currently executing thread is saved, and the machine state is set according to the context of the next executable thread.


Scheduling Priorities

The scheduling priority of each thread is determined by the following criteria:

The priority class of its process (high, normal, or idle)

The priority level of the thread within the priority class of its process (lowest, below normal, normal, above normal, highest)

The dynamic priority boost, if any, the system applies to the thread's base priority

By default, the priority class of a process is set to normal. The CreateProcess function allows a parent process to specify the priority class of its child processes. Use SetPriorityClass to change the priority class of a process, and GetPriorityClass to determine the current priority class of a process.

There are five priority levels within each priority class. The levels range from lowest (-2) to highest (2). All threads are started with normal (0) priority. The SetThreadPriority function enables you to change the priority level of a thread to any of the five levels. Use the GetThreadPriority function to determine the current priority level of a thread.

The base priority of each thread is the thread's priority level within the priority class of its process. The scheduler uses this base priority to determine a thread's dynamic priority, which it uses to make scheduling decisions. A thread's dynamic priority is never less than its base priority. The scheduler raises and lowers the dynamic priority of a thread to enhance its responsiveness when significant things happen to the thread. For example, whenever a window receives input (such as timer messages, mouse move messages, keyboard input), the scheduler boosts the priorities of all threads within the process that owns the window. In some cases, the dynamic priority of a waiting thread is raised when a wait is satisfied. For example, a wait associated with disk or keyboard I/O results in a dynamic boost when the input occurs.

After raising a thread's dynamic priority, the scheduler reduces that priority by one level each time the thread completes a timeslice, until the thread drops back to its base priority.

In addition to these dynamic priority boosts, the scheduler raises the priority class of the process associated with the foreground window, so it is greater than or equal to the priority class of any background processes. The process's priority class returns to its original setting when it is no longer in the foreground. A user can always make a given window lose the foreground priority boost by clicking on another window or by using the ALT+TAB or CTRL+ESC key combination.

The three priority classes are intended to be used as follows:

Priority	Meaning

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.

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.

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.

Use the high priority class with extreme care. If a thread runs at the highest priority level for extended periods, other threads in the system will be starved for CPU time. If several threads are set at high priority at the same time, the effect of the high priority is neutralized. The high priority class should be reserved for threads that must respond to time critical events. If your application has a task that requires the high priority class while most of its functions are normal priority, use SetPriorityClass to raise the priority class temporarily; then reduce it once the time critical task has been completed. Another strategy is to create a high priority process that is blocked most of the time, awakening only when the critical task is needed. The important point is that a thread should be high priority and executable only for a brief period, when it has time-critical work to perform.

Having selected a priority class for a multithreaded process, use SetThreadPriority to adjust the relative priority of its threads. A typical strategy is to use a higher priority level for the process's input thread, to ensure responsiveness to the user. Other threads, particularly those that are CPU intensive, can be set to a lower relative priority, to ensure that they can be preempted when necessary. However, if you have a higher priority thread waiting for a lower priority thread to complete some task, be sure to block the execution of the waiting thread (using a wait function, critical section, or Sleep) rather than having it iterate in a loop. Otherwise, the process will deadlock because the lower priority thread will never get scheduled.


Creating Threads

The CreateThread function creates a new thread for a process. The creating thread must specify the starting address of the code that the new thread is to execute. Typically, the starting address is the name of a function defined in the program's code. A process can have multiple threads simultaneously executing the same function. The function called by the thread takes a single 32-bit parameter and returns a doubleword result.

The following example illustrates the creation of a new thread that executes the ThreadFunc function:

DWORD ThreadFunc(LPDWORD lpdwParam) {

    printf("ThreadFunc: thread parameter=%d\n", *lpdwParam);

    return 0;

}

DWORD main(VOID) {

    DWORD dwThreadId, dwThrdParam = 1;

    HANDLE hThread;

    hThread = CreateThread(

        NULL,                                /* no security attributes        */

        0,                                   /* use default stack size        */

        (LPTHREAD_START_ROUTINE) ThreadFunc, /* thread function               */

        &dwThrdParam,                        /* argument to thread function   */

        0,                                   /* use default creation flags    */

        &dwThreadId);                        /* returns thread the identifier */

    /* Check the return value for success. */

    if (hThread == NULL)

        ErrorExit("CreateThread error\n");

For simplicity, this example passes a pointer to dwThrdParam as an argument to the thread function. This could be a pointer to any type of data or structure, or it could be omitted altogether by passing a NULL pointer and deleting the references to the parameter in ThreadFunc. It is risky to pass the address of the local variable if the creating thread exits before the new thread, because the pointer becomes invalid. Instead, either pass dynamically allocated parameters or make the creating thread wait for the new thread to terminate. Data can also be passed from the creating thread to the new thread using global variables. With global variables, it is usually necessary to synchronize access by multiple threads. For more information about synchronizing, see Synchronizing Execution of Multiple Threads.

Using the thread function's argument to pass data to the new thread is particularly useful in processes where the main thread might create multiple threads to execute the same code. In this case, it is inconvenient to use global variables. For example, a process that enables the user to open several files at the same time can create a new thread for each file, with each of the threads executing the same thread function. The creating thread can pass as an argument the unique information (such as the filename) required by each instance of the thread function.

The creating thread can use the arguments to CreateThread to specify the following:

The security attributes for the handle of the new thread. These security attributes include an inheritance flag that determines whether the handle can be inherited by child processes. The security attributes also include a security descriptor, which the system uses to perform access checks on all subsequent uses of the thread's handle before access is granted. For more information about security attributes, see Security.

The initial stack size of the new thread. The thread's stack is allocated automatically in the memory space of the process; it can grow as needed; and it is freed when the thread terminates.

A creation flag that enables you to create the thread in a suspended state. When suspended, the thread does not run until the ResumeThread function is called.

The handle returned by CreateThread has full access rights to the new thread. Subject to security checks, the handle can be used in any of the Win32 API functions that accepts a handle to a thread object. The handle can be duplicated by DuplicateHandle, which enables you to create a thread handle with a subset of the access rights.

A thread can also be created with the CreateRemoteThread function. This is used by debugger processes to create a thread that runs in the address space of another process.


Suspending Thread Execution

A thread can suspend and resume the execution of another thread using the SuspendThread and ResumeThread functions. While a thread is suspended, it is not scheduled for time on the processor.

SuspendThread is not particularly useful for synchronization, because it does not control the point in the code at which the thread's execution is suspended. However, you might want to suspend a thread in a situation where you are confirming a user's input that would terminate the work of the thread. If confirmed, the thread is terminated; otherwise, it resumes.

If a thread is created in a suspended state, it does not begin to run until ResumeThread is called with a handle to the suspended thread. This can be useful for initializing the thread's state before it begins to run. See Example: Multithreaded MDI Application for an example that uses this method to modify the thread's priority before it can run. Suspending a thread at creation can be useful for one-time synchronization, because ResumeThread ensures that the suspended thread will resume running at the starting point of its code.

A thread can temporarily suspend its own execution for a specified interval by calling the Sleep or SleepEx functions. This is useful particularly in cases where the thread responds to user interaction, as it can delay execution long enough to enable the users to observe the results of their actions. During the sleep interval, the thread is not scheduled for time on the processor.


Synchronizing Execution of Multiple Threads

To avoid conflicts, it is necessary to synchronize access by multiple threads to shared resources. Synchronization is also necessary to ensure that interdependent code is executed in the proper sequence.

The Win32 API provides a number of objects whose handles can be used to synchronize multiple threads. These objects include:

Synchronization objects: mutex, semaphore, and event handles

File handles

Named pipe handles

Console input buffer handles

Communication device handles

Process handles

Thread handles

The state of each of these objects is either signaled or not signaled. When a handle to any of these objects is specified in a call to one of the wait functions--WaitForSingleObject, WaitForMultipleObjects, WaitForSingleObjectEx, or WaitForMultipleObjectsEx--the execution of the calling thread is blocked until the state of the specified object is signaled. As with a suspended thread, a waiting thread consumes very little processor time.

Some of these objects are useful in blocking a thread until some event occurs. For example, a console input buffer handle is signaled when there is unread input, such as a keystroke or mouse button press. Process and thread handles are signaled when the process or thread terminates. This allows a process, for example, to create a child process and then block its own execution until the new process has terminated.

Other objects are useful in protecting shared resources from simultaneous access. For example, multiple threads can each have a handle to a mutex object. Before accessing a shared resource, the threads must call one of the wait functions to wait for the state of the mutex to be signaled. When the mutex becomes signaled, only one waiting thread is released to access the resource. The state of the mutex is immediately reset to not signaled so any other waiting threads remain blocked. When the thread is finished with the resource, it must set the state of the mutex to signaled to free other threads to access the resource.

For the threads of a single process, critical section objects provide another (and slightly more efficient) means of synchronization. A critical section is used like a mutex to enable only one thread at a time to use the protected resource. A thread uses the EnterCriticalSection function to request ownership of a critical section. If it is already owned by another thread, the requesting thread is blocked. After it receives ownership, the thread is free to use the protected resource. The execution of the other threads of the process is not affected unless they attempt to enter the same critical section.

The WaitForInputIdle function makes a thread wait until a specified process is initialized and waiting for user input with no input pending. This can be useful for synchronizing parent and child processes, because CreateProcess returns without waiting for the child process to complete its initialization.

For more about critical sections and synchronization, see Synchronization.


Thread Local Storage

All threads of a process share the virtual address space and the global variables of that process. Sometimes it is desirable to have static storage that is local to each thread. Of course the local variables of a thread function are local to each thread that runs the function. But when a thread invokes another function, the static or global variables used by that function store the same value for all threads. With thread local storage, one thread allocates an index that can be used by any thread of the process to store and retrieve a different value for each thread.

The following is a typical thread local storage (TLS) scenario:

1	TlsAlloc is used during process or dynamic-link library (DLL) initialization to allocate a TLS index.

2	Each thread that needs to use the TLS index allocates dynamic storage, then uses TlsSetValue to associate the index with a pointer to the dynamic storage.

3	When a thread needs to access its storage, it specifies the TLS index in a call to TlsGetValue to retrieve the pointer.

4	Each thread frees the dynamic storage that it has associated with a TLS index when it is no longer needed. When all threads have finished using a TLS index, the TlsFree function frees the index.

The constant TLS_MINIMUM_AVAILABLE defines the minimum number of TLS indices available in each process. This minimum is guaranteed to be at least 64 for all systems.

Thread local storage can be useful with DLLs. The DllEntryPoint function performs the initial TLS operations in the context of the process or thread the DLL is attaching to or detaching from. When the DLL attaches to a new process, the entrypoint function calls TlsAlloc to allocate a TLS index for that process. When the DLL attaches to a new thread of that process, the entrypoint function allocates dynamic memory for that thread and uses TlsSetValue to save private data to the index. The DLL stores the TLS index in a global variable that is private to each attached process. The functions of the DLL can use the TLS index in a call to TlsGetValue to access the private data for the calling thread.

For an example illustrating the use of thread local storage, see Using Thread Local Storage.


Terminating a Thread

A thread runs until one of the following events occurs:

It calls ExitThread.

The thread function returns. This results in an implicit call to ExitProcess for a primary thread, or to ExitThread for other threads.

ExitProcess is invoked explicitly or implicitly by any thread of the process.

TerminateThread is called with a handle to the thread.

TerminateProcess is called with a handle to the thread's process.

When a thread terminates, the state of the thread object changes to signaled, releasing any other threads that had been waiting for the thread to terminate. Then its termination status changes from STILL_ACTIVE to the exit code of the thread.

If a thread is terminated by ExitThread, the entrypoint function of all attached DLLs is invoked with a code indicating that the thread is detaching from the DLL. If a thread is terminated by ExitProcess, the DLL entrypoint functions are invoked once, to indicate that the process is detaching. DLLs are not notified when a thread is terminated by TerminateThread or TerminateProcess. For more information about DLLs, see Dynamic-Link Libraries

The GetExitCodeThread function returns the termination status of a thread. While a thread is executing, its termination status is STILL_ACTIVE. When a thread terminates, its termination status is the exit code of the thread, which is the value specified in the call to ExitThread, ExitProcess, or TerminateThread, or the value returned by the thread function.

For more information about termination, see Terminating a Process.


Multiple Threads and GDI Objects

To enhance performance, access to graphics device interface (GDI) objects (such as palettes, device contexts, regions, and the like) is not serialized. This creates a potential danger for processes that have multiple threads sharing these objects. For example, if one thread deletes a GDI object while another thread is using it, the results are unpredictable. This danger can be avoided simply by not sharing GDI objects. If sharing is unavoidable (or desirable), the application must provide its own mechanisms for synchronizing access. For more information about synchronizing access, see Synchronizing Execution of Multiple Threads.


Creating Processes

The CreateProcess function creates a new process, which runs independently of the creating process. The function provides two methods for identifying the program to be executed. The most common method is to specify the image file's path and filename. If the lpszImageName argument is NULL, the program is identified in the CommandLine argument.

If CreateProcess succeeds, it returns a PROCESS_INFORMATION structure containing handles and identification numbers for the new process and its primary thread. The thread and process handles are created with full access rights, although access can be restricted if a security descriptor is specified.


Inheritance

A child process can inherit a number of properties and resources from its parent process. You can also prevent a child process from inheriting anything from its parent process. The following can be inherited:

Any inheritable open handle returned by the CreateFile function. This includes handles to files, console input buffers, console screen buffers, named pipes, serial communication devices, and mailslots.

Inheritable open handles to process, thread, mutex, event, semaphore, named pipe, anonymous pipe, and file mapping objects.

Environment variables.

The current directory.

The console of parent process, unless the process is detached or a new console is created. A child console process also inherits the parent's standard handles, as well as access to the input buffer and the active screen buffer. For more about console processes, see Consoles and Character-Mode Support

The fInheritHandles flag of CreateProcess determines whether the inheritable handles of the parent process are inherited by the child process. The inheritability of the handles listed above is specified in the functions used to create, open, or duplicate the handles. This allows a child process to inherit some of its parent's handles, while not inheriting others. For each of these object types there is a creation function (such as CreateProcess or CreateFile) that takes a security attributes argument whose inherit flag determines whether the handle can be inherited. If the security attributes argument is NULL, the handle is not inherited.

Some of these objects have an open function (such as OpenMutex or OpenEvent) with an inherit flag parameter that determines inheritability.

Any of these handles can be duplicated using the DuplicateHandle function by which you can specify whether the handle can be inherited. This can be useful if a process has an inheritable open handle that you do not want to be inherited by the child process. In this case, use DuplicateHandle to open a noninheritable duplicate of the handle; then use CloseHandle to close the inheritable handle. DuplicateHandle can also open an inheritable duplicate of a noninheritable handle.

An inherited handle has the same value and access privileges as the parent process's handle. To use a handle, the child process must retrieve the handle and know the object to which it refers. For most handles, the parent process must communicate this information to the child process. This can be done using the command line or any of the other methods for interprocess communication (such as pipes or shared memory).

An inherited handle refers to the same object as the parent process's handle does. When one process changes the state of the object, the change affects both processes. With file handles, for example, if one process uses a handle to read from a file, the current file position is moved for all processes using the same handle.

A child process inherits the environment variables and current directory of its parent process by default. However, CreateProcess enables the parent process to specify a different current directory or block of environment variables. For more information about environment variables, see Environment Variables.

The child process does not inherit the following:

Priority class

Memory handles

Pseudo handles, as in the handles returned by GetCurrentProcess or GetCurrentThread. These handles are valid only for the calling process. For more information about these functions, see Process and Thread Handles and Identifiers.

DLL module handles returned by LoadLibrary.

GDI or User handles, such as HBITMAP or HMENU. Refer to WINDEF.H for a complete list of these handles.


Environment Variables

Every process has an environment block that contains a set of environment variables and their values. The command processor for Microsoft® Windows NT™ (called CMD.EXE) provides the "set" command to display its environment block or to create new environment variables (as in, "set name=value"). Programs started by the command processor inherit the command processor's environment variables.

By default, a child process inherits the environment variables of its parent process. However, you can specify a different environment for the child process by creating a new environment block and passing a pointer to it as a parameter to the CreateProcess function.

The GetEnvironmentStrings function returns a pointer to the environment block of the calling process. This should be treated as a read-only block; do not modify it directly. Instead, use the SetEnvironmentVariable function to change an environment variable. The GetEnvironmentVariable function determines whether a specified variable is defined in the environment of the calling process, and, if so, what its value is. For more information about environments, see the examples in Changing Environment Variables.


StartupInfo

Setting Window Properties Using STARTUPINFO

A parent process can specify properties associated with the main window of its child process. A pointer to a STARTUPINFO structure is passed as a parameter to the CreateProcess function. The members of this structure can be used to specify more than a dozen different characteristics of the child's main window. The dwFlags member contains a bit field that determines whether the other members of the structure are used. This allows the creating process to specify values for any subset of the window properties. Default values are used for the properties not specified by dwFlags. The dwFlags member can also force a feedback cursor to be displayed during the initialization of the new process. A process can use the GetStartupInfo function to retrieve the STARTUPINFO structure specified when it was created.

For GUI processes, the STARTUPINFO structure specifies the default values to be used the first time the new process calls CreateWindow and ShowWindow to create and display an overlapped window. The following default values can be specified:

The width and height in pixels of the window created by CreateWindow.

The location in screen coordinates of the window created by CreateWindow.

The nCmdShow parameter of ShowWindow.

For console processes, use the STARTUPINFO specifications only when a new console is created either by CreateProcess with CREATE_NEW_CONSOLE or by AllocConsole. For more about console processes, see Consoles and Character-Mode Support. STARTUPINFO can specify the following console window properties:

The size, in character cells, and the location in screen coordinates of the new console window.

The size, in character cells, of the new console's screen buffer.

The text and background color attributes of the new console's screen buffer.

The title of the new console's window.


Terminating a Process

A process terminates when one of the following occurs:

Any thread of the process calls ExitProcess.

The primary thread of the process returns. This results in an implicit call to ExitProcess.

The last thread of the process terminates.

TerminateProcess is called with a handle to the process.

When a process terminates, the following events occur:

Open handles to files or other resources are closed automatically. Note that the objects referenced by these handles exist until all open handles are closed. This means that an object remains valid after a process closes, if another process has a handle to it.

The state of the process object becomes signaled, satisfying any threads that are waiting for the process to terminate. For more about synchronization, see Synchronizing Execution of Multiple Threads.

The termination status of the process changes from STILL_ACTIVE to the exit code of the process.

Child processes are not automatically terminated when a parent process terminates.

ExitProcess is the preferred way to terminate a process, because it notifies all attached DLLs of the termination, and it ensures that all threads of the process are terminated. If a process is terminated by ExitProcess, the entrypoint function of all attached DLLs is invoked with a code indicating that the process is detaching from the DLL. DLLs are not notified when a process is terminated by TerminateProcess. For more information about DLLs, see Dynamic-Link Libraries.

When a process is terminated by ExitProcess or TerminateProcess, all threads of the process are terminated immediately with no chance to run additional code (except for the DLL process detach code if ExitProcess is called). This means that the process does not execute code in termination handler blocks such as the "finally" block of the try-finally handler supported by Microsoft compilers. For more information about handlers, see Structured Exception Handling.

The primary thread of a process differs from the other threads of a process in that ExitProcess (rather than ExitThread) is invoked implicitly when a primary thread returns. Alternatively, the primary thread can avoid terminating other threads by explicitly calling ExitThread before it exits. In this case, one of the remaining threads explicitly calls ExitProcess, to ensure that all threads of the process are terminated. For example, it is possible for an attached DLL to create a thread that does not terminates unless ExitProcess is invoked.

ExitProcess can be invoked implicitly by the system. For most unhandled exceptions, the system's default action is to call ExitProcess. For console processes, ExitProcess is called by the default handler function that can be invoked when a CTRL+C or CTRL+BREAK signal is received. For more about console application, see Consoles and Character-Mode Support. Note that this default handling of console interrupt signals can terminate parent and child processes, because all processes attached to a console receive the signal. An interrupt signal received by a console window is propagated only to attached console processes. Detached processes and processes that have created new console windows are not affected. GUI processes are not affected by CTRL+C or CTRL+BREAK signals.

The GetExitCodeProcess function returns the termination status of a process. While a process is running, its termination status is STILL_ACTIVE. When a process terminates, its termination status is the exit code of the process, which is the value specified in the call to ExitProcess or TerminateProcess, or the value returned by the main or WinMain function of the process. If a process is terminated in some other way (for example, by a fatal unhandled exception or a CTRL+C signal) the process's termination code is the exception code that caused the termination. The process's exit code is also used as the exit code of all of the threads that had not previously terminated.


Process and Thread Handles and IDs

Process and Thread Handles and Identifiers

When a new thread is created by CreateThread or CreateRemoteThread, a handle of the thread is returned. Similarly, when a new process is created by CreateProcess, handles of the new process and its primary thread are returned. These handles are created with full access rights, and--subject to security access checking--can be used in any of the functions that accepts a thread or process handle. These handles can be inherited by child processes, depending on the inheritance flag specified when they are created. The handles are valid until closed, even after the process or thread they represent is terminated.

The OpenProcess function opens a handle to a process specified by its process identifier. OpenProcess enables you to specify the handle's access rights and inheritability.

A process can use the GetCurrentProcess function to retrieve a pseudohandle of its own process object; a thread can use the GetCurrentThread function to retrieve a pseudo handle to its own thread object. These pseudohandles are valid only for the calling process; they cannot be inherited or duplicated for use by other processes.

The functions that create a process or thread also return an identifier that uniquely identifies the process or thread throughout the system. A process can use the GetCurrentProcessId function to get its own process identifier. Similarly, a thread can use the GetCurrentThreadId function to get its own thread identifier. The identifiers are valid from the time the thread or process is created until the thread or process terminates.


Example: Multithreaded MDI Application

The following example shows how to use multiple threads in a multiple document interface (MDI) process. The process has a single main window, but can have any number of child windows. The primary thread of the process performs initialization and also handles messages to all windows through the MainWndProc and ChildWndProc functions.

Each time a child window is created, a new thread is also created. In this example, the new thread only checks continually to see if it is time to terminate. In a real application the new thread could be used to draw the contents of the window or to carry out the functions associated with the window.

The ThreadFunc function is specified in CreateThread as the code for the new thread to execute. The handle of the child window associated with the thread is passed as a parameter to ThreadFunc. The child window's handle is also a parameter to ChildWndProc when a message is dispatched to the child window. A handle is necessary for any communication between a child window and its corresponding thread. Both ThreadFunc and ChildWndProc use the window handle in the SetWindowLong function to access the 32-bit value that is reserved for application use in each window structure. In this example, the 32-bit value is a termination flag. When ChildWndProc gets the WM_CLOSE message, it sets the flag; ThreadFunc checks the flag each time through its loop.

This example shows how to use normal priority for the primary thread and below-normal priority for the other threads. Because the primary thread passes all messages for both the main window and the child windows, its higher relative priority ensures responsiveness to user input. (Even when the child threads are left at normal priority, the scheduler automatically boosts the priority of the input thread when necessary.)

When the user terminates the process by closing the main window, a global boolean parameter is set to terminate the child threads. At this point, the primary thread waits for each child thread to terminate before proceeding. This is necessary only if you want the threads to clean up save changes to a file, detach from DLLs before closing. Without waiting, the primary thread terminates the process by returning before the lower priority threads were able to run any additional code.

#include <windows.h>

#include <stdio.h>

#include <stdlib.h>

#define MM_NEWWIN       8001

typedef struct _PTHREADLIST {

  HANDLE hThread;

  LPVOID lpvNext;

} THREADLIST, *PTHREADLIST;

/* Globals */

HANDLE hModule;            /* handle to .EXE file for this process */

HWND   hwndMain = NULL;    /* handle to main window                */

BOOL fKillAll = FALSE;     /* sets TRUE to terminate all threads   */

PTHREADLIST pHead = NULL;  /* head of linked list of thread info. */

/* Forward declarations */

BOOL InitializeApp(VOID);

LRESULT CALLBACK MainWndProc(HWND, UINT, WPARAM, LPARAM);

LRESULT CALLBACK ChildWndProc(HWND, UINT, WPARAM, LPARAM);

DWORD ThreadFunc(HWND);

VOID AddThreadToList(HANDLE);

VOID ErrorExit(LPSTR);

/* Primary thread: Initialize the application and dispatch messages. */

int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrevInst,

        LPSTR lpszCmdLn, int nShowCmd) {

    MSG msg;

    hModule = GetModuleHandle(NULL);

    if (! InitializeApp())

        ErrorExit("InitializeApp failure!");

    while (GetMessage(&msg, NULL, 0, 0)) {

      TranslateMessage(&msg);

      DispatchMessage(&msg);

    }

    return 1;

    UNREFERENCED_PARAMETER(hInst);

    UNREFERENCED_PARAMETER(hPrevInst);

    UNREFERENCED_PARAMETER(lpszCmdLn);

    UNREFERENCED_PARAMETER(nShowCmd);

}

/* Register window classes and create the main window. */

BOOL InitializeApp(VOID) {

    HMENU hmenuMain, hmenuPopup;

    WNDCLASS wc;

    /* Register a window class for the main window. */

    wc.style            = CS_OWNDC;

    wc.lpfnWndProc      = MainWndProc;

    wc.cbClsExtra       = 0;

    wc.cbWndExtra       = 0;

    wc.hInstance        = hModule;

    wc.hIcon            = LoadIcon(NULL,IDI_APPLICATION);

    wc.hCursor          = LoadCursor(NULL, IDC_ARROW);

    wc.hbrBackground    = (HBRUSH)(COLOR_BACKGROUND+1);

    wc.lpszMenuName     = NULL;

    wc.lpszClassName    = "MainWindowClass";

    if (! RegisterClass(&wc))

        return FALSE;

    /* Register a window class for child windows. */

    wc.lpfnWndProc      = ChildWndProc;

    wc.lpszClassName    = "ThreadWindowClass";

    if (! RegisterClass(&wc))

        return FALSE;

    /* Create a menu for the main window. */

    hmenuMain = CreateMenu();

    hmenuPopup = CreateMenu();

    if (! AppendMenu(hmenuPopup, MF_STRING, MM_NEWWIN, "&New Window"))

        return FALSE;

    if (! AppendMenu(hmenuMain, MF_POPUP, (UINT) hmenuPopup, "&Threads"))

        return FALSE;

    /* Create the main window. */

    hwndMain = CreateWindow("MainWindowClass", "Primary Window",

        WS_OVERLAPPED | WS_CAPTION | WS_BORDER | WS_THICKFRAME |

        WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_CLIPCHILDREN |

        WS_VISIBLE | WS_SYSMENU, CW_USEDEFAULT, CW_USEDEFAULT,

        CW_USEDEFAULT, CW_USEDEFAULT, NULL, hmenuMain, hModule,

        NULL);

    if (hwndMain == NULL)

        return FALSE;

    /* Set the initial focus. */

    SetFocus(hwndMain);

    return TRUE;

}

/* Main window procedure: Handle messages for the main window. */

LRESULT CALLBACK MainWndProc(HWND hwnd, UINT uiMessage,

        WPARAM wParam, LPARAM lParam) {

    static HWND hwndClient;

    static DWORD dwCount = 1;

    CLIENTCREATESTRUCT ccsClientCreate;

    HWND hwndChildWnd;

    DWORD IDThread;

    PTHREADLIST pNode;

    switch (uiMessage) {

       /* Create a client window to receive child window messages. */

       case WM_CREATE:

           ccsClientCreate.hWindowMenu = NULL;

           ccsClientCreate.idFirstChild = 1;

           hwndClient = CreateWindow("MDICLIENT", NULL,

               WS_CHILD | WS_CLIPCHILDREN | WS_VISIBLE, 0, 0, 0, 0,

               hwnd, NULL, hModule, (LPVOID)&ccsClientCreate);

           return 0L;

       /*

        * Close the main window. First set fKillAll to TRUE to

        * terminate all threads. Then wait for the threads to exit

        * before passing a close message to a default handler. If you

        * don't wait for threads to terminate, process terminates

        * with no chance for thread cleanup.

        */

       case WM_CLOSE:

           fKillAll = TRUE;

           pNode = pHead;

           while (pNode) {

               DWORD dwRes;

               SetThreadPriority(pNode->hThread,

                   THREAD_PRIORITY_HIGHEST);

               dwRes = WaitForSingleObject(pNode->hThread,

                   INFINITE);

               pNode = (PTHREADLIST) pNode->lpvNext;

           }

           return DefFrameProc(hwnd, hwndClient, uiMessage,

               wParam, lParam);

       /* Terminate the process. */

       case WM_DESTROY:

           PostQuitMessage(0);

           return 0L;

       /* Handle the menu commands. */

       case WM_COMMAND:

           switch (LOWORD(wParam)) {

           /* Create a child window and start a thread for it. */

             case MM_NEWWIN: {

               HANDLE hThrd;

               MDICREATESTRUCT mdicCreate;

               TCHAR tchTitleBarText[32];

               LONG lPrev;

               sprintf(tchTitleBarText, "Thread Window %d", dwCount);

               mdicCreate.szClass = "ThreadWindowClass";

               mdicCreate.szTitle = tchTitleBarText;

               mdicCreate.hOwner  = hModule;

               mdicCreate.x = mdicCreate.y =

               mdicCreate.cx = mdicCreate.cy = CW_USEDEFAULT;

               mdicCreate.style = mdicCreate.lParam = 0L;

               /* Send a "create child window" message to the client window. */

               hwndChildWnd = (HWND) SendMessage(hwndClient,

                   WM_MDICREATE, 0L, (LONG)&mdicCreate);

               if (hwndChildWnd == NULL)

                   ErrorExit("Failed in Creating Thread Window!");

               /* Window structure used to pass a quit message to the thread. */

               lPrev = SetWindowLong(hwndChildWnd, GWL_USERDATA, 0);

               /* Create suspended, alter priority before resuming. */

               hThrd = CreateThread(NULL,  /* no security attributes */

                         0,                /* use default stack size */

                         (LPTHREAD_START_ROUTINE) ThreadFunc,

                         (LPVOID)hwndChildWnd, /* parameter to thrd func */

                         CREATE_SUSPENDED, /* creation flag          */

                         &IDThread);       /* returns thread id      */

               if (hThrd == NULL)

                   ErrorExit("CreateThread Failed!");

               AddThreadToList(hThrd);

               dwCount++;

               /*

                * Set the priority lower than the primary (input) thread, so

                * that the process is responsive to user input. Then resume

                * the thread.

                */

               if (! SetThreadPriority(hThrd,

                       THREAD_PRIORITY_BELOW_NORMAL))

                   ErrorExit("SetThreadPriority failed!");

               if ((ResumeThread(hThrd)) == -1)

                   ErrorExit("ResumeThread failed!");

               return 0L;

             }

             default:

               return DefFrameProc(hwnd, hwndClient, uiMessage,

                              wParam, lParam);

           }

       default:

           return DefFrameProc(hwnd, hwndClient, uiMessage,

                          wParam, lParam);

    }

}

/* Handle messages for the child windows. */

LRESULT CALLBACK ChildWndProc(HWND hwnd, UINT uiMessage, WPARAM wParam, LPARAM lParam) {

    LONG lPrevLong;

    switch (uiMessage) {

        /* Use a window structure to pass "close" message to the thread. */

        case WM_CLOSE:

            lPrevLong = SetWindowLong(hwnd, GWL_USERDATA, 1);

            return DefMDIChildProc(hwnd, uiMessage, wParam, lParam);

        case WM_DESTROY:

            return 0L;

        default:

            return DefMDIChildProc(hwnd, uiMessage, wParam, lParam);

    }

}

/*

 * Each child window has a thread that can be used to perform tasks

 * associated with that window--for example, drawing its contents.

 */

DWORD ThreadFunc(HWND hwnd) {

    LONG lKillMe = 0L;

    while (TRUE) {

        lKillMe = GetWindowLong(hwnd, GWL_USERDATA);

        if (fKillAll || lKillMe) break;

        /* Perform tasks. */

    }

        /* Perform actions needed before thread termination. */

    return 0;

}

VOID AddThreadToList(HANDLE hThread) {

    PTHREADLIST pNode;

    pNode = (PTHREADLIST) LocalAlloc(LPTR, sizeof(PTHREADLIST));

    if (pNode == NULL)

        ErrorExit("malloc Failed!");

    pNode->hThread = hThread;

    pNode->lpvNext = (LPVOID) pHead;

    pHead = pNode;

}

VOID ErrorExit(LPSTR lpszMessage) {

    MessageBox(hwndMain, lpszMessage, "Error", MB_OK);

    ExitProcess(0);

}


Example: Child Process With Redirected I/O

Example: Child Process with Redirected Input and Output

The following example shows the creation of a child process by a console process and illustrates a technique for using anonymous pipes to redirect the child process's standard input and output. If you have a program that can read its input from STDIN or write its results to STDOUT, redirected I/O enables you to execute the program as a child process while controlling its input and receiving its output.

The example shows how to use a SECURITY_ATTRIBUTES structure to create handles that can be inherited by the child process. The structure is used in the CreatePipe function to create inheritable handles to the read and write ends of two pipes. The read end of one pipe serves as standard input for the child process, and the write end of the other pipe is the child's standard output. These pipe handles are specified in the SetStdHandle function, which makes them the standard handles inherited by the child process. After the child process is created, SetStdHandle is used again to restore the original standard handles for the parent process.

The parent process uses the other ends of the pipes to write to the child's input and read the child's output. The handles to these ends of the pipe are also inheritable. However, the handle must not be inherited. Before creating the child process, the parent process must use DuplicateHandle to create a non-inheritable duplicate of hChildStdinWr. It then uses CloseHandle to close the inheritable handle. This leaves the parent process with a pipe handle it can use, but which the child process does not inherit. For more information about pipes, see Pipes.

Here's the parent process:

#include <stdio.h>

#include <windows.h>

#define BUFSIZE 4096

HANDLE hChildStdinRd, hChildStdinWr, hChildStdinWrDup,

    hChildStdoutRd, hChildStdoutWr,

    hInputFile, hSaveStdin, hSaveStdout;

BOOL CreateChildProcess(VOID);

VOID WriteToPipe(VOID);

VOID ReadFromPipe(VOID);

VOID ErrorExit(LPTSTR);

VOID ErrMsg(LPTSTR, BOOL);

DWORD main(int argc, char *argv[]) {

    SECURITY_ATTRIBUTES saAttr;

    BOOL fSuccess;

    /* Set the bInheritHandle flag so pipe handles are inherited. */

    saAttr.nLength = sizeof(SECURITY_ATTRIBUTES);

    saAttr.bInheritHandle = TRUE;

    saAttr.lpSecurityDescriptor = NULL;

    /*

     * The steps for redirecting child's STDOUT:

     *     1. Save current STDOUT, to be restored later.

     *     2. Create anonymous pipe to be STDOUT for child.

     *     3. Set STDOUT of parent to be write handle of pipe, so

     *         it is inherited by child.

     */

    /* Save the handle to the current STDOUT. */

    hSaveStdout = GetStdHandle(STD_OUTPUT_HANDLE);

    /* Create a pipe for the child's STDOUT. */

    if (! CreatePipe(&hChildStdoutRd, &hChildStdoutWr, &saAttr, 0))

        ErrorExit("Stdout pipe creation failed\n");

    /* Set a write handle to the pipe to be STDOUT. */

    if (! SetStdHandle(STD_OUTPUT_HANDLE, hChildStdoutWr))

        ErrorExit("Redirecting STDOUT failed");

    /*

     * The steps for redirecting child's STDIN:

     *     1. Save current STDIN, to be restored later.

     *     2. Create anonymous pipe to be STDIN for child.

     *     3. Set STDIN of parent to be read handle of pipe, so

     *         it is inherited by child.

     *     4. Create a noninheritable duplicate of write handle,

     *         and close the inheritable write handle.

     */

    /* Save the handle to the current STDIN. */

    hSaveStdin = GetStdHandle(STD_INPUT_HANDLE);

    /* Create a pipe for the child's STDIN. */

    if (! CreatePipe(&hChildStdinRd, &hChildStdinWr, &saAttr, 0))

        ErrorExit("Stdin pipe creation failed\n");

    /* Set a read handle to the pipe to be STDIN. */

    if (! SetStdHandle(STD_INPUT_HANDLE, hChildStdinRd))

        ErrorExit("Redirecting Stdin failed");

    /* Duplicate the write handle to the pipe, so it is not inherited. */

    fSuccess = DuplicateHandle(GetCurrentProcess(), hChildStdinWr,

        GetCurrentProcess(), &hChildStdinWrDup, 0,

        FALSE,       /* not inherited */

        DUPLICATE_SAME_ACCESS);

    if (! fSuccess)

        ErrorExit("DuplicateHandle failed");

    CloseHandle(hChildStdinWr);

    /* Now create the child process. */

    if (! CreateChildProcess())

        ErrorExit("Create process failed");

    /* After process creation, restore the saved STDIN and STDOUT. */

    if (! SetStdHandle(STD_INPUT_HANDLE, hSaveStdin))

        ErrorExit("Re-redirecting Stdin failed\n");

    if (! SetStdHandle(STD_OUTPUT_HANDLE, hSaveStdout))

        ErrorExit("Re-redirecting Stdout failed\n");

    /* Get a handle to the parent's input file. */

    if (argc > 1)

        hInputFile = CreateFile(argv[1], GENERIC_READ, 0, NULL,

            OPEN_EXISTING, FILE_ATTRIBUTE_READONLY, NULL);

    else

        hInputFile = hSaveStdin;

    if (hInputFile == INVALID_HANDLE_VALUE)

        ErrorExit("no input file\n");

    /* Write to the pipe that is the standard input for a child process. */

    WriteToPipe();

    /* Read from the pipe that is the standard output for the child process. */

    ReadFromPipe();

    return 0;

}

BOOL CreateChildProcess() {

    PROCESS_INFORMATION piProcInfo;

    STARTUPINFO siStartInfo;

    /* Set up members of STARTUPINFO structure. */

    siStartInfo.cb = sizeof(STARTUPINFO);

    siStartInfo.lpReserved = NULL;

    siStartInfo.lpReserved2 = NULL;

    siStartInfo.cbReserved2 = 0;

    siStartInfo.lpDesktop = NULL;

    siStartInfo.dwFlags = 0;

    /* Create the child process. */

    return CreateProcess(NULL,

        "child",       /* command line                       */

        NULL,          /* process security attributes        */

        NULL,          /* primary thread security attributes */

        TRUE,          /* handles are inherited              */

        0,             /* creation flags                     */

        NULL,          /* use parent's environment           */

        NULL,          /* use parent's current directory     */

        &siStartInfo,  /* STARTUPINFO pointer                */

        &piProcInfo);  /* receives PROCESS_INFORMATION       */

VOID WriteToPipe(VOID) {

    DWORD dwRead, dwWritten;

    CHAR chBuf[BUFSIZE];

    /* Read from a file and write its contents to a pipe. */

    for (;;) {

        if (! ReadFile(hInputFile, chBuf, BUFSIZE, &dwRead, NULL) ||

            dwRead == 0) break;

        if (! WriteFile(hChildStdinWrDup, chBuf, dwRead,

            &dwWritten, NULL)) break;

    }

    /* Close the pipe handle so the child stops reading. */

    if (! CloseHandle(hChildStdinWrDup))

        ErrorExit("Close pipe failed\n");

}

VOID ReadFromPipe(VOID) {

    DWORD dwRead, dwWritten;

    CHAR chBuf[BUFSIZE];

    HANDLE hStdout = GetStdHandle(STD_OUTPUT_HANDLE);

    /* Close the write end of the pipe before reading from the read end of the pipe. */

    if (! CloseHandle(hChildStdoutWr))

        ErrorExit("Closing handle failed");

    /* Read output from the child, and write it to the parent's STDOUT. */

    for (;;) {

        if (! ReadFile(hChildStdoutRd, chBuf, BUFSIZE, &dwRead, NULL) ||

            dwRead == 0) break;

        if (! WriteFile(hSaveStdout, chBuf, dwRead, &dwWritten, NULL))

            break;

    }

}

VOID ErrorExit (LPTSTR lpszMessage) {

    fprintf(stderr, "%s\n", lpszMessage);

    ExitProcess(0);

}

Here's the child process:

#include <windows.h>

#define BUFSIZE 4096

VOID main(VOID) {

    CHAR chBuf[BUFSIZE];

    DWORD dwRead, dwWritten;

    HANDLE hStdin, hStdout;

    BOOL fSuccess;

    hStdout = GetStdHandle(STD_OUTPUT_HANDLE);

    hStdin = GetStdHandle(STD_INPUT_HANDLE);

    if ((hStdout == INVALID_HANDLE_VALUE) ||

        (hStdin == INVALID_HANDLE_VALUE))

        ExitProcess(1);

    for (;;) {

      /* Read from standard input. */

      fSuccess = ReadFile(hStdin, chBuf, BUFSIZE, &dwRead, NULL);

      if (! fSuccess || dwRead == 0)

          break;

      /* Write to standard output. */

      fSuccess = WriteFile(hStdout, chBuf, dwRead, &dwWritten, NULL);

      if (! fSuccess)

          break;

    }

}


Changing Environment Variables

The environment block consists of a null-terminated block of null-terminated strings (that is, two null bytes at the end of the block), where each string is in the form: NAME=value. Because the equal sign is a separator, it must not be used in the name of an environment variable. The following example creates a new environment block to pass to a child process:

TCHAR tchNewEnv[BUFSIZE];

LPTSTR lpszCurrentVariable;

BOOL fSuccess;

/* Copy name=value environment variable pairs into the environment block. */

lpszCurrentVariable = tchNewEnv;

if (lstrcpy(lpszCurrentVariable, "OperatingSystem=Windows NT") == NULL)

    ErrorExit("lstrcpy failed");

lpszCurrentVariable += lstrlen(lpszCurrentVariable) + 1;

if (lstrcpy(lpszCurrentVariable, "API=Win32") == NULL)

    ErrorExit("lstrcpy failed");

/* Terminate the block with a NULL byte. */

lpszCurrentVariable += lstrlen(lpszCurrentVariable) + 1;

*lpszCurrentVariable = '\0';

/* Create the child process, specifying a new environment block. */

fSuccess = CreateProcess(NULL, "childenv", NULL, NULL, TRUE, 0,

    (LPVOID) tchNewEnv,     /* new environment block */

    NULL, &siStartInfo, &piProcInfo);

if (! fSuccess)

    ErrorExit("CreateProcess failed");

If you want the child process to inherit most of the parent's environment with only a few changes, save the current values, make changes for the child to inherit, and then restore the saved values for example:

LPTSTR lpszOldValue;

TCHAR tchBuf[BUFSIZE];

BOOL fSuccess;

/*

 * lpszOldValue gets current value of "varname", or NULL if "varname"

 * environment variable does not exist. Set "varname" to new value,

 * create child process, then use SetEnvironmentVariable to restore

 * original value of "varname". If lpszOldValue is NULL, the "varname"

 * variable will be deleted.

 */

lpszOldValue = ((GetEnvironmentVariable("varname", tchBuf, BUFSIZE) > 0) ?

    tchBuf : NULL);

/* Set a value for the child to inherit. */

if (! SetEnvironmentVariable("varname", "newvalue"))

    ErrorExit("SetEnvironmentVariable failed");

/* Create a child process. */

fSuccess = CreateProcess(NULL, "childenv", NULL, NULL, TRUE, 0,

    NULL,     /* inherit parent's environment */

    NULL, &siStartInfo, &piProcInfo);

if (! fSuccess)

    ErrorExit("CreateProcess failed");

/* Restore the parent's environment. */

if (! SetEnvironmentVariable("varname", lpszOldValue))

    ErrorExit("SetEnvironmentVariable failed");

The following example, taken from a console process, prints the contents of the process's environment block.

LPTSTR lpszVariable;

LPVOID lpvEnv;

/* Get a pointer to the environment block. */

lpvEnv = GetEnvironmentStrings();

/*

 * Variable strings are separated by NULL byte, and the block is

 * terminated by a NULL byte.

 */

for (lpszVariable = (LPTSTR) lpvEnv; *lpszVariable; lpszVariable++) {

    while (*lpszVariable)

        putchar(*lpszVariable++);

    putchar('\n');

}


Using Thread Local Storage

Thread local storage (TLS) enables multiple threads of the same process to use an index allocated by TlsAlloc to store and retrieve a value that is local to the thread. In this example, an index is allocated when the process starts. When each thread starts, it allocates a block of dynamic memory and stores a pointer to this memory by using the TLS index. The TLS index is used by the CommonFunc function to access the data local to the calling thread. Before each thread terminates, it releases its dynamic memory.

#include <stdio.h>

#include <windows.h>

#define THREADCOUNT 4

DWORD dwTlsIndex;

VOID ErrorExit(LPTSTR);

VOID CommonFunc(VOID) {

  LPVOID lpvData;

    /* Retrieve a data pointer for the current thread. */

    lpvData = TlsGetValue(dwTlsIndex);

    if ((lpvData == 0) && (GetLastError() != 0))

        ErrorExit("TlsGetValue error");

    /*

     *    Use the data stored for the current thread.

     */

    printf("common: thread %d: lpvData=%lx\n",

        GetCurrentThreadId(), lpvData);

    Sleep(5000);

}

DWORD ThreadFunc(VOID) {

    LPVOID lpvData;

    /* Initialize the TLS index for this thread. */

    lpvData = (LPVOID) LocalAlloc(LPTR, 256);

    if (! TlsSetValue(dwTlsIndex, lpvData))

        ErrorExit("TlsSetValue error");

    printf("thread %d: lpvData=%lx\n", GetCurrentThreadId(), lpvData);

    CommonFunc();

    /* Release the dynamic memory before the thread returns. */

    lpvData = TlsGetValue(dwTlsIndex);

    if (lpvData != 0)

        LocalFree((HLOCAL) lpvData);

    return 0;

}

DWORD main(VOID) {

    DWORD IDThread;

    HANDLE hThread[THREADCOUNT];

    int i;

    /* Allocate a TLS index. */

    if ((dwTlsIndex = TlsAlloc()) == 0xFFFFFFFF)

        ErrorExit("TlsAlloc failed");

    /* Create multiple threads. */

    for (i = 0; i < THREADCOUNT; i++) {

        hThread[i] = CreateThread(NULL,/* no security attributes    */

            0,                       /* use default stack size      */

            (LPTHREAD_START_ROUTINE) ThreadFunc, /* thread function */

            NULL,                    /* no thread function argument */

            0,                       /* use default creation flags  */

            &IDThread);              /* returns thread identifier   */

        /* Check the return value for success. */

        if (hThread[i] == NULL)

            ErrorExit("CreateThread error\n");

    }

    for (i = 0; i < THREADCOUNT; i++)

        WaitForSingleObject(hThread[i], INFINITE);

    return 0;

}

VOID ErrorExit (LPTSTR lpszMessage) {

    fprintf(stderr, "%s\n", lpszMessage);

    ExitProcess(0);

}


Functions

Following are the functions used with processes.

AttachThreadInput

CreateProcess

CreateRemoteThread

CreateThread

DuplicateHandle

ExitProcess

ExitThread

GetCommandLine

GetCurrentProcess

GetCurrentProcessId

GetCurrentThread

GetCurrentThreadId

GetEnvironmentStrings

GetEnvironmentVariable

GetExitCodeProcess

GetExitCodeThread

GetPriorityClass

GetProcessShutdownParameters

GetProcessTimes

GetStartupInfo

GetThreadPriority

GetThreadTimes

LoadModule (obsolete)

OpenProcess

ResumeThread

SetEnvironmentVariable

SetPriorityClass

SetProcessShutdownParameters

SetThreadPriority

Sleep

SleepEx

SuspendThread

TerminateProcess

TerminateThread

TlsAlloc

TlsFree

TlsGetValue

TlsSetValue

WaitForInputIdle

WinExec (obsolete)

Yield (obsolete)


Synchronization Overview

About Synchronization

The Microsoft Win32™ application programming interface (API) provides a variety of ways to coordinate multiple threads of execution. This topic describes the use of the following synchronization mechanisms:

Wait functions and synchronization objects

Overlapped input and output (I/O) operations

Critical section objects

Interlocked variable access

The following topics discuss synchronization:

Terms

Wait Functions

Synchronization Objects

Mutex Objects

Semaphore Objects

Event Objects

Sharing Mutex, Semaphore, and Event Objects

Synchronization and Overlapped Input and Output

Critical Section Objects

Interlocked Variable Access

Using Named Objects

Waiting for Multiple Objects

Using Event Objects

Using a Mutex Object

Using a Semaphore Object

Using Critical Section Objects

Functions


Wait Functions

The Win32 API provides a set of wait functions that enable a thread to block its own execution. These functions do not return until a set of conditions specified by the wait function's parameters have been satisfied. These parameters include a time-out interval and handles of one or more synchronization objects. For more information about synchronization objects, see Synchronization Objects.

When a wait function is called, it checks the state of the specified synchronization object or objects and any other conditions that could cause it to return. If this initial state does not satisfy the specified conditions and the time-out interval has not elapsed, the calling thread enters an efficient wait state, consuming very little processor time while waiting for the conditions to be satisfied. The time-out interval can be set to INFINITE to cause an indefinite wait.

The WaitForSingleObject and WaitForSingleObjectEx functions require a handle of one synchronization object. These functions return when the state of the object is signaled, or when the time-out interval elapses. (The state of a synchronization object is either signaled or nonsignaled.)

The WaitForMultipleObjects, WaitForMultipleObjectsEx, and MsgWaitForMultipleObjects functions enable the calling thread to specify an array containing one or more synchronization object handles. These functions can be set to return when the state of any one of the specified objects is signaled, in which case the return value indicates the array index of the object that caused the function to return. Alternatively, the functions can be set to return only when the state of all objects is signaled at the same time, in which case the return value simply indicates that the specified conditions were satisfied.

When waiting for all objects to be signaled, these multiple-object functions do not modify the state of the specified objects until all objects are signaled simultaneously. For example, a mutex can be signaled, but the calling thread does not get ownership of it until the other objects are also signaled. In the meantime, some other thread may get ownership of the mutex, thereby delaying satisfaction of all specified conditions.

The WaitForSingleObjectEx and WaitForMultipleObjectsEx functions differ from the other wait functions in that they can optionally perform an alertable wait. In an alertable wait, the function can return when the specified conditions are satisfied, but it can also return if the system queues a completion routine for execution by the waiting thread. For more information about alertable waits and input and output (I/O) completion routines, see Synchronization and Overlapped Input and Output.

The MsgWaitForMultipleObjects function is identical to WaitForMultipleObjects, except that it can also return when a specified type of input is available in the calling thread's input queue. For example, a thread could use MsgWaitForMultipleObjects to block its execution until either the state of a specified object is signaled, or there is mouse input available in the thread's input queue. When input is available, the thread can use the GetMessage or PeekMessage function to retrieve it.

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. A wait function can modify the state of synchronization objects as follows:

The count of a semaphore object decreases by one, with the semaphore's state changing to nonsignaled if its count is zero.

The state of mutex, auto-reset event, and change notification objects changes to nonsignaled.

The state of manual-reset event, process, thread, and console input objects is not affected by a wait function.


Synchronization Objects

A synchronization object is an object whose handle can be specified in one of the wait functions to coordinate the execution of multiple threads. The state of a synchronization object is either signaled, which can allow the wait function to return, or nonsignaled, which can prevent the function from returning. More than one process can have a handle of the same synchronization object, making interprocess synchronization possible.

The Win32 API provides the following three object types intended exclusively for synchronization.

Type	Description

event	Notifies one or more waiting threads that an event has occurred.

mutex	Can be owned by only one thread at a time, enabling threads to coordinate mutually exclusive access to a shared resource.

semaphore	Maintains a count between zero and some maximum value, limiting the number of threads that are simultaneously accessing a shared resource.

Though available for other uses, the following objects can also be used for synchronization.

Object	Description

change notification	Created by the FindFirstChangeNotification function, its state is signaled when a specified type of change occurs within a specified directory or directory tree.

console input	Created when a console is created, when a handle to console input is returned by the CreateFile function when CONIN$ is specified, or by the GetStdHandle function. Its state is signaled when there is unread input in the console's input buffer, and nonsignaled when the input buffer is empty.

process	Created when a new process is created by calling the CreateProcess function, its state is nonsignaled while the process is running, and signaled when the process terminates.

thread	Created when a new thread is created by calling the CreateProcess, CreateThread, or CreateRemoteThread function, its state is nonsignaled while the thread is running, and signaled when the thread terminates.

In some circumstances you can also use a file, named pipe, or communications device as a synchronization object; however, their use for this purpose is discouraged. For additional information, see Synchronization and Overlapped Input and Output.


Mutex Objects

A mutex object is a synchronization object whose state is 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, whose name comes from the fact that it is useful in coordinating mutually exclusive access to a shared resource. For example, to prevent two threads from writing to shared memory at the same time, each thread waits for ownership of a mutex before executing the code that accesses the memory. After writing to the shared memory, the thread releases the mutex.

A thread uses the CreateMutex function to create a mutex object. The creating thread can request immediate ownership of the mutex and can also specify a name for the mutex object. Threads in other processes can open a handle of an existing mutex object by specifying its name in a call to the OpenMutex function. For additional information about names for mutex, event, and semaphore objects, see Interprocess Synchronization.

Any thread with a handle of a mutex object can use one of the wait functions to request ownership of the mutex. If the mutex is owned by another thread, the wait function blocks the execution of the requesting thread until the owning thread releases the mutex using the ReleaseMutex function. The return value of the wait function indicates whether the function returned for some reason other than the state of the mutex being signaled.

Once a thread owns a mutex, it can specify the same mutex in repeated wait-function calls without blocking its execution. This prevents a thread from deadlocking itself while waiting for a mutex that it already owns. To release its ownership under such circumstances, the thread must call ReleaseMutex once for each time that the mutex satisfied the conditions of a wait function.

If a thread terminates without releasing its ownership of a mutex object, the mutex is considered to be abandoned. A waiting thread can acquire ownership of an abandoned mutex, but the wait function's return value indicates that the mutex is abandoned. It is best to assume that an abandoned mutex indicates that an error has occurred and that any shared resource being protected by the mutex is in an undefined state. If the thread proceeds normally, as though the mutex had not been abandoned, the mutex's abandoned flag is cleared when the thread releases its ownership. This restores normal mutex behavior if the mutex is subsequently specified in a wait function.


Semaphore Objects

Semaphore Objects

A semaphore object is a synchronization object that maintains a count between zero and a specified maximum value. A semaphore's state is signaled when its count is greater than zero, and nonsignaled when its count is zero.

The semaphore object is useful in controlling a shared resource that can support a limited number of users. It acts like a gate that counts the threads as they enter and exit a controlled area and limits the number of threads sharing the resource to a specified maximum number. For example, an application might want to place a limit on the number of windows that it creates. It uses a semaphore with a maximum count equal to the window limit, decrementing the count whenever a window is created and incrementing it whenever a window is closed. The application specifies the semaphore object in a wait function before each window is created. When the count is zero--indicating that the window limit has been reached--the wait function blocks execution of the window-creation code.

A thread uses the CreateSemaphore function to create a semaphore object. The creating thread specifies the initial count and the maximum count of the object. The initial count must be neither less than zero nor greater than the maximum count. The creating thread can also specify a name for the semaphore object. Threads in other processes can open a handle of an existing semaphore object by specifying its name in a call to the OpenSemaphore function. For additional information about names for mutex, event, and semaphore objects, see Interprocess Synchronization.

Each time that a wait function returns because of a semaphore's signaled state, the count of the semaphore is decreased by one. The ReleaseSemaphore function increases a semaphore's count by a specified amount. The count can never be less than zero or greater than the maximum count.

The initial count of a semaphore is typically set to the maximum value. The count is then decremented from that level as the protected resource is consumed. Alternatively, a semaphore can be created with an initial count of zero to block access to the protected resource while the application is being initialized. After initialization, you would use ReleaseSemaphore to increment the count to the maximum.

Threads do not acquire ownership of semaphore objects as they do with mutex objects. A thread that owns a mutex can wait repeatedly for the same mutex object without its execution becoming blocked. A thread that waits repeatedly for the same semaphore object, however, decrements the semaphore's count each time a wait is satisfied; its execution is blocked when the count gets to zero. Similarly, only the thread that owns a mutex can successfully call the ReleaseMutex function, though any thread can use ReleaseSemaphore to increase the count of a semaphore object, even if the thread never used a wait function to decrement the count.

A thread can decrement a semaphore's count more than once by repeatedly specifying the same semaphore object in calls to any of the wait functions. However, calling the WaitForMultipleObjects function with an array that contains multiple handles of the same semaphore does not perform multiple decrements.


Event Objects

Event Objects

An event object is a synchronization object whose state can be set to signaled explicitly by use of the SetEvent or PulseEvent function. Following are the two types of event object.

Object	Description

manual-reset event	An event object whose state remains signaled until it is explicitly reset to nonsignaled by the ResetEvent function. While it is signaled, any number of waiting threads, or threads that subsequently specify the same event object in one of the wait functions, can be released.

auto-reset event	An event object whose state 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.

The event object is useful in signaling a thread that a particular event has occurred. For example, in overlapped input and output, the system sets a specified event object to the signaled state when the overlapped operation has been completed. A single thread can specify different event objects in several simultaneous overlapped operations, then use the WaitForMultipleObjects function to wait for the state of any one of the event objects to be signaled.

A thread uses the CreateEvent function to create an event object. The creating thread specifies the initial state of the object and whether it is a manual-reset or auto-reset event object. The creating thread can also specify a name for the event object. Threads in other processes can open a handle of an existing event object by specifying its name in a call to the OpenEvent function. For additional information about names for mutex, event, and semaphore objects, see Interprocess Synchronization.

A thread can use the PulseEvent function to set an event object's state to signaled and then reset it to nonsignaled after releasing the appropriate number of waiting threads. For a manual-reset event object, all waiting threads that can be released immediately are released. For an auto-reset event object, the function releases only 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.


Interprocess Synchronization

Multiple processes can have handles of the same mutex, semaphore, or event object, so these objects can be used to accomplish interprocess synchronization. The process that creates an object can use the handle returned by the creation function (CreateEvent, CreateMutex, or CreateSemaphore). Other processes can open a handle of the object by using its name, or through inheritance or duplication.

Object Names

Named objects provide an easy way for processes to share object handles. The name specified by the creating process is limited to MAX_PATH characters, and can include any character except the backslash path-separator character (\). Once a process has created a named event, mutex, or semaphore object, other processes can use the name to call the appropriate function (OpenEvent, OpenMutex, or OpenSemaphore) to open a handle of the object. Name comparison is case sensitive. The names of event, semaphore, mutex, and file-mapping objects share the same name space, so an error occurs if a specified name matches the name of an existing object of a different type. When creating named objects, therefore, use unique names and be sure to check function return values for duplicate-name errors.

If the name specified in a call to the CreateMutex function matches the name of an existing mutex object, the function returns a handle of the existing object. In this case, the call to CreateMutex is equivalent to a call to the OpenMutex function. (The CreateEvent and CreateSemaphore functions work the same way with existing named event and semaphore objects, respectively.) Having multiple processes use CreateMutex for the same mutex is therefore equivalent to having one process that calls CreateMutex while the other processes call OpenMutex, except that it eliminates the need to ensure that the creating process is started first. When using this technique for mutex objects, however, none of the calling processes should request immediate ownership of the mutex. If multiple processes do request immediate ownership, it can be difficult to predict which process actually gets the initial ownership.

Object Inheritance

A child process created by the CreateProcess function can inherit a handle of a mutex, event, or semaphore if the SECURITY_ATTRIBUTES structure--specified when the object was created--enabled inheritance. The handle inherited by the child process has the same access to the object as the parent's handle. The inherited handle appears in the handle table of the child process, but for the child process to be able to use the handle, the parent process must communicate the handle's value to the child process. The parent can do this by specifying the value as a command-line argument when it calls the CreateProcess function. The child process can then use the GetCommandLine function to retrieve the command-line string and convert the handle argument into a usable handle.

Object Duplication

The DuplicateHandle function creates a duplicate handle that can be used by another specified process. This method of sharing object handles is more complex than using named objects or inheritance. It requires communication between the creating process and the process into which the handle is duplicated. The necessary information (the handle value and process identifier) can be communicated by any of the interprocess communication methods (for example, named pipe, shared file, shared memory).


Synchronization and Overlapped Input and Output

The Win32 API supports both synchronous and asynchronous (or overlapped) I/O operations on files, named pipes, and serial communications devices. The WriteFile, ReadFile, DeviceIoControl, WaitCommEvent, ConnectNamedPipe, and TransactNamedPipe functions can be performed either synchronously or asynchronously. The ReadFileEx and WriteFileEx functions can be performed asynchronously only.

When a function is executed synchronously, it does not return until the operation has been completed. This means that the execution of the calling thread can be blocked for an indefinite period while it waits for a time-consuming operation to finish. Functions called for overlapped operation can return immediately, even though the operation has not been completed. This enables a time-consuming I/O operation to be executed in the background while the calling thread is free to perform other tasks. For example, a single thread can perform simultaneous I/O operations on different handles, or even simultaneous read and write operations on the same handle. To synchronize its execution with the completion of the overlapped operation, the calling thread uses the GetOverlappedResult function or one of the wait functions to determine when the operation has been completed.

Overlapped operations require a file, named pipe, or communications device that was created with the FILE_FLAG_OVERLAPPED flag. To call a function as an overlapped operation, the calling thread must specify a pointer to an OVERLAPPED structure. If this pointer is NULL, the operation is performed synchronously, even though the handle was created with FILE_FLAG_OVERLAPPED enabled. The OVERLAPPED structure must contain a handle to a manual-reset--not an auto-reset--event object. The system sets the state of the event object to nonsignaled when a call to the I/O function returns before the operation has been completed. The system sets the state of the event object to signaled when the operation has been completed.

When a function is called as an overlapped operation, the operation may have been completed before the function returns. When this happens, the results are handled as if the operation had been performed synchronously. If the operation has not yet been completed, however, the function's return value is FALSE, and the GetLastError function returns ERROR_IO_PENDING.

A thread can manage overlapped operations by either of two methods. It can use the GetOverlappedResult function to wait for the overlapped operation to be completed. Alternatively, it can specify a handle of the OVERLAPPED structure's manual-reset event object in one of the wait functions and then call GetOverlappedResult after the wait function returns. GetOverlappedResult returns the results of the completed overlapped operation, and for functions in which such information is appropriate, it reports the actual number of bytes that were transferred.

When performing multiple simultaneous overlapped operations, the calling thread must specify a separate OVERLAPPED structure with its own manual-reset event object for each operation. The thread can then specify handles of the different event objects in the handle-array parameter of the WaitForMultipleObjects function (or one of the other multiple-object wait functions) to wait for any one of the overlapped operations to be completed. The return value of the multiple-object wait function indicates which event object was signaled, so the thread can determine which operation was completed.

If no event object is specified in the OVERLAPPED structure, the system signals the state of the file, named pipe, or communications device when the overlapped operation has been completed. Thus, you can specify these handles as synchronization objects in a wait function, though their use for this purpose can be difficult to manage. When performing simultaneous overlapped operations on the same file, named pipe, or communications device, there is no way to know which operation caused the object's state to be signaled. It is safer to use a separate event object for each overlapped operation.


Critical Section Objects

Critical section objects provide synchronization similar to that provided by mutex objects, except that critical section objects can be used only by the threads of a single process. Event, mutex, and semaphore objects can also be used in a single-process application, but critical section objects provide a slightly faster, more efficient mechanism for mutual-exclusion synchronization. Like a mutex object, a critical section object can be owned by only one thread at a time, which makes it useful for protecting a shared resource from simultaneous access. For example, a process could use a critical section object to prevent more than one thread at a time from modifying a global data structure.

The process is responsible for allocating the memory used by a critical section object. Typically, this is done by simply declaring a variable of type CRITICAL_SECTION. Before the threads of the process can use it, the critical section object must be initialized by using the InitializeCriticalSection function.

A thread uses the EnterCriticalSection function to request ownership and the LeaveCriticalSection function to release its ownership. If the critical section object is currently owned by another thread, EnterCriticalSection waits indefinitely for ownership. This differs from the use of a mutex object for mutual exclusion, where the wait functions accept a specified time-out interval.

Once a thread owns a critical section object, it can make additional calls to EnterCriticalSection without blocking its execution. This prevents a thread from deadlocking itself while waiting for a critical section object that it already owns. To release its ownership, 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.

When a critical section object is owned, the only other threads affected are those that are waiting for ownership in a call to EnterCriticalSection. Threads that are not waiting are free to continue their normal execution.


Interlocked Variable Access

The InterlockedIncrement and InterlockedDecrement functions provide a simple mechanism for synchronizing access to a specified 32-bit variable that is shared by multiple threads in the same or in different processes. These functions combine the operations of incrementing or decrementing the variable and checking the resulting value. This is useful in a multitasking operating system, in which the system can interrupt one thread's execution to grant a slice of processor time to another thread. Without such synchronization, one thread could increment a variable but be interrupted by the system before it can check the resulting value of the variable. A second thread could then increment the same variable. When the first thread receives its next timeslice, it will check the value of the variable, which has now been incremented not once but twice. The interlocked variable-access functions protect against this kind of error.

The threads of different processes can use this mechanism if the variable is in shared memory.


Using Named Objects

This example illustrates the use of an object name to let two processes open handles of the same mutex object.

The first process uses the CreateMutex function to create the mutex object. Note that the function succeeds even if there is an existing object with the same name.

/* One process creates the mutex object. */

HANDLE hMutex;

DWORD dwErr;

hMutex = CreateMutex(

    NULL,                  /* no security descriptor */

    FALSE,                 /* mutex not owned        */

    "NameOfMutexObject");  /* object name            */

if (hMutex == NULL)

    printf("CreateMutex error: %d\n", GetLastError() );

else

    if ( GetLastError() == ERROR_ALREADY_EXISTS )

        printf("CreateMutex opened existing mutex\n");

    else

        printf("CreateMutex created new mutex\n");

The second process uses the OpenMutex function to open a handle of the existing mutex. This function fails if a mutex object with the specified name does not exist. The access parameter requests full access to the mutex object, which is necessary for the handle to be used in any of the wait functions.

/* Another process opens a handle of the existing mutex. */

HANDLE hMutex;

hMutex = OpenMutex(

    MUTEX_ALL_ACCESS,      /* request full access    */

    FALSE,                 /* handle not inheritable */

    "NameOfMutexObject");  /* object name            */

if (hMutex == NULL)

    printf("OpenMutex error: %d\n", GetLastError() );

The following example uses the CreateSemaphore function to illustrate a named-object creation operation that fails if the object already exists.

HANDLE CreateNewSemaphore(LPSECURITY_ATTRIBUTES lpsa,

    LONG cInitial, LONG cMax, LPTSTR lpszName) {

HANDLE hSem;

/* Create or open a named semaphore. */

hSem = CreateSemaphore(

    lpsa,         /* security attributes */

    cInitial,     /* initial count       */

    cMax,         /* maximum count       */

    lpszName);    /* semaphore name      */

/* Close handle, and return NULL if existing semaphore opened. */

if (hSem != NULL &&

        GetLastError() == ERROR_ALREADY_EXISTS) {

    CloseHandle(hSem);

    return NULL;

}

/* If new semaphore was created, return the handle. */

return hSem;

}


Waiting for Multiple Objects

This example uses the CreateEvent function to create two event objects. It then uses the WaitForMultipleObjects function to wait for one of them to be signaled.

HANDLE hEvents[2];

DWORD i, dwEvent;

/* Create two event objects. */

for (i = 0; i < 2; i++) {

    hEvents[i] = CreateEvent(

        NULL,   /* no security attributes        */

        FALSE,  /* auto-reset event object       */

        FALSE,  /* initial state is nonsignaled  */

        NULL);  /* unnamed object                */

    if (hEvents[i] == NULL) {

        printf("CreateEvent error: %d\n", GetLastError() );

        ExitProcess(0);

    }

}

/*

 * The creating thread waits for other threads or processes

 * to signal the event objects.

 */

dwEvent = WaitForMultipleObjects(

    2,           /* number of objects in array */

    hEvents,     /* array of objects           */

    FALSE,       /* wait for any               */

    INFINITE);   /* indefinite wait            */

/* Return value indicates which event is signaled. */

switch (dwEvent) {

    /* hEvent[0] was signaled. */

    case WAIT_OBJECT_0 + 0:

        /* Perform tasks required by this event. */

        break;

    /* hEvent[1] was signaled. */

    case WAIT_OBJECT_0 + 1:

        /* Perform tasks required by this event. */

        break;

    /* Return value is invalid. */

    default:

        printf("Wait error: %d\n", GetLastError());

        ExitProcess(0);

}


Using Mutex Objects

You can use a mutex object to protect a shared resource from simultaneous access by multiple threads or processes. Each thread must wait for ownership of the mutex before it can execute the code that accesses the shared resource. For example, if several threads share access to a database, the threads can use a mutex object to permit only one thread at a time to write to the database.

In the following example, a process uses the CreateMutex function to create a named mutex object or open a handle of an existing mutex object.

HANDLE hMutex;

/* Create a mutex with no initial owner. */

hMutex = CreateMutex(

    NULL,                       /* no security attributes */

    FALSE,                      /* initially not owned      */

    "MutexToProtectDatabase");  /* name of mutex          */

if (hMutex == NULL) {

    /* check for error */

}

When a thread of this process writes to the database, as in the next example, it first requests ownership of the mutex. If it gets ownership, the thread writes to the database and then releases its ownership.

The example uses the try-finally structured exception handling syntax to ensure that the thread properly releases the mutex. The finally block of code is executed no matter how the try block terminates (unless the try block includes a call to the TerminateThread function). This prevents the mutex from being abandoned inadvertently.

BOOL FunctionToWriteToDatabase(HANDLE hMutex) {

DWORD dwWaitResult;

/* Request ownership of mutex. */

dwWaitResult = WaitForSingleObject(

        hMutex,   /* handle of mutex           */

        5000L);   /* five-second time-out interval */

switch (dwWaitResult) {

    /* The thread got mutex ownership. */

    case WAIT_OBJECT_0:

        try {

            .

            . /* Write to the database. */

            .

        }

        finally {

            /* Release ownership of the mutex object. */

            if (! ReleaseMutex(hMutex)) {

                /* Deal with error. */

            }

            break;

        }

    /* Cannot get mutex ownership due to time-out. */

    case WAIT_TIMEOUT:

        return FALSE;

    /* Got ownership of the abandoned mutex object. */

    case WAIT_ABANDONED:

        return FALSE;

}

return TRUE;

}


Using Semaphore Objects

In the following example, a process uses a semaphore object to limit the number of windows it creates. First, it uses the CreateSemaphore function to create the semaphore and to specify initial and maximum counts.

HANDLE hSemaphore;

LONG cMax = 10;

LONG cPreviousCount;

/* Create a semaphore with initial and max. counts of 10. */

hSemaphore = CreateSemaphore(

    NULL,   /* no security attributes */

    cMax,   /* initial count          */

    cMax,   /* maximum count          */

    NULL);  /* unnamed semaphore      */

if (hSemaphore == NULL) {

    /* Check for error. */

}

Before any thread of the process creates a new window, it uses the WaitForSingleObject function to determine whether the semaphore's current count permits the creation of additional windows. The wait function's time-out parameter is set to zero, so the function returns immediately if the semaphore is nonsignaled.

DWORD dwWaitResult;

/* Try to enter the semaphore gate. */

dwWaitResult = WaitForSingleObject(

        hSemaphore,   /* handle of semaphore          */

        0L);          /* zero-second time-out interval */

switch (dwWaitResult) {

    /* The semaphore object was signaled. */

    case WAIT_OBJECT_0:

        .

        . /* OK to open another window. */

        .

        break;

    /* Semaphore was nonsignaled, so a time-out occurred. */

    case WAIT_TIMEOUT:

        .

        . /* Cannot open another window. */

        .

        break;

}

When a thread closes a window, it uses the ReleaseSemaphore function to increment the semaphore's count.

/* Increment the count of the semaphore. */

if (! ReleaseSemaphore(

        hSemaphore,  /* handle of semaphore              */

        1,           /* increase count by one            */

        NULL) ) {    /* not interested in previous count */

    /* Deal with the error. */

}


Using Event Objects

The Win32 API uses event objects in a number of situations to notify a waiting thread of the occurrence of an event. For example, overlapped input and output (I/O) operations on files, named pipes, and communications devices use an event object to signal their completion. For more information about the use of event objects in overlapped I/O operations, see Synchronization and Overlapped Input and Output.

In the following example, an application uses event objects to prevent several threads from reading from a shared memory buffer while a master thread is writing to that buffer. First, the master thread uses the CreateEvent function to create a manual-reset event object. The master thread sets the event object to nonsignaled when it is writing to the buffer and then resets the object to signaled when it has finished writing. Then it creates several reader threads and an auto-reset event object for each thread. Each reader thread sets its event object to signaled when it is not reading from the buffer.

#define NUMTHREADS 4

HANDLE hGlobalWriteEvent;

void CreateEventsAndThreads(void) {

HANDLE hReadEvents[NUMTHREADS], hThread;

DWORD i, IDThread;

/*

 * Create a manual-reset event object. The master thread sets

 * this to nonsignaled when it writes to the shared buffer.

 */

hGlobalWriteEvent = CreateEvent(

    NULL,        /* no security attributes    */

    TRUE,        /* manual-reset event        */

    TRUE,        /* initial state is signaled */

    "WriteEvent" /* object name               */

    );

if (hGlobalWriteEvent == NULL) {

    /* error exit */

}

/*

 * Create multiple threads and an auto-reset event object

 * for each thread. Each thread sets its event object to

 * signaled when it is not reading from the shared buffer.

 */

for(i = 1; i <= NUMTHREADS; i++) {

    /* Create the auto-reset event. */

    hReadEvents[i] = CreateEvent(

        NULL,     /* no security attributes    */

        FALSE,    /* auto-reset event          */

        TRUE,     /* initial state is signaled */

        NULL);    /* object not named          */

    if (hReadEvents[i] == NULL) {

        /* error exit */

    }

    hThread = CreateThread(NULL, 0,

            (LPTHREAD_START_ROUTINE) ThreadFunction,

            &hReadEvents[i], /* pass event handle  */

            0, &IDThread);

    if (hThread == NULL) {

        /* error exit */

    }

}

}

Before the master thread writes to the shared buffer, it uses the ResetEvent function to set the state of hGlobalWriteEvent to nonsignaled. This blocks the reader threads from starting a read operation. The master then uses the WaitForMultipleObjects function to wait for all reader threads to finish any current read operations. When WaitForMultipleObjects returns, the master thread can safely write to the buffer. After it has finished, it sets hGlobalWriteEvent and all the reader-thread events to signaled, enabling the reader threads to resume their read operations.

VOID WriteToBuffer(VOID) {

DWORD dwWaitResult, i;

/* Reset hGlobalWriteEvent to nonsignaled, to block readers. */

if (! ResetEvent(hGlobalWriteEvent) ) {

        /* error exit */

}

/* Wait for all reading threads to finish reading. */

dwWaitResult = WaitForMultipleObjects(

        NUMTHREADS,   /* number of handles in array   */

        hReadEvents,  /* array of read-event handles  */

        TRUE,         /* wait until all are signaled  */

        INFINITE);    /* indefinite wait              */

switch (dwWaitResult) {

    /* All read-event objects were signaled. */

    case WAIT_OBJECT_0:

        .

        . /* Write to the shared buffer. */

        .

        break;

    /* An error occurred. */

    default:

        printf("Wait error: %d\n", GetLastError());

        ExitProcess(0);

}

/* Set hGlobalWriteEvent to signaled. */

if (! SetEvent(hGlobalWriteEvent) ) {

        /* error exit */

}

/* Set all read events to signaled. */

for(i = 1; i <= NUMTHREADS; i++)

    if (! SetEvent(hReadEvents[i]) ) {

            /* error exit */

    }

}

Before starting a read operation, each reader thread uses WaitForMultipleObjects to wait for hGlobalWriteEvent and its own read event to be signaled. When WaitForMultipleObjects returns, the reader thread's auto-reset event has been reset to nonsignaled. This blocks the master thread from writing to the buffer until the reader thread uses the SetEvent function to set the event's state back to signaled.

VOID ThreadFunction(LPVOID lpParam) {

DWORD dwWaitResult, i;

HANDLE hEvents[2];

hEvents[0] = (HANDLE) *lpParam;  /* thread's read event */

hEvents[1] = hGlobalWriteEvent;

dwWaitResult = WaitForMultipleObjects(

        2,            /* number of handles in array   */

        hEvents,      /* array of event handles       */

        TRUE,         /* wait till all are signaled   */

        INFINITE);    /* indefinite wait              */

switch (dwWaitResult) {

    /* Both event objects were signaled. */

    case WAIT_OBJECT_0:

        .

        . /* Read from the shared buffer. */

        .

        break;

    /* An error occurred. */

    default:

        printf("Wait error: %d\n", GetLastError());

        ExitThread(0);

}

/* Set the read event to signaled. */

if (! SetEvent(hEvents[0]) ) {

        /* error exit */

}

}


Using Critical Section Objects

The following example shows how a thread initializes, enters, and leaves a critical section. As with the mutex example (see Using Mutex Objects), this example uses the try-finally structured exception handling syntax to ensure that the thread calls the LeaveCriticalSection function to release its ownership of the critical section object.

CRITICAL_SECTION GlobalCriticalSection;

/* Initialize the critical section. */

InitializeCriticalSection(&GlobalCriticalSection);

/* Request ownership of the critical section. */

try {

    EnterCriticalSection(&GlobalCriticalSection);

    #ifdef REF

        .

        . /* Access the shared resource. */

        .

    #endif

}

finally {

    /* Release ownership of the critical section. */

    LeaveCriticalSection(&GlobalCriticalSection);

}


Functions

Following are the functions used in synchronization.

CreateEvent

CreateMutex

CreateSemaphore

DeleteCriticalSection

EnterCriticalSection

GetOverlappedResult

InitializeCriticalSection

InterlockedDecrement

InterlockedIncrement

LeaveCriticalSection

MsgWaitForMultipleObjects

OpenEvent

OpenMutex

OpenSemaphore

PulseEvent

ReleaseMutex

ReleaseSemaphore

ResetEvent

SetEvent

WaitForMultipleObjects

WaitForMultipleObjectsEx

WaitForSingleObject

WaitForSingleObjectEx


Files Overview

About Files

In Microsoft® Windows™, a file is a named, ordered collection of information, such as a program, a set of data used by a program, or a user-created document. Files are stored on storage media, such as disks or tapes, and can be organized into groups called directories. The Windows file input/output functions enable applications to create, open, modify, and delete files and directories. They also enable applications to obtain system information, such as what disk drives are present.

The following topics discuss Windows Files :

Terms

System Organization

Creating and Opening Files

Closing and Deleting Files

Copying and Moving Files

Reading From and Writing to a File

Searching for Files

Creating Temporary Files

Getting Information About Files

Directory Operations

Getting System Information

Using Files

Example: Creating and Opening Files

Example: Reading, Writing, and Locking Files

Example: Creating and Using a Temporary File

Example: Searching for Files and Changing File Attributes

Example: Monitoring Changes in a Directory or Directory Tree

Example: Retrieving a File Pointer

Functions


System Organization

A volume is a storage device, such as a fixed disk or floppy disk, formatted to store directories and files. Each volume has a root directory. Directories and files on the volume are organized in a tree structure that starts at the root directory. Each directory entry identifies the name, attributes, location, and size of a file or subdirectory.

A large volume can be divided into more than one logical volume, also called a partition. Each partition appears to the user, and to the operating system, as a separate volume.

A file system is operating system software that manages the low-level organization of files on a volume. Windows supports the following file systems:

file allocation table (FAT)

high-performance file system (HPFS)

New Technology file system (NTFS)

The type of file system defines the filename conventions on a volume and may also provide specific file system features, such as security, recoverability, and high input and output (I/O) performance. Each volume can use a different file system.

The first time a file function accesses a volume and whenever a volume is placed in a floppy-disk drive, Windows examines the volume to determine the appropriate file system. Thereafter, Windows manages all I/O to that volume through the device driver supporting the file system. If an error occurs, the driver returns it to Windows, which then passes it back to the application.

The Windows file functions enable applications to access files regardless of the underlying file system. However, their functionality may vary depending on the file system and/or operating system in use. For example, the CreateFile function includes a security parameter that provides no security benefits for an application written for Windows running with current versions of MS-DOS.

The Windows file functions that create, open, and delete files and directories identify them by their names. These functions store or search for the file or directory in the current directory on the current disk drive unless the name explicitly specifies a path to a different directory, disk drive, or both.

Filename Conventions

Although each file system can have specific rules about the formation of individual components in a directory or filename, all file systems follow the same general conventions for combining components. For example, the FAT file system requires file and directory names to have the 8.3-character filename format; the HPFS file system allows names to be up to 254 characters; and the NTFS file system allows names to be up to 255 characters. All three file systems use the backslash (\) character to separate directory names and the filename when forming a path.

General rules for applications creating names for directories and files or processing names supplied by the user include the following:

Use any character in the current code page for a name, but do not use a path separator, a character in the range 0 through 31, or any character explicitly disallowed by the file system. A name can contain characters in the extended character set (128-255).

Use the backslash (\), the forward slash (/), or both to separate components in a path. No other character is acceptable as a path separator.

Use a period (.) as a directory component in a path to represent the current directory.

Use two consecutive periods (..) as a directory component in a path to represent the parent of the current directory.

Use a period (.) to separate components in a directory name or filename.

Do not use the following characters in directory names or filenames, because they are reserved for Windows:

< > : " / \ |

Do not use reserved words, such as aux, con, and prn, as filenames or directory names.

Process a path as a null-terminated string. The maximum length for a path is given by MAX_PATH.

Do not assume case sensitivity. Consider names such as OSCAR, Oscar, and oscar to be the same.

By following the rules listed in this section, an application can create valid names for files and directories regardless of the file system in use.


Creating and Opening Files

Creating and Opening Files

The CreateFile function can create a new file or open an existing file. When an application uses this function, it must specify whether it will read from the file, write to the file, or both. The application must also specify what action to take whether or not the file exists. For example, an application can specify that CreateFile always be used to create the file. As a result, the function creates the file if it does not exist and overwrites the file if it does exist.

CreateFile also enables an application to specify whether it wants to share the file for reading, writing, both, or neither. A file that is not shared cannot be opened more than once by the first application nor by another application until the first application has closed.

Windows assigns a unique identifier, called a file handle, to each file that is opened or created. An application can use the file handle in functions that read from, write to, and describe the file. It is valid until the file is closed. When an application starts, it inherits all open file handles from the process that started it, if the handles are inheritable.

An application should check the return value of CreateFile before attempting to use the handle to access the file. If an error occurs, the application can use the GetLastError function to get extended error information.


Closing and Deleting Files

Closing and Deleting Files

To use operating system resources efficiently, an application should close files when they are no longer needed by using the CloseHandle function. If a file is open when an application terminates, Windows closes it automatically.

The DeleteFile function can be used to delete a file. The file must, however, be closed before any attempt to delete it.


Copying and Moving Files

Copying and Moving Files

Before a file can be copied, it must be closed or opened only for reading. No thread can have the file opened for writing. To copy an existing file to a new one, use the CopyFile function. Applications can specify whether CopyFile fails if the new file already exists.

A file must also be closed before an application can move it. The MoveFile function copies an existing file to a new location and deletes the original. Applications frequently use this function to rename files.


Reading From and Writing to a File

Reading from and Writing to a File

Every open file has a file pointer that specifies the next byte to be read or the location to receive the next byte written. When a file is opened for the first time, Windows places the file pointer at the beginning of the file. As each byte is read or written, Windows advances the file pointer. An application can also move the file pointer by using the SetFilePointer function.

An application reads from and writes to a file by using the ReadFile and WriteFile functions. These functions require a handle of a file to be opened for reading and writing, respectively. ReadFile and WriteFile read and write a specified number of bytes at the location indicated by the file pointer. The data is read and written exactly as given; the functions do not format the data.

When the file pointer reaches the end of a file and the application attempts to read from the file, no error occurs, but no bytes are read. Therefore, reading zero bytes without an error means the program has reached the end of the file.

An application can truncate or extend a file by using the SetEndOfFile function. This function sets end-of-file to the current position of the file pointer. A WriteFile of zero bytes does nothing.

When an application writes to a file, Windows usually collects the data being written in an internal buffer and writes the data to the disk on a regular basis.

An application can force the operating system to write the contents of the buffer to the disk by using the FlushFileBuffers function. Alternatively, an application can specify that write operations are to bypass the internal buffer and write directly to the disk by setting a flag when the file is created or opened by using the CreateFile function.

If there is data in the internal buffer when the file is closed, Windows does not automatically write the contents of the buffer to the disk before closing the file. If the application does not force the operating system to write the buffer to disk before closing the file, the caching algorithm determines when the buffer is written.

Locking and Unlocking Files

Although Windows allows more than one application to open a file and write to it, applications must not write over each other's work. An application can prevent this problem by temporarily locking a region in a file. The LockFile function locks a specified range of bytes in a file. The range may extend beyond the current end of the file. Locking part of a file prevents all other processes from reading or writing anywhere in the specified area. Attempts to read from or write to a region locked by another process always fail. The application unlocks the region by using the UnlockFile function. An application should unlock all locked areas before closing a file.

Synchronizing Input and Output

Asynchronous input and output is a type of I/O in which some 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 be completed at a later time. Asynchronous I/O is also called overlapped I/O.

The ReadFile and WriteFile functions enable an application to specify an OVERLAPPED structure that indicates where to position the file pointer before the read or write operation. The handle of the file being read from or written to must have been opened with the FILE_FLAG_OVERLAPPED flag. The OVERLAPPED structure can also contain an event handle on which the WaitForSingleObject or WaitForMultipleObjects function can wait.

An application can also wait on the file handle to synchronize the completion of an I/O operation, but this requires extreme caution. Each time an I/O operation is started, the operating system sets the file handle to the nonsignaled state. Each time an I/O operation is completed, the operating system sets the file handle to the signaled state. Therefore, if an application starts two I/O operations and waits on the file handle, there is no way to determine which operation is finished when the handle is set to the signaled state. If an application must perform multiple asynchronous I/O operations on a single file, make it wait on the event handle in the OVERLAPPED structure for each I/O operation, rather than on the file handle.

The ReadFileEx and WriteFileEx functions enable an application to specify a routine to execute when the asynchronous I/O request is completed.


Searching for Files

Searching for Files

An application can search the current directory for all filenames that match a given pattern by using the FindFirstFile, FindNextFile, and FindClose functions. The pattern must be a valid filename and can include wildcard characters.

FindFirstFile creates a handle that FindNextFile uses to search for other files with the same pattern. Both functions also return information about the file that was found in a WIN32_FIND_DATA structure. This information includes the filename, size, attributes, and time. The FindClose function destroys the handle created by FindFirstFile. For more information about the WIN32_FIND_DATA structure, see the <Microsoft Win32 Programmer's Reference, Volume 5>.

An application can search for a single file on a specific path by using the SearchPath function.


Creating Temporary Files

Creating Temporary Files

Applications can create temporary filenames with the GetTempFileName function. The GetTempPath function retrieves the path to the directory where temporary files are to be created.


Getting Information About Files

Getting Information About Files

Nine characteristics called attributes may be associated with a file, as described in the following table.

Attribute	Meaning

FILE_ATTRIBUTE_ARCHIVE	The file is an archive file. Applications use this flag to mark files for backup or removal.

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 attribute is valid only if used alone.

FILE_ATTRIBUTE_READONLY	The file is read only. Applications can read from 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 a temporary file. Applications can 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.

FILE_ATTRIBUTE_ATOMIC_WRITE	Reserved for future use. Do not specify.

FILE_ATTRIBUTE_XACTION_WRITE	Reserved for future use. Do not specify.

An application can retrieve and set a file's attributes by using the GetFileAttributes and SetFileAttributes functions. Applications cannot, however, use SetFileAttributes to set the directory attribute.

The GetFileType function returns the type of a file: disk, character (such as a console), pipe, or unknown. The GetFileSize function returns the size of a file. Applications can retrieve the full path of a file by using the GetFullPathName function.

Applications can retrieve and set the date and time a file was created, last modified, or last accessed by using the GetFileTime and SetFileTime functions.


Directory Operations

Directory Operations

When an application creates a new file, the operating system adds it to the specified directory. Each directory can have any number of files, up to the physical limit of the disk. An application can create new directories and delete existing directories by using the CreateDirectory and RemoveDirectory functions. An application cannot delete a directory unless it is empty.

The directory at the end of the active path is called the current directory. This is the directory in which the active application started, unless explicitly changed. An application can determine which directory is current by using the GetCurrentDirectory function. An application can change the current directory by using the SetCurrentDirectory function.

An application can monitor the contents of a directory and its subdirectories by using the FindFirstChangeNotification, FindNextChangeNotification, and FindCloseChangeNotification functions. Waiting for a change notification is similar to having a read operation pending against a directory and, if necessary, its subdirectories. When something changes within the directory being watched, the read operation is completed. For example, an application can use these functions to update a directory listing whenever a filename within the monitored directory changes.

An application can specify a set of conditions that trigger a change notification by using the FindFirstChangeNotification function. The conditions include changes to filenames, directory names, attributes, file size, time of last write, and security. This function also returns a handle that can be waited on by using the WaitForSingleObject or WaitForMultipleObjects function. If the wait condition is satisfied, FindNextChangeNotification can be used to provide a notification handle to wait on subsequent changes.

The FindCloseChangeNotification function closes the notification handle.


Getting System Information

Getting System Information

Windows provides several functions that applications can use to obtain information about the file system, operating system, and hardware.

The GetVolumeInformation function retrieves information about the file system on a given volume. This information includes the volume name, volume serial number, file system name, file system flags, maximum length of a filename, and so on.

The GetSystemDirectory and GetWindowsDirectory functions retrieve the paths to the Windows system directory and the Windows directory, respectively.

The GetDiskFreeSpace function retrieves organizational information about a disk, including the number of bytes per sector, the number of sectors per cluster, the number of free clusters, and the total number of clusters.

The GetDriveType function indicates whether the disk referenced by the specified disk drive is removable, fixed, CD-ROM, RAM, or a network drive.

The GetLogicalDrives function identifies the drives currently present on the operating system. The GetLogicalDriveStrings function retrieves a null-terminated string for each drive present on the operating system. Use these strings whenever a root directory is required.


Using Files

The Windows file functions enable applications to access files regardless of the underlying file system. However, their functionality may vary depending on the operating system in use. If you have questions about a specific function, consult the reference information on that function.

For functions that manipulate files, the filenames may be relative to the current directory. A filename is relative to the current directory if it does not begin with a disk designator or directory name separator, such as a backslash (\). If the filename begins with a disk designator, it is a fully qualified path.

The examples in this section illustrate how to perform the following tasks:

Create, open, close, and delete a file

Read from and write to a file

Lock and unlock a file

Set the file pointer

Get a unique temporary filename

Move a file

Search for a file

Create a directory

Copy a file

Get and set a file's attributes

Monitor changes in a directory or directory tree


Example: Creating and Opening Files

You can use the CreateFile function to create a new file or open an existing file. You must specify the filename, preferred access, share mode, creation instructions, and attributes.

The following example returns a handle of the current console input buffer.

HANDLE hReadWriteInput;

hReadWriteInput = CreateFile("CONIN$",

    GENERIC_READ | GENERIC_WRITE,

    FILE_SHARE_READ | FILE_SHARE_WRITE, /* share with cmd. */

    NULL,

    OPEN_EXISTING,              /* open already created console */

    0,                          /* normal file open             */

    NULL

    );

Character-Mode Support.

In the following example, CreateFile opens an existing file for reading.

HANDLE hFile;

hFile = CreateFile("MYFILE.TXT",           /* open MYFILE.TXT    */

                GENERIC_READ,              /* open for reading   */

                FILE_SHARE_READ,           /* share for reading  */

                (LPSECURITY_ATTRIBUTES) NULL, /* no security     */

                OPEN_EXISTING,             /* existing file only */

                FILE_ATTRIBUTE_NORMAL,     /* normal file        */

                (HANDLE) NULL);            /* no attr. template  */

if (hFile == INVALID_HANDLE_VALUE) {

        ErrorHandler("Could not open file.");   /* process error */

}

In this example, CreateFile succeeds only if a file named MYFILE.TXT already exists in the current directory. Your application should check the return value of CreateFile before attempting to use the handle to access the file. If an error occurs, use the GetLastError function to obtain extended error information and respond accordingly.

You must close a file before the file can be deleted. The following lines close and delete the file MYFILE.TXT.

CloseHandle(hFile);

DeleteFile("MYFILE.TXT");

In the following example, CreateFile creates a new file and opens it for writing.

HANDLE hFile;

hFile = CreateFile("MYFILE.TXT",           /* create MYFILE.TXT  */

             GENERIC_WRITE,                /* open for writing   */

             0,                            /* do not share       */

             (LPSECURITY_ATTRIBUTES) NULL, /* no security        */

             CREATE_ALWAYS,                /* overwrite existing */

             FILE_ATTRIBUTE_NORMAL |       /* normal file        */

             FILE_FLAG_OVERLAPPED,         /* asynchronous I/O   */

             (HANDLE) NULL);               /* no attr. template  */

if (hFile == INVALID_HANDLE_VALUE) {

    ErrorHandler("Could not open file.");  /* process error      */

}

In addition to the standard attributes (read only, hidden, system, and so on), you can also specify security attributes by including a pointer to a SECURITY_ATTRIBUTES structure as the fourth parameter. However, the underlying operating system must support security for these attributes for them to have any effect.


Example: Reading, Writing, and Locking Files

The ReadFile function requires a file handle that is open for reading, or reading and writing. ReadFile copies a specified number of bytes, up to the end of the file, to a specified buffer. It returns the actual number of bytes read in a variable specified by its fourth parameter.

The WriteFile function requires a file handle that is open for writing, or writing and reading. WriteFile copies a specified number of bytes, up to the end of the buffer, to a specified file. It returns the actual number of bytes written in a variable specified by its fourth parameter.

The following example illustrates a possible flow for using callback completion asynchronous I/O.

Completion Routine:

VOID IoCompletionRoutine(DWORD dwErrorCode,

        DWORD dwNumberOfBytesTransfered, LPOVERLAPPED lpOverlapped)

{

    /* If an I/O error occurred, display the error and then exit. */

    if (dwErrorCode) {

        printf("FATAL I/O Error %ld I/O Context %lx.%lx\n",

            dwErrorCode, lpOverlapped, lpOverlapped->hEvent);

        ExitProcess(dwErrorCode);

    }

    LocalFree(lpOverlapped);

}

Main Thread:

VOID IoWorkerThread(VOID)

{

    HANDLE HandleVector[2];

    DWORD CompletionStatus;

    PIOREQUEST IoRequestPacket;

    LPOVERLAPPED Overlapped;

    BOOL IoOperationStatus;

    HandleVector[0] = IoWorkerListLock;

    HandleVector[1] = IoWorkerListSemaphore;

    for(;;) {

        /* Do an alertable wait on the handle vector. Both objects */

        /* being signaled at the same time means there is an       */

        /* I/O request in the queue, and the caller has exclusive  */

        /* access to the queue.                                    */

        CompletionStatus = WaitForMultipleObjectsEx(2, HandleVector,

                TRUE, INFINITE, TRUE);

        /* If the wait failed, error out. */

        if (CompletionStatus == 0xFFFFFFFF) {

            printf("FATAL WAIT ERROR %ld\n", GetLastError());

            ExitProcess(1);

        }

        /* If an I/O completion occurred, wait for another         */

        /* I/O request or I/O completion.                          */

        if (CompletionStatus != WAIT_IO_COMPLETION) {

        /* Wait was satisfied. We now have exclusive ownership of  */

        /* the I/O request queue, and there is something in the    */

        /* queue. To insert something in the queue, the            */

        /* inserter gets the list lock (mutex), inserts an entry,  */

        /* signals the list semaphore, and finally releases the    */

        /* list lock.                                              */

            IoRequestPacket = RemoveHeadList(&IoRequestList);

            ReleaseMutex(IoWorkerListLock);

            /* Allocate an overlapped structure. */

            Overlapped = LocalAlloc(LMEM_ZEROINIT,

                    sizeof(OVERLAPPED));

            if (!Overlapped) {

                printf("FATAL allocation error\n");

                ExitProcess(1);

            }

            Overlapped->Offset = IoRequestPacket->Offset;

            Overlapped->OffsetHigh = IoRequestPacket->OffsetHigh;

            Overlapped->hEvent =

                    IoRequestPacket->dwAdditionalIoContext;

            if (IoRequestPacket->bRead) {

                IoOperationStatus =

                            ReadFileEx(IoRequestPacket->hFile,

                    IoRequestPacket->lpBuffer,

                    IoRequestPacket->dwTransferCount,

                    Overlapped, IoCompletionRoutine);

            }

            else {

                IoOperationStatus =

                    WriteFileEx(IoRequestPacket->hFile,

                        IoRequestPacket->lpBuffer,

                        IoRequestPacket->dwTransferCount,

                        Overlapped,

                        IoCompletionRoutine);

            }

            /* Test to see if I/O was queued successfully. */

            if (!IoOperationStatus) {

                printf("FATAL I/O Error %ld I/O Context %lx.%lx\n",

                    GetLastError(), Overlapped, Overlapped->hEvent);

                ExitProcess(1);

            }

            /* The I/O queued successfully. Go back into the */

            /* alertable wait for I/O completion or for      */

            /* more I/O requests.                            */

        }

    }

}

The SetFilePointer function moves the file pointer a specified number of bytes, relative to the beginning or end of the file, or the file pointer's current position. If you specify a positive number of bytes, SetFilePointer moves the file pointer toward the beginning of the file; a negative value moves the pointer toward the end of the file.

The following example appends one file to the end of another file. The application opens two files by using CreateFile: ONE.TXT is opened for reading, and TWO.TXT is opened for writing. Then, the application appends the contents of ONE.TXT to the end of TWO.TXT by reading and writing 4K blocks by using ReadFile and WriteFile. Before writing to the second file, the application sets the second file's pointer to the end of the file by using SetFilePointer and locks the area to be written by using LockFile. This prevents another process from accessing the area while the write is in progress. After each write operation, UnlockFile unlocks the locked area.

HANDLE hFile;

HANDLE hAppend;

DWORD  dwBytesRead, dwBytesWritten, dwPos;

char   buff[4096];

/* Open the existing file. */

hFile = CreateFile("ONE.TXT",     /* open ONE.TXT       */

    GENERIC_READ,                 /* open for reading   */

    0,                            /* do not share       */

    (LPSECURITY_ATTRIBUTES) NULL, /* no security        */

    OPEN_EXISTING,                /* existing file only */

    FILE_ATTRIBUTE_NORMAL,        /* normal file        */

    (HANDLE) NULL);               /* no attr. template  */

if (hFile == INVALID_HANDLE_VALUE) {

    ErrorHandler("Could not open ONE.");  /* process error */

}

/*

 * Open the existing file or, if the file doesn't exist,

 * create new file.

 */

hAppend = CreateFile("TWO.TXT",   /* open TWO.TXT       */

    GENERIC_WRITE,                /* open for writing   */

    0,                            /* do not share       */

    (LPSECURITY_ATTRIBUTES) NULL, /* no security        */

    OPEN_ALWAYS,                  /* open or create     */

    FILE_ATTRIBUTE_NORMAL,        /* normal file        */

    (HANDLE) NULL);               /* no attr. template  */

if (hAppend == INVALID_HANDLE_VALUE) {

    ErrorHandler("Could not open TWO.");    /* process error */

}

/*

 * Append the first file to the end of the second file.

 * Lock the second file to prevent another process from

 * accessing it while writing to it. Unlock the

 * file when writing is finished.

 */

do {

  if (ReadFile(hFile, (LPSTR) buff, 4096, &dwBytesRead, NULL)) {

      dwPos = SetFilePointer(hAppend, 0, (LPLONG) NULL, FILE_END);

      LockFile(hAppend, dwPos, 0, dwPos + dwBytesRead, 0);

      WriteFile(hAppend, (LPSTR) buff, dwBytesRead,

          &dwBytesWritten, NULL);

      UnlockFile(hAppend, dwPos, 0, dwPos + dwBytesRead, 0);

  }

} while (dwBytesRead == 4096);

/* Close both files. */

CloseHandle(hFile);

CloseHandle(hAppend);


Example: Creating and Using a Temporary File

The following example copies one file to another. The second file is an uppercase version of the first file.

The application opens the file ORIGINAL.TXT by using CreateFile. The application then obtains a temporary filename with the GetTempFileName function and uses CreateFile to create the temporary file. The application reads 4K blocks into a buffer, converts the buffer contents to uppercase, and writes the converted buffer to the temporary file. When all of ORIGINAL.TXT has been written to the temporary file, the application closes both files and renames the temporary file to ALLCAPS.TXT by using the MoveFile function.

HANDLE hFile;

HANDLE hTempFile;

DWORD  dwBytesRead, dwBytesWritten, dwPos;

char szTempName[MAX_PATH];

char buffer[4096];

/* Open the existing file. */

hFile = CreateFile("ORIGINAL.TXT",        /* filename   */

    GENERIC_READ,                 /* open for reading   */

    0,                            /* do not share       */

    (LPSECURITY_ATTRIBUTES) NULL, /* no security        */

    OPEN_EXISTING,                /* existing file only */

    FILE_ATTRIBUTE_NORMAL,        /* normal file        */

    (HANDLE) NULL);               /* no attr. template  */

if (hFile == INVALID_HANDLE_VALUE) {

    ErrorHandler("Could not open file."); /* process err. on fail*/

}

/* Create a temporary file. */

GetTempFileName("\\TEMP", /* dir. for temp. files            */

    "NEW",                /* temp. filename prefix           */

    0,                    /* create unique name w/ sys. time */

    (LPTSTR) szTempName); /* buffer for name                 */

hTempFile = CreateFile((LPTSTR) szTempName,  /* filename     */

    GENERIC_READ | GENERIC_WRITE, /* open for read-write     */

    0,                            /* do not share            */

    (LPSECURITY_ATTRIBUTES) NULL, /* no security             */

    CREATE_ALWAYS,                /* overwrite existing      */

    FILE_ATTRIBUTE_NORMAL,        /* normal file             */

    (HANDLE) NULL);               /* no attr. template       */

if (hTempFile == INVALID_HANDLE_VALUE) {

    ErrorHandler("Could not create temporary file.");

}

/*

 * Read 4K blocks to the buffer.

 * Change all characters in the buffer to uppercase.

 * Write the buffer to the temporary file.

 */

do {

    if (ReadFile(hFile, (LPSTR) buffer, 4096,

        &dwBytesRead, NULL)) {

        CharUpperBuff((LPTSTR) buffer, dwBytesRead);

        WriteFile(hTempFile, (LPSTR) buffer, dwBytesRead,

            &dwBytesWritten, NULL);

    }

} while (dwBytesRead == 4096);

/* Close both files. */

CloseHandle(hFile);

CloseHandle(hTempFile);

/* Move the temporary file to the new text file. */

if (!MoveFile(szTempName, "ALLCAPS.TXT")) {

    ErrorHandler("Could not move temp. file.");

}


Example: Searching for Files and Changing File Attributes

The following example copies all text files in the current directory to a new directory of read-only files named \TEXTRO. Files in the new directory are changed to read only, if necessary.

The application uses the GetCurrentDirectory function to retrieve the current directory path. This is also used to return to the current directory after changing to the \TEXTRO directory.

The application then creates the \TEXTRO directory by using the CreateDirectory function.

The application searches the current directory for all .TXT files by using the FindFirstFile and FindNextFile functions. Each .TXT file is copied to the \TEXTRO directory. After a file is copied, the GetFileAttributes function determines whether the file is read only. If the file is not read only, the application changes directories to \TEXTRO and converts the copied file to read only by using the SetFileAttributes function.

After all .TXT files in the current directory have been copied, the application closes the search handle by using the FindClose function.

WIN32_FIND_DATA FileData;

HANDLE hSearch;

DWORD dwAttrs;

char szDirPath[] = "c:\\TEXTRO\\";

char szNewPath[MAX_PATH];

char szHome[MAX_PATH];

BOOL fFinished = FALSE;

/* Create a new directory. */

if (!CreateDirectory(szDirPath, NULL)) {

    ErrorHandler("Couldn't create new directory.");

}

/* Start searching for .TXT files in the current directory. */

hSearch = FindFirstFile("*.txt", &FileData);

if (hSearch == INVALID_HANDLE_VALUE) {

    ErrorHandler("No .TXT files found.");

}

/*

 * Copy each .TXT file to the new directory

 * and change to read only, if not already.

 */

while (!fFinished) {

    lstrcpy(szNewPath, szDirPath);

    lstrcat(szNewPath, FileData.cFileName);

    if (CopyFile(FileData.cFileName, szNewPath, FALSE)) {

        dwAttrs = GetFileAttributes(FileData.cFileName);

        if (!(dwAttrs & FILE_ATTRIBUTE_READONLY)) {

                SetFileAttributes(szNewPath,

                    dwAttrs | FILE_ATTRIBUTE_READONLY);

            }

    }

    else {

        ErrorHandler("Couldn't copy file.");

    }

    if (!FindNextFile(hSearch, &FileData))

        if (GetLastError() == ERROR_NO_MORE_FILES) {

            MessageBox(hwnd, "No more .TXT files.",

                "Search completed.", MB_OK);

            fFinished = TRUE;

        }

        else {

            ErrorHandler("Couldn't find next file.");

        }

}

/* Close the search handle. */

if (!FindClose(hSearch)) {

    ErrorHandler("Couldn't close search handle.");

}


Example: Monitoring Changes in a Directory or Directory Tree

The following example monitors the directory tree starting at C:\ for directory name changes. It also monitors the C:\WINDOWS directory for filename changes.

The example uses the FindFirstChangeNotification function to create two notification handles and the WaitForMultipleObjects function to wait on the handles. Whenever a directory is created or deleted in the tree starting at C:\, the example updates the entire directory tree. Whenever a file is created or deleted in the C:\WINDOWS directory, the example refreshes the WINDOWS directory. The FindNextChangeNotification function restarts the change notification each time the example processes a change.

DWORD dwWaitStatus;

HANDLE dwChangeHandles[2];

/*

 * Watch the C:\WINDOWS directory for file creation and

 * deletion.

 */

dwChangeHandles[0] = FindFirstChangeNotification(

    "C:\\WINDOWS",                 /* directory to watch       */

    FALSE,                         /* do not watch the subtree */

    FILE_NOTIFY_CHANGE_FILE_NAME); /* watch filename changes   */

if (dwChangeHandles[0] == INVALID_HANDLE_VALUE)

    ExitProcess(GetLastError());

/*

 * Watch the C:\ subtree for directory creation and

 * deletion.

 */

dwChangeHandles[1] = FindFirstChangeNotification(

    "C:\\",                        /* directory to watch      */

    TRUE,                          /* watch the subtree       */

    FILE_NOTIFY_CHANGE_DIR_NAME);  /* watch dir. name changes */

if (dwChangeHandles[1] == INVALID_HANDLE_VALUE)

    ExitProcess(GetLastError());

/*

 * Change notification is set. Now wait on both notification

 * handles and refresh accordingly.

 */

while (TRUE) {

  /* Wait for notification. */

  dwWaitStatus = WaitForMultipleObjects(2, dwChangeHandles,

      FALSE, INFINITE);

  switch (dwWaitStatus) {

    case WAIT_OBJECT_0:

      /*

       * A file was created or deleted in C:\WINDOWS.

       * Refresh this directory and restart the

       * change notification. RefreshDirectory is an

       * application-defined function.

       */

      RefreshDirectory("C:\\WINDOWS")

      if (FindNextChangeNotification(dwChangeHandles[0]) == FALSE)

          ExitProcess(GetLastError());

      break;

    case WAIT_OBJECT_0 + 1:

      /*

       * A directory was created or deleted in C:\.

       * Refresh the directory tree and restart the

       * change notification. RefreshTree is an

       * application-defined function.

       */

      RefreshTree("C:\\");

      if (FindNextChangeNotification(dwChangeHandles[1]) == FALSE)

          ExitProcess(GetLastError());

      break;

       default:

            ExitProcess(GetLastError());

  }

}


Example: Retrieving a File Pointer

The following example retrieves the current position of the file pointer in the file specified by the hFile value.

HANDLE hFile;

DWORD dwCurrentFilePosition;

dwCurrentFilePosition = SetFilePointer(

    hFile, /* must have GENERIC_READ and/or GENERIC_WRITE    */

    0,     /* do not move pointer                            */

    NULL,  /* hFile is not large enough to need this pointer */

    FILE_CURRENT);  /* provides offset from current position */


Functions

Following are the functions used with files.

CloseHandle

CopyFile

CreateDirectory

CreateFile

DefineDosDevice

DeleteFile

FileIOCompletionRoutine

FindClose

FindCloseChangeNotification

FindFirstChangeNotification

FindFirstFile

FindNextChangeNotification

FindNextFile

FlushFileBuffers

GetCurrentDirectory

GetDiskFreeSpace

GetDriveType

GetFileAttributes

GetFileInformationByHandle

GetFileSize

GetFileType

GetFullPathName

GetLogicalDrives

GetLogicalDriveStrings

GetTempFileName

GetTempPath

GetVolumeInformation

_hread

_hwrite

_lclose

_lcreat

_llseek

LockFile

LockFileEx

_lopen

_lread

_lwrite

MoveFile

MoveFileEx

OpenFile

QueryDosDevice

ReadFile

ReadFileEx

RemoveDirectory

SearchPath

SetCurrentDirectory

SetEndOfFile

SetFileAttributes

SetFilePointer

SetHandleCount

SetVolumeLabel

UnlockFile

UnlockFileEx

WriteFile

WriteFileEx


File Systems Overview

The following topics discuss the Windows NT file systems:

About File Systems for Microsoft Windows NT

The New Technology File System

The FAT File System

The High-Performance File System


About File Systems for Microsoft Windows NT

Windows® NT™ supports three file systems: New Technology file system (NTFS), file allocation table (FAT) file system, and high-performance file system (HPFS).

A file system defines how information is organized on a volume. This includes mandating the filename conventions on a volume and providing specific features of a file system, such as security, recoverability, and high input and output (I/O) performance. Each volume can use a different file system. All three file systems in Windows NT use one or more tables that specify the location and size of the data files on the volume, as well as other information specific to the file system.

With Windows NT, you can install a file system by specifying the desired file-system device drivers and dynamic-link libraries during setup. Device drivers access volumes; the driver's .INF file describes the driver to the setup procedure. Dynamic-link libraries control the format of information on a volume and manage the flow of data to and from the volume.

The FAT file system is the default file system for Windows NT; it does not need to be installed. HPFS and NTFS are installable file systems; their software can be installed when the operating system starts.

Although Windows NT may be booted from all three file systems, FAT and NTFS are strongly recommended. Note that on a MIPS®-based ARC-compliant machine, the system partition (that is, the one that contains the program OSLOADER.EXE) must be a FAT file system. The Windows NT system root may be on FAT or NTFS.


The New Technology File System
The New Technology File System (NTFS)

The New Technology file system (NTFS) organizes data on fixed disks. This file system supports object-oriented applications by treating all files as objects with user- and system-defined attributes. NTFS provides all the capabilities of the FAT and HPFS file systems without many of their limitations. Accessing files under NTFS is often faster than accessing similar files under the FAT or HPFS file systems.

NTFS is a fully recoverable file system. It is designed to restore consistency to a disk after a CPU failure, system crash, or I/O error. NTFS allows the operating system to recover without your having to use the autochk or chkdsk utilities. However, NTFS provides these utilities in case recovery fails or corruption occurs outside the control of the file system. NTFS also includes features not present in HPFS or FAT, such as security, Unicode filenames, automatic creation of MS-DOS® aliases, multiple data streams, and unique functionality specific to the POSIX subsystem.

NTFS follows the filename conventions described in the HPFS section, but it also supports Unicode filenames.

NTFS cannot manipulate a file's extended attributes if the file was created on HPFS.


The FAT File System

The File Allocation Table File System

The FAT file system organizes data on fixed disks and floppy disks. The distinguishing feature of the FAT file system is its filename convention. The filename convention consists of a filename (up to eight characters), a separating period (.), and a filename extension (up to three characters).

The main advantage of FAT volumes is that they are accessible by MS-DOS, Microsoft® Windows™, and OS/2® systems. FAT is also the only file system currently supported on floppy disks and other removable media.

Valid Windows NT FAT filenames have the following form:

[[drive:]][[directory\]]filename[[.extension]]

The drive parameter must name an existing drive and can be any letter from A through Z. The drive letter must be followed by a colon (:).

The directory parameter specifies the directory that contains the file's directory entry. This value must be followed by a backslash (\) to separate it from the filename. If the specified directory is not in the current directory, directory must include the names of all directories in the file's path, separated by backslashes. The root directory is specified by using a backslash at the beginning of the name. For example, if the directory ABCD is in the directory SAMPLE and SAMPLE is in the root directory, the correct directory specification is \SAMPLE\ABCD. A directory name consists of any combination of up to eight letters, digits, or the following special characters:

$ % ' - _ @ { } ~ ` ! # ( )

A directory name can also have an extension that is any combination of up to three letters, digits, or special characters, preceded by a period (.).

The filename and extension parameters specify the file. Filename can be any combination of up to eight letters, digits, or the special characters previously listed; extension can be any combination of up to three letters, digits, or special characters, all preceded by a period. Filename can also include embedded (preceded and followed by one or more letters, digits, or special characters just noted) spaces. For example, the string "disk 1" is a legal value for filename.

FAT volumes do not distinguish between uppercase and lowercase letters.


The High-Performance File System

HPFS organizes data on fixed disks. Filenames under HPFS can be any practical length (up to 254 characters) and can contain characters that are not valid for the FAT file system, such as spaces and periods. In many cases, accessing files under HPFS is faster than accessing similar files under the FAT file system. Although HPFS is provided for data exchange with OS/2, in Windows NT, HPFS offers no performance advantages over FAT.

Blank spaces can be used anywhere in an HPFS filename or directory name, but blank spaces and periods at the end of a filename are ignored. There is no requirement that HPFS filenames have extensions; however, many applications still create and use them.

The following special characters can also be used in HPFS filenames:

, + = [ ] ; _

An HPFS filename can be all uppercase, all lowercase, or mixed case. The case is preserved for directory listings but is ignored in file searches and all other system operations. Therefore, in a given directory, there cannot be more than one file with the same name when the only difference is case.


File Mapping Overview

About File Mapping

File mapping is the copying of a file's contents to a process's virtual address space. The copy of the file's contents is called the file view, and the internal structure the operating system uses to maintain the copy is called the file-mapping object.

Another process can create an identical file view in its own virtual address space by using the first process's file-mapping object to create the view. This enables the processes to share data. Any process that has the name or a handle of a file-mapping object can create a file view.

Microsoft® Windows NT™ file-mapping functions create file-mapping objects and file views necessary for this method of data sharing.

Terms

Sharing a File

Sharing a Memory Block

Closing a File View

Using File Mapping

Functions


Sharing a File

If two (or more) processes need to share a file, one process should open the file for exclusive access by using the CreateFile function. The CreateFileMapping function uses the handle returned by CreateFile to create a file-mapping object. Processes that have the name or a handle of the file-mapping object can share the file's data. The file handle should remain open until the processes are no longer sharing the file; this prevents nonsharing processes from reading from or writing to the file.

CreateFileMapping enables you to specify an object name, the number of bytes to be mapped from the file, and the read-and-write access to the mapped memory. CreateFileMapping fails if the access flags conflict with those specified when the file was opened by using CreateFile. CreateFileMapping returns a handle of the file-mapping object. This handle is used to create a "view of the file," or "file view," in the process's virtual address space. A file view is a copy of the entire file or a portion of the file, depending on the number of bytes requested.

The process that created the file-mapping object uses the MapViewOfFile function with the file-mapping object handle to create a file view, or copy of the file, in the process's virtual address space. MapViewOfFile returns a pointer to the file view. This function fails if the access flags conflict with those specified when the mapping object was created with CreateFileMapping.

To share the data in the file view, another process must create an identical file view in its own virtual address space. To do this, the process must first obtain a handle of the same file-mapping object and then create its own file view by using MapViewOfFile. The easiest way to obtain a handle of the file-mapping object is to use the OpenFileMapping function and specify the object's name. If the file-mapping object does not have a name, the process must obtain a handle of it through inheritance or duplication.

MapViewOfFile returns a pointer to the file view. To ensure that multiple processes are sharing the same data through their own pointers, all views of a file must be derived from the same file-mapping object. If this is the case, the file views are said to be coherent, or identical. Typically, file views are not coherent if they are derived from different file-mapping objects, even if the mapping objects refer to the same file.

Because the file view is a block of memory and not a file, processes must read from and write to the file view by using the ReadProcessMemory and WriteProcessMemory functions, not the ReadFile and WriteFile functions.

If one or more of the processes has write access to the shared data, processes must synchronize their access to the shared data by using a semaphore. This ensures that the file views remain coherent in all processes.

Some applications require that a file be mapped to the same address in multiple processes. To place the file view at a specific location within the process's address space, you should use the MapViewOfFileEx function and specify the desired address. If there is not enough space at the specified address, the function fails.

Although CreateFileMapping works with remote files, it does not keep them coherent. For example, if two machines both map a file as writable, and both change the same page, each machine will only see its own writes to the page. When the data gets updated on the disk, it is not merged.


Sharing a Memory Block

If two (or more) processes need to share a memory block not associated with a file, one process must use the CreateFileMapping function and specify (HANDLE)0xFFFFFFFF instead of an existing file handle. The corresponding file-mapping object accesses memory from the operating-system paging file. Processes sharing the operating-system paging file must create file views by using the MapViewOfFile or MapViewOfFileEx function just as when sharing a named file.


Closing a File View

When a process has finished using the shared memory, it should destroy the file view in its address space by using the UnmapViewOfFile function. This invalidates the pointer to the shared memory. If any of the pages of the file view changed since the view was mapped, this function copies the changed pages to the physical file.

To copy a specified number of bytes from the file view to the physical file, you should use the FlushViewOfFile function. FlushViewOfFile does not destroy the file view.

For more information on other ways to share data among applications, see OLE.


Using File Mapping

The code samples in this section illustrate how two processes might access an existing file as named shared memory.

As discussed earlier, if one or both processes write to the shared memory, the processes must use a semaphore to synchronize their access to the memory.

In the following code, the CreateFileMapping function creates a file-mapping object. When a corresponding file view is created, the process has read-and-write access to the memory.

hMapFile = CreateFileMapping(hFile,    /* current file handle */

    (LPSECURITY_ATTRIBUTES) NULL,      /* no security         */

    PAGE_READWRITE,                    /* read-write access   */

    0,                                 /* max. object size is */

    0,                                 /*   size of hFile     */

    "MyFileMappingObject");            /* name of map. object */

if (hMapFile == NULL) {

    ErrorHandler("Could not create file-mapping object.");

}

The following code uses the file-mapping object handle returned by CreateFileMapping to create a view of the file in the process's address space.

lpMapAddress = MapViewOfFile(hMapFile, /* handle to map. object */

    FILE_MAP_ALL_ACCESS,               /* read-write access     */

    0,                                 /* max. object size is   */

    0,                                 /*   size of hFile       */

    0);                                /* map entire file       */

if (lpMapAddress == NULL) {

    ErrorHandler("Could not map view of file.");

}

The MapViewOfFile function returns a pointer to the file view. The process can use the pointer to access the memory for whatever it needs to do.

In the next example, a second process uses the OpenFileMapping function to share the same memory. As in the original process, the MapViewOfFile function returns a pointer to the file view.

hMapFile = OpenFileMapping(FILE_MAP_ALL_ACCESS, /* r-w access  */

    FALSE,                             /* do not inherit       */

    "MyFileMappingObject");            /* name of mapping obj. */

if (hMapFile == NULL) {

    ErrorHandler("Could not open file-mapping object.");

}

lpMapAddress = MapViewOfFile(hMapFile, /* hndl. to map. obj. */

    FILE_MAP_ALL_ACCESS,               /* read-write access   */

    0,                                 /* max. object size is */

    0,                                 /*   size of hFile     */

    0);                                /* map entire file     */

if (lpMapAddress == NULL) {

    ErrorHandler("Could not map view of file.");

}

Note that MapViewOfFile returns different addresses in different processes. To specify the location of the file view within a process's address space, use the MapViewOfFileEx function, rather than MapViewOfFile.

The following example uses the UnmapViewOfFile function to invalidate the pointer to the mapped memory. This destroys the file view in the process's address space. If any pages of the file view changed since the view was mapped, UnmapViewOfFile also copies the changed pages to the physical file.

if (!UnmapViewOfFile(lpMapAddress)) {

    ErrorHandler("Could not unmap view of file.");

}

The FlushViewOfFile function copies the specified number of bytes of the file view to the physical file but does not destroy the file view:

if (!FlushViewOfFile(lpMapAddress, dwBytesToFlush)) {

    ErrorHandler("Could not flush memory to disk.");

}


Functions

The following functions are used with file mapping.

CreateFileMapping

FlushViewOfFile

MapViewOfFile

MapViewOfFileEx

OpenFileMapping

UnmapViewOfFile


Handles and Objects Overview

About Handles and Objects

An object is an internal structure that represents a system resource, such as a file, a thread, or a graphic image. An application cannot directly access the internal structure of an object or the system resource that an object represents. Instead, an application must obtain an object handle and use this handle to examine or modify the system resource (or both). In the Microsoft® Windows NT™ operating system, handles are usually implemented as indirect pointers, but this is not always the case.

The following topics discuss Win32 handles and objects:

Terms

Handle Limitations

User and Graphics Device Interface (GDI) Objects

Kernel Objects

Windows NT uses objects and handles to regulate access to system resources for two main reasons. First, the use of objects ensures that developers are not writing code specifically to low-level, internal structures. This enables Microsoft to add or change functionality in future versions of the operating system, as long as the original calling conventions are maintained. When subsequent versions of the operating system are released, applications will gain this new functionality with little or no additional development.

Second, the use of objects enables developers to take advantage of Windows NT security. Each object has its own access-control list (ACL) that specifies the types of actions processes can perform on the object. The operating system examines an object's ACL each time an application attempts to create a handle to the object. For more information about security, see Security

For most objects, the Win32 API provides functions that create the object, create an object handle, close the object handle, and destroy the object. These tasks may be combined or unnecessary, depending on the type of object and the situation. For example, an application could create an event object. Other applications could open the event and each would have a unique handle to the same event object. In this scenario, as the applications finish using the object, each closes its handle. When there are no open handles to the event object, the operating system removes the object from memory.

In contrast, an application could obtain the existing window-object handle. In this instance, when the window object is no longer needed, the application must remove the object from memory, which invalidates the window handle.

When a process terminates, the operating system automatically closes handles and deletes objects created by the process. However, when a thread terminates, the operating system usually does not close handles or delete objects. The only exceptions are window, hook, window position, and dynamic data exchange (DDE) conversation objects that are deleted when the creating thread terminates.

Handles and objects consume memory. Therefore, to preserve operating-system performance, applications should close handles and delete objects as soon as the handles and objects are no longer needed. Applications that do not do this can slow the operating system, due to excessive use of the paging file.

Windows NT provides three categories of objects: user, graphics device interface (GDI), and kernel. The operating system uses user objects to support window management, GDI objects to support graphics, and kernel objects to support memory management, process execution, and interprocess communications (IPC).


Handle Limitations

Some objects, such as user and GDI objects, support only one handle at a time. The operating system provides the handle when an application creates the object and invalidates the handle when the application destroys the object. Other objects, such as some kernel objects, support multiple handles to a single object. The operating system automatically removes the object from memory after the last handle to the object is closed.

The total number of open handles in the operating system is limited only by the amount of memory available to the operating system. However, a single process may have no more than 65,536 open GDI object handles. The per-process limit on user handles is 2^ 32; the per-process limit on kernel handles is 2^ 30.


User and GDI Objects

User and Graphics Device Interface Objects

User and GDI objects support only one handle per object. Processes cannot inherit or duplicate handles to user or GDI objects.

Handles to user objects are public to all processes. That is, any process can use the user object handle, provided that the process has access to the object as defined by user security. For more information about security, see Security.

Handles to GDI objects are private to a process. That is, only the process that created the GDI object can use the object handle.

The following illustrations show the creation and destruction of a user object, although the concepts apply equally to GDI objects.

In the following illustration, an application creates a window object. The CreateWindow function creates the window object and returns an object handle.

After the window object has been created, the application can use the window handle to display or change the window. The handle remains valid until the window object is destroyed.

In the next illustration, the application destroys the window object. The DestroyWindow function removes the window object from memory, which invalidates the window handle.

The following table lists the Windows NT user objects and each object's creator and destructor functions. The creator functions either create the object and an object handle or simply return the existing object handle. The destructor functions remove the object from memory, which invalidates the object handle.

Note that the window station and desktop objects are created and maintained by the system; applications cannot delete these objects.

Object	Creator function	Destructor function
Accelerator table	CreateAcceleratorTable	DestroyAcceleratorTable
Cursor	CreateCursor, LoadCursor, GetCursor, SetCursor	DestroyCursor
Dynamic data exchange conversation	DdeConnect, DdeConnectList, DdeQueryNextServer, DdeReconnect	DdeDisconnect, DdeDisconnectList
Desktop	GetThreadDesktop	-
Hook	SetWindowsHook, SetWindowsHookEx	UnhookWindowsHook
Menu	CreateMenu, CreatePopupMenu, GetMenu, GetSubMenu, GetSystemMenu,LoadMenu, LoadMenuIndirect	DestroyMenu
Window	CreateWindow, CreateWindowEx, CreateDialogParam, CreateDialogIndirectParam,CreateMDIWindow, FindWindow, GetWindow, GetClipboardOwner, GetDesktopWindow, GetDlgItem, GetForegroundWindow, GetLastActivePopup, GetOpenClipboardWindow, GetTopWindow, WindowFromDC, WindowFromPoint, and others	DestroyWindow
Window position	BeginDeferWindowPos	EndDeferWindowPos
Window station	GetProcessWindowStation	-
The following table lists the Windows NT GDI objects and each object's creator and destructor functions. The creator functions either create the object and an object handle or simply return the existing object handle. The destructor functions remove the object from memory, which invalidates the object handle.

Object	Creator function	Destructor function
Bitmap	CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIBitmap,CreateDIBSection, CreateDiscardableBitmap	DeleteObject
Brush	CreateBrushIndirect, CreateDIBPatternBrush, CreateDIBPatternBrushPt,CreateHatchBrush, CreatePatternBrush, CreateSolidBrush	DeleteObject
Font	CreateFont, CreateFontIndirect	DeleteObject
Palette	CreatePalette	DeleteObject
Pen	CreatePen, CreatePenIndirect	DeleteObject
Extended pen	ExtCreatePen	DeleteObject
Region	CombineRgn, CreateEllipticRgn, CreateEllipticRgnIndirect,CreatePolygonRgn, CreatePolyPolygonRgn, CreateRectRgn, CreateRectRgnIndirect, CreateRoundRectRgn, ExtCreateRegion, PathToRegion	DeleteObject
Device context	CreateDC, GetDC	DeleteDC, ReleaseDC
Memory device context	CreateCompatibleDC	DeleteDC
Metafile	CloseMetaFile, CopyMetaFile, GetMetaFile, SetMetaFileBitsEx	DeleteMetaFile
Metafile device context	CreateMetafile	CloseMetaFile
Enhanced metafile	CloseEnhMetaFile, CopyEnhMetaFile, GetEnhMetaFile, SetEnhMetaFileBits	DeleteEnhMetaFile
Enhanced-metafile device context	CreateEnhMetaFile	CloseEnhMetaFile


Kernel Objects

Kernel object handles are process specific. That is, a process must either create a kernel object or open an existing object to obtain an object handle. Any process can create a new handle to an existing kernel object (even one created by another process), provided that the process knows the name of the object and has access to the object as defined by user security. For more information about security, see Security.

Processes can inherit or duplicate handles to the following types of kernel objects:

Processes

Threads

Files (including file-mapping objects)

Events

Semaphores

Mutexes

Pipes (named and anonymous)

Mailslots

Communications devices

All other kernel objects are private to the process that created them; object handles cannot be duplicated or inherited.

A child process inherits an open handle from its parent process if inheritance was specified when the original handle was created and if the child process was created with the "inherit handles" flag set. An inherited handle is valid only in the context of the child process.

The DuplicateHandle function duplicates a handle into the current process or into another process. If an application duplicates one of its handles into another process, the duplicated handle is valid only in the context of the other process.

A duplicated or inherited handle is a unique value, but it refers to the same object as the original handle.

Kernel object handles include access rights that indicate the actions the application wants to perform on the object. An application specifies access rights when it creates an object or obtains an existing object handle. Each type of kernel object supports its own set of access rights. For example, event handles can have "set" or "wait" access (or both), file handles can have "read" or "write" access (or both), and so on. For more information on access rights, see Security, and the topics that describe individual objects.

In the following illustration, an application creates an event object. The CreateEvent function creates the event object and returns an object handle.

After the event object has been created, the application can use the event handle to set or wait on the event. The handle remains valid until the application closes the handle or terminates.

Most kernel objects support multiple handles to a single object. For example, the application in the preceding illustration could obtain additional event object handles by using the OpenEvent function, as shown in the next illustration.

This enables an application to have handles with different access rights. For example, Handle 1 might have "set" and "wait" access to the event, and Handle 2 might have only "wait" access.

If another process knows the event name and has security access to the object, it can create its own event object handle by using OpenEvent.

The original application could also duplicate one of its handles into the same process or into another process by using the DuplicateHandle function, as shown in the following illustration.

The next illustration shows how a child process inherits a handle created by its parent process.

A child process of an application automatically inherits handles created by its parent process if inheritance was specified when the handles were created and if the child process is created with the "inherit handles" flag set. Note that in the preceding illustration, Handle 2 is not equivalent to Handle 1 but does refer to the same event object.

An object remains in memory as long as at least one object handle exists. In the following illustration, the applications use the CloseHandle function to close their event object handles. When there are no event handles, the operating system removes the object from memory, as shown in the following illustration.

Occasionally, an object remains in memory after all object handles have been closed. For example, a thread could create an event object and wait on the event handle. While the thread is waiting, another thread could close the same event object handle. The event object remains in memory, without any event object handles, until the event object is set to the signaled state and the wait operation is completed. At this time, the operating system removes the object from memory.

Windows NT manages file objects somewhat differently from other kernel objects. File objects contain the file pointer--the pointer to the next byte to be read or written in a file. Whenever an application creates a new file handle, the operating system creates a new file object. Therefore, more than one file object can refer to a single file on disk, as shown in the next illustration.

Only through duplication or inheritance can more than one file handle refer to the same file object, as shown in the following illustration.

The following table lists each of the Windows NT kernel objects and each object's creator and destructor functions. The creator functions either create the object and an object handle or create a new existing object handle. The destructor functions close the object handle. When an application closes the last handle to a kernel object, the operating system removes the object from memory.

Object	Creator function	Destructor function
Process	CreateProcess, OpenProcess, GetCurrentProcess	CloseHandle, TerminateProcess
Thread	CreateThread, CreateRemoteThread, GetCurrentThread	CloseHandle, TerminateThread
File	CreateFile	CloseHandle, DeleteFile
File mapping	CreateFileMapping, OpenFileMapping	CloseHandle
Event	CreateEvent, OpenEvent	CloseHandle
Semaphore	CreateSemaphore, OpenSemaphore	CloseHandle
Mutex	CreateMutex, OpenMutex	CloseHandle
Pipe	CreatePipe	CloseHandle
Named pipe	CreateNamedPipe	CloseHandle, DisconnectNamedPipe
Mailslot	CreateMailslot	CloseHandle
Communications device	GetStdHandle	CloseHandle
Heap	HeapCreate	HeapDestroy
Module	LoadLibrary, GetModuleHandle	FreeLibrary
Update resource	BeginUpdateResource	EndUpdateResource
Find file	FindFirstFile	FindClose
Event log	OpenEventLog, RegisterEventSource, OpenBackupEventLog	CloseEventLog
Change notification	FindFirstChangeNotification	FindCloseChangeNotification


Security Overview

The following topics discuss Win32 security:

Terms

About Security

Security Model

Access Tokens

Security Descriptors

Access-control Lists (ACLs)

Access-control Entries (ACEs)

Access Masks and Access Rights

Security Identifiers (SIDs)

Privileges

Impersonation

Security in New Objects

Inheritance

Audit Generation

Securable Objects

File and Directory Objects

Mailslot Objects

Pipe Objects

Kernel Objects

Window-management Objects

Registry Key Objects

Service Objects

Synchronization Objects

Denying All Access

Allowing Access

Setting Privileges

Security Editor

Designing a Protected Server

Functions


About Security

The security provisions of Microsoft® Windows NT™ are available to Windows-based applications automatically. Every application running on the system is subject to the security imposed by the particular configuration of the local implementation of Windows NT.

The security functions in the Win32 application programming interface (API) allow an application to selectively grant and deny access to an object. An application can specify many different kinds of access for particular users and groups of users. The operating system grants or denies access to an object based on a comparison of the security provisions stored with an object with the access rights specified in a token associated with the process or thread requesting the access. These security functions allow an application to query and manipulate the security features of both an object and a process or thread.

The impact of Windows security on most Windows functions is minimal, and a Windows-based application not requiring security functionality usually does not need to incorporate any special code. However, a developer can use the security features of Windows NT to provide a number of services in a Windows-based application. Generally, any application that manipulates a system-wide resource such as the system time, must use the security system to gain access to that resource. A security-aware application might allow the user to query the security attributes of a file, provide specialized feedback when access to a secure file is denied, or customize the security attributes of a file or group of files so that only a subset of other users on a network has access to the information.

The first release of Windows NT is designed to support C2-level security as defined by the US Department of Defense. Some of the most important requirements of C2-level security are shown in the following list.

It must be possible to control access to a resource. This access control must include or exclude individual users or named groups of users.

Memory must be protected so its contents cannot be read after it is freed by a process.

Users must identify themselves in a unique manner when they log on. All auditable actions must identify the user performing the action.

System administrators must be able to audit security-related events. Access to this audit data must be limited to authorized administrators.

The system must protect itself from external interference or tampering, such as modification of the running system or of system files stored on disk.


Security Model

All named objects in Windows NT, and some unnamed objects, can be secured. The security attributes of each securable object in Windows are described by a security descriptor, that contains information about the owner of the object and by an access-control list (ACL), identifying the users and groups allowed or denied access to the object. An ACL contains an entry for each user, global group, or local group (alias) being allowed or denied access to the object. Each of these entries is an access-control entry (ACE).

At logon, a user is assigned an access token containing identifiers that represent the user and any groups to which the user belongs. Every process run on behalf of this user will have a copy of this particular access token. When a process attempts to use an object, the system compares the security attributes listed in the access token with the ACEs in the object's ACL. The system compares the access token with each ACE until access is either granted or denied or until there are no more ACEs to check. Conceivably, several ACEs could apply to a token. And, if this occurs, the access rights granted by each ACE accumulate. For example, if one ACE grants read access to a group in an access token and another ACE grants write access to the user, who is also a member of the group, the user will have both read and write access to the object when the access check is complete.

The following illustration shows the relationship between these blocks of security information:

Typically, the application protecting an object is a server in that it defines the users and groups with access to the object. The application interacts with clients when they attempt to gain access to the object. Users and groups are identified by security identifiers (SIDs). An SID is a structure of variable length that uniquely identifies a user or group. SIDs are stored in a security database that an application can query by calling Win32 functions. With one exception, an SID is used to identify a user or group is never reassigned to another user or group. For a given account, the only SID that will not be the same from logon to logon is the logon-identifier SID. In the model represented by the preceding illustration, SIDs would be used to identify the following:

The owner and group in the security descriptor

The recipient of the access being granted by each ACE

The user and groups in the access token

Security descriptors, SIDs, and ACLs are treated by applications as opaque structures and are intended to be manipulated only by using Win32 functions. This helps ensure that these structures remain syntactically accurate and prevents future enhancements to the security system from breaking existing code.

Pointers to doubleword values or structures must be aligned on doubleword boundaries. However, the exception is strings, for which alignment is not critical. All Win32 memory-allocation functions return handles of doubleword-aligned memory objects.


Access Tokens

When a user logs on, the system verifies the user's password by comparing it with information stored in a security database. If the password is authenticated, the system produces an access token and attaches it to the user's process. This access token identifies the user in all subsequent interactions with securable objects and contains the following information about a process:

The user's SID

Group SIDs

Privileges

An owner SID

The SID for the primary group

The default discretionary access-control list (ACL)

The source of the access token

Whether the token is a primary or impersonation token

Current impersonation levels

Other statistics

Every process must have an access token, but even a thread can have one assigned to it. When a thread has an access token, it supersedes the token of the process that owns the thread. This allows individual threads of a server process to impersonate clients by associating a client's access token with the thread. The only exception to this is any action requiring the SE_TCB_NAME privilege. This privilege is always checked against the process token, even if the current thread has an impersonation token.

For more information about privileges, see Privileges. For more information about security identifiers (SIDs), see Security Identifiers. For more information about discretionary ACLs, see Access-control Lists. For more information about the components of an access token, see the following token structures and enumerated types:

Structure or type	Specifies

TOKEN_CONTROL	Information useful in identifying an access token.

TOKEN_DEFAULT_DACL	The default discretionary ACL for an access token.

TOKEN_GROUPS	Specifies the SIDs of the access token's groups and whether any privileges are enabled.

TOKEN_INFORMATION_CLASS	Information being set in or retrieved from an access token.

TOKEN_OWNER	The SID of an access token's owner.

TOKEN_PRIMARY_GROUP	The SID of the access token's primary group.

TOKEN_PRIVILEGES	The privileges associated with an access token and whether the privileges are enabled.

TOKEN_SOURCE	The source of an access token.

TOKEN_STATISTICS	Statistics associated with an access token.

TOKEN_TYPE	Whether an access token is being used as an impersonation token.

TOKEN_USER	The SID of an access token's user.

Following are the functions an application can use to manipulate access tokens.

Function	Description

AdjustTokenGroups	Changes the group information in an access token.

AdjustTokenPrivileges	Changes the privileges in an access token.

GetTokenInformation	Retrieves information about a token.

OpenProcessToken	Retrieves the handle of the access token for a process.

OpenThreadToken	Retrieves the handle of the access token for a thread.

SetTokenInformation	Changes a token's owner, primary group, or default discretionary ACL.


Security Descriptors

A security descriptor contains the security information associated with an object. This information can include an owner, a primary group, a discretionary access-control list, and a system access-control list. This information is stored in the form of security identifiers (SIDs) and access-control lists (ACLs). For more information about access-control lists, see Access-control Lists.

There are five groups of Windows functions that manipulate security descriptors, corresponding to five different kinds of objects:

Files

User Objects (also called window-management objects)

Kernel objects

Registry objects

Private objects

To manipulate security descriptors for files and directories, an application can use the GetFileSecurity and SetFileSecurity functions. These functions identify files and directories by using character strings, instead of using the handles required by other security functions.

Kernel objects and user objects are manipulated by two pairs of functions: GetKernelObjectSecurity and SetKernelObjectSecurity, and GetUserObjectSecurity and SetUserObjectSecurity. Kernel and user objects are separated in this way because it is possible for a file handle and a window handle to have the same value. An application can use these functions to ensure that the correct object referenced.

An application can use the RegGetKeySecurity and RegSetKeySecurity functions to retrieve and set security descriptors for keys in the registry.

The functions that manipulate private objects allow an application, usually a server, to associate a security descriptor with its own object type. The functions provide the ability to retrieve default information from an access token, support inheritance, and manipulate specific parts of the security descriptor. These functions are CreatePrivateObjectSecurity, GetPrivateObjectSecurity, SetPrivateObjectSecurity, and DestroyPrivateObjectSecurity.

The Windows functions in the following table enable an application to query a security descriptor or set specific information in it.

Function	Description

GetSecurityDescriptorControl	Retrieves revision and control information.

GetSecurityDescriptorDacl	Retrieves the discretionary ACL.

GetSecurityDescriptorGroup	Retrieves primary group information.

GetSecurityDescriptorLength	Returns the length of a security descriptor.

GetSecurityDescriptorOwner	Retrieves the owner of a security descriptor.

GetSecurityDescriptorSacl	Retrieves the system ACL.

SetSecurityDescriptorDacl	Sets discretionary ACL information.

SetSecurityDescriptorGroup	Sets primary group information.

SetSecurityDescriptorOwner	Sets the owner of the security descriptor.

SetSecurityDescriptorSacl	Sets system ACL information.

To check the revision level and structural integrity of a security descriptor, an application can call the IsValidSecurityDescriptor function.

A security descriptor can be in either an absolute or self-relative format. In absolute format, a security descriptor contains pointers to its information, not the information itself. This format is useful when default settings for the owner, group, and discretionary ACL are available, because an application can simply call the InitializeSecurityDescriptor function to initialize a SECURITY_DESCRIPTOR structure and then point to preexisting components, such as SIDs and ACLs.

A security descriptor in self-relative format contains information in a contiguous block of memory. In this format, a SECURITY_DESCRIPTOR structure always starts the information, but the other components of the security descriptor can follow the structure in any order. Instead of using memory addresses, the security descriptor's components are identified by offsets from the beginning of the descriptor. This format is useful when a security descriptor must be stored on disk, transmitted by means of a communications protocol, or copied in memory.

All security descriptors provided by the operating system as the result of calls to Win32 API functions are in self-relative format. Security descriptors passed back to the operating system can be in either form, depending on the situation.

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. The MakeAbsoluteSD function can create an absolute security descriptor from a self-relative security descriptor.


Access-control Lists
Access-control Lists (ACLs)

Access-control Lists (ACLs)

Part of the security descriptor for each securable object is a list specifying users and groups, and the access to the object each is granted or denied. This list is an access-control list (ACL). An ACL consists of two parts. The first is a header in the form of an ACL structure. This structure contains information pertaining to the entire ACL, such as its revision level and size. The second part is an ordered list of access-control entries (ACEs). Each ACE identifies a user, group, or local group, and the access each of them is allowed.

There are two types of ACLs: discretionary and system.

A discretionary ACL is controlled by the owner of an object and specifies the access particular users or groups can have to an object. For example, the owner of a file can use a discretionary ACL to control who can and cannot have access to the file.

When an object's discretionary ACL contains no access-control entries, no access rights have been explicitly granted. Therefore, access to the object is implicitly denied. However, when an object has no discretionary ACL, no protection is assigned to the object and any access request is granted. For information about setting no ACL for an object, see Allowing Access.

An object may also have system-level security information associated with it, in the form of a system ACL. System ACLs are controlled by system administrators. A system ACL can enable the system administrator to audit any attempts to gain access to an object. In future releases, a system ACL will also be able to raise an alarm when an unauthorized user attempts to gain access to an object.

An application can use Win32 functions to retrieve, initialize, query, and modify ACLs.

Function	Description

GetAclInformation	Retrieves revision or size information about an ACL.

GetSecurityDescriptorDacl	Retrieves a discretionary ACL from a specified security descriptor.

GetSecurityDescriptorSacl	Retrieves a system ACL from a specified security descriptor.

InitializeAcl	Initializes an ACL by creating an empty ACL structure.

IsValidAcl	Determines whether an ACL's revision level and structure are valid.

SetAclInformation	Changes the revision information in an ACL.

SetSecurityDescriptorDacl	Puts a discretionary ACL into a specified security descriptor, superseding any preexisting discretionary ACL.

SetSecurityDescriptorSacl	Puts a system access-control list into a specified security descriptor, superseding any preexisting system ACL.

To change a security descriptor's ACL, an application generally initializes a new ACL, adds ACEs to it, then uses either the SetSecurityDescriptorDacl or SetSecurityDescriptorSacl function to add the new ACL to the security descriptor. GetSecurityDescriptorDacl and GetSecurityDescriptorSacl retrieve a pointer to a preexisting ACL in a security descriptor so an application can copy information from the previous ACL as it creates a new one.


Access-control Entries
Access-control Entries (ACEs)

Access-control Entries (ACEs)

Each of the entries in an access-control list (ACL) is an access-control entry (ACE). Each ACE consists of three parts:

A header in the form of an ACE_HEADER structure

An access mask for the specified ACE type

A security identifier (SID)

The ACE_HEADER structure gives information such as the type of the ACE and its size. The access mask is a 32-bit value that specifies the rights being granted, denied, or monitored. The security identifier is in the form of an SID structure and it specifies the user or group to which the ACE applies.

Discretionary ACLs have two types of ACE defined in the AceType member of the ACE_HEADER structure. They are shown in the following table.

Type	Description

ACCESS_ALLOWED_ACE_TYPE	This ACE grants the specified rights to the user or group identified by the security identifier. It is defined by an ACCESS_ALLOWED_ACE structure.

ACCESS_DENIED_ACE_TYPE	This ACE denies the specified rights to the user or group identified by the security identifier. It is defined by an ACCESS_DENIED_ACE structure.

Only one type of ACE, SYSTEM-AUDIT-ACE-TYPE, is currently supported for system ACLs. It specifies what types of access cause system-level audits. This ACE is defined by a SYSTEM_AUDIT_ACE structure.

The SYSTEM_ALARM_ACE_TYPE is not supported in the current version of Windows NT.

Security auditing is used to keep a log of security-significant events, such as which users access a secured file. The SYSTEM_AUDIT_ACE_TYPE ACE is used to generate security audit messages and causes them to be entered into a system audit log for later processing. An administrator can view this log by using Event Viewer (EVENTVWR.EXE) and can manipulate the log by using the event-logging functions. For more information about event logging, see Event Logging.

The order of ACEs in an ACL is important. An access token is checked against the ACEs in an ACL until it either accumulates the access rights it needs, it is explicitly denied access in an access-denied ACE, or it reaches the end of the ACL and is implicitly denied access. If a user is a member of several groups represented by ACEs in the ACL, the rights granted to each group apply to the user. For example, a user may request read and write access to an object protected by an ACE that grants one group read access only. Another ACE may provide protection that grants write access. If the user belongs to both groups, the request will succeed. An ACL typically denies access to specific users or groups of users and allows access to more general categories of users. Although the ACEs in an ACL can be in any order, the security menu items in File Manager and Registry Editor (REGEDT32.EXE) only work with ACLs in which access-denied ACEs precede access-allowed ACEs.

To change a security descriptor's ACL, an application usually initializes a new ACL, adds ACEs to it, and then adds the ACL to the security descriptor. The AddAccessAllowedAce and AddAccessDeniedAce functions add an ACE at the end of a discretionary ACL. The AddAuditAccessAce function adds an ACE at the end of a system ACL. The AddAce function allows an application to specify the position of a new ACE in an ACL, and the DeleteAce function allows an application to remove an ACE from a specified position in one. The GetAce and FindFirstFreeAce functions are especially useful when copying information from a preexisting ACL to a new one.


Access Masks and Access Rights

An access right defines a particular set of abilities that can be granted or denied to a process when it attempts to use an object. For example, if an application attempts to create a subkey in the registry but does not have the KEY_CREATE_SUB_KEY access right, the system does not carry out the operation. An application usually requests a set of access rights when it opens an object, and in the case of registry keys, it makes that request when it calls the RegOpenKeyEx function.

An access mask is the component of an access-control entry (ACE) that contains the specific rights, standard rights, and generic rights defining the access a user or group has to an object. Access masks are also used to request access rights when an object is opened. For example, an application that needs to set values, create subkeys, and query values in the registry can open a key using an access mask that combines the KEY_WRITE and KEY_QUERY_VALUE access rights.

An access mask is a single 32-bit value. The first 16 bits are the specific rights and apply only to the object type associated with the access mask. Bits 16 through 23 are the standard rights applying to all objects. Bits 28 through 31 are the generic rights mapped to specific and standard rights when access to an object is requested.

Generic access rights are broad types of access whose exact implementation is determined by the application defining an object. These rights are used when protecting an object. For example, an application that defines a voice-annotation object might define specific access rights by using VOICE_PLAY and VOICE_EDIT for playing and editing the object. It might set up a GENERIC_MAPPING structure in which GENERIC_EXECUTE maps to VOICE_PLAY and GENERIC_WRITE maps to both VOICE_PLAY and VOICE_EDIT.

The following are the generic rights that have been defined.

Constant	Meaning

GENERIC_ALL	Read, write, and execute access

GENERIC_EXECUTE	Execute access

GENERIC_READ	Read access

GENERIC_WRITE	Write access

If an application receives GENERIC_WRITE access to a file, for example, it has specific rights allowing it to write and append data to the file, write file attributes, and write extended attributes. In addition, the application has the STANDARD_RIGHTS_WRITE and SYNCHRONIZE standard access rights.

The following constants are masks for the standard access rights.

Constant	Meaning

DELETE	Delete access.

READ_CONTROL	Read access to the security descriptor not including the system ACL.

STANDARD_RIGHTS_ALL	Combines DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER, and SYNCHRONIZE access.

STANDARD_RIGHTS_EXECUTE	Currently defined to equal READ_CONTROL.

STANDARD_RIGHTS_READ	Currently defined to equal READ_CONTROL.

STANDARD_RIGHTS_REQUIRED	Combines DELETE, READ_CONTROL, WRITE_DAC, and WRITE_OWNER access.

STANDARD_RIGHTS_WRITE	Currently defined to equal READ_CONTROL.

SYNCHRONIZE	Synchronize access. Allows a thread to wait for the object. This access type is not supported by all object types.

WRITE_DAC	Write access to the discretionary ACL.

WRITE_OWNER	Write access to the owner.

The SPECIFIC_RIGHTS_ALL constant denotes all of the specific rights, even those not be defined for an object.

The system validates each requested access against the process's access token, so requests for broad access can require a great deal of validation time. Therefore, it is generally better for applications to avoid requesting the broadest possible access to an object except when such access is actually required. Certain rights are commonly used in an ACL to deny access to an object, but they are rarely used in requests to open an object. In particular, requesting any of the access rights in the following list has a negative impact on system performance:

EVENT_ALL_ACCESS	SECTION_ALL_ACCESS

FILE_MAP_ALL_ACCESS	SEMAPHORE_ALL_ACCESS

GENERIC_ALL	SERVICE_ALL_ACCESS

KEY_ALL_ACCESS	SPECIFIC_RIGHTS_ALL

MUTEX_ALL_ACCESS	STANDARD_RIGHTS_ALL

PROCESS_ALL_ACCESS	THREAD_ALL_ACCESS

SC_MANAGER_ALL_ACCESS	TOKEN_ALL_ACCESS

The MAXIMUM_ALLOWED constant specifies that an object is to be opened by using all the access rights that are valid for the given user. An additional access type, ACCESS_SYSTEM_SECURITY, is needed to manipulate an object's system ACL. Neither MAXIMUM_ALLOWED nor ACCESS_SYSTEM_SECURITY can be used in an ACL.

The MapGenericMask function maps a series of generic rights specified in a GENERIC_MAPPING structure to specific and standard rights in an access mask. An application can use the GENERIC_MAPPING structure to specify the access rights for an object when it is created. When a client process requests access to the object, the server can use MapGenericMask to translate the client's requested access into the standard and specific rights for that object.

To discover whether a client process has the proper access rights to an object, a server can call the AccessCheck or AccessCheckAndAuditAlarm function. The AreAllAccessesGranted and AreAnyAccessesGranted functions compare a requested access mask with a granted access mask.


Security Identifiers
Security Identifiers (SIDs)

Security Identifiers (SIDs)

A security identifier (SID) is a unique value of variable length used to identify a user or group. The SID assigned to a user when he or she logs on becomes part of the access token that accompanies any process begun by that user. Except for the logon SID, an SID is always unique. When it has been used to identify a user or group, it cannot be used again, at any time, to identify another user or group.

SIDs identify several separate elements. These include the owner and group in security descriptors, the recipient of the access being granted by access-control entries (ACEs), and the user, as well as groups of which the user is a member in access tokens.

An SID also contains the following information.

A 48-bit identifier authority value

A revision level

A variable number of subauthority values (relative identifiers)

The identifier authority value actually contains two values and is the most important piece of information in an SID. It contains a value identifying the agency that issued the SID, usually representing a Microsoft® Advanced Server™ domain, and a 32-bit relative identifier (RID) value, to uniquely identify the user or group in that agency. Joining these values ensures that no two SIDs will be the same, even if two different SID-issuing authorities issue the same RID. Each SID-issuing authority issues a given RID only once.

A standardized shorthand notation for SIDs makes it simpler to visualize their components:

S-R-I-S-S...

In the notation shown above, S identifies the series of digits as an SID, R is the revision level, I is the identifier-authority value, and S is the subauthority value. An SID could be written in this notation as follows:

S-1-4138-86

In this example, the SID has a revision level of 1, an identifier-authority value of 4138, and one subauthority value of 86.

An application is never required to manipulate an SID directly. The following Win32 functions provide all the functionality required to work with SIDs.

Function	Description

AllocateAndInitializeSid	Allocates and initializes an SID with the specified number of subauthorities.

CopySid	Copies a source SID to a buffer.

EqualPrefixSid	Tests two SID prefix values for equality. An SID prefix is the entire SID except for the last subauthority value.

EqualSid	Tests two SIDs for equality. They must match exactly to be considered equal.

FreeSid	Frees an SID previously allocated by using the AllocateAndInitializeSid function.

GetLengthSid	Retrieves the length of an SID.

GetSidIdentifierAuthority	Retrieves a pointer to an SID's identifier authority.

GetSidLengthRequired	Retrieves the size of the buffer required to store an SID with a specified number of subauthorities.

GetSidSubAuthority	Retrieves a pointer to a specified subauthority in an SID.

GetSidSubAuthorityCount	Retrieves the number of subauthorities in an SID.

InitializeSid	Initializes an SID structure.

IsValidSid	Tests the validity of an SID by verifying that the revision number is within a known range and that the number of subauthorities is less than the maximum.

LookupAccountName	Retrieves the SID corresponding to a specified account name. Use the GetUserName function to retrieve the user name for the current thread.

LookupAccountSid	Retrieves the account name corresponding to a specified SID.

Some identifier authorities are predefined, as shown in the following table.

Identifier authority	SID 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

The following RID values are also defined.

Relative identifier authority	Value	Superior authority

SECURITY_NULL_RID	0	S-1-0

SECURITY_WORLD_RID	0	S-1-1

SECURITY_LOCAL_RID	0	S-1-2

SECURITY_CREATOR_OWNER_RID	0	S-1-3

SECURITY_CREATOR_GROUP_RID	1	S-1-3

An application can combine an identifier authority and one of these RID values to create an SID that is meaningful on all installations. For example, S-1-1-0 (SECURITY_WORLD_SID_AUTHORITY and SECURITY_WORLD_RID) always identifies the special group representing all users. These security identifiers are universal well-known SIDs. A universal well-known SID is meaningful on all secure systems using this security model, including systems not running Windows NT. The AllocateAndInitializeSid function provides a simple method of combining an identifier authority and an RID.

The following are some universal well-known SIDs.

Universal well-known SID	Value	Identifies

Null SID	(S-1-0-0)	A group with no members. This is often used when an SID value is not known.

World	(S-1-1-0)	A group that includes all users.

Local	(S-1-2-0)	Users who log on to terminals locally (physically) connected to the system.

Creator Owner ID	(S-1-3-0)	A security identifier to be replaced by the security identifier of the user who created a new object. This SID is used in inheritable ACLs.

Creator Group ID	(S-1-3-1)	Identifies a security identifier to be replaced by the primary-group SID of the user who created a new object. Use this SID in inheritable ACLs.

Another predefined identifier authority is SECURITY_NT_AUTHORITY (S-1-5). This identifier authority produces SIDs that are not universal but are meaningful only on Windows NT installations. An application can use the following RID values with SECURITY_NT_AUTHORITY to create well-known SIDs.

Constant	Identifies

SECURITY_DIALUP_RID (S-1-5-1)

Users who log on to terminals using a dialup modem. This is a group identifier.

SECURITY_NETWORK_RID (S-1-5-2)

Users who log on across a network. This is a group identifier.

SECURITY_BATCH_RID (S-1-5-3)

Users who log on using a batch queue facility. This is a group identifier.

SECURITY_INTERACTIVE_RID (S-1-5-4)

Users who log on for interactive operation. This is a group identifier.

SECURITY_LOGON_IDS_RID (S-1-5-5-X-Y)

A logon session. This is used to ensure that only processes in a given logon session can gain access to the window-station objects for that session. The X and Y values for these SIDs are different for each logon session. The value SECURITY_LOGON_IDS_RID_COUNT is the number of RIDs in this identifier (5-X-Y).

SECURITY_SERVICE_RID (S-1-5-6)

An account authorized to perform security services.

SECURITY_LOCAL_SYSTEM_RID

(S-1-5-0x12) The user account used by the operating system.

SECURITY_BUILTIN_DOMAIN_RID (S-1-5-0x20)

The built-in system domain.

The following RIDs are relative to each domain.

RID	Identifies

DOMAIN_USER_RID_ADMIN	The administrative user account in a domain.

DOMAIN_USER_RID_GUEST	The guest-user account in a domain. This account can be logged onto automatically by users who do not have an account.

DOMAIN_GROUP_RID_ADMINS	The domain administrator's group. This account exists only on systems running Microsoft® Lan Manager for Windows NT™, not Windows NT systems.

DOMAIN_GROUP_RID_USERS	A group containing all user accounts in a domain. All users are automatically added to this group.

An alias is a local group and is similar to a global group, but it can contain members from other domains. Its members can be users or other groups. Some domain-relative RIDs, such as the following, can be used to form well-known SIDs used as local groups.

RID	Identifies

DOMAIN_ALIAS_RID_ADMINS

A local group used for administration of the domain.

DOMAIN_ALIAS_RID_USERS

A local group representing all users in the domain.

DOMAIN_ALIAS_RID_GUESTS

A local group representing guests of the domain.

DOMAIN_ALIAS_RID_POWER_USERS

A local group used to represent a user or set of users that expect to treat a system as if it were their personal computer rather than a multiuser workstation.

DOMAIN_ALIAS_RID_ACCOUNT_OPS

A local group existing only on systems running Microsoft Lan Manager for Windows NT. This local group permits control over non-administrator accounts.

DOMAIN_ALIAS_RID_SYSTEM_OPS

A local group existing only on systems running Microsoft Lan Manager for Windows NT. This local group performs system administrative functions, not including security functions. It establishes network shares, controls printers, unlocks workstations, and performs other operations.

DOMAIN_ALIAS_RID_PRINT_OPS

A local group existing only on systems running Microsoft Lan Manager for Windows NT. This local group controls printers and print queues.

DOMAIN_ALIAS_RID_BACKUP_OPS

A local group used for controlling assignment of file backup-and-restore privileges.

DOMAIN_ALIAS_RID_REPLICATOR

A local group responsible for copying security databases from the primary domain controller to the backup domain controllers.


Privileges

A privilege is used to control access to an object or service more strictly than is normal 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 resource, such as when it changes the system time or shuts down the system.

A privilege is a locally unique identifier (LUID) identified by a character string. This 64-bit value is guaranteed to be unique on the operating system that generated it until the system is restarted. For example, SE_SYSTEMTIME_NAME is a string identifying an LUID. A privilege has three representations, as shown below.

A string name, meaningful across systems, called a global program name (for example, SE_SYSTEMTIME_NAME).

A readable name that can be displayed to the user when necessary. For example, "Change the system time."

A local representation that differs from computer to computer.

Privileges provide access to services rarely needed by most users. An account usually has privileges that are disabled, and they must be enabled to be used. For example, to set the time on the local computer, an application has to set the SE_PRIVILEGE_ENABLED attribute for the SE_SYSTEMTIME_NAME privilege. For security reasons, disable an enabled privilege when it is no longer needed.

The following privileges are defined by Windows NT.

Privilege	Description

SE_ASSIGNPRIMARYTOKEN_NAME	Required to assign the primary token of a process.

SE_AUDIT_NAME	Required to generate audit-log entries. Give this privilege to secure servers.

SE_BACKUP_NAME	Required to perform backup operations.

SE_CHANGE_NOTIFY_NAME	Required to receive notifications of changes to files or directories. This privilege also causes the system to skip all traversal access checks. It is enabled by default for all users.

SE_CREATE_PAGEFILE_NAME	Required to create a paging file.

SE_CREATE_PERMANENT_NAME	Required to create a permanent object.

SE_CREATE_TOKEN_NAME	Required to create a primary token.

SE_DEBUG_NAME	Required to debug a process.

SE_INC_BASE_PRIORITY_NAME	Required to increase the base priority of a process.

SE_INCREASE_QUOTA_NAME	Required to increase the quota assigned to a process.

SE_LOAD_DRIVER_NAME	Required to load or unload a device driver.

SE_LOCK_MEMORY_NAME	Required to lock physical pages in memory.

SE_PROF_SINGLE_PROCESS_NAME	Required to gather profiling information for a single process.

SE_REMOTE_SHUTDOWN_NAME	Required to shut down a system using a network request.

SE_RESTORE_NAME	Required to perform restore operations.

SE_SECURITY_NAME	Required to perform a number of security-related functions, such as controlling and viewing audit messages. This privilege identifies its holder as a security operator.

SE_SHUTDOWN_NAME	Required to shut down a local system.

SE_SYSTEM_ENVIRONMENT_NAME	Required to modify the non-volatile RAM of systems that use this type of memory to store configuration information.

SE_SYSTEM_PROFILE_NAME	Required to gather profiling information for the entire system.

SE_SYSTEMTIME_NAME	Required to modify the system time.

SE_TAKE_OWNERSHIP_NAME	Required to take ownership of an object without being granted discretionary access. This privilege allows the owner value to be set only to those values that the holder may legitimately assign as the owner of an object.

SE_TCB_NAME	This privilege identifies its holder as part of the trusted computer base. Some trusted protected subsystems are granted this privilege.

SE_UNSOLICITED_INPUT_NAME	Required to read unsolicited input from a terminal device.

The following functions are provided for working with privileges.

Function	Description

LookupPrivilegeValue	Allows an application to retrieve the LUID corresponding to a privilege on the local system. This is the local representation of that privilege and an application can set it in the TOKEN_PRIVILEGES and LUID_AND_ATTRIBUTES structures.

LookupPrivilegeDisplayName	Retrieves a displayable privilege name. For example, "Force shutdown from a remote system."

LookupPrivilegeName	Retrieves a programmatic privilege name.

PrivilegeCheck	Determines whether a client application has the privileges required to gain access to an object, such as, SE_REMOTE_SHUTDOWN_NAME.


Impersonation

Impersonation is the ability of a process to take on the security attributes of another process. Typically, a server thread impersonates a client thread to act on behalf of that client to access objects or validate access to its own objects. For example, when a client in a DDE conversation requests information from a DDE server, the server can impersonate the client so the system can verify that the client is allowed access to the information.

Currently, there are three impersonation levels:

Impersonation Level	Meaning

SecurityAnonymous	Indicates the client does not want the server to obtain identification information about the client.

SecurityIdentification	Allows the server to obtain information about the client, such as security identifiers and privileges, without being able to impersonate the client. This is useful for servers who export their own objects, such as tables and views exported by a database product. Using the retrieved client security information, the server is able to make access-validation decisions for itself even though it is unable to use other services as the client.

SecurityImpersonation	Allows the server to impersonate the client's security context on its local system. The server cannot impersonate the client on remote systems.

A fourth level, SecurityDelegation, is not supported in this release of Windows NT.

A DDE server application can impersonate a client by calling the DdeImpersonateClient function. When it has finished the task requiring the impersonation, the DDE server application can revert to its own security information by calling the RevertToSelf function. Similarly, a named-pipe server can use the ImpersonateNamedPipeClient and RevertToSelf functions. The DuplicateToken function creates an impersonation token that duplicates an existing token.

The ImpersonateSelf function enables a thread to generate a copy of its own access token. This is useful when an application needs to change the security attributes of a single thread. For example, sometimes only one thread of a process requires a special privilege.


Security in New Objects

When an application creates an object, any values explicitly provided in a security descriptor are assigned to the object. If a security descriptor is not explicitly provided, the system searches for security information in different places, depending on the information required.

This section describes the algorithms for security attribute assignments to newly created objects.

Assignment of Owner

To assign an owner to a new object when a security descriptor is not provided, the system checks the creator's access token for a default value. If no default value is found, the creator's user identifier (from the access token) is assigned as the object's owner. Even when an owner is provided in a security descriptor, the system checks these values in the access token to make sure the specified owner can be assigned ownership of the object.

Assignment of Group

To assign a primary group to a new object when a security descriptor is not provided, the system uses the primary group in the creator's access token.

Assignment of Discretionary ACL

To assign a discretionary access-control list (ACL) to a new object when a security descriptor is not provided, the system checks the parent's discretionary ACL for inheritable access-control entries (ACEs) and creates an ACL from any it finds. If there are no inheritable ACEs, the system checks the creator's security descriptor for a default discretionary ACL. If none is found in the security descriptor, the system looks in the creator's access token. If none of these sources provides a discretionary ACL, the object is created without one, and universal unconditional access to the object is granted.

Assignment of System ACL

To assign a system ACL to a new object when a security descriptor is not provided, the system checks the parent's system ACL for inheritable ACEs and creates an ACL from any it finds. If there are no inheritable ACEs, the system checks the creator's security descriptor for a default system ACL. When a system ACL is provided explicitly or by default in a security descriptor, the creator of the object must have the SE_SECURITY_NAME privilege, although this privilege is not required if the system ACL is acquired by inheritance. If none of these sources provides a system ACL, the object is created without one.


Inheritance

The security attributes of an object can be passed from process to process through the mechanism of handle inheritance. In addition, individual ACEs in an ACL can be inherited by new objects. This section discusses these two inheritance mechanisms.

Handle Inheritance

If a new process inherits a handle, it also inherits the security attributes associated with that handle. A pointer to a SECURITY_ATTRIBUTES structure is used as a parameter in most Win32 kernel and window-management functions that return object handles. The bInheritHandle member of this structure specifies whether the returned handle is inherited when a new process is created. The security attributes of the inherited handle are identical to those of the original handle.

ACE Inheritance

Each ACE in an ACL begins with an ACE_HEADER structure specifying how that ACE is inherited. Among other things, the flags in an ACE_HEADER structure specify whether the ACE is inherited by container objects (directories or registry keys) or by non-container objects, such as files.

ACE Inheritance in Container Objects

This section outlines the rules governing the inheritance of ACEs by container objects.

If the CONTAINER_INHERIT_ACE flag is set in the ACE_HEADER structure of the parent ACE, a copy of the ACE is added to the end of the inherited ACL and the following actions are performed on the inherited ACE:

All inheritance flags in the inherited ACE are cleared.

If the ACE contains an access mask and any generic access flags are set, the generic rights are mapped to the standard and specific rights for the child object type.

If neither the CONTAINER_INHERIT_ACE flag nor the NO_PROPAGATE_INHERIT_ACE flag is set, the OBJECT_INHERIT_ACE and INHERIT_ONLY_ACE flags are set. If both the CONTAINER_INHERIT_ACE and the NO_PROPAGATE_INHERIT_ACE are set, the ACE is added to the end of the inherited ACL.

If neither the NO_PROPAGATE_INHERIT_ACE nor the CONTAINER_INHERIT_ACE flag is set in the ACE_HEADER structure of the parent ACE, a copy of the ACE is added to the end of the inherited ACL and its INHERIT_ONLY_ACE flag is set.

Otherwise, the ACE is not inherited.

ACE Inheritance in Non-container Objects

The following rules govern the inheritance of ACEs in objects other than containers.

If the OBJECT_INHERIT_ACE flag is set in the ACE_HEADER structure of the parent ACE, the ACE is copied to the end of the inherited ACL and:

The INHERIT_ONLY_ACE flag in the inherited ACE is cleared.

The NO_PROPAGATE_INHERIT_ACE, OBJECT_INHERIT_ACE, and CONTAINER_INHERIT_ACE flags in the inherited ACE are cleared.

If the ACE contains an access mask and, if any generic access flags are set, the generic rights are mapped to the standard and specific rights for the child object type.

Otherwise, the ACE is not inherited.

Duplicating Handles

Among cooperating processes, any one process is only as restricted as the least restricted process. For example, a process can call the DuplicateHandle function to duplicate an object handle belonging to a second (source) process into a third (target) process. If the access rights requested for the target process are greater than the rights held by the source process, the system checks the requested access rights against the security context of the process calling DuplicateHandle. If the calling process has the required access rights, the handle is duplicated, and the target process has greater access to the object than the source process.


Audit Generation

C2-level security requirements specify that system administrators must be able to audit security-related events and that access to this audit data must be limited to authorized administrators. The Win32 API provides functions enabling an administrator to monitor security-related events.

The system access-control list (ACL) contains audit access-control entries (ACEs) for an object. An application can use the GetSecurityDescriptorSacl and SetSecurityDescriptorSacl functions to retrieve an existing system ACL or to set a new one. The AddAuditAccessAce function adds an ACE to a system ACL that causes the system to record specified access attempts in a security log. This security log can be read by using the Microsoft Windows Event Viewer (EVENTVWR.EXE), and can be manipulated by using the event-logging functions discussed in Event Logging. For more information about system ACLs, see Access-control Lists.

An application can use the ObjectPrivilegeAuditAlarm function to generate audit and alarm messages whenever a process attempts to complete a privileged operation. The PrivilegedServiceAuditAlarm generates audit and alarm messages whenever a process attempts to perform a privileged system-service operation.

The ObjectCloseAuditAlarm generates audit messages when an object is deleted. The ObjectOpenAuditAlarm function generates audit messages when a process attempts to open or gain access to an object.


Securable Objects

The kernel and window-management systems contain securable objects. This term refers to an object that has a security descriptor.

All named objects are securable. Some unnamed objects, such as unnamed process and thread objects, have security descriptors also.

You can use Win32 functions to query and set the security attributes of securable objects. The following are types of securable objects and the functions an application can use to manipulate their security attributes.

Object type	Functions

Files and directories	GetFileSecurity, SetFileSecurity

Mailslots	GetFileSecurity, SetFileSecurity

Pipes	GetFileSecurity, SetFileSecurity

Kernel objects (processes, threads, access tokens, and file-mapping objects)	SetKernelObjectSecurity, GetKernelObjectSecurity

Window-management objects (window stations, desktops, windows, and menus)	GetUserObjectSecurity, SetUserObjectSecurity

Registry objects	RegGetKeySecurity, RegSetKeySecurity

Service objects	QueryServiceObjectSecurity, SetServiceObjectSecurity

Synchronization objects	SetKernelObjectSecurity, GetKernelObjectSecurity

Private objects (objects private to the creating application)	CreatePrivateObjectSecurity, DestroyPrivateObjectSecurity, GetPrivateObjectSecurity, SetPrivateObjectSecurity

The following sections discuss the security attributes of these types of securable objects.


File and Directory Objects

File and directory objects can be secured only when the New Technology file system (NTFS) is in use.

The access rights for files and directories must be manipulated by using the generic access rights.

For file objects, the handle returned by the CreateFile function has SYNCHRONIZE access and the right to read file attributes, in addition to the access rights specified in the call (GENERIC_READ, GENERIC_WRITE, or both).

GENERIC_READ access for file objects combines STANDARD_RIGHTS_READ and SYNCHRONIZE with rights that allow the process to read data from the file, read file attributes, and read extended attributes.

GENERIC_WRITE access for file objects combines STANDARD_RIGHTS_WRITE and SYNCHRONIZE with rights that allow the process to write data to the file, append data to it, write file attributes, and write extended attributes.

An application cannot use an access-denied ACE to deny only GENERIC_READ or GENERIC_WRITE access to a file. If an application denies GENERIC_WRITE access to a file, SYNCHRONIZE access is implicitly denied. When the CreateFile function is used in an attempt to open the file for read access, the function requests SYNCHRONIZE access and the operation fails. Instead of denying read or write access to a file, an application can explicitly allow the permitted access rights.

For directory objects, the handle returned by the CreateDirectory function has SYNCHRONIZE access and the right to list the contents of the directory.

For more information about files and directories, see Files.


Mailslot Objects

The handle returned by the CreateMailslot function has GENERIC_READ, SYNCHRONIZE, and WRITE_DAC access to the mailslot object.

GENERIC_READ access for a mailslot combines STANDARD_RIGHTS_READ with rights allowing the process to read data from the mailslot, read mailslot attributes, and read extended attributes.

For more information about mailslots, see Mailslots.


Pipe Objects

The security attributes of named pipes differ slightly from those of anonymous pipes.

Named Pipes

The handle returned by the CreateNamedPipe function always has SYNCHRONIZE access. It also has GENERIC_READ, GENERIC_WRITE, or both, depending on the open mode of the pipe. The following are the access rights for each open mode.

Open mode	Access rights

PIPE_ACCESS_DUPLEX	GENERIC_READ, GENERIC_WRITE, and SYNCHRONIZE

PIPE_ACCESS_INBOUND	GENERIC_READ and SYNCHRONIZE

PIPE_ACCESS_OUTBOUND	GENERIC_WRITE  and SYNCHRONIZE

GENERIC_READ access for a named pipe combines STANDARD_RIGHTS_READ access with rights that allow the process to read data from the named pipe and to read named-pipe attributes.

GENERIC_WRITE access for a named pipe combines STANDARD_RIGHTS_WRITE with rights that allow the process to write data to the named pipe and to write named-pipe attributes.

Anonymous Pipes

The handles returned by the CreatePipe function have GENERIC_READ, GENERIC_WRITE, and SYNCHRONIZE access to the anonymous pipe, in addition to the right to write the attributes of the pipe. GENERIC_READ and GENERIC_WRITE access map to the same access rights as for named pipes.

For more information about pipes, see Pipes.


Kernel Objects

The following are the kernel objects for which the system defines special access rights:

Processes

Threads

Access tokens

File mapping

Process Objects

The valid access rights for process objects are STANDARD_RIGHTS_REQUIRED and the rights given in the following table.

Value	Meaning

PROCESS_ALL_ACCESS	Specifies all possible access rights for a process object.

PROCESS_CREATE_PROCESS	Required to create a process.

PROCESS_CREATE_THREAD	Required to create a thread.

PROCESS_DUP_HANDLE	Required to duplicate a handle.

PROCESS_QUERY_INFORMATION	Required to retrieve certain information about a process, such as its priority class.

PROCESS_SET_INFORMATION	Required to set certain information about a process, such as its priority class.

PROCESS_TERMINATE	Required to terminate a process.

PROCESS_VM_OPERATION	Required to perform an operation on the address space of a process.

PROCESS_VM_READ	Required to read memory in a process.

PROCESS_VM_WRITE	Required to write to memory in a process.

SYNCHRONIZE	Required to wait for the process to terminate.

The handle returned by the CreateProcess function has PROCESS_ALL_ACCESS access to the process object.

For more information about processes, see Processes and Threads.

Thread Objects

The valid access rights for thread objects are STANDARD_RIGHTS_REQUIRED and the rights given in the following table.

Value	Meaning

SYNCHRONIZE	Required to wait for the thread to exit.

THREAD_ALL_ACCESS	Specifies all possible access rights for a thread object. A thread created with THREAD_ALL_ACCESS access is created with its execution suspended.

THREAD_DIRECT_IMPERSONATION	Required for a server thread that impersonates a client.

THREAD_GET_CONTEXT	Required to read the context of a thread using GetThreadContext.

THREAD_IMPERSONATE	Required to use a thread's security information directly without calling it by using a communication mechanism that provides impersonation services.

THREAD_QUERY_INFORMATION	Required to read certain information from the thread object.

THREAD_SET_CONTEXT	Required to write the context of a thread.

THREAD_SET_INFORMATION	Required to set certain information in the thread object.

THREAD_SET_THREAD_TOKEN	Required to set the impersonation token for a thread.

THREAD_SUSPEND_RESUME	Required to suspend or resume a thread.

THREAD_TERMINATE	Required to terminate a thread.

The handle returned by the CreateThread function has THREAD_ALL_ACCESS access to the thread object.

For more information about threads, see Processes and Threads.

Access-token Objects

A process or thread cannot wait on an access-token object because the access-token object type does not support the SYNCHRONIZE standard access type.

The access rights defined for access-token objects are STANDARD_RIGHTS_REQUIRED and the rights given in the following table.

Value	Meaning

TOKEN_ADJUST_DEFAULT	Required to adjust default information, such as the owner, primary group, and default ACL in an access token.

TOKEN_ADJUST_GROUPS	Required to adjust the groups in an access token.

TOKEN_ADJUST_PRIVILEGES	Required to adjust the privileges in an access token.

TOKEN_ASSIGN_PRIMARY	Required to attach a primary token to a process. The SE_CREATE_TOKEN_NAME privilege is also required to accomplish this task.

TOKEN_DUPLICATE	Required to duplicate an access token.

TOKEN_EXECUTE	Combines STANDARD_RIGHTS_EXECUTE and TOKEN_IMPERSONATE.

TOKEN_IMPERSONATE	Required to attach an impersonation access token to a process.

TOKEN_QUERY	Required to query an access token.

TOKEN_QUERY_SOURCE	Required to query the source of an access token.

TOKEN_READ	Combines STANDARD_RIGHTS_READ and TOKEN_QUERY.

TOKEN_WRITE	Combines STANDARD_RIGHTS_WRITE, TOKEN_ADJUST_PRIVILEGES, TOKEN_ADJUST_GROUPS, and TOKEN_ADJUST_DEFAULT.

The TOKEN_ALL_ACCESS access right combines all possible access rights for a token.

The access rights for tokens are typically specified in calls to the OpenProcessToken and OpenThreadToken functions.

File Mapping Objects

A process or thread cannot wait on an access-token object because the access-token object because the access-token object type does not support the SYNCHRONIZE standard access type.

The access rights defined for file mapping objects are STANDARD_RIGHTS_REQUIRED and the rights given in the following table.

Value	Meaning

FILE_MAP_READ	Read access to the file-mapping object is requested. This allows a readable view of the file to be mapped.

FILE_MAP_WRITE	Write access to the file mapping object is requested. This allows a writable view of the file to be mapped. If the file mapping access rights do not include PAGE_READWRITE, this access type does not allow writing the mapped file.

SECTION_EXTEND_SIZE	Required to extend the size of a file mapping object.

SECTION_MAP_EXECUTE	Required to complete an operation in a file mapping object.

SECTION_MAP_READ	Equivalent to FILE_MAP_READ.

SECTION_MAP_WRITE	Equivalent to FILE_MAP_WRITE.

SECTION_QUERY	Required to query a file mapping object.

If the call to the CreateFileMapping function specifies the PAGE_READWRITE protection flag, the handle to the file mapping object has SECTION_QUERY | SECTION_MAP_READ | SECTION_MAP_WRITE access. If the call to CreateFileMapping specifies PAGE_READONLY, the handle of the file mapping object has SECTION_QUERY | SECTION_MAP_READ access.

The FILE_MAP_ALL_ACCESS access right specifies all possible access rights for the file mapping object. The SECTION_ALL_ACCESS access right is equivalent to it.

For more information about file-mapping objects, see File Mapping.


Window-management Objects

The following are the securable window-management objects.

Securable Object	Description

Window station	A combination of the screen, keyboard, and mouse. It provides the first level of security for a work station and is the source of inheritable security for other user objects.

Desktop	The top-level window for an individual work station. This object is a subobject of a window-station object, from which it inherits security. The desktop object contains window and menu objects.

Window	A subobject of a desktop object, from which it inherits security.

Menu	A subobject of a desktop object, from which it inherits security.

Window-station Objects

The following are the window-station access rights and their meanings.

Constant	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 function. Window stations can be shared by users and this access type can prevent other users of a window station from logging off the window station owner.

WINSTA_READATTRIBUTES	Required to read the attributes of a window station object. This attribute includes color settings and other global window station properties.

WINSTA_READSCREEN	Required to access screen contents.

WINSTA_WRITEATTRIBUTES	Required to modify the attributes of a window station object. The attributes include color settings and other global window-station properties.

The following are the generic mappings for a window-station object.

Value	Maps to

GENERIC_READ	STANDARD_RIGHTS_READ, WINSTA_ENUMDESKTOPS, WINSTA_ENUMERATE, WINSTA_READATTRIBUTES, and WINSTA_READSCREEN

GENERIC_WRITE	STANDARD_RIGHTS_WRITE, WINSTA_ACCESSCLIPBOARD, WINSTA_CREATEDESKTOP, and WINSTA_WRITEATTRIBUTES

GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, WINSTA_ACCESSGLOBALATOMS, and WINSTA_EXITWINDOWS

GENERIC_ALL	STANDARD_RIGHTS_REQUIRED, WINSTA_ACCESSCLIPBOARD, WINSTA_ACCESSGLOBALATOMS, WINSTA_CREATEDESKTOP, WINSTA_ENUMDESKTOPS, WINSTA_ENUMERATE, WINSTA_EXITWINDOWS, WINSTA_READATTRIBUTES, WINSTA_READSCREEN, and WINSTA_WRITEATTRIBUTES

An application can call the GetProcessWindowStation function to retrieve a handle of the window station. The security attributes of the window station can be retrieved and set by using this handle in calls to the GetUserObjectSecurity and SetUserObjectSecurity functions.

Desktop Objects

A new desktop inherits its security descriptor from its parent window station.

The following are the desktop access rights and their meanings.

Constant	Description

DESKTOP_CREATEMENU	Required to create a menu associated with 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 a desktop.

DESKTOP_JOURNALRECORD	Required to perform journal recording on a desktop.

The following are the generic mappings for a desktop object.

Value	Maps to

GENERIC_READ	DESKTOP_ENUMERATE and STANDARD_RIGHTS_READ

GENERIC_WRITE	DESKTOP_CREATEMENU, DESKTOP_CREATEWINDOW, DESKTOP_HOOKCONTROL, DESKTOP_JOURNALPLAYBACK, DESKTOP_JOURNALRECORD, and STANDARD_RIGHTS_WRITE

GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE

GENERIC_ALL	DESKTOP_CREATEMENU, DESKTOP_CREATEWINDOW, DESKTOP_ENUMERATE, DESKTOP_HOOKCONTROL, DESKTOP_JOURNALPLAYBACK, DESKTOP_JOURNALRECORD, and STANDARD_RIGHTS_REQUIRED

An application can call the GetThreadDesktop function to retrieve a handle of the desktop for a given thread. The desktop's security attributes can be retrieved and set by using this handle in calls to GetUserObjectSecurity and SetUserObjectSecurity.

Window Objects

A new window inherits its security descriptor from its parent desktop and is implicitly opened during its creation.

The following are the generic mappings for a window object.

Value	Maps to

GENERIC_READ	STANDARD_RIGHTS_READ

GENERIC_WRITE	STANDARD_RIGHTS_WRITE

GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE

GENERIC_ALL	STANDARD_RIGHTS_REQUIRED

For more information about window objects, see Windows.

Menu Objects

A new menu inherits its security descriptor from its parent desktop and is implicitly opened during during the call to the CreateMenu function.

The following are the generic mappings for a menu object.

Value	Maps to

GENERIC_READ	STANDARD_RIGHTS_READ

GENERIC_WRITE	STANDARD_RIGHTS_WRITE

GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE

GENERIC_ALL	STANDARD_RIGHTS_REQUIRED

For more information about menu objects, see Menus.


Registry Key Objects

The following are the registry-key access rights and their meanings.

Value	Meaning

KEY_ALL_ACCESS	Combines the STANDARD_RIGHTS_REQUIRED, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, and KEY_CREATE_LINK values.

KEY_CREATE_LINK	Required to create a link to a registry-key object.

KEY_CREATE_SUB_KEY	Required to create a subkey of a registry-key object.

KEY_ENUMERATE_SUB_KEYS	Required to enumerate the subkeys of a registry-key object.

KEY_EXECUTE	Equivalent to KEY_READ.

KEY_NOTIFY	Required to request change notifications for a registry key or for subkeys of a registry key.

KEY_QUERY_VALUE	Required 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	Required 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.

For more information about registry objects, see Registry and Initialization Files.


Service Objects

The access rights and generic mappings for service-control manager objects and service objects are given in the reference materials for the OpenService and OpenSCManager functions. For information about service objects, see Services.


Synchronization Objects

There are three kinds of securable synchronization objects: semaphores, events, and mutexes. The fourth type of synchronization object is critical sections. Because they are per-process objects and not kernel objects, they are not securable.

Semaphore Objects

The valid access rights for semaphore objects are STANDARD_RIGHTS_REQUIRED and the rights given in the following table.

Value	Meaning

SEMAPHORE_ALL_ACCESS	Specifies all possible access rights for a semaphore object.

SEMAPHORE_MODIFY_STATE	Specifies modify state (release) access.

SYNCHRONIZE	Specifies synchronization (wait) access.

The handle returned by the CreateSemaphore function has SEMAPHORE_ALL_ACCESS access to the semaphore object.

Event Objects

The valid access rights for event objects are STANDARD_RIGHTS_REQUIRED and the rights given in the following table.

Value	Meaning

EVENT_ALL_ACCESS	Specifies all possible access rights for an event object.

EVENT_MODIFY_STATE	Specifies modify state (release) access.

SYNCHRONIZE	Specifies synchronization (wait or release) access.

The handle returned by the CreateEvent function has EVENT_ALL_ACCESS access to the semaphore object.

Mutex Objects

The valid access rights for mutex objects are STANDARD_RIGHTS_REQUIRED and the rights given in the following table.

Value	Meaning

MUTEX_ALL_ACCESS	Specifies all possible access rights for a mutex object.

MUTEX_MODIFY_STATE	Specifies modify state (release) access.

SYNCHRONIZE	Specifies synchronization (wait or release) access.

The handle returned by the CreateMutex function has MUTEX_ALL_ACCESS access to the mutex object.


Denying All Access

The following example demonstrates adding an empty discretionary access-control list (ACL) to a file's security descriptor. An empty ACL implicitly denies all access to the file.

PSECURITY_DESCRIPTOR pSD;

PACL pACL;

DWORD cbACL = 1024;

/* Initialize a security descriptor. */

pSD = (PSECURITY_DESCRIPTOR) LocalAlloc(LPTR,

    SECURITY_DESCRIPTOR_MIN_LENGTH);   /* defined in WINNT.H */

if (pSD == NULL) {

    ErrorHandler("LocalAlloc");

    return FALSE;

}

if (!InitializeSecurityDescriptor(pSD,

        SECURITY_DESCRIPTOR_REVISION)) { /* defined in WINNT.H */

    ErrorHandler("InitializeSecurityDescriptor");

    goto Cleanup;

}

/* Initialize a DACL. */

pACL = (PACL) LocalAlloc(LPTR, cbACL);

if (pACL == NULL) {

    ErrorHandler("LocalAlloc");

    goto Cleanup;

}

if (!InitializeAcl(pACL, cbACL, ACL_REVISION2)) {

    ErrorHandler("InitializeAcl");

    goto Cleanup;

}

/* Add an empty ACL to the SD to deny access. */

if (!SetSecurityDescriptorDacl(pSD,

        TRUE,     /* fDaclPresent flag  */

        pACL,

        FALSE)) { /* not a default DACL */

    ErrorHandler("SetSecurityDescriptorDacl");

    goto Cleanup;

}

/* Use the new SD as the file's security info. */

if (!SetFileSecurity(lpszTestFile,

        DACL_SECURITY_INFORMATION,

        pSD)) {

    ErrorHandler("SetFileSecurity");

    goto Cleanup;

}

Cleanup:

    if(pSD != NULL)

        LocalFree((HLOCAL) pSD);

    if(pACL != NULL)

        LocalFree((HLOCAL) pACL);


Allowing Access

The following example demonstrates adding a NULL discretionary ACL to a file's security descriptor. A NULL ACL implicitly allows all access to the file.

Note: It is fine to write code like this that builds security descriptors from scratch. It is, however, a good practice for people who write code that builds or manipulates security descriptors to first write code that explores the default security descriptors that Windows NT places on objects. For example, if Windows NT by default includes in a DACL an ACE granting the Local Logon SID certain access, it's good to know that, so that a decision not to grant any access to the Local Logon SID would be a conscious decision

PSECURITY_DESCRIPTOR pSD;

/* Initialize a security descriptor. */

pSD = (PSECURITY_DESCRIPTOR) LocalAlloc(LPTR,

    SECURITY_DESCRIPTOR_MIN_LENGTH);   /* defined in WINNT.H */

if (pSD == NULL) {

    ErrorHandler("LocalAlloc");

    return FALSE;

}

if (!InitializeSecurityDescriptor(pSD,

        SECURITY_DESCRIPTOR_REVISION)) { /* defined in WINNT.H */

    ErrorHandler("InitializeSecurityDescriptor");

    goto Cleanup;

}

/* Add a NULL disc. ACL to the security descriptor. */

if (!SetSecurityDescriptorDacl(pSD,

        TRUE,     /* specifying a disc. ACL  */

        (PACL) NULL,

        FALSE)) { /* not a default disc. ACL */

    ErrorHandler("SetSecurityDescriptorDacl");

    goto Cleanup;

}

/* Add the security descriptor to the file. */

if (!SetFileSecurity(lpszTestFile,

        DACL_SECURITY_INFORMATION,

        pSD)) {

    ErrorHandler("SetFileSecurity");

    goto Cleanup;

}

Cleanup:

    if(pSD != NULL)

        LocalFree((HLOCAL) pSD);

Rather than allowing all access by using a NULL ACL, applications generally allow access to an object by adding access-control entries (ACEs) to an ACL. The following example demonstrates finding a security identifier (SID) for a particular account and adding an access-allowed ACE for that account.

PSECURITY_DESCRIPTOR pSD;

PACL pACLNew;

DWORD cbACL = 1024;

PSID pSID;

DWORD cbSID = 1024;

LPSTR lpszAccount = "UserABC";

LPSTR lpszDomain;

DWORD cchDomainName = 80;

PSID_NAME_USE psnuType;

/* Initialize a new security descriptor. */

pSD = (PSECURITY_DESCRIPTOR) LocalAlloc(LPTR,

    SECURITY_DESCRIPTOR_MIN_LENGTH);  /* defined in WINNT.H  */

if (pSD == NULL) {

    ErrorHandler("LocalAlloc");

    return FALSE;

}

if (!InitializeSecurityDescriptor(pSD,

        SECURITY_DESCRIPTOR_REVISION)) {

    ErrorHandler("InitializeSecurityDescriptor");

    goto Cleanup;

}

/* Initialize a new ACL. */

pACLNew = (PACL) LocalAlloc(LPTR, cbACL);

if (pACLNew == NULL) {

    ErrorHandler("LocalAlloc");

    goto Cleanup;

}

if (!InitializeAcl(pACLNew, cbACL, ACL_REVISION2)) {

    ErrorHandler("InitializeAcl");

    goto Cleanup;

}

/* Retrieve the SID for UserABC. */

pSID = (PSID) LocalAlloc(LPTR, cbSID);

psnuType = (PSID_NAME_USE) LocalAlloc(LPTR, 1024);

lpszDomain = (LPSTR) LocalAlloc(LPTR, cchDomainName);

if (pSID == NULL || psnuType == NULL || lpszDomain == NULL) {

    ErrorHandler("LocalAlloc");

    goto Cleanup;

}

if (!LookupAccountName((LPSTR) NULL, /* local name */

        lpszAccount,

        pSID,

        &cbSID,

        lpszDomain,

        &cchDomainName,

        psnuType)) {

    ErrorHandler("LookupAccountName");

    goto Cleanup;

}

/* Allow read but not write access to the file. */

if (!AddAccessAllowedAce(pACLNew,

        ACL_REVISION2,

        GENERIC_READ,

        pSID)) {

    ErrorHandler("AddAccessAllowedAce");

    goto Cleanup;

}

/* Add a new ACL to the security descriptor. */

if (!SetSecurityDescriptorDacl(pSD,

        TRUE,              /* fDaclPresent flag  */

        pACLNew,

        FALSE)) {          /* not a default disc. ACL */

    ErrorHandler("SetSecurityDescriptorDacl");

    goto Cleanup;

}

/* Apply the new security descriptor to the file. */

if (!SetFileSecurity("d:\\ntfs_sample_file",

        DACL_SECURITY_INFORMATION,

        pSD)) {

    ErrorHandler("SetFileSecurity");

    goto Cleanup;

}

Cleanup:

    FreeSid(pSID);

    if(pSD != NULL)

        LocalFree((HLOCAL) pSD);

    if(pACLNew != NULL)

        LocalFree((HLOCAL) pACLNew);

    if(psnuType != NULL)

        LocalFree((HLOCAL) psnuType);

    if(lpszDomain != NULL)

        LocalFree((HLOCAL) lpszDomain);


Setting Privileges

The following example removes the discretionary ACL from a file. If necessary, ownership of the file is given to the Administrator account. If required, the SE_TAKE_OWNERSHIP_NAME privilege is enabled for the account.

LPSTR lpszOwnFile = "d:\\ntfs_sample_file";

PSID pSIDAliasAdmins = NULL;

static SID_IDENTIFIER_AUTHORITY

    siaNTAuthority = SECURITY_NT_AUTHORITY;

BOOL FAR PASCAL TakeOwnership()

{

    SECURITY_DESCRIPTOR sd;

    /*

     * Initialize a security descriptor and assign it a NULL

     * discretionary ACL to allow unrestricted access.

     * Assign the security descriptor to a file.

     */

    if (!InitializeSecurityDescriptor(&sd,

            SECURITY_DESCRIPTOR_REVISION)) {

        ErrorHandler("InitializeSecurityDescriptor");

        return FALSE;

    }

    if (!SetSecurityDescriptorDacl(&sd,

            TRUE,

            (PACL) NULL,

            FALSE)) {

        ErrorHandler("SetSecurityDescriptorDacl");

        return FALSE;

    }

    if (SetFileSecurity(lpszOwnFile,

            DACL_SECURITY_INFORMATION,

            &sd))

        return TRUE;

    else

        ErrorHandler("SetFileSecurity1");

    /*

     * If the preceding call to SetFileSecurity fails, create

     * an Administrator SID and use it to set the owner of

     * the security descriptor.

     */

    if (!AllocateAndInitializeSid(&siaNTAuthority,

            2,                            /* subauthority count  */

            SECURITY_BUILTIN_DOMAIN_RID,  /* first subauthority  */

            DOMAIN_ALIAS_RID_ADMINS,      /* second subauthority */

            0, 0, 0, 0, 0, 0,

            &pSIDAliasAdmins)) {

        ErrorHandler("AllocateAndInitializeSid");

        return FALSE;

    }

    if (!SetSecurityDescriptorOwner(&sd,

            pSIDAliasAdmins,

            FALSE)) {

        ErrorHandler("SetSecurityDescriptorOwner");

        FreeSid(pSIDAliasAdmins);

        return FALSE;

    }

    /*

     * If the following call to SetFileSecurity fails, enable

     * SE_TAKE_OWNERSHIP_NAME in the access token for the

     * current process and try again.

     */

    if (!SetFileSecurity(lpszOwnFile,

            OWNER_SECURITY_INFORMATION,

            &sd)) {

        ErrorHandler("SetFileSecurity2");

        if (!AssertTakeOwnership(TRUE)) {  /* locally defined    */

            MessageBox(NULL, "Must be logged on as Administrator",

                "AssertTakeOwnership", MB_OK);

            FreeSid(pSIDAliasAdmins);

            return FALSE;

        }

        if (!SetFileSecurity(lpszOwnFile,

                OWNER_SECURITY_INFORMATION,

                &sd)) {

            MessageBox(NULL, "Must be logged on as Administrator",

                "SetFileSecurity", MB_OK);

            FreeSid(pSIDAliasAdmins);

            return FALSE;

        }

    }

    /*

     * The Administrator is now the owner of the file.

     * Try again to assign a NULL ACL.

     */

    if (SetFileSecurity(lpszOwnFile,

            DACL_SECURITY_INFORMATION,

            &sd)) {

        MessageBox(NULL, "Added NULL DACL; protection removed",

            "SetFileSecurity", MB_OK);

        AssertTakeOwnership(FALSE);

        return TRUE;

    }

    else {

        AssertTakeOwnership(FALSE);

        ErrorHandler("SetFileSecurity3");

        return FALSE;

    }

}

BOOL FAR PASCAL AssertTakeOwnership(BOOL fEnable)

{

    HANDLE hToken;

    LUID TakeOwnershipValue;

    TOKEN_PRIVILEGES tkp;

    /* Retrieve a handle of the access token. */

    if (!OpenProcessToken(GetCurrentProcess(),

            TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY,

            &hToken)) {

        ErrorHandler("OpenProcessToken");

        return FALSE;

    }

    /*

     * Enable the SE_TAKE_OWNERSHIP_NAME privilege or disable

     * all privileges, depending on the fEnable flag.

     */

    if(fEnable) {

        if (!LookupPrivilegeValue((LPSTR) NULL,

                SE_TAKE_OWNERSHIP_NAME,

                &TakeOwnershipValue)) {

            ErrorHandler("LookupPrivilegeValue");

            return FALSE;

        }

        tkp.PrivilegeCount = 1;

        tkp.Privileges[0].Luid = TakeOwnershipValue;

        tkp.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;

        AdjustTokenPrivileges(hToken,

            FALSE,

            &tkp,

            sizeof(TOKEN_PRIVILEGES),

            (PTOKEN_PRIVILEGES) NULL,

            (PDWORD) NULL);

        /* The return value of AdjustTokenPrivileges be texted. */

        if (GetLastError() != ERROR_SUCCESS) {

            ErrorHandler("AdjustTokenPrivileges");

            return FALSE;

        }

    }

    else {

        AdjustTokenPrivileges(hToken,

            TRUE,                  /* disable all privileges */

            (PTOKEN_PRIVILEGES) NULL,

            (DWORD) 0,

            (PTOKEN_PRIVILEGES) NULL,

            (PDWORD) NULL);

        /* The return value of AdjustTokenPrivileges cannot be tested. */

        if (GetLastError() != ERROR_SUCCESS) {

            ErrorHandler("AdjustTokenPrivileges");

            return FALSE;

        }

    }

    return TRUE;

}


Security Editor

Both File Manager and the Microsoft Windows NT Registry Editor (REGEDT32.EXE) include a security editor that allows a user with the appropriate privileges and access rights to change the security attributes of files and registry keys. This security editor imposes guidelines on the form of the security information. Applications that modify the security of files, directories, or registry keys can follow these guidelines so the security editor will function correctly after the modifications.

The security editor accepts discretionary ACLs having either zero or more ACCESS_DENIED_ACE access-control entries (ACEs) or zero or more ACCESS_ALLOWED_ACE ACEs. The two ACE types cannot be mixed in a discretionary ACL. Neither does the security editor accept ACCESS_DENIED_ACE ACEs that deny only partial access. For example, it would reject an ACE that denies only read access to a file.

The security editor also imposes a requirement on inheritance flags. These flags are ignored for noncontainer objects, such as files, but are important for container objects, such as directories and registry keys. For container objects that support permissions on objects in the container, make sure that each security identifier (SID) has an ACE inherited by objects and an ACE inherited by containers. Accordingly, the discretionary ACL should contain ACEs in which the AceFlags member of the ACE_HEADER structure contains the OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE flags. Sometimes these flags can be combined in a single ACE. For example, a discretionary ACL that grants read access to a directory can contain a CONTAINER_INHERIT_ACE ACE that grants GENERIC_READ access to the user or group as well as an ACE with the OBJECT_INHERIT_ACE and INHERIT_ONLY_ACE flags that also grants GENERIC_READ access. In this case, the required flags could be combined into an ACE that grants GENERIC_READ access and combines the CONTAINER_INHERIT_ACE and OBJECT_INHERIT_ACE flags.

The same rules for inheritance flags apply to system ACLs. The security editor does not support the SYSTEM_ALARM_ACE type and will not edit a system ACL containing one. As noted earlier, this ACE type is not supported by the current version of Windows NT.


Designing a Protected Server

The designer of a server application that assigns security to private object types must make many decisions about the design of the security interface, such as those in the following list:

Define object.

Determine the types of objects and the access types required, including whether to support SYNCHRONIZE.

Determine whether an object is a container or noncontainer, as well as the appropriate inheritance flags. For more information about container objects, see Networks.

Define appropriate access types and generic mappings.

Determine impersonation characteristics.

Develop security descriptor for the initial object and for new objects assembled from the parent's security descriptor and the client's access token.

Consider string- versus handle-based object-manipulation functions.

Resolve potential conflicts in access rights. For example, decide what is to be done if an administrator and a user both have delete access to an object.

For example, the designer of a protected print server might choose to define a server object, a printer object, and a document object. The three access rights in the following table are likely to be required:

Access right	Description

Administrate	Allows the holder to add objects to and delete them from another object. This right applies to the server, the printers, and the documents.

Enumerate	Allows the holder to list a container object's contents. This right applies to the server and to the printers.

Use	Allow the holder to add items to a print queue. This right applies to the printers.


Functions

Following are the functions used to control security.

AccessCheck

AccessCheckAndAuditAlarm

AddAccessAllowedAce

AddAccessDeniedAce

AddAce

AddAuditAccessAce

AdjustTokenGroups

AdjustTokenPrivileges

AllocateAndInitializeSid

AllocateLocallyUniqueId

AreAllAccessesGranted

AreAnyAccessesGranted

CopySid

CreatePrivateObjectSecurity

DdeImpersonateClient

DeleteAce

DestroyPrivateObjectSecurity

DuplicateToken

EqualPrefixSid

EqualSid

FindFirstFreeAce

FreeSid

GetAce

GetAclInformation

GetFileSecurity

GetKernelObjectSecurity

GetLengthSid

GetPrivateObjectSecurity

GetProcessWindowStation

GetSecurityDescriptorControl

GetSecurityDescriptorDacl

GetSecurityDescriptorGroup

GetSecurityDescriptorLength

GetSecurityDescriptorOwner

GetSecurityDescriptorSacl

GetSidIdentifierAuthority

GetSidLengthRequired

GetSidSubAuthority

GetSidSubAuthorityCount

GetThreadDesktop

GetTokenInformation

GetUserObjectSecurity

ImpersonateNamedPipeClient

ImpersonateSelf

InitializeAcl

InitializeSecurityDescriptor

InitializeSid

IsValidAcl

IsValidSecurityDescriptor

IsValidSid

LookupAccountName

LookupAccountSid

LookupPrivilegeDisplayName

LookupPrivilegeName

LookupPrivilegeValue

MakeAbsoluteSD

MakeSelfRelativeSD

MapGenericMask

ObjectCloseAuditAlarm

ObjectOpenAuditAlarm

ObjectPrivilegeAuditAlarm

OpenProcessToken

OpenThreadToken

PrivilegeCheck

PrivilegedServiceAuditAlarm

RevertToSelf

SetAclInformation

SetFileSecurity

SetKernelObjectSecurity

SetPrivateObjectSecurity

SetSecurityDescriptorDacl

SetSecurityDescriptorGroup

SetSecurityDescriptorOwner

SetSecurityDescriptorSacl

SetTokenInformation

SetUserObjectSecurity


Dynamic-Link Libraries Overview

About Dynamic-Link Libraries

In Microsoft Windows, dynamic linking provides a way for a process to call a function that is not part of its executable code. The executable code for the function is located in a dynamic-link library (DLL), containing one or more functions that are compiled, linked, and stored separately from the processes using them. The Microsoft Win32 application program interface (API) is implemented as a set of dynamic-link libraries, so any process using the Win32 API uses dynamic linking.

The following topics discuss Win32 dynamic link libraries:

Terms

Advantages of Dynamic Linking

DLL Creation

The DLL Entrypoint Function

The Module Definition File

Load-Time Dynamic Linking

Run-Time Dynamic Linking

DLL Data

Using Dynamic Link Libraries

Creating a Simple dynamic-link library

Using Load-time Dynamic Linking

Using Run-time Dynamic Linking

Using Shared Memory in a DLL

Using Thread Local Storage in a DLL

Functions

Dynamic linking allows an executable module (either a .DLL or .EXE file) to include only the information needed at run time to locate the executable code for a DLL function. This differs from the more familiar static linking, which requires a copy of a library function's executable code in the executable module of each application using it.

There are two methods for calling a function in a DLL:

Load-time dynamic linking occurs when an application's code makes an explicit call to a DLL function. This requires that the executable module of the application be built by linking with the DLL's import library, which supplies the information needed to locate the DLL function when the application starts. For more information, see Load-Time Dynamic Linking.

Run-time dynamic linking occurs when a program uses the LoadLibrary and GetProcAddress functions to get the starting address of a DLL function. This eliminates the need to link with an import library. For more information, see Run-Time Dynamic Linking.

A DLL attaches to a process when the process starts or when one of it threads calls the LoadLibrary function. When a DLL attaches to a process, the operating system maps the DLL module into the address space of the process, making the DLL's executable code available to the process. When a DLL detaches from a process at process termination or as a result of a call to the FreeLibrary function, the DLL module is unmapped from the address space of the process.

Like any other function, a DLL function is executed in the context of the thread (and the thread's process) that calls it. Therefore, the following conditions apply:

The threads of the process that called the DLL can use handles opened by a DLL function. Similarly, handles opened by any thread of the calling process can be used in the DLL function.

The DLL uses the user stack of the calling thread and the address space of the calling process.

Memory allocated by the DLL is in the address space of the calling process.

The threads of the process that called the DLL can read from or write to the globally declared variables in the DLL.


Advantages of Dynamic Linking

Dynamic linking has the following advantages:

Many processes can use a single DLL simultaneously, sharing a single copy of the DLL in memory. This saves memory space and reduces swapping.

You can change the functions in a DLL without recompiling or relinking the applications that use them, as long as the functions' arguments and return values do not change. This differs from statically linked object code in which you must relink the application to update it when the functions change.

You can use a DLL for after-market support. For example, a display driver DLL can be modified to support a display that was not available when the application was shipped.

Programs written in different programming languages can call the same DLL function, as long as the programs follow the function's calling convention. The programs and the DLL function must be compatible in the order the function expects its arguments to be pushed onto the stack, whether the function or the application is responsible for cleaning up the stack, and whether any arguments are passed in registers.

A potential disadvantage to using DLLs is that the application is not self-contained; it depends on the existence of a separate DLL module. A process using load-time dynamic linking is terminated by the operating system if the DLL is not found at process startup. A process using run-time dynamic linking is not terminated in this situation, but the functionality provided by the DLL is not available to the program.


Dynamic-Link Library Creation

To create a DLL, first create one or more source code files (.C) and a module definition file (.DEF). The source code file contains the exported functions for the DLL. The .DEF file lists these functions and defines other attributes of the DLL.

The compiler uses the .C file to create an object code file (.OBJ). The library manager creates an export file (.EXP) and an import library file (.LIB) from the .DEF file.

Finally, the linker uses the .OBJ, .EXP, and .LIB files to build the executable files for the DLL. The .OBJ and .EXP files provide the information the linker needs to build the .DLL file. The .LIB file contains the information the linker needs to resolve the external references to DLL functions, so that a program can locate the specified DLL at run time. The .LIB file enables the linker to build any executable module (.EXE or .DLL) that calls a function in the DLL. For more information about .DEF files, see The Module Definition File.

Note that the information in this section is based on using Win32 software development tools. Refer to the documentation provided with the development tools you are using for more detailed information about creating DLLs.


The DLL Entrypoint Function

A DllEntryPoint function is an optional DLL function that the operating system calls to perform user-defined operations. DllEntryPoint is not a typical function, but is a reference to a function specified in the linker command line. A DLL is not required to have an entrypoint function, but it can be useful for initializing and cleaning up processes and threads. The name of a DLL's entrypoint function is specified by the hyphen entry switch of the linker. For example, the following command line specifies LibMain as the entrypoint function of MYDLL.DLL:

link -entry:LibMain -out:mydll.dll mydll.exp mydll.obj $(mylibs)

If an entrypoint function is specified, the operating system causes it to be called whenever any of the following events occurs:

The DLL attaches to a process. For processes using load-time dynamic linking, this occurs during initialization. For processes using run-time linking, the DLL attaches and the entrypoint function is called before LoadLibrary returns.

The DLL detaches from a process. This occurs when the process terminates or when the DLL is unloaded by a call to the FreeLibrary function. If the process terminates as a result of the TerminateProcess or the TerminateThread function, the system does not call the entrypoint function.

The DLL attaches to a thread. This occurs whenever a new thread is created in a process to which a DLL is attached.

The DLL detaches from a thread. This occurs whenever a thread of an attached process terminates, except as a result of the TerminateThread or the TerminateProcess function. When a DLL detaches from a process, the entrypoint function is called only once for the entire process, rather than once for each existing thread of the process.

The system causes the entrypoint function to be called, but it is called in the context of a process or thread attaching to or detaching from the DLL. This allows a DLL to use its entrypoint function for allocating memory in the address space of the process or to open handles accessible to the process. When called to attach a new thread, the entrypoint function can allocate memory for thread local storage (TLS) that is private to the new thread.

When a DLL's entrypoint function is called for process attachment, it returns TRUE to indicate success. For processes using load-time linking, a return value of FALSE causes the process initialization to fail and the process terminates. For processes using run-time linking, a return value of FALSE causes the LoadLibrary function to return NULL, indicating failure. The return value of the entrypoint function is disregarded when it is called for any other reasons, such as process detach, thread attach, or thread detach.


The Module Definition File

The Module-Definition File

A module definition (.DEF) file is a text file containing one or more module statements that describe various attributes of a dynamic-link library. The descriptions and examples in this section are based on the keywords and syntax used by the Win32 software development tools. Refer to the documentation provided with your development tools for complete documentation of module definition files.

A DLL requires a module-definition file to create an import library (.LIB) file and an export (.EXP) file. The linker uses the import library to build any executable module that uses the DLL; it also uses the export file to build the .DLL file.

A DLL's module definition file must include a LIBRARY statement and an EXPORTS statement. The LIBRARY statement identifies the module definition file as belonging to a DLL and must be the first statement in the file. The name specified in the LIBRARY statement identifies the library in the DLL's import library. The EXPORTS statement lists the names and, optionally, the ordinal values of the functions exported by the DLL. When ordinal values are specified, they must be in the range 1 through N, where N is the number of functions exported by the DLL.

The following is a DLL's module definition file that exports three functions and associates an ordinal value with each function.

LIBRARY mydll

EXPORTS

    Func_A @1

    Func_B @2

    Func_C @3

The module definition file can contain additional statements specifying other attributes of a DLL. For example, the SECTIONS statements can change the default scope of global and static variables. The following SECTIONS statement makes the DLL's initialized data shared, while the uninitialized variables are not.

SECTIONS

    .data READ WRITE SHARED    ; share initialized variables


Load-Time Dynamic Linking

Load-time dynamic linking occurs when an application's code explicitly calls a DLL function. When the source code is compiled or assembled, the DLL function call generates an external function reference in the object code. To resolve this external reference, the application must be linked with the import library for the DLL.

Finding an external function in an import library informs the linker that the code for that function is in a dynamic-link library. To resolve external references to dynamic-link libraries, the linker simply adds information to the executable file that tells the system where to find the DLL code when the process starts up.

When the system starts a program that contains dynamically linked references, it uses the information in the program's executable file to locate the required DLLs. The system first searches the set of pre-installed DLLs, such as the performance library, (KERNEL32.DLL) and the security library, (USER32.DLL). The system then searches for the DLLs by using the following search path:

1	The directory where the executable module for the current process is located.

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.

The LIBPATH environment variable is not used.

If it cannot locate a specified DLL, the system terminates the process and displays a dialog box that reports the error. Otherwise, the system maps the DLL modules into the process's address space.

If any of the DLLs has a DllEntryPoint function, the operating system calls the function. DllEntryPoint specifies a code that indicates the DLL is attaching to the process. If the entrypoint function does not return TRUE, the system terminates the process and reports the error. For more information about the entrypoint function, see The DLL Entrypoint Function.

Finally, the system modifies the executable code of the process to provide the starting addresses for the DLL functions.

Like the rest of a program's code, DLL code is mapped into the address space of the process when the process starts up and loaded into memory only when needed. As a result, the PRELOAD or LOADONCALL code attributes used by module-definition files to control loading in previous versions of Windows have no meaning in Windows NT.


Run-Time Dynamic Linking

Run-time dynamic linking occurs when the process calls the LoadLibrary function to specify the name of a DLL and the GetProcAddress function to get the starting address of any function in the DLL. Run-time dynamic linking eliminates the need to link the process with an import library the process does not explicitly call the DLL's functions, so it does not generate the external references.

If the call to LoadLibrary specifies a DLL module already mapped into the address space of the calling process, LoadLibrary simply returns a handle of the DLL and increments the module's reference count. Otherwise, LoadLibrary attempts to locate the DLL on the same search path used for load-time dynamic linking (see Load-Time Dynamic Linking). If the search succeeds, the system maps the DLL module into the address space of the process. If the DLL has a DllEntryPoint function, the operating system calls the function in the context of the thread that called LoadLibrary. The entrypoint function is not called if the DLL is already attached to the process due to load-time linking to a previous call to LoadLibrary. This occurs when no corresponding call to the FreeLibrary function has been made.

If the system cannot find the DLL or if the entrypoint function returns FALSE, LoadLibrary returns NULL. If LoadLibrary succeeds, it returns a handle of the DLL module. The process can use this handle to identify the DLL in a call to the GetProcAddress or FreeLibrary functions.

The GetModuleHandle function also returns a handle used in GetProcAddress or FreeLibrary. GetModuleHandle succeeds only if the DLL module is already mapped into the address space of the process by load-time linking or by a previous call to LoadLibrary. Unlike LoadLibrary, GetModuleHandle does not increment the module's reference count. The GetModuleFileName function retrieves the full path of the module associated with a handle returned by GetModuleHandle or LoadLibrary.

The process can use GetProcAddress to get the starting handle returned by either LoadLibrary or address of a function in the DLL using a DLL module handle returned by either LoadLibrary or GetModuleHandle. The function is specified by using its name or ordinal value as listed in the EXPORTS statement of the DLL's module definition file.

When the DLL module is no longer needed, the process can call the FreeLibrary function. This decrements the module's reference count and unmaps it from the address space of the process if the reference count is zero.

Run-time dynamic linking enables the process to continue executing even if a DLL is not available. This allows the process to use an alternative method to accomplish its objective. For example, if a process is unable to locate one DLL, it can try to use another, or it can notify the user of an error. If the user can provide the full path of the missing DLL, the process can use this information to load the library even though it is not in the normal search path. This contrasts with load-time linking in which the operating system simply terminates the process if it cannot find the DLL.

The developer need not know the names of either the DLLs or of the functions within a DLL. The process can get this information from a configuration file or from the user.

Run-time dynamic linking can cause problems if the DLL is using the DllEntryPoint function to perform initialization for each thread of a process, because threads existing when LoadLibrary is called will not be initialized. For an example showing how to deal with this problem, see Using Thread Local Storage in a Dynamic-Link Library.


Dynamic-Link Library Data

Windows NT supports the use of the following:

Global and static variables in a DLL module private to each process that uses the DLL.

Global and static variables shared by all processes simultaneously using a DLL.

Dynamically allocated memory private to each process that uses a DLL.

Dynamically allocated memory shared by multiple processes.

Static storage private to each thread of a multithreaded process.

The default scope of a DLL's variables is the same as in any statically linked code. Global variables in a DLL source code file are global to each process using the DLL. Static variables create permanent storage for each process, limiting their scope to the block in which they are declared. As a result, each process has its own instance of a DLL's global and static variables by default.

Win32 development tools enable you to use a DLL's module definition file to override the default scope of global and static variables. For more information, see The Module Definition File, and the documentation for the tools being used.

When a DLL allocates memory using any of the allocation functions (GlobalAlloc, LocalAlloc, HeapAlloc, VirtualAlloc, or malloc and other C run-time allocation functions) the memory is allocated in the address space of the calling process and is accessible only to the threads of that process. A DLL's module-definition file cannot be used to change the scope of dynamically allocated memory.

A DLL can use file mapping to allocate memory that can be shared among processes. For an example that uses the DllEntryPoint function to set up shared memory using file mapping, see Using Shared Memory in a Dynamic-Link Library.

The thread local storage functions enable a DLL to allocate an index for storing and retrieving a different value for each thread of a multithreaded process. For example, a spreadsheet application can create a new instance of the same thread each time the user opens a new spreadsheet. A DLL providing the functions for various spreadsheet operations can use thread local storage to save information about the current state of each spreadsheet (row, column, and so on).


Using Dynamic-Link Libraries

The examples in this section illustrate the following tasks:

Creating a simple dynamic-link library.

Calling a DLL function by using load-time linking.

Calling a DLL function by using run-time linking.

Using a DLL's entrypoint function to create named shared memory accessible to all processes using the DLL.

Using thread local storage in a DLL.


Creating a Simple Dynamic-Link Library

Dynamic-link libraries make common functions available to a number of processes or threads at once. The following file, MYPUTS.C, contains a simple string printing function. This DLL does not use a DllEntryPoint function because it has no initialization or cleanup functions to perform.

#include <windows.h>

/*

 * A function that writes a null terminated string to

 * console output.

 */

VOID myPuts(LPTSTR lpszMsg) {

    DWORD cchWritten;

    HANDLE hStdout;

    /* Get a handle to the console output. */

    hStdout = GetStdHandle(STD_OUTPUT_HANDLE);

    /* Write a null-terminated string to the console output. */

    while (*lpszMsg)

        WriteFile(hStdout, lpszMsg++, 1, &cchWritten, NULL);

}

The module-definition file for this DLL is MYPUTS.DEF, and it contains the following information:

LIBRARY myputs

EXPORTS

     myPuts

The name specified in the LIBRARY statement identifies the DLL in the DLL's import library. Load-time dynamic linking enables the system to use this name for locating the DLL. If run-time dynamic linking is being used, the LoadLibrary function does not use this name to locate the DLL. The EXPORTS statement indicates that other .EXE or .DLL modules can call the myPuts function.

The source code in MYPUTS.C is compiled to produce an object module, MYPUTS.OBJ. The library manager uses the module-definition file (MYPUTS.DEF) to create the import library (MYPUTS.LIB) and the export file (MYPUTS.EXP). The linker uses MYPUTS.EXP and MYPUTS.OBJ to produce the executable DLL module (MYPUTS.DLL). The MYPUTS.LIB import library is not used in creating MYPUTS.DLL, but the linker uses it to create any executable module (.EXE or .DLL) that calls the myPuts function.

Following are some typical command lines used to compile and link a DLL. For more information about compiling and linking dynamic-link libraries and programs that use them, refer to the documentation for the development tools you are using.

cvars=-DWIN32 -D_MT -DSTRICT

# Compile myputs.c to create myputs.obj.

myputs.obj: myputs.c

    $(cc)  $(cflags) $(cvars) myputs.c

# Create the DLL's import library.

# Also create the myputs.exp export file.

myputs.lib: myputs.def

    $(lib) -machine:i386 \

    -def:myputs.def     \

    -out:myputs.lib

# Link myputs.obj and myputs.exp to create myputs.dll.

# myputs.lib is not used here but is included as a

# dependency to force creation of myputs.exp.

myputs.dll: myputs.obj myputs.lib

    $(link)          \

    -out:myputs.dll  \

    myputs.exp myputs.obj $(conlibs)

# If dll has a DllEntryPoint function, substitute a line

# like this to specify the name of the entrypoint function.

#    $(link) -entry:LibMain    \


Using Load-Time Dynamic Linking

Once you have created a dynamic-link library, you can use it in an application. The following file, LOADTIME.C, is the source code for a simple console process that uses the myPuts function from MYPUTS.DLL.

/*

 *   File: loadtime.c

 *   A simple program that uses myPuts() from myputs.dll

 */

#include <windows.h>

VOID myPuts(LPTSTR);   /* a function from a DLL */

VOID main(VOID) {

    myPuts("message printed using the DLL function\n");

}

Because LOADTIME.C calls the DLL function explicitly, the executable module for the application must be linked with the import library (MYPUTS.LIB). Following are some typical command lines used for compiling and linking a program that uses a DLL.

# Compile loadtime.c to create loadtime.obj.

loadtime.obj: loadtime.c

    $(cc)  $(cflags) $(cvars) loadtime.c

# Link loadtime.obj and myputs.lib to create loadtime.exe.

loadtime.exe: loadtime.obj myputs.lib

    $(link) $(conflags) \

    -out:loadtime.exe loadtime.obj myputs.lib $(conlibs)


Using Run-Time Dynamic Linking

You can use the same dynamic-link library in both load-time and run-time dynamic linking. If the system can find the specified DLL module, the following source code produces the same output as the load-time example in the previous section. The program uses the LoadLibrary function to get a handle of MYPUTS.DLL. If LoadLibrary succeeds, the program uses the returned handle in the GetProcAddress function to get the starting address of the DLL's myPuts function. After calling the DLL function, the program calls the FreeLibrary function to detach the DLL from the process.

The following example illustrates an important difference between run-time and load-time dynamic linking. If the MYPUTS.DLL file is not available, the application using load-time dynamic linking simply terminates. The run-time dynamic linking example, however, is able to respond to the error.

/*

 *   File: runtime.c

 *   A simple program that uses LoadLibrary and

 *   GetProcAddress to access myPuts() from the myputs DLL

 */

#include <stdio.h>

#include <windows.h>

typedef VOID (*MYPROC)(LPTSTR);

VOID main(VOID) {

    HINSTANCE hinstLib;

    MYPROC ProcAdd;

    BOOL fFreeResult, fRunTimeLinkSuccess = FALSE;

    /* Get a handle to the DLL module. */

    hinstLib = LoadLibrary("myputs");

    /* If a handle is valid, try to get the function address. */

    if (hinstLib != NULL) {

        ProcAdd = (MYPROC) GetProcAddress(hinstLib, "myPuts");

        /* If the function address is valid, call the function. */

        if (fRunTimeLinkSuccess = (ProcAdd != NULL))

            (ProcAdd) ("message via DLL function\n");

        /* Free the DLL module. */

        fFreeResult = FreeLibrary(hinstLib);

  }

    /* If unable to call the DLL function, use the alternative. */

    if (! fRunTimeLinkSuccess)

        printf("message via alternative method\n");

}

Because the program uses run-time dynamic linking, it is not necessary to link with the DLL's import library when creating the program's executable module. The following lines are typical of the command lines used to compile and link a program using run-time linking.

# Compile runtime.c to create runtime.obj.

runtime.obj: runtime.c

    $(cc)  $(cflags) $(cvars) runtime.c

# Link runtime.obj to create loadtime.exe.

runtime.exe: runtime.obj

    $(link) $(conflags) \

    -out:runtime.exe runtime.obj $(conlibs)


Using Shared Memory in a Dynamic-Link Library

This section shows the use of a DLL's entrypoint function to set up memory that can be shared by multiple processes. In this DLL, the name of the entrypoint function is LibMain. The module definition file for this DLL is MYPUTS.DEF, and it contains the following information.

LIBRARY myputs

EXPORTS

     myPuts

The example uses file mapping to map a block of named shared memory into the address space of each process to which the DLL is attached. The entrypoint function calls the CreateFileMapping function to create a file-mapping object whenever the DLL attaches to a new process. You can use this function to either create or open a named file-mapping object. The first process to which the DLL attaches creates the file-mapping object. Subsequent processes open a handle of the existing object. The GetLastError function triggers initialization of the shared memory, because it returns NO_ERROR to the first process and ERROR_ALREADY_EXISTS to subsequent processes.

The MapViewOfFile function maps the file-mapping object into the address space of each process, returning a pointer to the memory. Note that the shared memory can be mapped to a different address in each process. For this reason, each process has its own instance of lpvMem, declared as a global variable so it is available to the DLL's functions. The example assumes that the DLL's global data is not shared, so each attaching process has its own instance of lpvMem. By default, DLL data is not shared, but this can be modified by the DLL's module definition file (see The Module Definition File).

Any shared DLL memory persists only as long as the DLL is attached to a process. In this example, the shared memory is released when the last handle of the file-mapping object is closed. To create persistent shared memory, a DLL can create a detached process when the DLL attaches to the first process. If this detached process uses the DLL and does not terminate, it has a handle of the file-mapping object that prevents the shared memory from being released.

/*

 *   File: dllshmem.c

 *

 *   DLL entrypoint function sets up shared memory using

 *   named file mapping.

 */

#include <windows.h>

#include <memory.h>

#define SHMEMSIZE 4096

static LPVOID lpvMem = NULL; /* address of shared memory */

/*

 * LibMain() is the DllEntryPoint function for this DLL.

 */

BOOL LibMain(HINSTANCE hinstDLL,   /* DLL module handle  */

        DWORD fdwReason,      /* reason called           */

        LPVOID lpvReserved) { /* reserved                */

    HANDLE hMapObject = NULL;   /* handle to file mapping */

    BOOL fInit, fIgnore;

    switch (fdwReason) {

        /*

         * DLL is attaching to a process, due to process

         * initialization or a call to LoadLibrary.

         */

          case DLL_PROCESS_ATTACH:

            /* create named file mapping object */

            hMapObject = CreateFileMapping(

                (HANDLE) 0xFFFFFFFF, /* use paging file    */

                NULL,                /* no security attr. */

                PAGE_READWRITE,      /* read/write access  */

                0,                   /* size: high 32-bits */

                SHMEMSIZE,           /* size: low 32-bits  */

                "dllmemfilemap");    /* name of map object */

            if (hMapObject == NULL)

                return FALSE;

            /* The first process to attach initializes memory. */

            fInit = (GetLastError() != ERROR_ALREADY_EXISTS);

            /* Get a pointer to file mapped shared memory. */

            lpvMem = MapViewOfFile(

                hMapObject,     /* object to map view of    */

                FILE_MAP_WRITE, /* read/write access        */

                0,              /* high offset: map from  */

                0,              /* low offset: beginning */

                0);             /* default: map entire file */

            if (lpvMem == NULL)

                return FALSE;

            /* Initialize memory if this is the first process. */

            if (fInit)

                memset(lpvMem, '\0', SHMEMSIZE);

            break;

        /* The attached process creates a new thread. */

        case DLL_THREAD_ATTACH:

            break;

        /* The thread of the attached process terminates. */

        case DLL_THREAD_DETACH:

            break;

        /*

         * The DLL is detaching from a process, due to

         * process termination or a call to FreeLibrary.

         */

        case DLL_PROCESS_DETACH:

            /* Unmap shared memory from process' address space. */

            fIgnore = UnmapViewOfFile(lpvMem);

            /* Close the process' handle to the file-mapping object. */

            fIgnore = CloseHandle(hMapObject);

            break;

        default:

          break;

  }

    return TRUE;

    UNREFERENCED_PARAMETER(hinstDLL);

    UNREFERENCED_PARAMETER(lpvReserved);

}

/*

 * SetSharedMem() sets the contents of shared memory.

 */

VOID SetSharedMem(LPTSTR lpszBuf) {

    LPTSTR lpszTmp;

    /* Get the address of the shared memory block. */

    lpszTmp = (LPTSTR) lpvMem;

    /* Copy the null-terminated string into shared memory. */

    while (*lpszBuf)

        *lpszTmp++ = *lpszBuf++;

    *lpszTmp = '\0';

}

/*

 * GetSharedMem() gets contents of shared memory.

 */

VOID GetSharedMem(LPTSTR lpszBuf, DWORD cchSize) {

    LPTSTR lpszTmp;

    /* Get the address of the shared memory block. */

    lpszTmp = (LPTSTR) lpvMem;

    /* Copy from shared memory into the caller's buffer. */

    while (*lpszTmp && --cchSize)

        *lpszBuf++ = *lpszTmp++;

    *lpszBuf = '\0';

}


Using Thread Local Storage in a Dynamic-Link Library

This section shows the use of a DLL's entrypoint function to set up a thread local storage (TLS) index to provide private storage for each thread of a multithreaded process.

The entrypoint function uses the TlsAlloc function to allocate a TLS index whenever the DLL attaches to a process. Each thread of the process can then use this index to store a pointer to its own block of memory.

When the entrypoint function is called with the DLL_PROCESS_ATTACH code, it does the following:

1	Uses the TlsAlloc function to allocate a TLS index.

2	Allocates a block of memory to be used exclusively by the initial thread of the process.

3	Uses the TLS index in a call to the TlsSetValue function to store a pointer to the allocated memory.

Each time the process creates a new thread, the entrypoint function is called with the DLL_THREAD_ATTACH code. The entrypoint function then allocates a block of memory for the new thread and stores a pointer to it by using the TLS index. Each thread can use the TLS index in a call to TlsGetValue to retrieve the pointer to its own block of memory.

When a thread terminates, the entrypoint function is called with the DLL_THREAD_DETACH code and the memory for that thread is freed. When a process terminates, the entrypoint function is called with the DLL_PROCESS_DETACH code and the TLS index is freed.

The TLS index is stored in a global variable, making it available to all the DLL's functions. The following example assumes that the DLL's global data is not shared, because the TLS index is not necessarily the same for each process to which the DLL is attached.

static DWORD dwTlsIndex; /* address of shared memory */

/*

 * LibMain() is the DllEntryPoint function for this DLL.

 */

BOOL LibMain(HINSTANCE hinstDLL,   /* DLL module handle  */

        DWORD fdwReason,     /* reason called      */

        LPVOID lpvReserved) {/* reserved           */

    LPVOID lpvData;

    BOOL fIgnore;

    switch (fdwReason) {

        /*

         * The DLL is attaching to a process, due to process

         * initialization or a call to LoadLibrary.

         */

        case DLL_PROCESS_ATTACH:

              /* Allocate a TLS index. */

              if ((dwTlsIndex = TlsAlloc()) == 0xFFFFFFFF)

                  return FALSE;

            /* No break: Initialize the index for first thread. */

        /* The attached process creates a new thread. */

        case DLL_THREAD_ATTACH:

            /* Initialize the TLS index for this thread. */

            lpvData = (LPVOID) LocalAlloc(LPTR, 256);

            if (lpvData != NULL)

                fIgnore = TlsSetValue(dwTlsIndex, lpvData);

            break;

        /* The thread of the attached process terminates. */

        case DLL_THREAD_DETACH:

            /* Release the allocated memory for this thread. */

            lpvData = TlsGetValue(dwTlsIndex);

            if (lpvData != NULL)

                LocalFree((HLOCAL) lpvData);

            break;

        /*

         * The DLL is detaching from a process, due to

         * process termination or call to FreeLibrary.

         */

        case DLL_PROCESS_DETACH:

            /* Release the allocated memory for this thread. */

            lpvData = TlsGetValue(dwTlsIndex);

            if (lpvData != NULL)

                LocalFree((HLOCAL) lpvData);

            /* Release the TLS index. */

            TlsFree(dwTlsIndex);

            break;

        default:

            break;

    }

    return TRUE;

    UNREFERENCED_PARAMETER(hinstDLL);

    UNREFERENCED_PARAMETER(lpvReserved);

}

When a process uses load-time linking with this DLL, the entrypoint function is sufficient to manage the thread local storage. Problems can occur with a process that uses run-time linking, because the TLS memory is not allocated for threads that exist before the LoadLibrary function is called to attach the process. The following example solves this problem by checking the value returned by the TlsGetValue function and allocating memory if the value indicates that the TLS slot for this thread is not set.

LPVOID lpvData;

/* Retrieve a data pointer for the current thread. */

lpvData = TlsGetValue(dwTlsIndex);

/* If NULL, allocate memory for this thread. */

if (lpvData == NULL) {

    lpvData = (LPVOID) LocalAlloc(LPTR, 256);

    if (lpvData != NULL)

        TlsSetValue(dwTlsIndex, lpvData);

}


Functions

Following are the functions used in dynamic linking.

DllEntryPoint

FreeLibrary

GetModuleFileName

GetModuleHandle

GetProcAddress

LoadLibrary

LoadLibraryEx

LoadModule


Resources Overview

About Resources

A resource is binary data that a resource compiler or developer adds to an application's executable file. A resource can be either standard or defined. The data in a standard resource describes an icon, cursor, menu, dialog box, bitmap, font, accelerator table, message-table entry, string-table entry, or version. An application-defined resource, also called a custom resource, contains any data required by a specific application.

The following topics discuss Windows resources.:

Terms

Finding and Loading Resources

Adding, Deleting, and Replacing Resources

Enumerating Resources

Updating Resources

Creating a Resource List

Functions

This topic describes the functions that enable applications to find a resource in a module; load a resource into memory; add, delete or replace a resource in an executable file; and generate a list of the resources contained in a module. For specific information about the organization of resource data within executable files, refer to the resource formats documentation.

For information about how to create standard resources, refer to the following table.

Resource	Overview

Bitmap	Bitmaps

Cursor	Cursors

Dialog box	Dialog Boxes

Font	Fonts and Text

Accelerator table	Keyboard Accelerators

Icon	Icons

Menu	Menus

Message-table entry	Your message-compiler documentation

String-table entry	String Manipulation and Unicode

Version information	File Installation Library

For information about how to include resource data in a Microsoft® Windows™ executable file, refer to the documentation for your resource compiler.


Loading Resources

Finding and Loading Resources

Before using a resource, an application must load it into memory. The FindResource and FindResourceEx functions find a resource in a module and return a handle to the binary resource data. FindResource locates a resource by type and name. The FindResourceEx function locates the resource by type, name, and language. Information about FindResource in this topic also applies to FindResourceEx.

The LoadResource function uses the resource handle returned by FindResource to load the resource into memory. After an application loads a resource by using LoadResource, Windows automatically unloads and reloads the resource as memory conditions and application execution require, so that it is not necessary for an application to explicitly unload a resource that is no longer needed.

An application can use FindResource and LoadResource to find and load any type of resource, but these functions should be used only if the application must access the binary resource data for subsequent function calls. To use a resource immediately, an application should use one of the following resource-specific functions to find and load 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 a screen. However, the application should use FindResource and LoadResource if it is loading the icon to copy its data to another application.

Before terminating, an application should release the memory occupied by accelerator tables, bitmaps, cursors, icons, and menus by using one of the functions in the following table.

Resource	Release function

Accelerator table	DestroyAcceleratorTable

Bitmap	DeleteObject

Cursor	DestroyCursor

Icon	DestroyIcon

Menu	DestroyMenu

When the application terminates, Windows automatically releases the memory occupied by the other types of resources.


Adding, Deleting, and Replacing Resources

Adding, Deleting, and Replacing Resources

Applications must frequently add, delete, or replace resources in executable files. Two methods can be used to accomplish these tasks. The first is to edit the resource-definition file, recompile the resources, and add the recompiled resources to the application's executable file. The second method is to copy the resource data directly into the application's executable file.

For example, to localize an English-language application for use in Norway, it may be necessary to replace the English dialog box with one using Norwegian. A developer creates an appropriate dialog box by using a dialog box editor or by writing a template in the resource-definition file. Then the developer recompiles the resources and adds the new resources to the application's executable file.

If an appropriate dialog box exists in binary form, however, the developer can copy the data directly to the executable file being localized by using three Windows functions. The BeginUpdateResource function creates an update handle for the executable file whose resources are to be changed. The UpdateResource function uses this handle to add, delete, or replace a resource in the executable file. The EndUpdateResource function closes the handle.

After an update handle to an executable file is created by using BeginUpdateResource, 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. Immediately before closing the update handle, EndUpdateResource writes the accumulated changes to the executable file.

Sometimes, an application must copy resources or find resource sizes. The LoadLibrary function provides a module handle to an executable file whose resources are to be copied, and the LockResource function provides a pointer to the resource data in the specified module. The SizeofResource function returns the size, in bytes, of a specified resource.


Enumerating Resources

Three Windows functions enable an application to obtain lists of resource types, names, and languages in a specified module. The EnumResourceTypes function provides a list of resource types found in the module, the EnumResourceNames function provides the name of each resource within a given type, and the EnumResourceLanguages function provides the language of each resource of a given name and type. These functions and their associated callback functions enable applications to create a list of all resources in a module. This process is described in Creating a Resource List.


Updating Resources

The following example copies a dialog box resource from one executable file, HAND.EXE, to another, FOOT.EXE, by following these steps:

1	The LoadLibrary function loads the executable file HAND.EXE.

2	The FindResource and LoadResource functions locate and load the dialog box resource named If from the file.

3	The LockResource function returns a pointer to the dialog box resource data.

4	The BeginUpdateResource function opens an update handle FOOT.EXE.

5	The UpdateResource function copies the dialog box resource from HAND.EXE to FOOT.EXE.

6	The EndUpdateResource function completes the update.

The following code implements these steps.

HRSRC hResLoad;     /* handle to loaded resource         */

HANDLE hExe;        /* handle to existing .EXE file      */

HRSRC hRes;         /* handle/ptr. to res. info. in hExe */

HANDLE hUpdateRes;  /* update resource handle            */

char *lpResLock;    /* pointer to resource data          */

BOOL result;

/* Load the .EXE file that contains the dialog box you want to copy. */

hExe = LoadLibrary("hand.exe");

if (hExe == NULL) {

    ErrorHandler("Could not load exe.");

}

/* Locate the dialog box resource in the .EXE file. */

hRes = FindResource(hExe, "AboutBox", RT_DIALOG);

if (hRes == NULL) {

    ErrorHandler("Could not locate dialog box.");

}

/* Load the dialog box into global memory. */

hResLoad = LoadResource(hExe, hRes);

if (hResLoad == NULL) {

    ErrorHandler("Could not load dialog box.");

}

/* Lock the dialog box into global memory. */

lpResLock = LockResource(hRes);

if (lpResLock == NULL) {

    ErrorHandler("Could not lock dialog box.");

}

/* Open the file to which you want to add the dialog box resource. */

hUpdateRes = BeginUpdateResource("foot.exe", FALSE);

if (hUpdateRes == NULL) {

    ErrorHandler("Could not open file for writing.");

}

/* Add the dialog box resource to the update list. */

result = UpdateResource(hUpdateRes,       /* update resource handle     */

             RT_DIALOG,                   /* change dialog box resource */

             "AboutBox",                  /* dialog box name            */

             MAKELANGID(LANG_NEUTRAL,

                 SUBLANG_NEUTRAL),        /* neutral language ID        */

             lpResLock,                   /* ptr to resource info       */

             SizeofResource(hExe, hRes)); /* size of resource info. */

if (result == FALSE) {

    ErrorHandler("Could not add resource.");

}

/* Write changes to FOOT.EXE and then close it. */

if (!EndUpdateResource(hUpdateRes, FALSE)) {

    ErrorHandler("Could not write changes to file.");

}

/* Clean up. */

if (!FreeLibrary(hExe)) {

    ErrorHandler("Could not free executable.");

}


Creating a Resource List

The following example creates a list of every resource in the HAND.EXE file. The list is written to the RESINFO.TXT file.

The code demonstrates how to load the executable file, create a file in which to write resource information, and call the EnumResourceTypes function to send each resource type found in the module to the EnumTypesFunc function, an application-defined callback function. See EnumResTypeProc for information on callback functions of this type. This callback function uses the EnumResourceNames function to pass the name of every resource within the specified type to the EnumNamesFunc function, another application-defined callback function. See EnumResNameProc for information on callback functions of this type. EnumNamesFunc uses the EnumResourceLanguages function to pass the language of every resource of the specified type and name to the EnumLangsFunc function, a third callback function. See EnumResLangProc for information on callback functions of this type. EnumLangsFunc writes information about the resource of the specified type, name, and language to the RESINFO.TXT file.

char szBuffer[80]; /* print buffer for EnumResourceTypes         */

DWORD cbWritten;   /* number of bytes written to res. info. file */

int cbString;      /* length of string in sprintf                */

/* Declare callback functions. */

BOOL EnumTypesFunc(

    HANDLE hModule,

    LPTSTR lpType,

    LONG lParam);

BOOL EnumNamesFunc(

    HANDLE hModule,

    LPCTSTR lpType,

    LPTSTR lpName,

    LONG lParam);

BOOL EnumLangsFunc(

    HANDLE hModule,

    LPCTSTR lpType,

    LPCTSTR lpName,

    WORD wLang,

    LONG lParam);

/* Load the .EXE whose resources you want to list. */

hExe = LoadLibrary("hand.exe");

if (hExe == NULL) {

    ErrorHandler("Could not load .EXE.");

}

/* Create a file to contain the resource info. */

hFile = CreateFile("resinfo.txt",      /* name of file    */

    GENERIC_READ | GENERIC_WRITE,      /* access mode     */

    0,                                 /* share mode      */

    (LPSECURITY_ATTRIBUTES) NULL,      /* no security     */

    CREATE_ALWAYS,                     /* create flags    */

    FILE_ATTRIBUTE_NORMAL,             /* file attributes */

    (HANDLE) NULL);                    /* no template     */

if (hFile == INVALID_HANDLE_VALUE) {

    ErrorHandler("Could not open file.");

}

/* Find all of the loaded file's resources. */

cbString = sprintf(szBuffer,

    "The file contains the following resources:\n\n");

WriteFile(hFile,           /* file to hold resource info. */

    szBuffer,              /* what to write to the file   */

    (DWORD) cbString,      /* number of bytes in szBuffer */

    &cbWritten,            /* number of bytes written     */

    NULL);                 /* no overlapped I/O           */

EnumResourceTypes(hExe,              /* module handle     */

    (ENUMRESTYPEPROC)EnumTypesFunc,  /* callback function */

    0);                              /* extra parameter   */

/*

 * Unload the executable file whose resources were

 * enumerated and close the file created to contain

 * the resource information.

 */

FreeLibrary(hExe);

CloseHandle(hFile);

/********************************************************

    FUNCTION: EnumTypesFunc(HANDLE, LPSTR, LONG)

    PURPOSE: Resource type callback

*********************************************************/

BOOL EnumTypesFunc(

    HANDLE hModule,   /* module handle             */

    LPTSTR lpType,    /* address of resource type  */

    LONG lParam)      /* extra parameter, could be */

                      /* used for error checking   */

{

    int cbString;

    /*

     * Write the resource type to a resource information file.

     * The type may be a string or an unsigned decimal

     * integer, so test before printing.

     */

    if ((ULONG)lpType & 0xFFFF0000) {

        cbString = sprintf(szBuffer, "Type: %s\n", lpType);

    }

    else {

        cbString = sprintf(szBuffer, "Type: %u\n", (USHORT)lpType);

    }

    WriteFile(hFile, szBuffer, (DWORD) cbString,

        &cbWritten, NULL);

    /* Find the names of all resources of type lpType. */

    EnumResourceNames(hModule,

                      lpType,

                      (ENUMRESNAMEPROC)EnumNamesFunc,

                      0);

    return TRUE;

}

/********************************************************

    FUNCTION: EnumNamesFunc(HANDLE, LPSTR, LPSTR, LONG)

    PURPOSE: Resource name callback

*********************************************************/

BOOL EnumNamesFunc(

    HANDLE hModule,   /* module handle             */

    LPCTSTR lpType,   /* address of resource type  */

    LPTSTR lpName,    /* address of resource name  */

    LONG lParam)      /* extra parameter, could be */

                      /* used for error checking   */

{

    int cbString;

    /*

     * Write the resource name to a resource information file.

     * The name may be a string or an unsigned decimal

     * integer, so test before printing.

     */

    if ((ULONG)lpName & 0xFFFF0000) {

        cbString = sprintf(szBuffer, "\tName: %s\n", lpName);

    }

    else {

        cbString = sprintf(szBuffer, "\tName: %u\n",

                      (USHORT)lpName);

    }

    WriteFile(hFile, szBuffer, (DWORD) cbString,

        &cbWritten, NULL);

    /*

     * Find the languages of all resources of type

     * lpType and name lpName.

     */

    EnumResourceLanguages(hModule,

                          lpType,

                          lpName,

                          (ENUMRESLANGPROC)EnumLangsFunc,

                          0);

    return TRUE;

}

/*************************************************************

    FUNCTION: EnumLangsFunc(HANDLE, LPSTR, LPSTR, WORD, LONG)

    PURPOSE: Resource language callback

**************************************************************/

BOOL EnumLangsFunc(

    HANDLE hModule,  /* module handle            */

    LPCTSTR lpType,  /* address of resource type */

    LPCTSTR lpName,  /* address of resource name */

    WORD wLang,      /* resource language        */

    LONG lParam)     /* extra parameter, could be

                        used for error checking  */

{

    HANDLE hResInfo;

    char szBuffer[80];

    int cbString = 0;

    hResInfo = FindResourceEx(hModule, lpType, lpName, wLang);

    /* Write the resource language to the resource information file. */

    cbString = sprintf(szBuffer, "\t\tLanguage: %u\n",

                  (USHORT)wLang);

    WriteFile(hFile, szBuffer, (DWORD) cbString,

        &cbWritten, NULL);

    /* Write the resource handle and size to buffer. */

    cbString = sprintf(szBuffer,

                  "\t\thResInfo == %lx,  Size == %lu\n\n",

                  hResInfo,

                  SizeofResource(hModule, hResInfo));

    WriteFile(hFile, szBuffer, (DWORD) cbString,

        &cbWritten, NULL);

    return TRUE;


Functions

Following are the functions used with resources.

BeginUpdateResource

EndUpdateResource

EnumResLangProc

EnumResNameProc

EnumResourceLanguages

EnumResourceNames

EnumResourceTypes

EnumResTypeProc

FindResource

FindResourceEx

LoadResource

LockResource

SizeofResource

UpdateResource


Registry and Initialization Files Overview

About the Registry and Initialization Files

In Microsoft Windows, applications use initialization files to store information that otherwise would be lost when the application closes. These files typically contain such information as user preferences for the configuration of the application. Initialization files, however, have the following inherent limitations:

Information in initialization files is typically available only to the application that put it there.

The text format of initialization files allows casual manipulation by potentially naive end users.

Separate initialization files for many applications can proliferate on a hard disk.

There is no way to secure initialization files against tampering.

Initialization files do not support multiple users.

Initialization files do not support for multiple versions of the same app.

Initialization files are not recoverable.

Information in initialization files cannot be accessed or administered remotely in any consistent way.

Microsoft Windows version 3.1 included a new feature: a registration database. A registration database contains information that supports shell applications (such as Windows File Manager) and applications that use object linking and embedding (OLE). Each piece of information in the database is identified by a key, which may have a value (data) associated with it. Windows 3.1 introduced a set of functions to support querying and setting information in the database. This database was not meant as a place for applications to store private configuration information; initialization files were required for that purpose.

The Win32 application programming interface (API) expands the usefulness of the version 3.1 registration database in two fundamental ways; the database now uses more keys and each key can hold more data. The new database is called the registry. The functions that manipulate the registration database in Windows 3.1 work with the Win32 registry, but some of them have been superseded in the Win32 API by extended versions.

The purpose of the registry is to meet the following goals:

Provide one source for configuration information, making initialization and configuration files (such as CONFIG.SYS and WIN.INI) obsolete.

Many of these files, however, are maintained for compatibility with previous versions of Windows or Windows apps.

Enumerate, track, and configure the applications, device drivers, and operating system control parameters.

Enumerate and track the hardware on a computer.

Standardize the user interface for configuration information through the use of Windows Control Panel.

Reduce the likelihood of syntactic errors in configuration information.

Separate user-, application-, and computer-related information, so that separate data for multiple users can be maintained on a single computer.

Provide security for configuration data. This security prevents unauthorized changes to critical data but allows users direct control over matters of personal preference.

Provide a set of network-independent functions for setting and querying configuration information and enable direct examination of configuration data over a network.

Provide storage that is recoverable after system crashes.

Provide atomicity of edits.

Applications, device drivers, and the system itself use the registry api to store and retrieve data. The registry stores this data in files which appear in the file system. These files are in a private binary format, and are held open for exclusive access, so apps cannot write to them directly, but must use the api instead.

The following topics discuss the Win32 registry and initialization-file functions:

Terms

Structure of the Registry

Mapping and Initialization Files

Structure of HKEY_LOCAL_MACHINE

Hardware

Security and SAM

Software

System

Structure of HKEY_USERS

Storing Information in the Registry

Storage Space

Applications and the Registry

Using the Registry Functions

Example: Enumerating Keys and Values

Functions


Structure of the Registry

The registry is stored in binary format in a series of files in the SYSTEM32 directory of Microsoft® Windows NT™. (Hives that contain user profiles may reside elsewhere.) These files correspond to hives; that is, discrete bodies of registry information, rooted at the top of the registry hierarchy. The size of the registry is user-configurable, limited only by system resources. The default registry size limit is one-fourth the size of the system's paged pool size.

Data in the registry is in the form of a hierarchically structured tree. Each entry node in the tree is called a key. The registry is something like a file system, in that each key can contain both subkeys (analogous to directories) and data entries (analogous to files).

Applications use the registry in much the same way as they use initialization files, as a place where information can be stored and retrieved.

Sometimes, the presence of a key is all the information that an application requires; other times, an application opens a key and uses the data associated with that key. For the Windows 3.1 registration database, this data was in the form of a string. For the Win32 registry, a key can have any number of data entries, and the data can be in any form. Each data entry is called a value.

Each key can contain the following items.

Key component	Description

Name	String used to gain access to the key. This name must be unique relative to other subkeys at the same level in the hierarchy (that is, KeyA and KeyB could each have a subkey KeyC, but KeyA could not have two KeyC subkeys). A key name cannot contain backslash (\) or null characters. This key component is required.

Class	Object class name. Intended for use in associating class method code with class instances stored in the registry. Not normally used by apps. This key component is optional.

Security Descriptor	Keys use standard Windows NT security descriptors, and can thus express auditing control and full access control. Normal security inheritance rules apply. This is key component is optional.

Last write time	A time stamp indicating the last time the key was modified. Any change to a value is considered a modification of the value's parent key.

Value(s)	Zero or more pieces of information to be stored with the key. This key component is optional. A value consists of the following three parts.

Value component	Description

Name	Identifies the value. The name can be up to 32,767 Unicode characters (65,534 bytes) in size. Backslash characters (\) are legal in value names. A NULL name (that is, "") is also legal to allow compatibility with Windows 3.1.

Type	Defines the type of data stored in this value. In Windows 3.1, this type was always REG_SZ, designating a null-terminated string. In the Win32 API, types are defined for most data formats. Although the system does not use this type information, applications should use the predefined types so that registry tools can find and manipulate the value data. Types with values below 0x7fffffff are reserved for system use.

Data	Specifies user data of arbitrary length and format. May not exceed 1 megabyte in Windows NT 3.1 release.

All name strings in the registry are stored in Unicode format. The registry preserves the case of any strings stored in the registry but ignores the case in all operations. (Data stored in the Data section of values is arbitrary, but strings should be stored as Unicode there as well.) For more information about Unicode, see String Manipulation and Unicode.

The registry enforces a rule of atomicity: for any value entry, a given change either either occurs in its entirety, or the change does not occur at all. This means that the name, type, size, and data will always match, and all of the data in the value entry will be consistent. This is true even if the system crashes while a value entry is being updated. Keys are always consistent with the value entries they contain; to repeat, this is true even if the system crashes during an update.

Consistency amoung multiple values of the same key, or multiple keys, is NOT enforced by the system. Applications that write multiple values and require that they be consistent with one another must build their own transaction mechanism on top of the Registry's atomicity enforcement mechanism.

Whenever an application opens a key, it must supply the handle of another key in the registry that is already open. The system defines four standard handles that are always open. An application can use the following predefined handles as entry points to the registry.

Entry Points	Use

HKEY_CLASSES_ROOT	Registry entries subordinate to this handle define types (or classes) of documents and the properties associated with these classes.

This is the entry point used in Windows version 3.1; the information it contains has not changed for Windows NT.

Information stored under this handle is used by Windows shell applications and by OLE applications. Filename extensions are associated with applications that can work with files of that type. The OLE information includes the server command line, appropriate data types, and the action taken by an activated OLE object. This handle is an alias for HKEY_LOCAL_MACHINE, Software\Classes.

HKEY_CURRENT_USER	Registry entries subordinate to this handle define the preferences of the current user. These preferences include the settings of environment variables, information about program groups, colors, printers, network connections, and application preferences. The information for this handle is stored under the HKEY_USERS key.

HKEY_LOCAL_MACHINE	Registry entries subordinate to this handle define the configuration state of the system, including information about the bus type, system memory, and installed hardware and software.

HKEY_USERS	Registry entries subordinate to this handle define the default user configuration for users on the local computer and the user configuration for the current user. (User profiles appear as subtrees under this handle, the HKEY_CURRENT_USER is an alias to the profile of the current user.)

By convention, data in HKEY_CURRENT_USER overrides similar data in HKEY_LOCAL_MACHINE. That is, per-user preferences should normally override per-machine defaults. However, the system does not enforce this convention; it is the responsibility of application code to do so.

Standardized keys help an application navigate in the registry and make it possible to develop tools that a system administrator can use to manipulate categories of information. Applications that add data to the registry should always work within the framework of predefined keys, so that the administrative tools can find and use the new data. There are many predefined keys in addition to the four entry points already discussed; they are listed later in this topic.

To see the contents of the registry, developers can run the Registry Editor (REGEDT32.EXE), a Windows application that ships with Windows NT. This application is not meant to be used as a standard means of modifying the registry. However, using it is an excellent way to get acquainted with the contents of the registry and to monitor changes to the registry's contents.


Mapping and Initialization Files

Many benefits of the registry are available even to applications that do not explicitly write information to it or read information from it. When an application uses a profile or private profile function to get or set information in a configuration or initialization file, the function may be mapped to the registry instead of to the specified file. 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

The system is likely to map function calls to the registry if an application modifies system-component initialization files, such as WIN.INI, SYSTEM.INI, CONTROL.INI, and WINFILE.INI. The change in the storage location has no effect on the GetPrivateProfileInt function's behavior.

Applications can use the IniFileMapping key to simplify their installation procedure. To do this, an application can use an installation routine that calls such functions as GetPrivateProfileString and WritePrivateProfileString. It can use this routine to write either to the registry or to a private initialization file, depending on whether the host system is running Windows NT. For example, if an application writes to an initialization file named ABC.INI, it can use its standard initialization routine to read from and write to the registry by adding a subkey named ABC.INI to the IniFileMapping key.


Structure of HKEY_LOCAL_MACHINE

Note:	The arrangement of registry information may have changed since the publication of this book.

Most applications store information under the HKEY_LOCAL_MACHINE key during their installation procedure. This key contains information specific to the local computer, irrespective of the user. Information such as the name and version of the installing software, the capabilities of OLE-enabled applications, and the names and types of device drivers are stored in this key.

The HKEY_LOCAL_MACHINE key has five subkeys: Hardware, Security, Sam, Software, and System. Applications can query Hardware, Software, and System. They may write to Software and System.


Hardware

The Hardware key is a volatile key, constructed from information gathered by the system each time it starts. This key contains information an application can query to determine the type and state of physical devices attached to the local computer, the resources claimed by various device drivers, and the relationships between device drivers. Applications cannot set information in this key, since this key is overwritten whenever the computer is restarted.

The Hardware key contains three subkeys: Description, DeviceMap, and ResourceMap.

Description

The Description subkey of the Hardware key contains information that describes the hardware on the local computer. Each piece of hardware is described by the following named values.

Named value	Contents

Component information	Binary data that identifies the component

Identifier	String that names the component

Configuration data	Binary data that gives the configuration of the component

The structure of the tree under the Description key varies somewhat with the type of computer (ISA, EISA, ARC, etc) and the bus structure of the computer. (How many and what types of buses does it have.)

The general layout is a key whose name identifies a general object type such as "CentralProcessor" or "EisaAdapter". Under that key will be keys named "0", "1", etc, representing various instances of the object. If the object is a container object (e.g. a bus) then the structure is repeated below it. Thus, one might find a key named

 ...\Description\EisaAdapter\0\DiskController\0

and another key named

 ...\Description\EisaAdapter\1\DiskController\2

The first key describes the 0th disk controller on the first EISA bus on the machine. The second key describes the 2th disk controller on the second EISA bus on the machine.

An application looking for a particular type of device needs to walk the tree and find all instances of that device (e.g. "DiskController") throughout the tree, if it wants to find all of the devices.

Note that a key like ...\EisaAdapter\0 can have value entries that report configuration data about the bus itself, and configuration data that can be read from the bus, but which the system cannot interpret.

CentralProcessor

The CentralProcessor subkey contains numbered keys corresponding to the number of CPUs on the local computer. If there is only one CPU, subkey 0 describes it. The values of these keys reveal model and stepping data for the processors, among other things.

MultifunctionAdapter

The MultifunctionAdapter subkey contains zero-based numbered keys corresponding to the number of multifunction adapters (bus controllers) on the local computer. Each numbered key contains the following zero-based numbered keys.

Key	Contents

DiskController	Keys corresponding to the disk controllers. Floppy disk drives are listed under the FloppyDiskPeripheral subkey of each numbered DiskController key. The values describing each floppy disk drive are associated with numbered subkeys of FloppyDiskPeripheral.

DisplayController	Keys corresponding to the display controllers. Displays are listed under the MonitorPeripheral subkey of each numbered DisplayController key. The values describing each display are associated with numbered subkeys of MonitorPeripheral.

KeyboardController	Keys corresponding to the keyboard controllers. Keyboards are listed under the KeyboardPeripheral subkey of each numbered KeyboardController key. The values describing each keyboard are associated with numbered subkeys of KeyboardPeripheral.

ParallelController	Keys corresponding to the controllers for the parallel ports.

PointerController	Keys corresponding to the pointer controllers. Pointers are listed under the PointerPeripheral subkey of each numbered PointerController key. The values describing each pointer are associated with numbered subkeys of PointerPeripheral.

SerialController	Keys corresponding to the controllers for the serial ports.

DeviceMap

The DeviceMap subkey of the Hardware key maps devices to their drivers. Each key contained by DeviceMap contains one or more named values indicating the location in the registry for the relevant driver information. For example, the PointerPort key may have only the following value, if the local computer has a single mouse device:

\Device\PointerPort0 : REG_SZ :

\REGISTRY\Machine\System\ControlSet001\Services\Inport

In this example, colons separate the name, type, and data elements of the value. This example is displayed on two lines here for formatting reasons; there is no line break in the value data.

This path allows the system to find information about the mouse driver. This information is stored under the following keys:

HKEY_LOCAL_MACHINE\System\ControlSet001\Services\Inport

The DeviceMap key typically contains the following keys:

Keyboard Class

Keyboard Port

Parallel Ports

Pointer Class

Pointer Port

Serialcomm

Video

SCSI

ResourceMap

The ResourceMap subkey of the Hardware key maps device drivers to lists of resources that the drivers use. Applications do not write this data, however, they may read it to understand how resources such as interrupts and dma channels are allocated on the system. For example, an installation program can read the resource map to compute which of the interrupt vectors the card it supports can use are not already in use elsewhere in the system.

Application writers who require further information on resource maps should study the header file NTConfig.h. The application WinMSD.exe allows examination of resource map data.


Security and SAM

The Security and SAM keys contain all of the security information for the local computer. None of the keys contained by Security or SAM can be modified by an application. Applications that must query security information should use the security functions to do so. For more information about security, see Security.


Software

The Software key contains information about the software on the local computer that is independent of per-user configurations. That is, this key contains such information as the manufacturer and version number of software. This key also contains file associations and OLE information.

The Software key can contain many subkeys, but three are of prime importance: Classes, Company name, and Program Groups. (Company name is a placeholder for an actual company name, of which there may be many on a given system.)

Classes

The Classes subkey of the Software key defines types (or classes) of documents. Windows shell applications and OLE applications use the information stored here. Filename extensions are associated with applications that can work with files of that type. OLE information includes the server command line, appropriate data types, and the action taken by an activated OLE object.

The HKEY_CLASSES_ROOT entry-point handle maps to the HKEY_LOCAL_MACHINE\Software\Classes key.

The Classes key contains two kinds of keys: filename-extension keys, which indicate the application associated with files whose names have that extension, and class-definition keys, which indicate the shell and OLE properties of documents in that class.

Filename-Extension Keys

The names of filename-extension keys are in the form .ext. An .ext key defines all files with that extension as members of a specified class. The registering application specifies the document class for an extension in the value associated with the .ext key name.

The .ext key name associates a class with a specific filename extension. For example, if a voice-annotation application named TALK.EXE were registered as an OLE server, it might use .tlk as the filename-extension key and use "Talk" as the value of that key. The application would then create a "Talk" key as the class-definition key.

Class-Definition Keys

The names of class-definition keys are the names of document classes. For example, if a voice-annotation application uses .tlk as a filename-extension key and uses "Talk" as the value of that key, it would also use "Talk" as a class-definition key. The application would record its name (for example, "Talk Voice Annotation") as the value of the class-definition key.

Registry entries that are subordinate to the class-definition keys describe the properties of a class. The registry can describe two kinds of document properties for each class of document: shell properties and protocol properties.

Shell properties describe how a document of a given class interacts with Windows shell applications. There are two key names for shell properties: open and print. The open properties describe how the class responds to a request from a Windows shell application to open a document. The print properties describe how the class responds to a request from Windows Print Manager to print a document. Both the open and print keys must have the command subkey. The value assigned to command specifies the command line used to run the application. If appropriate, this value can include command-line options. For example, the value of the open key for Paintbrush (PBRUSH.EXE) is "pbrush.exe %1".

If an application supports dynamic data exchange (DDE), it can also define the ddeexec subkey for either or both of the open and print key names. The value specified for the ddeexec key name is treated as a DDE command. Defining ddeexec is particularly useful if an application already supports DDE open and print commands. Using DDE messages can add flexibility, particularly for applications that support multiple document interface (MDI), because a DDE message string can include more than one command. The ddeexec key subkeys contains the following.

Key	Contents

application	Application name to use in establishing the DDE conversation. If the registering application does not specify an application key, the system uses the application name specified in the command key.

topic	Topic name of the DDE conversation. If the application does not register a topic key, the system uses the System topic as the default topic name.

ifexec	DDE command to use when initiation of the DDE conversation fails (for example, if the application is not running). When the initiation fails, the command specified by the command key is carried out and then the string specified with the ifexec key is sent. (If an application does not specify a value for the ifexec key, the command specified by the command key is executed when initiation fails and the string specified with the ddeexec key is sent again.)

For more information about DDE, see Dynamic Data Exchange, and Dynamic Data Exchange Management Library.

Protocol properties are the second kind of document properties the registry can describe for each class of document. A protocol is a convention for manipulating a document or some other collection of data. The Protocol key contains keys that describe the properties of a protocol. Although a class can support any number of protocols, currently only two are defined. Both protocol names are used as key names. The most common protocol, StdFileEditing, is used by all documents that support OLE. The second protocol, StdExecute, is used by OLE client applications that must send DDE execute commands to OLE server applications. For more information about using these protocols, see the OLE documentation.

The StdFileEditing protocol contains the following subkeys:

Key	Description

server	Command line that an OLE client application uses to start the server application for a linked or embedded object.

handler	Name of a dynamic-link library (DLL) that acts as an object handler for OLE objects.

verb	This key does not have a value. Subkeys identify the kind of action a server should take when it opens an object. These subkeys are consecutive numbers, beginning with zero. The 0 subkey corresponds to the primary verb for the objects supported by the server. For example, the value for 0 is often "Edit" and the value for the 1 subkey is often "Play".

Company Name

The Company name keys of the Software key contain the names and version numbers of the software installed on the local computer. (Company name is a placeholder for the name of the company that produced the software.) Installing applications should record this information in the following form:

HKEY_LOCAL_MACHINE\Software\CompanyName\

        ProductName\Version

This information is specific to the local computer; information about the configuration of the application is stored on a per-user basis under the HKEY_CURRENT_USER key.

Program Groups

The Program Groups subkey of the Software key contains the common program groups.They are program groups that are used in common by all users of the computer. (A program group is a window in Program Manager containing icons that represent applications.) The program groups for individual users are stored elsewhere in the registry, for example, in HKEY_CURRENT_USER\Program Groups. The name of each subkey of the Program Groups key is the name of a common program group. The value of each of these subkeys is binary data describing the common program group. Applications should use the shell dynamic data exchange (DDE) interface to modify this data. For more information about shell DDE, see Shell Dynamic Data Exchange Interface.


System

The System key contains information about devices and services. Information that Windows and Windows-based applications retrieved from the CONFIG.SYS configuration file in previous versions of Windows is now stored under this key. Applications that provide device drivers or services add or modify information under this key. The System key contains the following keys:

ControlSetnnn

Select

Setup

Clone

CurrentControlSet

These keys are described in detail in the following sections.

ControlSet<nnn>

The ControlSetnnn subkeys for the System key describe control sets. A control set is a set of configurable options for a particular computer. A computer will have more than one ControlSetnnn subkey after it has booted. However, only one ControlSetnnn subkey is in use at any time. The CurrentControlSet key is an alias for the ControlSetnnn key that is currently in use. It provides a symbolic link to that key.

Applications typically do not modify the information in the ControlSetnnn keys; modifications to configuration information are usually made through the CurrentControlSet key.

When the system starts, it obtains configuration information from a ControlSetnnn key. One of the system's first startup actions is to store a copy of that startup ControlSetnnn key as the Clone key for safekeeping. When the system determines that it has successfully booted, it copies the Clone key to another ControlSetnnn key, and makes the Clone key inaccessible. The CurrentControlSet key is an alias to the particular ControlSetnnn key used to start the system. The second ControlSetnnn key, copied from Clone, is kept as a safety backup. Its configuration information has proven to be capable of starting the system.

Thus, the ControlSetnnn keys prevent incorrect configuration information from creating a computer that cannot be started. If, during a system boot, the configuration information in the startup ControlSetnnn key prevents the system from starting up, the system switches to the safety backup ControlSetnnn key. The system uses that backup ControlSetnnn key to complete the startup routine. It is the last known good key. Its identity is stored in the Select key. For more information about this procedure, see Select.

Each ControlSetnnn key has two subkeys: Control and Services.

Control

The Control subkey of the ControlSetnnn key contains configuration information for the computer. The Control key contains the following keys.

Key	Contents

ComputerName	Two keys, ComputerName and ActiveComputerName, specifying the names of the default and active computers.

GroupOrderList	Specifies the load order of drivers within a group.

Keyboard Layout	Available DLLs for the keyboard layout, and which one is used as the default layout.

Lsa	Authentication package for the local security authority.

NetworkProvider	Two keys named: Active and Order. The Active key contains one or more subkeys that specify the active network provider, for example, LanmanWorkstation. The Order key has no subkeys; its value specifies the order in which the system should load these providers.

Nls	Information about national language support. The Nls key contains three subkeys: CodePage, Language, and OEMLocale. The values for the CodePage subkey specify the available code pages. The values for the Language subkey specify the available languages and the default setting.

Print	Information about the current printers and printing environment. This key can contain the following subkeys:

Subkey	Contents

Environments	This key does not have a value. Subkeys of this key have the names of environments, for example, Windows NT x86 or Windows NT R4000. Each Environment key has two subkeys: Drivers and Print Processors.

Drivers keys have subkeys whose names are printer drivers. The values of these subkeys are driver specific.

Print Processors keys have a single value that specifies the print processor, for example, "WinPrint".

Monitors	Subkeys of this key have the names of network printing monitors. The names, as well as any subkeys and values are monitor specific.

Printers	This key does not have a value. Subkeys of this key have the names of installed printers. Each subkey has named values that describe the printer parameters. The printer subkeys can each contain a subkey named PrinterDriverData.

ProductOptions	Product type, for example, "WinNt".

ServiceGroupOrder	Order in which the system loads services. The data required for some of the services is stored in the GroupOrderList key.

Session Manager	Global variables used by the session manager and the following subkeys:

Subkey	Contents

DOS Devices

MS-DOS devices, such as "PRN", "AUX", "NUL", "PIPE", "MAILSLOT", and "UNC".

Environment

Environment variables, such as "ComSpec", "Os2LibPath", "LibPath", "Path", "NtVersion", and "WinDir".

KnownDLLs

Directory in which session-manager DLLs are stored and the names of those DLLs. The named values are "DllDirectory", "kernel32", "gdi32", "user32", "rpcrt4", and "advapi32".

Memory Management

Paging options. The named values are "PagedPoolSize", "NonPagedPoolSize", and "PagingFiles".

SubSystems

Available subsystems. The named values are "Required", "Optional", "Debug", "Windows", "Os2", and "Posix".

Setup	Hardware setup options. The named values are "Video", "Pointer", and "Keyboard".

TimeZoneInformation	Named values for time-zone information: "Bias", "StandardName", "StandardStart", "StandardBias", "DaylightName", "DaylightStart", "DaylightBias", and "ActiveTimeBias".

VirtualDeviceDrivers	Virtual-device drivers.

Windows	Directory and system directory for Windows. The named values are "Directory" and "SystemDirectory".

WOW	Options for Windows-on-Windows. The named values are "LogonSwitch", "cmdline", "size", "wowcmdline", and "wowsize".

hivelist	Location of the files that contain registry information. There is value for each hive, giving the path of the file backing that hive.

Services

The Services subkey of the ControlSetnnn key contains information about device drivers, file systems, hardware adapters, and service programs used by the computer.

Each subkey of the Services key is the name of a service (e.g. a device driver) Each subkey has at least four named values: "Type", "Start", "Group", and "ErrorControl". Most driver keys also use either the "Dependencies" or "Tag" value name.

When a subkey of the Services key contains a key, that key is either Linkage or Parameters. The named values of the Linkage key specify link options for the driver; the named values are Bind and Export. The named values for the Parameters key vary according to the device driver.

Select

The Select subkey of the System key contains information about the control set for the local computer. This key contains no subkeys, but it has the following named values.

Named value	Contents

Current	Control set from which the CurrentControlSet key is derived. If this value is 0x1, the key producing CurrentControlSet is ControlSet001.

Default	Default control set. If this value is 0x1, the default control set is ControlSet001.

LastKnownGood	Last control set that successfully started the system. If this value is 0x1, the last control set known to be good is ControlSet001.

Failed	Flag indicating whether the control set identified by the "Default" value successfully started the system. If this value is 0, the default control set was successful. If it is 1, the system could not use the default control set to start, and the "Current" and "LastKnownGood" values identify the control set that was used instead.

System administrators can use these values to verify that applications that write information to the System key are successfully modifying the registry.

Setup

The Setup subkey of the System key contains values that identify the setup type and command line. The named values are "SetupType" and "CmdLine".

Clone

The Clone subkey of the System key is a copy of the control set used to start the system. The system makes the copy before any changes are made to the control set. Making a copy before any changes can occur helps ensure that the computer always has a working control set.

If the system starts successfully, this key is identified by the "LastKnownGood" value. For more information about this value, see Select.

CurrentControlSet

The CurrentControlSet subkey of the System key contains the current configuration information for the local computer. The information in this key is in exactly the same form as the information for ControlSetnnn, which is described in ControlSetnnn.


Structure of HKEY_USERS

The HKEY_USERS key contains a .DEFAULT subkey and one or more subkeys whose names are the security identifiers (SIDs) of the users. The subkeys of the .DEFAULT key are a subset of the subkeys for the users' keys. The information in the .DEFAULT key is assigned to new accounts on the local system.

The registry information for each known user is stored directly in a separate file. By default, these files reside in the ...\SYSTEM32\CONFIG directory of Windows NT.

The HKEY_CURRENT_USER predefined handle is made to refer to the currently logged on user, it is reset each time someone logs on. The description of HKEY_CURRENT_USER in this section includes information that is also relevant for HKEY_USERS.

The HKEY_CURRENT_USER key contains the configuration information that is specific to the current user. This kind of information was previously stored in the WIN.INI initialization file. A user profile (that is, a set of configuration information) is saved for every user that logs on to the local computer. When a user logs on, the user's SID is compared against the known SIDs in the registry. If the system "knows" the SID for the user logging on, the system loads the profile for that user. Otherwise, the system uses the configuration information stored in HKEY_USERS\.DEFAULT.

For more information about security identifiers, see Security.

The HKEY_CURRENT_USER key contains the following keys.

Key	Contents

Console	Subkeys that specify the options and window size for a console. (A console is an interface that provides input and output for character-mode applications.)

Control Panel	Subkeys that describe Windows Control Panel applications.

Environment	Values that specify the user's environment variables.

Keyboard Layout	Value that specifies the current keyboard layout.

Network	Subkeys that specify the redirected device (for example, a drive letter). Each subkey has four named values: "RemotePath", "UserName", "ProviderName", and "ConnectionType".

Printers	Value that specifies the default printer.

Program Groups	Subkeys that describe the user's program groups. (Note that common program groups are stored in HKEY_LOCAL_MACHINE\Software\ProgramGroups.)

Software	Subkeys that describe the user-configurable options of installed software. Every installing application and every application that stores user options writes information to this key.

The following sections describe these keys in more detail.

Console

The Console subkey of the HKEY_CURRENT_USER key contains subkeys that specify the options and window size for a console. The Console key has one standardized subkey: Configuration.

The Configuration key contains named values that describe the configuration of the console. The names of the values are "FillAttr", "CommandRecallBufferSize", "ScreenBufferColumns", "ScreenBufferRows", "WindowColumns", and "WindowRows".

Additional keys describe the configuration of console applications. The key names are the names of the applications, and they vary from system to system.

Control Panel

The Control Panel subkey of the HKEY_CURRENT_USER key contains subkeys that describe Control Panel applications. The following keys are defined.

Key	Contents

Color Schemes	Values that describe the color schemes for the Color Schemes section of the Colors application. The names of the values are the names of the color schemes, for example, "Arizona" and "Bordeaux".

Colors	Values that describe the colors of screen elements, from the Screen Elements section of the Colors application. The names of the values are the names of the screen elements, for example, "Desktop" and "Window Text".

Current	Value that describes the current color setting. The name of this value is "Color Schemes".

Custom Colors	Values that describe any custom colors the user has defined in the Custom Colors section of the Colors application. The names of the values are "ColorA" through "ColorP".

Desktop	Values that describe the settings of the options in the Desktop application. This key has the following values.

Value	Contents

CoolSwitch	Flag that is 1 when the ALT+TAB key combination causes the title and icon for each open application to appear on the screen, providing easy switching between applications. The value is 0 when ALT+TAB cycles through the open applications instead.

CursorBlinkRate	Any integer between 1200 (the slowest blink rate) and 200 (the fastest).

BorderWidth	Width of the border, in pixels.

ScreenSaveTimeOut	Number of seconds of inactivity before the screen saver is activated.

ScreenSaveActive	Flag that is 1 when the screen saver is active and 0 when it is not.

SCRNSAVE.SCR	No data. This value name specifies the file containing the default screen saver; there is no data associated with this value name.

Pattern	Description of the pattern chosen by the user in the Patterns section of the Desktop application. The data is a series of integers that describe the bitmap.

Wallpaper	Name of the bitmap file for the current wallpaper.

TileWallPaper	Flag that is 1 when the wallpaper is tiled and 0 when it is centered.

GridGranularity	Grid granularity, in pixels.

IconSpacing	Icon spacing, in pixels.

IconVerticalSpacing	Icon vertical spacing, in pixels.

IconTitleWrap	Flag that is 1 when the icon titles wrap and 0 when they do not.

IconTitleFaceName	Name of the font used for icon titles.

IconTitleSize	Size of the icon titles, in points.

IconTitleStyle	Style of the icon titles. When this value is 0, the default style is used.

International	Named values that specify settings in the International application. Values that begin with the letter "s" are strings, and values that begin with the letter "i" are integers.

Value	Description

Locale	Locale identifier.

sLanguage	Language.

sCountry	Country.

iCountry	Country code.

sList	List separator.

iMeasure	Flag that is 1 for the English system and 0 for metric.

sDecimal	Character used as a decimal separator.

sThousand	Character used as the separator between every three digits in numbers larger than 999.

iDigits	Default number of digits that follow the decimal separator character in decimal notation.

iLZero	Flag that is 1 if a zero precedes the decimal separator character when a number is less than one and 0 if no zero precedes the character.

sCurrency	Monetary symbol used to denote a currency value. This symbol is a dollar sign ($) in the United States.

iCurrDigits	Number of digits following the decimal separator character in currency values.

iCurrency	Placement of the monetary symbol in relation to the number in a currency value. The following values are defined.

Value	Meaning

0	$1

1	1$

2	$ 1

3	1 $

iNegCurr	Method used to denote a negative currency value. The values are defined.

Value	Meaning

0	($123.45)

1	-$123.45

2	$-123.45

3	$123.45-

4	(123.45$)

5	-123.45$

6	123.45-$

7	123.45$-

8	-123.45 $

9	-$ 123.45

10	123.45 $-

sDate	Character used to separate days, months, and years in dates.

sTime	Character used to separate hours, minutes, and seconds in time values.

sShortDate	Format used to report the short form of the date. The following values are defined.

Value	Meaning

M/d/yy	Month/day/last two digits of year

d/M/yy	Day/month/last two digits of year

yy/M/d	Last two digits of year/month/day

sLongDate	Format used to report the long form of the date. The following values are defined.

Value	Meaning

dddd, MMMM dd, yyyy	Day of week, month and date, year

dddd, dd MMMM, yyyy	Day of week, date and month, year

dddd, yyyy MMMM, dd	Day of week, year and month, date

iDate	Flag that is 0 for the M/d/yy short date format, 1 for the d/M/yy format, and 2 for the yy/M/d format.

iTime	Flag that is 0 for time reporting in a 12-hour format and 1 for a 24-hour format.

iCentury	Flag that is 0 for the year designated with a four-digit number and 1 for the year designated with a two-digit number.

iTLZero	Flag that is 0 for no zero preceding one-digit hours in time values and 1 for a leading zero.

iDayLZero	Flag that is 0 for no zero preceding one-digit days in dates and 1 for a leading zero.

iMonLZero	Flag that is 0 for no zero preceding one-digit months in dates and 1 for a leading zero.

s1159	Flag that is AM to designate that 11:59 is the last time prior to PM.

s2359	Flag that is PM to designate that 23:59 is the last time prior to AM.

Keyboard	Named values for the settings in the Keyboard application. This key has the following values.

Value	Contents

KeyboardSpeed	Keyboard repeat rate. The data is a value from 0 (the slowest rate) to 31 (the fastest).

KeyboardDelay	Delay, in seconds, before the keyboard begins to repeat. The data is a value from 3 (the longest delay) to 0 (the shortest).

InitialKeyboardIndicators	Initial keyboard indicators. The default setting is 0.

MMCPL	Named values specifying the number of applications in Control Panel, the dimensions of the Control Panel window, and the paths to any applications the user has added to Control Panel. The name of this key is derived from "Multimedia Control Panel". This key has the following values.

Value	Contents

NumApps	Number of applications in Control Panel.

X	X-coordinate of the upper left corner of the Control Panel window.

Y	Y-coordinate of the upper left corner of the Control Panel window.

W	Width of the Control Panel window, in pixels.

H	Height of the Control Panel window, in pixels.

Mouse	Named values that correspond to the options in the Mouse application. This key has the following values.

Value	Contents

SwapMouseButtons	Flag that indicates whether the functionality of the mouse buttons has been swapped. If the value is 0, they have not been swapped; if it is "Yes", they have.

DoubleClickSpeed	Duration required between two mouse clicks for them to be considered a double click, in milliseconds. The slowest setting is 900; the fastest setting is 100.

MouseThreshold1	Mouse threshold for mouse button number one, in pixels. (The mouse threshold is the maximum distance the mouse may move during a double-click without causing the system to interpret the event as two single clicks.) The minimum setting is 0; the maximum setting is 4.

MouseThreshold2	Mouse threshold for mouse button number two, in pixels. The minimum setting is 0; the maximum setting is 6.

MouseSpeed	Mouse tracking speed. The slowest setting is 0; the fastest setting is 2.

The data for the mouse-threshold values is set by the system, not by options in the Mouse application.

Patterns	Named values corresponding to the patterns the user can specify in the Desktop application. The names of the values are the names displayed in the Pattern list box.

Screen Saver.name	Named values corresponding to the settings for each of the screen savers. The name portion of the key name identifies the screen saver, for example, "Marquee" or "Stars". The values for each key are dependent on the configuration options for that screen saver.

Sound	A named value, "Beep", whose data is "yes" if the beep is activated.

Environment

The Environment subkey of the HKEY_CURRENT_USER key contains named values corresponding to the "user environment variables" the user can specify in the System application in Control Panel. The name of each value is the name of an environment variable, for example, "tmp" and "include". The data for each value is a path. In earlier versions of Windows, this information was stored in the AUTOEXEC.BAT file.

Keyboard Layout

The Keyboard Layout subkey of the HKEY_CURRENT_USER key contains a value named "Active" that defines the current active keyboard layout. This value is set in the Keyboard Layout list box in the International application in Control Panel.

Network

The Network subkey of the HKEY_CURRENT_USER key contains subkeys that specify the redirected device (for example, a drive letter). Each subkey has four named values: "RemotePath", "UserName", "ProviderName", and "ConnectionType".

Printers

The Printers subkey of the HKEY_CURRENT_USER key contains a named value, "Default", whose data is the name of the default printer.

Program Groups

The Program Groups subkey of the HKEY_CURRENT_USER key contains subkeys that describe the user's program groups. (Note that common program groups are stored in the HKEY_LOCAL_MACHINE\Software\Program Groups key.)

Software

The Software subkey of the HKEY_CURRENT_USER key contains subkeys that describe the configurable settings of installed software. Every installing application that can be customized by the user or that saves its state when it closes should save that information in the Software key. This key contains most of the information that was stored in the WIN.INI initialization file and in private files in earlier versions of Windows.

The name of each key contained by the Software key should have the following form:

Software\CompanyName\ApplicationName\ApplicationVersion[\AnyRequiredSubkeys]

For example, the Windows NT Clock application (CLOCK.EXE) stores configuration information by using the following sequence of key names: Software\Microsoft\Clock. Values associated with the Clock key specify configuration information for the application.

Much of the configuration information for Windows is stored in the Software key as follows: Software\Microsoft\Windows NT\CurrentVersion. The CurrentVersion key contains the following keys.

Key	Contents

Extensions	Values that identify the executable files associated with specified filename extensions. For example, the value that associates filenames that have the .TXT extension with Windows Notepad is named txt; the data for this value is "notepad.exe ^.txt".

Print Manager	A value named "Print Manager" whose data is binary initialization information. This key contains a subkey, Printers. The Printers subkey contains values whose names are the current printers and whose data is also binary initialization information.

Program Manager	Keys that describe the configuration of Program Manager; these keys are Groups, Restrictions, and Settings.

The Groups key contains values that describe the order of the program groups. The values are named "Group1" through "Groupn"; the data for each value is the name of a program group.

The Restrictions key contains values that specify any restrictions for the current user when the user works with Program Manager. The data for each value is a flag in which 1 means the restriction is in force and 0 means that the restriction does not apply. The names of the values are "NoRun", "NoClose", "EditLevel", "Restrictions", "NoFileMenu", and "NoSaveSettings".

The Settings key contains the following values describing the configurable settings for Program Manager.

Value	Contents

MinOnRun	Flag that indicates whether Program Manager should be minimized when it starts. The value is 1 to display Program Manager minimized and is 0 otherwise.

AutoArrange	Flag that indicates whether the icons in Program Manager are arranged automatically. The value is 1 to arrange them automatically and is 0 otherwise.

SaveSettings	Flag that indicates whether the settings are saved when Program Manager terminates. The value is 1 to save the settings and is 0 otherwise.

display.drv	Name of the display driver.

Window	Series of integers specifying the x- and y-coordinates of the upper left corner of the Program Manager window, its width, and its height.

Order	Series of integers that specify the order in which the program groups appear in the Program Manager window. The integers correspond to the group numbers specified by the Group subkey of the Program Manager key.

TrueType	Values corresponding to the TrueType options a user can set in the Fonts application in Control Panel. The "TTEnable" value is a flag that is 1 if TrueType fonts are enabled and 0 otherwise. The "TTonly" value is a flag that is 1 if only TrueType fonts are to be used and is 0 otherwise.

Windows	Values describing some of the configurable options of Windows. The values correspond to the [windows] section of the WIN.INI file. This key has the following values.

Value	Contents

load	Filenames or path and filenames for applications that are run minimized when Windows starts.

run	Filenames or the names of documents that are associated with filenames for applications that are run when Windows starts.

NullPort	Null port.

Programs	List of filename extensions identifying executable files, for example, "com exe bat pif cmd".


Storing Information in the Registry

The registry is an excellent place to store relatively small amounts of initialization and configuration data. Although there are few technical limits to the type and size of data an application can store, there are practical guidelines for registry use that can make a large difference in system efficiency. Configuration and initialization data should be stored in the registry, but other kinds of information should be stored elsewhere.


Storage Space

Generally, data of more than one or two kilobytes (K) should be stored as a file and referred to by using a key in the registry, rather than by being stored as a value. Rather than repeatedly duplicating large pieces of data in the registry, an application should save the data as a file and refer to the file. Executable images should never be stored in the registry, since a user's profile could be used on computers with different types of CPUs.

Storing information in the registry consumes far fewer resources than storing it in a file system. To store a byte of data as a file requires between 512 and 8000 bytes of overhead, depending on the file system. Storage in the registry is much more efficient than this. The following table shows the approximate amounts of storage space required by various parts of the registry:

Component	Approximate size

Security descriptor	20 bytes plus the size of the security descriptor itself

Value	38 bytes plus the value name plus the data

List of values	4 bytes per entry

List of subkeys	4 or 5 bytes per entry

Key	90 bytes plus the preceding items in this table.

A value entry uses much less space than a key, particularly when the size of a security descriptor is taken into account. To save space, applications should group similar data together as a structure and store the structure as a value, rather than storing each of the structure members as a separate key. (Storing the data in binary form allows an application to store data in one value that otherwise would be made up of several incompatible types.) A separate key should be used whenever unique access rights are required, because keys are protected by security descriptors.

The size of a single value entry is limited to one MB. The size of the registry is user-configurable, limited only by system resources. The default registry size limit is one-fourth the size of the system's paged pool.

For this version of Windows NT, no limits are imposed on the amount of information a single application can write to the registry. However, to avoid storage problems later, applications should use the registry only as specified in this section.


Applications and the Registry

Before putting configuration and initialization data into the registry, applications should divide the data into two categories: computer-specific data and user-specific data. By making this distinction, an application can support multiple users, and yet locate user-specific data over a network and use that data in different locations, allowing location-independent profile information.

When the application is installed, it should record the computer-specific data under the HKEY_LOCAL_MACHINE key. In particular, it should create keys for the company name, product name, and version number, as in the following example:

HKEY_LOCAL_MACHINE\Software\CompanyName\ProductName\Version

If the application supports object linking and embedding, it should record that information under HKEY_LOCAL_MACHINE\Software\Classes, as described in Classes.

An application should record user-specific data under the HKEY_CURRENT_USER key, as in the following example:

HKEY_CURRENT_USER\Software\CompanyName\ProductName\

    Version\...

Subkeys of this user-specific Version key are application specific.

In Windows 3.1, the preferred mechanism for changing the registration database was to produce a text file listing the entries and then merge them with the database by using a command-line option with Registry Editor (REGEDIT.EXE). Because key values in the Windows NT registry can be in any data format, this method for changing the registry is not supported in Windows NT.


Using the Registry Functions

An application can open or create a key, query the registry, write to the registry, work with registry files, and delete information from the registry.

Opening, Creating, and Closing Keys

To open or create a key, an application always refers to it as a subkey of a currently open key. The four predefined (HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_USERS, and HKEY_CURRENT_USER) are always open. The following functions are used to open a key.

Function	Description

RegOpenKey	Opens a key. This function is provided for compatibility with Windows version 3.1; it does not enable an application to request specific access rights.

RegOpenKeyEx	Opens a key with specified access rights.

The following functions are used to create a key.

Function	Description

RegCreateKey	Creates or opens a key. This function is provided for compatibility with Windows version 3.1; it does not enable an application to set security attributes.

RegCreateKeyEx	Creates or opens a key with the specified security attributes and access rights.

An application can use the RegCloseKey function to close a key and write the information it contains into the registry. This function does not necessarily write the 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.

Querying the Registry

To query information in the registry, an application typically enumerates the subkeys of a key until it finds a particular one, and then retrieves data from the value or values associated with it.

An application can call one of the following functions to enumerate subkeys.

Function	Description

RegEnumKey	Enumerates subkeys of a specified key.

RegEnumKeyEx	Enumerates subkeys of a specified key and also returns the class of the subkey.

To retrieve detailed information about a particular subkey, an application can call the RegQueryInfoKey function. The RegGetKeySecurity function retrieves a copy of the security descriptor protecting a key.

An application can use the following functions to retrieve the values associated with a key.

Function	Description

RegEnumValue	Enumerates the values for a specified key.

RegQueryValue	Retrieves a value for a specified key. This function was introduced in Windows 3.1, but in that version a key could have only one value and values had no names. Therefore, this function can retrieve the data only for a value that has a NULL name.

RegQueryValueEx	Retrieves the type and data information for a named value. An application typically calls the RegEnumValue function to determine the value names and then the RegQueryValueEx function to retrieve the data for the names.

The RegQueryValue and RegQueryValueExn functions also differ in how they treat unexpanded references to environment variables. If an unnamed value contains an unexpanded environment variable (for example, %PATH%), RegQueryValue expands the variable into the storage buffer provided as one of the parameters. RegQueryValueEx, however, does not expand these references. (Windows NT applications can use the ExpandEnvironmentStrings function to expand environment variables.)

Writing to the Registry

An application can use either the RegSetValue or RegSetValueEx function to associate a value and its data with a key. RegSetValue was introduced in Windows version 3.1 and can work only with strings (the REG_SZ type). RegSetValueEx, however, can write values with any type of data. Either of these functions can create a key and its value at the same time.

To change a key's security, an application can use the RegSetKeySecurity function.

Working with Registry Files

Applications can save part of the registry in a file and then load the contents of the file back into the registry. This is useful when a large amount of information is being manipulated, when many entries are being made in the registry, or when the information is transitory and must be loaded and then unloaded again. Applications that back up and restore parts of the registry are likely to use these registry files.

To save a key and its subkeys and values to a registry file, an application can call the RegSaveKey function. To write the registry file back to the registry, the application can call any of the following functions.

Function	Description

RegLoadKey	Loads registration information from a specified file into a specified subkey under HKEY_USERS or HKEY_LOCAL_MACHINE on the caller's computer or on a remote computer. The function creates the specified subkey. If the specified subkey already exists, the function fails.

After calling this function, an application can use the RegUnLoadKey function to restore the registry to its previous state.

RegReplaceKey	Replaces a key and all its subkeys and values in the registry with the information contained in a specified file. The new information takes effect the next time the system is started.

RegRestoreKey	Loads registry information from a specified file into a specified key on the caller's computer or on a remote computer. 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.

Deleting Information from the Registry

To delete a value from a key, an application can use the RegDeleteValue function. To delete a key it can use the RegDeleteKey function.

A deleted key is not removed until the last handle to it has been closed. Subkeys and values cannot be created under a deleted key.


Enumerating Keys and Values

The following example demonstrates the use of the RegEnumKey, RegEnumValue, and RegQueryInfoKey functions. The hKey parameter passed to each function is the handle of an open key. This key must be opened before the call and closed afterward.

VOID QueryKey(HWND hDlg, HANDLE hKey)

{

    CHAR     achKey[MAX_PATH];

    CHAR     achClass[MAX_PATH] = "";  /* buffer for class name   */

    DWORD    cchClassName = MAX_PATH;  /* length of class string  */

    DWORD    cSubKeys;                 /* number of subkeys       */

    DWORD    cbMaxSubKey;              /* longest subkey size     */

    DWORD    cchMaxClass;              /* longest class string    */

    DWORD    cValues;              /* number of values for key    */

    DWORD    cchMaxValue;          /* longest value name          */

    DWORD    cbMaxValueData;       /* longest value data          */

    DWORD    cbSecurityDescriptor; /* size of security descriptor */

    FILETIME ftLastWriteTime;      /* last write time             */

    DWORD i, j;

    DWORD retCode, retValue;

    CHAR  achValue[MAX_VALUE_NAME];

    DWORD cchValue = MAX_VALUE_NAME;

    CHAR  achBuff[80];

    /* Get the class name and the value count. */

    RegQueryInfoKey(hKey,        /* key handle                    */

        achClass,                /* buffer for class name         */

        &cchClassName,           /* length of class string        */

        NULL,                    /* reserved                      */

        &cSubKeys,               /* number of subkeys             */

        &cbMaxSubKey,            /* longest subkey size           */

        &cchMaxClass,            /* longest class string          */

        &cValues,                /* number of values for this key */

        &cchMaxValue,            /* longest value name            */

        &cbMaxValueData,         /* longest value data            */

        &cbSecurityDescriptor,   /* security descriptor           */

        &ftLastWriteTime);       /* last write time               */

    SetDlgItemText(hDlg, IDE_CLASS, achClass);

    SetDlgItemInt(hDlg, IDE_CVALUES, cValues, FALSE);

    SendMessage(GetDlgItem(hDlg, IDL_LISTBOX),

        LB_ADDSTRING, 0, (LONG) "..");

   /*

    * Loop until RegEnumKey fails. Then get the name of each child

    * key and type it into the box.

    */

    /* Enumerate the child keys. */

    SetCursor(LoadCursor(NULL, IDC_WAIT));

    for (i = 0, retCode = ERROR_SUCCESS;

            retCode == ERROR_SUCCESS; i++) {

        retCode = RegEnumKey(hKey, i, achKey, MAX_PATH);

        if (retCode == (DWORD)ERROR_SUCCESS)

            SendMessage(GetDlgItem(hDlg, IDL_LISTBOX),

                LB_ADDSTRING, 0, (LONG) achKey);

    }

    SetCursor(LoadCursor (NULL, IDC_ARROW));

    /* Enumerate the key values. */

    SetCursor(LoadCursor(NULL, IDC_WAIT));

    if (cValues)

        for (j = 0, retValue = ERROR_SUCCESS;

                j < cValues; j++) {

            cchValue = MAX_VALUE_NAME;

            achValue[0] = '\0';

            retValue = RegEnumValue(hKey, j, achValue,

                &cchValue,

                NULL,

                NULL,    /* &dwType, */

                NULL,    /* &bData,  */

                NULL);   /* &bcData  */

            /* Add each value to a list box. */

            if (!lstrlen(achValue))

                lstrcpy(achValue, "<NO NAME>");

            wsprintf(achBuff, "%d) %s ", j, achValue);

            SendMessage(GetDlgItem(hDlg,IDL_LISTBOX2),

                LB_ADDSTRING, 0, (LONG) achBuff);

        }

    SetCursor(LoadCursor(NULL, IDC_ARROW));

}


Functions

Functions and Messages

Following are the functions and messages used with the registry and initialization files.

Functions

GetPrivateProfileInt

GetPrivateProfileSection

GetPrivateProfileString

GetProfileInt

GetProfileSection

GetProfileString

RegCloseKey

RegConnectRegistry

RegCreateKey

RegCreateKeyEx

RegDeleteKey

RegDeleteValue

RegEnumKey

RegEnumKeyEx

RegEnumValue

RegFlushKey

RegGetKeySecurity

RegLoadKey

RegNotifyChangeKeyValue

RegOpenKey

RegOpenKeyEx

RegQueryInfoKey

RegQueryValue

RegQueryValueEx

RegReplaceKey

RegRestoreKey

RegSaveKey

RegSetKeySecurity

RegSetValue

RegSetValueEx

RegUnLoadKey

WritePrivateProfileSection

WritePrivateProfileString

WriteProfileSection

WriteProfileString

Messages

WM_DEVMODECHANGE

WM_WININICHANGE


String Manipulation and Unicode Overview

About Strings and Unicode

The complexities of an expanding global market for applications written for Microsoft® Windows™ and the difficulty of maintaining extremely large programming projects have forced many developers to manage character strings in increasingly sophisticated ways. This topic documents the ways in which Windows helps developers manipulate strings, gives details about the implementation of national language support in Windows programming, and discusses Unicode, the new global character-encoding system.

The following topics discuss string manipulation and Unicode in Windows NT.

Character Sets

String Manipulation in Windows

Unicode in Windows

Using Strings and Unicode

Window Classes

Subclassing and Automatic Message Translation

Special Characters

Functions Without Unicode Equivalents

Functions

For details about Unicode beyond the scope of this overview, see The Unicode™ Standard: Worldwide Character Encoding, Version 1.0, Volumes 1 and 2, Addison-Wesley Publishing Company: 1991, 1992, ISBN 0201567881.


Character Sets

A character set is a mapping of characters to their identifying numeric values. Most of the character sets commonly used in computers are single-byte character sets in which each character is identified by a value one byte wide. The large number of characters in Asian languages led to the development of multibyte character sets, in particular the double-byte character set (DBCS). Microsoft® Windows NT™ incorporates a new global standard for character encoding: Unicode. The following sections discuss these character sets.

Single-byte Character Sets

A single-byte character set is a mapping of 256 individual characters to their identifying numeric values. The character codes 0x20 through 0x7E represent standardized displayable characters, but the characters represented by the remaining codes vary among character sets. The ASCII character set covers the range 0x00 through 0x7F.

In Windows, the ANSI character set is used in window manager and graphics device interface (GDI), but the MS-DOS file allocation table (FAT) file system uses a character set called the original equipment manufacturer (OEM) character set. Variations on the character sets, called code pages, include different special characters, typically customized for a language or group of languages. The OEM code page generally used in the United States is code page 437.

Applications that use the Win32 application programming interface (API) can use Unicode to avoid the inconsistencies of varied code pages and as an aid in developing easily localized applications. For more information about Unicode, see Unicode.

An application can use the GetACP function to retrieve the ANSI code-page identifier for the system or use the GetOEMCP function to retrieve the OEM code-page identifier.

The OemToChar and OemToCharBuff functions allow an application to convert a character or string from the OEM code page to either the ANSI code page or Unicode. To convert in the other direction, you can use either the CharToOem or CharToOemBuff function. In addition, an application can use the MultiByteToWideChar and WideCharToMultiByte functions to map single-byte character set (SBCS) strings to Unicode and Unicode strings to SBCS strings.

The GetCPInfo function fills a CPINFO structure with information that includes the size, in bytes, of the largest character in the code page and the default character used when a character code is entered that has no corresponding entry in the code page.

Double-byte Character Sets

The double-byte character set (DBCS) is called an expanded 8-bit character set because its smallest unit is a byte. It can be thought of as the ANSI character set for some Asian versions of Windows (particularly the Japanese version). Win32 functions for the Japanese version of Windows accept DBCS strings for the ANSI versions of the functions. However, unlike the handling of Unicode, DBCS character handling requires detailed changes in the character-processing algorithms throughout an application's source code.

An application can use the IsDBCSLeadByte function to determine whether a given character is the first byte in a 2-byte character; this helps identify double-byte character sets. In addition, an application can use the MultiByteToWideChar and WideCharToMultiByte functions to map DBCS strings to Unicode and Unicode strings to DBCS strings.

Unicode

Unicode is a worldwide character-encoding standard. Windows uses it exclusively at the system level for character and string manipulation. Unicode simplifies localization of software and improves multilingual text processing. By implementing it in an application, a developer can enable the application with universal data exchange capabilities for global marketing, using a single binary file for every possible character code.

Unicode defines semantics for each character, standardizes script behavior, provides a standard algorithm for bidirectional text, and defines cross-mappings to other standards. Among the scripts supported by Unicode are Latin, Greek, Han, Hiragana, and Katakana. Supported languages include, but are not limited to, German, French, English, Greek, Chinese, and Japanese.

Unicode can represent all the world's characters in modern computer use, including technical symbols and special characters used in publishing. Because each Unicode character is 16 bits wide, it is possible to have separate values for up to 65,536 characters. Unicode-enabled functions are often referred to as "wide-character" functions.

Win32 functions support applications that use either Unicode or the regular ANSI character set. Mixed use in the same application is also possible. Adding Unicode support to an application is easy, and a developer can even maintain a single set of sources from which to compile an application that supports either Unicode or the Windows ANSI character set.

Win32 functions support Unicode by assigning its strings a specific data type and providing a separate set of entry points and messages to support this new data type. A series of macros and naming conventions make transparent migration to Unicode, or even compiling both non-Unicode and Unicode versions of an application from the same set of sources, a straightforward matter.

Implementing Unicode as a separate data type also enables the compiler's type checking to ensure that only Unicode parameters are used with functions expecting Unicode strings.


String Manipulation in Windows

Many Windows functions duplicate or enhance familiar string-manipulation functions from the standard C library. Many of the enhancements enable Windows functions to work with Unicode or extended character sets. For example, the Windows functions in the following table are identical to standard C functions except that the Windows functions are enhanced for use with Unicode.

Windows function	Standard C function

lstrcat	strcat

lstrcmp	strcmp

lstrcmpi	strcmpi

lstrcpy	strcpy

lstrlen	strlen

The strlen standard C function, for example, always returns the number of bytes in a string, but the lstrlen function returns the number of characters, regardless of whether the characters are 1 or 2 bytes wide.

The following Windows functions differ from standard C functions such as tolower and toupper in that they operate on any character in a character set. By using the CharLower function, for example, a Windows-based application can convert an uppercase U with an umlaut to lowercase. For more information about character sets, see Single-byte Character Sets.

Function	Description

CharLower	Converts a character or string to lowercase.

CharLowerBuff	Converts a character string to lowercase.

CharNext	Moves to the next character in a string.

CharPrev	Moves to the preceding character in a string.

CharUpper	Converts a character or string to uppercase.

CharUpperBuff	Converts a string to uppercase.

The following Windows functions make determinations about a character based on the semantics of the language selected by the user. These functions are Unicode enabled.

Function	Description

IsCharAlpha	Determines whether a character is alphabetic.

IsCharAlphaNumeric	Determines whether a character is alphanumeric.

IsCharLower	Determines whether a character is lowercase.

IsCharUpper	Determines whether a character is uppercase.

The wsprintf and wvsprintf functions are extensions to the standard C functions sprintf and vsprintf. The Windows versions support format specifications unique to Unicode.

String Resources

An application that maintains character strings in resources can be translated into new languages with minimum effort. Instead of searching for strings in the source modules, a developer can simply translate the strings in the resource file and relink the application. In addition, using string resources simplifies creation of Unicode and non-Unicode versions of the application from the same source files.

The LoadString function loads a string resource from an application's executable file. The FormatMessage function loads a string resource and interprets formatting options that may be embedded in the string.

Windows 32-bit resources in binary form are stored in Unicode format. When loading resources, applications can use the Unicode version of the resource functions (LoadStringW, for example) to obtain resources as Unicode data.

Locales and Language Identifiers

A sophisticated application can use Windows functions to retrieve specific information about the language and locale for the system on which the application is installed. This can be important for handling language- and locale-specific strings.

A locale identifier is a language/sub-language identifier and a reserved word combined into a doubleword value. There are two predefined locale identifiers: LOCALE_SYSTEM_DEFAULT, which identifies the system default locale, and LOCALE_USER_DEFAULT, which identifies the locale of the current user. An application can call the GetSystemDefaultLCID and GetUserDefaultLCID functions to retrieve the current locale identifiers. To retrieve the current language identifiers, an application can call the GetSystemDefaultLangID and GetUserDefaultLangID functions. For a list of locale and language identifiers, see Locale Identifiers

The CompareStringW function compares two Unicode strings based on a supplied locale identifier.

The GetLocaleInfoW function can retrieve many different kinds of information about a locale. Locale Identifiers

The GetStringTypeW function retrieves information about a Unicode string on a character-by-character basis.


Unicode in Windows

Win32 API elements that use characters are generally implemented in one of three formats:

A generic version that can be compiled for either ANSI or Unicode

An ANSI version

A Unicode version

The following sections discuss Unicode data types and how they are used in functions and messages; the use of resources, filenames, and command-line arguments; and methods of translating between different types of strings.

Data Types

Most string operations for Unicode can be written by using the same logic used for handling the Windows ANSI character set, except that the basic unit of operation is a 16-bit character instead of an 8-bit byte. The header files provide a number of type definitions that make it easy to create sources that can be compiled for Unicode or for the ANSI character set.

The following example shows the method used in the Win32 header files to define three sets of data types: a set of generic type definitions that can compile for either ANSI or Unicode, and two sets of specific type definitions. The first set of specific type definitions is for use with the existing Windows (ANSI) character set, and the other is for use with Unicode (or wide) characters.

/* Generic types */

#ifdef UNICODE

 typedef wchar_t TCHAR;

#else

 typedef unsigned char TCHAR;

#endif

typedef TCHAR * LPTSTR, *LPTCH;

/* 8-bit character specific */

typedef unsigned char CHAR;

typedef CHAR *LPSTR, *LPCH;

/* Unicode specific (wide characters) */

typedef unsigned wchar_t WCHAR;

typedef WCHAR *LPWSTR, *LPWCH;

The letter T preceding a type definition designates a generic type that can be compiled for either ANSI or Unicode. The letter W preceding a type definition designates a wide-character (Unicode) type. For the actual implementation of this method, see the WINNT.H header file.

An application using generic data types can be compiled for Unicode simply by defining UNICODE before the include statements for the header files. To compile the code for ANSI, omit the UNICODE definition.

Developers are encouraged to use the generic data types, but the specific types exist for applications that require mixed-type control.

Function Prototypes

Function prototypes are also provided in generic, ANSI, and Unicode varieties, as shown below. The generic function prototype consists of the standard function name implemented as a macro. The preprocessor expands each macro into one of the specific function prototypes, depending on whether UNICODE is defined. The letters A (ANSI) and W (wide) are added at the end of the function names in the specific function prototypes. In this example, the generic prototype uses the generic type LPTSTR for the text parameter, but the A and W prototypes use the LPCSTR and LPCWSTR character types, respectively.

SetWindowText(HWND hwnd, LPTSTR lpText);

SetWindowTextA(HWND hwnd, LPCSTR lpText);

SetWindowTextW(HWND hwnd, LPCWSTR lpText);

An application can use the generic function and make Unicode dependent on whether the UNICODE option is used to compile the code, or it can make mixed calls by using the explicit function names ending with A and W.

This three-prototype approach applies to all functions with text arguments. Always use a generic function prototype with the generic string and character types. All function names that end with an uppercase W take wide-character arguments.

Some functions exist only in wide-character versions and can be used only with the appropriate data type.

The reference material for each Unicode-enabled function is labeled with a globe bitmap. If the function exists as a macro that the preprocessor must expand into an ANSI or Unicode form, only the macro form is documented.

Note:	Whenever a function has a length parameter for a character string, the length should be given as a count of characters (TCHAR units) in the string. However, functions that require or return pointers to untyped memory blocks, such as the GlobalAlloc function, are exceptions.

Messages

Although applications generally use the same window class, messages between windows of different classes are transparently translated by the system.

Even though a window function is implemented to receive messages in Unicode or ANSI format, the window procedure can still send messages or call functions of either type.

The following messages have text arguments and are subject to automatic text translation. (For information about automatic translation, see Subclassing and Automatic Message Translation.

CB_ADDSTRING	WM_ASKCBFORMATNAME

CB_DIR	WM_CHAR

CB_FINDSTRING	WM_CHARTOITEM

CB_GETLBTEXT	WM_CREATE

CB_INSERTSTRING	WM_DEADCHAR

CB_SELECTSTRING	WM_DEVMODECHANGE

WM_GETTEXT

EM_GETLINE	WM_MDICREATE

EM_REPLACESEL	WM_MENUCHAR

EM_SETPASSWORDCHAR	WM_NCCREATE

WM_SETTEXT

LB_ADDFILE	WM_SYSCHAR

LB_ADDSTRING	WM_SYSDEADCHAR

LB_DIR	WM_WININICHANGE

LB_FINDSTRING

LB_GETTEXT

LB_INSERTSTRING

LB_SELECTSTRING

String Functions

All of the string functions listed in this section exist in ANSI and Unicode implementations to support ANSI and Unicode arguments. There are, however, subtle differences among some of them.

The following string functions do not require special comment; their ANSI and Unicode implementations work identically.

CharNext

CharPrev

lstrcat

lstrcpy

lstrlen

The value returned by the lstrlen function is always the number of characters, regardless of whether the ANSI or Unicode form is used.

The following string functions are sensitive to the locale of the current thread (as derived from the locale the user selects in Control Panel). The lstrcmp and lstrcmpi functions do not perform byte comparisons like their ANSI C namesakes; they compare strings according to the rules of the selected locale.

CharLower

CharLowerBuff

CharUpper

CharUpperBuff

lstrcmp

lstrcmpi

The following functions convert between the OEM character set and either ANSI or Unicode, depending on which version is used.

CharToOem

CharToOemBuff

OemToChar

OemToCharBuff

The print function wsprintf supports Unicode by providing the following new and changed data types in its format specifications. These format specifications affect the way the wsprintf function interprets the corresponding passed-in parameter.

Format specification	ANSI version	Unicode version

c	CHAR	WCHAR

C	WCHAR	CHAR

hc, hC	CHAR	CHAR

hs, hS	LPSTR	LPSTR

lc, lC	WCHAR	WCHAR

ls, lS	LPWSTR	LPWSTR

s	LPSTR	LPWSTR

S	LPWSTR	LPSTR

The data type for the output text always depneds on the version of the function. Where the data type of the passed-in parameter and of the output text do not agree, wsprintf will perform a conversion from Unicode to ANSI, or vice versa, as required.

For the Unicode version of wsprintf, the format string is Unicode, as is the output text.

Standard C Functions

The standard C libraries contain wide-character versions of the ANSI string functions that begin with the letters str. The wide-character versions of the functions start with the letters wcs (or sometimes _wcs). The Unicode data type is compatible with the wide-character data type wchar_t in ANSI C; this allows access to the wide-character string functions.

Generic functions exist for all standard C string functions. They start with the letters _tcs and are listed in the TCHAR.H header file. These functions use the generic data types TCHAR and TCHAR*

An application must add the following lines to its program in order to use the generic functions and compile for Unicode:

     #define _UNICODE

     #include <tchar.h>

     #include <wchar.h>

Note that both the TCHAR.H and WCHAR.H are required, and that the leading underscore on the _UNICODE variable is also required.

The wcstombs and mbstowcs functions can convert from the character set supported by the standard C library to Unicode and back, with some limitations. For more information about translating strings to and from Unicode, see Translation Between String Types.

The printf function defined in TCHAR.H supports the same format specifications as wsprintf; for details, see String Functions. Similarly, TCHAR.H contains a wprintf function, in which the format string itself is a Unicode string.

Filenames

In Windows, the ANSI character set is used in window manager and GDI; the MS-DOS FAT file system uses the OEM character set. Windows applications that create MS-DOS files have sometimes had to use the CharToOem and OemToChar functions to translate between these character sets. However, the New Technology file system (NTFS) file system is capable of storing filenames in Unicode; no translation is necessary with NTFS.

With Unicode implementations of the file-system functions, it is not necessary to perform translations to and from ANSI and OEM character sets. Instead, a developer can use a single source file to compile non-Unicode versions of an application by providing macros for functions that are not invoked when compiling for Unicode, such as CharToOem and OemToChar.

The special filename characters in MS-DOS are unchanged in Unicode filenames:

"\," "/," ".," "?," "*."

These special characters are in the ASCII range of characters (0x00 through 0x7F) and their Unicode equivalents are simply the same values in a 2-byte form: 0x0000 through 0x007F.

Translation Between String Types

The following Win32 functions translate character strings from one string type to another.

Function	Description

FoldStringW	Translates one wide-character string to another.

LCMapStringW	Maps a character string by locale.

ToUnicode	Translates a virtual-key code into a Unicode character.

MultiByteToWideChar	Maps a multibyte string into a wide-character string.

WideCharToMultiByte	Maps a wide-character string into a multibyte string.

The WideCharToMultiByte and MultiByteToWideChar functions are particularly useful for applications that support several string types. ANSI C also defines the conversion functions wcstombs and mbstowcs, but they can only convert to and from the character set supported by the standard C library.

Command-line Arguments

An application can use the GetCommandLine function to retrieve Unicode command-line arguments by calling it as a Unicode function.


Using Strings and Unicode

This section describes how to perform the following tasks:

Use generic data types to convert code so that it can be compiled for either ANSI or Unicode from a single source file

Register window classes for ANSI and Unicode applications

Subclass

Use automatic message translation

Use characters with special meanings in Unicode

Work with functions that have no Unicode equivalents

Using Generic Data Types

If you use generic data types in your code, it can be compiled for Unicode simply by defining UNICODE before the include statements for the header files. To compile the code for ANSI, omit the UNICODE definition.

To convert code that processes strings so it can be compiled for either ANSI or Unicode, follow these steps.

1	Change all character and string types used for text to TCHAR, LPTSTR, or LPTCH.

2	Be sure that pointers to nontext data buffers or binary byte arrays are coded with the LPBYTE type and not mistakenly with the LPTSTR or LPTCH type. Declare pointers of indeterminate type explicitly as void pointers by using LPVOID, as appropriate.

3	Make pointer arithmetic type independent. Using units of TCHAR size yields an answer in bytes when the UNICODE option is not defined and in words when it is. The following expression actually calculates the size of the string, not a count of its elements.

cCount = lpEnd - lpStart;

Change the expression to the following form to return a type-independent count.

cCount = (lpEnd - lpStart) / sizeof(TCHAR);

There is no need to change a statement like the following one, because the pointer increment points to the next character element.

chNext = *++lpText;

4	Replace literal strings and manifest character constants with macros. Change expressions like the following one.

while(*lpFileName++ != '\\') {

    .

    .

    .

}

Use the TEXT macro as follows in this expression.

while(*lpFileName++ != TEXT('\\')) {

    .

    .

    .

}

Precede a literal string in the Unicode form of a function by the letter L. The TEXT macro causes strings to be evaluated as L"string" when UNICODE is defined, and to "string" otherwise. The following call to the Unicode version of lstrlen demonstrates the use of the L identifier.

cch == lstrlenW(L"hello world");

For easier management, move literal strings into resources, especially if they contain characters outside the ASCII range (that is, 0x00 through 0x7F).

5	Call only the Unicode versions of the standard C library string functions, as listed in Standard C Functions.

6	Change any code that relies on 255 as the largest value for a character.

When you compile code that you have changed as outlined above, the compiler creates the same binary file as it did before you made the changes. When you compile the code using the UNICODE option, however, it is compiled as a Unicode application.


Registering Window Classes

A window class is supported by a window procedure. You can register a window class by using either the RegisterClassA or RegisterClassW function. If you register the window class by using RegisterClassA, the application tells the system that the windows of the created class expect messages with text or character parameters to use the ANSI character set; if you register it by using RegisterClassW, the application requests that the system pass text parameters of messages as Unicode. The IsWindowUnicode function enables applications to query the nature of each window.

The following example shows how to register an ANSI window class and a Unicode window class and how to write the window procedures for both cases. For the purposes of this example, all functions and structures are shown with the specific A or W data types. Using the techniques explained in Using Generic Data Types, you could alternatively write this example by using generic data types, so that it could be compiled as either ANSI or Unicode, depending on whether UNICODE is defined.

/* Register an ANSI window class. */

WNDCLASSA AnsiWndCls;

AnsiWndCls.style         = CS_DBLCLKS | CS_PARENTDC;

AnsiWndCls.lpfnWndProc   = (WNDPROC)AnsiWndProc;

AnsiWndCls.cbClsExtra    = 0;

AnsiWndCls.cbWndExtra    = 0;

AnsiWndCls.hInstance     = hmodUser;

AnsiWndCls.hIcon         = NULL;

AnsiWndCls.hCursor       = LoadCursor(NULL, (LPTSTR)IDC_IBEAM);

AnsiWndCls.hbrBackground = NULL;

AnsiWndCls.lpszMenuName  = NULL;

AnsiWndCls.lpszClassName = "TestAnsi";

RegisterClassA(&AnsiWndCls);

/* Register a Unicode window class. */

WNDCLASSW UnicodeWndCls;

UnicodeWndCls.style         = CS_DBLCLKS | CS_PARENTDC;

UnicodeWndCls.lpfnWndProc   = (WNDPROC)UniWndProc;

UnicodeWndCls.cbClsExtra    = 0;

UnicodeWndCls.cbWndExtra    = 0;

UnicodeWndCls.hInstance     = hmodUser;

UnicodeWndCls.hIcon         = NULL;

UnicodeWndCls.hCursor       = LoadCursor(NULL,(LPTSTR)IDC_IBEAM);

UnicodeWndCls.hbrBackground = NULL;

UnicodeWndCls.lpszMenuName  = NULL;

UnicodeWndCls.lpszClassName = L"TestUnicode";

RegisterClassW(&UnicodeWndCls);

The following example shows the difference between handling the WM_CHAR message in an ANSI window procedure and a Unicode window procedure.

/* ANSI Window Procedure */

LONG AnsiWndProc(HWND hwnd, UINT message,

                 WPARAM wParam, LPARAM lParam)

{

    /* Dispatch the messages that can be received. */

    switch (message) {

        case WM_CHAR:

            /*

             * wParam - the value of the key

             * lParam - (not used in this example)

             */

            if (lstrcmpA("Q", (LPCSTR) wParam)) {

                 .

                 .

                 .

            }

            else {

                 .

                 .

                 .

            }

            break;

        .

        . /* process other messages */

        .

    }

}

/* Unicode Window Procedure */

LONG UniWndProc(HWND hwnd, UINT message,

    WPARAM wParam, LPARAM lParam)

{

    /* Dispatch the messages that can be received. */

    switch (message) {

        case WM_CHAR:

            /*

             * wParam - the value of the key

             * lParam - (not used in this example)

             */

            if (lstrcmpW(L"Q", (LPCWSTR) wParam)) {

                 .

                 .

                 .

            }

            else {

                 .

                 .

                 .

            }

            break;

        .

        . /* process other messages */

        .

    }

}

All text in messages received by AnsiWndProc will be composed of ANSI characters, and all text in messages received by UniWndProc will be composed of Unicode characters.


Subclassing and Message Translation

Subclassing and Automatic Message Translation

Subclassing is 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. The system automatically translates messages into ANSI or Unicode form, depending on the form of the function that subclassed the window procedure.

The following call to the SetWindowLongA function subclasses the current window procedure associated with the window identified by the hwnd parameter. The new window procedure, NewWndProc, will receive messages with text in ANSI format.

OldWndProc = (WNDPROC) SetWindowLongA(hwnd,

    GWL_WNDPROC, (LONG)NewWndProc);

When NewWndProc has finished processing a message, it uses the CallWindowProc function as follows to pass the message to OldWndProc.

CallWindowProc(OldWndProc, hwnd, uMessage, wParam, lParam);

If OldWndProc was created with a class style of UNICODE, messages will be translated from the ANSI form received by NewWndProc into Unicode.

Similarly, a call to the SetWindowLongW function would subclass the current window procedure with a window procedure that expects Unicode text messages. Message translation, if necessary, is performed during the processing of the CallWindowProc function.


Using Special Characters in Unicode

There are a few special characters and characters with unusual meanings in Unicode text strings. To avoid unexpected problems with these characters, use the rules in the following sections.

Null-terminated Strings

Always cast zero to TCHAR when using null-terminated strings. The code 0x0000 is the Unicode string terminator for null-terminated strings. A single null byte is not sufficient for this code, because many Unicode characters contain null bytes as either the high or the low byte. An example is the letter A, for which the character code is 0x0041.

Byte-order Mark

Always prefix a Unicode plain text file with a byte-order mark. Because Unicode plain text is a sequence of 16-bit codes, it is sensitive to the byte ordering used when the text was written.

A byte-order mark is not a control character that selects the byte order of the text; it simply informs an application receiving the file that the file is byte ordered.

Ideally, all Unicode text would follow only one set of byte-ordering rules. This is not possible, however, because microprocessors differ in the position of the least significant byte: Intel® and MIPS® processors have the least significant byte first; Motorola processors (and byte-reversed Unicode files) have it last. With only a single set of byte-ordering rules, users of one type of microprocessor would be forced to swap the byte order every time a plain text file is read from or written to, even if the file is never transferred to another system based on a different microprocessor.

The preferred place to specify byte order is in a file header, but text files do not have headers. Therefore, Unicode has defined a character (0xFEFF) and a noncharacter (0xFFFE) as byte-order marks. They are mirror byte-images of each other.

Since the sequence 0xFEFF is exceedingly rare at the outset of regular non-Unicode text files, it can serve as an implicit marker or signature to identify the file as a Unicode file. Applications written to read both Unicode and non-Unicode text files should use the presence of this sequence as a near-certain indicator that the file is a Unicode file. (Compare this technique to using the MS-DOS EOF marker to terminate text files.)

When an application finds 0xFEFF at the beginning of a text file, it typically processes the file as though it were a Unicode file, although it may also perform further heuristic checks to verify that this is true. Such a check could be as simple as a test of whether the variation in the low-order bytes is much higher than the variation in the high-order bytes. For example, if ASCII text is converted to Unicode text, every second byte is zero. Also, checking both for the linefeed and carriage-return characters (0x000A and 0x000D) and for even or odd file size can provide a strong indicator of the nature of the file.

When an application finds 0xFFFE at the beginning of a text file, it interprets it to mean the file is a byte-reversed Unicode file. The application can either swap the order of the bytes or alert the user that an error has occurred.

The Unicode byte-order mark character is not found in any code page, so it disappears if data is converted to ANSI. Unlike other Unicode characters, it is not replaced by a default character when it is converted. If a byte-order mark is found in the middle of a file, it is not interpreted as a Unicode character and has no effect on text output.

The Unicode value 0xFFFF is illegal in plain text files and cannot be passed between Windows functions. The value 0xFFFF is reserved for an application's private use.

Escape Sequences and Control Characters

Translate escape sequences character by character into Unicode. When an ASCII plain text file is converted to Unicode, there is a chance that it will subsequently be converted back to ASCII. Converting escape sequences into Unicode on a character-by-character basis, rather than as a single 2-byte characters makes it possible to perform the reverse conversion without recognizing and parsing the escape sequences as such. For example, ESC+A should become 0x001B (ESC), 0x0041 (A), rather than 0x411B.

The first 32 sixteen-bit characters in Unicode are intended for the 32 control characters. This approach supports the existing use of control characters for formatting purposes--that is, Unicode applications can treat these control characters in exactly the same way as they treat their ASCII equivalents.

Line and Paragraph Separators

Use the line-separator character (0x2028) and the paragraph-separator character (0x2029) to divide plain text. A new line is begun after each line separator. A new paragraph is begun after each paragraph separator.

Because these are separator codes, it is not necessary to start the first line or paragraph in the file with them, or to end the last line or paragraph with them. (Doing so would indicate that there is an empty line or paragraph in that location.)

The line separator can be used to indicate an unconditional end of line. However, line separators do not correspond to the carriage-return and linefeed characters, or to the carriage-return-linefeed character combination; they must be processed separately from carriage return and linefeed characters.

The paragraph separator can be inserted between paragraphs of text. This allows plain text files to be created that can be formatted with different line widths on different systems. The receiving system can ignore any line breaks and break paragraphs only at the paragraph separators.

ASCII Control Codes 0x000D and 0x000A

The Unicode standard does not prescribe a specific meaning for the control codes 0x000D (carriage return) and 0x000A (linefeed). There is no requirement that these codes be used in combination, and if used individually, either code may represent either itself only or both codes together. It is entirely up to the application to determine what these codes represent. (Applications have always had to interpret these control codes in ASCII; the Unicode policy is not a change in their use.)

Nonspacing Characters and Diacritics

When breaking lines or otherwise separating text, be sure to keep nonspacing characters with their base characters. Many scripts contain characters that visually combine with other characters on output--for example, the diacritical marks (or "floating accents"). In Unicode, nonspacing characters follow their base character.


Functions Without Unicode Equivalents

Using Functions Without Unicode Equivalents

Windows functions that have not been exported in a Unicode version have typically been replaced by more powerful or extended functions that do support Unicode. If you are porting code that calls the OpenFile function, for example, you can support Unicode by using the CreateFile or CreateFileEx function instead.

If a function has no Unicode equivalent, you can map characters to and from 8-bit character sets before and after the function call. For example, the number-formatting functions atoi and itoa use only the digits 0 through 9. Normally, mapping Unicode to 8-bit characters could cause loss of data, but you can avoid this by making your code type independent and conditionalizing the expressions. For example, the following statements are type dependent and should be changed to support Unicode.

char str[4];

num = atoi(str);

These statements could be rewritten as follows to make them type independent.

TCHAR tstr[4];

CHAR strTmp[SIZE];

#ifdef UNICODE

wcstombs(strTmp, (const wchar_t *) tstr, sizeof(strTmp));

num = atoi(strTmp);

#else

num = atoi(tstr);

#endif

In this example, the wcstombs function is the standard C function that translates Unicode to ASCII. The example relies on the fact that the digits 0 through 9 can always be translated from Unicode to ASCII, even if some of the surrounding text cannot. The atoi function stops at any character that is not a digit. You can use the LCMapStringW function if you need to process text that includes the native digits provided for some of the scripts in Unicode.


Functions

Following are the functions used with string manipulation.

CharLower

CharLowerBuff

CharNext

CharPrev

CharToOem

CharToOemBuff

CharUpper

CharUpperBuff

CompareStringW

FoldStringW

FormatMessage

GetACP

GetCPInfo

GetLocaleInfoW

GetOEMCP

GetStringTypeW

GetSystemDefaultLangID

GetSystemDefaultLCID

GetThreadLocale

GetUserDefaultLangID

GetUserDefaultLCID

IsCharAlpha

IsCharAlphaNumeric

IsCharLower

IsCharUpper

IsDBCSLeadByte

IsValidCodePage

LCMapStringW

LoadString

lstrcat

lstrcmp

lstrcmpi

lstrcpy

lstrlen

MultiByteToWideChar

OemToChar

OemToCharBuff

SetThreadLocale

WideCharToMultiByte

wsprintf

wvsprintf

AnsiLower (obsolete)

AnsiLowerBuff (obsolete)

AnsiNext (obsolete)

AnsiPrev (obsolete)

AnsiToOem (obsolete)

AnsiToOemBuff (obsolete)

AnsiUpper (obsolete)

AnsiUpperBuff (obsolete)

OemToAnsi (obsolete)

OemToAnsiBuff (obsolete)


Pipes Overview

About Pipes

A pipe is a communication conduit with two ends: A process with a handle to one end can communicate 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 read or write. The Microsoft® Win32™ application programming interface (API) provides both anonymous (unnamed) pipes and named pipes. This topic describes how to create, manage, and use pipes.

The following topics discuss pipes:

Terms

Anonymous Pipes

Named Pipes

Named Pipe Modes

Named Pipe Operations

The Named Pipe Server Process

Pipe Names

Named Pipe Type and Read Mode

Blocking and Non-blocking Pipe Operations

Synchronous and Overlapped I/O

Write-through to Remote Clients

Pipe Security

Using Anonymous Pipes

Example: A Multi-threaded Server

Example: A Server Using Overlapped I/O

Example: A Server Using Completion Routines

The Named Pipe Client Process

Transactions on Named Pipes

Functions


Anonymous Pipes

An anonymous pipe is an unnamed, one-way pipe that transfers data between a parent process and a child process, or between two child processes of the same parent process. Although it is possible to use anonymous pipes for communication between unrelated processes, it is easier to use named pipes for that purpose (see Named Pipes). Anonymous pipes are always local, and cannot be used for communication over a network.

The CreatePipe function creates an anonymous pipe and returns two handles: one to the read end and one to the write end of the pipe. The read handle has only read access to the pipe, and the write handle has only write access to the pipe. To communicate through the pipe, a handle to one of the ends must be passed to another process. Usually, this is done through inheritance, where a child process inherits a handle from its parent process. The inheritability of these handles is controlled by the creating process in the following ways:

The CreatePipe function specifies a SECURITY_ATTRIBUTES structure. If the bInheritHandle member of this structure is TRUE, the handles can be inherited.

The DuplicateHandle function can change the inheritability of a pipe handle. This enables a process to create a noninheritable duplicate of an inheritable pipe handle, or to create an inheritable duplicate of a noninheritable pipe handle.

The CreateProcess function enables a parent process to specify whether the new child process will inherit all or none of the parent's inheritable handles.

When a child process inherits a handle, the system enables the process to access the pipe referred to by that handle. However, to do so, the process must retrieve the value of the handle. To do this, the parent process must communicate the handle value to the child process. Typically, this is done using the SetStdHandle and GetStdHandle functions, which set and retrieve the standard handles (standard input, standard output, or standard error) of a process. The parent process can specify a pipe handle in a call to SetStdHandle before the child process is created. The current standard handles of the parent process are inherited by the child process. So, when the child process starts up, it can use the GetStdHandle function to retrieve the handle value. The parent process can change its own standard handles without affecting the standard handles of its existing child processes.

To read from the pipe, a process uses the read handle in a call to the ReadFile function. Unless an error occurs, ReadFile does not return until the specified number of bytes has been read or all handles to the write end of the pipe have been closed.

To write to the pipe, a process uses the write handle in a call to the WriteFile function. WriteFile does not return until the specified number of bytes has been written or an error occurs. If the pipe's buffer is full and bytes remain to be written, WriteFile does not return until some other process or thread reads from the pipe, making more buffer space available. CreatePipe enables the creating process to specify a buffer size for the pipe, or it can use the default buffer size.

Asynchronous (overlapped) read and write operations are not supported for anonymous pipes. This means that the ReadFileEx and WriteFileEx functions cannot be used with anonymous pipes. The lpOverLapped parameter of the ReadFile and WriteFile functions is ignored when used with an anonymous pipe.

An anonymous pipe exists until all handles to both read and write ends of the pipe are closed by the CloseHandle function.


Named Pipes

A named pipe is a one-way or two-way pipe for communicating between a server process and one or more client processes. A server process specifies a name when it calls the CreateNamedPipe function to create one or more instances of a named pipe. All instances of a named pipe share the same pipe name, but each instance has its own buffers and handles and provides a separate conduit for client-server communication. When a client process specifies a pipe name in the CreateFile or CallNamedPipe functions, it connects to an instance of the pipe. This enables multiple client processes to use the same named pipe simultaneously.

Subject to security checks, any client process can access a named pipe, making it easy to communicate between related or unrelated processes. Named pipes can be used locally to communicate between processes on the same machine or across a network, to connect processes on different machines.

In Windows NT, the difference between client and server processes is greatly diminished, because any Windows NT process can act as both a server and a client, making peer-to-peer communication possible. As used here, server refers to a process that uses CreateNamedPipe to create a named pipe, and client refers to a process that uses CreateFile or CallNamedPipe to connect to an instance of a named pipe.


Pipe Names

Each named pipe must have a unique name that distinguishes it from other named pipes. Use the following form when specifying the name of a pipe in the CreateNamedPipe, CreateFile, WaitNamedPipe, or CallNamedPipe functions.

\\servername\pipe\pipename

The server process cannot create a pipe on a computer, so CreateNamedPipe must use a period to indicate the local computer--for example:

\\.\pipe\pipename

Client processes using CreateFile, WaitNamedPipe, or CallNamedPipe can use a period to specify a local pipe, but must specify the name of a server to open a pipe on a remote computer.

The pipename part of the name can include any character, including numbers and special characters. The entire pipe name string can be up to 256 characters long. Pipe names are not case sensitive.


Named Pipe Modes

A number of modes associated with a named pipe or with a handle to a named pipe affect the use and behavior of the pipe. Some of these modes can be set differently for each handle to a pipe, while others must be the same for all handles to a pipe.

The server process specifies the following modes when it calls the CreateNamedPipe function. The type and access modes must be the same for all instances of a pipe.

Mode	Meaning

Type	PIPE_TYPE_BYTE or PIPE_TYPE_MESSAGE. The type mode determines whether data is written to a named pipe as a stream of messages or as a stream of bytes. If no type is specified in CreateNamedPipe, the default is PIPE_TYPE_BYTE. A handle to a byte pipe must be in byte-read mode. A handle to a message pipe can be in either byte-read or message-read mode. For more information about pipe types, see Named Pipe Type and Read Mode.

Access	PIPE_ACCESS_INBOUND, PIPE_ACCESS_OUTBOUND, or PIPE_ACCESS_DUPLEX. This is equivalent to specifying the read or write access of the server's handles to the pipe, where inbound is equivalent to GENERIC_READ access, outbound is equivalent to GENERIC_WRITE access, and duplex is equivalent to GENERIC_READ | GENERIC_WRITE access. Client processes using CreateFile to connect to a named pipe must specify an access compatible with the access specified by the server. For example, a client must specify GENERIC_READ access for an outbound pipe.

The remaining pipe modes can differ for each pipe handle. This means that the client and server ends of the same pipe instance can use different modes. The CreateNamedPipe function sets all of these modes for the pipe handles of a server. The CreateFile function supports setting the overlapped and write-through modes for the pipe handles of a client. Both client and server processes use the SetNamedPipeHandleState function to set the read and wait modes of a pipe handle.

Mode	Meaning

Read	PIPE_READMODE_BYTE or PIPE_READMODE_MESSAGE. In byte-read mode, data is read from a named pipe as a stream of bytes. In message-read mode, data is read from a named pipe as a stream of messages. Only byte-read mode is allowed for byte-type pipes. Either byte- or message-read mode is allowed for message-type pipes. The default is byte-type mode, if no read mode is specified in CreateNamedPipe. For more information about read modes, see Named Pipe Type and Read Mode.

Wait	PIPE_WAIT or PIPE_NOWAIT. In blocking-wait mode, the ReadFile, WriteFile, and ConnectNamedPipe functions wait indefinitely--in some situations--for a process on the other end of the pipe to perform an action. In nonblocking-wait mode, the functions return if they cannot finish their operations immediately. For more information about wait modes, see Blocking and Non-blocking Pipe Operations.

Overlapped	FILE_FLAG_OVERLAPPED. In overlapped mode, the functions that perform read, write, and connect operations that take a significant time to be completed can return immediately. This enables the thread to perform other operations while the time-consuming operation executes in the background. For more information about overlapped mode, see Synchronous and Overlapped I/O.

Write-through	FILE_FLAG_WRITE_THROUGH. In write-through mode, the functions that write to a named pipe do not return until the data written is transmitted across the network and in the pipe's buffer on the remote computer. This mode affects only write operations on byte-type pipes, and then only when the client and server processes are on different computers. If write-through mode is not enabled, the write function returns successfully, even if the data is not transmitted. For more information about write-through modes, see Write-through to Remote Clients.

The initial read mode for a pipe handle is specified when a server process calls CreateNamedPipe. If PIPE_READMODE_BYTE is specified, or if no read mode is specified, the pipe handle is created in byte-read mode. If both PIPE_READMODE_MESSAGE and PIPE_TYPE_MESSAGE are specified, the handle is created in message-read mode. For a client process, a pipe handle returned by the CreateFile function is always in byte-read mode initially. Both client and server processes can use the SetNamedPipeHandleState function to change the read mode of a pipe handle. For a message-type pipe, the read mode can be different for server and client handles to the same pipe instance.


Named Pipe Operations

The first time the server calls CreateNamedPipe, the function specifies the maximum number of instances of the pipe that can exist simultaneously. Limited by this maximum, the server can call CreateNamedPipe repeatedly to create additional instances of the pipe. If the function succeeds, each call returns a handle to the server end of a named pipe instance.

As soon as a pipe instance is created, a client process can connect to it by calling the CreateFile or CallNamedPipe functions. If a pipe instance is available, CreateFile returns a handle to the client end of the pipe instance. If no instances of the pipe are available, a client process can use the WaitNamedPipe function to wait for one to become available.

A client process can also use the CallNamedPipe function to combine into a single operation the functions that connect to a pipe instance (waiting for one to be available, if necessary), write a message, read a message, and close its pipe handle. The CallNamedPipe function can be used only by a client process and only with a message-type pipe.

A server process specifies a handle to a pipe instance in a call to the ConnectNamedPipe function to determine when a client process is connected to it. If the pipe handle is in blocking mode, the ConnectNamedPipe operation does not return until a client is connected.

Client and server processes can call one of several functions--in addition to CallNamedPipe--to read from and write to a named pipe. The behavior of these functions depends on the type of pipe and the modes in effect for the specified pipe handle.

The ReadFile and WriteFile functions can be used with either byte-type or message-type pipes.

The ReadFileEx and WriteFileEx functions can be used with either byte-type or message-type pipes, if the pipe handle was opened for overlapped operations.

The PeekNamedPipe function can be used to read without removing the contents of either a byte-type or a message-type pipe. PeekNamedPipe can also return additional information about the pipe instance.

The TransactNamedPipe function can be used with message-type pipes if the pipe handle of the calling process is set to message-read mode. This function writes a request message and reads a reply message in a single operation, enhancing network performance.

For a pipe handle in byte-read mode, a read operation is completed successfully when all available bytes in the pipe are read or when the specified number of bytes is read.

For a pipe handle in message-read mode, a ReadFile or ReadFileEx operation is completed successfully only when the entire message is read. If the specified number of bytes to read is less than the size of the next message, the function reads as much of the message as possible before returning FALSE (with the GetLastError function returning ERROR_MORE_DATA). In this case, you can read the remainder of the message by making additional calls to ReadFile, ReadFileEx, or PeekNamedPipe. Note that PeekNamedPipe returns TRUE after reading a complete or partial message, and reports the number of bytes remaining in a partially read message.

For a message-type pipe with multiple unread messages, a read operation using a message-read pipe handle returns after reading one message. An operation using a byte-read handle does not distinguish between the messages--it reads all available bytes up to the specified number.

When a client and server finish using a pipe instance, the server calls the DisconnectNamedPipe function to close the connection to the client process. This function makes the client's handle invalid (if it has not already been closed). Any unread data in the pipe is discarded. To ensure that all bytes or messages written to the pipe are read by the client, the server first calls the FlushFileBuffers function, which does not return until the client has read all data from the pipe. After the client is disconnected, the server calls the CloseHandle function to close its handle to the pipe instance. Alternatively, the server can use ConnectNamedPipe to enable a new client to connect to this instance of the pipe.

A process can retrieve information about a named pipe by calling the GetNamedPipeInfo function, which returns the type of the pipe, the size of the input and output buffers, and the maximum number of pipe instances that can be created. The GetNamedPipeHandleState function reports on the read and wait modes of a pipe handle, the current number of pipe instances, and additional relevant information for pipes that communicate over a network. The SetNamedPipeHandleState function sets the read mode and wait modes of a pipe handle. For client processes communicating with a remote server, the function also controls the maximum number of bytes to collect or the maximum time to wait before transmitting a message (assuming the client's handle was not opened with write-through mode enabled).


The Named Pipe Server Process

The simplest server process can use the CreateNamedPipe function to create a single instance of a pipe, connect to a single client, communicate with the client, disconnect the pipe, close the pipe handle, and terminate. Typically, however, a server process must communicate with multiple client processes. A server process can use a single pipe instance by connecting to and disconnecting from each client in sequence, but performance would be poor. To handle multiple clients simultaneously, the server process must create multiple pipe instances.

The Win32 API supports three basic strategies for servicing multiple pipe instances. The server process can do the following.

Create multiple threads (and/or processes) with a separate thread for each instance of the pipe. For an example of a multithreaded server process, see Example: A Multi-threaded Server.

Overlap operations by specifying an OVERLAPPED structure in the ReadFile, WriteFile, and ConnectNamedPipe functions. For an example of a server process that uses overlapped operations, see Example: A Server Using Overlapped I/O.

Overlap operations by using the ReadFileEx and WriteFileEx functions, which specify a completion routine to be executed when the operation is complete. For an example of a server process that uses completion routines, see Example: A Server Using Completion Routines.

The multithreaded server strategy is easy to write, because the thread for each instance handles communications for only a single client. The system allocates processor time to each thread as needed. But each thread uses system resources, which is a potential disadvantage for a server that handles a large number of clients. Other complications occur if the actions of one client necessitate communications with other clients (as with a network game program, where a move by one player must be communicated to the other players).

With a single-threaded server, it is easier to coordinate operations that affect multiple clients, and it is easier to protect shared resources (for example, a database file) from simultaneous access by multiple clients. The challenge of a single-threaded server is that it requires the coordination of overlapped operations in order to allocate processor time for handling the simultaneous needs of the clients.


Named Pipe Type and Read Mode

The type of a pipe determines how data is written to a named pipe, and the read mode determines how data is read from a named pipe. Data can be transmitted through a named pipe as either a stream of bytes or as a stream of messages. When using the CreateNamedPipe function to create an instance of a named pipe, the server process specifies the type, the type it must specify for all instances.

A byte pipe is created if PIPE_TYPE_BYTE is specified, or by default if no type is specified. This means that data is written to the pipe as a stream of bytes, and the system does not differentiate between the bytes written in different write operations. A handle to a byte-type pipe can be in byte-read mode only.

A message type pipe is created if PIPE_TYPE_MESSAGE is specified. This means that the system treats each write operation to the pipe as a message unit. A handle to a message type pipe can be in either byte or message read mode.


Blocking and Non-blocking Pipe Operations

Blocking and Nonblocking Pipe Operations

The wait mode (blocking or nonblocking) of a pipe handle determines whether the ReadFile, WriteFile, and ConnectNamedPipe functions return immediately in situations that would otherwise require an indefinite wait. By default, all named pipe handles returned by the CreateNamedPipe or CreateFile functions are created with blocking mode enabled. Nonblocking mode can be enabled for a server's pipe handle by specifying PIPE_NOWAIT in CreateNamedPipe. Both server and client processes can change a pipe handle's wait mode by specifying either PIPE_WAIT or PIPE_NOWAIT in a call to the SetNamedPipeHandleState function.

Note that nonblocking mode is supported for compatibility with Microsoft® LAN Manager version 2.0, and should not be used to achieve overlapped input and output (I/O) with named pipes. Instead, use overlapped I/O, which enables time-consuming ReadFile, WriteFile, and ConnectNamedPipe operations to execute in the background after the function returns. For more information about overlapped I/O, see Synchronous and Overlapped I/O.

A ReadFile operation is affected by the wait mode of a pipe handle when the pipe is empty. With a blocking handle, the operation is not completed successfully until data is available from a thread writing to the other end of the pipe. Using a nonblocking handle, the function returns FALSE immediately and the GetLastError function returns ERROR_NO_DATA.

A WriteFile operation is affected by a pipe handle's wait mode when there is insufficient space in the pipe's buffer to hold all the data. With a blocking handle, the write operation cannot succeed until sufficient space is created in the buffer by a thread reading from the other end of the pipe. With a nonblocking handle, the write operation returns TRUE immediately, without writing any bytes (for a message-type pipe) or after writing as many bytes as the buffer holds (for a byte-type pipe).

A ConnectNamedPipe operation is affected by the wait mode of a pipe handle when there is no client connected or waiting to connect to the pipe instance. With a blocking handle, the connect operation does not succeed until a client process connects to the pipe instance by calling either CreateFile or CallNamedPipe. With a non-blocking handle, the connect operation returns FALSE immediately and the GetLastError function returns ERROR_PIPE_LISTENING.

The wait mode of a pipe handle does not affect read or write operations when using the TransactNamedPipe or CallNamedPipe functions.


Synchronous and Overlapped I/O

Synchronous and Overlapped Input and Output

The Win32 API supports both synchronous and asynchronous (overlapped) operations on named pipes. The ReadFile, WriteFile, TransactNamedPipe, and ConnectNamedPipe functions can run either synchronously or asynchronously. The ReadFileEx and WriteFileEx functions can run only asynchronously. When functions run synchronously, they do not return until the operation is finished. This means that the execution of the calling thread can be blocked for an indefinite period while it waits for a time-consuming operation to finish. When functions run asynchronously, they return immediately even before their operations are finished. This enables a time-consuming operation to be executed in the background while the calling thread is free to perform other tasks. In the Win32 API, this asynchronous execution is known as overlapped I/O.

Overlapped operations make it possible for one pipe to read and write data simultaneously and for a single thread to perform simultaneous I/O operations on multiple pipe handles. This enables a single-threaded server process to handle communications with multiple client processes efficiently . For examples that illustrate overlapped operations by a server process, see Example: A Server Using Overlapped I/O, and Example: A Server Using Completion Routines.

For a server process to use synchronous operations to communicate with more than one client, it must create a separate thread for each client process. This makes it possible for one or more threads to run while other threads are waiting. For an example of a multithreaded server process that uses synchronous operations, see Example: A Multi-threaded Server.

To enable overlapped operations on a named pipe, specify the FILE_FLAG_OVERLAPPED flag when the handle is created (by the CreateNamedPipe function for a server process or the CreateFile function for a client process). If this flag is not specified, overlapped mode is disabled. The overlapped mode of a pipe handle cannot be changed after the pipe handle has been created. The overlapped mode can be different for server and client handles to the same pipe instance.

The ReadFile, WriteFile, TransactNamedPipe, and ConnectNamedPipe functions can be performed asynchronously only if the specified pipe handle has overlapped mode enabled and a pointer to an OVERLAPPED structure is specified. If the OVERLAPPED pointer is NULL, the operation is performed synchronously, even though the pipe handle has overlapped mode enabled. When the functions are performed asynchronously, one of the following occurs:

If the operation is complete when the function returns, the return value indicates the success or failure of the operation. If an error occurs, the return value is FALSE and the GetLastError function returns something other than ERROR_IO_PENDING.

If the operation has not finished when the function returns, the return value is FALSE and GetLastError returns ERROR_IO_PENDING. In this case, the calling thread must wait until the operation has finished. The calling thread must then call the GetOverlappedResult function to determine the results.

The hEvent member of the specified OVERLAPPED structure must contain a handle to a manual reset--not an auto reset--event object. This is a synchronization object created by the CreateEvent function. The thread that initiates the overlapped operation uses the event object to determine when the operation is finished.

An event object is either in a signaled or not-signaled state. If an overlapped function returns before its operation has finished, the system sets the state of the event object to not-signaled. When the operation is finished, the system sets the state to signaled. The thread can detect the object's state by specifying a handle to the event object in a call to one of the wait functions: WaitForSingleObject, WaitForMultipleObjects, WaitForSingleObjectEx or WaitForMultipleObjectsEx. These functions do not return until the state of a specified object is signaled or until a time-out interval has elapsed. For the wait functions that wait for multiple objects, the function's return value indicates which of the objects is signaled. This enables a server process to use a loop that does the following:

1	Specifies multiple event objects in a call to WaitForMultipleObjects or WaitForMultipleObjectsEx, and then waits for one of the objects to be in a signaled state.

2	Uses the wait function's return value to determine which overlapped operation is finished.

3	Performs the tasks necessary to clean up the completed operation and initiate the next operation for that pipe handle. This may involve starting another overlapped operation for the same pipe handle.

If the hEvent member of the OVERLAPPED structure is a NULL pointer instead of a handle to an event object, the calling thread can use the pipe handle to determine when an overlapped operation has finished. In this case, the system sets the state of the pipe handle to signaled or not-signaled, as described previously for the state of an event object. It is strongly recommended that, rather than relying on the pipe handle, you always use an event object when performing overlapped operations. In particular, you should not use the pipe handle for this purpose if you are performing simultaneous operations on the same handle. The reason for this is that you would have no way of knowing which operation's completion caused the pipe handle to be signaled. When performing simultaneous operations on the same pipe handle, the only safe technique is to use a separate OVERLAPPED structure with its own event object for each operation.

The ReadFileEx and WriteFileEx functions provide another form of overlapped I/O. Unlike the overlapped ReadFile and WriteFile functions, which use an event object to signal completion, the extended functions specify a completion routine. A completion routine is a function that is queued for execution when the read or write operation is finished. The completion routine is not executed until the thread that called ReadFileEx and WriteFileEx enters an alertable wait by calling one of the extended wait functions: WaitForSingleObjectEx, WaitForMultipleObjectsEx, or SleepEx. These functions are like the normal wait functions in that they return when a specified object is in the signaled state or when a time-out interval has elapsed. However, these functions can also perform an alertable wait that occurs when their fAlertable flag is set to TRUE. In an alertable wait, the functions that also return when a ReadFileEx or WriteFileEx completion routine is queued for execution. A server process can use the extended functions to perform a sequence of read and write operations for each client that connects to it. Each read or write operation in the sequence specifies a completion routine, and each completion routine initiates the next step in the sequence.


Write-through to Remote Clients

The write-through mode of a named pipe handle affects the behavior of byte-type pipes when data is transmitted across a network. To enable write-through mode for a named pipe handle, a process specifies the FILE_FLAG_WRITE_THROUGH flag in the CreateNamedPipe function for a server process or in the CreateFile function for a client process. If this flag is not specified, write-through mode is disabled. The write-through mode of a pipe handle cannot be changed after the pipe handle has been created. The write-through mode can be different for server and client handles to the same pipe instance.

If write-through mode is not enabled, the system enhances the efficiency of network operations by buffering data until a minimum number of bytes have accumulated or until a maximum time period has elapsed. This enables multiple write operations to be combined into a single network transmission. This also means that a write operation can be completed successfully when the data is in the outbound buffer but before it is transmitted across the network.

A client process can use the SetNamedPipeHandleState function to control the number of bytes and the time-out period before transmission for a pipe on which write-through mode is disabled.

If write-through mode is enabled, the transmission across the network is not delayed and the write operation is not completed until the data is in the pipe buffer on the remote machine. Write-through mode is useful for applications that require synchronization with every write operation.

The system always performs write operations on message-type pipes as if write-through mode were enabled.


Pipe Security

A server process uses ImpersonateNamedPipeClient to assume the security token of the client process connected to the specified pipe instance. This can be useful in determining whether to grant the request of a client process. For example, a named pipe server can provide access to a database or file system to which the server process has privileged access. When a client process makes a request from the server, the client typically has some lesser level of security access. By assuming the security token of the client, the server can attempt to access the protected database and the system grants or denies the server's access, based on the security level of the client. When finished, the server uses the RevertToSelf function to restore its original security token.


Using Anonymous Pipes

A typical use of anonymous pipes is to create a channel for communication between a parent process and its child process by redirecting the standard input or standard output handles of the child process. To redirect the standard output handle of a child process, the parent process does the following:

1	Calls the GetStdHandle function to get the current standard output handle, which it saves for later use.

2	Calls the CreatePipe function to create an anonymous pipe. This function returns handles to the read and write ends of the pipe.

3	Calls the SetStdHandle function to set its standard output to be the write handle of the pipe.

4	Calls the CreateProcess function to create the child process. The child process inherits the inheritable handles of the parent process. It also inherits the values of the standard handles of its parent process, which it can retrieve using the GetStdHandle function.

5	Calls the CloseHandle function to close the parent's handle to the write end of the pipe. After the child process inherits this handle, the parent process no longer needs its copy of the handle.

6	Calls the ReadFile function to read from the pipe. This operation enables the parent process to read the data written to standard output by the child process.

The child process uses the GetStdHandle function to get its standard output handle, which is actually a handle to the write end of the pipe. The child process then uses the WriteFile function to write its output to the pipe.

Data is written to an anonymous pipe as a stream of bytes. This means that a process reading from a pipe cannot distinguish between the bytes written in separate write operations, unless both reading and writing processes use some protocol that lets the reader know how many bytes to read. Typically, there is no protocol, so the reading process reads from the pipe until all write handles to the pipe are closed, which causes the ReadFile function to return FALSE. When a child process's standard output is redirected, this occurs when the child process calls CloseHandle or terminates (which automatically closes the handle). Note that it is important for the parent process to close its handle to the write end of the pipe before trying to read from the pipe. Otherwise, its ReadFile operation cannot return FALSE because there is still an open handle to the write end of the pipe.

The procedure for redirecting standard input is similar to that for redirecting standard output, except that the pipe's read handle is used for the child's standard input. In this case, the parent process must ensure that the child process does not inherit the pipe's write handle. Otherwise, the ReadFile operation of the child process cannot return FALSE because the child process has an open handle to the write end of the pipe.

The parent process typically creates the read and write handles to the pipe so that they can be inherited by a child process. It does this through CreatePipe, by specifying a SECURITY_ATTRIBUTES structure with its bInheritHandle member set to TRUE. When redirecting a child's standard input, you do not want the child process to inherit the pipe's write handle. The parent process accomplishes this by using the DuplicateHandle function to create a noninheritable duplicate of the handle, and then using CloseHandle to close the inheritable handle.


Example: A Multi-threaded Server

Example: A Multithreaded Server

This example of a multithreaded server process has a main thread that loops continuously, creating a pipe instance and waiting for a client process to connect. When a client process connects, the server process creates a thread to service that client and the loop starts over. It is possible for a client process to connect successfully to the pipe instance in the interval between the CreateNamedPipe and ConnectNamedPipe function calls. If this happens, ConnectNamedPipe returns FALSE, with GetLastError returning ERROR_PIPE_CONNECTED.

The thread created to service each pipe instance reads requests from the pipe and writes replies to the pipe until the client process closes its handle. When this happens, the thread flushes the pipe, disconnects, closes its pipe handle, and terminates.

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <windows.h>

VOID InstanceThread(LPVOID);

VOID GetAnswerToRequest(LPTSTR, LPTSTR, LPDWORD);

int xx = 0;

DWORD main(VOID) {

  BOOL fConnected;

  DWORD dwThreadId;

  HANDLE hPipe, hThread;

  LPTSTR lpszPipename = "\\\\.\\pipe\\mynamedpipe";

  /*

   * Main loop creates an instance of the named pipe, and

   * then waits for a client to connect to it. When the client

   * connects, a thread is created to handle communications

   * with that client, and the loop is repeated.

   */

  for (;;) {

      hPipe = CreateNamedPipe(

          lpszPipename,             /* pipe name          */

          PIPE_ACCESS_DUPLEX,       /* read/write access  */

          PIPE_TYPE_MESSAGE |       /* message type pipe  */

          PIPE_READMODE_MESSAGE |   /* message-read mode  */

          PIPE_WAIT,                /* blocking mode      */

          PIPE_UNLIMITED_INSTANCES, /* max. instances     */

          BUFSIZE,                  /* output buffer size */

          BUFSIZE,                  /* input buffer size  */

          PIPE_TIMEOUT,             /* client time-out    */

          NULL);                    /* no security attr. */

      if (hPipe == INVALID_HANDLE_VALUE)

          MyErrExit("CreatePipe");

      /*

       * Wait for the client to connect; if it succeeds

       * the function returns TRUE. If the function returns FALSE,

       * GetLastError returns ERROR_PIPE_CONNECTED.

       */

      fConnected = ConnectNamedPipe(hPipe, NULL) ?

                   TRUE :

                   (GetLastError() == ERROR_PIPE_CONNECTED);

      if (fConnected) {

          /* Create a thread for this client. */

          hThread = CreateThread(

              NULL,           /* no security attr. */

              0,              /* default stack size   */

              (LPTHREAD_START_ROUTINE) InstanceThread,

              (LPVOID) hPipe, /* thread parameter     */

              0,              /* not suspended        */

              &dwThreadId);   /* returns thread ID    */

          if (hThread == INVALID_HANDLE_VALUE)

              MyErrExit("CreateThread");

      } else

         /* The client could not connect, so close the pipe. */

         CloseHandle(hPipe);

  }

  return 1;

}

VOID InstanceThread(LPVOID lpvParam) {

  CHAR chRequest[BUFSIZE];

  CHAR chReply[BUFSIZE];

  DWORD cbBytesRead, cbReplyBytes, cbWritten;

  BOOL fSuccess;

  HANDLE hPipe;

  /* The thread's parameter is a handle to a pipe instance. */

  hPipe = (HANDLE) lpvParam;

  while (1) {

      /* Read client requests from the pipe. */

      fSuccess = ReadFile(

          hPipe,        /* handle to pipe         */

          chRequest,    /* buffer to receive data */

          BUFSIZE,      /* size of buffer         */

          &cbBytesRead, /* number of bytes read   */

          NULL);        /* not overlapped I/O     */

      if (! fSuccess || cbBytesRead == 0)

          break;

      GetAnswerToRequest(chRequest, chReply, &cbReplyBytes);

      /* Write the reply to the pipe. */

      fSuccess = WriteFile(

         hPipe,        /* handle to pipe           */

         chReply,      /* buffer to write from     */

         cbReplyBytes, /* number of bytes to write */

         &cbWritten,   /* number of bytes written  */

         NULL);        /* not overlapped I/O       */

      if (! fSuccess || cbReplyBytes != cbWritten) break;

  }

  /*

   * Flush the pipe to allow the client to read the pipe's contents before

   * disconnecting, then disconnect the pipe and close the handle to

   * this pipe instance.

   */

  FlushFileBuffers(hPipe);

  DisconnectNamedPipe(hPipe);

  CloseHandle(hPipe);

}


Example: A Server Using Overlapped I/O

Example: A Server Using Overlapped Input and Output

This example is a single-threaded server process that uses overlapped operations to service simultaneous connections to multiple client processes. The server process creates a fixed number of pipe instances, each of which can be connected to a separate client process. When a client process has finished using its pipe instance, the server disconnects from the client and reuses the pipe instance to connect to a new client.

Associated with each pipe instance is an OVERLAPPED structure containing an event object. This OVERLAPPED structure is specified as a parameter in each ReadFile, WriteFile, and ConnectNamedPipe operation on that pipe instance. Although the example makes simultaneous operations possible on different pipe instances, it is careful to avoid simultaneous operations on a single pipe instance. This is because the same event object is used for read, write, and connect operations for each instance, so with simultaneous operations on the same pipe instance, there would be no way to know which operation's completion caused the event to be set to the signaled state.

The event handles for each pipe instance are also stored in an array used by the WaitForMultipleObjects function. This function waits for one of the events to be signaled, and its return value is the array index of the event that satisfied the wait. The example uses this index to retrieve a structure containing information for this pipe instance. The server uses the fPendingIO member of this structure to keep track of whether the most recent I/O operation on that instance was pending, necessitating a call to the GetOverlappedResult function. It uses the dwState member of the structure to determine the next operation that must be performed for this instance.

Overlapped ReadFile, WriteFile, and ConnectNamedPipe operations may have finished when the function returns, or they may still be pending when the function returns. If the operation is pending, the event object in the specified OVERLAPPED structure is set to the not-signaled state before the function returns. When the pending operation has finished, the system sets the state of the event object to signaled. The state of the event object is not changed if the operation finishes before the function returns.

Because the example uses manual reset event objects, the state of the event objects is not changed to not-signaled by the WaitForMultipleObjects function. This is important, because the example relies on the event objects remaining in the signaled state except when there is a pending operation.

If the operation is already finished when ReadFile, WriteFile, or ConnectNamedPipe returns, the function's return value indicates the result. For read and write operations, the number of bytes transferred is also returned. If the operation is still pending, the ReadFile, WriteFile, or ConnectNamedPipe function returns FALSE and the GetLastError function returns ERROR_IO_PENDING. In this case, the results are retrieved using the GetOverlappedResult function after the operation has finished. GetOverlappedResult returns only the results of operations that were pending, and does not report the results of operations that were completed before the overlapped ReadFile, WriteFile, or ConnectNamedPipe returned.

Before disconnecting from a client, the multithreaded server example in the previous section used FlushFileBuffers to ensure that the client had read everything written to the pipe. This would defeat the purpose of overlapped I/O, because the flush operation would block the execution of the server thread while waiting for the client to empty the pipe. Consequently, it is necessary to wait for a signal from the client that it has finished before disconnecting. In this example, the signal is the error generated by trying to read from the pipe after the client process closes its handle.

#include <windows.h>

#define CONNECTING_STATE 0

#define READING_STATE 1

#define WRITING_STATE 2

#define INSTANCES 4

typedef struct {

  OVERLAPPED oOverlap;

  HANDLE hPipeInst;

  CHAR chBuf[BUFSIZE];

  DWORD cbToWrite;

  DWORD dwState;

  BOOL fPendingIO;

} PIPEINST, *LPPIPEINST;

VOID DisconnectAndReconnect(DWORD);

BOOL ConnectToNewClient(HANDLE, LPOVERLAPPED);

VOID GetDataToWriteToClient(LPPIPEINST);

PIPEINST Pipe[INSTANCES];

HANDLE hEvents[INSTANCES];

DWORD main(VOID) {

  DWORD i, dwWait, cbBytes, dwErr;

  BOOL fSuccess;

  LPTSTR lpszPipename = "\\\\.\\pipe\\mynamedpipe";

  /*

   * The initial loop creates several instances of a named pipe,

   * along with an event object for each instance. An

   * overlapped ConnectNamedPipe operation is started for

   * each instance.

   */

  for (i = 0; i < INSTANCES; i++) {

      /* Create an event object for this instance. */

      hEvents[i] = CreateEvent(

          NULL,    /* no security attr. */

          TRUE,    /* manual reset event       */

          TRUE,    /* initial state = signaled */

          NULL);   /* unnamed event object     */

      if (hEvents[i] == NULL)

          MyErrExit("CreateEvent");

      Pipe[i].oOverlap.hEvent = hEvents[i];

      Pipe[i].hPipeInst = CreateNamedPipe(

          lpszPipename,            /* pipe name           */

          PIPE_ACCESS_DUPLEX |     /* read/write access   */

          FILE_FLAG_OVERLAPPED,    /* overlapped mode     */

          PIPE_TYPE_MESSAGE |      /* message-type pipe   */

          PIPE_READMODE_MESSAGE |  /* message-read mode   */

          PIPE_WAIT,               /* blocking mode       */

          INSTANCES,               /* number of instances */

          BUFSIZE,                 /* output buffer size  */

          BUFSIZE,                 /* input buffer size   */

          PIPE_TIMEOUT,            /* client time-out     */

          NULL);                   /* no security attr    */

      if (Pipe[i].hPipeInst == INVALID_HANDLE_VALUE)

          MyErrExit("CreatePipe");

      /* Call the subroutine to connect to the new client. */

      Pipe[i].fPendingIO = ConnectToNewClient(

          Pipe[i].hPipeInst,

          &Pipe[i].oOverlap);

      Pipe[i].dwState = Pipe[i].fPendingIO ?

          CONNECTING_STATE : /* still connecting   */

          READING_STATE;     /* ready to read      */

  }

  while (1) {

      /*

       * Wait for the event object to be signaled, indicating

       * completion of an overlapped read, write, or

       * connect operation.

       */

      dwWait = WaitForMultipleObjects(

         INSTANCES,    /* number of event objects */

         hEvents,      /* array of event objects  */

         FALSE,        /* does not wait for all   */

         INFINITE);    /* waits indefinitely      */

      /* dwWait shows which pipe had completed operation. */

      i = dwWait - WAIT_OBJECT_0; /* determines which pipe */

      if (i < 0 || i > (INSTANCES - 1))

          MyErrExit("index out of range");

      /* Get the result if the operation was pending. */

      if (Pipe[i].fPendingIO) {

          fSuccess = GetOverlappedResult(

               Pipe[i].hPipeInst, /* handle to pipe       */

               &Pipe[i].oOverlap, /* OVERLAPPED structure */

               &cbBytes,          /* bytes transferred    */

               FALSE);            /* do not wait          */

          switch (Pipe[i].dwState) {

              /* Pending connect operation */

              case CONNECTING_STATE:

                  if (! fSuccess)

                      MyErrExit("ConnectNamedPipe");

                  Pipe[i].dwState = READING_STATE;

                  break;

              /* Pending read operation */

              case READING_STATE:

                  if (! fSuccess || cbBytes == 0) {

                      DisconnectAndReconnect(i);

                      continue;

                  }

                  Pipe[i].dwState = WRITING_STATE;

                  break;

              /* Pending write operation */

              case WRITING_STATE:

                  if (! fSuccess ||

                          cbBytes != Pipe[i].cbToWrite) {

                      DisconnectAndReconnect(i);

                      continue;

                  }

                  Pipe[i].dwState = READING_STATE;

                  break;

              default:

                  MyErrExit("invalid pipe state");

          }

      }

      /* The pipe state determines which operation to do next. */

      switch (Pipe[i].dwState) {

          /*

           * READING_STATE:

           * The pipe instance is connected to the client

           * and ready to read a request from the client.

           */

          case READING_STATE:

                  fSuccess = ReadFile(

                  Pipe[i].hPipeInst,

                  Pipe[i].chBuf,

                  BUFSIZE,

                  &cbBytes,

                  &Pipe[i].oOverlap);

              /* The read operation was successfully completed. */

              if (fSuccess && cbBytes != 0) {

                  Pipe[i].fPendingIO = FALSE;

                  Pipe[i].dwState = WRITING_STATE;

                  continue;

              }

              /* The read operation is still pending */

              dwErr = GetLastError();

              if (! fSuccess &&

                    (dwErr == ERROR_IO_PENDING)) {

                Pipe[i].fPendingIO = TRUE;

                continue;

              }

              /* An error occurred; disconnect from the client. */

              DisconnectAndReconnect(i);

              break;

          /*

           * WRITING_STATE:

           * The request was successfully read from the client.

           * Get the reply data and write it to the client.

           */

          case WRITING_STATE:

              GetDataToWriteToClient(&Pipe[i]);

              fSuccess = WriteFile(

                  Pipe[i].hPipeInst,

                  Pipe[i].chBuf,

                  Pipe[i].cbToWrite,

                  &cbBytes,

                  &Pipe[i].oOverlap);

              /* Write operation completed successfully */

              if (fSuccess &&

                      cbBytes == Pipe[i].cbToWrite) {

                  Pipe[i].fPendingIO = FALSE;

                  Pipe[i].dwState = READING_STATE;

                  continue;

              }

              /* The write operation is still pending. */

              dwErr = GetLastError();

              if (! fSuccess &&

                      (dwErr == ERROR_IO_PENDING)) {

                  Pipe[i].fPendingIO = TRUE;

                  continue;

              }

              /* An error occurred; disconnect from the client. */

              DisconnectAndReconnect(i);

              break;

          default:

              MyErrExit("invalid pipe state");

      }

  }

  return 0;

}

/*

 * DisconnectAndReconnect(DWORD)

 * This function is called when an error occurs or when the client closes

 * its handle to the pipe. Disconnect from this client, and then call

 * ConnectNamedPipe to wait for another client to connect.

 */

VOID DisconnectAndReconnect(DWORD i) {

  /* Disconnect the pipe instance. */

  if (! DisconnectNamedPipe(Pipe[i].hPipeInst) )

      MyErrExit("DisconnectNamedPipe");

  /* Call a subroutine to connect to the new client. */

  Pipe[i].fPendingIO = ConnectToNewClient(

      Pipe[i].hPipeInst,

      &Pipe[i].oOverlap);

  Pipe[i].dwState = Pipe[i].fPendingIO ?

      CONNECTING_STATE : /* still connecting   */

      READING_STATE;     /* ready to read      */

}

/*

 * ConnectToNewClient(HANDLE, LPOVERLAPPED)

 * This function is called to start an overlapped connect operation. It

 * returns TRUE if an operation is pending or FALSE if the connection has

 * been completed.

 */

BOOL ConnectToNewClient(HANDLE hPipe, LPOVERLAPPED lpo) {

  BOOL fConnected, fPendingIO = FALSE;

  /* Start an overlapped connection for this pipe instance. */

  fConnected = ConnectNamedPipe(hPipe, lpo);

  /* Overlapped ConnectNamedPipe should return FALSE */

  if (fConnected)

      MyErrExit("ConnectNamedPipe");

  switch (GetLastError()) {

      /* Overlapped connection in progress */

      case ERROR_IO_PENDING:

          fPendingIO = TRUE;

          break;

      /* Client already connected, so signal an event. */

      case ERROR_PIPE_CONNECTED:

          if (SetEvent(lpo->hEvent))

              break;

      /* If an error occurs during the connection operation... */

      default:

          MyErrExit("ConnectNamedPipe");

  }

  return fPendingIO;

}

The ReadFileEx and WriteFileEx functions provide another form of overlapped I/O. Unlike the overlapped ReadFile and WriteFile functions, which use an event object to signal completion, the extended functions specify a completion routine. A completion routine is a function that is queued for execution when the read or write operation is done. The completion routine is not executed until the thread that called ReadFileEx and WriteFileEx enters an alertable wait by calling one of the extended wait functions: WaitForSingleObjectEx, WaitForMultipleObjectsEx, or SleepEx. These functions are like the other wait functions in that they return when a specified object is in the signaled state or when a time-out interval has elapsed. However, these functions can also perform an alertable wait, which occurs when their fAlertable flag is set to TRUE. In an alertable wait, the functions also return when a ReadFileEx or WriteFileEx completion routine is queued for execution. A server process can use the extended functions to perform a sequence of read and write operations for each client that connects to it. Each read or write operation in the sequence specifies a completion routine, and each completion routine initiates the next step in the sequence.

This example is a single-threaded server process that uses overlapped operations to handle simultaneous connections to multiple client processes. The server process creates a fixed number of pipe instances, each of which can be connected to a separate client process. When a client process has finished using its pipe instance, the server disconnects from the client and reuses the pipe instance to connect to a new client.

Associated with each pipe instance is an OVERLAPPED structure containing an event object. This OVERLAPPED structure is specified as a parameter in each ReadFile, WriteFile, and ConnectNamedPipe operation on that pipe instance.


Example: A Server Using Completion Routines

Like the previous example, this example is a single-threaded server process that creates a message-type pipe and uses overlapped operations. This server process differs in that it uses the extended functions ReadFileEx and WriteFileEx to perform overlapped I/O. Unlike the overlapped ReadFile and WriteFile functions, which signal an event object upon completion, the extended functions specify a completion routine, which is queued for execution when the operation is finished. The server process uses the WaitForSingleObjectEx function, which performs an alertable wait that returns when a completion routine is ready to execute. The wait function also returns when an event object is signaled, which in this example indicates that the overlapped ConnectNamedPipe operation has finished (a new client has connected).

Initially, the server process creates a single instance of the pipe and starts an overlapped ConnectNamedPipe operation. When a client connects, the server allocates a structure to provide storage for that pipe instance and then calls the ReadFileEx function to launch a sequence of I/O operations to handle communications with the client. Each operation specifies a completion routine that performs the next operation in the sequence. The sequence terminates when the client is disconnected and the pipe instance closed. After starting the sequence of operations for the new client, the server creates another pipe instance and waits for the next client to connect.

The parameters to the ReadFileEx and WriteFileEx functions specify a completion routine and a pointer to an OVERLAPPED structure. This pointer is later passed to the completion routine in its lpOverLap parameter. Because the OVERLAPPED structure points to the first member in the structure allocated for each pipe instance, the completion routine can use its lpOverLap parameter to access the structure for the pipe instance.

To avoid duplication, the listing for the ConnectToNewClient subroutine is not shown; it is identical to the one used by the overlapped server process in the previous section.

#include <windows.h>

typedef struct {

  OVERLAPPED oOverlap;

  HANDLE hPipeInst;

  CHAR chBuf[BUFSIZE];

  DWORD cbToWrite;

} PIPEINST, *LPPIPEINST;

BOOL CreateAndConnectInstance();

BOOL ConnectToNewClient(HANDLE, LPOVERLAPPED);

VOID GetDataToWriteToClient(LPPIPEINST);

VOID DisconnectAndClose(LPPIPEINST);

VOID CompletedWriteRoutine(DWORD, DWORD, LPOVERLAPPED);

VOID CompletedReadRoutine(DWORD, DWORD, LPOVERLAPPED);

HANDLE hPipe;

DWORD main(VOID) {

  HANDLE hConnectEvent;

  OVERLAPPED oConnect;

  LPPIPEINST lpPipeInst;

  DWORD dwWait, cbBytes;

  BOOL fSuccess, fPendingIO;

  /* Create one event object for the connection operation */

  hConnectEvent = CreateEvent(

      NULL,    /* no security attr. */

      TRUE,    /* manual reset event        */

      TRUE,    /* initial state = signaled  */

      NULL);   /* unnamed event object      */

  if (hConnectEvent == NULL)

      MyErrExit("CreateEvent");

  oConnect.hEvent = hConnectEvent;

  /*

   * Call a subroutine to create one instance, and wait for

   * the client to connect.

   */

  fPendingIO = CreateAndConnectInstance(&oConnect);

  while (1) {

   /*

    * Wait for a client to connect, or for a read or write

    * operation to be completed, which causes a completion

    * routine to be queued for execution.

    */

      dwWait = WaitForSingleObjectEx(

          hConnectEvent,  /* event object to wait for */

          INFINITE,       /* waits indefinitely       */

          TRUE);          /* alertable wait enabled   */

      switch (dwWait) {

        /* The wait is satisfied by a completed connection operation. */

          case 0:

              /* If an operation is pending, get the result of the

               * connection operation.

               */

              if (fPendingIO) {

                  fSuccess = GetOverlappedResult(

                      hPipe,     /* pipe handle          */

                      &oConnect, /* OVERLAPPED structure */

                      &cbBytes,  /* bytes transferred    */

                      FALSE);    /* does not wait        */

                  if (! fSuccess)

                      MyErrExit("ConnectNamedPipe");

              }

              /* Allocate storage for this instance. */

              lpPipeInst = (LPPIPEINST) GlobalAlloc(

                  GPTR, sizeof(PIPEINST));

              if (lpPipeInst == NULL)

                  MyErrExit("GlobalAlloc lpPipeInst");

              lpPipeInst->hPipeInst = hPipe;

              /*

               * Start the read operation for this client.

               * Note that this same routine is later used as a

               * completion routine after a write operation.

               */

              lpPipeInst->cbToWrite = 0;

              CompletedWriteRoutine(0, 0,

                  (LPOVERLAPPED) lpPipeInst);

              /* Create new pipe instance for the next client. */

              fPendingIO = CreateAndConnectInstance(

                  &oConnect);

              break;

        /*

         * The wait is satisfied by a completed read or write

         * operation. This allows the system to execute the

         * completion routine.

         */

          case WAIT_IO_COMPLETION:

              break;

        /* An error occurred in the wait function. */

          default:

              MyErrExit("WaitForSingleObjectEx");

      }

  }

  return 0;

}

/*

 * CompletedWriteRoutine(DWORD, DWORD, LPOVERLAPPED)

 * This routine is called as an I/O completion routine after writing to

 * the pipe, or when a new client has connected to a pipe instance. It

 * starts another read operation.

 */

VOID CompletedWriteRoutine(DWORD dwErr, DWORD cbWritten,

    LPOVERLAPPED lpOverLap) {

  LPPIPEINST lpPipeInst;

  BOOL fRead = FALSE;

  /* lpOverlap points to storage for this instance. */

  lpPipeInst = (LPPIPEINST) lpOverLap;

  /*

   * The write operation has finished, so read the next request (if no

   * error).

   */

  if ((dwErr == 0) && (cbWritten == lpPipeInst->cbToWrite))

      fRead = ReadFileEx(

          lpPipeInst->hPipeInst,

          lpPipeInst->chBuf,

          BUFSIZE,

          (LPOVERLAPPED) lpPipeInst,

          (LPOVERLAPPED_COMPLETION_ROUTINE) CompletedReadRoutine);

  /* Disconnect if an error occurred. */

  if (! fRead)

      DisconnectAndClose(lpPipeInst);

}

/*

 * CompletedReadRoutine(DWORD, DWORD, LPOVERLAPPED)

 * This routine is called as an I/O completion routine after reading a

 * request from the client. It gets data and writes it to the pipe.

 */

VOID CompletedReadRoutine(DWORD dwErr, DWORD cbBytesRead,

    LPOVERLAPPED lpOverLap) {

  LPPIPEINST lpPipeInst;

  BOOL fWrite = FALSE;

  /* lpOverlap points to storage for this instance */

  lpPipeInst = (LPPIPEINST) lpOverLap;

  /*

   * The read operation has finished, so write a response (if no

   * errorred).

   */

  if ((dwErr == 0) && (cbBytesRead != 0)) {

      GetDataToWriteToClient(lpPipeInst);

      fWrite = WriteFileEx(

          lpPipeInst->hPipeInst,

          lpPipeInst->chBuf,

          lpPipeInst->cbToWrite,

          (LPOVERLAPPED) lpPipeInst,

          (LPOVERLAPPED_COMPLETION_ROUTINE) CompletedWriteRoutine);

  }

  /* Disconnect if an error occurred. */

  if (! fWrite)

      DisconnectAndClose(lpPipeInst);

}

/*

 * DisconnectAndClose(LPPIPEINST)

 * Called when error occurs or when the client closes its handle

 * to the pipe.

 */

VOID DisconnectAndClose(LPPIPEINST lpPipeInst)

{

  /* Disconnect the pipe instance. */

  if (! DisconnectNamedPipe(lpPipeInst->hPipeInst) )

      MyErrExit("DisconnectNamedPipe");

  /* Close the handle to the pipe instance. */

  CloseHandle(lpPipeInst->hPipeInst);

  /* Release the storage for the pipe instance. */

  if (lpPipeInst != NULL)

      GlobalFree(lpPipeInst);

}

/*

 * CreateAndConnectInstance(LPOVERLAPPED)

 * This function creates a pipe instance and connects to the new client.

 * It returns TRUE if the connection operation is pending FALSE if

 * the connection has been completed.

 */

BOOL CreateAndConnectInstance(LPOVERLAPPED lpoOverlap) {

  LPTSTR lpszPipename = "\\\\.\\pipe\\mynamedpipe";

  hPipe = CreateNamedPipe(

      lpszPipename,             /* pipe name           */

      PIPE_ACCESS_DUPLEX |      /* read/write access   */

      FILE_FLAG_OVERLAPPED,     /* overlapped mode     */

      PIPE_TYPE_MESSAGE |       /* message-type pipe   */

      PIPE_READMODE_MESSAGE |   /* message read mode   */

      PIPE_WAIT,                /* blocking mode       */

      PIPE_UNLIMITED_INSTANCES, /* unlimited instances */

      BUFSIZE,                  /* output buffer size  */

      BUFSIZE,                  /* input buffer size   */

      PIPE_TIMEOUT,             /* client time-out     */

      NULL);                    /* no security attr. */

  if (hPipe == INVALID_HANDLE_VALUE)

      MyErrExit("CreatePipe");

  /* Call a subroutine to connect to the new client. */

  return ConnectToNewClient(hPipe, lpoOverlap);

}


The Named Pipe Client Process

A client process uses the CreateFile function to open a handle to a named pipe. If the pipe exists but all of its instances are busy, CreateFile returns FALSE and the GetLastError function returns ERROR_PIPE_BUSY. When this happens, the client process uses the WaitNamedPipe function to wait for an instance of the pipe to be available.

The CreateFile function fails if the access specified is incompatible with the access specified (duplex, outbound, or inbound) when the server created the pipe. For a duplex pipe (read/write), the client can specify read, write, or read/write access; for an outbound pipe (server write only), the client must specify read only; for an inbound pipe (server read only), the client must specify write only.

The handle returned by CreateFile defaults to byte-read mode, blocking-wait mode, overlapped mode disabled, and write-through mode disabled. The client process can use the CreateFile function to enable overlapped mode by specifying FILE_FLAG_OVERLAPPED, or write-through mode by specifying FILE_FLAG_WRITE_THROUGH. The client can use the SetNamedPipeHandleState function to enable nonblocking mode by specifying PIPE_WAIT, or message-read mode by specifying PIPE_READMODE_MESSAGE.

The following example shows a client process that opens a named pipe, sets the pipe handle to message-read mode, uses WriteFile to send a request to the server, and uses ReadFile to read the server's reply. You could use this client process with any of the message-type servers shown in the previous sections. With a byte-type server, however, this client process fails when it calls SetNamedPipeHandleState to change to message-read mode. Because the client is reading from the pipe in message-read mode, it is possible for the ReadFile operation to return FALSE after reading a partial message. This happens when the message is larger than the read buffer. In this situation, GetLastError returns ERROR_MORE_DATA and the remainder of the message is read by additional calls to ReadFile.

#include <windows.h>

 DWORD main(int argc, char *argv[]) {

  HANDLE hPipe;

  LPVOID lpvMessage;

  CHAR chBuf[512];

  BOOL fSuccess;

  DWORD cbRead, cbWritten, dwMode;

  LPTSTR lpszPipename = "\\\\.\\pipe\\mynamedpipe";

  /* Try to open a named pipe; wait for it, if necessary. */

  while (1) {

      hPipe = CreateFile(

          lpszPipename,   /* pipe name           */

          GENERIC_READ |  /* read/write access   */

          GENERIC_WRITE,

          0,              /* no sharing          */

          NULL,           /* no security attr. */

          OPEN_EXISTING,  /* opens existing pipe */

          0,              /* default attributes  */

          NULL);          /* no template file    */

      /* Break if the pipe handle is valid. */

      if (hPipe != INVALID_HANDLE_VALUE)

          break;

      /* Exit if an error other than ERROR_PIPE_BUSY occurs */

      if (GetLastError() != ERROR_PIPE_BUSY)

          MyErrExit("Could not open pipe");

      /* All pipe instances are busy, so wait for 20 seconds. */

      if (! WaitNamedPipe(lpszPipename, 20000) )

          MyErrExit("Could not open pipe");

  }

  /* The pipe connected; change to message read mode. */

  dwMode = PIPE_READMODE_MESSAGE;

  fSuccess = SetNamedPipeHandleState(

      hPipe,    /* pipe handle          */

      &dwMode,  /* new pipe mode        */

      NULL,     /* don't set max. bytes */

      NULL);    /* don't set max. time  */

  if (! fSuccess)

      MyErrExit("SetNamedPipeHandleState");

  /* Send a message to the pipe server. */

  lpvMessage = (argc > 1) ? argv[1] : "default message";

  fSuccess = WriteFile(

      hPipe,                  /* pipe handle     */

      lpvMessage,             /* message         */

      strlen(lpvMessage) + 1, /* message length  */

      &cbWritten,             /* bytes written   */

      NULL);                  /* not overlapped  */

  if (! fSuccess)

      MyErrExit("WriteFile");

  do {

      /* Read from the pipe. */

      fSuccess = ReadFile(

          hPipe,    /* pipe handle              */

          chBuf,    /* buffer to receive reply  */

          512,      /* size of buffer           */

          &cbRead,  /* number of bytes read     */

          NULL);    /* not overlapped           */

      if (! fSuccess && GetLastError() != ERROR_MORE_DATA)

          break;

      /* Reply from pipe written to stdout. */

      if (! WriteFile(GetStdHandle(STD_OUTPUT_HANDLE),

              chBuf, cbRead, &cbWritten, NULL))

          break;

  } while (! fSuccess); /* repeat loop if ERROR_MORE_DATA */

  CloseHandle(hPipe);

  return 0;

}


Transactions on Named Pipes

A named pipe transaction is a client-server communication that combines a write operation and a read operation into a single network operation. A transaction can be used only on a duplex, message-type pipe. Transactions improve the performance of network communications between a client and a remote server. Processes can use the TransactNamedPipe and CallNamedPipe functions to perform named pipe transactions.

The TransactNamedPipe function is typically used by a client process to write a request message to the named pipe server and read the server's response message. The client process must specify GENERIC_READ | GENERIC_WRITE access when it opens its pipe handle by calling the CreateFile function. Then, the client process sets the pipe handle to message-read mode by calling the SetNamedPipeHandleState function. If the read buffer specified in the call to TransactNamedPipe is not large enough to hold the entire message written by the server, the function returns FALSE and GetLastError returns ERROR_MORE_DATA. The client can read the remainder of the message by calling either ReadFile, ReadFileEx, or PeekNamedPipe.

TransactNamedPipe is typically called by client processes, but can also be used by a server process.

The following example shows a client process using TransactNamedPipe. The example presumes the client process has used CreateFile to connect to the pipe and SetNamedPipeHandleState to set the pipe handle's read mode, as shown in the client process example of the previous section.

fSuccess = TransactNamedPipe(

    hPipe,               /* pipe handle             */

    lpszWrite,           /* message to server       */

    strlen(lpszWrite)+1, /* message length          */

    chReadBuf,           /* buffer to receive reply */

    512,                 /* size of read buffer     */

    &cbRead,             /* number of bytes read    */

    NULL);               /* not overlapped          */

/*

 * Exit if an error occurs, unless the error indicates there is more

 * data in the message.

 */

if (! fSuccess && (GetLastError() != ERROR_MORE_DATA))

    MyErrExit("TransactNamedPipe");

while(1) {

    /* Data from the pipe is written to stdout. */

    if (! WriteFile(GetStdHandle(STD_OUTPUT_HANDLE),

            chReadBuf, cbRead, &cbWritten, NULL) )

        break;

    /* Break if successful TransactNamedPipe or ReadFile. */

    if (fSuccess)

        break;

    /* Read from the pipe if there is more data in the message.*/

    fSuccess = ReadFile(

        hPipe,      /* pipe handle              */

        chReadBuf,  /* buffer to receive reply  */

        512,        /* size of buffer           */

        &cbRead,    /* number of bytes read     */

        NULL);      /* not overlapped           */

    /* Exit if an error other than ERROR_MORE_DATA occurs. */

    if (! fSuccess && (GetLastError() != ERROR_MORE_DATA))

        break;

}

A client process uses the CallNamedPipe function to combine the CreateFile, WaitNamedPipe (if necessary), TransactNamedPipe, and CloseHandle operations into a single function. Because the pipe handle is closed before the function returns, any additional bytes in the message are lost if the message is larger than the specified size of the read buffer.

The following example shows the use of CallNamedPipe.

/* Combines connect, wait, write, read, and close */

fSuccess = CallNamedPipe(

    lpszPipename,        /* pipe name               */

    lpszWrite,           /* message to server       */

    strlen(lpszWrite)+1, /* message length          */

    chReadBuf,           /* buffer to receive reply */

    512,                 /* size of read buffer     */

    &cbRead,             /* number of bytes read    */

    20000);              /* waits for 20 seconds    */

if (fSuccess || GetLastError() == ERROR_MORE_DATA) {

    /* Data from the pipe is written to stdout. */

    WriteFile(GetStdHandle(STD_OUTPUT_HANDLE),

        chReadBuf, cbRead, &cbWritten, NULL);

    /*

     * The pipe is closed; so no more bytes can be read from the

     * message.

     */

    if (! fSuccess)

        printf("\n...extra data in message was lost\n");

}


Functions

Following are the functions used with pipes.

CallNamedPipe

ConnectNamedPipe

CreateNamedPipe

CreatePipe

DisconnectNamedPipe

GetNamedPipeHandleState

GetNamedPipeInfo

PeekNamedPipe

SetNamedPipeHandleState

TransactNamedPipe

WaitNamedPipe


Mailslots Overview

About Mailslots

A mailslot is a mechanism for one-way interprocess communications. An application written for Microsoft® Windows™ can store messages in a mailslot. The owner of the mailslot can retrieve messages that are stored there. Mailslot messages are typically sent over a network to either a specified computer or to all computers in a specified domain. A domain is a group of workstations and servers that share a group name.

The following topics discuss mailslots:

Terms

Mailslot Names

Mailslots and LAN Manager

Server and Client Functions

Creating a Mailslot

Writing to a Mailslot

Reading from a Mailslot

Functions

A mailslot is a pseudofile; it resides in memory, and standard Windows file functions write to it. Unlike disk files, however, mailslots are temporary. When every handle of a mailslot is closed, the mailslot and all the data it contains are deleted. The data in a mailslot message can be in any form.

A mailslot server is a process that creates and owns a mailslot. When the server creates a mailslot, it receives a mailslot handle. This handle must be used when a process reads messages from the mailslot. Only the process that creates a mailslot (or has obtained the handle by some other mechanism, such as inheritance) can read from the mailslot. A mailslot exists until all server handles to it have been closed or all server processes have exited. All mailslots are local to the process that creates them; a process cannot create a remote mailslot.

A mailslot client is a process that writes a message to a mailslot. Any process that has the name of a mailslot can put a message there. New messages follow preexisting messages in the mailslot.

Mailslots can broadcast messages within a domain. If several processes in a domain each create a mailslot using the same name, every message that is addressed to that mailslot and sent to the domain is received by the participating processes. Because one process can control both a server mailslot handle and the client handle retrieved when the mailslot is opened for a write operation, applications can easily implement a simple message-passing facility within a domain.

Some developers choose to use named pipes instead of mailslots for interprocess communications (IPC). Named pipes are a simple way for two processes to exchange messages. Mailslots, on the other hand, are a simple way for a process to broadcast messages to many other processes.

There is another issue involved in the choice between mailslots and named pipes. Mailslots use datagrams, and named pipes do not. A datagram is a small packet of information that the network sends along the wire. Like a radio or television broadcast, a datagram offers no confirmation of receipt; there is no  way to guarantee that a datagram has been received. Just as mountains, large buildings, or interfering signals might cause a radio or television signal to get lost, there are things the sender has no knowledge of that can prevent a datagram from reaching a particular destination. Named pipes are more like simple one-to-one telephone calls: you can only talk to one party, but you know that the conversation is occurring. So, if an application needs guaranteed reception, it  should use a named pipe; but named pipes cannot broadcast. Mailslots do not guarantee reception, but they can broadcast.


Mailslot Names

When a process creates a mailslot, the mailslot name must have the following form.

\\.\mailslot\[path]name

A mailslot name requires the following elements: two backslashes to begin the name, a period, a backslash following the period, the word mailslot, and a trailing backslash. Case, however, is not important. A mailslot name can be preceded by a path consisting of the names of one or more pseudodirectories; separated by backslashes. For example, if a user expects messages on the subject of taxes from Bob, Pete, and Sue; the user's mailslot application might allow the user to create individual mailslots for each sender.

\\.\mailslot\taxes\bobs_comments

\\.\mailslot\taxes\petes_comments

\\.\mailslot\taxes\sues_comments

To put a message into a mailslot, a process opens a mailslot whose name is in one of several forms. To write to a mailslot on the local computer, a process can use a mailslot name using the same form required for creating a mailslot. This situation, however, is relatively uncommon. More frequently, a process uses the following form to write to a mailslot on a specific remote computer.

\\computername\mailslot\[path]name

The following form allows a process to put a message into every mailslot in the specified domain that has the given name.

\\domainname\mailslot\[path]name

To put a message into every mailslot with a given name in the system's primary domain, a process uses the following form.

\\*\mailslot\[path]name


Mailslots and Microsoft LAN Manager

Mailslots and Microsoft LAN Manager 2.x

Windows uses mailslots similar to those developed for Microsoft LAN Manager version 2.0. An application that uses LAN Manager 2.x mailslots can interact easily with mailslots created by Windows. There are significant differences, however, between Windows-based mailslots and LAN Manager mailslots:

Windows-based mailslots all have the same class--there are no "first class" and "second class" mailslots.

All Windows-based mailslot messages have equal priority and are always appended to the mailslot buffer. When a Windows-based mailslot message is written to a mailslot on a computer that requires message priority, the system sets the priority to the lowest value (0).

Write operations to Windows-based mailslots on local computers return an error value if an error occurs. Write operations to remote Windows-based mailslots do not return an error value when they fail. (Because there is no built-in limit to the size of the mailslot buffer failure is unlikely.)

Write operations to Windows-based mailslots fail immediately if the message cannot be appended to the mailslot buffer (if the buffer is too small, for example). Immediate failure makes write time-outs irrelevant; contrary to LAN Manager mailslots, there are no write time-outs for Windows-based mailslots.

A process that creates a Windows-based mailslot can specify that the mailslot handle be inherited by its child processes. (Mailslot handles in LAN Manager cannot be inherited.)

A process writes messages to a Windows-based mailslot by using standard file input and output functions. The following table shows LAN Manager mailslot functions and their corresponding Windows functions.

LAN Manager functions	Windows functions

DosDeleteMailslot	CloseHandle

DosMailslotInfo	GetMailslotInfo

DosMakeMailslot	CreateMailslot

DosReadMailslot	ReadFile

DosWriteMailslot	WriteFile


Server and Client Functions

Clients and servers when working with mailslots should use only the functions discussed in this section. Other Windows functions should not be used, even if they accept file handles or filenames as arguments.

Server Functions

Mailslot servers have exclusive use of three functions, as shown in the following table.

Function	Description

CreateMailslot	Creates a mailslot and returns a mailslot handle.

GetMailslotInfo	Retrieves the maximum message size, the mailslot size, the size of the next message in the mailslot, the number of messages in the mailslot, and the amount of time a read operation can wait for a message.

SetMailslotInfo	Changes the read time-out for a mailslot.

The following functions are also used by mailslot servers.

Function	Description

DuplicateHandle	Duplicates the mailslot handle.

ReadFile	Retrieves messages from a mailslot.

GetFileTime	Retrieves the date and time a mailslot was created.

SetFileTime	Sets the date and time a mailslot was created.

Client Functions

A client process uses the following functions when interacting with a mailslot.

Function	Description

CloseHandle	Closes a mailslot handle for a client process.

CreateFile	Creates a mailslot handle for a client process.

DuplicateHandle	Duplicates a mailslot handle.

WriteFile	Writes data to a mailslot.


Creating a Mailslot

Mailslots in Windows are supported by three specialized functions: CreateMailslot, GetMailslotInfo, and SetMailslotInfo. These functions are used by the mailslot server.

The following code sample uses the CreateMailslot function to retrieve the handle of a mailslot named sample_mailslot.

BOOL FAR PASCAL Makeslot(HWND hwnd, HDC hdc)

{

    LPSTR lpszSlotName = "\\\\.\\mailslot\\sample_mailslot";

    /* The mailslot handle "hSlot1" is declared globally. */

    hSlot1 = CreateMailslot(lpszSlotName,

        0,                         /* no maximum message size         */

        MAILSLOT_WAIT_FOREVER,     /* no time-out for read operations */

        (LPSECURITY_ATTRIBUTES) NULL); /* no security attributes      */

    if (hSlot1 == INVALID_HANDLE_VALUE) {

        ErrorHandler(hwnd, "CreateMailslot"); /* local error handler */

        return FALSE;

    }

    TextOut(hdc, 10, 10, "CreateMailslot successful.", 26);

    return TRUE;

}

To create a mailslot inherited by child processes, an application should change the SECURITY_ATTRIBUTES structure passed as the last parameter of CreateMailslot. To do this, the application sets the bInheritHandle member of this structure to TRUE (the default setting is FALSE).


Writing to a Mailslot

Writing to a mailslot is similar to writing to a standard disk file. The following code uses the CreateFile, WriteFile, and CloseHandle functions to put a short message in a mailslot. The message is broadcast to every computer in the primary domain of the system.

LPSTR lpszMessage = "Message for sample_mailslot in primary domain.";

BOOL fResult;

HANDLE hFile;

DWORD cbWritten;

hFile = CreateFile("\\\\*\\mailslot\\sample_mailslot",

    GENERIC_WRITE,

    FILE_SHARE_READ, /* required to write to a mailslot */

    (LPSECURITY_ATTRIBUTES) NULL,

    OPEN_EXISTING,

    FILE_ATTRIBUTE_NORMAL,

    (HANDLE) NULL);

if (hFile == INVALID_HANDLE_VALUE) {

    ErrorHandler(hwnd, "Primary domain"); /* local error handler */

    return FALSE;

}

fResult = WriteFile(hFile,

    lpszMessage,

    (DWORD) lstrlen(lpszMessage) + 1, /* include terminating null character */

    &cbWritten,

    (LPOVERLAPPED) NULL);

if (!fResult) {

    ErrorHandler(hwnd, "WriteFile");

    return FALSE;

}

TextOut(hdc, 10, 10, "WriteFile successful.", 21);

fResult = CloseHandle(hFile);

if (!fResult) {

    ErrorHandler(hwnd, "CloseHandle");

    return FALSE;

}

TextOut(hdc, 10, 30, "CloseHandle successful.", 23);

return TRUE;

Messages that are broadcast to a domain must be no more than 400 bytes in length. Messages that are not broadcast should be smaller than 64 kilobytes. The number of messages that can be sent to a mailslot is not limited.


Reading from a Mailslot

The process that creates a mailslot can read messages from it by using the mailslot handle in a call to the ReadFile function. The code in the following example calls the GetMailslotInfo function to determine whether there are messages in the mailslot. If messages are waiting, each is displayed in a message box along with the number of messages remaining to be read.

BOOL FAR PASCAL Readslot(HWND hwnd, HDC hdc)

{

    DWORD cbMessage, cMessage, cbRead;

    BOOL fResult;

    LPSTR lpszBuffer;

    CHAR achID[80];

        DWORD cAllMessages;

    cbMessage = cMessage = cbRead = 0;

    /* Mailslot handle "hSlot1" is declared globally. */

    fResult = GetMailslotInfo(hSlot1, /* mailslot handle         */

        (LPDWORD) NULL,               /* no maximum message size */

        &cbMessage,                   /* size of next message    */

        &cMessage,                    /* number of messages      */

        (LPDWORD) NULL);              /* no read time-out        */

    if (!fResult) {

        ErrorHandler(hwnd, "GetMailslotInfo");

        return FALSE;

    }

    if (cbMessage == MAILSLOT_NO_MESSAGE) {

        TextOut(hdc, 10, 10, "No waiting messages.", 20);

        return TRUE;

    }

    cAllMessages = cMessage;

    while (cMessage != 0) {              /* retrieves each message  */

        /* Create a message-number string. */

        wsprintf((LPSTR) achID,

            "\nMessage #%d of %d\n", cAllMessages - cMessage + 1,

            cAllMessages);

        /* Allocate memory for the message. */

        lpszBuffer = (LPSTR) GlobalAlloc(GPTR,

            lstrlen((LPSTR) achID) + cbMessage);

        lpszBuffer[0] = '\0';

        fResult = ReadFile(hSlot1,

            lpszBuffer,

            cbMessage,

            &cbRead,

            (LPOVERLAPPED) NULL);

        if (!fResult) {

            ErrorHandler(hwnd, "ReadFile");

            GlobalFree((HGLOBAL) lpszBuffer);

            return FALSE;

        }

        /* Concatenate the message and the message-number string. */

        lstrcat(lpszBuffer, (LPSTR) achID);

        /* Display the message. */

        MessageBox(hwnd,

            lpszBuffer,

            "Contents of Mailslot",

            MB_OK);

        GlobalFree((HGLOBAL) lpszBuffer);

        fResult = GetMailslotInfo(hSlot1, /* mailslot handle         */

            (LPDWORD) NULL,               /* no maximum message size */

            &cbMessage,                   /* size of next message    */

            &cMessage,                    /* number of messages      */

            (LPDWORD) NULL);              /* no read time-out        */

        if (!fResult) {

            ErrorHandler(hwnd, "GetMailslotInfo");

            return FALSE;

        }

    }

    return TRUE;

}

A mailslot exists until the CloseHandle function is called for all open server handles or until all server processes that own a mailslot handle exit. In both cases, any unread messages are deleted from the mailslot, all client handles to the mailslot are closed, and the mailslot itself is deleted from memory.


Mailslot Functions

The following functions can be used with mailslots.

CreateMailslot

GetMailslotInfo

SetMailslotInfo


Networks Overview

About Networks

An application written for Microsoft Windows NT can use the network functions in the Microsoft Win32 application programming interface (API) to implement networking capabilities without making allowances for a particular network provider or physical network implementation. In other words, these functions are network-independent. Applications can use these functions to add and cancel network connections and to retrieve information about the current configuration of the network. In addition, the Win32 API implements a version of the IBM NetBIOS network interface for applications that require it.

The following topics discuss Win32 networks:

Terms

Network-Independent Functions

The Netbios Function

Using Networks

Using the Connections Dialog Box

Enumerating Network Resources

Adding a Network Connection

Retrieving the Connection Name

Retrieving the User Name

Canceling a Network Connection

Retrieving Network Errors

Network Functions

In addition to using the network functions, processes can also use the Win32 API implementations of mailslots and named pipes to communicate with one another. For more information about these subjects, see Mailslots and Pipes.

The following figure shows the structure of a typical network:

In the preceding figure, the hierarchy for Microsoft Advanced Servver resources is given in detail as Network provider #1. Network resources from other providers have different hierarchical systems. An application does not need information about the hierarchy before it begins to work with a network. It can proceed from the network root (that is, the topmost container resource) and retrieve information about the network resources as the information is required.

Network resources that contain other resources are called containers. Container resources are in boxes in the preceding figure. Resources that do not contain other resources are objects. Sharepoint #1 and Sharepoint #2 in the figure are objects.

A sharepoint is an object that is accessible across the network, such as a printer or a shared directory.


Network-Independent Functions

Windows version 3.1 included the following network-independent network functions:

WNetAddConnection

WNetCancelConnection

WNetGetConnection

The Win32 API supports these functions and adds the following new network and network-enumeration functions:

WNetAddConnection2	WNetEnumResource

WNetCancelConnection2	WNetGetLastError

WNetCloseEnum	WNetGetUser

WNetConnectionDialog	WNetOpenEnum

WNetDisconnectDialog

Many of these functions use a NETRESOURCE structure, which is also new for the Win32 API. WNetAddConnection and WNetCancelConnection are supported for compatibility with earlier versions of Windows. However, new applications typically use WNetAddConnection2 and WNetCancelConnection2 instead.

An application can use the network functions to browse, add, or cancel network connections anywhere in the hierarchy. By starting at the network root, the resources from all network providers can be enumerated.

A persistent connection is a network connection that Windows automatically restores when the user logs on. With the WNetAddConnection2 and WNetCancelConnection2 functions, an application can control whether a network connection is persistent from one session to the next.


The Netbios Function

The Netbios function is provided primarily for applications that were written for the IBM NetBIOS system and need to be ported to Windows. Applications not requiring compatibility with IBM NetBIOS can usually use other interfaces, such as mailslots and named pipes, to accomplish tasks similar to those supported by Netbios.

The Netbios function in the Win32 API takes one parameter: a pointer to a network-control block (NCB) structure. This structure contains information about the network environment and a pointer to a buffer that is used for messages or for further data about the network.

Windows NetBios Enhancements

The Win32 implementation of the Netbios function includes the following enhancements that are not part of the IBM NetBIOS 3.0 specification:

POST routines can be called from the C programming language by means of the ncb_post member of the NCB structure.

Each asynchronous network-control block can supply an event (in the ncb_event member of the NCB structure) set to the signalled state when the NCB completes.

An application can enumerate all available LAN adapters by using the NCBENUM command in the ncb_command member of the NCB structure.

Differences Between Windows and IBM NetBIOS

In addition to the enhancements listed in the preceding section, the following differences exist between the Win32 implementation of the Netbios function and the IBM NetBIOS 3.0 specification:

The system does not monitor the number of outstanding NCB commands specified when the NCBRESET command is issued. The memory quota limits for Windows NT are used to limit the total resources an application can use.

Asynchronous commands on invalid sessions are rejected when they are submitted.

The numbers of the network names (the ncb_num member of the NCB structure) are assigned on a per-process basis.

Requests for the status of the local adapter retrieve only the names that were added by the process making the request.

The value 1 for the ncb_lana_num member of the NCB structure is not exclusive when the NCBRESET command is issued. All MS-DOS and 16-bit Windows-based applications also share access to name number 1.


Using Networks

The Windows network functions enable your application to query and control network connections directly or to give direct control of the network connections to the user. To use these functions, you must link to the multiple-provider router library (MPR.LIB). This section discusses how to use the network functions in your application.


Using the Connect and Disconnect Dialog Boxes

Using the Connections Dialog Box

The WNetConnectionDialog function creates a dialog box that allows the user to browse and connect to network resources.

Conversely, the WNetDisconnectDialog function creates a dialog box that allows the user to disconnect from network resources.

The following example shows how to use the WNetConnectionDialog function to create a dialog box that displays disk resources:

DWORD dwResult;

dwResult = WNetConnectionDialog(hwnd,

    RESOURCETYPE_DISK);

if(dwResult != NO_ERROR) {

    /*

     * An application-defined error handler is demonstrated in the

     * section titled "Retrieving Network Errors" later in

     * this chapter.

     */

    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetConnectionDialog");

    return FALSE;

}


Enumerating Network Resources

To enumerate a network container resource, your application should pass the address of a NETRESOURCE structure to the WNetOpenEnum function. WNetOpenEnum creates a handle to the resource described by the NETRESOURCE structure. The application then passes this handle to the WNetEnumResource function, which returns information about the resource in the form of an array of NETRESOURCE structures. When the handle is no longer needed, close it by calling the WNetCloseEnum function.

Your application can continue enumerating any container resource described in the array of NETRESOURCE structures retrieved by WNetEnumResource. If the dwUsage member of the NETRESOURCE structure is RESOURCEUSAGE_CONTAINER, the application can pass the address of that structure to WNetOpenEnum to open the container and continue the enumeration. If dwUsage is RESOURCEUSAGE_CONNECTABLE, the application can pass the structure's address to the WNetAddConnection2 function.

The following example illustrates an application-defined function (EnumerateFunc) that enumerates all the resources on a network. When calling this function, specify NULL for the pointer to the NETRESOURCE structure; when WNetOpenEnum receives the NULL pointer, it retrieves a handle to the root of the network. Whenever a NETRESOURCE structure retrieved by WNetEnumResource is RESOURCEUSAGE_CONTAINER, the EnumerateFunc function calls itself and uses a pointer to that structure in the call to WNetOpenEnum.

BOOL FAR PASCAL EnumerateFunc(hwnd, hdc, lpnr)

HWND hwnd;

HDC hdc;

LPNETRESOURCE lpnr;

{

    DWORD dwResult, dwResultEnum;

    HANDLE hEnum;

    DWORD cbBuffer = 16384; /* 16K is reasonable size for Windows NT  */

    DWORD cEntries = 0xFFFFFFFF; /* enumerate all possible entries    */

    LPNETRESOURCE lpnrLocal;     /* pointer to enumerated structures  */

    DWORD i;

    dwResult = WNetOpenEnum(RESOURCE_GLOBALNET,

        RESOURCETYPE_ANY,

        0,                 /* enumerate all resources                 */

        lpnr,              /* NULL first time this function is called */

        &hEnum);           /* handle to resource                      */

    if (dwResult != NO_ERROR) {

        /*

         * An application-defined error handler is demonstrated in the

         * section titled "Retrieving Network Errors."

         */

        NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetOpenEnum");

        return FALSE;

    }

    do {

        /* Allocate memory for NETRESOURCE structures. */

        lpnrLocal = (LPNETRESOURCE) GlobalAlloc(GPTR, cbBuffer);

        dwResultEnum = WNetEnumResource(hEnum, /* resource handle     */

            &cEntries,               /* defined locally as 0xFFFFFFFF */

            lpnrLocal,               /* LPNETRESOURCE                 */

            &cbBuffer);              /* buffer size                   */

        if (dwResultEnum == NO_ERROR) {

            for(i = 0; i < cEntries; i++) {

                /*

                 * The following is an application-defined function for

                 * displaying contents of NETRESOURCE structures.

                 */

                DisplayStruct(hdc, &lpnrLocal[i]);

                /*

                 * If this NETRESOURCE is a container, call the function

                 * recursively.

                 */

                if(RESOURCEUSAGE_CONTAINER ==

                        (lpnrLocal[i].dwUsage & RESOURCEUSAGE_CONTAINER))

                    if(!EnumerateFunc(hwnd, hdc, &lpnrLocal[i]))

                        TextOut(hdc, 10, 10,

                            "EnumerateFunc returned FALSE.", 29);

            }

        }

        else if (dwResultEnum != ERROR_NO_MORE_ITEMS) {

            NetErrorHandler(hwnd, dwResultEnum, (LPSTR)"WNetEnumResource");

            break;

        }

    }

    while(dwResultEnum != ERROR_NO_MORE_ITEMS);

    GlobalFree((HGLOBAL) lpnrLocal);

    dwResult = WNetCloseEnum(hEnum);

    if(dwResult != NO_ERROR) {

        NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetCloseEnum");

        return FALSE;

    }

    return TRUE;

}


Adding a Network Connection

To make a connection to a network resource described by a NETRESOURCE structure, an application can call the WNetAddConnection2 function, as shown in the following example.

DWORD dwResult;

NETRESOURCE nr;

dwResult = WNetAddConnection2(&nr, /* NETRESOURCE from enumeration */

    (LPSTR) NULL,             /* no password                       */

    (LPSTR) NULL,             /* logged-in user                    */

    CONNECT_UPDATE_PROFILE);  /* update profile with connect info  */

if (dwResult == ERROR_ALREADY_ASSIGNED) {

    TextOut(hdc, 10, 10, "Already connected to specified resource.", 40);

    return FALSE;

}

else if (dwResult == ERROR_DEVICE_ALREADY_REMEMBERED) {

    TextOut(hdc, 10, 10,

        "Attempted reassignment of remembered device.", 44);

    return FALSE;

}

else if(dwResult != NO_ERROR) {

    /*

     * An application-defined error handler is demonstrated in the

     * section titled "Retrieving Network Errors."

     */

    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetAddConnection2");

    return FALSE;

}

TextOut(hdc, 10, 10, "Connected to specified resource.", 32);

return TRUE;

The WNetAddConnection function is supported for compatibility with earlier versions of Windows. For new applications, use WNetAddConnection2.


Retrieving the Connection Name

To retrieve the name of the network resource associated with a local device, an application can use the WNetGetConnection function, as shown in the following example.

CHAR szDeviceName[80];

DWORD dwResult, cchBuff = sizeof(szDeviceName);

dwResult = WNetGetConnection("z:",

    (LPSTR) szDeviceName,

    &cchBuff);

switch (dwResult) {

    case NO_ERROR:

        TextOut(hdc, 10, 10, (LPSTR) szDeviceName,

            lstrlen((LPSTR) szDeviceName));

        break;

    case ERROR_NOT_CONNECTED:

        TextOut(hdc, 10, 10, "Device z: not connected.", 24);

    case ERROR_CONNECTION_UNAVAIL:

        /* A connection is remembered but not connected. */

        TextOut(hdc, 10, 10, "Connection unavailable.", 23);

    default:

        /*

         * An application-defined error handler is demonstrated in the

         * section titled "Retrieving Network Errors."

         */

        NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetGetConnection");

        return FALSE;

}


Retrieving the User Name

To retrieve the name of the user associated with either a local device connected to a network resource or with the name of a network, an application can call the WNetGetUser function. The following example uses the device name to retrieve the name of the user.

CHAR szUserName[80];

DWORD dwResult, cchBuff = 80;

dwResult = WNetGetUser("z:",

    (LPSTR) szUserName,

    &cchBuff);

if(dwResult == NO_ERROR)

    TextOut(hdc, 10, 10,

        (LPSTR) szUserName,

        lstrlen((LPSTR) szUserName));

else {

    /*

     * An application-defined error handler is demonstrated in the

     * section titled "Retrieving Network Errors."

     */

    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetGetUser");

    return FALSE;

}


Canceling a Network Connection

To cancel a connection to a network resource, an application can call the WNetCancelConnection2 function, as shown in the following example.

DWORD dwResult;

dwResult = WNetCancelConnection2("z:",

    CONNECT_UPDATE_PROFILE, /* remove connection from profile */

    FALSE);               /* fail if open files or jobs       */

if (dwResult == ERROR_NOT_CONNECTED) {

    TextOut(hdc, 10, 10, "Drive z: not connected.", 23);

    return FALSE;

}

else if(dwResult != NO_ERROR) {

    /*

     * An application-defined error handler is demonstrated in the

     * section titled "Retrieving Network Errors."

     */

    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetCancelConnection2");

    return FALSE;

}

TextOut(hdc, 10, 10, "Connection closed for z:.", 25);

The WNetCancelConnection function is supported for compatibility with earlier versions of Windows. For new applications, use WNetCancelConnection2.


Retrieving Network Errors

When one of the Windows network functions returns WN_EXTENDED_ERROR, an application can call the WNetGetLastError function to retrieve more information about the error that occurred. Usually, this information is specific to the network provider.

The following example illustrates an application-defined error-handling function (NetErrorHandler) that takes three arguments: a window handle, the error code returned by one of the Windows network functions, and the name of the function that produced the error. If the error code is WN_EXTENDED_ERROR, Net Error Handler calls WNetGetLastError to retrieve extended error information.

BOOL WINAPI NetErrorHandler(hwnd, dwErrorCode, lpszFunction)

HWND  hwnd;

DWORD dwErrorCode;

LPSTR lpszFunction;

{

    DWORD dwWNetResult, dwLastError;

    CHAR szError[256];

    CHAR szCaption[256];

    CHAR szDescription[256];

    CHAR szProvider[256];

    /* The following performs standard error-handling. */

    if (dwErrorCode != ERROR_EXTENDED_ERROR) {

        wsprintf((LPSTR) szError, "%s failed; \nResult is %ld",

            lpszFunction, dwErrorCode);

        wsprintf((LPSTR) szCaption, "%s error", lpszFunction);

        MessageBox(hwnd, (LPSTR) szError, (LPSTR) szCaption, MB_OK);

        return TRUE;

    }

    /*

     * The following performs error-handling when the ERROR_EXTENDED_ERROR

     * return value indicates that WNetGetLastError can

     * retrieve additional information.

     */

    else {

        dwWNetResult = WNetGetLastError(&dwLastError,

            (LPSTR) szDescription,  /* buffer for error description  */

            sizeof(szDescription),

            (LPSTR) szProvider,     /* buffer for provider name      */

            sizeof(szProvider));

        if(dwWNetResult != NO_ERROR) {

            wsprintf((LPSTR) szError,

                "WNetGetLastError failed; error %ld", dwWNetResult);

            MessageBox(hwnd, (LPSTR) szError,

                "WNetGetLastError", MB_OK);

            return FALSE;

        }

        wsprintf((LPSTR) szError,

            "%s failed with code %ld;\n%s",

            (LPSTR) szProvider, dwLastError, (LPSTR) szDescription);

        wsprintf((LPSTR) szCaption, "%s error", lpszFunction);

        MessageBox(hwnd, (LPSTR) szError, (LPSTR) szCaption, MB_OK);

        return TRUE;

    }

}


Network Functions

Following are the functions used with networks:

NetBios

WNetAddConnection

WNetAddConnection2

WNetCancelConnection

WNetCancelConnection2

WNetCloseEnum

WNetConnectionDialog

WNetDisconnectDialog

WNetEnumResource

WNetGetConnection

WNetGetLastError

WNetGetUser

WNetOpenEnum


Consoles and Character-Mode Support Overview

About Character-Mode Support

The Microsoft® Win32™ application programming interface (API) provides consoles that manage input and output (I/O) for character-mode applications (applications that do not provide their own graphical user interface). Consoles provide high-level support for simple character-mode applications that interact with the user by using functions that read from standard input and write to standard output or standard error. Consoles also provide sophisticated low-level support that gives direct access to a console's screen buffer and that enables applications to receive extended input information (such as mouse input).

The following topics discuss consoles and character-mode support:

Terms

Consoles

Creation of a Console

Closing a Console

Console Handles

Console Input Buffer

Keyboard Events

Mouse Events

Buffer-Resizing Events

Console Screen Buffers

Window and Screen Buffer Size

Scrolling the Screen Buffer

Cursor Appearance and Position

Screen Buffer Color Attributes

Input and Output Methods

Console Modes

High Level Console I/O

High Level Console Modes

High Level Console Input and Output Functions

Low Level Console I/O

Low Level Console Modes

Low Level Console Input Functions

Low Level Console Output Functions

Console Code Pages

Console Control Handlers

CTRL+C and CTRL+BREAK Signals

CTRL+CLOSE Signal

Console Process Groups

Using the High Level Input and Output Functions

Writing Characters or Colors to Consecutive Cells

Reading and Writing Blocks of Characters and Attributes

Reading Input Buffer Events

Scrolling a Screen Buffer's Window

Scrolling a Screen Buffer's Contents

Registering a Control Handler Function

Console Application Issues

Functions


Consoles

A console is an interface that provides input and output (I/O) to character-mode applications. This processor-independent mechanism makes it easy to port existing character-mode applications or to create new character-mode tools and applications.

A console consists of an input buffer and one or more screen buffers. The input buffer contains a queue of input records, each of which contains information about an input event. The input queue always includes key-press and key-release events. It can also include mouse events (pointer movements and button presses and releases) and events in which user actions affect the size of the active screen buffer. A screen buffer is a two-dimensional array of character and color data for output in a console window.

The Win32 API functions enable different levels of access to a console. The high-level console I/O functions enable an application to read from standard input to retrieve keyboard input stored in a console's input buffer. The functions also enable an application to write to standard output or standard error to display text in the console's screen buffer. The high-level functions also support redirection of standard handles and control of console modes for different I/O functionality. The low-level console I/O functions enable applications to receive detailed input about keyboard and mouse events, as well as events involving user interactions with the console window. The low-level functions also enable greater control of output to the screen.


Creation of a Console

Creation of a Console

Windows Program Manager creates a new console when it starts a console process, a character-mode process whose entry point is the main function. For example, Program Manager creates a new console when it starts the Microsoft® Windows command processor (CMD.EXE). When the command processor starts a new console process, the user can specify whether the system creates a new console for the new process or whether it inherits the command processor's console. A process can create a console by using one of the following methods:

A graphical user interface (GUI) or console process that is not currently attached to a console can use the AllocConsole function to create a new console.

A GUI or console process can use the CreateProcess function to create a new console process and specify a flag to tell the system to create a new console.

Typically, a process uses AllocConsole to create a console when an error occurs requiring interaction with the user. For example, a GUI process can create a console when an error occurs that prevents it from using its normal graphical interface, or a console process that does not normally interact with the user can create a console when an error makes it necessary. The process that calls AllocConsole must not be attached to an existing console. GUI processes are not attached to any console when they are created. A console process is not attached to a console if the DETACHED_PROCESS flag was specified in a call to CreateProcess when the process was created. A process can use the FreeConsole function to detach itself from an inherited console or from a console created by AllocConsole.

A process can also create a console by specifying the CREATE_NEW_CONSOLE flag in a call to CreateProcess. This method creates a new console that is accessible to the child process but not to the parent process. Separate consoles enable both parent and child processes to interact with the user without conflict. If this flag is not specified when a console process is created, both processes are attached to the same console, and there is no guarantee that the correct process will receive the input intended for it. Applications can prevent confusion by creating child processes that do not inherit handles of the input buffer, or by enabling only one child process at a time to inherit an input buffer handle while preventing the parent process from reading console input until the child has finished.

Creating a new console results in a new console window, as well as separate I/O screen buffers. The process associated with the new console uses the GetStdHandle function to get the handles of the new console's input and screen buffers. These handles enable the process to access the console.

When a process uses CreateProcess, it can specify a STARTUPINFO structure, whose members control the characteristics of the first new console (if any) created for the child process. The STARTUPINFO structure specified in the call to CreateProcess affects a console created if the CREATE_NEW_CONSOLE flag is specified. It also affects a console created if the child process subsequently uses AllocConsole. The following console characteristics can be specified:

The size, in character cells, and the location, in screen pixel coordinates, of the new console window.

The size, in character cells, of the new console's screen buffer.

The text and background color attributes of the new console's screen buffer.

The name appearing in the title bar of the new console's window.

The system uses default values if the STARTUPINFO values are not specified. A child process can use the GetStartupInfo function to determine the values in its STARTUPINFO structure.

A process cannot change the location of its console window on the screen, but the following console functions are available to set or query the other properties specified in the STARTUPINFO structure.

Function	Description

GetConsoleScreenBufferInfo	Queries window size, screen buffer size, and color attributes

SetConsoleWindowInfo	Changes the size of the console window

SetConsoleScreenBufferSize	Changes the size of the screen buffer

SetConsoleTextAttribute	Sets the color attributes

SetConsoleTitle	Sets the console window title

GetConsoleTitle	Queries the console window title


Closing a Console

Closing a Console

A process can use FreeConsole to detach itself from its console. If other processes share the console, the console is not destroyed, but the process that called FreeConsole cannot reference it. After calling FreeConsole, the process can use AllocConsole to create a new console.

A console is closed when the last process attached to it terminates or calls FreeConsole.


Console Handles

Console Handles

A console process uses handles to access the input and screen buffers of its console. A process can use the GetStdHandle, CreateFile, or CreateConsoleScreenBuffer function to open one of these handles.

The GetStdHandle function provides a mechanism for retrieving the standard input (STDIN), standard output (STDOUT), and standard error (STDERR) handles associated with a process. During console creation, the system creates these handles. Initially, STDIN is a handle of the console's input buffer; STDOUT and STDERR are handles of the console's active screen buffer. However, the SetStdHandle function can redirect the standard handles by changing the handle associated with STDIN, STDOUT, or STDERR. Subsequent calls to GetStdHandle return the redirected handle, and the parent's standard handles are inherited by any child processes. This means that a handle returned by GetStdHandle may refer to something other than console I/O. For example, before creating a child process, a parent process can use SetStdHandle to set a pipe handle to be the STDIN handle that is inherited by the child process. When the child process calls GetStdHandle, it gets the pipe handle. This means that the parent process can control the standard handles of the child process. The handles returned by GetStdHandle have GENERIC_READ | GENERIC_WRITE access unless SetStdHandle has been used to set the standard handle to have lesser access.

The value of the handles returned by GetStdHandle will not be 0, 1, and 2, so the standard predefined stream constants in the STDIO.H header file (STDIN, STDOUT, and STDERR) cannot be used in the functions that require a console handle.

The CreateFile function enables a process to get a handle of its console's input buffer and active screen buffer, even if STDIN and STDOUT have been redirected. To open a handle of a console's input buffer, specify "CONIN$" in a call to CreateFile. Specify "CONOUT$" in a call to CreateFile to open a handle of a console's active screen buffer. CreateFile enables you to specify the read-write access of the handle that it returns.

The CreateConsoleScreenBuffer function creates a new screen buffer and returns a handle, which can be used in any function that accepts a handle of console output. The new screen buffer is not active until its handle is specified in a call to the SetConsoleActiveScreenBuffer function. Note that changing the active screen buffer does not affect the handle returned by GetStdHandle. Similarly, using SetStdHandle to change the STDOUT handle does not affect the active screen buffer.

Console handles returned by CreateFile and CreateConsoleScreenBuffer can be used in any of the console functions that require a handle of a console's input buffer or of a console screen buffer. Handles returned by GetStdHandle can be used by the console functions if they have not been redirected to refer to something other than console I/O. If a standard handle has been redirected to refer to a file or a pipe, however, the handle can only be used by the ReadFile and WriteFile functions.

A process can use the DuplicateHandle function to create a duplicate console handle that has different access or inheritability from the original handle. Note, however, that a process can create a duplicate console handle only for its own use. This differs from other handle types (such as file, pipe, or mutex objects), for which DuplicateHandle can create a duplicate that is valid for a different process.

To close a console handle, a process can use the CloseHandle function.


Console Input Buffer

Console Input Buffer

Each console has an input buffer that contains a queue of input event records. When a console's window has the keyboard focus, a console formats each input event (such as a single keystroke, a movement of the mouse, or a mouse-button click) as an input record that it places in the console's input buffer.

Applications can access a console's input buffer indirectly by using the high-level console I/O functions, or directly by using the low-level console I/O functions. The high-level input functions filter and process the data in the input buffer, returning only a stream of input characters. The low-level input functions enable applications to read input records directly from a console's input buffer, or to place input records into the input buffer.

An input record is a structure containing information about the type of event that occurred (keyboard, mouse, window resizing, focus, or menu event) as well as specific details about the event. The EventType member in an INPUT_RECORD structure indicates which type of event is contained in the record.

Focus and menu events are placed in a console's input buffer for internal use by the system and should be ignored by applications.


Keyboard Events

Keyboard Events

Keyboard events are generated when any key is pressed or released; this includes control keys. However, the ALT key has special meaning to Windows when pressed and released without being combined with another character, and it 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.

If the input event is a keystroke, the Event member in INPUT_RECORD is a KEY_EVENT_RECORD structure containing the following information:

A Boolean value indicating whether the key was pressed or released.

A repeat count that can be greater than one when a key is held down.

The virtual-key code, identifying the given key in a device-independent manner.

The virtual-scan code, indicating the device-dependent value generated by the keyboard hardware.

The translated Unicode or ANSI character.

A flag indicating the state of the control keys (the ALT, CTRL, SHIFT, NUM LOCK, SCROLL LOCK, and CAPS LOCK keys), and whether an enhanced key was pressed. Enhanced keys for the IBM 101-key and 102-key keyboards are 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.


Mouse Events

Mouse Events

Mouse events are generated whenever the user moves the mouse or presses or releases one of the mouse buttons. Mouse events are placed in the input buffer only if the following conditions are met:

The console input mode is set to ENABLE_MOUSE_INPUT (the default).

The console window has the keyboard focus.

The mouse pointer is within the borders of the console's window.

If the input event is a mouse event, the Event member in INPUT_RECORD is a MOUSE_EVENT_RECORD structure containing the following information:

The coordinates of the mouse pointer in terms of the character cell row and column in the screen buffer's coordinate system.

A flag variable indicating the state of the mouse buttons.

A flag variable indicating the state of the control keys (ALT, CTRL, SHIFT, NUM LOCK, SCROLL LOCK, and CAPS LOCK), and whether an enhanced key was pressed. Enhanced keys for the IBM 101-key and 102-key keyboards are 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.

A flag variable indicating whether the event was a normal button-press or button-release event, a mouse movement event, or the second click of a double-click event.

Note that the mouse position coordinates are in terms of the screen buffer, not the console window. The screen buffer may have been scrolled with respect to the window, so the upper left corner of the window is not necessarily the (0,0) coordinate of the screen buffer. To determine the coordinates of the mouse relative to the coordinate system of the window, subtract the window origin coordinates from the mouse position coordinates. Use the GetConsoleScreenBufferInfo function to determine the window origin coordinates.

The dwButtonState member of the MOUSE_EVENT_RECORD structure has a bit corresponding to each mouse button. The bit is 1 if the button is down and 0 if the button is up. A button-release event is detected by a 0 value for the dwEventFlags member of MOUSE_EVENT_RECORD and a change in a button's bit from 1 to 0. The GetNumberOfConsoleMouseButtons function retrieves the number of buttons on the mouse.


Buffer-Resizing Events

Buffer-Resizing Events

A console window's menu enables the user to change the size of the active screen buffer; this change generates a buffer-resizing event. Buffer-resizing events are placed in the input buffer if the console's input mode is set to ENABLE_WINDOW_INPUT (that is, the default is disabled).

If the input event is a buffer-resizing event, the Event member in INPUT_RECORD is a WINDOW_BUFFER_SIZE_RECORD structure containing the new size of the screen buffer, expressed in character cell columns and rows.

If the user reduces the size of the screen buffer, any data in the discarded portion of the buffer is lost.

Changes to the screen buffer size as a result of application calls to the SetConsoleScreenBufferSize function do not generate as buffer-resizing events.


Console Screen Buffers

Console Screen Buffers

A screen buffer is a two-dimensional array of character and color data for output in a console window. A console can have multiple screen buffers. The active screen buffer is the one that is displayed on the screen.

The system creates a screen buffer whenever it creates a new console. A process can use the CreateConsoleScreenBuffer function to create additional screen buffers for its console. A new screen buffer is not active until its handle is specified in a call to the SetConsoleActiveScreenBuffer function. However, screen buffers can be accessed for reading and writing whether they are active or inactive.

Each screen buffer has its own two-dimensional array of character information records. The data for each character is stored in a CHAR_INFO structure that specifies the Unicode or ANSI character and the foreground and background colors in which that character is displayed.

A number of properties associated with a screen buffer can be set independently for each screen buffer. This means that changing the active screen buffer can have a dramatic effect on the appearance of the console window. The properties associated with a screen buffer include:

Screen buffer size, in character rows and columns.

Text attributes (foreground and background colors for displaying text to be written by the WriteFile or WriteConsole function).

Window size and location (the rectangular region of the screen buffer that is displayed in the console window).

Cursor position, appearance, and visibility.

Output modes (ENABLE_PROCESSED_OUTPUT and ENABLE_WRAP_AT_EOL_OUTPUT). For more information about console output modes, see High-Level Console Modes.

When a screen buffer is created, it contains blanks. Its cursor is visible and positioned at the buffer's origin (0,0), and the window is positioned with its upper left corner at the buffer's origin. The size of the screen buffer, the window size, the text attributes, and the appearance of the cursor are determined by the user or by the system defaults. To determine the current values of the various properties associated with the screen buffer, use the GetConsoleScreenBufferInfo, GetConsoleCursorInfo, and GetConsoleMode functions.

Applications that change any of the screen buffer properties should either create their own screen buffer or save the state of the inherited screen buffer during startup and restore it at exit.


Windows and Screen Buffer Size

Window and Screen Buffer Size

The size of a screen buffer is expressed in terms of a coordinate grid based on character cells. The width is the number of character cells in each row, and the height is the number of rows. Associated with each screen buffer is a window that determines the size and location of the rectangular portion of the screen buffer displayed in the console window. A screen buffer's window is defined by specifying the character cell coordinates of the upper left and lower right cells of the window's rectangle.

A screen buffer can be any size, limited only by available memory. The dimensions of a screen buffer's window cannot exceed the corresponding dimensions of either the screen buffer or the maximum window that can fit on the screen based on the current font size (controlled exclusively by the user).

The GetConsoleScreenBufferInfo function returns the following information about a screen buffer and its window:

The current size of the screen buffer

The current location of the window

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 size of a console's window based on the current font and screen sizes. This size differs from the maximum window size returned by GetConsoleScreenBufferInfo in that the screen buffer size is ignored.

To change a screen buffer's size, use the SetConsoleScreenBufferSize function. This function fails if either dimension of the specified size is less than the corresponding dimension of the console's window.

To change the size or location of a screen buffer's window, use the SetConsoleWindowInfo function. This function fails if the specified window-corner coordinates exceed the limits of the screen buffer or the screen. Changing the window size of the active screen buffer changes the size of the console window displayed on the screen.

A process can change its console's input mode to enable window input so that the process is able to receive input when the user changes the screen buffer size. If an application does not enable window input, it must either use the inherited window and screen buffer sizes, or set them to the desired size during startup and restore the inherited sizes at exit. If an application enables window input, it can use GetConsoleScreenBufferInfo to query window and screen buffer size at startup. This information can then be used to determine the way data is displayed in the window. If the user changes the screen buffer size, the application can respond by changing the way data is displayed. For example, an application can adjust the way text wraps at the end of the line if the number of characters per row changes. For additional information about window input mode, see Low-Level Console Modes.


Scrolling the Screen Buffer

Scrolling the Screen Buffer

The console window displays a portion of the active screen buffer. Each screen buffer maintains its own current window rectangle that specifies the coordinates of the upper left and lower right character cells to be displayed in the console window. To determine the current window rectangle of a screen buffer, use GetConsoleScreenBufferInfo. When a screen buffer is created, the upper-left corner of its window is at the upper left corner of the screen buffer at (0,0).

The window rectangle can change to display different parts of the screen buffer. The window rectangle of a screen buffer can change in the following situations:

When SetConsoleWindowInfo is called to specify a new window rectangle, it scrolls the view of the screen buffers by changing the position of the window rectangle without changing the size of the window. For examples of scrolling the window's contents, see Scrolling a Screen Buffer's Window.

When using the WriteFile function to write to a screen buffer with wrap at end-of-line (EOL) output mode enabled, the window rectangle shifts automatically, so the cursor is always displayed.

When the SetConsoleCursorPosition function specifies a new cursor position that is outside the boundaries of the current window rectangle, the window rectangle shifts automatically to display the cursor.

When the user changes the size of the console window or uses the window's scroll bars, the window rectangle of the active screen buffer can change. This change is not reported as a window resizing event in the input buffer.

In each of these situations, the window rectangle shifts to display a different part of the screen buffer, but the contents of the screen buffer remain in the same position. The following situations can cause the screen buffer's contents to shift:

When the ScrollConsoleScreenBuffer function is called, a rectangular block is copied from one part of a screen buffer to another.

When using WriteFile to write to a screen buffer with wrap at end-of-line (EOL) output mode enabled, the screen buffer's contents scroll automatically when the end of the screen buffer is encountered. This scrolling discards the top line of the screen buffer.

ScrollConsoleScreenBuffer specifies the screen buffer rectangle that is moved and the new upper left coordinates to which the rectangle is copied. This function can scroll a portion or the entire contents of the screen buffer. The effects of ScrollConsoleScreenBuffer can be limited by specifying an optional clipping rectangle so that the contents of the screen buffer outside the clipping rectangle are unchanged. The effect of clipping is to create a subwindow (the clipping rectangle) whose contents are scrolled without affecting the rest of the screen buffer. For an example that uses ScrollConsoleScreenBuffer, see Scrolling a Screen Buffer's Contents.

The illustration shows a ScrollConsoleScreenBuffer operation that scrolls the entire contents of the screen buffer up by several rows. The contents of the top rows are discarded, and the bottom rows are filled with a specified character and color.


Cursor Appearance and Position

Cursor Appearance and Position

A screen buffer's cursor can be visible or hidden. When it is visible, its appearance can vary, ranging from from completely filling a character cell to appearing as a horizontal line at the bottom of the cell. To query the appearance and visibility of the cursor, use the GetConsoleCursorInfo function. This function reports whether the cursor is visible and describes the appearance of the cursor as the percentage of a character cell that it fills. To set the appearance and visibility of the cursor, use the SetConsoleCursorInfo function.

Characters written by the high-level console I/O functions are written at the current cursor location, advancing the cursor to the next location. To determine the current cursor position in the coordinate system of a screen buffer, use the GetConsoleScreenBufferInfo function. You can use SetConsoleCursorPosition to set the cursor position and thereby control the placement of text that is written or echoed by the high-level I/O functions. If you move the cursor, text at the new cursor location is overwritten.

The position, appearance, and visibility of the cursor are set independently for each screen buffer.


Screen Buffer Color Attribute

Screen Buffer Color Attributes

Each screen buffer character cell stores the color attributes for the colors used in drawing the text and background of that cell. An application can set the color data for each character cell individually, storing the data in the Attributes member of the CHAR_INFO structure for each cell.

The current text attributes of each screen buffer determine the text (foreground) and background colors of characters subsequently written or echoed by the high-level functions. An application can use GetConsoleScreenBufferInfo to determine the current text attributes of a screen buffer and the SetConsoleTextAttribute function to set the text attributes. Changing a screen buffer's text attributes does not affect the display of characters previously written. These text attributes do not affect characters written by the low-level console I/O functions (such as the WriteConsoleOutput or WriteConsoleOutputCharacter function) which either explicitly specify the attributes for each cell that is written or leave the attributes unchanged at the written positions.

The following attribute constants are defined in the WINCON.H file:

FOREGROUND_BLUE

FOREGROUND_GREEN

FOREGROUND_RED

FOREGROUND_INTENSITY

BACKGROUND_BLUE

BACKGROUND_GREEN

BACKGROUND_RED

BACKGROUND_INTENSITY

The foreground attributes specify the text color, and the background attributes specify the color used to fill the cell's background. An application can combine the constants to achieve different colors. For example, the following combination results in bright cyan text on a blue background.

FOREGROUND_BLUE | FOREGROUND_GREEN | FOREGROUND_INTENSITY | BACKGROUND_BLUE

If no background constant is specified, the background is black, and if no foreground constant is specified, the text is black. For example, the following combination produces black text on a white background.

BACKGROUND_BLUE | BACKGROUND_GREEN | BACKGROUND_RED


Input and Output Methods

The Win32 API provides two very different approaches to console I/O, the choice of which depends on how much flexibility and control your application needs. The high-level approach enables simple character stream I/O, but it limits access to a console's input and screen buffers. The low-level approach requires that developers write more code and choose among a greater range of functions, but it also gives the application more flexibility.

An application can use the file I/O functions, ReadFile and WriteFile, and the console functions, ReadConsole and WriteConsole, for high-level I/O that provides indirect access to a console's input and screen buffers. The high-level input functions filter and process the data in a console's input buffer to return input as a stream of characters, discarding mouse and buffer-resizing input. Similarly, the high-level output functions write a stream of characters that are displayed at the current cursor location in a screen buffer. An application controls the way these functions work by setting a console's I/O modes.

The low-level I/O functions provide direct access to a console's input and screen buffers, enabling your application to access mouse and buffer-resizing input events and extended information for keyboard events. Low-level output functions enable an application to read from or write to consecutive character cells in a screen buffer, or to read or write rectangular blocks of character cells of a size and at a specified location. A console's input modes affect low-level input by enabling the application to determine whether mouse and buffer-resizing events are placed in the input buffer. A console's output modes have no effect on low-level output.

The high-level and low-level I/O methods are not mutually exclusive, and an application can use any combination of these functions. Typically, however, an application uses one approach or the other exclusively.

The sections that follow describe in detail the console modes and the high-level and low-level I/O functions.


Console Modes

Console Modes

Associated with each console input buffer are a set of input modes that affects input operations. Similarly, each console screen buffer has a set of output modes that affects output operations. The input modes can be divided into two groups: those that affect the high-level input functions, and those that affect the low-level input functions. The output modes affect only applications that use the high-level output functions.

The GetConsoleMode function reports the current input mode of a console's input buffer or the current output mode of a screen buffer. The SetConsoleMode function sets the current mode of either a console input buffer or a screen buffer. If a console has multiple screen buffers, the output modes of each can be different. An application can change I/O modes at any time. For more information about the console modes that affect high-level and low-level I/O operations, see High-Level Console Modes, and Low-Level Console Modes.


High-Level Console I/O

High-Level Console I/O

The high-level I/O functions provide a simple way to read a stream of characters from console input or to write a stream of characters to console output. A high-level read operation gets input characters from a console's input buffer and stores them in a specified buffer. A high-level write operation takes characters from a specified buffer and writes them to a screen buffer at the current cursor location, advancing the cursor as each character is written.

High-level I/O gives you a choice between the ReadFile and WriteFile functions and the ReadConsole and WriteConsole functions. They are identical, except for two important differences. The console functions support the use of either Unicode characters or the ANSI character set; the file I/O functions do not support Unicode. Also, the file I/O functions can be used to access files, pipes, and serial communications devices; the console functions can only be used with console handles. This distinction is important if an application relies on standard handles that may have been redirected.

When using either set of high-level functions, an application can control the text and background colors used to display characters subsequently written to a screen buffer. An application can also use the console modes that affect high-level console I/O to enable or disable the following properties:

Echoing keyboard input to the active screen buffer

Line input, in which a read operation does not return until the ENTER key is pressed

Automatic processing of keyboard input to handle carriage returns, CTRL+C, and other input details

Automatic processing of output to handle line wrapping, carriage returns, backspaces, and other output details


High-Level Console Modes

High-Level Console Modes

The behavior of the high-level console functions is affected by the console input and output modes. All of the following console input modes are enabled for a console's input buffer when a console is created:

Line input mode

Processed input mode

Echo input mode

Both of the following console output modes are enabled for a console screen buffer when it is created:

Processed output mode

Wrapping at end-of-line (EOL) output mode

All three input modes, along with processed output mode, are designed to work together. It is best to either enable or disable all of these modes as a group. When all are enabled, the application is said to be in "cooked" mode, in which most of the processing is handled for the application. When all are disabled, the application is in "raw" mode, in which input is unfiltered and any processing is left to the application.

An application can use the GetConsoleMode function to determine the current mode of a console's input buffer or screen buffer. You can enable or disable any of these modes by using the following flags in the SetConsoleMode function. Note that setting the output mode of one screen buffer does not affect the output mode of other screen buffers.

Flag	Description

ENABLE_PROCESSED_INPUT

Used with a console input handle to cause the system to process any system editing or control key input, rather than returning it as input in the read operation's buffer. If line input is also enabled, backspaces and carriage returns are handled correctly. A backspace causes the cursor to move back one space without affecting the character at the cursor position. A carriage return is converted to carriage return-linefeed character combination. If echo input mode is enabled and the output should reflect the system editing, processed output must be enabled for the active screen buffer. If processed input is enabled, the CTRL+C key combination is passed on to the appropriate handler regardless of whether line input is enabled. For more information about control handlers, see Console Control Handlers.

ENABLE_LINE_INPUT

Used with a console input handle to cause the ReadFile and ReadConsole functions to return when the ENTER key is pressed. If line input mode is disabled, the functions return when one or more characters are available in the input buffer.

ENABLE_ECHO_INPUT

Used with a console input handle to cause keyboard input read by the ReadFile or ReadConsole function to be echoed to the active screen buffer. Characters are echoed only if the process that calls ReadFile or ReadConsole has an open handle of the active screen buffer. Echo mode cannot be enabled unless line input is also enabled. The output mode of the active screen buffer affects the way echoed input is displayed.

ENABLE_PROCESSED_OUTPUT

Used with a console screen buffer handle to cause the system to perform the appropriate action for ANSI control characters that are written to a screen buffer. The BACKSPACE, TAB, bell, carriage return, and linefeed characters are processed. A TAB character moves the cursor to the next tab stop, which occurs every eight characters. A bell character sounds a short tone.

ENABLE_WRAP_AT_EOL_OUTPUT

Used with a console screen buffer handle to cause the current output position (cursor position) to move to the first column in the next row when the end of the current row is reached. If the bottom of the window region is reached, the window origin is moved down one row. This movement has the effect of scrolling the contents of the window up one row. If the bottom of the screen buffer is reached, the contents of the screen buffer are scrolled up one row, and the top row of the screen buffer is discarded. If wrap at EOL output mode is disabled, the last character in the row is overwritten with any subsequent characters.


High-Level Console Input and Output Functions

High-Level Console Input and Output Functions

The ReadFile and WriteFile functions, or the ReadConsole and WriteConsole functions, enable an application to read console input and write console output as a stream of characters. ReadConsole and WriteConsole behave exactly like ReadFile and WriteFile except that they can be used either as wide-character functions (in which text arguments must use Unicode) or as ANSI functions (in which text arguments must use characters from the Windows 3.x character set). Applications that need to maintain a single set of sources to support either Unicode or the ANSI character set should use ReadConsole and WriteConsole.

ReadConsole and WriteConsole can only be used with console handles; ReadFile and WriteFile can be used with other handles (such as files or pipes). This means that ReadConsole and WriteConsole fail if used with a standard handle that has been redirected and is no longer a console handle.

To get keyboard input, a process can use ReadFile or ReadConsole with a handle of the console's input buffer, or it can use ReadFile to read input from a file or a pipe if STDIN has been redirected. These functions only return keyboard events that can be translated into ANSI characters (or Unicode characters, in the case of ReadConsole). The input that can be returned includes control key combinations. The functions do not return keyboard events involving the function keys or arrow keys. Input events generated by mouse, window, focus, or menu input are discarded.

If line input mode is enabled (the default), ReadFile and ReadConsole do not return to the calling application until the ENTER key is pressed. If line input mode is disabled, the functions do not return until at least one character is available. In either mode, all available characters are read until either no more keys are available or the specified number of characters has been read. Unread characters are buffered until the next read operation. The functions report the total number of characters actually read. If echo input mode is enabled, characters read by these functions are written to the active screen buffer at the current cursor position.

A process can use WriteFile or WriteConsole to write to either an active or inactive screen buffer, or it can use WriteFile to write to a file or a pipe if STDOUT has been redirected. Processed output mode and wrap at EOL output mode control the way characters are written or echoed to a screen buffer.

Characters written by WriteFile or WriteConsole, or echoed by ReadFile or ReadConsole, are inserted in a screen buffer at the current cursor position. As each character is written, the cursor position advances to the next character cell, except that the behavior at the end of a line depends on the screen buffer's wrap at EOL output mode. An application can use the GetConsoleScreenBufferInfo function to determine the current cursor position and the SetConsoleCursorPosition function to set the cursor position.

For an example that uses the high-level console I/O functions, see Using the High-Level Input and Output Functions.


Low-Level Console I/O

Low-Level Console I/O

The low-level console I/O functions expand an application's control over console I/O by enabling direct access to a console's input and screen buffers. These functions enable an application to peform the following tasks:

Receive input about mouse and buffer-resizing events

Receive extended information about keyboard input events

Write input records to the input buffer

Read input records without removing them from the input buffer

Determine the number of pending events in the input buffer

Flush the input buffer

Read and write strings of Unicode or ANSI characters at a specified location in a screen buffer

Read and write strings of text and background color attributes at a specified screen buffer location

Read and write rectangular blocks of character and color data at a specified screen buffer location

Write a single Unicode or ANSI character, or a text and background color attribute combination, to a specified number of consecutive cells beginning at a specified screen buffer location


Low-Level Console Modes

Low-Level Console Modes

The types of input events reported in a console's input buffer depend on the console's mouse and window input modes. The console's processed input mode determines how the system handles the CTRL+C key combination. To set or query the state of a console's input modes, an apllication can specify a console input buffer handle in a call to the SetConsoleMode or GetConsoleMode function.

Following are the flags used with console input handles:

Flag	Description

ENABLE_MOUSE_INPUT

Controls whether mouse events are reported in the input buffer. By default, mouse input is enabled and window input is disabled. Changing either of these modes affects only input that occurs after the mode is set; pending mouse or window events in the input buffer are not flushed. The mouse pointer is displayed regardless of the mouse mode.

ENABLE_WINDOW_INPUT

Controls whether buffer-resizing events are reported in the input buffer. By default, mouse input is enabled and window input is disabled. Changing either of these modes affects only input that occurs after the mode is set; pending mouse or window events in the input buffer are not flushed. The mouse pointer is displayed regardless of the mouse mode.

ENABLE_PROCESSED_INPUT

Controls the processing of input for applications using the high-level console I/O functions. However, if processed input mode is enabled, the CTRL+C key combination is not reported in the console's input buffer. Instead, it is passed on to the appropriate control handler function. For more information about control handlers, see Console Control Handlers.

The output modes of a screen buffer do not affect the behavior of the low-level output functions.


Low-Level Console Input Functions

Low-Level Console Input Functions

A console's input buffer contains input records that can include information about keyboard, mouse, buffer-resizing, focus, and menu events. The low-level functions provide direct access to the input buffer, unlike the high-level functions that filter and process the input buffer's data, discarding all but keyboard input.

The Win32 API provides five low-level functions for accessing a console's input buffer:

ReadConsoleInput

PeekConsoleInput

GetNumberOfConsoleInputEvents

WriteConsoleInput

FlushConsoleInputBuffer

The ReadConsoleInput, PeekConsoleInput, and WriteConsoleInput functions use the INPUT_RECORD structure to read from or write to an input buffer.

Following are descriptions of the low-level console input functions.

Function	Description

ReadConsoleInput	Reads and removes input records from an input buffer. The function does not return until at least one record is available to be read. Then all available records are transferred to the buffer of the calling process until either no more records are available or the specified number of records has been read. Unread records remain in the input buffer for the next read operation. The total number of records read is indicated. For an example that uses ReadConsoleInput, see Reading Input Buffer Events.

PeekConsoleInput	Reads without removing the pending input records in an input buffer. All available records up to the specified number are copied into the buffer of the calling process. If no records are available, the function returns immediately. The total number of records read is indicated.

GetNumberOfConsoleInputEvents	Determines the number of unread input records in an input buffer.

WriteConsoleInput	Places input records into the input buffer behind any pending records in the buffer. The input buffer grows dynamically, if necessary, to hold as many records as are written. To use this function, the specified input buffer handle must have GENERIC_WRITE access.

FlushConsoleInputBuffer	Discards all unread events in the input buffer. To use this function, the specified input buffer handle must have GENERIC_WRITE access.

A thread of an application's process can perform a wait operation to wait for input to be available in an input buffer. To initiate a wait operation, specify a handle of the input buffer in a call to any of the wait functions (WaitForSingleObject, WaitForMultipleObjects, MsgWaitForMultipleObjects, WaitForSingleObjectEx, or WaitForMultipleObjectsEx). These functions can return when the state of one or more objects is signaled. The state of a console input handle becomes signaled when there are unread records in its input buffer. The state is reset to nonsignaled when the input buffer becomes empty. If there is no input available, the calling thread enters an efficient wait state, consuming very little processor time while waiting for the conditions of the wait operation to be satisfied.


Low-Level Console Output Functions

Low-Level Console Output Functions

The low-level console output functions provide direct access to the character cells of a screen buffer. One set of functions reads from or writes to consecutive cells beginning at any location in the screen buffer. Another set of functions reads from or writes to rectangular blocks of cells.

The following functions read from or write to a specified number of consecutive character cells in a screen buffer, beginning with a specified cell:

Function	Description

ReadConsoleOutputCharacter

Copies a string of Unicode or ANSI characters from a screen buffer.

WriteConsoleOutputCharacter

Writes a string of Unicode or ANSI characters to a screen buffer.

ReadConsoleOutputAttribute

Copies a string of text and background color attributes from a screen buffer.

WriteConsoleOutputAttribute

Writes a string of text and background color attributes to a screen buffer.

FillConsoleOutputCharacter

Writes a single Unicode or ANSI character to a specified number of consecutive cells in a screen buffer.

FillConsoleOutputAttribute

Writes a text and background color attribute combination to a specified number of consecutive cells in a screen buffer.

For all of these functions, when the last cell of a row is encountered, reading or writing wraps around to the first cell of the next row. When the end of the last row of the screen buffer is encountered, the write functions discard all unwritten characters or attributes, and the read functions return with the number of characters or attributes actually written. For examples that illustrate the use of these functions, see Writing Characters or Colors to Consecutive Cells.

The following functions read from or write to rectangular blocks of character cells at a specified location in a screen buffer:

Function	Description

ReadConsoleOutput

Copies character and color data from a specified block of screen buffer cells into a given block in a destination buffer.

WriteConsoleOutput

Writes character and color data to a specified block of screen buffer cells from a given block in a source buffer.

These functions treat screen buffers and source or destination buffers as two-dimensional arrays of CHAR_INFO structures (containing character and color attribute data for each cell). The functions specify the width and height, in character cells, of the source or destination buffer, and the pointer to the buffer is treated as a pointer to the origin cell (0,0) of the two-dimensional array. The functions use a SMALL_RECT structure to specify which rectangle to access in the screen buffer, and the coordinates of the upper left cell in the source or destination buffer determine the location of the corresponding rectangle in that buffer.

The functions automatically clip the specified screen buffer rectangle to fit within the boundaries of the screen buffer. For example, if the rectangle specifies lower right coordinates that are (column 100, row 50) and the screen buffer is only 80 columns wide, the coordinates are clipped so that they are (column 79, row 50). Similarly, this adjusted rectangle is again clipped to fit within the boundaries of the source or destination buffer. The screen buffer coordinates of the actual rectangle that was read from or written to are specified. For an example that uses these functions, see Reading and Writing Blocks of Characters and Attributes.

The illustration shows a ReadConsoleOutput operation where clipping occurs when the block is read from the screen buffer, and again when the block is copied into the destination buffer. The function reports the actual screen buffer rectangle that was copied from.


Console Code Pages

A code page is a mapping of 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages.

Associated with each console are two code pages: one for input and one for output. A console uses its input code page to translate keyboard input into the corresponding character value. It uses its output code page to translate the character values written by the various output functions into the images displayed in the console window. An application can use the SetConsoleCP and GetConsoleCP functions to set and query a console's input code pages and the SetConsoleOutputCP and GetConsoleOutputCP functions to set and query its output code pages.

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%

For information about using the registry functions to determine the available code pages, see egistry and Initialization Files.

For more information about code pages, see String Manipulation and Unicode.


Console Control Handlers

Each console process has its own list of control handler functions that are called by the system when the process receives a CTRL+C, CTRL+BREAK, or CTRL+CLOSE signal. Initially, the list of control handlers for each process contains only a default handler function that calls the ExitProcess function. A console process can add or remove additional handler functions by calling the SetConsoleCtrlHandler function. This function does not affect the lists of control handlers for other processes. When a console process receives any of the control signals, it calls the handler functions 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 following typedef declaration illustrates the format of a control handler function.

typedef BOOL (*PHANDLER_ROUTINE)(DWORD dwCtrlType);

The function's argument identifies which control signal was received, and the return value indicates whether the signal was handled.

For an example of a control handler function, see Registering a Control Handler Function.


CTRL+C and CTRL+BREAK Signals

CTRL+C and CTRL+BREAK Signals

The CTRL+C and CTRL+BREAK key combinations receive special handling by console processes. By default, when a console window has the keyboard focus, CTRL+C or CTRL+BREAK is treated as a signal (SIGINT or SIGBREAK) and not as keyboard input. By default, these signals are passed to all console processes that are attached to the console. This causes the system to call the control handler function or functions associated with these processes. Detached processes (GUI processes or console processes started with the DETACHED_PROCESS or CREATE_NEW_CONSOLE flags set) are not affected.

CTRL+BREAK is always treated as a signal, but an application can change the default CTRL+C behavior in two ways that prevent the handler functions from being called.

The SetConsoleMode function can disable the ENABLE_PROCESSED_INPUT input mode for a console's input buffer, so CTRL+C is reported as keyboard input rather than as a signal.

When SetConsoleCtrlHandler is called with the NULL and TRUE arguments, the calling process ignores CTRL+C signals. Normal CTRL+C processing is restored by calling SetConsoleCtrlHandler with the NULL and FALSE arguments. This attribute of ignoring or not ignoring CTRL+C signals is inherited by child processes, but it can be enabled or disabled by any process without affecting existing processes.


CTRL+CLOSE Signal

CTRL+CLOSE Signal

The system generates a CTRL+CLOSE signal when the user closes a console. All processes attached to the console receive the signal, giving each process an opportunity to clean up before termination. When a process receives this signal, the handler function can take one of the following actions after performing any cleanup operations:

Call ExitProcess 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 a pop-up dialog box asks the user whether to terminate the process. If the user chooses not to terminate the process, the system does not close the console until the process finally terminates.


Console Process Group

Console Process Groups

When a process uses the CreateProcess function to create a new console process, it can specify the CREATE_NEW_PROCESS_GROUP flag to make the new process the root process of a console process group. The process group includes all processes that are descendants of this root process.

A process can use the GenerateConsoleCtrlEvent function to send a CTRL+C or CTRL+BREAK signal to all processes in a console process group. The signal is only received by those processes in the group that are attached to the same console as the process that called GenerateConsoleCtrlEvent.


Using the High-Level Input and Output Functions

The following example uses the high-level console I/O functions for console I/O. For more information about the high-level console I/O functions, see High-Level Console I/O.

The example assumes that the default I/O modes are in effect initially for the first calls to the ReadFile and WriteFile functions. Then the input mode is changed to turn off line input mode and echo input mode for the second calls to ReadFile and WriteFile. The SetConsoleTextAttribute function is used to set the colors in which subsequently written text will be displayed. Before exiting, the program restores the original console input mode and color attributes.

The example's NewLine function is used when line input mode is disabled. It handles carriage returns by moving the cursor position to the first cell of the next row. If the cursor is already in the last row of the screen buffer, the contents of the screen buffer are scrolled up one line. For an example that illustrates the use of the ScrollConsoleScreenBuffer function to scroll a screen buffer, see Scrolling a Screen Buffer's Contents.

#include <windows.h>

VOID NewLine(VOID);

VOID ScrollScreenBuffer(HANDLE, INT);

HANDLE hStdout, hStdin;

CONSOLE_SCREEN_BUFFER_INFO csbiInfo;

VOID main(void) {

LPSTR lpszPrompt1 = "Type something and press Enter:\n";

LPSTR lpszPrompt2 = "Type any key: ";

CHAR chBuffer[256];

DWORD cRead, cWritten, fdwMode, fdwOldMode;

WORD wOldColorAttrs;

/* Get handles to STDIN and STDOUT. */

hStdin = GetStdHandle(STD_INPUT_HANDLE);

hStdout = GetStdHandle(STD_OUTPUT_HANDLE);

if (hStdin == INVALID_HANDLE_VALUE ||

        hStdout == INVALID_HANDLE_VALUE)

    MyErrorExit("GetStdHandle");

/* Save the current text colors. */

if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo))

    MyErrorExit("GetConsoleScreenBufferInfo");

wOldColorAttrs = csbiInfo.wAttributes;

/* Set text attr. to draw red text on black background. */

if (! SetConsoleTextAttribute(hStdout, FOREGROUND_RED))

        MyErrorExit("SetConsoleTextAttribute");

/*

 * Write to STDOUT and read from STDIN by using default

 * modes. Input is echoed automatically, and ReadFile

 * does not return until a carriage return is typed.

 *

 * The default input modes are line, processed, and echo.

 * The default output modes are processed and wrap at EOL.

 */

while (1) {

    if (! WriteFile(

            hStdout,              /* output handle  */

            lpszPrompt1,          /* prompt string  */

            lstrlen(lpszPrompt1), /* string length  */

            &cWritten,            /* bytes written  */

            NULL) )               /* not overlapped */

        break;

    if (! ReadFile(

            hStdin,    /* input handle        */

            chBuffer,  /* buffer to read into */

            255,       /* size of buffer      */

            &cRead,    /* actual bytes read   */

            NULL) )    /* not overlapped      */

        break;

    if (chBuffer[0] == 'q') break;

}

/* Turn off the line input mode, and echo the input mode. */

if (! GetConsoleMode(hStdin, &fdwOldMode))

    MyErrorExit("GetConsoleMode");

fdwMode = fdwOldMode &

          ~(ENABLE_LINE_INPUT | ENABLE_ECHO_INPUT);

if (! SetConsoleMode(hStdin, fdwMode))

    MyErrorExit("SetConsoleMode");

/* Prompt for input. */

if (! WriteFile(

        hStdout,              /* output handle  */

        lpszPrompt2,          /* prompt string  */

        lstrlen(lpszPrompt2), /* string length  */

        &cWritten,            /* bytes written  */

        NULL) )               /* not overlapped */

    MyErrorExit("WriteFile");

/*

 * Without line and echo input modes, ReadFile returns

 * when any input is available. Carriage returns must

 * be handled, and WriteFile is used to echo input.

 */

while (1) {

    if (! ReadFile(hStdin, chBuffer, 1, &cRead, NULL))

        break;

    if (chBuffer[0] == '\r')

        NewLine();

    else

        if (! WriteFile(hStdout, chBuffer, cRead,

                        &cWritten, NULL))

            break;

    if (chBuffer[0] == 'q') break;

}

/* Restore the original console mode. */

if (! SetConsoleMode(hStdin, fdwOldMode))

    MyErrorExit("SetConsoleMode");

/* Restore the original text colors. */

if (! SetConsoleTextAttribute(hStdout, wOldColorAttrs))

    MyErrorExit("SetConsoleTextAttribute");

}

/*

 * The NewLine function handles carriage returns when the processed

 * input mode is disabled. It gets the current cursor position,

 * and resets it to the first cell of the next row.

 */

VOID NewLine(VOID) {

if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo))

    MyErrorExit("GetConsoleScreenBufferInfo");

csbiInfo.dwCursorPosition.X = 0;

/*

 * If it is the last line in the screen buffer, scroll

 * the buffer up.

 */

if ((csbiInfo.dwSize.Y-1) == csbiInfo.dwCursorPosition.Y) {

    ScrollScreenBuffer(hStdout, 1);

}

/* Otherwise, advance the cursor to the next line. */

else

    csbiInfo.dwCursorPosition.Y += 1;

if (! SetConsoleCursorPosition(hStdout,

              csbiInfo.dwCursorPosition))

    MyErrorExit("SetConsoleCursorPosition");

}


Writing Characters or Colors to Consecutive Cells

You can write characters or color attributes to specified character cells in a screen buffer. The following example uses the WriteConsoleOutputCharacter function to write a string of characters beginning at the upper left corner of a screen buffer. Then the example uses the WriteConsoleOutputAttribute function to write a string of color attributes to the first 51 cells of the same line. The coord parameter for both functions specifies the character cell in the screen buffer at which writing begins. The location in the console window where these characters or colors appear depends on the current window rectangle of the screen buffer. For additional information about the relationship between a screen buffer and its windows, see Window and Screen Buffer Size, and Scrolling the Screen Buffer.

    HANDLE hOutput;

    LPTSTR lpszString = "Character String";

    DWORD cWritten;

    BOOL fSuccess;

    COORD coord;

    WORD wColors[3], wColor;

    CHAR chFillChar;

/* Write a string of characters to a screen buffer. */

    coord.X = 0;            /* start at first cell */

    coord.Y = 0;            /*   of first row      */

    fSuccess = WriteConsoleOutputCharacter(

        hOutput,              /* screen buffer handle     */

        lpszString,           /* pointer to source string */

        lstrlen(lpszString),  /* length of string         */

        coord,                /* first cell to write to   */

        &cWritten);           /* actual number written to */

    if (! fSuccess)

        MyErrorExit("WriteConsoleOutputCharacter");

/* Write a string of colors to a screen buffer. */

    wColors[0] = BACKGROUND_RED;

    wColors[1] = BACKGROUND_RED |     /* white background */

                 BACKGROUND_GREEN |

                 BACKGROUND_BLUE;

    wColors[2] = BACKGROUND_BLUE;

    for (;fSuccess && coord.X < 50; coord.X += 3)

        fSuccess = WriteConsoleOutputAttribute(

            hOutput,          /* screen buffer handle     */

            wColors,          /* pointer to source string */

            3,                /* length of string         */

            coord,            /* first cell to write to   */

            &cWritten);       /* actual number written to */

    if (! fSuccess)

        MyErrorExit("WriteConsoleOutputAttribute");

You can write the same character or color attribute to a specified number of consecutive screen buffer cells beginning at a specified location. The following example uses the FillConsoleOutputCharacter function to clear a 80-by-50-character screen buffer, and then it uses the FillConsoleOutputAttribute function to set the color attributes of the same cells.

/* Fill an 80-by-50-character screen buffer with the space character. */

    coord.X = 0;            /* start at first cell */

    coord.Y = 0;            /*   of first row      */

    chFillChar = ' ';

    fSuccess = FillConsoleOutputCharacter(

        hStdout,          /* screen buffer handle     */

        chFillChar,       /* fill with spaces         */

        80*50,            /* number of cells to fill  */

        coord,            /* first cell to write to   */

        &cWritten);       /* actual number written to */

    if (! fSuccess)

        MyErrorExit("FillConsoleOutputCharacter");

/* Set 80-by-50-character screen buffer colors to white text on red. */

    wColor = BACKGROUND_RED |

             FOREGROUND_RED |

             FOREGROUND_GREEN |

             FOREGROUND_BLUE;

    fSuccess = FillConsoleOutputAttribute(

        hStdout,          /* screen buffer handle     */

        wColor,           /* color to fill with       */

        80*50,            /* number of cells to fill  */

        coord,            /* first cell to write to   */

        &cWritten);       /* actual number written to */

    if (! fSuccess)

        MyErrorExit("FillConsoleOutputAttribute");


Reading and Writing Blocks of Characters and Attributes

The ReadConsoleOutput function copies a rectangular block of character and color data from a screen buffer into a destination buffer. The function treats the destination buffer as a two-dimensional array of CHAR_INFO structures. Similarly, the WriteConsoleOutput function copies a rectangular block of character and color attribute data from a source buffer to a console screen buffer. For more information about reading from or writing to rectangular blocks of screen buffer cells, see Low-Level Console Output Functions.

The following example uses the CreateConsoleScreenBuffer function to create a new screen buffer. After the SetConsoleActiveScreenBuffer function makes this the active screen buffer, a block of characters and attributes is copied from the top two rows of the SDTOUT screen buffer into a temporary buffer. The data is then copied from the temporary buffer into the new active screen buffer. When the application is finished using the new screen buffer, it calls SetConsoleActiveScreenBuffer to restore the original STDOUT screen buffer.

#include <windows.h>

VOID main(void) {

    HANDLE hStdout, hNewScreenBuffer;

    SMALL_RECT srctReadRect;

    SMALL_RECT srctWriteRect;

    CHAR_INFO chiBuffer[160]; // [2][80];

    COORD coordBufSize;

    COORD coordBufCoord;

    BOOL fSuccess;

    /*

     * Get a handle of the STDOUT screen buffer to copy from and

     * create a new screen buffer to copy to.

     */

    hStdout = GetStdHandle(STD_OUTPUT_HANDLE);

    hNewScreenBuffer = CreateConsoleScreenBuffer(

       GENERIC_READ |           /* read-write access      */

       GENERIC_WRITE,

       0,                       /* not shared             */

       NULL,                    /* no security attributes */

       CONSOLE_TEXTMODE_BUFFER, /* must be TEXTMODE       */

       NULL);                   /* reserved; must be NULL */

    if (hStdout == INVALID_HANDLE_VALUE ||

            hNewScreenBuffer == INVALID_HANDLE_VALUE)

        MyErrorExit("CreateConsoleScreenBuffer");

    /* Make the new screen buffer the active screen buffer. */

    if (! SetConsoleActiveScreenBuffer(hNewScreenBuffer) )

        MyErrorExit("SetConsoleActiveScreenBuffer");

    /* Set the source rectangle. */

    srctReadRect.Top = 0;    /* top left: row 0, col 0  */

    srctReadRect.Left = 0;

    srctReadRect.Bottom = 1; /* bot. right: row 1, col 79 */

    srctReadRect.Right = 79;

    /* The temporary buffer size is 2 rows x 80 columns. */

    coordBufSize.Y = 2;

    coordBufSize.X = 80;

    /* The top left destination cell of the temporary buffer is

     * row 0, col 0. */

    coordBufCoord.X = 0;

    coordBufCoord.Y = 0;

    /* Copy the block from the screen buffer to the temp. buffer. */

    fSuccess = ReadConsoleOutput(

       hStdout,        /* screen buffer to read from       */

       chiBuffer,      /* buffer to copy into              */

       coordBufSize,   /* col-row size of chiBuffer        */

       coordBufCoord,  /* top left dest. cell in chiBuffer */

       &srctReadRect); /* screen buffer source rectangle   */

    if (! fSuccess)

        MyErrorExit("ReadConsoleOutput");

    /* Set the destination rectangle. */

    srctWriteRect.Top = 10;    /* top lt: row 10, col 0 */

    srctWriteRect.Left = 0;

    srctWriteRect.Bottom = 11; /* bot. rt: row 11, col 79 */

    srctWriteRect.Right = 79;

    /* Copy from the temporary buffer to the new screen buffer. */

    fSuccess = WriteConsoleOutput(

        hNewScreenBuffer, /* screen buffer to write to    */

        chiBuffer,        /* buffer to copy from          */

        coordBufSize,     /* col-row size of chiBuffer    */

        coordBufCoord, /* top left src cell in chiBuffer  */

        &srctWriteRect); /* dest. screen buffer rectangle */

    if (! fSuccess)

        MyErrorExit("WriteConsoleOutput");

    Sleep(10000);

    /* Restore the original active screen buffer. */

    if (! SetConsoleActiveScreenBuffer(hStdout))

        MyErrorExit("SetConsoleActiveScreenBuffer");

}


Reading Input Buffer Events

You can use the ReadConsoleInput function to directly access a console's input buffer. When a console is created, mouse input is enabled and window input is disabled. To ensure that the process receives all types of events, this example uses the SetConsoleMode function to enable window and mouse input. Then it goes into a loop that reads and handles console input events.

VOID MouseEventProc(MOUSE_EVENT_RECORD);

VOID ResizeEventProc(WINDOW_BUFFER_SIZE_RECORD);

VOID KeyEventProc(KEY_EVENT_RECORD);

VOID GetInputEvents(VOID);

DWORD main(VOID) {

    HANDLE hStdin;

    DWORD cNumRead, fdwMode, fdwSaveOldMode, i;

    INPUT_RECORD irInBuf[128];

    /* Get the standard input handle. */

    hStdin = GetStdHandle(STD_INPUT_HANDLE);

    if (hStdin == INVALID_HANDLE_VALUE)

        MyErrorExit("GetStdHandle");

    /* Save the current input mode, to be restored on exit. */

    if (! GetConsoleMode(hStdin, &fdwSaveOldMode) )

        MyErrorExit("GetConsoleMode");

    /* Enable the window and mouse input events. */

    fdwMode = ENABLE_WINDOW_INPUT | ENABLE_MOUSE_INPUT;

    if (! SetConsoleMode(hStdin, fdwMode) )

        MyErrorExit("SetConsoleMode");

    /* Loop to read and handle the input events. */

    while (1) {

        /* Wait for the events. */

        if (! ReadConsoleInput(

                hStdin,      /* input buffer handle    */

                irInBuf,     /* buffer to read into    */

                128,         /* size of read buffer    */

                &cNumRead) ) /* number of records read */

            MyErrorExit("ReadConsoleInput");

        /* Dispatch the events to the appropriate handler. */

        for (i = 0; i < cNumRead; i++)

            switch(irInBuf[i].EventType) {

                case KEY_EVENT: /* keyboard input */

                    KeyEventProc(irInBuf[i].Event.KeyEvent);

                    break;

                case MOUSE_EVENT: /* mouse input */

                    MouseEventProc(irInBuf[i].Event.MouseEvent);

                    break;

                case WINDOW_BUFFER_SIZE_EVENT: /* screen buffer resizing */

                    ResizeEventProc(

                        irInBuf[i].Event.WindowBufferSizeEvent);

                    break;

                case FOCUS_EVENT: /* disregard focus events */

                case MENU_EVENT: /* disregard menu events  */

                    break;

                default:

                    MyErrorExit("unknown event type");

                    break;

            }

    }

    return 0;

}


Scrolling a Screen Buffer's Window

To scroll the contents of a screen buffer in the console window, call the SetConsoleWindowInfo function. You can also use this function to change the window size. The function can either specify the new upper left and lower right corners of the screen buffer's window as absolute screen buffer coordinates or specify the changes from the current window coordinates. The function fails if the specified window coordinates are outside the boundaries of the screen buffer.

The following example scrolls the view of the screen buffer up one line by modifying the absolute window coordinates returned by the GetConsoleScreenBufferInfo function.

HANDLE hStdout;

CONSOLE_SCREEN_BUFFER_INFO csbiInfo;

SMALL_RECT srctWindow;

hStdout = GetStdHandle(STD_OUTPUT_HANDLE);

/* Get the current screen buffer size and window position. */

if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo))

    MyErrorExit("GetConsoleScreenBufferInfo");

/* Set the srctWindow function to the current window size and location. */

srctWindow = csbiInfo.srWindow;

/* If the window is not at the screen buffer top, move it up one line. */

if ( srctWindow.Top > 0 ) {

    srctWindow.Top -= 1;      /* move top up by one row    */

    srctWindow.Bottom -= 1;   /* move bottom up by one row */

    if (! SetConsoleWindowInfo(

               hStdout,      /* screen buffer handle       */

               TRUE,         /* absolute coordinates       */

               &srctWindow)) /* specifies new location     */

        MyErrorExit("SetConsoleWindowInfo");

}

The same scrolling can be done by specifying the changes in the window coordinates.

/* Get the current screen buffer window position. */

if (! GetConsoleScreenBufferInfo(hStdout, &csbiInfo))

    MyErrorExit("GetConsoleScreenBufferInfo");

/* If the window is not at the screen buffer top, move it up one line. */

if (csbiInfo.srWindow.Top > 0) {

    srctWindow.Top = -1;      /* move top up by one row    */

    srctWindow.Bottom = -1;   /* move bottom up by one row */

    srctWindow.Left = 0;      /* no change                 */

    srctWindow.Right = 0;     /* no change                 */

    if (! SetConsoleWindowInfo(

               hStdout,      /* screen buffer handle   */

               FALSE,        /* deltas, not absolute   */

               &srctWindow)) /* specifies new location */

        MyErrorExit("SetConsoleWindowInfo");

}


Scrolling a Screen Buffer's Contents

The ScrollConsoleScreenBuffer function enables you to move a block of character cells from one part of a screen buffer to another part of the same screen buffer. The function specifies the upper left and lower right cells of the source rectangle to be moved and the destination coordinates of the new location for the upper left cell. The character and color data in the source cells is moved to the new location, and any cells left empty by the move are filled in with a specified character and color. If you specify a clipping rectangle, the cells outside of it are left unchanged.

You can use ScrollConsoleScreenBuffer to delete a line by specifying coordinates of the first cell in the line as the destination coordinates and specifying a scrolling rectangle that includes all the rows below the line.

The following example shows the use of a clipping rectangle to scroll only the bottom 15 rows of the screen buffer. The rows in the specified rectangle are scrolled up one line at a time, and the top row of the block is discarded. The contents of the screen buffer outside the clipping rectangle are left unchanged.

HANDLE hStdout;

BOOL fSuccess;

CONSOLE_SCREEN_BUFFER_INFO csbiInfo;

SMALL_RECT srctScrollRect, srctClipRect;

CHAR_INFO chiFill;

COORD coordDest;

hStdout = GetStdHandle(STD_OUTPUT_HANDLE);

if (hStdout == INVALID_HANDLE_VALUE)

    MyErrorExit("GetStdHandle");

/* Get the screen buffer size. */

fSuccess = GetConsoleScreenBufferInfo(hStdout, &csbiInfo);

if (! fSuccess)

    MyErrorExit("GetConsoleScreenBufferInfo");

/*

 * The scrolling rectangle is the bottom 15 rows of the

 * screen buffer.

 */

srctScrollRect.Top = csbiInfo.dwSize.Y - 16;

srctScrollRect.Bottom = csbiInfo.dwSize.Y - 1;

srctScrollRect.Left = 0;

srctScrollRect.Right = csbiInfo.dwSize.X - 1;

/* The destination for the scroll rectangle is one row up. */

coordDest.X = 0;

coordDest.Y = csbiInfo.dwSize.Y - 17;

/*

 * The clipping rectangle is the same as the scrolling rectangle.

 * The destination row is left unchanged.

 */

srctClipRect = srctScrollRect;

/* Fill the bottom row with green blanks. */

chiFill.Attributes = BACKGROUND_GREEN | FOREGROUND_RED;

chiFill.Char.AsciiChar = ' ';

/* Scroll up one line. */

fSuccess = ScrollConsoleScreenBuffer(

    hStdout,         /* screen buffer handle     */

    &srctScrollRect, /* scrolling rectangle      */

    &srctClipRect,   /* clipping rectangle       */

    coordDest,       /* top left destination cell*/

    &chiFill);       /* fill character and color */


Registering a Control Handler Function

This section shows an example of the SetConsoleCtrlHandler function that is used to install a control handler.

When a CTRL+C signal is received, the control handler returns TRUE, indicating that it has handled the signal. This prevents other control handlers from being invoked.

When a CTRL_CLOSE_EVENT signal is received, the control handler returns TRUE. This causes the system to display a dialog box that gives the user the choice of terminating the process and closing the console or allowing the process to continue execution. If the user chooses not to terminate the process, the system closes the console when the process finally terminates.

When a CTRL+BREAK, CTRL_LOGOFF_EVENT, or CTRL_SHUTDOWN_EVENT signal is received, the control handler returns FALSE. This causes the signal to be passed to the next control handler function. If no other control handlers have been registered or none of the registered handlers returns TRUE, the default handler will be invoked, resulting in the process being terminated.

BOOL CtrlHandler(DWORD fdwCtrlType) {

    switch (fdwCtrlType) {

        /* Handle the CTRL+C signal. */

        case CTRL_C_EVENT:

            Beep(1000, 1000);

            return TRUE;

        /* CTRL+CLOSE: confirm that the user wants to exit. */

        case CTRL_CLOSE_EVENT:

            return TRUE;

        /* Pass other signals to the next handler. */

        case CTRL_BREAK_EVENT:

        case CTRL_LOGOFF_EVENT:

        case CTRL_SHUTDOWN_EVENT:

        default:

            return FALSE;

    }

}

VOID main(void) {

BOOL fSuccess;

fSuccess = SetConsoleCtrlHandler(

    (PHANDLER_ROUTINE) CtrlHandler,  /* handler function */

    TRUE);                           /* add to list      */

if (! fSuccess)

    MyErrorExit("Could not set control handler");


Console Application Issues

The 8-bit console APIs use the OEM codepage. All other APIs use the ANSI codepage by default. This means that strings returned by the console APIs may not be processed correctly by the other APIs and vice versa. For example, if FindFirstFileA returns a string that contains certain extended ANSI characters, WriteConsoleA will not display the string properly.

The best long-term solution for a console application is to use Unicode. Short of that solution, a console application should use the SetFileApisToOEM function. That function changes the relevant Windows NT file functions so that they produce OEM character set strings rather than ANSI character set strings.

When dealing with command lines, a console  application should obtain the command line in Unicode form and convert it to OEM form using the relevant  character-to-OEM functions. Also, note that argv uses the ANSI character set.

Here is a list of Windows NT file functions that are involved in this situation:

_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	SetFileAttrributes

 GetDiskFreeSpace	GetWindowsDirectory


Functions

Following are the functions used to access a console.

AllocConsole

CreateConsoleScreenBuffer

FillConsoleOutputAttribute

FillConsoleOutputCharacter

FlushConsoleInputBuffer

FreeConsole

GenerateConsoleCtrlEvent

GetConsoleCP

GetConsoleCursorInfo

GetConsoleMode

GetConsoleOutputCP

GetConsoleScreenBufferInfo

GetConsoleTitle

GetLargestConsoleWindowSize

GetNumberOfConsoleInputEvents

GetNumberOfConsoleMouseButtons

GetStdHandle

PeekConsoleInput

ReadConsole

ReadConsoleInput

ReadConsoleOutput

ReadConsoleOutputAttribute

ReadConsoleOutputCharacter

ScrollConsoleScreenBuffer

SetConsoleActiveScreenBuffer

SetConsoleCP

SetConsoleCtrlHandler

SetConsoleCursorInfo

SetConsoleCursorPosition

SetConsoleMode

SetConsoleOutputCP

SetConsoleScreenBufferSize

SetConsoleTextAttribute

SetConsoleTitle

SetConsoleWindowInfo

SetStdHandle

WriteConsole

WriteConsoleInput

WriteConsoleOutput

WriteConsoleOutputAttribute

WriteConsoleOutputCharacter


Services Overview

About Services

In the Microsoft Win32 application programming interface (API), a service is an executable object that is installed in a registry database maintained by the service control manager. The services database includes information that determines whether each installed service is started on demand or is started automatically when the system starts up. The database can also contain logon and security information for a service so that a service can run even though no user is logged on. It also enables system administrators to customize security requirements for each service and thereby control access to the service. No more than one instance of a service can be running at a time.

Services can be divided into these two groups: Win32 services that conform to the interface rules of the service control manager and driver services that conform to the device driver protocols for Windows NT.

The following topics discuss Win32 services:

Terms

The Service Control Manager

Database of Installed Services

Win32 Service Programs

Service Configuration Programs

Service Control Programs

Service Security

Using Services

Writing a Service Program's Main()

Writing a ServiceMain Function

Writing a Service Control Handler Function

Opening an SCManager Database

Installing a Service

Deleting a Service

Reconfiguring a Service

Starting a Service

Querying a Service's Status

Controlling a Service


The Service Control Manager

A service control manager provides a unified and secure means of controlling services. Each machine that is running Windows NT has a service control manager process started by the system at system startup. The service control manager is a Remote Procedure Call (RPC) server. The functions in the Win32 API that access a service control manager are provided through RPC so that service configuration and service control processes can manipulate services on remote machines.

The Win32 API includes a set of functions that provide a programmer's interface for the following tasks performed by the service control manager:

Using the registry to maintain a database of installed service objects.

Starting services either when the system is starting up or on demand.

Maintaining status information on running services.

Transmitting control requests to running services.

Three types of programs use these functions:

Type	Description

Win32 service process

A process that provides executable code for one or more services. Win32 services use functions that connect to the service control manager and send status information to it. Driver services do not use these functions.

Service configuration program

A program that queries or modifies a service control manager database. Service configuration programs use functions that open a database, install or delete services in a database, and query or modify the configuration and security parameters of installed services. The functions are used to manipulate Win32 services and driver services.

Service control program

A program that starts a service and controls a running service. Service control programs use functions that send requests to the service control manager, which starts the requested service or sends the control request to the specified service.


Database of Installed Services

The service control manager maintains a ServicesActive database in the configuration registry. This is the currently active database that was used to start the system. The registry path to this database is HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services. In this directory, there is a <ServiceName> key for each installed Win32 service or driver service. The <ServiceName> key is the name of the service specified by the CreateService function when the service was installed.

The database includes the following information about each installed service:

The type of service. For Win32 services, the service type indicates whether the service executes in its own process or shares a process with other Win32 services. For driver services, it indicates whether the service is a kernel driver or a file system driver.

The start type of the service. The start type indicates whether the service is started automatically at system startup or whether the service control manager starts it when requested to by a service control process. The start type can also indicate whether the service is disabled, in which case it cannot be started.

A fully-qualified path of the service's executable file. The filename extension is .EXE for Win32 services and .SYS for driver services.

Optional information used by the service control manager to determine the proper order for starting services. This information can include a list of services that must be running before the service can start, the name of a load ordering group that the service is part of, and a tag identifier that indicates the start order of the service in its load ordering group.

For Win32 services, an optional logon account name in which the service process runs and an optional password for this account. If no account is specified, the service runs in the LocalSystem account.

For driver services, an optional Windows NT driver object name (for example, \FileSystem\Rdr or \Driver\Xns), used by the I/O system to load the device driver. If no name is specified, the I/O system creates a default name based on the service name.


Win32 Service Processes

A Win32 service process contains executable code for one or more services. To conform to the interface requirements of the service control manager, it must include:

A main function that immediately calls the StartServiceCtrlDispatcher function to connect the main thread of the process to the Service Control Manager.

An entry point function, ServiceMain, for each service that can run in the process.

A control handler function, Handler, for each service that can run in the process.

For simplicity, the discussions in this section use the term service to mean Win32 service. The information in this section does not apply to driver services.

Main Function

When the service control manager starts a service process, it waits for the process to call the StartServiceCtrlDispatcher function. If a service does not share a process with other services (SERVICE_WIN32_OWN_PROCESS services), the main thread of a service process should make this call immediately, leaving all initialization tasks to be performed by the ServiceMain function after the service is started. For services where multiple services share a process (SERVICE_WIN32_SHARE_PROCESS services) and where 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. Any service specific initialization should still be done by the individual ServiceMain functions.

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 calling 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 StartServiceCtrlDispatcher function specifies a dispatch table containing 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.

Service Main Function

Each service has a ServiceMain function that performs the initialization tasks for the service. A service process that can execute multiple services can have multiple ServiceMain functions.

When a service control program calls the StartService function to start a service, the service control manager starts the service process (if it is not already running). Then the service control manager sends the start request to the control dispatcher in the main thread of the service process. The dispatcher creates a new thread to execute the ServiceMain function for the specified service.

A ServiceMain function should perform the following ordered steps:

1	Call the RegisterServiceCtrlHandler function immediately to register a Handler function to handle control requests for the service. The return value of RegisterServiceCtrlHandler is a SERVICE_STATUS_HANDLE type that identifies the service in calls to the SetServiceStatus function.

2	Call SetServiceStatus to update the status of the service control manager information for the service. This function should specify the current service state as SERVICE_START_PENDING.

3	Complete the initialization tasks for the service, such as starting additional threads to perform the work of the service. If this initialization is time-consuming, the application should make additional calls to SetServiceStatus to report the progress of the initialization to the service control manager.

4	As one of the initialization tasks, call the CreateEvent function to create an event object. The other threads of the process, such as the control handling thread, use this event object to signal the ServiceMain function thread that it is time to terminate.

5	When initialization is complete, call SetServiceStatus to specify SERVICE_RUNNING as the current service state.

6	Call the WaitForSingleObject function to wait for the termination event object to be signaled. This blocks the execution of the ServiceMain function thread until the service is ready to terminate. The service's Handler function sets the event object to the signaled state if it receives the SERVICE_CONTROL_STOP control code. If an error occurs that requires service termination, other threads of the service can also signal the event object.

7	When the wait function returns, perform any cleanup tasks, and then return.

During lengthy initializations, the ServiceMain function should make frequent calls to SetServiceStatus to let the service control manager know that progress is being made. The following members of the SERVICE_STATUS structure specified by SetServiceStatus should change as the initialization progresses:

Member	Value

dwCurrentState	This value should be SERVICE_START_PENDING service state during initialization, changing to SERVICE_RUNNING when initialization is complete.

dwControlsAccepted	Control codes may be disabled during initialization. After initialization is complete, enable the desired control codes.

dwCheckPoint	This value lets the service control manager know how far initialization has progressed. Increment this value each time SetServiceStatus is called during lengthy initializations.

dwWaitHint	This value specifies a worst-case estimate of the amount of time in milliseconds that will elapse before the next status message will be sent out. If this interval elapses and the checkpoint has not been incremented, the service control manager or the service control program that started the service may assume that an error has occurred. Set this value to allow a generous amount of time to complete the next initialization step.

Control Handler Function

Each Win32 service has a control handler function, the Handler function, that is invoked by the main thread's control dispatcher when the service receives a control request. The service specifies the address of this function when it calls the RegisterServiceCtrlHandler entrypoint function, in its ServiceMain function. Control requests are generated by service control programs that call the ControlService function.

Whenever a service's Handler function is invoked, the service must call the SetServiceStatus function to report its status to the service control manager. This reporting must be done even if the service's status did not change.

The ControlService function can specify any of the standard control codes listed in the following table. All services must accept and process the SERVICE_CONTROL_INTERROGATE code. When a service calls SetServiceStatus, it can enable or disable the other standard control codes. Services can also handle additional user-defined control codes, which must be in the range 128 to 255, inclusive.

Control	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 update 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 the extremely limited time available for shutdown, this control should only be used by services that absolutely need to shut down. For instance, the eventlog service needs to clear a dirty bit in the files that it maintains, or the server service needs to shut down so that network connections cannot be 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 wait hint 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.


Service Configuration Programs

Service configuration programs are used by programmers or system administrators to query or modify a service control manager database. These databases are maintained in the configuration registry, so they can also be accessed by using the registry functions or a registry editor. It is, however, safer to use the service control manager's configuration functions, which ensure that the service is installed and configured properly.

Service control manager databases and services are implemented as objects that should only be accessed through the service control manager's configuration functions. A database of installed services is represented by an SCManager object, and an installed service is represented by a service object. An SCManager object is a container object that holds service objects.

The handle type of both SCManager objects and service objects is SC_HANDLE. The OpenSCManager function returns a handle to an SCManager object on a specified machine. The CreateService and OpenService functions return a handle to a service object installed in a specified SCManager object. The CloseServiceHandle function closes SC_HANDLE to either an SCManager object or a service object.

The functions that return SC_HANDLE can request different types of access to the SCManager or service object. The requested access is granted or denied depending on the access token of the calling process and the security descriptor associated with the SCManager or service object.

A configuration program uses the CreateService function to install a new service in an service control manager database. This function specifies the name of the service and provides the service's configuration information that is stored in the database. For a description of the information stored in the database for each service, see Database of Installed Services. The DeleteService function removes an installed service from its database.

The following functions are available to determine the current configuration of a service control manager database:

Function	Description

QueryServiceConfig

Fills in a buffer with a QUERY_SERVICE_CONFIG structure, containing the current configuration information for a specified service object.

QueryServiceObjectSecurity

Fills in a buffer with the SECURITY_DESCRIPTOR structure of a specified SCManager or service object.

EnumDependentServices

Fills in a buffer with an array of ENUM_SERVICE_STATUS structures, containing the name and current status of all services that are dependent on a specified service object.

EnumServicesStatus

Fills in a buffer with an array of ENUM_SERVICE_STATUS structures, containing the name and current status of all services in a specified SCManager object.

To modify the configuration information for a service object, a configuration program uses the ChangeServiceConfig function. To modify the security descriptor for either an SCManager object or a service object, a configuration program uses the SetServiceObjectSecurity function.

Before using either of these functions to reconfigure a service object, a program should use the LockServiceDatabase function. This function tries to acquire a lock on the specified service control manager database and, if successful, prevents the service control manager from starting a service while the database is being reconfigured. A lock should also be acquired before using the registry functions to reconfigure a service object. Note, however, that failure to acquire a lock does not prevent a configuration program from successfully reconfiguring a service object. The only effect of a lock is to prevent the service control manager from starting a service in the locked database. To release the lock on the database when the reconfiguration is complete, use the UnlockServiceDatabase function. To determine whether the database is locked, use the QueryServiceLockStatus function.


Service Control Programs

A service control program performs the following actions:

Starts a Win32 service or a driver service, if the service's start type is SERVICE_DEMAND_START.

Sends control requests to a running service.

Queries the current status of a running service.

The program must have an open handle to any service object that it wants to start or control. To do this, it must perform these steps:

1	Use the OpenSCManager function to open a handle to a service control manager database on a specified machine.

2	Use the OpenService or CreateService function to open a handle to the desired service object.

Service Startup

To start a service, use the StartService function. For Win32 services, the calling process can use the parameters of this function to specify an array of arguments that are passed to the ServiceMain function of the service. This function fails if the service control manager database is locked. If this occurs, the service control program can wait a few seconds and call StartService again. It can check the current lock status of the database by calling the QueryServiceLockStatus function.

When starting a driver service, StartService returns after the device driver has completed its initialization.

When starting a Win32 service, StartService returns after the ServiceMain function thread for the new service has been created. During its initialization, a service specifies a SERVICE_STATUS structure in calls to the SetServiceStatus function to report its progress to the service control manager. The service control program can retrieve this status information by calling the QueryServiceStatus function. During initialization, the dwCurrentState member of the SERVICE_STATUS structure should be SERVICE_START_PENDING. The service should increment the dwCheckPoint member at regular intervals during initialization. The dwWaitHint member is a time interval, in milliseconds, that indicates how long the service control program should wait before calling QueryServiceStatus again. When the initialization is complete, the service changes the dwCurrentState member to SERVICE_RUNNING.

Service Control Requests

To send control requests to a running service, use the ControlService function. This function specifies a control code that is passed to the Handler function of the specified service. This control code can be a user-defined code, or it can be one of the standard codes that enable the calling program to perform the following actions:

Stops or pauses a service.

Resumes a paused service.

Gets updated status information from a service.

Each service specifies the control codes that it will accept and process. To determine which of the standard control codes are accepted by a service, use the QueryServiceStatus function or specify the SERVICE_CONTROL_INTERROGATE control code in a call to the ControlService function. The dwControlsAccepted member of the SERVICE_STATUS structure returned by these functions indicates whether the service can be stopped and whether it can be paused and resumed. All services accept the SERVICE_CONTROL_INTERROGATE control code, which requests the service to immediately report its current status.

Note, however, that the QueryServiceStatus function reports the service control manager's most recent status for a specified service, but does not get an updated status from the service itself. Using the SERVICE_CONTROL_INTERROGATE control code in a call to ControlService ensures that the status information returned is current.


Service Security

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 access enables any process to open a service control manager database handle that it can use for the OpenService, EnumServicesStatus, and QueryServiceLockStatus functions. Only processes with Administrator privileges are able to open a database handle that can be used by the CreateService and LockServiceDatabase functions.

Security for service objects is provided by an access check performed when a process uses the OpenService function. The access permitted to different users depends on the SECURITY_DESCRIPTOR structure associated with the service object. The service control manager creates a service object's security descriptor when the service is installed by the CreateService function. You can use the QueryServiceObjectSecurity and SetServiceObjectSecurity functions to query and set the security descriptor of a service object. The default security descriptor of a service object permits the following access:

All users have SERVICE_QUERY_CONFIG, SERVICE_QUERY_STATUS, SERVICE_ENUMERATE_DEPENDENTS, SERVICE_INTERROGATE, and SERVICE_USER_DEFINED_CONTROL access.

Local users have SERVICE_START access in addition to those listed above.

LocalSystem users and PowerUsers have SERVICE_START, SERVICE_PAUSE_CONTINUE, and SERVICE_STOP access in addition to those listed above.

Administrators have SERVICE_ALL_ACCESS access.

Win32 Service User Accounts

Each Win32 service runs in a user account. The username and password of an account are specified by the CreateService function at the time the service is installed. The user name and password can be changed by using the ChangeServiceConfig function. You can use the QueryServiceConfig function to get the user name (but not the password) of a service object.

When starting a service process, the service control manager logs on to the account associated with the service. If the log on is successful, the system produces an access token and attaches it to the new service process. This token identifies the service process in all subsequent interactions with securable objects (objects that have a security descriptor associated with them). For example, if the service tries to open a handle to a pipe, the system compares the service's access token to the pipe's security descriptor before granting access.

A SERVICE_WIN32_OWN_PROCESS service that runs in a process by itself can have an account from either the built-in (local), primary, or trusted domain. A SERVICE_WIN32_SHARE_PROCESS service that can share a process with multiple services must be installed to run in the LocalSystem account. This restriction exists because different services in the same process must run under the same security context.

The service control manager does not try to maintain the passwords of service user accounts. If a password is expired, the logon fails and the service fails to start. The system administrator who assigns accounts to services can create accounts with passwords that never expire. The administrator can also manage accounts with passwords that expire by using a service configuration program to periodically change the passwords.

If a service needs to recognize another service before sharing its information, the second service can either use the same account as the first service, or it can run in an account belonging to an alias that is recognized by the first service. Services that need to run in a distributed manner across the network should run in domain-wide accounts.


Using Services

The examples in this section illustrate the following:

The main function of a Win32 service process

The entry point function, ServiceMain, of a Win32 service process

The control handler function, Handler, of a Win32 service process

Opening a service control manager database

Installing and deleting a service in a service control manager database

Changing or querying the configuration of an installed service

Starting a service

Sending control requests to a running service


Writing a Win32 Service Process's %main% Function
Writing a Win32 Service Process's main Function

Writing a Win32 Service Process's main Function

The main function of a Win32 service process must call the StartServiceCtrlDispatcher function as soon as possible. For service processes that execute only one service, the function is called immediately, because the service's ServiceMain function can perform all initialization tasks for the service. The following example shows the main function for a SERVICE_WIN32_OWN_PROCESS service process:

/* Globals */

SERVICE_STATUS ssStatus;

HANDLE hServDoneEvent = NULL;

SERVICE_STATUS_HANDLE sshStatusHandle;

/* Exit code that is set by any thread when error occurs. */

DWORD dwGlobalErr = NO_ERROR;

VOID main(VOID) {

  SERVICE_TABLE_ENTRY   steDispatchTable[] = {

      /* entry for "Sample_Srv" */

      { TEXT("Sample_Srv"),

        (LPSERVICE_MAIN_FUNCTION) ServMainFunc},

      /* NULL entry designating the end of the table. */

      { NULL, NULL }

  };

  /*

   * The main thread of a service process starts the service control

   * dispatcher that dispatches start and control requests

   * for the services specified in steDispatchTable. This

   * function does not return unless there is an error.

   */

  if (! StartServiceCtrlDispatcher(steDispatchTable) )

      MyErrorExit("StartServiceCtrlDispatcher");

}

When a service process will execute multiple services, it may be necessary to perform some common process-wide initialization before starting any of the services. If this initialization is brief (less than 30 seconds), the main thread can do it before calling the StartServiceCtrlDispatcher function. Otherwise, you can use one of the following strategies:

Use the CreateThread function to create a thread to perform the initialization.

Use a global flag that each service's ServiceMain function checks during its initialization so that the first service to start up performs the common initialization.

Other than these initialization issues and the fact that there is a dispatch table with additional entries, the main thread of a multiple service process does not differ from that of a service process with a single service.


Writing a ServiceMain Function

The ServMainFunc function in the following example is the service's entry point function, ServiceMain. It first calls the RegisterServiceCtrlHandler function to register the Handler function, called the ServCtrlHandler function in this example. Then it calls the ReportStatusToSCMgr subroutine, which updates the service's status by calling the SetServiceStatus function. As the initialization tasks are completed, it makes additional status updates, incrementing the checkpoint value each time.

As part of the initialization, the service calls the CreateEvent function to create the hServDoneEvent event object. The initial state of hServDoneEvent is not-signaled. After the initialization is complete, the service updates its status to SERVICE_RUNNING (with checkpoint and waithint values set to zero). Then it calls the WaitForSingleObject function to wait for the state of hServDoneEvent, to be signaled. When this occurs, the ServMainFunc function updates the services status to SERVICE_STOPPED, cleans up, and exits.

/*

 * ServiceMain function of "Sample_Srv"

 *

 * When the service is started, the service control dispatcher

 * creates a new thread to execute this function.

 */

VOID ServiceMain(DWORD dwArgc, LPTSTR *lpszArgv) {

  DWORD dwWait;

  /* Register the control handler function for this service. */

  sshStatusHandle = RegisterServiceCtrlHandler(

      TEXT("Sample_Srv"), /* service name             */

      ServCtrlHandler);   /* control handler function */

  if (sshStatusHandle == (SERVICE_STATUS_HANDLE) NULL)

      goto Cleanup;

  /* SERVICE_STATUS members that do not change in example. */

  ssStatus.dwServiceType = SERVICE_WIN32_OWN_PROCESS;

  ssStatus.dwServiceSpecificExitCode = 0;

  /* Report the status to service control manager. */

  if (! ReportStatusToSCMgr(

      SERVICE_START_PENDING, /* service state */

      NO_ERROR,              /* exit code     */

      1,                     /* checkpoint    */

      3000) )                /* wait hint     */

      goto Cleanup;

  /*

   * Create the event object. The control handler function signals

   * this event when it receives the "stop" control code.

   */

  hServDoneEvent = CreateEvent (

     NULL,    /* no security attributes */

     TRUE,    /* manual reset event     */

     FALSE,   /* nonsignaled            */

     NULL);   /* no name                */

  if ( hServDoneEvent == (HANDLE) NULL )

      goto Cleanup;

  /* Report the status to the service control manager. */

  if (! ReportStatusToSCMgr(

      SERVICE_START_PENDING, /* service state */

      NO_ERROR,              /* exit code     */

      2,                     /* checkpoint    */

      3000) )                /* wait hint     */

      goto Cleanup;

  /* Start the thread that performs the work of the service. */

  if (! SampleServiceInit() )

      goto Cleanup;

  /* Report the status to the service control manager. */

  if (! ReportStatusToSCMgr(

      SERVICE_RUNNING, /* service state */

      NO_ERROR,        /* exit code     */

      0,               /* checkpoint    */

      0) )             /* wait hint     */

      goto Cleanup;

  /* Wait indefinitely until hServDoneEvent is signaled. */

  dwWait = WaitForSingleObject (

    hServDoneEvent,  /* event object      */

    INFINITE);       /* wait indefinitely */

Cleanup :

  if (hServDoneEvent != NULL)

     CloseHandle(hServDoneEvent);

  /* Try to report the stopped status to the service control manager. */

  if (sshStatusHandle != NULL)

      (VOID) ReportStatusToSCMgr(SERVICE_STOPPED,

                             dwGlobalErr, 0, 0);

  /*

   * When ServiceMain function returns in a single service

   * process, the StartServiceCtrlDispatcher function in

   * the main thread returns, terminating the process.

   */

  return;

}

/*

 * ReportStatusToSCMgr function

 *

 * This function is called by the ServMainFunc() and

 * ServCtrlHandler() functions to update the service's status

 * to the service control manager.

 */

BOOL ReportStatusToSCMgr (DWORD dwCurrentState,

     DWORD dwWin32ExitCode, DWORD dwCheckPoint,

     DWORD dwWaitHint) {

  BOOL fResult;

  /* Disable control requests until the service is started. */

  if (dwCurrentState == SERVICE_START_PENDING)

      ssStatus.dwControlsAccepted = 0;

  else

      ssStatus.dwControlsAccepted = SERVICE_ACCEPT_STOP |

          SERVICE_ACCEPT_PAUSE_CONTINUE;

  /* These SERVICE_STATUS members are set from parameters. */

  ssStatus.dwCurrentState = dwCurrentState;

  ssStatus.dwWin32ExitCode = dwWin32ExitCode;

  ssStatus.dwCheckPoint = dwCheckPoint;

  ssStatus.dwWaitHint = dwWaitHint;

  /* Report the status of the service to the service control manager. */

  if (! (fResult = SetServiceStatus (

      sshStatusHandle,    /* service reference handle */

      &ssStatus) ) ) {    /* SERVICE_STATUS structure */

      /* If an error occurs, stop the service. */

      StopSampleService("SetServiceStatus");

  }

  return fResult;

}

/*

* The StopSampleService function can be used by any thread to report an

* error, or stop the service.

*/

VOID StopSampleService(LPTSTR lpszMsg) {

CHAR chMsg[256];

HANDLE hEventSource;

LPTSTR lpszStrings[2];

  dwGlobalErr = GetLastError();

  /*  Use event logging to log the error. */

  hEventSource = RegisterEventSource(NULL,

                         TEXT("Sample_Srv"));

  sprintf(chMsg, "Sample_Srv error: %d", dwGlobalErr);

  lpszStrings[0] = chMsg;

  lpszStrings[1] = lpszMsg;

  if (hEventSource != NULL) {

      ReportEvent(hEventSource, /* handle of event source */

          EVENTLOG_ERROR_TYPE,  /* event type             */

          0,                    /* event category         */

          0,                    /* event ID               */

          NULL,                 /* current user's SID     */

          2,                    /* strings in lpszStrings */

          0,                    /* no bytes of raw data   */

          lpszStrings,          /* array of error strings */

          NULL);                /* no raw data            */

      (VOID) DeregisterEventSource(hEventSource);

  }

  /* Set a termination event to stop ServiceMain function. */

  SetEvent(hServDoneEvent);

}


Writing a Service Control Handler Function

Writing a Control Handler Function

The ServCtrlHandler function in the following example is the service's control handler function, Handler function. When this function is called by the main thread's control dispatcher, it handles the control request and then calls the ReportStatusToSCMgr subroutine to update the service's status.

/*

 * The service control dispatcher invokes this function when it

 * gets a control request from the service control manager.

 */

VOID ServCtrlHandler (DWORD dwCtrlCode) {

  DWORD  dwState = SERVICE_RUNNING;

  /* Handle the requested control code. */

  switch(dwCtrlCode) {

      /* Pause the service if it is running. */

      case SERVICE_CONTROL_PAUSE:

          if (ssStatus.dwCurrentState == SERVICE_RUNNING) {

              PauseSampleService();

              dwState = SERVICE_PAUSED;

          }

          break;

      /* Resume the paused service. */

      case SERVICE_CONTROL_CONTINUE:

          if (ssStatus.dwCurrentState == SERVICE_PAUSED) {

              ResumeSampleService();

              dwState = SERVICE_RUNNING;

          }

          break;

      /* Stop the service. */

      case SERVICE_CONTROL_STOP:

          dwState = SERVICE_STOP_PENDING;

          /*

           * Report the status, specifying the checkpoint and waithint,

           * before setting the termination event.

           */

          (VOID) ReportStatusToSCMgr(

                   SERVICE_STOP_PENDING, /* current state */

                   NO_ERROR,             /* exit code     */

                   1,                    /* checkpoint   */

                   3000);                /* waithint     */

          SetEvent(hServDoneEvent);

          return;

      /* Update the service status. */

      case SERVICE_CONTROL_INTERROGATE:

          break;

      /* invalid control code */

      default:

          break;

    }

    /* Send a status response. */

    (VOID) ReportStatusToSCMgr(dwState, NO_ERROR, 0, 0);

}


Opening an SCManager Database

The examples in the following sections require an open handle to an SCManager database object. Different operations on a service control manager database require different levels of access, and you should only request the minimum access required. If SC_MANAGER_ALL_ACCESS is requested, the OpenSCManager function fails if the calling process does not have Administrator privileges. The following example shows how to request full access to the ServicesActive database on the local machine.

/* Open a handle to the SC Manager database. */

schSCManager = OpenSCManager(

     NULL,                   /* local machine           */

     NULL,                   /* ServicesActive database */

     SC_MANAGER_ALL_ACCESS); /* full access rights      */

if (schSCManager == NULL)

    MyErrorExit("OpenSCManager");


Installing a Service

A service configuration program uses the CreateService function to install a service in a service control manager database. The schSCManager handle must have SC_MANAGER_CREATE_SERVICE access to the SCManager object. The following example shows how to install a service.

VOID CreateSampleService() {

LPCTSTR lpszBinaryPathName =

          TEXT("%SystemRoot%\\system\\testserv.exe");

  schService = CreateService(

       schSCManager,              /* SCManager database     */

       TEXT("Sample_Srv"),        /* name of service        */

       SERVICE_ALL_ACCESS,        /* desired access         */

       SERVICE_WIN32_OWN_PROCESS, /* service type           */

       SERVICE_DEMAND_START,      /* start type             */

       SERVICE_ERROR_NORMAL,      /* error control type     */

       lpszBinaryPathName,        /* service's binary       */

       NULL,                      /* no load ordering group */

       NULL,                      /* no tag identifier      */

       NULL,                      /* no dependencies        */

       NULL,                      /* LocalSystem account    */

       NULL);                     /* no password            */

  if (schService == NULL)

      MyErrorExit("CreateService");

  else

      printf("CreateService SUCCESS\n");

  CloseServiceHandle(schService);

}


Deleting a Service

In the following example, a service configuration program uses the OpenService function to get a handle with DELETE access to an installed service object. The program then uses the service object handle in the DeleteService function to remove the service from the service control manager database.

VOID DeleteSampleService() {

  schService = OpenService(

       schSCManager,       /* SCManager database      */

       TEXT("Sample_Srv"), /* name of service         */

       DELETE);            /* only need DELETE access */

  if (schService == NULL)

      MyErrorExit("OpenService");

  if (! DeleteService(schService) )

      MyErrorExit("DeleteService");

  else

      printf("DeleteService SUCCESS\n");

  CloseServiceHandle(schService);

}


Reconfiguring a Service

Changing a Service Configuration

In the following example, a service configuration program uses the ChangeServiceConfig function to change the configuration parameters of an installed service. The program first tries to lock the database, to prevent the service control manager from starting a service while it is being reconfigured. If it successfully locks the database, the program opens a handle to the service object, modifies its configuration, unlocks the database, and then closes the service  object handle. If the program does not successfully in lock the database, it uses the QueryServiceLockStatus function to retrieve information about the lock.

VOID ReconfigureSampleService(BOOL fDisable) {

SC_LOCK sclLock;

LPQUERY_SERVICE_LOCK_STATUS lpqslsBuf;

DWORD dwBytesNeeded, dwStartType;

  /* Need to acquire database lock before reconfiguring. */

  sclLock = LockServiceDatabase(schSCManager);

  /* If the database cannot be locked, report the details. */

  if (sclLock == NULL) {

      /* Exit if the database is not locked by another process. */

      if (GetLastError() != ERROR_SERVICE_DATABASE_LOCKED)

          MyErrorExit("LockServiceDatabase");

      /* Allocate a buffer to get details about the lock. */

      lpqslsBuf = (LPQUERY_SERVICE_LOCK_STATUS) LocalAlloc(

          LPTR, sizeof(QUERY_SERVICE_LOCK_STATUS)+256);

      if (lpqslsBuf == NULL)

          MyErrorExit("LocalAlloc");

      /* Get and print the lock status information. */

      if (! QueryServiceLockStatus(

          schSCManager,

          lpqslsBuf,

          sizeof(QUERY_SERVICE_LOCK_STATUS)+256,

          &dwBytesNeeded) )

          MyErrorExit("QueryServiceLockStatus");

      if (lpqslsBuf->fIsLocked)

          printf("Locked by: %s, duration: %d seconds\n",

              lpqslsBuf->lpLockOwner,

              lpqslsBuf->dwLockDuration);

      else

          printf("No longer locked\n");

      LocalFree(lpqslsBuf);

      MyErrorExit("Could not lock database");

  }

  /* The database is locked, so it is safe to make changes. */

  /* Open a handle to the service. */

  schService = OpenService(

       schSCManager,           /* SCManager database */

       TEXT("Sample_Srv"),     /* name of service    */

       SERVICE_CHANGE_CONFIG); /* need CHANGE access */

  if (schService == NULL)

      MyErrorExit("OpenService");

  dwStartType = (fDisable) ? SERVICE_DISABLED :

                             SERVICE_DEMAND_START;

  if (! ChangeServiceConfig(

       schService,        /* handle of service            */

       SERVICE_NO_CHANGE, /* service type: no change      */

       dwStartType,       /* *change* service start type  */

       SERVICE_NO_CHANGE, /* error control: no change     */

       NULL,              /* binary path: no change       */

       NULL,              /* load order group: no change  */

       NULL,              /* tag ID: no change            */

       NULL,              /* dependencies: no change      */

       NULL,              /* account name: no change      */

       NULL) )            /* password: no change          */

      MyErrorExit("ChangeServiceConfig");

  else

      printf("ChangeServiceConfig SUCCESS\n");

  /* Release the database lock. */

  UnlockServiceDatabase(sclLock);

  /* Close the handle to the service. */

  CloseServiceHandle(schService);

}


Querying a Service's Configuration

In the following example, a service configuration program uses the OpenService function to get a handle with SERVICE_QUERY_CONFIG access to an installed service object. Then the program uses the service object handle in the QueryServiceConfig function to retrieve the current configuration of the service.

VOID GetSampleServiceConfig() {

LPQUERY_SERVICE_CONFIG lpqscBuf;

DWORD dwBytesNeeded;

  /* Open a handle to the service. */

  schService = OpenService(

       schSCManager,           /* SCManager database  */

       TEXT("Sample_Srv"),     /* name of service     */

       SERVICE_QUERY_CONFIG);  /* need QUERY access   */

  if (schService == NULL)

      MyErrorExit("OpenService");

  /* Allocate a buffer for the information configuration. */

  lpqscBuf = (LPQUERY_SERVICE_CONFIG) LocalAlloc(

                                       LPTR, 4096);

  if (lpqscBuf == NULL)

      MyErrorExit("LocalAlloc");

  /* Get and print the information configuration. */

  if (! QueryServiceConfig(

      schService,

      lpqscBuf,

      4096,

      &dwBytesNeeded) )

      MyErrorExit("QueryServiceConfig");

  printf("\nSample_Srv configuration: \n");

  printf("  Type: 0x%x\n", lpqscBuf->dwServiceType);

  printf("  Start Type: 0x%x\n", lpqscBuf->dwStartType);

  printf("  Err Control: 0x%x\n", lpqscBuf->dwErrorControl);

  printf("  Binary path: %s\n", lpqscBuf->lpBinaryPathName);

  if (lpqscBuf->lpLoadOrderGroup != NULL)

      printf("  Load order group: %s\n",

                 lpqscBuf->lpLoadOrderGroup);

  if (lpqscBuf->dwTagId != 0)

      printf("  Tag ID: %d\n", lpqscBuf->dwTagId);

  if (lpqscBuf->lpDependencies != NULL)

      printf("  Dependencies: %s\n", lpqscBuf->lpDependencies);

  if (lpqscBuf->lpServiceStartName != NULL)

      printf("  Start Name: %s\n",

                 lpqscBuf->lpServiceStartName);

  LocalFree(lpqscBuf);

}


Starting a Service

To start a service, the following example opens a handle to an installed database and then specifies the handle in a call to the StartService function. StartService can be used to start either a Win32 service or a driver service, but this example assumes that a Win32 service is being started. After starting the service, the program uses the members of the SERVICE_STATUS structure returned by the QueryServiceStatus function to track the progress of the Win32 service.

VOID StartSampleService() {

SERVICE_STATUS ssStatus;

DWORD dwOldCheckPoint;

  schService = OpenService(

       schSCManager,          /* S. C. Manager database */

       TEXT("Sample_Srv"),    /* name of service        */

       SERVICE_ALL_ACCESS);

     //  SERVICE_START |        /* need START access  */

     //  SERVICE_QUERY_CONFIG); /* and QUERY access   */

  if (schService == NULL)

      MyErrorExit("OpenService");

  if (! StartService(schService, /* handle of service   */

            0,                   /* number of arguments */

            NULL) )              /* no arguments        */

      MyErrorExit("StartService");

  else

      printf("Service start pending\n");

  /* Check the status until the service is running. */

  if (! QueryServiceStatus(

      schService,   /* handle of service       */

      &ssStatus) )  /* address of status info  */

      MyErrorExit("QueryServiceStatus");

  while (ssStatus.dwCurrentState != SERVICE_RUNNING) {

      /* Save the current checkpoint. */

      dwOldCheckPoint = ssStatus.dwCheckPoint;

      /* Wait for the specified interval. */

      Sleep(ssStatus.dwWaitHint);

      /* Check the status again. */

      if (! QueryServiceStatus(

              schService,   /* handle of service       */

              &ssStatus) )  /* address of status info  */

          break;

      /* Break if the checkpoint has not been incremented. */

      if (dwOldCheckPoint >= ssStatus.dwCheckPoint)

          break;

  }

  if (ssStatus.dwCurrentState == SERVICE_RUNNING)

      printf("StartService SUCCESS\n");

  else {

      printf("\nService not started: \n");

      printf("  Current State: %d\n",

                   ssStatus.dwCurrentState);

      printf("  Exit Code: %d\n", ssStatus.dwWin32ExitCode);

      printf("  Service Specific Exit Code: %d\n",

                   ssStatus.dwServiceSpecificExitCode);

      printf("  Check Point: %d\n", ssStatus.dwCheckPoint);

      printf("  Wait Hint: %d\n", ssStatus.dwWaitHint);

  }

  CloseServiceHandle(schService);

}


Controlling a Service

Sending Control Requests to a Service

The following example uses the ControlService function to send a control code to a running service. Different control codes require different levels of access to the service object. For example, a service object handle must have SERVICE_STOP access to send the SERVICE_CONTROL_STOP code. When ControlService returns, a SERVICE_STATUS structure contains the latest status information for the service.

VOID ControlSampleService(DWORD fdwControl) {

SERVICE_STATUS ssStatus;

DWORD fdwAccess;

  /* The required service object access depends on the control. */

  switch (fdwControl) {

      case SERVICE_CONTROL_STOP:

          fdwAccess = SERVICE_STOP;

          break;

      case SERVICE_CONTROL_PAUSE:

      case SERVICE_CONTROL_CONTINUE:

          fdwAccess = SERVICE_PAUSE_CONTINUE;

          break;

      case SERVICE_CONTROL_INTERROGATE:

          fdwAccess = SERVICE_INTERROGATE;

          break;

      default:

          fdwAccess = SERVICE_INTERROGATE;

  }

  /* Open a handle to the service. */

  schService = OpenService(

       schSCManager,        /* SCManager database */

       TEXT("Sample_Srv"),  /* name of service    */

       fdwAccess);          /* specify access     */

  if (schService == NULL)

      MyErrorExit("OpenService");

  /* Send a control code to the service. */

  if (! ControlService(

      schService,   /* handle of service       */

      fdwControl,   /* control code to send    */

      &ssStatus) )  /* address of status info  */

      MyErrorExit("ControlService");

  /* Print the service status. */

  printf("\nStatus of Sample_Srv: \n");

  printf("  Service Type: 0x%x\n", ssStatus.dwServiceType);

  printf("  Current State: 0x%x\n", ssStatus.dwCurrentState);

  printf("  Controls Accepted: 0x%x\n",

               ssStatus.dwControlsAccepted);

  printf("  Exit Code: %d\n", ssStatus.dwWin32ExitCode);

  printf("  Service Specific Exit Code: %d\n",

               ssStatus.dwServiceSpecificExitCode);

  printf("  Check Point: %d\n", ssStatus.dwCheckPoint);

  printf("  Wait Hint: %d\n", ssStatus.dwWaitHint);

  return;

}

Functions

Following are the Win32 functions used by services and by programs that control or configure services:

ChangeServiceConfig

CloseServiceHandle

ControlService

CreateService

DeleteService

EnumDependentServices

EnumServicesStatus

Handler

LockServiceDatabase

OpenSCManager

OpenService

QueryServiceConfig

QueryServiceLockStatus

QueryServiceObjectSecurity

QueryServiceStatus

RegisterServiceCtrlHandler

ServiceMain

SetServiceObjectSecurity

SetServiceStatus

StartService

StartServiceCtrlDispatcher

UnlockServiceDatabase


Tape Backup Overview

About Tape Backup

In Microsoft® Windows™, a tape volume consists of a recording medium and its physical carrier. The entire length of tape in a volume is not available for recording data. Short sections at the beginning and the end of the tape are reserved for attaching the tape to the hubs in the carrier. The first position on the tape where data can be recorded is the called the beginning-of-medium marker, and the last position is called the end-of-medium marker.

Every tape volume has one or more partitions. A partition is a portion of the volume, with its own beginning and ending points that does not overlap with any other portion of the volume. Each partition has three predefined positions. The first position in a partition  you can record data is called the beginning-of-partition marker, and the last is called end-of-partition marker. The early-warning position is located immediately before the end-of-partition.The early-warning position notifies type applications to transfer buffered data to the tape before reaching the end-of-partition.

The area between a partition's beginning and ending points is typically divided into sections by filemarks or setmarks. Filemarks and setmarks are special recorded elements that do not contain user data, but simply divide the partition into smaller areas to provide an address scheme. Filemarks and setmarks serve similar purposes, but setmarks provide faster positioning on high-capacity tape drives.

Typically, tape devices support filemarks and setmarks. This enables tape data to be formatted such that setmarks separate data from different disk volumes and filemarks separate data from individual files on a disk volume.

Another recorded element that denotes locations on the tape is an erase gap, an area of erased tape or a pattern that the device does not recognize as a mark or as user data.

There are three types of 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 enables an application to position the tape at the beginning of the filemark and to overwrite the filemark and the erase gap. A normal filemark does not contain an erase gap. Tape devices that use filemarks support either short and long filemarks or normal filemarks, but not all three.

The area on a partition between setmarks or filemarks is available for recording data. The unit of data written to or read from a tape is referred to as a block.

The tape functions provided in the Win32™ application programming interface (API) enable backup applications to read from and write to a tape, initialize a tape, and retrieve tape or tape drive information.

The following topics discuss tape backup:

Terms

Tape Initialization

Tape Input and Output

Creating A Backup Application

Backing Up and Restoring Posix File Links

Functions


Tape Initialization

An application must use the CreateFile function to create a handle of a tape device. This handle is used in subsequent operations on the tape in the device.

Before an application writes to a tape, the tape must be formatted according to the needs of the application and the capabilities of the tape drive being used. The CreateTapePartition function reformats a tape, creating on it a specified number of partitions of a specified size.

The PrepareTape function prepares a tape to be accessed or removed. This function can load, unload, lock, or unlock a tape. This function can also tension the tape by moving the tape to the end-of-medium and back to the beginning-of-medium.

To retrieve and set information about an application tape and tape drive, an application uses the GetTapeParameters, SetTapeParameters, and GetTapeStatus functions.

GetTapeParameters retrieves information that describes a tape or a tape drive. The tape information includes the tape's type, density, and block size, the number of partitions on the tape, the amount of tape remaining, and so on. The tape drive information includes the drive's default block size, the maximum partition count, and the features that are supported.

SetTapeParameters either sets the tape block size or sets the tape drive flags that indicate whether the drive supports hardware error correction, data compression, or data padding, or any combination of the three.

GetTapeStatus indicates whether the tape drive is ready to process tape commands.


Tape Input and Output

The Win32 API provides several functions that applications can use to perform input and output (I/O) on a tape drive. Tape I/O is similar to I/O performed on a communications device.

Please note the following when dealing with tape I/O: some tape drives store tape firmware information in the first few blocks on a tape, typically using some portion of the first 100 blocks. Applications should not use those blocks. More specific information on this subject is available from individual tape system manufacturers. In general, an application that skips the first 100 blocks on a tape will avoid tape-specific idiosyncracies.

The GetTapePosition and SetTapePosition functions retrieve and move the current tape position. The WriteTapemark function writes a specified number of setmarks, filemarks, short filemarks, and long filemarks. The EraseTape function erases all or part of a tape.

The ReadFile and WriteFile functions read and write file data from and to the tape. The data is read and written in complete blocks. If the tape's block size is 512 bytes, all read and write operations must use buffers that are simple integer multiples of that block size: 512, 1024, 1536, 2048, etc. Most, if not all, drives only allow a write operation after the tape is rewound or after a read operation produces an end-of-data error message.

If ReadFile encounters a filemark, the data up to the filemark is read and the function fails. (The GetLastError function returns an error code indicating the type of filemark that was encountered.) To continue reading beyond the filemark, the application must move the tape past the filemark and call ReadFile again.

ReadFile and WriteFile read and write only the data stream. The BackupRead and BackupWrite functions read and write all the streams associated with a file. These include data, extended attributes, security, and alternative data streams. The security and alternate data streams are relevant only on the new technology file system (NTFS) partition.

The BackupSeek function seeks forward in a file being accessed by BackupRead or BackupWrite. This enables an application to skip information that causes access errors.

If an application needs to access only the file data, it should use ReadFile and WriteFile. These functions can also read alternative data streams if the streams were created by using the CreateFile function.

A tape-backup application must use BackupRead and BackupWrite to copy all information pertaining to a file. However, these functions do not read or write file characteristics such as attributes, file creation time, and so on. Applications must use the file input and output functions, such as GetFileAttributes and SetFileAttributes, to query and set these values.


Creating A Backup Application

The most common use of the Win32 tape functions is to create a backup application. To perform any input or output on a tape, your application must first obtain a handle of the tape device. The following example shows how to use the CreateFile function to open a tape device.

HANDLE hTape;   /* handle to tape device */

hTape = CreateFile(

    "\\\\.\\TAPE0",     /* name of tape device to open */

    GENERIC_READ | GENERIC_WRITE, /* read-write access */

    0,                    /* not used                  */

    0,                    /* not used                  */

    OPEN_EXISTING,        /* required for tape devices */

    0,                    /* not used                  */

    NULL);                /* not used                  */

To back up a directory tree to a tape, your application must use the FindFirstFile and FindNextFile functions to traverse the directory tree. Each time a file is found, the application should get the file's attributes by using the GetFileAttributes function. If hard links, the application should determine the number of links and save the file's unique identifier in a table for future comparisons. The first time a file is found, the application should use CreateFile to open the file and the BackupRead function to begin the backup. Then, it can use the WriteFile function repeatedly to transfer all the information in the buffer filled by BackupRead to the tape. The second time a file is found (checked against the table of file identifiers when there are hard links), the application can simply write the general file information to the tape, followed by a stream whose identifier is BACKUP_LINK.

When restoring files from tape to disk, your application must use the CreateFile, BackupWrite, and ReadFile functions. For each file on the tape, the application should use CreateFile to create a new file on disk and BackupWrite to begin restoring the file. Then, it should use ReadFile repeatedly until all the information for the file has been read from the tape into the BackupWrite buffer. If one of the streams in the BackupWrite buffer has a BACKUP_LINK stream identifier, the application must establish a hard link. If the data to establish the link does not exist, BackupWrite fails. The application can use a preexisting catalog to locate and restore the original data, or it can notify the user that the file data to be restored is in a different location.


Backing Up and Restoring Posix File Links

A backup application can use the BackupWrite function to recreate Posix file links.

The BackupRead function does not return Posix file link data. A backup application must maintain the link information itself. The following pseudocode presents algorithms for backing up and restoring Posix file link data along with other file information:

PseudoCode Algorithm for Backing Posix File Links

1.  Initialize and empty a list of known links.

2.  While there are more files to back up

3.     Read the disk and get the next file.

4.     Open the file for read.

5.     Call GetFileInformationByHandle() to get the

          NumberOfLinks and the FileIndex.

6.     If the NumberOfLinks is greater than 1

7.        Search the list of know links looking for

             the same FileIndex.

8.           If a match is NOT found

9.              add the full path of the file and the

                   FileIndex to the list.

10.             Call BackupRead() to copy all data to

                   your backup media.

10.          Else

11.             Mark the data as a LINK on your backup media

11.             store the full path from the list

                   to your backup media.

12.          Endif

13.    Else

14.       Call BackupRead() to copy all data to your

             backup media.

15.    Endif

16. EndWhile

PseudoCode Algorithm for Restoring Posix File Links

1.  While there are more files to restore

2.     If the file is a LINK

3.        use the full path which was saved as data

             to open the file.

4.        Initialize a WIN32_STREAM_ID structure with

             dwStreamId equal to BACKUP_LINK.

5.        Initialize the dwStreamAttributes to 0.

6.        Initialize the dwStreamNameSize to 0.

7.        Initialize a buffer containing the full path

             of the file you are restoring in UNICODE.

8.        Initialize the dwStreamSizeHigh to 0.

9.        Initialize the dwStreamSizeLow to the size

             in bytes of the buffer     containing the full path.

10.       Call BackupWrite() with the WIN32_STREAM_ID

11.       Call BackupWrite() with the buffer containing

             the full path.

13.          Else

14.       Call BackupWrite() with the data stored on

             your backup media.

15.    Endif

16. EndWhile


Functions

Following are the functions used for tape backup.

BackupRead

BackupSeek

BackupWrite

CreateTapePartition

EraseTape

GetTapeParameters

GetTapePosition

GetTapeStatus

PrepareTape

SetTapeParameters

SetTapePosition

WriteTapemark


Time Overview

About Date and Time Functions

The Microsoft® Win32™ application programming interface (API) represents time values in two formats. File time is a 64-bit value representing the number of 100-nanosecond intervals that have elapsed since January 1, 1601. System time is the "real-time" clock format. System time uses a structure containing individual members for the date and time.

The Win32 API also provides functions to manipulate two other time formats: MS-DOS date and time and Windows time.

The following sections describe these time formats and the functions that use them.

The following topics discuss the Win32 Date and Time functions:

Terms

File Times

System Times

MS-DOS Times

Windows Time

Displaying File Creation Times in a Directory Listing

Changing a File Time to the Current Time

Setting the System Time

Functions


File Times

A Win32 file time uses two 32-bit values as a combined 64-bit value to represent the number of 100-nanosecond intervals that have elapsed since January 1, 1601. File times are recorded in Coordinated Universal Time (UTC) format. The FileTimeToLocalFileTime function converts a UTC-based file time to local time, and the LocalFileTimeToFileTime function converts a local file time to a UTC file time.

Windows records file creation time, last access time, and last write time for each file. (Note that this capability depends on the underlying file system. The file allocation table [FAT] file system does not record creation or access times, but both the high-performance file system [HPFS] and the new technology file system [NTFS] do.) These times are retrieved in a WIN32_FIND_DATA structure containing FILETIME structures for creation, write, and access times. Writing to a file changes the last write time; writing to or reading from the file (including running an executable file) changes the last access time.

The SetFileTime function can be used to explicitly set the file times. The GetFileTime, FindFirstFile, and FindNextFile functions return file times as FILETIME structures.

The file time format is a convenient way to represent time internally, but the number of 100-nanosecond intervals elapsed since 1601 is usually not useful to a user. The FileTimeToSystemTime function converts a FILETIME structure to a SYSTEMTIME structure containing individual members for the month, day, year, weekday, hour, minute, second, and millisecond.

The CompareFileTime function compares two 64-bit file times and returns a value indicating which file time is greater. If the file times are equal, CompareFileTime returns zero.

For more information about files and file systems, see Files, and File Systems.


System Times

A Win32 system time uses a SYSTEMTIME structure that contains separate member values for the year, month, day, hour, minute, second, and millisecond. This time format is used for the internal system time (the "real-time" clock). As with file times, the system time is kept in UTC format.

The internal system time is set automatically from the hardware clock when Windows starts running. The GetSystemTime function retrieves the system time, and the SetSystemTime function sets it.

Note:	To set the system time, a process must have system time privilege. For information about acquiring this privilege, see Security.

An application can also retrieve the current time in local time format (rather than UTC format) by using the GetLocalTime function. The SetLocalTime function sets the internal system time using a specified local time. The only difference between SetLocalTime and SetSystemTime (or between GetLocalTime and GetSystemTime) is the time format.

The conversion between UTC time and local time can be controlled by using the SetTimeZoneInformation function to set the current time-zone parameters. The GetTimeZoneInformation function retrieves the current time-zone settings.

The SystemTimeToFileTime function converts a SYSTEMTIME structure to a 64-bit FILETIME structure.

For compatibility with earlier versions of Windows, the Win32 API also supports the GetTickCount and GetCurrentTime functions. These functions return the time since Windows started running.


MS-DOS Times

MS-DOS records file dates and times as packed 16-bit values. An MS-DOS date has 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)

An MS-DOS time has 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)

The DosDateTimeToFileTime function converts MS-DOS date and time values into filetime values. The FileTimeToDosDateTime function converts filetime values into MS-DOS date and time values.


Windows Time

Windows keeps track of the number of milliseconds elapsed since it was started. This number is kept in a 32-bit value, so it can record 2^ 32 100-millisecond intervals before the 32-bit value overflows to zero. This is approximately 49.7 days.

The GetCurrentTime and GetTickCount functions both return the Windows time. These functions are provided primarily for compatibility with earlier versions of Windows.


Displaying File Creation Times in a Directory Listing

The following example displays a detailed directory of files in the current directory.

void main(void)

{

    HANDLE hSearch;

    WIN32_FIND_DATA ffd;

    /* Find the first file or indicate there are none. */

    hSearch = FindFirstFile("*.*", &ffd);

    if (hSearch == INVALID_HANDLE_VALUE)

        puts("no files");

    /* Display the header and process files until done. */

    else {

        printf("\nfile name         created");

        printf("           last written      size\n\n");

        PrintData(&ffd);

        while (FindNextFile(hSearch, &ffd))

            PrintData(&ffd);

    }

}

void PrintData(PWIN32_FIND_DATA pffd)

{

    FILETIME ft;

    SYSTEMTIME stCreate, stWrite;

    if (pffd->dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY)

        return;                         /* don't display directories */

    /* Convert creation and write times from UTC time to local time. */

    /* Convert creation and write times to system format. */

    FileTimeToLocalFileTime(&pffd->ftCreationTime, &ft);

    FileTimeToSystemTime(&ft, &stCreate);

    FileTimeToLocalFileTime(&pffd->ftLastWriteTime, &ft);

    FileTimeToSystemTime(&ft, &stWrite);

    /* Display the creation and write times. */

    printf("%-12s  %02d/%02d/%d  %02d:%02d",

            pffd->cFileName,

            stCreate.wDay, stCreate.wMonth, stCreate.wYear,

            stCreate.wHour, stCreate.wMinute);

    printf("   %02d/%02d/%d  %02d:%02d   %lu\n",

            stWrite.wDay, stWrite.wMonth, stWrite.wYear,

            stWrite.wHour, stWrite.wMinute, pffd->nFileSizeLow);

}


Changing a File Time to the Current Time

The following example sets the creation time for a file to the current system time.

HANDLE hf;

FILETIME ft;

SYSTEMTIME st;

/* Open ftime.c for write access. */

hf = CreateFile("\\ftime.c", GENERIC_WRITE, 0,

        (LPSECURITY_ATTRIBUTES)NULL, OPEN_EXISTING,

        FILE_ATTRIBUTE_NORMAL, (HANDLE)NULL);

if (hf == INVALID_HANDLE_VALUE) {

    puts("Could not open ftime.c.");

    ExitProcess(1);

}

GetSystemTime(&st);             /* get current time            */

SystemTimeToFileTime(&st, &ft); /* convert to file time format */

SetFileTime(hf, &ft,            /* set creation time for file  */

    (LPFILETIME)NULL, (LPFILETIME)NULL);


Setting the System Time

The following example enables the user to set the system time.

static char *aszDay[] =  { "Sunday", "Monday", "Tuesday",

        "Wednesday", "Thursday", "Friday", "Saturday" };

void _cdecl main(void)

{

    HANDLE hToken;

    SYSTEMTIME st;

    char szTime[25], *pc;

    TOKEN_PRIVILEGES tkp;

    GetSystemTime(&st);  /* get the current time          */

    ShowTime(&st);       /* display the current time      */

    for (;;) {           /* get the new time in hh:mm format */

        printf("Enter new time: ");

        gets(szTime);

        if ((pc = strchr(szTime, ':')) != NULL) {

            *pc = '\0';

            st.wHour = (WORD)atoi(szTime);

            st.wMinute = (WORD)atoi(pc + 1);

            break;

        }

        else {

            puts("Time must be in hh:mm format:");

        }

    }

    /* Get the current process token handle */

    /* so we can get set-time privilege. */

    if (!OpenProcessToken(GetCurrentProcess(),

            TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, &hToken))

        error("OpenProcessToken");

    /* Get the LUID for system-time privilege. */

    LookupPrivilegeValue(NULL, "SE_SYSTEMTIME_NAME",

            &tkp.Privileges[0].Luid);

    tkp.PrivilegeCount = 1;  /* one privilege to set      */

    tkp.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;

    /* Get set-time privilege for this process. */

    AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,

        (PTOKEN_PRIVILEGES) NULL, 0);

    /* Cannot test return value of AdjustTokenPrivileges. */

    if (GetLastError() != ERROR_SUCCESS)

        error("AdjustTokenPrivileges enable");

    if (!SetSystemTime(&st))       /* set the system time */

        error("SetSystemTime");

    ShowTime(&st);

    /* Now disable set-time privilege. */

    tkp.Privileges[0].Attributes = 0;

    AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,

        (PTOKEN_PRIVILEGES) NULL, 0);

    if (GetLastError() != ERROR_SUCCESS)

        error("AdjustTokenPrivileges disable");

}

void error(LPSTR lpszFunction)

{

    DWORD dw = GetLastError();

    printf("%s failed: GetLastError returned %u\n",

        lpszFunction, dw);

    ExitProcess(dw);

}

void ShowTime(PSYSTEMTIME pst)

{

    printf("It is now %02u:%02u:%02u on %s, %02u/%02u/%4u.\n",

        pst->wHour, pst->wMinute, pst->wSecond,

        aszDay[pst->wDayOfWeek], pst->wMonth,

        pst->wDay, pst->wYear);

}


Functions

Following are the functions used with date and time formats.

CompareFileTime

DosDateTimeToFileTime

FileTimeToDosDateTime

FileTimeToLocalFileTime

FileTimeToSystemTime

GetCurrentTime

GetFileTime

GetLocalTime

GetSystemTime

GetTickCount

GetTimeZoneInformation

LocalFileTimeToFileTime

SetFileTime

SetLocalTime

SetSystemTime

SetTimeZoneInformation

SystemTimeToFileTime


Atoms Overview

About Atom Tables

In the Microsoft® Win32™ application programming interface (API) an atom table is a system-defined table that stores strings and corresponding identifiers. An application places a string in an atom table and receives a 16-bit integer, called an atom, that can be used to access the string. A string that has been placed in an atom table is called an atom name.

Dynamic data exchange (DDE) applications use an atom table to share item-name and topic-name strings with other applications. Instead of passing actual strings, a DDE application passes atoms to its partner application. The partner uses the atoms to obtain the strings from the atom table.

The following topics discuss atoms:

Terms

Global Atom Table

Local Atom Tables

Atom Types

Atom Creation and Usage Count

Atom-Table Queries

Atom String Formats

Using Atoms

Functions


Global Atom Table

The Windows global atom table, which can contain up to 37 entries, is available to all applications. When an application places a string in the global atom table, the system generates an atom that is unique throughout the system. Any application that has the atom can obtain the string it identifies by querying the global atom table.

An application that defines a private clipboard-data format or DDE-data format for sharing data with other applications should place the format name in the global atom table. This technique prevents conflicts with the names of formats defined by the system or by other applications, and makes the identifiers (atoms) for the messages or formats available to the other applications.


Local Atom Tables

An application can use a local atom table to efficiently manage a large number of strings used only within the application. These strings, and the associated atoms, are available only to the application that created the table.

An application requiring the same string in a number of structures can reduce memory usage by using a local atom table. Rather than copying the string into each structure, the application can place the string in the atom table and include the resulting atom in the structures. In this way, a string appears only once in memory but can be used many times in the application.

Applications can also use local atom tables to save time when searching for a particular string. To perform a search, an application need only place the search string in the atom table and compare the resulting atom with the atoms in the relevant structures. Comparing atoms is typically faster than comparing strings.

By default, a local atom table can contain up to 37 entries. However, unlike the size of a global atom table, the size of a local atom table can be changed. An application uses the InitAtomTable function to accomplish this task. If the application calls InitAtomTable, however, it must do so before calling any other atom-management function.


Atom Types

Applications can use two types of atoms: string and integer. The following sections describe these types.

String Atoms

Applications pass null-terminated strings to atom tables and receive string atoms (16-bit integers) in return. String atoms have the following properties:

The values of string atoms are in the range 0xC000 through 0xFFFF.

Case is not significant in searches for an atom name in an atom table. Also, the entire string must match in a search operation; no substring matching is performed.

A reference count is associated with each atom name. The count is incremented each time the atom name is added to the table and decremented each time the atom name is deleted from it. This prevents different users of the same string atom from destroying each other's atom names. When the reference count for an atom name equals zero, the system removes the atom and the atom name from the table.

Integer Atoms

Integer atoms differ from string atoms in the following ways:

The values of integer atoms are in the range 0x0001 through 0xBFFF. The values of integer atoms and string atoms do not overlap, so both types of atoms can be used in the same block of code.

The string representation of an integer atom is #dddd, where the values represented by dddd are decimal digits. Leading zeros are ignored.

There is no reference count or storage overhead associated with an integer atom.

Several Windows functions accept either string or integer atoms as parameters. When passing an integer atom to these functions, an application must use the MAKEINTATOM macro to create the atom.


Atom Creation and Reference Count

Atom Creation and Usage Count

An application creates a local atom by calling the AddAtom function; it creates a global atom by calling the GlobalAddAtom function. Both functions require a pointer to a string. The system searches the appropriate atom table for the string and returns the corresponding atom to the application. In the case of a string atom, if the string already resides in the atom table, the system increments the reference count for the string during this process.

Repeated calls to add the same atom name return the same atom. If the atom name does not exist in the table when AddAtom is called, the atom name is added to the table and a new atom is returned. If it is a string atom, its reference count is also set to one.

An application should call the DeleteAtom function when it no longer needs to use a local atom; it should call the GlobalDeleteAtom function when it no longer needs a global atom. In the case of a string atom, either of these functions reduces the reference count of the corresponding atom by one. When the reference count reaches zero, the system deletes the atom name from the table.

The atom name of a string atom remains in the global atom table as long as its reference count is greater than zero, even after the application that placed it in the table terminates. A local atom table is destroyed when the associated application terminates, regardless of the reference counts of the atoms in the table.


Atom-Table Queries

An application can determine whether a particular string is already in an atom table by using the FindAtom or GlobalFindAtom function. These functions search an atom table for the specified string and, if the string is there, return the corresponding atom.

An application can use the GetAtomName or GlobalGetAtomName function to retrieve an atom-name string from an atom table, provided the application has the atom corresponding to the string sought. Both functions copy the atom-name string of the specified atom to a buffer and return the length of the string that was copied. GetAtomName retrieves an atom-name string from a local atom table, and GlobalGetAtomName retrieves an atom-name string from the global atom table.


Atom String Formats

The AddAtom, GlobalAddAtom, FindAtom, and GlobalFindAtom functions take a pointer to a null-terminated string. An application can specify this pointer in one of the following ways.

Format	Description

#dddd	An integer specified as a decimal string. Used to create or find an integer atom.

string atom name	A string atom name. Used to add a string atom name to an atom table and receive an atom in return.


Using Atoms

The most typical use for atoms is in dynamic data exchange (DDE) applications. In the DDE protocol, applications use global atoms to identify the applications exchanging data, the nature of the data being exchanged, and the actual data items being exchanged.


Functions

Following are the functions associated with atoms.

AddAtom

DeleteAtom

FindAtom

GetAtomName

GlobalAddAtom

GlobalDeleteAtom

GlobalFindAtom

GlobalGetAtomName

InitAtomTable

GetAtomHandle (Obsolete)


Debugging Overview

About Debugging Support

A debugger is an application that enables a developer to observe and correct programming errors. Microsoft® Windows NT™ supports several functions that can be used to create a basic, event-driven debugger. "Event-driven" means that the debugger is notified every time certain events occur in the process being debugged. Notification enables the debugger to take appropriate action in response to the events.

The first section of this topic describes the debugging-specific features of certain standard Windows NT functions--specifically, process, thread, and exception-handling functions.

The second section of this topic describes the Windows NT debugging functions. These functions enable an application to wait for debugging events, cause breakpoint exceptions, transfer execution control to the debugger, and so on.

The following topics describe Windows NT debugging support:

Terms

Support from Process, Thread, and Exception Functions

Debugging Functions

Using Debugging Support

Functions


Support from Process, Thread, and Exception Functions

Some functions essential to debugging are actually part of the process, thread, or exception-handling architectures. This section describes how to start a process that is going to be debugged and how to examine and manipulate the context and execution of a thread. It also describes how a debugger should handle exceptions.

Process Functions

The CreateProcess function enables a debugger to start a process and debug it. The fdwCreate parameter of CreateProcess is used to specify the type of debugging operation. If the DEBUG_PROCESS flag is specified for the parameter, a debugger debugs the new process and all of the process's descendants, provided that the descendants are created without the DEBUG_PROCESS flag set.

If the DEBUG_PROCESS and DEBUG_ONLY_THIS_PROCESS flags are specified for fdwCreate, a debugger debugs the new process but none of its descendants.

One debugger can debug another by creating a process with the DEBUG_PROCESS flag set. The new process (the debugger being debugged) must then create a process with the DEBUG_PROCESS flag set.

The OpenProcess function enables a debugger to obtain the identifier of an existing process. (The DebugActiveProcess function uses this identifier to attach the debugger to the process.) Typically, debuggers open a process with the PROCESS_VM_READ and PROCESS_VM_WRITE flags set. Using these flags enables the debugger to read from and write to the virtual memory of the process by using the ReadProcessMemory and WriteProcessMemory functions. For more information about processes, see Processes and Threads.

Thread Functions

The CreateThread function creates a new thread for a process. Debuggers typically need to examine or change the contents of a thread's registers. To accomplish this, a debugger must obtain a handle of the thread by using the DuplicateHandle function and specifying the appropriate access to the thread (THREAD_GET_CONTEXT, THREAD_SET_CONTEXT, or both).

A process with appropriate access to a thread can examine the thread's registers by using the GetThreadContext function and set the contents of the thread's registers by using the SetThreadContext function.

A process can also obtain THREAD_SUSPEND_RESUME access to a thread. This enables a debugger to control a thread's execution with the SuspendThread and ResumeThread functions. For more information about threads, see Processes and Threads

Exception Handling

When an exception occurs in a process that is being debugged, the kernel notifies the debugger by passing the exception to it. This is known as first-chance notification. The kernel then suspends all threads in the process being debugged.

If the debugger does not handle the exception, the kernel attempts to locate an appropriate exception handler. If the kernel cannot locate an appropriate one, the kernel again notifies the debugger that an exception has occurred. This is known as last-chance notification. If the debugger does not handle the exception after the last-chance notification, the kernel terminates the process being debugged.

For more information about exception handling, see Structured Exception Handling.


Debugging Functions

Although most of the Windows NT debugging functions are used to create a debugger, several functions are designed for use in the process being debugged.

To start a process and debug it, a debugger must use CreateProcess, as described in the previous section.

To debug a process that is already executing, the debugger should use DebugActiveProcess with the process identifier retrieved by OpenProcess. DebugActiveProcess attaches the debugger to the active process. In this case, only the active process can be debugged; its descendants cannot. The debugger must have appropriate access to the executing process to use DebugActiveProcess. For more information about access rights, see Security

After the debugger has either created or attached itself to the process it intends to debug, the kernel notifies the debugger of all debugging events that occur in the process, and, if specified, in the process's descendants. For more information about debugging events, see Debugging Events.

The debugger uses the WaitForDebugEvent function at the beginning of its main loop. This function blocks the debugger until a debugging event occurs. When the debugging event occurs, the kernel suspends all threads in the process being debugged and notifies the debugger of the event. The debugger can interact with the user, or manipulate the state of the process being debugged, by using the FlushInstructionCache, GetThreadContext, GetThreadSelectorEntry, ReadProcessMemory, SetThreadContext, and WriteProcessMemory functions.

GetThreadSelectorEntry returns the descriptor table entry for a specified selector and thread. Debuggers use the descriptor table entry to convert a segment-relative address to a linear virtual address. The ReadProcessMemory and WriteProcessMemory functions require linear virtual addresses.

Debuggers frequently read the memory of the process being debugged and write the memory that contains instructions to the instruction cache. After the instructions are written, the debugger calls FlushInstructionCache to execute the cached instructions.

The debugger uses the ContinueDebugEvent function at the end of its main loop. This function allows the process being debugged to continue executing.

Communicating with the Debugger

The OutputDebugString function sends a string from the process being debugged to the debugger by generating an OUTPUT_DEBUG_STRING_EVENT debugging event.

The DebugBreak function causes a breakpoint exception in the current process. A breakpoint is a location in a program where execution is stopped to allow the developer to examine the program's code, variables, and register values, and, as necessary, to make changes, continue execution, or terminate execution.

The FatalExit function terminates the current process and gives execution control to the debugger, but unlike DebugBreak, does not generate an exception. This function should only be used as a last resort, because it does not always free the process's memory or close its files.

Debugging Events

A debugging event is an incident in the process being debugged that causes the kernel to notify the debugger. Debugging events include creating a process, creating a thread, loading a dynamic-link library (DLL), unloading a DLL, sending an output string, and generating an exception.

If a debugging event occurs while a debugger is waiting for one, the kernel fills the DEBUG_EVENT structure specified by WaitForDebugEvent with information describing the event.

When the kernel notifies the debugger of a debugging event, it also suspends all threads in the affected process. The threads do not resume execution until the debugger continues the debugging event by using ContinueDebugEvent. The following debugging events may occur while a process is being debugged.

Debugging event	Description

CREATE_PROCESS_DEBUG_EVENT

Generated whenever a new process is created in a process being debugged or whenever the debugger begins debugging an already active process. The kernel generates this debugging event before the process begins to execute in user mode and before the kernel generates any other debugging events for the new process.

The DEBUG_EVENT structure contains a CREATE_PROCESS_DEBUG_INFO structure. This structure includes a handle of the new process, a handle of the process's image file, a handle of the process's initial thread, and other information that describes the new process.

The handle of the process has PROCESS_VM_READ and PROCESS_VM_WRITE access. If a debugger has these types of access to a thread, it can read and write to the process's memory by using the ReadProcessMemory and WriteProcessMemory functions.

The handle of the process's image file has GENERIC_READ access and is opened for read-sharing.

The handle of the process's initial thread has THREAD_GET_CONTEXT, THREAD_SET_CONTEXT, and THREAD_SUSPEND_RESUME access to the thread. If a debugger has these types of access to a thread, it can read from and write the thread's registers by using the GetThreadContext and SetThreadContext functions and can suspend and resume the thread by using the SuspendThread and ResumeThread functions.

CREATE_THREAD_DEBUG_EVENT

Generated whenever a new thread is created in a process being debugged or whenever the debugger begins debugging an already active process. This debugging event is generated before the new thread begins to execute in user mode.

The DEBUG_EVENT structure contains a CREATE_THREAD_DEBUG_INFO structure. This structure includes a handle of the new thread and the thread's starting address. The handle has THREAD_GET_CONTEXT, THREAD_SET_CONTEXT, and THREAD_SUSPEND_RESUME access to the thread. If a debugger has these types of access to a thread, it can read from and write to the thread's registers by using the GetThreadContext and SetThreadContext functions and can suspend and resume the thread by using the SuspendThread and ResumeThread functions.

EXCEPTION_DEBUG_EVENT

Generated whenever an exception occurs in the process being debugged. Possible exceptions include attempting to access inaccessible memory, executing breakpoint instructions, attempting to divide by zero, or any other exception noted in Structured Exception Handling.

The DEBUG_EVENT structure contains an EXCEPTION_DEBUG_INFO structure. This structure describes the exception that caused the debugging event.

In addition to the standard exception conditions, an additional exception code can occur during console process debugging. The kernel generates a DBG_CONTROL_C exception code 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. An application should never use an exception handler to deal with it. It is raised only for the benefit of the debugger, and is only raised when a debugger is attached to the console process.

If a process is not being debugged, or if the debugger passes on the DBG_CONTROL_C exception unhandled (via the gn command), the application's list of handler functions is searched, as documented for SetConsoleCtrlHandler.

If the debugger handles the DBG_CONTROL_C exception (via the gh command), an application will not notice the Ctrl-C, with one exception: alertable waits terminate. This is most noticeable in code like this:

        while ((inputChar = getchar()) != EOF) ...

        while (gets(inputString)) ...

Thus, the debugger cannot be used to stop the read wait in such code from terminating.

EXIT_PROCESS_DEBUG_EVENT

Generated whenever the last thread in a process being debugged exits. This debugging event occurs immediately after the kernel unloads the process's dynamic-link libraries (DLLs) and updates the process's exit code.

The DEBUG_EVENT structure contains an EXIT_PROCESS_DEBUG_INFO structure that specifies the exit code.

The debugger deallocates any internal structures associated with the process on receipt of this debugging event. The kernel closes the debugger's handle of the exiting process and all of the process's threads.

EXIT_THREAD_DEBUG_EVENT

Generated whenever a thread that is part of a process being debugged exits. The kernel generates this debugging event immediately after it updates the thread's exit code.

The DEBUG_EVENT structure contains an EXIT_THREAD_DEBUG_INFO structure that specifies the exit code.

The debugger deallocates any internal structures associated with the thread on receipt of this debugging event. The system closes the debugger's handle of the exiting thread.

This debugging event does not occur if the exiting thread is the last thread of a process. In this case, the EXIT_PROCESS_DEBUG_EVENT debugging event occurs instead.

LOAD_DLL_DEBUG_EVENT

Generated whenever a process being debugged loads a DLL. This debugging event occurs when the system loader resolves links to a DLL or when the debugged process uses the LoadLibrary function. This debugging event only occurs the first time the kernel attaches a DLL to the virtual address space of a process.

The DEBUG_EVENT structure contains a LOAD_DLL_DEBUG_INFO structure. This structure includes a handle of the newly loaded DLL, the base address of the DLL, and other information that describes the DLL.

Typically, a debugger loads a symbol table associated with the DLL on receipt of this debugging event.

OUTPUT_DEBUG_STRING_EVENT

Generated when a process being debugged uses the OutputDebugString function.

The DEBUG_EVENT structure contains an OUTPUT_DEBUG_STRING_INFO structure. This structure specifies the address, length, and format of the debugging string.

UNLOAD_DLL_DEBUG_EVENT

Generated whenever a process being debugged unloads a DLL by using the FreeLibrary function. This debugging event only occurs the last time a DLL is unloaded from a process's address space (that is, when the DLL's usage count is zero).

The DEBUG_EVENT structure contains an UNLOAD_DLL_DEBUG_INFO structure. This structure specifies the base address of the DLL in the address space of the process that unloads the DLL.

Typically, a debugger unloads a symbol table associated with the DLL on receipt of this debugging event.

When a process exits, the kernel automatically unloads the process's DLLs, but does not generate an UNLOAD_DLL_DEBUG_EVENT debugging event.


Using Debugging Support

The following example uses the WaitForDebugEvent and ContinueDebugEvent functions to illustrate how a simple debugger might be organized.

DEBUG_EVENT DebugEv;                   /* debugging event info. */

DWORD dwContinueStatus = DBG_CONTINUE; /* exception continuation */

for(;;) {

 /*

  * Wait for a debugging event to occur. The second parameter

  * indicates that the function does not return until

  * a debugging event occurs.

  */

WaitForDebugEvent(&DebugEv, INFINITE);

  /* Process the debugging event code. */

  switch (DebugEv.dwDebugEventCode) {

    case EXCEPTION_DEBUG_EVENT:

      /*

       * Process the exception code. When handling

       * exceptions, remember to set the continuation

       * status parameter (dwContinueStatus). This value

       * is used by the ContinueDebugEvent function.

       */

      switch (DebugEv.u.Exception.ExceptionRecord.ExceptionCode) {

          case EXCEPTION_ACCESS_VIOLATION:

                 /*

                  * First chance: Pass this on to the kernel.

                  * Last chance: Display an appropriate error.

                  */

          case EXCEPTION_BREAKPOINT:

                 /*

                  * First chance: Display the current

                  * instruction and register values.

                  */

          case EXCEPTION_DATATYPE_MISALIGNMENT:

                 /*

                  * First chance: Pass this on to the kernel.

                  * Last chance: Display an appropriate error.

                  */

          case EXCEPTION_SINGLE_STEP:

                 /*

                  * First chance: Update the display of the

                  * current instruction and register values.

                  */

          case DBG_CONTROL_C:

                 /*

                  * First chance: Pass this on to the kernel.

                  * Last chance: Display an appropriate error.

                  */

          /* Handle other exceptions. */

      }

    case CREATE_THREAD_DEBUG_EVENT:

           /*

            * As needed, examine or change the thread's registers

            * with the GetThreadContext and SetThreadContext functions;

            * suspend and resume thread execution with the

            * SuspendThread and ResumeThread functions.

            */

    case CREATE_PROCESS_DEBUG_EVENT:

           /*

            * As needed, examine or change the registers of the process's

            * initial thread with the GetThreadContext and SetThreadContext

            * functions; read from and write to the process's virtual memory

            * with the ReadProcessMemory and WriteProcessMemory functions;

            * and suspend and resume thread execution with the SuspendThread

            * and ResumeThread functions.

            */

    case EXIT_THREAD_DEBUG_EVENT:

           /* Display the thread's exit code. */

    case EXIT_PROCESS_DEBUG_EVENT:

           /* Display the process's exit code. */

    case LOAD_DLL_DEBUG_EVENT:

           /*

            * Read the debugging information included

            * in the newly loaded DLL.

            */

    case UNLOAD_DLL_DEBUG_EVENT:

           /*

            * Display a message that the DLL has

            * been unloaded.

            */

    case OUTPUT_DEBUG_STRING_EVENT:

           /* Display the output debugging string. */

  }

/* Resume executing the thread that reported the debugging event. */

ContinueDebugEvent(DebugEv.dwProcessId,

    DebugEv.dwThreadId, dwContinueStatus);

}


Functions

Following are the functions that support debugging:

ContinueDebugEvent

DebugActiveProcess

DebugBreak

FatalAppExit

FatalExit

FlushInstructionCache

GetThreadContext

GetThreadSelectorEntry

OutputDebugString

ReadProcessMemory

SetDebugErrorLevel

SetThreadContext

WaitForDebugEvent

WriteProcessMemory


Errors Overview

About Errors

Well-written applications include code that allows them to recover gracefully from unexpected errors. When an error occurs, the application may need to request user intervention, or it may be able to recover without help. In extreme cases, the application may log the user off or shut down the system.

Microsoft® Windows NT™ includes a special error-handling mechanism for exceptions, such as divide-by-zero errors.

The following topics discuss errors:

Terms

Notifying the User

Logging Off or Shutting Down

Last-Error Code

Error Message Boxes

Notifying the User

Logging Off

Shutting Down

Retrieving the Last Error Code

Functions


Notifying the User

To notify the user that some kind of error has occurred, many applications simply produce a sound by using the Beep or MessageBeep function or flash the window by using the FlashWindow function. An application can also use these functions to call attention to an error and then display a message box or an error message containing details about the error.


Logging Off or Shutting Down

An application can use the ExitWindows function to log the current user off. The ExitWindowsEx function can also do any of the following:

Shut down the system

Shut down the system and restart it

Log off and force all running applications to terminate

Logging off stops all processes associated with the security context of the process that called the exit function, logs the user off the system, and displays the Logon dialog box.

Shutting down brings the system to a condition in which it is safe to turn the computer off. All file-system buffers are flushed to the disk, and a message box is displayed informing the user that the computer can be turned off. If the reboot option is specified, the computer restarts.

The calling process must have the SE_SHUTDOWN_NAME privilege to shut down, or to shut down and restart. For an example that enables this privilege and shuts down the system, see Shutting Down.


Last-Error Code

When an error occurs, most functions in the Win32 application programming interface (API) return an error code, usually FALSE, NULL, 0xFFFFFFFF, or -1. Most functions in the Win32 application programming interface (API) also set an internal error code called the last-error code. When a function succeeds, the last-error code is not reset. The error code is maintained separately for each running thread; an error in one thread does not overwrite the last-error code in another thread. An application can retrieve the last-error code by using the GetLastError function; the error code may tell more about what actually occurred to make the function fail.

The SetLastError function sets the error code for the current thread. The SetLastErrorEx function also allows the caller to set an error type indicating the severity of the error. These functions are intended primarily for dynamic-link libraries (DLLs), so that they can emulate the behavior of the Win32 API.

The Win32 API defines a set of error codes that can be set as last-error codes or returned by these functions. A list of these error code appears in Error Codes.

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. Developers who define an error code for an application should set this bit to indicate that the error code has been defined by an application and to ensure that the error code does not conflict with any system-defined error codes.


Error Message Boxes

Some errors, such as a drive-not-ready error (when the door of the floppy disk drive is open), cause Windows NT to display a message box informing the user that an error has occurred. Applications that handle these errors without user intervention can use the SetErrorMode function to suppress error message boxes.


Notifying the User

The following example flashes a window, plays the system exclamation sound, and displays a message box.

FlashWindow(hwnd, TRUE); /* invert the title bar   */

Sleep(500);              /* wait a bit             */

FlashWindow(hwnd, TRUE); /* invert again           */

/* Play the system exclamation sound. */

MessageBeep(MB_ICONEXCLAMATION);


Logging Off

The ExitWindows function logs the current user off. All applications must agree to terminate before the user logs off. If any application returns FALSE when it processes the WM_QUERYENDSESSION message, the user is not logged off. If your application handles the WM_QUERYENDSESSION message, you can allow the user to cancel the log-off operation, even if another application or Windows originated the end-session request.

The following example logs off the current user, unless the user selects the No button in the message box displayed when the application receives the WM_QUERYENDSESSION message.

            ExitWindows(0, 0); /* log the current user off    */

case WM_QUERYENDSESSION: /* in application's MainWndProc */

{

    int i  = MessageBox(NULL, "Shutdown?",

       "Received WM_QUERYENDSESSION", MB_YESNO);

    /*

     * Return TRUE to allow shutdown, FALSE to stop.

     */

    return i == IDYES;

    break;

}


Shutting Down

The ExitWindowsEx function can be used to shut down the system. Shutting down flushes file buffers to disk and brings the system to a condition in which it is safe to turn the computer off. The calling process must have the SE_SHUTDOWN_NAME privilege to shut down the system.

The following example enables the SE_SHUTDOWN_NAME privilege and then shuts down the system.

HANDLE hToken;

TOKEN_PRIVILEGES tkp;

/* Get a token for this process. */

if (!OpenProcessToken(GetCurrentProcess(),

        TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, &hToken))

    error("OpenProcessToken");

/* Get the LUID for shutdown privilege. */

LookupPrivilegeValue(NULL, TEXT("SE_SHUTDOWN_NAME"),

        &tkp.Privileges[0].Luid);

tkp.PrivilegeCount = 1;  /* one privilege to set    */

tkp.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;

/* Get shutdown privilege for this process. */

AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,

        (PTOKEN_PRIVILEGES)NULL, 0);

/* Cannot test the return value of AdjustTokenPrivileges. */

if (GetLastError() != ERROR_SUCCESS)

    error("AdjustTokenPrivileges");

/* Shut down the system and force all applications to close. */

if (!ExitWindowsEx(EWX_SHUTDOWN | EWX_FORCE, 0))

    error("ExitWindowsEx");


Retrieving the Last-Error Code

When a function in the Win32 API fails, it sets the last-error code. If your application needs more details about an error, it can retrieve the last-error code.

The following example shows an error-handling function used by the other examples in this topic.

void error(LPSTR lpszFunction)

{

    CHAR szBuf[80];

    DWORD dw = GetLastError();

    sprintf(szBuf, "%s failed: GetLastError returned %u\n",

        lpszFunction, dw);

    MessageBox(NULL, szBuf, "ERROR", MB_OK);

    ExitProcess(dw);

}


Functions

Following are the functions used with errors.

Beep

ExitWindows

ExitWindowsEx

FlashWindow

GetLastError

MessageBeep

PlaySound

SetErrorMode

SetLastError

SetLastErrorEx


Structured Exception Handling Overview

About Structured Exception Handling

An exception is an event that occurs during the execution of a program, and that requires the execution of software outside the normal flow of control. Hardware exceptions can result from the execution of certain instruction sequences, such as division by zero or an attempt to access an invalid memory address. A software routine can also initiate an exception explicitly.

The Microsoft® Win32™ application programming interface (API) supports structured exception handling, a mechanism for handling hardware- and software-generated exceptions. Structured exception handling gives programmers complete control over the handling of exceptions, provides support for debuggers, and is usable across all programming languages and machines.

The Win32 API also supports termination handling, which enables programmers to ensure that whenever a guarded body of code is executed, a specified block of termination code is also executed. The termination code is executed regardless of how the flow of control leaves the guarded body. For example, a termination handler can guarantee that clean-up tasks are performed even if an exception or some other error occurs while the guarded body of code is being executed.

Structured exception and termination handling is an integral part of the Win32 system and it enables a very robust implementation of the system software. It is envisioned that application developers also will use these mechanisms to create consistently robust and reliable applications.

Structured exception handling is made available to application developers primarily through compiler support. For example, the Microsoft compilers provided with the Win32 development kit support the try keyword that identifies a guarded body of code, and the except and finally keywords that identify an exception handler and a termination handler, respectively. Although this topic uses examples from the support available in Microsoft compilers, it is possible for other compiler vendors to provide this support as well.

The following topics discuss Win32 structured exception handling:

Terms

Exception Handling

Termination Handling

Exception Handling Syntax

Using an Exception Handler

Using a Termination Handler

Functions


Exception Handling

Exceptions can be initiated by hardware or software, and can occur in kernel-mode as well as user-mode code. Win32 structured exception handling provides a single mechanism for the handling of kernel-mode and user-mode exceptions, both hardware- and software-generated.

The execution of certain instruction sequences can result in exceptions that are initiated by hardware. For example, an access violation is generated by the hardware when a process attempts to read from or write to a virtual address to which it does not have the appropriate access.

Events that require exception handling may also occur during execution of a software routine (for example, when an invalid parameter value is specified). When this happens, a thread can initiate an exception explicitly by calling the RaiseException function. This function enables the calling thread to specify information that describes the exception.

Exception Dispatching

When a hardware or software exception occurs, the processor stops execution at the point at which the exception occurred and transfers control to the system. First, the system saves both the machine state of the current thread and information that describes the exception. The system then attempts to find an exception handler to handle the exception.

The machine state of the thread in which the exception occurred is saved in a CONTEXT structure. This information (called the context record) enables the system to continue execution at the point of the exception if the exception is successfully handled. The description of the exception (called the exception record) is saved in an EXCEPTION_RECORD structure. Because it stores the machine-dependent information of the context record separately from the machine-independent information of the exception record, the exception-handling mechanism is portable to different platforms. The information in both the context and exception records is available by means of the GetExceptionInformation function, and can be made available to any exception handlers that are executed as a result of the exception. The exception record includes the following information:

An exception code that identifies the type of exception.

Flags indicating whether the exception is continuable. Any attempt to continue execution after a noncontinuable exception generates another exception.

A pointer to another exception record. This facilitates creation of a linked list of exceptions if nested exceptions occur.

The address at which the exception occurred.

An array of 32-bit arguments that provide additional information about the exception.

When an exception occurs in user-mode code, the system goes 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.

When an exception occurs in kernel-mode code, the system searches the stack frames of the kernel stack in an attempt to locate an exception handler. If a handler cannot be located or no handler handles the exception, the system is shut down as if the ExitWindows function had been called.

Debugger Support

The system's handling of user-mode exceptions provides support for sophisticated debuggers. If the process in which an exception occurs is being debugged, the system generates a debug event. If the debugger is using the WaitForDebugEvent function, the debug event causes that function to return with a pointer to a DEBUG_EVENT structure. This structure contains the process and thread identifiers that the debugger can use to access the thread's context record. The structure also contains an EXCEPTION_DEBUG_INFO structure that includes a copy of the exception record.

The system's search for an exception handler includes two attempts to notify a process's debugger. The first notification attempt provides the debugger with an opportunity to handle breakpoint or single-step exceptions. The user can then issue debugger commands to manipulate the process's environment before any exception handlers are executed. The second attempt to notify the debugger occurs only if the system is unable to find a frame-based exception handler that handles the exception.

At each notification attempt, the debugger uses the ContinueDebugEvent function to return control to the system. Before returning control the debugger can handle the exception and modify the thread state as appropriate, or it can choose not to handle the exception. Using ContinueDebugEvent the debugger can indicate that it has handled the exception, in which case the machine state is restored and thread execution is continued at the point at which the exception occurred. The debugger can also indicate that it did not handle the exception, which causes the system to continue its search for an exception handler.

Frame-based Exception Handling

A frame-based exception handler is a mechanism by which a developer deals with the possibility that an exception may occur in a certain sequence of code. A frame-based exception handler consists of the following:

A guarded body of code

A filter expression

An exception-handler block

Frame-based exception handlers are declared in language-specific syntax. For example, in the Microsoft® C Optimizing Compiler, they are implemented by the try-except statement. For more information about the Microsoft C exception-handling syntax, see Syntax.

The guarded body of code is a set of one or more statements for which the filter expression and the exception-handler block provide exception-handling protection. The guarded body can be a block of code, a set of nested blocks, or an entire procedure or function. In Microsoft C, a guarded body is enclosed by braces ({}) following the try keyword.

The filter expression of a frame-based exception handler is an expression that is evaluated by the system when an exception occurs within the guarded body. This evaluation results in one of the following actions by the system:

The system stops its search for an exception handler, restores the machine state, and continues thread execution at the point at which the exception occurred.

The system continues its search for an exception handler.

The system transfers control to the exception handler, and thread execution continues sequentially in the stack frame in which the exception handler is found. If the handler is not in the stack frame in which the exception occurred, the system unwinds the stack, leaving the current stack frame and any other stack frames until it is back to the exception handler's stack frame. Before an exception handler is executed, termination handlers are executed for any guarded bodies of code that terminated as a result of the transfer of control to the exception handler. For more information about termination handlers, refer to Termination Handling.

The filter expression can be a simple expression, or it can invoke a filter function that attempts to handle the exception. You can call the GetExceptionCode and GetExceptionInformation functions from within a filter expression to get information about the exception being filtered. GetExceptionCode returns a code that identifies the type of exception, and GetExceptionInformation returns a pointer to an EXCEPTION_POINTERS structure that contains pointers to CONTEXT and EXCEPTION_RECORD structures.

These functions cannot be called from within a filter function, but their return values can be passed as parameters to a filter function. GetExceptionCode can be used within the exception-handler block, but GetExceptionInformation cannot because the information it points to is typically on the stack and is destroyed when control is transferred to an exception handler. However, an application can copy the information to safe storage to make it available to the exception handler.

The advantage of a filter function is that it can handle an exception and return a value that causes the system to continue execution from the point at which the exception occurred. With an exception-handler block, in contrast, execution continues sequentially from the exception handler rather than from the point of the exception.

Handling an exception may be as simple as noting an error and setting a flag that will be examined later, printing a warning or error message, or taking some other limited action. If execution can be continued, it may also be necessary to change the machine state by modifying the context record. For an example of a filter function that handles a page fault exception, see Memory Management.

The UnhandledExceptionFilter function can be used as a filter function in a filter expression. It returns EXCEPTION_EXECUTE_HANDLER unless the process is being debugged, in which case it returns EXCEPTION_CONTINUE_SEARCH.


Termination Handling

A termination handler is a mechanism by which a developer ensures that a specific block of code is executed whenever flow of control leaves a particular guarded body of code. A termination handler consists of the following elements:

A guarded body of code

A block of termination code to be executed when the flow of control leaves the guarded body

Termination handlers are declared in language-specific syntax. In Microsoft C, they are implemented by the try-finally statement. For more information about the Microsoft C exception-handling syntax, see Syntax.

The guarded body of code can be a block of code, a set of nested blocks, or an entire procedure or function. Whenever the guarded body is executed, the block of termination code will be executed. The only exception to this is when the thread terminates during execution of the guarded body (for example, if the ExitThread or ExitProcess function is called from within the guarded body).

The termination block is executed when the flow of control leaves the guarded body, regardless of whether the guarded body terminated normally or abnormally. The guarded body is considered to have terminated normally when the last statement in the block is executed and control proceeds sequentially into the termination block. Abnormal termination occurs when the flow of control leaves the guarded body due to an exception, or due to a control statement such as return, goto, break, or continue. The AbnormalTermination function can be called from within the termination block to determine whether the guarded body terminated normally.


Exception Handling Syntax

This section describes the syntax and usage of structured exception handling as implemented in Microsoft C. The following keywords are interpreted by the Microsoft C compiler as part of the structured exception-handling mechanism.

Keyword	Description

try	Begins a guarded body of code. Used with the except keyword to construct an exception handler, or with the finally keyword to construct a termination handler.

except	Begins a block of code that is executed only when an exception occurs within its associated try block.

finally	Begins a block of code that is executed whenever the flow of control leaves its associated try block.

The compiler also interprets the GetExceptionCode, GetExceptionInformation, and AbnormalTermination functions as keywords, and their use outside the appropriate exception-handling syntax generates a compiler error. Following are brief descriptions of these functions.

Function	Description

GetExceptionCode	Returns a code that identifies the type of exception. This function can be called only from within the filter expression or exception-handler block of a try-except exception handler.

GetExceptionInformation	Returns a pointer to an EXCEPTION_POINTERS structure containing pointers to the context record and the exception record. This function can be called only from within the filter expression of a try-except exception handler.

AbnormalTermination	Indicates whether the flow of control left the associated try block sequentially after executing the last statement in the block. This function can be called only from within the finally block of a try-finally termination handler.

Exception-handler Syntax

The try and except keywords are used to construct a frame-based exception handler. The following example shows the structure of a try-except exception handler.

try {

    /* guarded body of code */

}

except (filter-expression) {

    /* exception-handler block */

}

Note that the try block and the exception-handler block require braces ({}). Using a goto statement to jump into the body of a try block or into an exception-handler block is not permitted. This rule applies to both try-except and try-finally statements.

The try block contains the guarded body of code that is protected by the exception handler. A function can have any number of try-except statements, and these exception-handling statements can be nested within the same function or in different functions. If an exception occurs within the try block, the system takes control and begins the search for an exception handler. For a detailed description of this search, see Exception Handling.

The exception handler only receives exceptions that occur within a single thread. This means that if a try block contains a call to the CreateProcess or CreateThread function, exceptions that occur within the new process or thread are not dispatched to this handler.

The system evaluates the filter expression of each exception handler guarding the code in which the exception occurred until either the exception is handled or there are no more handlers. A filter expression must be evaluated as one of the three following values.

Value	Meaning

EXCEPTION_EXECUTE_HANDLER

The system transfers control to the exception handler, and execution continues in the stack frame in which the handler is found.

EXCEPTION_CONTINUE_SEARCH

The system continues to search for a handler.

EXCEPTION_CONTINUE_EXECUTION

The system stops its search for a handler, and returns control to the point at which the exception occurred. If the exception is non-continuable, this results in a STATUS_NONCONTINUABLE_EXCEPTION exception.

The filter expression is evaluated in the context of the function in which the try-except statement is located, even though the exception may have occurred in a different function. This means that the filter expression can access the function's local variables. Similarly, the exception-handler block can access the local variables of the function in which it is located.

For more information about filter expressions and filter functions, see Frame-based Exception Handling.

Termination-handler Syntax

The try and finally keywords are used to construct a termination handler. The following example shows the structure of a try-finally termination handler.

try {

    /* guarded body of code */

}

finally {

    /* finally block */

}

As with the try-except statement, both the try block and the finally block require braces ({}), and using a goto statement to jump into either block is not permitted.

The try block contains the guarded body of code that is protected by the termination handler. A function can have any number of try-finally statements, and these termination handling structures can be nested within the same function or in different functions.

The finally block is executed whenever the flow of control leaves the try block. However, the finally block is not executed if either the ExitProcess or ExitThread function is called from within the try block.

If execution of the try block terminates because of an exception that invokes the exception-handling block of a frame-based exception handler, the finally block is executed before the exception-handling block is executed. Similarly, a call to the standard C longjmp function from the try block causes execution of the finally block before execution resumes at the target of the longjmp operation. If try block execution terminates due to a normal control statement (return, break, continue, or goto), the finally block is executed.

The AbnormalTermination function can be used within the finally block to determine whether the try block terminated sequentially--that is, whether it reached the closing brace (}). Leaving the try block because of a call to longjmp, a jump to an exception handler, or a return, break, continue, or goto statement, is considered an abnormal termination. Note that failure to terminate sequentially causes the system to search backward through all stack frames to determine whether any termination handlers must be called. This can result in performance degradation due to the execution of hundreds of instructions.

Execution of the finally block can terminate by any of the following means:

Execution of the last statement in the block and continuation to the next instruction

Use of a normal control statement (return, break, continue, or goto)

Use of longjmp, or a jump to an exception handler

The finally block is executed in the context of the function in which the try-finally statement is located. This means that the finally block can access that function's local variables.


Using an Exception Handler

The following example shows a version of the standard C strcpy function that can handle an invalid pointer and return NULL if one is encountered.

Note that this exception handler is intended to handle an access-violation exception, but is inappropriate if some other type of exception occurs. Therefore, the filter expression in the example uses the GetExceptionCode function to check the exception type before executing the handler. This enables the system to continue its search for an appropriate handler if some other type of exception occurs.

Note also that there is no problem with using a return statement in the try block of a try-except statement. This differs from the use of return in the try block of a try-finally statement, which causes an abnormal termination of the try block.

LPTSTR SafeStrcpy(LPTSTR lpszString1, LPTSTR lpszString2) {

    try {

        return strcpy(string1, string2);

    }

    except (GetExceptionCode() == EXCEPTION_ACCESS_VIOLATION ?

                    EXCEPTION_EXECUTE_HANDLER :

                    EXCEPTION_CONTINUE_SEARCH ) {

        return NULL;

    }

}

The following example shows the interaction of nested try-finally and try-except statements. The RaiseException function causes an exception in the guarded body of a try-finally termination handler that is inside the guarded body of a try-except exception handler. The exception causes the system to evaluate the FilterFunction function, whose return value in turn causes the exception handler to be invoked. However, before the exception-handler block is executed, the finally block of the termination handler is executed because the flow of control has left the try block of the termination handler.

DWORD FilterFunction() {

    printf("1 ");                    /* this is printed first  */

    return EXCEPTION_EXECUTE_HANDLER;

}

VOID main(VOID) {

    try {

        try {

            RaiseException(1,        /* exception code         */

                           0,        /* continuable exception  */

                           0, NULL); /* no arguments           */

        }

        finally {

            printf("2 ")             /* this is printed second */

        }

    }

    except ( FilterFunction() ) {

        printf("3\n");               /* this is printed last   */

    }

}


Using a Termination Handler

The following example shows how a try-finally statement is used to ensure that resources are released when execution of a guarded body of code terminates. In this case, a thread uses the EnterCriticalSection function to wait for ownership of a critical section object. When the thread is finished executing the code that is protected by the critical section, it must call the LeaveCriticalSection function to make the critical section object available to other threads. Using a try-finally statement guarantees that this will happen.

For more information about critical section objects, see Synchronization.

LPTSTR lpBuffer = NULL;

CRITICAL_SECTION csCriticalSection;

try {

    /*

     * EnterCriticalSection synchronizes code

     * with other threads.

     */

    EnterCriticalSection(&CriticalSection);

    /* Perform a task that may cause an exception. */

    lpBuffer = (LPTSTR) LocalAlloc(LPTR, 10);

    strcpy(lpBuffer,"Hello");  /* possible access violation */

    printf("%s\n",lpBuffer);

    LocalFree(lpBuffer);

}

/*

 * LeaveCriticalSection is called even if

 * an exception occurred.

 */

finally {

    LeaveCriticalSection(&CriticalSection);

}


Functions

Following are the functions used in structured exception handling.

AbnormalTermination

GetExceptionCode

GetExceptionInformation

RaiseException

SetUnhandledExceptionFilter

UnhandledExceptionFilter


Event Logging Overview

About Event Logging

When an error occurs in an application written for Microsoft® Windows™, the system administrator or support personnel must determine what caused the error, attempt to recover any lost data, and prevent the error from recurring. If applications record important events such as low-memory conditions or excessive disk retries, the record of this information, called an event log, can be used to help determine what conditions may have caused the error and the context in which the error occurred. (Event logging can also be applied to the Windows operating system and to system services.) By periodically viewing the event log, the system administrator may be able to identify problems before they cause serious damage.

Many applications record errors and events in various proprietary error logs. These proprietary logs have different formats, apply different user interfaces for their display, and cannot be merged to provide a complete report. But all of these logs store similar information and present the logged data in similar ways.

Event logging in Windows provides a standard, centralized way for applications (and Windows) to record important software and hardware events. It also supplies a standard user interface for viewing the logs and a programming interface for examining the logs. Event logging provides a means to merge events from various sources into a single informative story.

The following topics discuss Win32 event logging:

Terms

Event Logging Model

Logging Guidelines

Logging Performance and Size

Event Logging Management Information

Event Logging Operations

Event Log Entry

Interesting Special Cases

Using Event Logging

Adding a Source to the Registry

Reporting an Event

Querying the Event Log

Reading the Event Log

Functions


Event Logging Model

Event logs store records of significant events on behalf of the Windows operating system and the applications that run with Windows. Generally, applications should log only information that could be useful in diagnosing a hardware or software problem.

Events are classified as information, warnings, and errors. All event classifications have well-defined common data and can optionally include event-specific data. For example, information can assert that a service has started. Warnings are used for recoverable problems such as low disk-space conditions. Errors are used for nonrecoverable conditions that might cause an application to fail. In addition to logging event classifications, the security service logs successes and failures in audits.


Logging Guidelines

Because logging functions are general purpose, developers must decide what information is appropriate to log. It is important to note that logging consumes resources: disk space and logging time. The event log is not intended to be used as a trace facility.

You should log information about events that can be used to diagnose problems after they have occurred. Logging low-memory conditions, for example, can provide information about a problem that the system administrator can solve by adding more memory to the computer.

Following are more examples in which event logging is helpful:

A disk driver encounters a bad sector on the disk. It may be able to read from or write to the sector after some retries, but the sector will probably go bad eventually. The disk driver should log a warning if it can proceed; otherwise, it should log an error.

A file system finds a bad sector and fixes it. A large number of events of this type might indicate that the disk is about to fail. The file system logs a warning event.

A device driver encounters a hardware problem, such as a disk controller time-out, a power failure in a parallel port, or a data error from a network or serial card. Logging information about these events can help in diagnosing hardware problems. The device driver logs the hardware problem.

An Application encounters resource problems. An application or a device driver may get into a low-memory situation (caused by a code bug, for example) that degrades performance. Logging an event when memory allocation fails might later provide a clue about what went wrong. The application logs the resource problem.

A server application (a database or a communications server, for example) records events such as a user logging on, opening a database, or starting a file transfer. The server can also log important information as it runs, such as the number of resources the application is using, errors it encounters (cannot access file, host process disconnected, and so on), a corruption in the database (not able to find a leaf node down a certain path in a tree), or whether a file transfer was successful or not. All of this information can be valuable to a support person (or to the developer of the application). The application records such events and logs them as information events.


Logging Performance and Size

Typically, how much disk space does an event log require? What is the overhead for an application that makes a call to log an event? The answers to these questions depend on how much information the application chooses to log. This is why it is important to log only essential information and to place event logging calls in an error path in the application, rather than place them in the main path, where the performance hit would be more severe.


Event Logging Management Information

Event logging management information is stored in the Services key of the configuration database and can be modified by a system administrator.

The structure of the configuration information is as follows:

HKEY_LOCAL_MACHINE

  SYSTEM

    CurrentControlSet

      Services

        EventLog

          Application

          Security

          System

The EventLog key contains several subkeys, called logfiles. The default logfiles are Application, Security, and System. Each logfile subkey can contain subkeys, called sources. You cannot use a source name that has been used as a logfile name, and source names should not be hierarchical. (The backslash character [\] cannot be used in a registry key.) Each source entry contains information specific to the source of the event, as shown in the following table.

Value	Description

EventMessageFile	Specifies the path and filename for the event identifier message file. This value has the type REG_EXPAND_SZ.

CategoryMessageFile	Specifies the path and filename for the category message file. The category and event identifier message strings may be in the same file. This value has the type REG_EXPAND_SZ.

CategoryCount	Specifies the number of categories supported. This value has the type REG_DWORD.

TypesSupported	Specifies a bitmask of supported types. This value has the type REG_DWORD.

When an application uses the RegisterEventSource or OpenEventLog function to get a handle of an event log, the event logging service searches for the specified source name in the registry. For example, the Application logfile might have configured sources of Microsoft® SQL Server™ and Microsoft® Excel. If an application uses RegisterEventSource or OpenEventLog with a source name of Application, SQL, or Excel, the event logging service returns a handle to the Application logfile.

An application can use the Application event log without adding a new source key to the registry. If the application calls RegisterEventSource, passing a source name that cannot be found in the registry, the event logging service uses the Application logfile by default. However, because there is not a message or category string file, the event viewer will not be able to map the event identifier or category to a replacement string. For this reason, the recommended procedure is to add a unique source name for the application to the registry. This allows you to specify message files for the event identifier and category in your events. When your application reports an event, Event Viewer (EVENTVWR.EXE) maps the event identifier and category parameters in the reported event to replacement strings in the message files.

Applications and services should add their source names to the Application logfile. Device drivers should add their source name to the System logfile.

For more information about creating and using message files, see your message compiler documentation.


Event Logging Operations

In the following table are the five operations that can be performed on the event logs.

Operation	Function

Backup	BackupEventLog

Clear	ClearEventLog

Query	GetOldestEventLogRecord, GetNumberOfEventLogRecords

Read	ReadEventLog

Write	ReportEvent

The OpenEventLog, OpenBackupEventLog, RegisterEventSource, DeregisterEventSource, and CloseEventLog functions also open and close event log handles; this provides an object-oriented model for the function set, as well as some performance gain when performing multiple operations on the logs.

The OpenEventLog and ReportEvent functions take an optional server name as a parameter so that the operations can be performed on the remote server. OpenEventLog should be used for reading or performing some administrative operation (backup, clear, query) on the log, and RegisterEventSource should be used for writing to logs.


Event Log Entry

The following sections describe the parameters supplied for logged events.

Source

Source is the name of the software that logs the event. For many applications, Source may be simply the application name, or it may reflect a subcomponent of a larger application.

Event Identifier

Event identifiers are looked up within a message file to locate a description string that can be presented to the user. Support personnel also use event identifiers; if a user can identify the source and the event identifier, support personnel will know exactly which event has occurred. Event identifiers are unique to a particular source.

Type

Windows NT™ defines five types of event logging. Each event must be of a single type, because types cannot be combined.

Event type	Description

Information	Information events are used to note infrequent but significant successful operations. For example, when Microsoft SQL Server successfully loads, it may be appropriate to log a "SQL Server has started" information event. Note that while this is appropriate for major server services, it is generally inappropriate for a desktop application (Microsoft Excel, for example) to log an event each time it is started. Information events should not be used as a trace facility.

Warning	Warning events are used to indicate problems that are not significant, but that may foretell of future errors or other problems. Resource consumption is a good candidate for a Warning event. For example, a warning could be logged if disk space is low. Errors that are recovered without loss of function or data can be classified as warnings.

Error	Error events are used to indicate significant problems that have occurred and that the user should know about. Errors usually indicate a loss of functionality or data. For example, if a service cannot be loaded as the system boots, an Error event can be logged.

Success Audit	Success Audit events are security events that occur when an audited access attempt is successful. For example, a successful logon attempt is a Success Audit event.

Failure Audit	Failure Audit events are security events that occur when an audited access attempt fails. For example, a failed attempt to open a file is a Failure Audit event.

Category

Categories are used to help organize events so that they can be filtered in the Event Viewer. Each Source can define its own numbered Categories and the text strings to which they are mapped. The Categories must be numbered consecutively beginning with the number 1. With Event Viewer, it is possible to filter by Source and within Source, by Category. The security system uses several categories: Logon/Logoff, File System Access, Privileged Actions, Change in Security Policy. Categories for other parts of the system are developed over time as it becomes clear which events are being logged. An application can define its own categories.

Strings

Strings are optional language-independent (nonlocalized) strings used to fill in values for placeholders in description strings. Because the strings are not localized, it is critical that this field be used only to store language-independent strings such as numeric values or string tokens (filenames, user names, and so on). String length must not exceed 32 kilobytes - 1 characters.

It is not acceptable to use several strings to "paste" together a larger description or to use nontoken strings. The insertion string should be treated as data, not text. For example, the following example is not recommended:

Str1$ = successfully

Description = "User was %1 added to database."

Using these two strings to form the string, "User was successfully added to database." (the alternative being Str1$ = "not") is not acceptable for three reasons:

1	The strings "successfully" and "not" should be localized.

2	Even if the insertion strings are obtained from language-dependent message files, this is done when the event is logged, not when it is viewed. When the event is viewed, the language may be wrong.

3	Such substitutions of adverbs and adjectives will not work in many other languages. The preceding example should use two separate events.

The following example shows an appropriate use of strings:

Str1$ = "c:\testapp.c".

Description = "Access denied. Attempted to open the file %1"

Description

Each event is associated with a description located in a message file that is registered by the Source. The description should help the user understand what went wrong and suggest what actions to take. Focus the description toward users solving their own problems, not toward support people or developers. Make the description clear and concise and avoid culture-specific phrases. If your event includes private data in the Data field, include at the end of the description an explanation about what the Data field contains. For example, the network software often notes: "(The SMB is the event data)." As a convention, use parentheses around such remarks, as indicated in this example. Several applications can share the same message file, and the message file can contain descriptions for both the event identifier and the event category.

The description strings are indexed by event identifier, enabling Event Viewer to display event-specific text for any event based on the event identifier. All descriptions are localized and language dependent. Description strings can optionally contain placeholders for insertion strings. Each placeholder is represented by a percent sign and an index number for the string to substitute. For example, the placeholder %1 is replaced by the first insertion string, %5 is replaced by the fifth insertion string, and so on.

Data

Each event can have event-specific data associated with it. Event Viewer has no information of any of the events, and only displays extra data in a combined hexadecimal and text dump format. Use event-specific data sparingly, including it only if you are sure it will be useful to a support technician or a developer. You might include, for example, data containing a structure filled with information that could help a technician debug an application failure.

Examples of event-specific data are found in many network events; network control blocks (NCBs) are included as event-specific data. In all cases, the last part of the description string should include a note about what information is available as event-specific data. Third-party applications can use the Data field to store information the application can process independently of Event Viewer. For example, you could write your own viewer specific to your events, or write a program that scans the logfiles and makes reports, including information from the event-specific data.

The EVENTLOGRECORD Structure

The ReadEventLog function uses the EVENTLOGRECORD structure to format event log information. This structure contains information relating to the content of the event record. The actual event record information follows this structure in the buffer returned by the ReadEventLog function.


Interesting Special Cases

Each call to an event logging function is considered to be an atomic operation. For reading the event log, only whole event records are returned. For logging events, each event record is guaranteed to be written as a complete record in the log. The following list describes how the event logging service handles special conditions:

Multiple calls written to the same log. The event logging service serializes the operations; the event logs are written sequentially in the logfile.

A call to read and a call to write are made at the same time. What happens depends on where the current read operation is being carried out in the file. If the read position is at the end of the file, either the read operation fails with an "end-of-file" status (if the write operation has not been done), or it returns the new record that the write operation has just written to the log.

Clearing the log before reading. The read operation returns an "end-of-file" status after the file is cleared.

Clearing the log before writing. The clear operation truncates the logfile; the write operation then writes the new record at the beginning of the log.


Using Event Logging

The following sections illustrate these tasks related to event logging:

Adding a source to the registry.

Reporting an event.

Querying the event log.

Reading an event.

You can use the Windows Registration Database Editor (REGEDIT.EXE) to view the event log registry keys, and you can use Event Viewer to view the event logs.


Adding a Source to the Registry

You can use the default Application event log without adding your source name to the registry. However, Event Viewer will not be able to map your event identifier codes to message strings unless you register your source and provide a message-file name.

You can add a new source name to the registry by opening a new registry subkey under the Application key and adding registry values to the new subkey. The following code sample opens a new source name called SamplApp and adds to the new subkey a message-file name and a bitmask of supported types.

HKEY hk;

DWORD dwData;

UCHAR szBuf[80];

/*

 * Add your source name as a subkey under the Application

 * key in the EventLog service portion of the registry.

 */

if (RegCreateKey(HKEY_LOCAL_MACHINE,

"SYSTEM\\CurrentControlSet\\Services\

\\EventLog\\Application\\SamplApp",

            &hk))

    ErrorExit("could not create registry key");

/* Set the Event ID message-file name. */

strcpy(szBuf, "%SystemRoot%\\System\\SamplApp.dll");

/* Add the Event ID message-file name to the subkey. */

if (RegSetValueEx(hk,             /* subkey handle         */

        "EventMessageFile",       /* value name            */

        0,                        /* must be zero          */

        REG_EXPAND_SZ,            /* value type            */

        (LPBYTE) szBuf,           /* address of value data */

        strlen(szBuf) + 1))       /* length of value data  */

    ErrorExit("could not set event message file");

/* Set the supported types flags. */

dwData = EVENTLOG_ERROR_TYPE | EVENTLOG_WARNING_TYPE |

    EVENTLOG_INFORMATION_TYPE;

if (RegSetValueEx(hk,      /* subkey handle                */

        "TypesSupported",  /* value name                   */

        0,                 /* must be zero                 */

        REG_DWORD,         /* value type                   */

        (LPBYTE) &dwData,  /* address of value data        */

        sizeof(DWORD)))    /* length of value data         */

    ErrorExit("could not set supported types");

RegCloseKey(hk);


Reporting an Event

After you have added a source name to the registry, use the RegisterEventSource function to get a handle of the Application event log, as in the following example, which gets the handle and then adds an event to the logs.

LPSTR aszMsg[] = {

    "SamplApp",

    };

HANDLE h;

h = RegisterEventSource(NULL, /* uses local computer         */

    "SamplApp");              /* source name                 */

if (h == NULL)

    ErrorExit("could not register event source");

if (!ReportEvent(h,           /* event log handle            */

        EVENTLOG_ERROR_TYPE,  /* event type                  */

        0,                    /* category zero               */

        0x1003,               /* event identifier            */

        NULL,                 /* no user security identifier */

        1,                    /* one substitution string     */

        0,                    /* no data                     */

        (LPTSTR *) aszMsg,    /* address of string array     */

        NULL))                /* address of data             */

    ErrorExit("could not report event");

DeregisterEventSource(h);


Querying the Event Log

The following code sample displays the number of event records currently in the Application event log and the System event log.

/* Open the System log. */

h = OpenEventLog(NULL,  /* uses local computer   */

    "System");          /* source name          */

if (h == NULL)

    ErrorExit("could not open System event log");

/* Get the number of records in the System event log. */

if (!GetNumberOfEventLogRecords(h, &cRecords))

    ErrorExit

       ("could not get number of records");

printf("There are %d records in the System event log.\n", cRecords);

CloseEventLog(h);

/* Open the Application log. */

h = OpenEventLog(NULL,  /* uses local computer  */

    "Application");     /* source name          */

if (h == NULL)

    ErrorExit("could not open Application event log");

/* Get the number of records in the Application event log. */

if (!GetNumberOfEventLogRecords(h, &cRecords))

    ErrorExit("could not get number of records");

printf("There are %d records in the Application event log.\n",

    cRecords);

CloseEventLog(h);


Reading the Event Log

The following code sample reads all the records in the Application logfile and displays the event identifier, event type, and source name for each event log entry.

EVENTLOGRECORD *pevlr;

BYTE bBuffer[BUFFER_SIZE];

DWORD dwRead, dwNeeded, cRecords, dwThisRecord = 0;

    /* Open the Application event log. */

    h = OpenEventLog(NULL,  /* uses local computer      */

        "Application");     /* source name              */

    if (h == NULL)

        ErrorExit("could not open Application event log");

    pevlr = (EVENTLOGRECORD *) &bBuffer;

    /*

     * Opening the event log positions the file pointer

     * for this handle at the beginning of the log.

     *

     * Read records sequentially until there

     * are no more.

     */

    while (ReadEventLog(h,                /* event log handle */

                EVENTLOG_FORWARDS_READ |  /* reads forward    */

                EVENTLOG_SEQUENTIAL_READ, /* sequential read  */

                0,            /* ignored for sequential reads */

                pevlr,        /* address of buffer            */

                BUFFER_SIZE,  /* size of buffer               */

                &dwRead,      /* count of bytes read          */

                &dwNeeded)) { /* bytes in next record         */

        while (dwRead > 0) {

            /*

             * Print the event ID, type, and source name.

             * The source name is just past the end of the

             * formal structure.

             */

            printf("%02d  Event ID: 0x%08X ",

                dwThisRecord++, pevlr->EventID);

            printf("EventType: %d Source: %s\n",

                pevlr->EventType, (LPSTR) ((LPBYTE) pevlr +

                sizeof(EVENTLOGRECORD)));

            dwRead -= pevlr->Length;

            pevlr = (EVENTLOGRECORD *)

                ((LPBYTE) pevlr + pevlr->Length);

        }

        pevlr = (EVENTLOGRECORD *) &bBuffer;

    }

    CloseEventLog(h);


Functions

The following functions are used with event logging.

BackupEventLog

ClearEventLog

CloseEventLog

DeregisterEventSource

GetNumberOfEventLogRecords

GetOldestEventLogRecord

OpenBackupEventLog

OpenEventLog

ReadEventLog

RegisterEventSource

ReportEvent


Performance Monitoring Overview

About Performance Monitoring

Performance monitoring refers to determining the system resources an application consumes, such as processor time and memory. Because the underlying architecture of Microsoft Windows NT is fundamentally different from previous versions of Windows, developers will probably want to examine their applications to ensure efficient use of their system resources and to fine-tune application performance. This is particularly true for applications ported from Windows versions 3.x. Many coding practices recommended for Windows 3.x are not necessary or are not recommended for Windows NT. For example, in Windows 3.x, developers were encouraged to keep files open only while the files were being used. With the increased size of the virtual address space in Windows NT, however, developers should avoid the practice of opening, using, and closing in favor of keeping files open while the application runs.

The Win32 performance-monitoring functions can help in evaluating the effects of such changes as developers migrate to Windows NT.

The following topics discuss performance monitoring:

Terms

Counters and Elapsed Times

Registry Database

Getting Performance Data

Getting Descriptive Text

Getting Selected Data

Using Performance Monitoring

Displaying Object, Counter, and Instance Names

Displaying Counter Title Indices

Functions


Counters and Elapsed Times

A counter is a general term used in programming to refer to an incrementing variable. Some systems include a high-resolution performance counter that provides high-resolution elapsed times. The elapsed time can be used to fine-tune sections of source code. Windows NT supports two functions that enable application developers to obtain the value of a counter.

If a high-resolution performance counter exists on the system, the QueryPerformanceFrequency function can be used to express the frequency in counts per second. The value of the count is processor dependent. On some processors, for example, the count might be the cycle rate of the processor clock.

The QueryPerformanceCounter function retrieves the current value of the high-resolution performance counter (if one exists on the system). By calling this function at the beginning and end of a section of code, an application essentially uses the counter as a stopwatch.

For example, QueryPerformanceFrequency might indicate that the frequency of the high-resolution performance counter on the system is 50,000 counts per second. If the application calls QueryPerformanceCounter immediately before and immediately after the section of code to be timed, the counter values might be 1500 counts and 3500 counts, respectively. This indicates that .04 seconds (2000 counts) elapsed while the code executed.


Registry Database

Windows NT includes several tools that monitor the system. To present this information in a different format, to use information inside another application, or to create a performance monitor, your application must retrieve information through the registry.


Getting Performance Data

Getting Performance Data

An application can obtain system-performance information by using the RegQueryValueEx registry function, with the HKEY_PERFORMANCE_DATA key. The application can use the RegOpenKey function to open the HKEY_PERFORMANCE_DATA handle, but it should use RegCloseKey to close the handle when it has finished running. This allows monitored software to be to be removed or installed, which cannot happen while they are being monitored. Network transports and drivers are examples of monitored software you may wish to remove.

The performance data is not stored in the registry. Using the RegQueryValueEx function with the HKEY_PERFORMANCE_DATA key causes the system to collect the data from the appropriate system object managers.

If an application is accessing a remote system, it must use the RegConnectRegistry function with the name of the remote system and the HKEY_PERFORMANCE_DATA key. RegConnectRegistry retrieves a key the application can use with RegQueryValueEx to retrieve performance data from the remote system.

The basic layout of the data retrieved by RegQueryValueEx is a PERF_DATA_BLOCK structure followed by one PERF_OBJECT_TYPE structure and accompanying data for each type of object being monitored. The system being observed defines objects that can be monitored. Typical object types include processors, disks, and memory.

The PERF_DATA_BLOCK structure describes the system and the performance data. This includes the size of the data, the number of objects being monitored, the frequency and value of the high-resolution performance counter, an offset to the system name, and so on.

The PERF_OBJECT_TYPE structure describes the performance data for one type of object. This includes the size of the structure and the object-specific data that follows the structure, the number of counters defined for the object type, the number of instances of this object type, the level of informational details provided, the code page, indices to the object name and Explain title in the title database, and so on.

Following each PERF_OBJECT_TYPE structure, there is a list of PERF_COUNTER_DEFINITION structures, one for each counter defined for the object. The PERF_COUNTER_DEFINITION structure specifies the type and size of the counter, the offset to the counter, the detail level, the counter name, and Explain title in the registry, and so on.

An instance is an instantiation (the creation of an instance) of a particular object type. The number of instances of a particular object type determines what follows the list of counter definitions. Not all object types have instances. A memory object, for example, has no instances because the system has only one memory. If the object type does not have instances, 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, in bytes, and the counter data that follows it.

If the object type has one or more instances, 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, identifier, and name of the parent of the instance. For example, the thread object type has instances; each thread in the system is an instance.

The number of object types, instances, and counters may vary from one RegQueryValueEx call to another. Therefore, the number and size of structures included in the performance data as well as the size of the data that follows each structure may also vary. To ensure that it is receiving the appropriate information, an application must use the offsets included in the performance structures to navigate through the performance data. Every offset is relative to the beginning of the structure containing it.


Getting Descriptive Text

Getting Descriptive Text

The names of the objects and counters, as well as the text that explains their meaning, are not returned in the performance structures described in the previous section. Instead, the structures contain indices to a structure in the Configuration Registry where the Unicode multilingual names and descriptions for each object and counter are stored. To access this information, the application must open the following registry node:

\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\<langid>

The language node (langid) is the ASCII representation of the 3-digit hexadecimal language identifier. For example, the U.S. English node is "009". This node, once opened, can be queried for values of either 'Counters' or 'Help'. The names of object types are included in the 'Counters' data. The 'Help' data supplies the Explain text.

The 'Counters' and 'Help' data are stored in MULTI_SZ strings. This type of data is 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 item is the Unicode string of the index contained in PERF_OBJECT_TYPE.ObjectNameTitleIndex or PERF_COUNTER_DEFINITION.CounterNameTitleIndex. The second item is the actual name of the index. Following is a fragment of the paired data:

2     System

4     Memory

6     % Processor Time

10    Read Operations/sec

12    Write Operations/sec

To retrieve a name or the Explain text for an item, an application must do the following:

1	If the system is remote, use RegConnectRegistry.

2	Use RegOpenKeyEx, specifying the registry node described previously, and the appropriate language node.

3	Use RegQueryValueEx, specifying either 'Counters' or 'Help' as the name of the value to query. This provides MULTI_SZ data containing either the names of all the objects and counters, or Help information for all the objects and counters.

4	Convert the appropriate index (PERF_OBJECT_TYPE.ObjectNameTitleIndex, PERF_OBJECT_TYPE.ObjectHelpTitleIndex, PERF_COUNTER_DEFINITION.CounterNameTitleIndex, or PERF_COUNTER_DEFINITION.CounterHelpTitleIndex) into Unicode or ASCII, depending on whether the application is Unicode or ASCII.

5	Search the MULTI_SZ data for the appropriate index.

6	Retrieve the string following the matching index as the object's name or descriptive information.


Getting Selected Data

Getting Selected Data

When using the RegQueryValueEx function, an application must use the lpcbData parameter to specify a byte count of the amount of data to retrieve. Estimating this amount is difficult because the number of object types and their instances is determined by the system configuration and system activity. The amount may vary from one request to another. If the function does not pass enough space, the return value will be ERROR_MORE_DATA. Therefore, your application should include a retry loop in which it passes increasing amounts of buffer space until it no longer gets this error. The successful buffer size should be the starting point for subsequent calls to RegQueryValueEx. This technique is illustrated in the example code at the end of this topic.

In some cases, the application may not need to retrieve all the performance data provided by the system. Retrieving all the performance data provided by the system may be costly in terms of processor or memory requirements. The lpszValueName parameter of RegQueryValueEx indicates the amount of information to retrieve. This parameter can be in one of the following formats. The strings are case sensitive. If a string includes more than one word, the words must be separated by a space.

String	Meaning

Global	The function returns all data for counters on the local computer except those included in the Costly category, described later in this table.

nnn xx yyy	Each of these strings is a Unicode string representing the decimal value for a PERF_OBJECT_TYPE.ObjectNameTitleIndex. The function returns data only about the specified object types on the local computer.

Note that more object types may be returned than are requested. This occurs if other object types are needed to support the requested data, e.g., processes are needed to identify threads, so processes will also be returned even if only threads are requested.

Foreign ssss	The string ssss is the name of a foreign computer--that is, one that does not support the registry calls for returning data remotely. The function returns all data for counters on the foreign computer, if your system is capable of collecting data from a foreign computer. You may want to try this approach if RegConnectRegistry fails to connect to a foreign computer.

Foreign ssss nnn xx yyy	This format combines Foreign ssss and nnn xx yyy, discussed above. The function returns all data for the specified counters on the foreign computer, if your system is capable of collecting data from a foreign computer. An application can try this approach if RegConnectRegistry fails to connect to a foreign computer, but you do not want all the available data.

Costly	The function returns data for object types whose data is expensive to collect, in terms of processor time or memory usage. You may wish to start a secondary thread to access this data, if you wish to respond to the user during data collection.


Using Performance Monitoring

The next two sections of this Overview provide code samples that illustrate common performance monitoring operations.

Displaying Object, Counter, and Instance Names

Displaying Counter Title Indices


Displaying Object, Counter, and Instance Names

The following example, PERFEX, includes code that illustrates how to display all counter indices in the system.

#define UNICODE 1

#define _UNICODE 1

//

//  "C" Include files

//

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <malloc.h>

//

//  Windows Include files

//

#include <windows.h>

#include <winperf.h>

#include <tchar.h>

//

//  Local constants

//

#define RESERVED        0L                  // reserved argument in fn. calls

#define INITIAL_SIZE    40960L              // initial perf data buff size

#define EXTEND_SIZE     4096L               // extend size of perf data buff

#define LINE_LENGTH     80                  // display line length

#define WRAP_POINT      LINE_LENGTH-12      // wrap point for explain text

#define OBJECT_TEXT_INDENT 4                // indent of object explain text

//

//  Command line option values

//

#define COMMAND_ERROR   0

#define COMMAND_HELP    1

#define COMMAND_COUNTER 2

//

//

//  Text string Constant definitions

//

const LPTSTR NamesKey = TEXT("SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Perflib");

const LPTSTR DefaultLangId = TEXT("009");

const LPTSTR Counters = TEXT("Counters");

const LPTSTR Help = TEXT("Help");

const LPTSTR LastHelp = TEXT("Last Help");

const LPTSTR LastCounter = TEXT("Last Counter");

const LPTSTR Slash = TEXT("\\");

const LPTSTR Global = TEXT("Global");

//

//  Global Buffers

//

TCHAR   cValueName[LINE_LENGTH];  // used to store counter value string

CHAR    cExeName[LINE_LENGTH*2];  // used in processing command line

CHAR    cCtrName[LINE_LENGTH];    // used in processing command line

BOOL

StringToInt (

    IN  LPTSTR  InStr,

    OUT PDWORD  pdwOutInt

)

/*++

StringToInt

    Returns the decimal interpretation of the string in the InStr

    argument. Works for either Unicode or ANSI strings.

Arguments:

    InStr

        string to translate

    pdwOutInt

        base 10 version of the number in the InStr argument

Return Value:

    TRUE if conversion was successful

    FALSE if not

--*/

{

    // check for NULL pointers passed to function

    if ((!InStr) || (!pdwOutInt)) {

        SetLastError (ERROR_BAD_ARGUMENTS);

        return FALSE;

    }

    if ( (_stscanf (InStr, TEXT(" %d"), pdwOutInt)) == 1) {

        return TRUE;

    } else {

        return FALSE;

    }

} // StringToInt

VOID

DisplayCommandHelp (

)

/*++

DisplayCommandHelp

    displays usage of command line arguments

Arguments

    NONE

Return Value

    NONE

--*/

{

    printf ("\n\nPERFEX:");

    printf ("\n    Sample program to demonstrate Win32 Performance API");

    printf ("\n\nUsage:");

    printf ("\n\n     perfex [-? | counter]");

    printf ("\n\n          -?  Displays a list of all counter objects in the system");

    printf ("\n     counter  is the name of a counter object");

    printf ("\n                  and displays the performance counters for that object");

    printf ("\n");

} // DisplayCommandHelp

LPTSTR

*BuildNameTable(

    IN HKEY    hKeyRegistry,   // handle to registry db with counter names

    IN LPTSTR  lpszLangId,     // unicode value of Language subkey

    OUT PDWORD  pdwLastItem     // size of array in elements

)

/*++

BuildNameTable

    Caches the counter names and explain text to accelerate name lookups

    for display.

Arguments:

    hKeyRegistry

            Handle to an open registry (this can be local or remote.) and

            is the value returned by RegConnectRegistry or a default key.

    lpszLangId

            The unicode id of the language to look up. (default is 009)

    pdwLastItem

            The last array element

Return Value:

    pointer to an allocated table. (the caller must free it when finished!)

    the table is an array of pointers to zero terminated TEXT strings.

    A NULL pointer is returned if an error occured. (error value is

    available using the GetLastError function).

    The structure of the buffer returned is:

        Array of pointers to zero terminated strings consisting of

            pdwLastItem elements

        MULTI_SZ string containing counter id's and names returned from

            registry for the specified language

        MULTI_SZ string containing explain text id's and explain text strings

            as returned by the registry for the specified language

    The structures listed above are contiguous so that they may be freed

    by a single "free" call when finished with them, however only the

    array elements are intended to be used.

--*/

{

    LPTSTR  *lpReturnValue;     // returned pointer to buffer

    LPTSTR  *lpCounterId;       //

    LPTSTR  lpCounterNames;     // pointer to Names buffer returned by reg.

    LPTSTR  lpHelpText ;        // pointet to exlpain buffer returned by reg.

    LPTSTR  lpThisName;         // working pointer

    BOOL    bStatus;            // return status from TRUE/FALSE fn. calls

    LONG    lWin32Status;       // return status from fn. calls

    DWORD   dwHelpItems;        // number of explain text items

    DWORD   dwCounterItems;     // number of counter text items

    DWORD   dwValueType;        // value type of buffer returned by reg.

    DWORD   dwArraySize;        // size of pointer array in bytes

    DWORD   dwBufferSize;       // size of total buffer in bytes

    DWORD   dwCounterSize;      // size of counter text buffer in bytes

    DWORD   dwHelpSize;         // size of help text buffer in bytes

    DWORD   dwThisCounter;      // working counter

    DWORD   dwLastId;           // largest ID value used by explain/counter text

    HKEY    hKeyValue;          // handle to Perflib entry in registry

    HKEY    hKeyNames;          // handle to names subkey in registry

    LPTSTR  lpValueNameString;  // pointer to buffer conatining subkey name

    //initialize pointers to NULL

    lpValueNameString = NULL;

    lpReturnValue = NULL;

    hKeyValue = NULL;

    hKeyNames = NULL;

    // check for null arguments and insert defaults if necessary

    if (!lpszLangId) {

        lpszLangId = DefaultLangId;

    }

    // open handle to Perflib key in registry to get number of items

    // used in order to compute array and buffer sizes

    lWin32Status = RegOpenKeyEx (

        hKeyRegistry,

        NamesKey,

        RESERVED,

        KEY_READ,

        &hKeyValue);

    // on error, free buffers, close keys and return NULL pointer

    if (lWin32Status != ERROR_SUCCESS) {

        goto BNT_BAILOUT;

    }

    // query registry to get number of Explain text items

    dwBufferSize = sizeof (dwHelpItems);

    lWin32Status = RegQueryValueEx (

        hKeyValue,

        LastHelp,

        RESERVED,

        &dwValueType,

        (LPBYTE)&dwHelpItems,

        &dwBufferSize);

    if ((lWin32Status != ERROR_SUCCESS) || (dwValueType != REG_DWORD)) {

        goto BNT_BAILOUT;

    }

    // query registry to get number of counter and object name items

    dwBufferSize = sizeof (dwCounterItems);

    lWin32Status = RegQueryValueEx (

        hKeyValue,

        LastCounter,

        RESERVED,

        &dwValueType,

        (LPBYTE)&dwCounterItems,

        &dwBufferSize);

    if ((lWin32Status != ERROR_SUCCESS) || (dwValueType != REG_DWORD)) {

        goto BNT_BAILOUT;

    }

    // use the greater of Help items or Counter Items to size array

    if (dwHelpItems >= dwCounterItems) {

        dwLastId = dwHelpItems;

    } else {

        dwLastId = dwCounterItems;

    }

    // array size is # of elements (+ 1, since names are "1" based)

    // times the size of a pointer

    dwArraySize = (dwLastId + 1) * sizeof(LPTSTR);

    // allocate string buffer for language ID key string

    lpValueNameString = malloc (

        lstrlen(NamesKey) * sizeof (TCHAR) +

        lstrlen(Slash) * sizeof (TCHAR) +

        lstrlen(lpszLangId) * sizeof (TCHAR) +

        sizeof (TCHAR));

    if (!lpValueNameString) {

        lWin32Status = ERROR_OUTOFMEMORY;

        goto BNT_BAILOUT;

    }

    // build the key string for the specified language ID

    lstrcpy (lpValueNameString, NamesKey);

    lstrcat (lpValueNameString, Slash);

    lstrcat (lpValueNameString, lpszLangId);

    lWin32Status = RegOpenKeyEx (   // get handle to this key in the

        hKeyRegistry,               // registry

        lpValueNameString,

        RESERVED,

        KEY_READ,

        &hKeyNames);

    if (lWin32Status != ERROR_SUCCESS) goto BNT_BAILOUT;

    // get size of counter names

    dwBufferSize = 0;

    lWin32Status = RegQueryValueEx (

        hKeyNames,

        Counters,

        RESERVED,

        &dwValueType,

        NULL,

        &dwBufferSize);

    if (lWin32Status != ERROR_SUCCESS) goto BNT_BAILOUT;

    dwCounterSize = dwBufferSize;

    // get size of help text

    dwBufferSize = 0;

    lWin32Status = RegQueryValueEx (

        hKeyNames,

        Help,

        RESERVED,

        &dwValueType,

        NULL,

        &dwBufferSize);

    if (lWin32Status != ERROR_SUCCESS) goto BNT_BAILOUT;

    dwHelpSize = dwBufferSize;

    // allocate buffer with room for pointer array, counter name

    // strings and help name strings

    lpReturnValue = malloc (dwArraySize + dwCounterSize + dwHelpSize);

    if (!lpReturnValue) {

        lWin32Status = ERROR_OUTOFMEMORY;

        goto BNT_BAILOUT;

    }

    // initialize pointers into buffer

    lpCounterId = lpReturnValue;

    lpCounterNames = (LPTSTR)((LPBYTE)lpCounterId + dwArraySize);

    lpHelpText = (LPTSTR)((LPBYTE)lpCounterNames + dwCounterSize);

    // read counter names into buffer. Counter names will be stored as

    // a MULTI_SZ string in the format of "###" "Name"

    dwBufferSize = dwCounterSize;

    lWin32Status = RegQueryValueEx (

        hKeyNames,

        Counters,

        RESERVED,

        &dwValueType,

        (LPVOID)lpCounterNames,

        &dwBufferSize);

    if (lWin32Status != ERROR_SUCCESS) goto BNT_BAILOUT;

    // read explain text into buffer. Counter names will be stored as

    // a MULTI_SZ string in the format of "###" "Text..."

    dwBufferSize = dwHelpSize;

    lWin32Status = RegQueryValueEx (

        hKeyNames,

        Help,

        RESERVED,

        &dwValueType,

        (LPVOID)lpHelpText,

        &dwBufferSize);

    if (lWin32Status != ERROR_SUCCESS) goto BNT_BAILOUT;

    // load counter array items, by locating each text string

    // in the returned buffer and loading the

    // address of it in the corresponding pointer array element.

    for (lpThisName = lpCounterNames;

         *lpThisName;

         lpThisName += (lstrlen(lpThisName)+1) ) {

        // first string should be an integer (in decimal digit characters)

        // so translate to an integer for use in array element identification

        bStatus = StringToInt (lpThisName, &dwThisCounter);

        if (!bStatus) {

            // error is in GetLastError

            goto BNT_BAILOUT;  // bad entry

        }

        // point to corresponding counter name which follows the id number

        // string.

        lpThisName += (lstrlen(lpThisName)+1);

        // and load array element with pointer to string

        lpCounterId[dwThisCounter] = lpThisName;

    }

    // repeat the above for the explain text strings

    for (lpThisName = lpHelpText;

         *lpThisName;

         lpThisName += (lstrlen(lpThisName)+1) ) {

        // first string should be an integer (in decimal unicode digits)

        bStatus = StringToInt (lpThisName, &dwThisCounter);

        if (!bStatus) {

            // error is in GetLastError

            goto BNT_BAILOUT;  // bad entry

        }

        // point to corresponding counter name

        lpThisName += (lstrlen(lpThisName)+1);

        // and load array element;

        lpCounterId[dwThisCounter] = lpThisName;

    }

    // if the last item arugment was used, then load the last ID value in it

    if (pdwLastItem) *pdwLastItem = dwLastId;

    // free the temporary buffer used

    if (lpValueNameString) {

        free ((LPVOID)lpValueNameString);

    }

    // close the registry keys

    RegCloseKey (hKeyValue);

    RegCloseKey (hKeyNames);

    // exit returning the pointer to the buffer

    return lpReturnValue;

BNT_BAILOUT:

    if (lWin32Status != ERROR_SUCCESS) {

        // if lWin32Status has error, then set last error value to it,

        // otherwise assume that last error already has value in it

        SetLastError (lWin32Status);

    }

    // free buffers used by this routine

    if (lpValueNameString) {

        free ((LPVOID)lpValueNameString);

    }

    if (lpReturnValue) {

        free ((LPVOID)lpReturnValue);

    }

    if (hKeyValue) RegCloseKey (hKeyValue);

    if (hKeyNames) RegCloseKey (hKeyNames);

    return NULL;

} // BuildNameTable

DWORD

GetSystemPerfData (

    IN HKEY hKeySystem,

    IN LPTSTR   pValue,

    IN PPERF_DATA_BLOCK *pPerfData

)

/*++

GetSystemPerfData

    Allocates data buffer as required and queries performance data

    specified in pValue from registry.

Arguments

    hKeySystem

        Handle to performance data in registry

    pValue

        Value string to return from registry

    pPerfData

        address of pointer to allocated perf data block that is

        filled in by call to RegQueryValue.

Return Value

    ERROR_SUCCESS if data returned

    WIN 32 ERROR if error encountered

--*/

{  // GetSystemPerfData

    LONG     lError ;   // Win 32 Error returned by fn. calls

    DWORD    Size;      // size of data buffer passed to fn. call

    DWORD    Type;      // type of data buffer returned by fn. call

    // allocate initial buffer if one is not passed into this routine

    if (*pPerfData == NULL) {

        *pPerfData = malloc (INITIAL_SIZE);

        if (*pPerfData == NULL) {

            return ERROR_OUTOFMEMORY;

        }

    }

    while (TRUE) {

        Size = _msize (*pPerfData); // query the size of the data buffer

        lError = RegQueryValueEx (  // get performance data from reg.

            hKeySystem,

            pValue,

            RESERVED,

            &Type,

            (LPBYTE)*pPerfData,

            &Size) ;

        // check for success and valid perf data block signature

        if ((!lError) &&

            (Size > 0) &&

            (*pPerfData)->Signature[0] == (WCHAR)'P' &&

            (*pPerfData)->Signature[1] == (WCHAR)'E' &&

            (*pPerfData)->Signature[2] == (WCHAR)'R' &&

            (*pPerfData)->Signature[3] == (WCHAR)'F' ) {

            return (ERROR_SUCCESS) ;

        }

        // if buffer is not big enough, reallocate and try again

        if (lError == ERROR_MORE_DATA) {

            *pPerfData = realloc (

                *pPerfData,

                _msize (*pPerfData) +

                EXTEND_SIZE) ;

            if (!*pPerfData) {

                return (lError) ;

            }

        } else {

            return (lError) ;

        }

    }

}  // GetSystemPerfData

/*++

Pointer Functions

    These functions are used to walk down the various structures

    in the perf data block returned by the call to RegQueryValueEx

--*/

PPERF_OBJECT_TYPE

FirstObject (

    PPERF_DATA_BLOCK pPerfData

)

{

    return ((PPERF_OBJECT_TYPE) ((PBYTE) pPerfData + pPerfData->HeaderLength)) ;

}

PPERF_OBJECT_TYPE

NextObject (

    PPERF_OBJECT_TYPE pObject

)

{  // NextObject

    return ((PPERF_OBJECT_TYPE) ((PBYTE) pObject + pObject->TotalByteLength)) ;

}  // NextObject

PERF_COUNTER_DEFINITION *

FirstCounter(

    PERF_OBJECT_TYPE *pObjectDef

)

{

    return (PERF_COUNTER_DEFINITION *)

               ((PCHAR) pObjectDef + pObjectDef->HeaderLength);

}

PERF_COUNTER_DEFINITION *

NextCounter(

    PERF_COUNTER_DEFINITION *pCounterDef

)

{

    return (PERF_COUNTER_DEFINITION *)

               ((PCHAR) pCounterDef + pCounterDef->ByteLength);

}

PERF_INSTANCE_DEFINITION *

FirstInstance (

    PERF_OBJECT_TYPE    *pObject

)

{

    return (PERF_INSTANCE_DEFINITION *)

        ((PBYTE) pObject + pObject->DefinitionLength);

}

PERF_INSTANCE_DEFINITION *

NextInstance (

    PERF_INSTANCE_DEFINITION *pInstance

)

{

    // next instance is after this instance + this instances counter data

    PERF_COUNTER_BLOCK  *pCtrBlk;

    pCtrBlk = (PERF_COUNTER_BLOCK *)

        ((PBYTE)pInstance + pInstance->ByteLength);

    return (PERF_INSTANCE_DEFINITION *)

        ((PBYTE)pInstance + pInstance->ByteLength + pCtrBlk->ByteLength);

}

LONG

PrintExplainText(

    DWORD   Indent,

    LPTSTR  szTextString

)

/*++

PrintExplainText

    Prints Long strings in a wrapped format for display on screen

Arguments

    Indent

        number of characters to indent text from left margin

    szTextString

        string to print on stdout

ReturnValue

    number of lines of text printed

--*/

{

    LPTSTR  szThisChar;

    BOOL    bNewLine;

    DWORD   dwThisPos;

    DWORD   dwLinesUsed;

    szThisChar = szTextString;

    dwLinesUsed = 0;

    // check arguments

    if (!szTextString) {

        return dwLinesUsed;

    }

    if (Indent > WRAP_POINT) {

        return dwLinesUsed; // can't do this

    }

    bNewLine = TRUE;

    // print text

    while (*szThisChar) {

        if (bNewLine){

            for (dwThisPos = 0; dwThisPos < Indent; dwThisPos++) {

                printf (" ");

            }

            bNewLine = FALSE;

        }

        if ((*szThisChar == ' ') && (dwThisPos >= WRAP_POINT)) {

            printf ("\n");

            bNewLine = TRUE;

            // go to next printable character

            while (*szThisChar <= ' ') {

                szThisChar++;

            }

            dwLinesUsed++;

        } else {

            printf ("%c", *szThisChar);

            szThisChar++;

        }

        dwThisPos++;

    }

    printf ("\n");

    bNewLine = TRUE;

    dwLinesUsed++;

    return dwLinesUsed;

} // PrintExplainText

DWORD

ProcessCommandLine (

    IN LPTSTR  lpCmdLine,

    IN LPTSTR  *lppCounterNames,

    IN DWORD   dwLastCounter,

    OUT LPTSTR  *lpValueString

)

/*++

ProcesCommandLine

    Reads arguments in command line and determines what program should do.

    Command line syntax is:

        PERFEX [ ? | Object]

    if "?" is in command line, then list of counter objects is displayed

    if a text string (other than "?") then string is translated to a

    counter object id and the counters for that object are displayed

Arguments

    lpCmdLine

        null terminated string that contains command line arguments

    lppCounterNames

        pointer to array of counter names (used for lookup)

    dwLastCounter

        number of elements in CounterNames array

    lpValueString

        value string to send to ReqQueryValue in order to return counter

        data for specified counter

ReturnValue

    TRUE    if valid data is returned

    FALSE   if unable to process command line (command syntax help should

            be displayed).

--*/

{

    LPTSTR   lpLocalString;

    DWORD   dwReturnValue;

    DWORD   dwElem;

    dwReturnValue = COMMAND_ERROR;  // assume error until proven otherwise

    lpLocalString = lpCmdLine;

    // move pointer past exe name

    while ((*lpLocalString > ' ') && (*lpLocalString)) lpLocalString++;

    // move pointer to next non-space char;

    while ((*lpLocalString <= ' ') && (*lpLocalString)) lpLocalString++;

    if (*lpLocalString) {

        // check for "HELP" command line argument

        if (*lpLocalString == '-') {

            if (*++lpLocalString == '?') {

                *lpValueString = Global;

                dwReturnValue = COMMAND_HELP;

            }

        } else { // first arg is not preceded by a '-' so compare to counters

            // see if command line matches a counter name

            for (dwElem = 0; dwElem <= dwLastCounter; dwElem++) {

                // compare counter name to command line

                if ((lstrcmpi(lppCounterNames[dwElem], lpLocalString)) == 0) {

                    // match found

                    // make element Number a string and exit

                    _stprintf ((LPTSTR)&cValueName[0], TEXT("%d"), dwElem);

                    *lpValueString = (LPTSTR)&cValueName[0];

                    dwReturnValue = COMMAND_COUNTER;

                    break;  // out of for loop

                } // endif command line matches string

            } // end for loop that searches table

        } // if not "-?"

    } else {

        dwReturnValue = COMMAND_ERROR;

    }

    return dwReturnValue;

} // ProcessCommandLine

VOID

DisplayObjectNames (

    PPERF_DATA_BLOCK    pPerf,

    LPTSTR              *pNames

)

/*++

DisplayObjectNames

    Scans the perf data and prints the name of each object found in the

    list

Arguments

    pPerf

        pointer to the perf data block returned by the call to

        RegQueryValueEx

    pNames

        pointer to the name table containing the array of counter names

        and explain text pointers.

Return Value

    NONE

--*/

{

    DWORD       dwThisObject;   // count of objects

    PPERF_OBJECT_TYPE pThisObject;    // pointer to object structure

    printf ("\nThe available performance counter objects are:");

    // loop from first object in buffer returned and display the

    // number of objects in the buffer

    for (dwThisObject = 0, pThisObject = FirstObject (pPerf);

        dwThisObject < pPerf->NumObjectTypes;

        dwThisObject++, pThisObject = NextObject(pThisObject)) {

        printf ("\n\"%ws\"\n",

            pNames[pThisObject->ObjectNameTitleIndex]);

        PrintExplainText (OBJECT_TEXT_INDENT,

            pNames[pThisObject->ObjectHelpTitleIndex]);

    }

} // DisplayObjectNames

VOID

DisplayCounterData (

    PPERF_DATA_BLOCK    pPerf,

    LPTSTR              *pNames

)

/*++

DisplayCounterData

    Scans the perf data and prints the name of counter and instance found

    in the list

Arguments

    pPerf

        pointer to the perf data block returned by the call to

        RegQueryValueEx

    pNames

        pointer to the name table containing the array of counter names

        and explain text pointers.

Return Value

    NONE

--*/

{

    DWORD               dwThisObject;   // count of objects

    PPERF_OBJECT_TYPE   pThisObject;    // pointer to object structure

    DWORD               dwThisCounter;  // count of counters

    PPERF_COUNTER_DEFINITION    pThisCounter;

    LONG               lThisInstance;

    PPERF_INSTANCE_DEFINITION   pThisInstance;

    // for each object in buffer, display each counter and instance

    for (dwThisObject = 0, pThisObject = FirstObject (pPerf);

        dwThisObject < pPerf->NumObjectTypes;

        dwThisObject++, pThisObject = NextObject(pThisObject)) {

        printf ("\n\nThe object \"%ws\", ",

            pNames[pThisObject->ObjectNameTitleIndex]);

        // if there are instnances, then loop through all instances

        // of this object

        if (pThisObject->NumInstances != PERF_NO_INSTANCES) {

            printf (" which has the following instances:");

            for (lThisInstance = 0, pThisInstance = FirstInstance(pThisObject);

                lThisInstance < pThisObject->NumInstances;

                lThisInstance++, pThisInstance = NextInstance(pThisInstance)) {

                printf ("\n\t\"%ws\"",

                    (LPWSTR)((PBYTE)pThisInstance + pThisInstance->NameOffset));

            }

            printf ("\n");

        } else {

            printf (" which has only one occurance,");

        }

        // now display all counters described in this object

        printf ("\nand has the following counters:");

        for (dwThisCounter = 0, pThisCounter = FirstCounter (pThisObject);

            dwThisCounter < pThisObject->NumCounters;

            dwThisCounter++, pThisCounter = NextCounter(pThisCounter)) {

            printf ("\n    \"%ws\"",

                    pNames[pThisCounter->CounterNameTitleIndex]);

        }

    }

} // DisplayCounterData

int

_CRTAPI1 main(

    int argc,

    char *argv[]

)

/*++

main

    entry point to perfex

    This program illustrates how to:

        get performance counter names and explain text from the registry

        obtain counter object value strings for use in querying perf. data

        walk the performance data structures returned by the registry

    This program does not show how to:

        format or process the counter data returned

            the counter data returned by the registry depends on the

            counter type. This data must be processed and formatted by

            the application program.

Arguments

    argc

        # of command line arguments present

    argv

        array of pointers to command line strings

    (note that these are obtained from the GetCommandLine function in

    order to work with both UNICODE and ANSI strings.)

ReturnValue

    0 (ERROR_SUCCESS) if command was processed

    Non-Zero if command error was detected.

--*/

{

    LPTSTR  *lpCounterText; // array of counter name strings

    LPTSTR  lpCommandLine;  // pointer to command line string

    LPTSTR  lpValueString;  // value string to pass to registry for data

    DWORD   dwLastElement;  // number of elements in lpCounterText

    PPERF_DATA_BLOCK  pDataBlock; // pointer to perfdata block

    DWORD   dwStatus;       // return status of fn. calls

    DWORD   dwAction;       // display mode indicated by command line

    // query counter names from registry and load into table

    lpCounterText = BuildNameTable (

        HKEY_LOCAL_MACHINE,

        DefaultLangId,

        &dwLastElement);

    if (!lpCounterText) {

        printf ("ERROR: Unable to read counter names from registry.");

        return (TRUE);

    }

    lpCommandLine = GetCommandLine(); // get command line

    // read command line to determine what to do

    dwAction = ProcessCommandLine (lpCommandLine,

        lpCounterText,

        dwLastElement,

        &lpValueString);

    if (dwAction == COMMAND_ERROR) { // if unable to read command line

        DisplayCommandHelp();        // display command line usage

        free (lpCounterText);        // free buffer and return error

        return (TRUE);

    } else {

        // of command requires processing, then get perf data from reg.

        pDataBlock = NULL;

        dwStatus = GetSystemPerfData (

            HKEY_PERFORMANCE_DATA,

            lpValueString,

            &pDataBlock);

        if (dwStatus != ERROR_SUCCESS) {

            printf ("\nERROR: Unable to obtain data for that counter");

            free (lpCounterText);

            return (dwStatus);

        } else {

            // if data was returned, then display in format requested by

            // command line

            if (dwAction == COMMAND_HELP) {

                // display object names returned from registry

                DisplayObjectNames (pDataBlock, lpCounterText);

            } else {

                // display counter data for specified object

                DisplayCounterData (pDataBlock, lpCounterText);

            }

        }

        free (lpCounterText);

        return (ERROR_SUCCESS); // success

    }

}


Displaying Counter Title Indices

This section includes example code that displays counter-title indices and their names.

#define UNICODE 1

#define _UNICODE 1

#include <stdio.h>

#include <stdlib.h>

#include <assert.h>

#include <windows.h>

#include <string.h>

#include <memory.h>

#include <process.h>

#include <tchar.h>

#define SZ_DUMMY 10

int GetRegDataBound(HKEY hkey)

{

    TCHAR chDummy[SZ_DUMMY];

    DWORD cSubKeys;

    DWORD cbMaxSubkey;

    DWORD cbMaxClass;

    DWORD cValues;

    DWORD cbMaxValueName;

    DWORD cbMaxValueData;

    DWORD cbSecurityDescriptor;

    FILETIME ftLastWriteTime;

    DWORD lErr;

    DWORD cbClassSize = SZ_DUMMY;

    lErr = RegQueryInfoKey(hkey, chDummy, &cbClassSize,

        NULL, &cSubKeys, &cbMaxSubkey, &cbMaxClass,

        &cValues, &cbMaxValueName, &cbMaxValueData,

        &cbSecurityDescriptor, &ftLastWriteTime);

    if (lErr == ERROR_SUCCESS)

        return cbMaxValueData;

    else

        return -1;

}

int

_CRTAPI1 main(

)

{

    HKEY hKeyData;

    LONG lErr;

    LPTSTR lptstr;

    int   iSize;

    DWORD dwType;

    DWORD dwSize;

    int   iIndex;

    lErr = RegOpenKeyEx(HKEY_LOCAL_MACHINE,

        TEXT("Software\\Microsoft\\Windows NT\\CurrentVersion\\Perflib\\009"),

        0, KEY_ALL_ACCESS, &hKeyData);

    assert(lErr == ERROR_SUCCESS);

    iSize = GetRegDataBound(hKeyData);

    if (iSize == -1)

        exit(-1);

    iSize++;

    lptstr = malloc(iSize * sizeof(TCHAR));

    dwSize = iSize;

    lErr = RegQueryValueEx(hKeyData, TEXT("Counters"), 0, &dwType,

        (LPBYTE) lptstr, &dwSize);

    assert(lErr == ERROR_SUCCESS);

    while (*lptstr) {

        _stscanf (lptstr, TEXT(" %d"), &iIndex);

//        iIndex = atoi(lptstr);

        lptstr += lstrlen(lptstr) + 1;

        printf("#define CNTR_%.3d\t \"%ws\"\n", iIndex, lptstr);

        lptstr += lstrlen(lptstr) + 1;

    }

    lErr = RegCloseKey(hKeyData);

    assert(lErr == ERROR_SUCCESS);

    return 0;

}


Functions

Following are the functions used for performance monitoring.

RegConnectRegistry

RegQueryValueEx

QueryPerformanceCounter

QueryPerformanceFrequency


System Information Overview

About System Information

The Microsoft® Win32™ application programming interface (API) includes functions that describe the current system configuration. These functions retrieve a variety of data, such as the computer name, user name, settings of environment variables, processor type, system colors, and so on. It also includes functions that can change the system configuration, shut down the system, and start the Windows Help application.

The following topics discuss the Win32 system-information functions:

Terms

System Configuration

System Shutdown

Windows Help

Getting System Configuration Information

Getting Hardware Information

Changing the Color of a Window Element

Shutting Down the System

Starting Windows Help

Functions


System Configuration

Several of the functions in the Win32 API are specifically intended to describe or change the system configuration. At startup, for example, a computer is assigned the name listed in the registry. An application can retrieve this name by using the GetComputerName function and can change the name by using the SetComputerName function. SetComputerName changes the registry, not the current computer name. As a result, the new name is not assigned until the computer is restarted.

The GetUserName function retrieves the name of the user currently logged onto the system. The user name is either the logon name or the user's full name, if the latter is included in the registry.

The GetSystemInfo function retrieves processor and memory information, such as the page size, original equipment manufacturer (OEM) identifier, number and type of processors, application address range, and so on. The GetVersion function retrieves the major and minor revision numbers of the installed version of Microsoft® Windows™. The GetKeyboardType function retrieves such information as the type of keyboard and the number of function keys on the current keyboard.

The SystemParametersInfo function retrieves or sets various system attributes, such as double-click time, screen saver time-out, window border width, and desktop pattern. When an application uses SystemParametersInfo to set a parameter, the change takes place immediately. This function also enables applications to update the user profile so changes to the system will be preserved when the system is restarted.

The GetThreadDesktop function retrieves a handle of the desktop for a given thread. This handle can be used in calls to functions that retrieve and set security attributes.

The Windows directory is the directory that contains Windows-based applications, initialization files, and Help files. The GetWindowsDirectory function retrieves the path to this directory. Applications that create files should do so in the Windows directory. This is the only directory guaranteed to be private to a user running a shared version of Windows.

The system directory is the directory that contains Windows libraries, drivers, and font files. The GetSystemDirectory function retrieves the path to this directory.

An environment variable is a symbolic variable that represents some element of the system, such as a path, a filename, or other literal data. For example, the environment variable PATH represents the directories in which to search for executable files. When a user logs on, the system initializes environment variables based on the environment section of the registry. The ExpandEnvironmentStrings function retrieves the values of specified environment variables.

System metrics are the dimensions of various Windows display elements. (Display elements are the parts of a window and the Windows display that appear on the system display screen.) Typical system metrics include the window border width, icon height, and so on. System metrics also describe other aspects of the system, such as whether a mouse is installed, double-byte characters are supported, or a debugging version of Windows is installed. The GetSystemMetrics function retrieves a specified system metric.

Applications can also retrieve and set the color of window elements such as menus, scroll bars, and buttons by using the GetSysColor and SetSysColors functions, respectively.


System Shutdown

The Win32 API also provides a way for an application to shut down a local or remote computer. This is particularly useful for system administrators who update system software on remote computers. The InitiateSystemShutdown function starts a timer and displays a dialog box that prompts the user to log off. While the dialog box is displayed, the AbortSystemShutdown function can stop the timer and prevent the computer from shutting down. However, if the timer expires, the computer is shut down. InitiateSystemShutdown can also restart the computer following shutdown.


Windows Help

Applications can provide help to users by starting the Windows Help application. The WinHelp function opens the specified Help file to an appropriate context, if specified.


Getting System Configuration Information

The following example uses the GetComputerName, GetUserName, GetSystemDirectory, GetWindowsDirectory, and ExpandEnvironmentStrings functions to get information that describes the system configuration. This example displays the information in a window's client area.

LPTSTR lpszSystemInfo;    /* ptr. to system info. string */

DWORD cchBuff = 256;     /* size of comp. or user name   */

TCHAR tchBuffer2[BUFFER];   /* buffer for concat'd. str. */

DWORD dwResult;               /* function return value */

SYSTEM_INFO siSysInfo;     /* struct. for hardware info. */

int aTabs[1] = {260};    /* tab stop for TabbedTextOut */

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */

int nSize;                           /* size of string */

lpszSystemInfo = tchBuffer2;

/* Get and display the name of the computer. */

GetComputerName(lpszSystemInfo, &cchBuff);

nSize = sprintf(tchBuffer, "Computer name: %s",

    lpszSystemInfo);

TextOut(hdc, 15, 20, tchBuffer, nSize);

/* Get and display the user name. */

GetUserName(lpszSystemInfo, &cchBuff);

nSize = sprintf(tchBuffer, "User name: %s",

    lpszSystemInfo);

TextOut(hdc, 15, 40, tchBuffer, nSize);

/* Get and display the system directory. */

nSize = GetSystemDirectory(lpszSystemInfo, MAX_PATH);

nSize = sprintf(tchBuffer, "System directory: %s",

    lpszSystemInfo);

TextOut(hdc, 15, 60, tchBuffer, nSize);

/* Get and display the Windows directory. */

nSize = GetWindowsDirectory(lpszSystemInfo, MAX_PATH);

nSize = sprintf(tchBuffer, "Windows directory: %s",

    lpszSystemInfo);

TextOut(hdc, 15, 80, tchBuffer, nSize);

/* Display the "environment variables" header. */

nSize = sprintf(tchBuffer,

    "Environment variables (partial list):");

TextOut(hdc, 15, 105, tchBuffer, nSize);

/* Expand the OS and NTVERSION environment variables. */

dwResult = ExpandEnvironmentStrings(

               "OS=%OS%     NTVERSION=%NTVERSION%",

               lpszSystemInfo,

               BUFFER);

TextOut(hdc, 25, 120, (LPCTSTR) lpszSystemInfo,

    dwResult - 1);

/* Expand the PATH environment variable. */

dwResult = ExpandEnvironmentStrings(

               "PATH=%PATH%",

               lpszSystemInfo,

               BUFFER);

TextOut(hdc, 25, 135, (LPCTSTR) lpszSystemInfo,

    dwResult - 1);

/* Expand the LIBPATH environment variable. */

dwResult = ExpandEnvironmentStrings(

               "LIBPATH=%LIBPATH%",

               lpszSystemInfo,

               BUFFER);

TextOut(hdc, 25, 150, (LPCTSTR) lpszSystemInfo,

    dwResult - 1);

/* Expand the TMP environment variable. */

dwResult = ExpandEnvironmentStrings(

               "TMP=%TMP%",

               lpszSystemInfo,

               BUFFER);

TextOut(hdc, 25, 165, (LPCTSTR) lpszSystemInfo,

    dwResult - 1);

The next example uses the GetVersion function to obtain the current version of Windows and then displays the version number in a message box.

DWORD dwResult;               /* function return value */

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */

int nSize;                           /* size of string */

dwResult = GetVersion();

nSize = sprintf(tchBuffer, "Windows version %d.%d\n",

    LOBYTE(LOWORD(dwResult)),

    HIBYTE(LOWORD(dwResult)));

MessageBox(NULL, tchBuffer, "GetVersion", MB_ICONINFORMATION);


Getting Hardware Information

The following example uses the GetSystemInfo function to obtain hardware information such as the OEM identifier, processor type, page size, and so on. The example displays the information in a window's client area.

SYSTEM_INFO siSysInfo;     /* struct. for hardware info. */

int aTabs[1] = {260};    /* tab stop for TabbedTextOut */

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */

int nSize;                           /* size of string */

/* Display the "hardware information" header. */

nSize = sprintf(tchBuffer,

    "Hardware information:");

TextOut(hdc, 15, 20, tchBuffer, nSize);

/* Copy the hardware information to the SYSTEM_INFO structure. */

GetSystemInfo(&siSysInfo);

/* Display the contents of the SYSTEM_INFO structure. */

nSize = sprintf(tchBuffer,

    "OEM ID: %u\tNumber of Processors: %u",

    siSysInfo.dwOemId,

    siSysInfo.dwNumberOfProcessors);

TabbedTextOut(hdc, 25, 40, tchBuffer,

    nSize, 1, aTabs, 25);

nSize = sprintf(tchBuffer,

    "Page size: %u\tProcessor Type: %u",

    siSysInfo.dwPageSize,

    siSysInfo.dwProcessorType);

TabbedTextOut(hdc, 25, 60, tchBuffer,

    nSize, 1, aTabs, 25);

nSize = sprintf(tchBuffer,

    "Minimum app address: %lx\tMaximum app address: %lx",

    siSysInfo.lpMinimumApplicationAddress,

    siSysInfo.lpMaximumApplicationAddress);

TabbedTextOut(hdc, 25, 80, tchBuffer,

    nSize, 1, aTabs, 25);

nSize = sprintf(tchBuffer,

    "Active processor mask: %u",

    siSysInfo.dwActiveProcessorMask);

TextOut(hdc, 25, 100, tchBuffer, nSize);

The following example uses the GetSystemMetrics function to determine whether a mouse is installed and whether the mouse buttons are swapped. The example also uses the SystemParametersInfo function to retrieve the mouse threshold and speed. It displays the information in a message box.

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */

int nSize;                           /* size of string */

BOOL fResult;                  /* system shutdown flag */

int aMouseInfo[3];             /* array for mouse info. */

/* Is there a mouse? */

fResult = GetSystemMetrics(SM_MOUSEPRESENT);

if (fResult == 0) {

    /* Indicate if there is no mouse. */

    nSize = sprintf(tchBuffer, "No mouse installed.");

} else {

    /*

     * If there is a mouse, determine if

     * its buttons are swapped.

     */

    fResult = GetSystemMetrics(SM_SWAPBUTTON);

    if (fResult == 0) {

        nSize = sprintf(tchBuffer, "Buttons not swapped.\r");

    } else {

        nSize = sprintf(tchBuffer, "Buttons swapped.\r");

    }

    /* Get the mouse speed and the threshold values. */

    SystemParametersInfo(SPI_GETMOUSE, /* get mouse info. */

        NULL,                          /* not used          */

        &aMouseInfo,                   /* holds mouse info. */

        NULL);                         /* not used          */

    nSize += sprintf(tchBuffer + nSize,

        "Speed: %d\r", aMouseInfo[2]);

    sprintf(tchBuffer + nSize,

        "Threshold (x,y): %d,%d",

        aMouseInfo[0], aMouseInfo[1]);

}

/* Display the mouse information. */

MessageBox(NULL, tchBuffer, "Mouse information",

    MB_ICONINFORMATION);

This next example uses SystemParametersInfo to double the mouse speed and update the MouseSpeed value in the win.ini file.

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */

int nSize;                           /* size of string */

int aMouseInfo[3];             /* array for mouse info. */

/* Get the current mouse speed. */

SystemParametersInfo(SPI_GETMOUSE, /* get mouse info. */

    NULL,                          /* not used          */

    &aMouseInfo,                   /* holds mouse info. */

    NULL);                         /* not used          */

/* Double it. */

aMouseInfo[2] = 2 * aMouseInfo[2];

/* Change the mouse speed to the new value and update WIN.INI. */

SystemParametersInfo(SPI_SETMOUSE, /* set mouse info. */

    NULL,                          /* not used           */

    aMouseInfo,                    /* mouse info. to set */

    SPIF_UPDATEINIFILE);           /* update win.ini     */


Changing the Color of a Window Element

Changing the Colors of Window Elements

The following example uses the SetSysColors function to change the color of active window borders to dark purple, of active title bars to dark cyan, and of the window background to light gray.

                          /* window elements to change */

int aiElements[3] = {COLOR_ACTIVEBORDER,

                     COLOR_ACTIVECAPTION,

                     COLOR_WINDOW};

DWORD aColors[3];               /* array of RGB values */

/* Define the new colors. */

aColors[0] = RGB(0x80, 0x00, 0x80);  /* dark purple */

aColors[1] = RGB(0x00, 0x80, 0x80);  /* dark cyan   */

aColors[2] = RGB(0xC0, 0xC0, 0xC0);  /* light gray  */

/*

 * Set the window elements in aiElements to the colors

 * specified in aColors.

 */

SetSysColors(3, aiElements, aColors);

The next example uses the GetSysColor function to retrieve the color of the window background and displays the red, green, blue (RGB) value, in hexadecimal notation, in a message box.

DWORD dwResult;               /* function return value */

TCHAR tchBuffer[BUFFER]; /* buffer for expanded string */

int nSize;                           /* size of string */

/* Get the color of the window background. */

dwResult = GetSysColor(COLOR_WINDOW);

nSize = sprintf(tchBuffer,

    "Window color: {%x, %x, %x}",

    GetRValue(dwResult),

    GetGValue(dwResult),

    GetBValue(dwResult));

MessageBox(NULL, tchBuffer, "GetSysColor", MB_ICONINFORMATION);


Shutting Down the System

The following example uses the InitiateSystemShutdown function to begin the system shutdown process on the local computer. Note that the application must first enable the SE_SHUTDOWN_NAME privilege to shut down the computer the user is logged onto.

HANDLE hToken;              /* handle to process token */

TOKEN_PRIVILEGES tkp;        /* ptr. to token structure */

BOOL fResult;                  /* system shutdown flag */

/*

 * Get the current process token handle

 * so we can get shutdown privilege.

 */

if (!OpenProcessToken(GetCurrentProcess(),

        TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, &hToken))

    ErrorHandler("OpenProcessToken failed.");

/* Get the LUID for shutdown privilege. */

LookupPrivilegeValue(NULL, SE_SHUTDOWN_NAME,

        &tkp.Privileges[0].Luid);

tkp.PrivilegeCount = 1;  /* one privilege to set    */

tkp.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;

/* Get shutdown privilege for this process. */

AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,

    (PTOKEN_PRIVILEGES) NULL, 0);

/* Cannot test the return value of AdjustTokenPrivileges. */

if (GetLastError() != ERROR_SUCCESS)

    ErrorHandler("AdjustTokenPrivileges enable failed.");

/* Display the shutdown dialog box and start the time-out countdown. */

fResult = InitiateSystemShutdown(

    NULL,            /* shut down local computer */

    "Click on the main window and press \

     the Escape key to cancel shutdown.",

                                 /* msg. to user */

    20,                       /* time-out period */

    FALSE,         /* prompt user to close apps. */

    TRUE);             /* reboot after shutdown  */

if (!fResult) {

    ErrorHandler("InitiateSystemShutdown failed.");

}

/* Disable shutdown privilege. */

tkp.Privileges[0].Attributes = 0;

AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,

        (PTOKEN_PRIVILEGES) NULL, 0);

if (GetLastError() != ERROR_SUCCESS)

    ErrorHandler("AdjustTokenPrivileges disable failed.");

If the AbortSystemShutdown function is executed in the time-out period specified by InitiateSystemShutdown, the system does not shut down. The following example enables the user to prevent the system from shutting down by clicking on the application's main window and pressing the esc key. As noted earlier, your application must enable the SE_SHUTDOWN_NAME privilege to stop the system shutdown.

HANDLE hToken;              /* handle to process token */

TOKEN_PRIVILEGES tkp;        /* ptr. to token structure */

BOOL fResult;                  /* system shutdown flag */

case WM_KEYDOWN:

    /* Process only the Escape key. */

    if (wParam != VK_ESCAPE) {

        break;

    }

    /*

     * Get the current process token handle

     * so we can get shutdown privilege.

     */

    if (!OpenProcessToken(GetCurrentProcess(),

            TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, &hToken))

        ErrorHandler("OpenProcessToken failed.");

    /* Get the LUID for shutdown privilege. */

    LookupPrivilegeValue(NULL, SE_SHUTDOWN_NAME,

            &tkp.Privileges[0].Luid);

    tkp.PrivilegeCount = 1;  /* one privilege to set    */

    tkp.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;

    /* Get shutdown privilege for this process. */

    AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,

        (PTOKEN_PRIVILEGES)NULL, 0);

    /* Cannot test the return value of AdjustTokenPrivileges. */

    if (GetLastError() != ERROR_SUCCESS)

        ErrorHandler("AdjustTokenPrivileges enable failed.");

    /* Prevent the system from shutting down. */

    fResult = AbortSystemShutdown(NULL);

    if (!fResult) {

        ErrorHandler("AbortSystemShutdown failed.");

    }

    /* Disable shutdown privilege. */

    tkp.Privileges[0].Attributes = 0;

    AdjustTokenPrivileges(hToken, FALSE, &tkp, 0,

        (PTOKEN_PRIVILEGES) NULL, 0);

    if (GetLastError() != ERROR_SUCCESS)

        ErrorHandler("AdjustTokenPrivileges disable failed.");

    break;


Starting Windows Help

The following example uses the WinHelp function to start the Windows Help application, open the Win32 API Help file, and display the Help file index.

HWND            hwnd;           /* main window handle         */

/* Start Windows Help; display index of Win32 API Help file. */

WinHelp(hwnd, "api32wh.hlp", HELP_INDEX, NULL);

This next example opens the Win32 API Help file, searches the file for the "menus" topic, and displays the topic.

HWND            hwnd;           /* main window handle         */

/* Start Windows Help; display menus topic of Win32 API Help. */

WinHelp(hwnd, "api32wh.hlp", HELP_KEY, (DWORD) "menus");


Functions

Following are the functions used to retrieve or set system information, shut down the system, or start Windows Help.

AbortSystemShutdown

ExpandEnvironmentStrings

GetComputerName

GetKeyboardType

GetSysColor

GetSystemDirectory

GetSystemInfo

GetSystemMetrics

GetThreadDesktop

GetUserName

GetVersion

GetWindowsDirectory

InitiateSystemShutdown

SetComputerName

SetSysColors

SystemParametersInfo

WinHelp

DOS3Call (Obsolete)

GetCurrentPDB (Obsolete)

GetCurrentTask (Obsolete)

GetDOSEnvironment (Obsolete)

GetSystemDir (Obsolete)

GetWindowsDir (Obsolete)

GetWinFlags (Obsolete)

IsTask (Obsolete)


Communications Overview

About Communications

A communications resource is 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.

The file input and output (I/O) functions (CreateFile, CloseHandle, ReadFile, ReadFileEx, WriteFile, and WriteFileEx) provide the basic interface for opening and closing a communications resource handle and for read and write operations. The Win32 application programming interface (API) also includes a set of communications functions that provide access to communications resources. This topic describes the use of file I/O and communications functions, which enable applications to perform the following tasks:

Open a handle to a specified communications resource.

Set and query the configuration of a serial communications resource.

Read from or write to a serial communications resource.

Monitor a specified set of events that might occur for a given serial communications resource.

Send a control command to the device driver associated with a specified communications resource, causing the driver to execute an extended function.

The following topics discuss the Win32 communications functions:

Terms

Communications Resource Handles

Communications Resource Configuration

I/O Operations

Communications Events

Control Functions

Configuring a Communications Resource

Monitoring Communications Events

Functions


Communications Resource Handles

A process uses the CreateFile function to open a handle to a communications resource. For example, specifying COM1 opens a handle to a serial port, and LPT1 opens a handle to a parallel port. If the specified resource is currently being used by another process, CreateFile fails. Any thread of the process can use the handle returned by CreateFile to identify the resource in any of the functions that access the resource.

When using CreateFile to open a handle directly to a device, an application must use the special characters "\." to identify the device. For example, to open a handle to drive A, specify "\.a:" for the lpszName parameter of CreateFile. The calling process can use the handle in the DeviceIoControl function to send control codes to the device.

When the process calls CreateFile to open a communications resource, it specifies the following attributes:

The type of read-write access to the specified resource.

Whether the handle can be inherited by child processes.

Whether the handle can be used in overlapped (asynchronous) I/O operations.

When the process uses CreateFile to open a communications resource, it must specify certain values for the following parameters:

The fdwShareMode parameter must be zero, opening the resource for exclusive access.

The fdwCreate parameter must specify the OPEN_EXISTING flag.

The hTemplateFile parameter must be NULL.


Communications Resource Configuration

Serial Communications Resource Configuration

When the CreateFile function opens a handle to a serial communications resource, the system initializes and configures the resource according to the values set up the last time the resource was opened. Preserving the previous settings enables the user to retain the settings specified through an MS-DOS MODE command when the device is reopened. The values inherited from the previous open operation include the configuration settings of the device control block (a DCB structure) and the timeout values used in I/O operations. If the device has never been opened, it is configured with the system defaults.

To determine the initial configuration of a serial communications resource, a process calls the GetCommState function, which fills in a serial port DCB structure with the current configuration settings. To modify this configuration, a process specifies a DCB structure in a call to the SetCommState function.

Members of the DCB structure specify the configuration settings such as the baud rate, the number of data bits per byte, and the number of stop bits per byte. Other DCB members specify special characters and enable parity checking and flow control. When a process needs to modify only a few of these configuration settings, it should first call GetCommState to fill in a DCB structure with the current configuration. Then the process can adjust the important values in the DCB structure and reconfigure the device by calling SetCommState and specifying the modified DCB structure. This procedure ensures that the unmodified members of the DCB structure contain appropriate values. For example, a common error occurs when a device is configured with a DCB structure in which the structure's XonChar member is equal to the XoffChar member. Some members of the DCB structure are different from those in previous versions of Windows. In particular, the flags for controlling RTS (request-to-send) and DTR (data-terminal-ready) flow control have changed.

The BuildCommDCB function provides another way to modify a DCB structure. BuildCommDCB uses a string with the same form as the MS-DOS MODE command-line arguments to specify the baud rate, parity scheme, number of stop bits, and number of character bits. The remaining members of DCB are not changed by this function, except that the appropriate members are set to disable XON/XOFF and hardware flow control. BuildCommDCB only modifies a DCB structure; it does not reconfigure the device.

A process can reconfigure a communications resource by using the GetCommProperties function to get information from a device driver about the configuration settings that it supports. The process can use this information to avoid specifying a configuration that is not supported.

The SetCommState function reconfigures the communications resource, but it does not affect the internal output and input buffers of the specified driver. The buffers are not flushed, and pending read and write operations are not terminated prematurely.

A process reinitializes a communications resource by using the SetupComm function, which performs the following tasks:

Terminates pending read and write operations, even if they have not been completed.

Discards unread characters and frees the internal output and input buffers of the driver associated with the specified resource.

Reallocates the internal output and input buffers.

A process is not required to call SetupComm. If it does not, the resource's driver initializes the device with the default settings the first time that the communications resource handle is used.


Read and Write Operations

The Win32 API supports both synchronous and asynchronous (overlapped) file I/O operations on serial communications resources. Overlapped operations enable the calling thread to perform other tasks while the operation executes in the background. A thread uses the ReadFile or ReadFileEx function to read from a communications resource, and the WriteFile or WriteFileEx function to write to a communications resource. ReadFile and WriteFile can be performed synchronously or asynchronously. ReadFileEx and WriteFileEx can only be performed asynchronously.

The behavior of these read and write functions is affected by whether the function is invoked as an overlapped operation; whether the timeout parameters are associated with the handle; and whether flow control parameters are associated with the handle.

A thread can also write to a communications resource by using the TransmitCommChar function, which transmits a specified character ahead of any pending data in the output buffer. This is useful in transmitting a high priority signal character to the receiving system. Transmission of the high priority character is still subject to flow control and write timeouts, and the operation is performed synchronously.

A thread can use the PurgeComm function to discard all characters in a device's output or input buffer. PurgeComm can also terminate pending read or write operations, even if the operations have not been completed. 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, a thread can call the FlushFileBuffers function (a synchronous operation). Note, however, that FlushFileBuffers is subject to flow control but not to write timeouts, and it will not return until all pending write operations have been transmitted.

Overlapped Operations

Overlapped operations enable a thread to execute a time-consuming I/O operation in the background, leaving the thread free to perform other tasks. To enable overlapped I/O operations on a communications resource, the thread must specify the FILE_FLAG_OVERLAPPED flag in the CreateFile function when the handle is opened. To invoke the ReadFile or WriteFile function as an overlapped operation, the calling thread must specify a pointer to an OVERLAPPED structure. If the function's OVERLAPPED pointer is NULL, the operation is performed synchronously, even though the handle was created with FILE_FLAG_OVERLAPPED enabled. The OVERLAPPED structure must contain a handle to a manual-reset (not an auto-reset) event object. The system sets the state of the event object to not-signaled when a call to the I/O function returns before the operation has been completed. The system sets the state of the event object to signaled when the operation has been completed. The thread uses wait function to check the current state of the event object or to wait for its state to be signaled.

The ReadFileEx and WriteFileEx functions can be performed only as overlapped operations. The calling thread specifies a pointer to the FileIOCompletionRoutine function, which is executed when the overlapped operation is completed. The completion routine is executed only if the calling thread performs an alertable operation.

Timeouts

A handle to a communications resource has an associated set of timeout parameters that affect the behavior of read and write operations. Timeouts can cause a ReadFile, ReadFileEx, WriteFile, or WriteFileEx operation to conclude when a timeout interval elapses, even though the specified number of characters have not been read or written. It is not treated as an error when a timeout occurs during a read or write operation (that is, the read or write function's return value indicates success). The count of bytes actually read or written is reported by ReadFile or WriteFile (or by the GetOverlappedResult or FileIOCompletionRoutine function, if the I/O was performed as an overlapped operation).

When a communications resource is opened, the timeout values are set according to the values set when the resource was last opened. If the resource has never been opened or if the SetupComm function is called, all timeout parameters are set to zero. To determine the current timeout values, an application can call the GetCommTimeouts function. To change the timeout values, an application can call the SetCommTimeouts function.

Two types of timeouts are enabled by the timeout parameters. An interval timeout occurs when the time between the receipt of any two characters exceeds a specified number of milliseconds. Timing starts when the first character is received and is restarted when each new character is received. A total timeout occurs when the total amount of time consumed by a read operation exceeds a calculated number of milliseconds. Timing starts immediately when the I/O operation begins. Write operations support only total timeouts. Read operations support both interval and total timeouts, which can be used separately or combined.

The size, in milliseconds, of the total timeout period for a read or write operation is calculated by using the multiplier and constant values from the COMMTIMEOUTS structure specified in the GetCommTimeouts or SetCommTimeouts function. The following formula is used:

Timeout = (MULTIPLIER * number_of_bytes) + CONSTANT

Using both a multiplier and a constant enables the total timeout period to vary, depending on the amount of data being requested. An application can use only the constant by setting the multiplier to zero, or use only the multiplier by setting the constant to zero. If both the constant and multiplier are zero, the total timeout is not used.

If all read timeout parameters are zero, read timeouts are not used, and a read operation is not complete until the requested number of bytes have been read or an error occurs. Similarly, if all write timeout parameters are zero, a write operation is not completed until the requested number of bytes have been written or an error occurs.

If the read interval timeout parameter is the value MAXDWORD and both read total timeout parameters are zero, read operations are completed immediately after reading whatever characters are available in the input buffer, even if it is empty. This is the same as the ReadComm function in previous versions of Windows.

Interval timing forces a read operation to return when there is a lull in reception. A process using interval timeouts can set a fairly short interval parameter, so it can respond quickly to small, isolated bursts of one or a few characters, yet it can still collect large buffers of characters with a single call when data is received in a steady stream.

Timeouts for a write operation can be useful when transmission is blocked by some kind of flow control or when the SetCommBreak function has been called to suspend character transmission.

The following table summarizes the behavior of read operations based on the values specified for interval or total timeouts.

Total	Interval	Behavior

0	0	Returns when the buffer is completely filled. The timeouts are not used.

T	0	Returns when the buffer is completely filled or when T milliseconds have elapsed since the beginning of the operation.

0	Y	Returns when the buffer is completely filled or when Y milliseconds have elapsed between the receipt of any two characters. Timing does not begin until the first character is received.

T	Y	Returns when the buffer is completely filled or when either timeout occurs.

Note, however, that timing is relative to the system controlling the physical device. For a remote device such as a modem, the timing is relative to the server system to which the modem is attached. Any network propagation delay is not factored in. For example, a client application might specify a total timeout that computes to be 500 milliseconds. When 500 milliseconds has elapsed at the server, a timeout error is returned to the client. If there is a 50 milliseconds network propagation delay, the client will not be notified of timeout until approximately 50 milliseconds after the timeout actually occurred.

The timeout parameters affect the behavior of overlapped read and write operations on a communications device. With overlapped I/O, the ReadFile, WriteFile, ReadFileEx, or WriteFileEx function can return before the operation has been completed. The timeout parameters can determine when the operation has been completed.

Communications Errors

There are other circumstances where a read or write operation can be completed with fewer than the requested number of characters, even though a timeout has not occurred. Following are some examples:

Some drivers support the use of special characters, which when received, complete a read operation immediately with only the characters that have been read to that point.

The PurgeComm function can be invoked to prematurely terminate pending read or write operations. This function can also delete the contents of the output or input buffers, or both.

If a communications error occurs during a read or write operation, all I/O operations on the communications resource are terminated. Break conditions, parity errors, or framing errors are examples of such errors. When an error occurs, the process must call the ClearCommError function to clear the error flag before it can begin additional I/O operations. ClearCommError reports the specific error that occurred and the current status of the device.


Communications Events

A process can monitor a set of events that occur in a communications resource. For example, an application can use event monitoring to determine when the CTS (clear-to-send) and DSR (data-set-ready) signals change state.

A process can monitor events on a given communications resource by using the SetCommMask function to create an event mask. To determine the current event mask for a communications resource, a process can use the GetCommMask function. The following table lists the events that can be monitored.

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

After a set of events is specified, a process uses the WaitCommEvent function to wait for one of the events to occur. WaitCommEvent can be used synchronously or as an overlapped operation. For additional information about executing a function as an overlapped operation, see Read and Write Operations.

When one of the events specified in the event mask occurs, the process completes the wait operation and sets an event mask variable is set to indicate the type of event detected. If the process calls SetCommMask is called for a communications resource while a wait is pending for that resource, WaitCommEvent returns an error.

Note that WaitCommEvent detects only events that occur after the wait was started. For example, if the EV_RXCHAR event is specified, the conditions of the wait are satisfied when any character is received and placed in the driver's input buffer. Characters already in the input buffer when WaitCommEvent is called do not satisfy the conditions of the wait.

When monitoring an event that occurs when a signal (CTS, DSR, and so on) changes state, WaitCommEvent reports the change, but not the current state. To query the current state of the CTS (clear-to-send), DSR (data-set-ready), RLSD (receive-line-signal-detect), and ring indicator signals, a process can use the GetCommModemStatus function.


Extended Functions

Some communications functions can be invoked for a device by using the EscapeCommFunction function. This function sends a code to direct the device to execute an extended function. For example, an application can suspend character transmission with the SETBREAK code and resume transmission with the CLRBREAK code. These particular operations can also be started by calling the SetCommBreak and ClearCommBreak functions. EscapeCommFunction can also be used to implement manual modem control. For example, the CLRDTR and SETDTR codes can be used to implement manual DTR (data-terminal-ready) flow control. Note, however, that an error occurs if a process uses EscapeCommFunction to manipulate the DTR line when the device has been configured to enable DTR handshaking, or the RTS (request-to-send) line if RTS handshaking is enabled.

The DeviceIoControl function enables a process to send an extended function code directly to a specified device driver, causing the device to perform a given operation. DeviceIoControl provides an interface to a device associated with a communications resource that has functionality not supported by the standard serial communications functions. It enables an application to configure a device using parameters unique to that device as well as to invoke any device-specific functions.


Configuring a Communications Resource

The following example opens a handle to COM1 and fills in a DCB structure with the current configuration. The DCB structure is then modified and used to reconfigure the device.

DCB dcb;

HANDLE hCom;

DWORD dwError;

BOOL fSuccess;

hCom = CreateFile("COM1",

    GENERIC_READ | GENERIC_WRITE,

    0,    /* comm devices must be opened with exclusive access */

    NULL, /* no security attrs */

    OPEN_EXISTING, // comm devices must use OPEN_EXISTING

    0,    /* not overlapped I/O */

    NULL  /* hTemplate must be NULL for comm devices */

    );

if (hCom == INVALID_HANDLE_VALUE) {

    dwError = GetLastError();

    /* handle error */

}

/*

 * Omit the call to SetupComm to use the default queue sizes.

 * Get the current configuration.

 */

fSuccess = GetCommState(hCom, &dcb);

if (!fSuccess) {

    /* handle error *

}

/* Fill in the DCB: baud=9600, 8 data bits, no parity, 1 stop bit */

dcb.BaudRate = 9600;

dcb.ByteSize = 8;

dcb.Parity = NOPARITY;

dcb.StopBits = ONESTOPBIT;

fSuccess = SetCommState(hCom, &dcb);

if (!fSuccess) {

    /* handle error */

}


Monitoring Communications Events

The following example code opens the serial port for overlapped I/O, creates an event mask to monitor CTS and DSR signals, and then waits for an event to occur. The WaitCommEvent function should be expected as an overlapped operation so the other threads of the process cannot perform I/O operations during the wait.

HANDLE hCom;

OVERLAPPED o;

BOOL fSuccess;

DWORD dwEvtMask;

hCom = CreateFile("COM1",

    GENERIC_READ | GENERIC_WRITE,

    0, /* exclusive access */

    NULL, /* no security attrs */

    OPEN_EXISTING,

    FILE_FLAG_OVERLAPPED,

    NULL

    );

if (hCom == INVALID_HANDLE_VALUE) {

    /* Deal with the error. */

}

/* Set the event mask. */

fSuccess = SetCommMask(hCom, EV_CTS | EV_DSR);

if (!fSuccess) {

    /* deal with error */

}

/* Create an event object for use in WaitCommEvent. */

o.hEvent = CreateEvent(NULL, /* no security attributes */

    FALSE, /* auto reset event */

    FALSE, /* not signalled */

    NULL /* no name */

    );

assert(o.hEvent);

if (WaitCommEvent(hCom, &dwEvtMask, &o)) {

    if (dwEvtMask & EV_DSR) {

        /*

         * . . .

         */

    }

    if (dwEvtMask & EV_CTS) {

        /*

         * . . .

         */

    }

}


Functions

Following are the functions used with communications devices.

BuildCommDCB

BuildCommDCBAndTimeouts

ClearCommBreak

ClearCommError

DeviceIoControl

EscapeCommFunction

GetCommMask

GetCommModemStatus

GetCommProperties

GetCommState

GetCommTimeouts

PurgeComm

SetCommBreak

SetCommMask

SetCommState

SetCommTimeouts

SetupComm

TransmitCommChar

WaitCommEvent


Introduction to Multimedia Services Overview

Introduction to Multimedia Services

The following topics discuss Win32 Multimedia Services:

About Windows Multimedia Services

Architecture of Windows Multimedia Services

Windows Multimedia Design Philosophy

Building a Multimedia Application


About Windows Multimedia Services

Microsoft® Windows™ provides developers with high-level and low-level services for developing multimedia applications that use the extended capabilities of a multimedia personal computer.

Windows provides the following multimedia services:

A Media Control Interface (MCI) for controlling media devices.

Extensible string-based and message-based interfaces for communicating with MCI device drivers.

MCI device drivers for playing and recording waveform audio, playing Musical Instrument Digital Interface (MIDI) files, and playing compact disc audio from a CD-ROM drive.

Low-level application programming interface (API) support for multimedia-related services.

Low-level support for playing and recording audio with waveform and MIDI audio devices.

Low-level support for precision timer services.

Multimedia file input and output (I/O) services that provide buffered and unbuffered file I/O and support for standard Resource Interchange File Format (RIFF) files. The services are extensible by means of custom I/O procedures.

A MIDI Mapper supporting standard MIDI patch services. This allows MIDI files to be authored independently of users' MIDI synthesizer setups.

Control Panel options that let users change display drivers, set up a screen saver, install multimedia device drivers, assign waveform sounds to system alerts, and configure the MIDI Mapper.

This topic covers the following topics:

The software architecture of the multimedia services

The design philosophy and implementation of the multimedia services

Basic information about developing applications that use the multimedia services


Architecture of Windows Multimedia Services

Although the multimedia services are provided by a number of files, the overall architecture can be viewed as consisting of just three software modules:

The WINMM library, which provides the MCI services and low-level multimedia support functions

Multimedia device drivers, which provide communication between the low-level WINMM functions and multimedia devices, such as waveform, MIDI, and timer hardware

Drivers for MCI, which provide high-level control of media devices


Windows Multimedia Design Philosophy

The architecture of the multimedia services is designed around the concepts of extensibility and device independence. Extensibility allows the software architecture to accommodate advances in technology easily, without changes to the architecture itself. Device independence makes it easy to develop multimedia applications that will run on a wide range of hardware providing different levels of multimedia support. Three design elements of the system software provide extensibility and device independence:

A translation layer (WINMM) that isolates applications from device drivers and centralizes device-independent code

Run-time linking that allows the translation layer to link to the drivers it needs

A well-defined and consistent driver interface that minimizes special-case code and makes the installation and upgrade process easier


Building a Multimedia Application

Before writing a multimedia application, you should be familiar with programming in the Windows environment.

When using the multimedia services, you must include the MMSYSTEM.H header file in all source-code files that call multimedia functions. This header file depends on declarations made in the WINDOWS.H header file, so you must first include WINDOWS.H. The MMSYSTEM.H header file provides function prototypes as well as definitions of multimedia data types and constants.

In addition to linking the normal Windows libraries, you must also link to the WINMM.LIB import library when linking an application that uses multimedia functions.


Media Control Interface Overview

About the Media Control Interface

The Media Control Interface (MCI) provides applications written for Microsoft® Windows™ with device-independent capabilities for controlling media devices such as audio hardware, videodisc players, and animation players. This topic presents an introduction to MCI and shows how to begin using it in Windows-based applications.

MCI provides a device-independent, extensible interface for controlling virtually any type of media device. Because of the high level of device independence provided by MCI, you are encouraged to use MCI rather than low-level functions to access the multimedia capabilities of Windows.

The following topics discuss the Media Control Interface:

The Architecture of MCI

The MCI Programming Interfaces

The MCI Command Set

About MCI Devices

Opening MCI Devices

About Command Messages

Summary of MCI Command Messages

Sending Command Messages

Opening a Device

Closing a Device

Using the Wait and Notify Flags

Obtaining MCI System Information

About the Command-String Interface

Sending Command Strings Using MciSendString

Additional Information About Command Strings

For more information about using MCI to control different types of audio devices, see High-Level Audio.


The Architecture of MCI

To provide extensibility, MCI is designed around an architecture that uses special MCI device drivers to interpret and execute MCI commands.

MCI device drivers can control media hardware directly or through the low-level multimedia functions provided by Windows. Most commonly used devices, such as waveform audio and Musical Instrument Digital Interface (MIDI) devices, are controlled through the low-level multimedia functions.


The MCI Programming Interfaces

MCI provides two programming interfaces: command string and command message.

The Command-String Interface

The command-string interface allows you to use English-language commands to communicate with MCI devices. For example, the following command string plays a WAVE file named TIMPANI.WAV.

play timpani.wav

The command-string interface is designed for use with high-level programming and authoring environments such as Microsoft® Visual Basic™ and Asymetrix® ToolBook®. Use the command-string interface for applications that provide a text-based interface to let users control MCI devices.

The Command-Message Interface

The command-message interface uses a message-passing paradigm to communicate with MCI devices. The following example performs the same operation as the previous command-string example.

WORD wDeviceID;

MCI_PLAY_PARMS mciPlayParms;

mciSendCommand(wDeviceID,            /* device identifier */

    MCI_PLAY,                        /* command message   */

    0,                               /* flags             */

    (DWORD) (LPVOID) &mciPlayParms); /* structure         */

The command-message interface is designed to be used by applications requiring a C-language interface to control multimedia devices. Use the command-message interface for applications that directly control multimedia devices.


The MCI Command Set

The MCI command set provides a generic core set of commands to control different types of media devices. For example, MCI uses the same command to begin playback of a waveform audio file, a videodisc track, and an animation sequence. Some devices have unique capabilities, such as the capability of an animation player to use a frame-based time format. For such devices, MCI provides extended commands that are unique to a particular type of device.

The commands in the command-string interface provide a good overview of the MCI command set. Each of these commands is represented by a similar command message in the command-message interface. For example, the close command string is the equivalent of the MCI_CLOSE command message.

Following are some commonly used commands.

Command	Description

capability	Requests information about the capabilities of a device.

close	Closes a device after it has been used.

info	Requests information about a device (for example, a description of the hardware associated with the device).

open	Opens and initializes a device.

pause	Pauses playing or recording on a device.

play	Begins playing on a device.

record	Begins recording on a device.

resume	Resumes playing or recording on a paused device.

seek	Changes the current position in the media.

set	Changes control settings, such as the time format the device is using.

status	Requests information about the status of a device (for example, whether the device is playing or paused).

stop	Stops playing or recording on a device.


About MCI Devices

MCI device drivers can be classified as either simple devices or compound devices. Simple devices do not require a data file for playback. Videodisc players and compact disc (CD) audio players are examples of simple devices. Compound devices require a data file for playback. MIDI sequencers and waveform audio players are examples of compound devices. The data file associated with a compound device is known as a device element. Examples of device elements are MIDI files and WAVE files.

Standard MCI Device Types

A device type identifies a class of MCI devices that responds to a common set of commands. Following are the currently defined device types.

Device type	Description

animation	Animation device

cdaudio	CD audio player

dat	Digital audio tape player

digitalvideo	Digital video in a window (not based on graphics device interface)

other	Undefined MCI device

overlay	Overlay device (analog video in a window)

scanner	Image scanner

sequencer	MIDI sequencer

videodisc	Videodisc player

waveaudio	Audio device that plays digitized waveform files

Device Names

For any given device type, there might be several MCI drivers that share the command set but operate on different data formats. For example, for animation devices there are several MCI drivers that use the same command set but use different file formats. To uniquely identify an MCI driver, MCI uses device names.

Device names are identified in the [mci32] section of the registry. This section identifies all MCI device drivers to Windows. The following is part of a typical [mci] section.

[mci32]

WaveAudio=mciwave.dll

Sequencer=mciseq.dll

AVIVideo=mciavi.dll

CDAudio=mcicda.dll

The key name (on the left side of the equal sign) is the device name. The value corresponding to the key name (on the right side of the equal sign) identifies the filename of the MCI driver. The device name is often the same as the device type for the driver, as is the case for the WaveAudio, Sequencer, and CDAudio devices in the preceding example. The AVIVideo device is a digital video device, but it uses a unique device name.

If an MCI driver is installed using a device name that already exists in the [mci32] section, Windows appends an integer to the device name of the new driver, creating a unique device name. In the preceding example, a driver installed using the cdaudio device name would be assigned device name cdaudio1. A subsequent cdaudio device would be assigned device name cdaudio2.


Opening MCI Devices

Before using an MCI device, you must initialize it by opening it. Opening a device loads its driver into memory (if it isn't already loaded) and establishes a device identifier to identify the device in subsequent commands. (The device identifier is not used in the command-string interface.) There are several ways to specify the device you want to open:

With simple devices, you can open the device by specifying the device name.

With compound devices, you can open the device by specifying the device name, the device element, or both.

For example, the following command string opens a CD audio device (a simple device) by specifying the device name.

open cdaudio

The next command string opens a waveform audio device (a compound device) by specifying the device name and a device element.

open bells.wav type waveaudio

You can also open a compound device by specifying only the device element, as shown in the following example.

open bells.wav

If you specify only a device element when opening a compound device, MCI uses the filename extension of the device element filename to determine which device to open. The registry contains an [mci extensions] section that associates filename extensions and corresponding MCI device types. The following is part of an [mci extensions] section.

[mci extensions]

Wav=WaveAudio

Mid=Sequencer

rmi=Sequencer

avi=avivideo


About Command Messages

MCI command messages consist of the following three elements:

A constant message value

A structure (parameter block) specifying additional parameters for the command

A set of flags specifying options for the command and validating members in the structure

Commands are sent by using the mciSendCommand function, which has parameters for the message, flags, and a pointer to the structure. For more information about the mciSendCommand function, see Sending Command Messages.

Command-Message Example

For an example of an MCI command message, consider MCI_PLAY. The MMSYSTEM.H header file defines the MCI_PLAY command message, the MCI_NOTIFY, MCI_WAIT, MCI_FROM, and MCI_TO flags, and the MCI_PLAY_PARMS structure. The MCI_PLAY_PARMS structure has the following form.

typedef struct {

    DWORD   dwCallback;

    DWORD   dwFrom;

    DWORD   dwTo;

} MCI_PLAY_PARMS;

The MCI_WAIT and MCI_NOTIFY flags are option flags. MCI_WAIT tells the driver to wait until the command is complete before returning control to the application. MCI_NOTIFY tells the driver to notify the application when the command is complete. For more information on using these flags, see Using the Wait and Notify Flags.

The MCI_FROM and MCI_TO flags validate the dwFrom and dwTo members in the MCI_PLAY_PARMS structure. These members specify beginning and ending positions for the play operation. Both flags are optional. If either flag is specified, the driver takes the value from the corresponding member in the structure as a beginning or ending position; otherwise, the members are ignored.

Note:	Members in a structure are ignored unless corresponding flags are specified to validate the members.

Items in Query Commands

Two command messages that query devices for information, MCI_GETDEVCAPS and MCI_STATUS, extend the command-message paradigm by adding a dwItem member to the structure and defining item constants for the member. Item constants specify which item of information is being requested. For example, MMSYSTEM.H defines the MCI_STATUS_PARMS structure for the MCI_STATUS command message as follows.

typedef struct {

    DWORD   dwCallback;

    DWORD   dwReturn;

    DWORD   dwItem;

    DWORD   dwTrack;

} MCI_STATUS_PARMS;

If you use the MCI_STATUS_ITEM flag to validate the dwItem member, make sure that dwItem contains a constant defined by MMSYSTEM.H to indicate the exact status information requested. The MCI_STATUS command message uses the following constants for dwItem:

MCI_STATUS_CURRENT_TRACK

MCI_STATUS_LENGTH

MCI_STATUS_MEDIA_PRESENT

MCI_STATUS_MODE

MCI_STATUS_NUMBER_OF_TRACKS

MCI_STATUS_POSITION

MCI_STATUS_READY

MCI_STATUS_TIME_FORMAT


Summary of MCI Command Messages

MCI defines four classifications of command messages. The command messages and options in the following two classifications are defined as the minimum command set for any MCI driver:

System command messages are handled directly by MCI rather than by the driver.

Required command messages are handled by the driver. All drivers should support the required command messages and options.

Regardless of the specific driver you use, you should be able to assume that the command messages and options in the two preceding groups are available.

The command messages in the following two classifications are not supported by all drivers:

Basic (or optional) command messages are used by some devices. If a device supports a basic command message, it must support a defined set of options for the command message.

Extended command messages are specific to certain device types or drivers. They include new command messages (for example, the MCI_PUT and MCI_WHERE command messages for the animation device type) and extensions to existing command messages (for example, the MCI_ANIM_GETDEVCAPS_CAN_STRETCH option added to the MCI_STATUS command message for the animation device type).

If you need to use a basic or extended command message or option, you should query the device driver before trying to use the command message or option (that is, unless you are certain that the MCI driver you have used during development is the same one that will be available on the delivery system). The following tables summarize the specific command messages in each category.

MCI directly processes the following system command messages, rather than passing them to MCI device drivers.

Command	Description

MCI_BREAK	Sets a break key for an MCI device.

MCI_SYSINFO	Returns information about MCI devices.

Required command messages must be supported by all MCI device drivers. The following table lists the required command messages.

Command	Description

MCI_CLOSE	Closes the device.

MCI_GETDEVCAPS	Obtains the capabilities of a device.

MCI_INFO	Obtains textual information from a device.

MCI_OPEN	Initializes the device.

MCI_STATUS	Obtains status information from the device.

Following are the basic command messages. The use of these command messages by a device is optional.

Command	Description

MCI_LOAD	Loads data from a file.

MCI_PAUSE	Stops playing.

MCI_PLAY	Starts transmitting output data.

MCI_RECORD	Starts recording data.

MCI_RESUME	Resumes playing or recording on a paused device.

MCI_SAVE	Saves data to a file.

MCI_SEEK	Seeks forward or backward.

MCI_SET	Sets the operating state of the device.

MCI_STATUS	Obtains status information about the device. (Supplements the required MCI_STATUS command message with options for devices using linear media with identifiable positions.)

MCI_STOP	Stops playing or recording.

Some MCI devices have additional command messages or add options to existing command messages. Although some extended command messages apply only to a specific device driver, most of them apply to all drivers of a particular device type. For example, the sequencer command set extends the MCI_SET command message to add time formats that are needed by MIDI sequencers.

Unless you are certain that the specific MCI driver you use during development will be available on the delivery system, do not assume that the device supports the extended command messages or options. You can use the MCI_GETDEVCAPS command message to determine whether a specific feature is supported. Applications should be ready to handle an MCIERR_UNSUPPORTED_FUNCTION return value.

The following extended command messages are available with certain device types.

Command	Device types	Description

MCI_CUE	waveaudio	Prepares for playing or recording.

MCI_DELETE	waveaudio	Deletes a data segment from the media element.

MCI_ESCAPE	videodisc	Sends custom information to a device.

MCI_FREEZE	overlay	Disables video acquisition to the frame buffer.

MCI_PUT	animation overlay	Defines the source, destination, and frame windows.

MCI_REALIZE	animation	Tells the device to select and realize its palette into a display context of the displayed window.

MCI_SPIN	videodisc	Starts the disc spinning or stops the disc from spinning.

MCI_STEP	animation, videodisc	Steps the play one or more frames forward or reverse.

MCI_UNFREEZE	overlay	Enables the frame buffer to acquire video data.

MCI_UPDATE	animation	Repaints the current frame into the display context.

MCI_WHERE	animation, overlay	Obtains the rectangle specifying the source, destination, or frame area.

MCI_WINDOW	animation, overlay	Controls display window options such as caption text.


Sending Command Messages

Windows provides the following functions to send command messages to devices and to query devices for error information.

Function	Description

mciSendCommand	Sends a command message to an MCI device.

mciGetErrorString	Returns the error string corresponding to an error number.

The MCI Device Identifier

MCI returns a device identifier when you open a device by using the MCI_OPEN command message. Use this identifier to identify the opened device when sending subsequent commands.

MMSYSTEM.H defines a special constant, MCI_ALL_DEVICE_ID, to indicate that a command message is to be sent to all of the MCI devices that an application has opened. You can use MCI_ALL_DEVICE_ID with any command message that does not return information. For instance, the following example closes all of the MCI devices that have been opened by an application.

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

    return FALSE;

Note:	Although using the MCI_ALL_DEVICE_ID identifier is a convenient way to broadcast a command to all your devices, don't rely on it to synchronize devices; the timing between messages can vary.


Opening a Device

Before using a device, you must initialize it by using the MCI_OPEN command message. The variations of this command message make it one of the most complex of all MCI commands.

The MCI_OPEN_PARMS Structure

Like all MCI command messages, MCI_OPEN has an associated structure. The default structure for MCI_OPEN is the MCI_OPEN_PARMS structure. Certain devices, such as waveaudio, animation, and overlay devices, have extended structures 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.

MCI uses the wDeviceID member of this structure to return the device identifier to the application. You should check the return value of the mciSendCommand function before using the device identifier, to be sure that it is valid. A nonzero return value indicates that an error occurred during the opening of the device process.

Note:	You can also determine the device identifier by specifying the device name in a call to the mciGetDeviceID function.

Other members used in opening a device correspond to the following flags for the command message.

Flag	Meaning

MCI_OPEN_ALIAS	The lpstrAlias member of the structure contains a pointer to a device alias.

MCI_OPEN_ELEMENT	The lpstrElementName member of the structure contains a pointer to the element name.

MCI_OPEN_SHAREABLE	The device or element was opened as shareable.

MCI_OPEN_TYPE	The lpstrDeviceType member of the structure contains a pointer to the device-type identifier.

MCI_OPEN_TYPE_ID	The lpstrDeviceType member of the structure contains an integer device-type identifier.

Opening Simple Devices

To open a simple device such as a CD audio or videodisc device, use the lpstrDeviceType member in the MCI_OPEN_PARMS structure to identify the device to open. There are three ways to identify devices:

Specify a pointer to a null-terminated string containing the device name.

Specify a device-type constant.

Specify the actual name of the device driver.

Regardless of which method you use to identify the device, you must specify the MCI_OPEN_TYPE flag to validate the lpstrDeviceType member. For instance, the following example opens a CD audio device by specifying the device name.

UINT wDeviceID;

DWORD dwReturn;

MCI_OPEN_PARMS mciOpenParms;

/* Open a compact disc device by specifying the device name. */

mciOpenParms.lpstrDeviceType = "cdaudio";

if (dwReturn = mciSendCommand(0, MCI_OPEN, MCI_OPEN_TYPE,

        (DWORD)(LPVOID) &mciOpenParms))

    /* Error, unable to open device. */

    return FALSE;

/* Device opened successfully. Get the device ID. */

wDeviceID = mciOpenParms.wDeviceID;

You can also open a device by specifying a device-type constant. To be opened by means of a device-type constant, device drivers must be installed in the [mci] section of the registry by using the following device types.

Device type	Device-type constant

animation	MCI_DEVTYPE_ANIMATION

cdaudio	MCI_DEVTYPE_CD_AUDIO

dat	MCI_DEVTYPE_DAT

digitalvideo	MCI_DEVTYPE_DIGITAL_VIDEO

other	MCI_DEVTYPE_OTHER

overlay	MCI_DEVTYPE_OVERLAY

scanner	MCI_DEVTYPE_SCANNER

sequencer	MCI_DEVTYPE_SEQUENCER

videodisc	MCI_DEVTYPE_VIDEODISC

waveaudio	MCI_DEVTYPE_WAVEFORM_AUDIO

If you open a device by specifying a device-type constant, you must specify the MCI_OPEN_TYPE_ID flag in addition to the MCI_OPEN_TYPE flag. The following example opens a CD audio device by specifying a device-type constant.

UINT wDeviceID;

DWORD dwReturn;

MCI_OPEN_PARMS mciOpenParms;

/*

* Open a compact disc device by

* specifying a device-type constant.

*/

mciOpenParms.lpstrDeviceType = (LPCSTR) MCI_DEVTYPE_CD_AUDIO;

if (dwReturn = mciSendCommand(0, MCI_OPEN,

        MCI_OPEN_TYPE | MCI_OPEN_TYPE_ID,

        (DWORD)(LPVOID) &mciOpenParms))

    /* Error, unable to open device. */

    return FALSE;

/* Device opened successfully. Get the device ID. */

wDeviceID = mciOpenParms.wDeviceID;

When you open a device by specifying a device-type constant, MCI uses the high-order word of the lpstrDeviceType member to distinguish between multiple occurrences of the device type in the registry.

For example, if the registry lists entries for waveaudio1 and waveaudio2, the following statement sets the lpstrDeviceType member to specify the device identified by waveaudio2.

LPSTR lpstrDeviceType;

lpstrDeviceType = (LPSTR)MAKELONG(MCI_DEVTYPE_WAVEFORM_AUDIO, 2);

Similarly, to specify the device identified by waveaudio1, set the high-order word of lpstrDeviceType to 0 or 1. (Setting the high-order word to 0 tells MCI to use an unnumbered device or the lowest-numbered device.)

You can also open a device by specifying the filename of the device driver in the lpstrDeviceType member of the MCI_OPEN_PARMS structure. You don't need to specify the complete path or the filename extension--MCI assumes that drivers are located in the Windows system directory and have a filename extension of .DRV.

Note:	Opening MCI devices by specifying the filename of the device driver may be useful during development and testing. However, this technique is not recommended for applications because it makes them device dependent. Applications that open MCI devices by filename may not work in all systems.

Opening Compound Devices

There are three ways to open a compound device:

Specify only the device (by using the device name, a device-type constant, or the filename of the device driver).

Specify both the device and the device element.

Specify only the device element.

The first method--specifying only the device--is useful for determining the capabilities of a device by using the MCI_GETDEVCAPS command message. To actually control a media device, you must specify a device element when you open the device.

To specify a device element, fill the lpstrElementName member of the MCI_OPEN_PARMS structure with a pointer to a null-terminated string containing the filename of the device element. You must also validate the lpstrElementName member by specifying the MCI_OPEN_ELEMENT flag in the dwFlags parameter of the mciSendCommand function.

You can specify the device in the same manner used for simple devices: by device name, by device-type constant, or by the filename of the driver. The following example opens the waveaudio device with a WAVE file named TIMPANI.WAV.

UINT wDeviceID;

DWORD dwReturn;

MCI_OPEN_PARMS mciOpenParms;

/*

 * Open a waveaudio device by specifying

 * the device name and device element.

 */

mciOpenParms.lpstrDeviceType = "waveaudio";

mciOpenParms.lpstrElementName = "timpani.wav";

if (dwReturn = mciSendCommand(0, MCI_OPEN,

        MCI_OPEN_TYPE | MCI_OPEN_ELEMENT,

        (DWORD)(LPVOID) &mciOpenParms))

    /* Error, unable to open device. */

    return FALSE;

/* Device opened successfully. Get the device ID. */

wDeviceID = mciOpenParms.wDeviceID;

You can also open a device by specifying just a device element. MCI uses the filename extension of the given device element along with the [mci extensions] section of the registry to select the device to open. For more information about opening devices by specifying only a device element, see Opening MCI Devices.


Closing a Device

The MCI_CLOSE command message releases access to a device or device element. MCI frees a device when all processes using a device have closed it. To help MCI manage devices, applications should explicitly close each device or device element when they are finished using it.

Note:	It is very important that applications close all opened MCI devices before terminating. You can close all devices with a single command message by specifying the MCI_ALL_DEVICE_ID constant as the device identifier.


Using the Wait and Notify Flags

Typically, MCI returns control to the application immediately, even if it takes several seconds to complete the action initiated by a command. For example, after a CD audio device receives a seek command, control returns to the application before the seek operation is complete. You can use the following two flags to request that MCI wait until a command is complete before returning control to the application, or that MCI notify the application when the command is complete.

Flag	Description

MCI_NOTIFY	Directs the device to return control immediately and post the MM_MCINOTIFY message when the requested action is complete.

MCI_WAIT	Directs the device to wait until the requested action is complete before returning control to the application.

Using the Notify Flag

The MCI_NOTIFY flag directs MCI to post the MM_MCINOTIFY message when the device completes an action. The application specifies the handle of the destination window for the message in the dwCallBack member of the structure sent with the command message. Every structure associated with a command message contains this member.

Note:	MCI can have only one pending notification message for each device.

When MCI posts the MM_MCINOTIFY message, it sets the low-order word of the lParam parameter of the window procedure to the identifier of the device initiating the callback. The wParam parameter of the window procedure contains one of the following constants specifying the notification status of the callback.

Flag	Meaning

MCI_NOTIFY_SUCCESSFUL	The conditions required for initiating the callback are satisfied and the command finished without interruption.

MCI_NOTIFY_SUPERSEDED	MCI had a notification pending and received another notify request. MCI resets the callback conditions to correspond to the notify request of the new command.

MCI_NOTIFY_ABORTED	The application sent a new command that prevented the callback conditions set by a previous command from being satisfied. If an application interrupts a command that requested notification, MCI does not inform the window procedure of the notify command being aborted.

MCI_NOTIFY_FAILURE	A device error occurred while a device was executing the command. For example, MCI posts this message when a hardware error occurs during a play command.

Using the Wait Flag and Break Command Message

Specifying the MCI_WAIT flag with a command message causes MCI to wait until the command has finished before returning control to the application. Using the wait flag with commands that take a long time essentially disables a system from receiving any user input until the command is complete.

MCI supports a break key to interrupt the wait operation and return control to the application. The break key does not interrupt the command, but by returning control to the application, it allows the application to monitor user input.

By default, MCI defines the break key as CTRL+BREAK. Applications can redefine this key by using the MCI_BREAK command message. MCI_BREAK uses the MCI_BREAK_PARMS structure.

The following flags validate members in the MCI_BREAK_PARMS structure:

Flag	Description

MCI_BREAK_HWND	Validates the hwndBreak member, which specifies the window that must have the focus to enable break detection.

MCI_BREAK_KEY	Validates the nVirtKey member, which specifies the virtual-key code to be used for the break key.

MCI_BREAK_OFF	Disables any existing break key.


Obtaining MCI System Information

The MCI_SYSINFO command message obtains system information about MCI devices. MCI handles this message without relaying it to any MCI device. MCI returns the system information in the MCI_SYSINFO_PARMS structure.

The MCI_SYSINFO command message has the following flags.

Flag	Meaning

MCI_SYSINFO_QUANTITY	MCI returns the number of devices of a given type listed in the [mci] section of the registry. When this flag is used with the MCI_SYSINFO_OPEN flag, the number of open devices is returned.

MCI_SYSINFO_NAME	MCI returns the name of a device that satisfies the query. When this flag is used with the MCI_SYSINFO_OPEN flag, only the names of open devices are returned.

MCI_SYSINFO_OPEN	MCI returns the number or names of open devices.

MCI_SYSINFO_INSTALLNAME	MCI returns the name listed in the registry entry used to install the device.

You use the MCI_SYSINFO_QUANTITY flag to determine the number of devices for a particular type listed in the [mci] section of the registry. For this flag, set the wDeviceType member of the structure to the device type. When requesting the number of devices, set the wDeviceID parameter to NULL. MCI returns the number of devices as a doubleword in the lpstrReturn member of the structure. If you combine the MCI_SYSINFO_QUANTITY flag with the MCI_SYSINFO_OPEN flag, MCI returns the number of devices of that type opened by the process.

Once you have the number of devices, you can enumerate the names of the devices by using the MCI_SYSINFO_NAME flag. To get information by using this flag, you must create a buffer for the return name. In the structure, specify a pointer to the buffer, the size of the buffer, the index number corresponding to the device (1 is the first device), and the device type. This information is entered in the lpstrReturn, dwRetSize, dwNumber, and wDeviceType members. MCI returns the device name in the buffer. When requesting the name of a particular device, set the wDeviceID parameter to NULL. To restrict the names to open devices, use the MCI_SYSINFO_OPEN flag with MCI_SYSINFO_NAME.

To retrieve information on all devices in the system, you can assign the MCI_ALL_DEVICE_ID constant to the wDeviceID parameter. When you use this identifier, MCI ignores the contents of the wDeviceType member and returns information on all MCI devices listed in the registry. When you use the MCI_SYSINFO_OPEN flag with the MCI_ALL_DEVICE_ID identifier, MCI returns information about the devices opened by the task.

You can retrieve the installation name of an open device by using the MCI_SYSINFO_INSTALLNAME flag. To get the installation name, you must create a buffer for the return name. In the structure, specify a pointer to the buffer and the size of the buffer in the lpstrReturn and dwRetSize members. MCI places the device that corresponds to the wDeviceID parameter name in the buffer.


About the Command-String Interface

This section presents an introduction to the MCI command-string interface. MCI provides the following functions for working with command strings.

Function	Description

mciSendString	Sends a command string to an MCI device driver. This function also has parameters for callback functions and return strings.

mciGetErrorString	Returns the error string corresponding to an error number.


Sending Command Strings

Use the mciSendString function to send command strings to a device. The following statement passes the "play to 500" command string to a waveaudio device driver.

DWORD dwErrorCode;

dwErrorCode = mciSendString("play waveaudio to 500", NULL, 0, 0L);

If the mciSendString function succeeds, it returns zero. If the function fails, it returns an error code. To get extended error information, use the mciGetErrorString function.


Additional Information About Command Strings

The MCITEST application contains examples of using the mciSendString and mciGetErrorString functions. You can use this application to experiment with MCI devices and command strings.


Introduction to Audio Overview

Introduction to Audio

About Audio Services

Microsoft® Windows™ provides several different types and levels of audio services. You should become familiar with these types and levels so you can choose the services appropriate for your application.

This topic covers the following topics:

The different types and levels of audio services

An overview of the audio architecture

Audio file formats used by Windows

Books and specifications providing additional information about audio

This topic assumes you have a basic knowledge of digital audio and Musical Instrument Digital Interface (MIDI). For more information on these subjects, see Further Reading.

The following topics discuss Win32 Audio Services:

Types of Audio Services

Levels of Audio Services

Windows Audio Architecture

High-Level Audio Functions

Low-Level Audio Functions

The MIDI Mapper

Audio File Formats

Further Reading


Types of Audio Services

Different types of audio services require different formats for the audio information and different technologies to reproduce audio. Windows offers the following types of audio services:

Waveform audio services provide playback and recording support for digital audio hardware. Waveform audio is useful for reproducing nonmusical audio material such as sound effects and voice-over narration. Waveform audio has moderate storage-space and data-transfer rate requirements--as low as 11 kilobytes per second of audio.

MIDI audio services provide support for MIDI-file and MIDI-event playback (through internal or external synthesizers) and MIDI-event recording. MIDI audio is useful with music-related applications such as music composition and MIDI sequencer programs. Because they require less storage space and a lower data-transfer rate than waveform audio, you may want to use MIDI audio services to provide introductory and background music in your applications.

Compact disc (CD) audio services provide support for playback of Red Book audio information on CDs by means of the CD-ROM drive on multimedia computers. CD audio offers the highest quality reproduction of musical material but has the highest storage-space requirements--176 kilobytes per second of audio. You cannot read from the CD-ROM drive while playing CD audio.


Levels of Audio Services

The different levels of audio services let you choose services appropriate to the requirements of your application and to your programming ability. Windows offers two levels of audio services:

High-level audio services allow you to play and record audio files by using as little as one function call. Compared with low-level audio services, high-level services are easier to use and require less programming. High-level services also meet the audio requirements of most applications.

Low-level audio services allow you to communicate directly with audio device drivers to manage playback and recording. Low-level audio services require more programming than high-level services but give you more control over audio playback and recording.

The easiest way to play and record audio is to use high-level audio services. If the high-level audio services do not meet the audio needs of your application, you can use low-level audio services to write your own routines to manage audio playback and recording.


Windows Audio Architecture

Windows provides audio services through high-level audio functions, Media Control Interface (MCI) device drivers, low-level audio functions, the MIDI Mapper, and low-level audio device drivers. The following illustration shows the relationship between an application and the elements of Windows that provide audio support.


High-Level Audio Functions

MCI functions, along with MCI device drivers, provide high-level audio support for MIDI, waveform, and CD audio devices. MCI drivers can play disk-resident (hard disk and CD-ROM) audio files in the background while an application runs in the foreground. In addition to MCI, Windows provides high-level audio support with three special-purpose functions that play waveform sounds: MessageBeep, PlaySound, and sndPlaySound. You can also use these functions to play waveform sounds associated with system alerts and sounds identified by entries in the registry.

High-level audio functions should meet the audio requirements of most applications.


Low-Level Audio Functions

Low-level audio functions provide a device-independent interface to audio hardware in multimedia computers. These functions supply low-level audio services by letting applications communicate directly with the audio device drivers. MCI drivers and the MessageBeep, PlaySound, and sndPlaySound functions use these low-level functions to provide high-level audio services.

Low-level audio functions are provided for applications--such as audio tools programs--that have special-purpose audio requirements. For example, a MIDI sequencer application would use low-level audio functions to record and play MIDI data.


The MIDI Mapper

The MIDI Mapper provides standard patch services for device-independent playback of MIDI files. Standard patch services ensure that different MIDI synthesizers use the same instrument sounds to reproduce the music in a MIDI file.

The MIDI Mapper translates and redirects messages sent to it by low-level MIDI output functions. Because the high-level MIDI services use low-level MIDI output functions, the MIDI Mapper can be used with high-level as well as low-level MIDI services. MIDI files must follow certain authoring guidelines to use the standard patch services provided by the MIDI Mapper.


Audio File Formats

Windows supports a tagged file structure called the Resource Interchange File Format (RIFF). There are two RIFF file formats currently defined for audio files.

RIFF type	Filename extension	Description

RMID	.RMI	MIDI audio file

WAVE	.WAV	Waveform audio file

The WAVE file format supports a number of digital audio data formats. All multimedia computers support pulse code modulated (PCM) formats of 8-bit monaural data at sample rates of 11.025 kilohertz (kHz) and 22.05 kHz.

In addition to Resource Interchange File Format MIDI (RMID) files, the MCI MIDI sequencer plays standard MIDI files in the format defined by the International MIDI Association in the "Standard MIDI Files 1.0" specification. For information about how to obtain this specification, see Further Reading. RMID files are standard MIDI files with a RIFF header.

Using RIFF Files

The multimedia file input and output (I/O) services include functions for working with RIFF files.


Further Reading

For more information on digital audio, digital-signal processing, and computer music, see the following books:

Boom, Michael. Music Through MIDI. Redmond: Microsoft Press, 1987.

Chamberlin, Hal. Musical Applications of Microprocessors. Hasbrouk Heights: Hayden Book Company, Inc., 1985.

Pohlmann, Ken. Principles of Digital Audio. Indianapolis: Howard W. Sams & Co., 1985.

Roads, Curtis, and John Strawn. Foundations of Computer Music. Cambridge: The MIT Press, 1985.

Strawn, John F. Digital Audio Engineering, An Anthology. Los Altos: William Kaufmann, Inc., 1985.

Strawn, John F. Digital Audio Signal Processing, An Anthology. Los Altos: William Kaufmann, Inc., 1985.

For information about MIDI and standard MIDI files, see the following MIDI specifications:

MIDI 1.0 Detailed Specification

Standard MIDI Files 1.0 Specification

These specifications are available from the International MIDI Association at the following address:

International MIDI Association

5316 West 57th Street

Los Angeles, CA 90056


High-Level Audio Overview

High-Level Audio

This topic explains how to use the high-level audio services of Microsoft® Windows™ to add sound to applications.

The following topics discuss the high-level audio services:

Function Prefixes

Playing Waveform Sounds

Restrictions in Playing Waveform Sounds

Using the PlaySound and sndPlaySound Functions

Playing System Alert Sounds

Playing and Recording Audio Using MCI

MCI Audio Data Types

MCI Audio Commands

Opening MCI Audio Devices

Handling MCI Errors

Starting Playback

Changing the Current Position

Setting the Time Format

Closing MCI Audio Devices

Getting Information About Devices and Media

Recording With Waveform Audio Devices

Using the MCI MIDI Sequencer

The MIDI Mapper

MIDI Notational Conventions

The MIDI Mapper and Windows

The MIDI Mapper Architecture

The Channel Map

Patch Maps

Key Maps

Summary of Maps and MIDI Messages

Authoring MIDI Files

About Base-Level and Extended Synthesizers

Authoring Guidelines for MIDI Files

Standard MIDI Patch Assignments

Standard MIDI Key Assignments

Using the MARKMIDI Utility

This topic assumes you have a basic knowledge of digital audio and MIDI.


Function Prefixes

High-level audio function names begin with the following prefixes:

Prefix	Function group

snd	System-alert sound functions

mci	MCI functions


Playing Waveform Sounds

One basic way to use sound is to associate a sound with a user action or with a warning or alert message. These sounds tend to be short in duration and are often played repeatedly. Windows provides three functions to play waveform sounds.

Function	Description

MessageBeep	Plays the sound that corresponds to a given system-alert level.

PlaySound	Plays the sound that corresponds to the given filename or registry entry.

sndPlaySound	Plays the sound that corresponds to the given filename or registry entry.

These functions provide methods of playing the following waveform sounds:

WAVE files stored on a hard disk or CD-ROM

In-memory WAVE resources

WAVE files specified by entries in the registry

WAVE files associated with system-alert levels


Restrictions in Playing Waveform Sounds

There are some restrictions to using the MessageBeep, PlaySound, and sndPlaySound function to play waveform sounds:

The entire sound must fit in available physical memory.

The sound must be in a data format playable by one of the installed waveform audio device drivers.

Use MessageBeep, PlaySound, and sndPlaySound to play WAVE files that are relatively small in size--up to about 100 kilobytes. For larger sound files, use the MCI services. For information about using MCI, see Playing and Recording Audio Using Media Control Interface.


Using the PlaySound and sndPlaySound Functions

The PlaySound and sndPlaySound functions can be used to perform the following tasks:

Play WAVE files

Loop sounds

Play WAVE resources

Play sounds specified in the registry

The following sections describe these tasks. Although the examples shown use the sndPlaySound function, most of the sample code works with the PlaySound function as well.

Playing WAVE Files

The following statement plays the C:\SOUNDS\BELLS.WAV file.

sndPlaySound("C:\\SOUNDS\\BELLS.WAV", SND_SYNC);

If the specified file does not exist or does not fit into the available physical memory, sndPlaySound plays the default system sound specified by the SystemDefault entry in the [sounds] section of the registry. If there is no SystemDefault entry, sndPlaySound fails without producing any sound. If you don't want the default system sound to play, specify the SND_NODEFAULT flags in the following example.

sndPlaySound("C:\\SOUNDS\\BELLS.WAV", SND_SYNC | SND_NODEFAULT);

Looping Sounds

If you specify the SND_LOOP and SND_ASYNC flags for the wFlags parameter of the sndPlaySound function, as in the following example, the sound continues to play repeatedly.

sndPlaySound("C:\\SOUNDS\\BELLS.WAV", 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 continues to play until sndPlaySound is called to play another sound. To stop playing a looped or asynchronous sound without playing another sound, use the following statement.

sndPlaySound(NULL, 0);

Playing WAVE Resources

You can also build WAVE files into an application as resources and use the sndPlaySound function to play these sounds by specifying the SND_MEMORY flag. 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 function in the following example plays a specified WAVE resource.

/* 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");

Playing Sounds Specified in the Registry

The sndPlaySound function also plays waveform sounds referred to by a key-name in the [sounds] section of the registry. This enables users to assign their own sounds to system alerts and warnings, or to user actions such as mouse-button click. For example, the [sounds] section of the registry might look like the following.

[sounds]

SystemDefault=C:\SOUNDS\BUMMER.WAV, Says BUMMER

SystemAsterisk=C:\SOUNDS\WHALES.WAV, Whale sounds

SystemExclamation=C:\SOUNDS\LASER.WAV, Laser gun sounds

SystemHand=C:\SOUNDS\OHOH.WAV, Says OH-OH

SystemQuestion=C:\SOUNDS\JIBERISH.WAV, Person mumbling

SystemStart=C:\SOUNDS\CHORD.WAV, Plays a chord

MouseClick=C:\SOUNDS\CLICK.WAV, Recording of a clicking sound

To play a sound identified by a registry entry, call sndPlaySound with the lpszSoundName parameter pointing to a string that contains the name of the entry that identifies the sound. For example, to play the sound associated with the MouseClick entry in the [sounds] section of the registry and wait for the sound to finish before returning, use the following statement.

sndPlaySound("MouseClick", SND_SYNC);

If the specified registry entry or the waveform file it identifies does not exist, or if the sound does not fit into the available physical memory, sndPlaySound plays the default system sound specified by the SystemDefault entry. If there is no SystemDefault entry, sndPlaySound fails without producing any sound. If you don't want the default system sound to play, specify the SND_NODEFAULT flag, as in the following example.

sndPlaySound("MouseClick", SND_SYNC | SND_NODEFAULT);

Note:	The sndPlaySound function always searches the [sounds] section of the registry for a keyname matching the lpszSoundName parameter before attempting to load a file with this name. The [sounds] section of the registry includes an optional string following the waveform filename for descriptive text about the sound in the file. This descriptive text is displayed in the Sound option of the Control Panel.


Playing System-Alert Sounds

The MessageBeep function uses the waveform audio hardware to produce a variety of user-selectable sounds.

When you call MessageBeep, it searches the [sounds] section of the registry for the WAVE file that corresponds to the specified alert level. Following are the registry entries for system-alert sounds.

Registry Entry	Description

SystemDefault	Identifies the sound produced when the MessageBeep function is called with the wAlert  parameter set to an invalid alert level or when the requested alert sound can't be found. This is called the default system sound.

SystemAsterisk	Identifies the sound produced when MessageBeep is called with wAlert set to MB_ICONASTERISK.

SystemExclamation	Identifies the sound produced when MessageBeep is called with wAlert set to MB_ICONEXCLAMATION.

SystemHand	Identifies the sound produced when MessageBeep is called with wAlert set to MB_ICONHAND.

SystemQuestion	Identifies the sound produced when MessageBeep is called with wAlert set to MB_ICONQUESTION.

If MessageBeep is called with wAlert set to zero, it plays the default system sound. If wAlert is set to -1, MessageBeep uses the computer speaker to produce a standard beep sound. If MessageBeep can't play the requested sound, it plays the default system sound. If it can't play the default system sound, then it produces a beep sound using the computer speaker.

The Sound option of the Control Panel enables users to set these registry entries to customize their environment for system-alert sounds. It also enables users to disable these alert sounds.


Playing and Recording Audio Using Media Control Interface

The Media Control Interface (MCI) provides a high-level interface for controlling both internal and external media devices. It provides support for playing wave- form, MIDI, and compact disc audio and for recording waveform audio. MCI is the easiest way for multimedia applications to play and record audio.

MCI uses device drivers to interpret and execute high-level MCI commands. MCI device drivers can stream digital audio and MIDI data directly from a storage device to the appropriate device driver, allowing applications to play files too large to fit in available physical memory. This data streaming takes place in the background while an application is running. The application is responsible only for setting up MCI and telling it to start playing or recording.

MCI provides two types of interface: command-message and command-string. This section explains how to use the command-message interface for waveform, MIDI, and compact disc audio devices.


MCI Audio Data Types

The MMSYSTEM.H header file defines data types and function prototypes for MCI. You must include this header file in any source-code module that uses MCI functions.

Following are the data types for structures used with extended MCI commands related to audio.

Type	Description

MCI_SEQ_SET_PARMS	Specifies a structure for the MCI_SET command message for MIDI sequencer devices.

MCI_WAVE_DELETE_PARMS	Specifies a structure for the MCI_DELETE command message for waveform audio devices.

MCI_WAVE_OPEN_PARMS	Specifies a structure for the MCI_OPEN command message for waveform audio devices.

MCI_WAVE_SET_PARMS	Specifies a structure for the MCI_SET command message for waveform audio devices.


MCI Audio Commands

MCI provides a standard set of commands applying to all types of media devices. Some of these commands can be extended to accommodate unique features of a particular type of device.

Following are the MCI command messages that perform common audio playback and recording tasks.

MCI command	Audio task

MCI_OPEN	Open an audio device.

MCI_CLOSE	Close an audio device.

MCI_PLAY	Play all or part of audio selection; resume playback from pause.

MCI_STOP	Stop playback.

MCI_PAUSE	Pause playback.

MCI_SEEK	Change current location.

MCI_CUE	Cue a device so playback or recording begins with minimum delay.

MCI_RECORD	Begin recording on a waveform audio device.

MCI_SAVE	Save a recorded waveform audio file.

MCI_INFO	Query device information such as the product name and the name of the device element currently associated with the device (returns information in string format).

MCI_GETDEVCAPS	Query device capabilities such as the device name and number of inputs and outputs (if the device can record).

MCI_STATUS	Query device status such as current playback position, media length, media format, time format, record level, CD audio track, and MIDI sequencer tempo.

MCI_SET	Set device parameters such as time format, waveform data format, and MIDI sequencer tempo.


Opening MCI Audio Devices

MCI requires that audio devices be opened before they can be accessed. Use the MCI_OPEN command message along with the MCI_OPEN_PARMS structure to open an audio device and obtain an MCI device identifier. Subsequent commands use this device identifier to identify the device to receive the command.

The MCI device identifier is returned in the wDeviceID member. Always check the return value of the mciSendCommand function after sending an MCI_OPEN command message before using this device identifier. A nonzero return value indicates that there was an error in opening the device and that the returned device identifier is not valid.

For waveform audio devices, you can use an extended structure, MCI_WAVE_OPEN_PARMS. This structure has a dwBufferSeconds member to specify the number of seconds of buffering used by the MCI waveform device driver. If you use this member, you must specify the MCI_WAVE_OPEN_BUFFER flag for the dwParam1 parameter of mciSendCommand to validate the member.

If you do not want to specify the number of seconds of buffering for the driver to use, you can use the MCI_WAVE_OPEN_PARMS structure when you open waveform audio devices.

When you open a simple device, such as a compact disc audio device, you must specify the device name. When you open a compound device, such as a waveform or MIDI sequencer device, the device name is optional. Use the lpstrDeviceType member of the MCI_OPEN_PARMS structure to specify the device name. MCI lets you use a string or a constant for this member. Following are the strings and constants for MCI audio devices.

Device	String	Constant

Compact disc	cdaudio	MCI_DEVTYPE_CD_AUDIO

Waveform	waveaudio	MCI_DEVTYPE_WAVEFORM_AUDIO

MIDI sequencer	sequencer	MCI_DEVTYPE_SEQUENCER

A string is the default format for specifying device names. If you use a constant to specify the device name, you must specify the MCI_OPEN_TYPE_ID flag in addition to the MCI_OPEN_TYPE flag.

Opening Waveform and MIDI Sequencer Devices

Waveform and MIDI sequencer devices are compound devices. Compound devices require an associated device element--a WAVE or MIDI file. There are three ways to open compound devices:

Specify only the device name.

Specify only the device element and let MCI select the device associated with the file extension of the device element.

Specify both the device name and the device element.

Specify only the device name when opening a device to query its capabilities with the MCI_GETDEVCAPS command message and when you plan to use the device to play more than one device element.

If you don't specify a device name when you open a compound device, MCI chooses an appropriate device type by comparing the file extension of the device element with entries in the [mci extensions] section of the registry. The following example uses this technique to open a MIDI sequencer device to play a MIDI file named CHOPIN.RMI.

UINT wDeviceID;

MCI_OPEN_PARMS mciOpenParms;

    .

    .

    .

/* Open the device by specifying only the device element. */

mciOpenParms.lpstrElementName = "CHOPIN.RMI";

if (mciSendCommand(0,                           /* device ID */

        MCI_OPEN,                               /* command   */

        MCI_OPEN_ELEMENT,                       /* flags     */

        (DWORD) (LPVOID) &mciOpenParms))  /* parameter block */

    /* Error, unable to open device. */

    return FALSE;

else

    /* Device opened successfully. Get the device ID. */

    wDeviceID = mciOpenParms.wDeviceID;

Instead of letting MCI choose the device, you can specify the device name when you open the device. The following example uses this technique to open a waveform audio device to play the BELLS.WAV file. This example uses a string to specify the device name. For an example using a constant to specify the device name, see Opening Compact Disc Devices.

UINT wDeviceID;

MCI_OPEN_PARMS mciOpenParms;

    .

    .

    .

/*

 * Open the device by specifying both the device

 * element and the device name.

 */

mciOpenParms.lpstrDeviceType = "waveaudio";

mciOpenParms.lpstrElementName = "C:\\SOUNDS\\BELLS.WAV";

if (mciSendCommand(0,                           /* device ID */

        MCI_OPEN,                               /* command   */

        MCI_OPEN_ELEMENT | MCI_OPEN_TYPE,       /* flags     */

        (DWORD) (LPVOID) &mciOpenParms))  /* parameter block */

    /* Error, unable to open device. */

    return FALSE;

else

    /* Device opened successfully. Get the device ID. */

    wDeviceID = mciOpenParms.wDeviceID;

Using the MIDI Mapper With the MCI Sequencer

The MIDI Mapper is the default output device for the MCI MIDI sequencer. It provides standard patch services for device-independent playback of MIDI files. Applications that use the MCI sequencer to play MIDI files should use the MIDI Mapper. For details about the MIDI Mapper, see The MIDI Mapper. For information about authoring device-independent MIDI files, see Authoring MIDI Files.

When you open the MCI MIDI sequencer, MCI attempts to select the MIDI Mapper as the output device. If the MIDI Mapper is unavailable because it is already in use, MCI selects another MIDI output device.

Note:	The MIDI Mapper currently supports only one client at a time in the current versions of Microsoft Windows NT.

After opening the sequencer, you should check to see if the MIDI Mapper was available and was selected as the output device. The following example uses the MCI_STATUS command message to verify that the MIDI Mapper is the output device for the MCI sequencer.

UINT wDeviceID;

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

}

if (LOWORD(mciStatusParms.dwReturn) == MIDI_MAPPER) {

    /* The MIDI Mapper is the output device. */

}

else {

    /* The MIDI Mapper is not the output device. */

}

MCI also provides a command message that explicitly selects the MIDI Mapper as the output device for the sequencer. The following example uses the MCI_SET command message to select the MIDI Mapper as the output device for the MCI sequencer.

UINT wDeviceID;

DWORD dwReturn;

MCI_SEQ_SET_PARMS mciSeqSetParms;

    .

    .

    .

/* Set the MIDI Mapper as the output port for the open device. */

mciSeqSetParms.dwPort = MIDI_MAPPER;

if (dwReturn = mciSendCommand(wDeviceID, MCI_SET, MCI_SEQ_SET_PORT,

                              (DWORD)(LPVOID) &mciSeqSetParms)) {

    /* Error, unable to set Mapper as output port. */

}

Before querying the sequencer or setting an output port, you must successfully open the sequencer. Both of the previous examples assume that the wDeviceID parameter contains a valid device identifier for the sequencer.

Opening Compact Disc Devices

Because a compact disc audio device is a simple device, you need only specify the device name when opening it by using either a string or a constant device identifier. The following example opens a compact disc device by using a constant device identifier to specify the device name.

UINT wDeviceID;

MCI_OPEN_PARMS mciOpenParms;

    .

    .

    .

/* Open the device by specifying a constant device ID. */

mciOpenParms.lpstrDeviceType = (LPCSTR) MCI_DEVTYPE_CD_AUDIO;

if (mciSendCommand(0,                           /* device ID */

        MCI_OPEN,                               /* command   */

        MCI_OPEN_TYPE | MCI_OPEN_TYPE_ID,       /* flags     */

        (DWORD) (LPVOID) &mciOpenParms))  /* parameter block */

    /* Error, unable to open device. */

    return FALSE;

else

    /* Device opened successfully. Get the device ID. */

    wDeviceID = mciOpenParms.wDeviceID;


Handling MCI Errors

Always check the return value of the mciSendCommand function. If it indicates an error, you can use the mciGetErrorString function to get a textual description of the error. You can also interpret the error code yourself; MMSYSTEM.H defines constants for MCI error return codes.

Note:	To interpret an error return value from mciSendCommand yourself, mask the high-order word, the low-order word contains the error code. However, if you pass the error return value to the mciGetErrorString function, you must pass the entire doubleword value.

The following example function takes the MCI error code specified by dwError, passes it to mciGetErrorString, and displays the resulting textual error description by using the MessageBox function.

/*

 * Uses mciGetErrorString to get a

 * text description of an MCI error.

 * Displays the error description by 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);

}


Starting Playback

Once you successfully open an MCI audio device, you can use the MCI_PLAY command message along with the MCI_PLAY_PARMS structure to begin playback. MMSYSTEM.H defines MCI_PLAY_PARMS as follows.

typedef struct {

        DWORD   dwCallback; /* callback for MCI_NOTIFY flag */

        DWORD   dwFrom;     /* playback begin position */

        DWORD   dwTo;       /* playback end position */

} MCI_PLAY_PARMS;

Playback begins at the current position in the device element. When a device element is opened, the current position is set to the beginning of the medium. After a device element is played, the current position is at the end of the medium. You can use the MCI_SEEK command message to change the current position. For more information about MCI_SEEK, see Changing the Current Position.

You can also set beginning and ending positions for playback by specifying the MCI_FROM and MCI_TO flags with the MCI_PLAY command message. If you specify one of these flags, you must fill in the corresponding dwFrom or dwTo member in the MCI_PLAY_PARMS structure with the desired beginning or ending time. If you are using a time format other than the default time format, you must set the time format before specifying a beginning or ending time with MCI_PLAY.

Example: Playing a WAVE File

The following example function opens a waveform device and plays the WAVE file specified by the lpszWAVEFileName parameter.

/*

 * Plays a given WAVE file by using MCI_OPEN, 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 name and device element.

     * MCI will choose a device capable

     * of playing the given 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;

    }

    /* Device opened successfully. Get the device ID. */

    wDeviceID = mciOpenParms.wDeviceID;

    /*

     * Begin playback. The window-procedure function

     * for the parent window is notified with an

     * MM_MCINOTIFY message when playback is

     * complete. The window procedure then

     * 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 0;

}

Example: Playing a MIDI File

The following example function 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 given MIDI file using MCI_OPEN, MCI_PLAY.

 * Returns as soon as playback begins. The window

 * procedure function for the given window is notified

 * when playback is complete. Returns 0L on success;

 * otherwise 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;

    /*

     * Open the device by specifying the

     * device name and device element.

     * 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;

    }

    /* Device opened successfully. Get the device ID. */

    wDeviceID = mciOpenParms.wDeviceID;

    /* See 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 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 0;

        }

    }

    /*

     * Begin playback. The window procedure function

     * for the parent window is notified with an

     * MM_MCINOTIFY message when playback is complete.

     * The window procedure then 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 0;

}

Example: Playing a Compact Disc Track

The following example function opens a compact disc device, plays the track specified by the wTrack parameter, and closes the device after playback is complete.

/*

 * Plays a given compact disc track using

 * MCI_OPEN, MCI_PLAY. Returns as

 * soon as playback begins. The window procedure

 * function for the given window will be notified

 * when playback is complete. Returns 0L on

 * success; otherwise, it 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 compact disc 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;

    }

    /* Device opened successfully, get the device ID. */

    wDeviceID = mciOpenParms.wDeviceID;

    /* Set the time format to track/minute/second/frame. */

    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 = 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 0;

}

To specify a track-relative position with a compact disc device, you must use the track/minute/second/frame time format. For details about setting time formats, see Setting the Time Format.


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. MMSYSTEM.H defines MCI_SEEK_PARMS as follows.

typedef struct {

        DWORD   dwCallback; /* callback for MCI_NOTIFY flag */

        DWORD   dwTo;       /* seek position */

} MCI_SEEK_PARMS;

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

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;

Using the Minute/Second/Frame Time Format

In the minute/second/frame time format specified with the MCI_FORMAT_MSF constant, the time is relative to the beginning of the medium. The time is packed into a double as follows.

Word	Byte	Contents

High-order word	High-order byte	Unused

Low-order byte	Frames

Low-order word	High-order byte	Seconds

Low-order byte	Minutes

The MMSYSTEM.H header file defines the following macros to get and set elements of a minute/second/frame packed doubleword.

Macro	Description

MCI_MSF_MINUTE	Gets minute value in a minute/second/frame doubleword.

MCI_MSF_SECOND	Gets second value in a minute/second/frame doubleword.

MCI_MSF_FRAME	Gets frame value in a minute/second/frame doubleword.

MCI_MAKE_MSF	Sets minute, second, and frame values in a minute/second/frame doubleword.

Note:	The first few seconds of audio compact discs contain table-of-contents data. To play from the beginning of a disc using the minute/second/frame time format, use the MCI_STATUS command message to get the position of the first track and play from that position.

Using the Track/Minute/Second/Frame Time Format

In the track/minute/second/frame time format specified with the MCI_FORMAT_TMSF constant, the time is relative to the beginning of the specified track. The time is packed into a doubleword, as follows.

Word	Byte	Contents

High-order word	High-order byte	Frames

Low-order byte	Seconds

Low-order word	High-order byte	Minutes

Low-order byte	Track

The MMSYSTEM.H header file defines the following macros to get and set elements of a track/minute/second/frame packed doubleword.

Macro	Description

MCI_TMSF_TRACK	Gets track value in a track/minute/second/frame doubleword.

MCI_TMSF_MINUTE	Gets minute value in a track/minute/second/frame doubleword.

MCI_TMSF_SECOND	Gets second value in a track/minute/second/frame doubleword.

MCI_TMSF_FRAME	Gets frame value in a track/minute/second/frame doubleword.

MCI_MAKE_TMSF	Sets track, minute, second, and frame values in a track/minute/second/frame doubleword.

Using the SMPTE Time Formats

Society of Motion Picture and Television Engineers (SMPTE) time formats are based on standard time formats developed for the motion picture and television industries. For SMPTE time formats, the time is packed into a doubleword, as shown in the following table follows.

Word	Byte	Contents

High-order word	High-order byte	Frames

Low-order byte	Seconds

Low-order word	High-order byte	Minutes

Low-order byte	Hours


Closing MCI Audio Devices

After you finish using an MCI device, you must use the MCI_CLOSE command messages to close the device. If you are playing a compound device, such as a waveform or MIDI device, and want to play a different device element using the same device, close the device and reopen it using the new device element.

Note:	If you're playing multiple device elements with the same device, you'll get better performance if you open the device by explicitly specifying its name, then open, play, and close the individual device elements separately. Don't close the device until you have finished playing all of the device elements. Otherwise, the driver is reloaded each time you open the device.


Getting Information About Devices and Media

Use the MCI_STATUS command message along with the MCI_STATUS_PARMS structure to get information about the status of an open device and its associated device element.

Before using the MCI_STATUS command message, you must identify the status item to query for by putting a constant in the dwItem member of the structure. Following are the constants and their corresponding status items for the different audio device types.

All Audio Devices

Constant	Status item

MCI_STATUS_LENGTH	Length of the medium

MCI_STATUS_POSITION	Current position

MCI_STATUS_MODE	Current mode

MCI_STATUS_TIME_FORMAT	Time format

MCI_STATUS_READY	Ready state

Waveform Devices

Constant	Status item

MCI_WAVE_STATUS_BLOCKALIGN	Block alignment

MCI_WAVE_STATUS_FORMATTAG	Format tag

MCI_WAVE_STATUS_CHANNELS	Number of channels

MCI_WAVE_STATUS_SAMPLESPERSEC	Sample rate

MCI_WAVE_STATUS_AVGBYTESPERSEC	Average bytes per second

MCI_WAVE_STATUS_BITSPERSAMPLE	Bits per sample (in PCM format files)

MCI_WAVE_STATUS_LEVEL	Record level

Compact Disc Devices

Constant	Status item

MCI_STATUS_NUMBER_OF_TRACKS	Number of tracks

MCI_STATUS_MEDIA_PRESENT	Media present

MCI_STATUS_CURRENT_TRACK	Current track

MIDI Sequencer Devices

Constant	Status item

MCI_SEQ_STATUS_TEMPO	Tempo

MCI_SEQ_STATUS_PORT	Port

MCI_SEQ_STATUS_OFFSET	SMPTE offset

MCI_SEQ_STATUS_DIVTYPE	Division type of file

Getting Track-Relative Information for Compact Disc Devices

For compact disc devices, you can get the starting position and length of a track by specifying the MCI_TRACK flag and setting the dwTrack member of the MCI_STATUS_PARMS structure to the desired track number. To get the starting position of a track, set the dwItem member to MCI_STATUS_POSITION. To get the length of a track, set dwItem to MCI_STATUS_LENGTH. The following function gets the number of tracks on the disc and the starting position of each track. It then uses the MessageBox function to report the starting positions of the tracks.

/*

 * Uses the MCI_STATUS command to get and

 * display the starting times for the tracks

 * on a compact disc. Returns 0L on success;

 * otherwise, it returns an MCI error code.

 */

DWORD getCDTrackStartTimes(void)

{

    UINT wDeviceID;

    int i, iNumTracks;

    DWORD dwReturn;

    DWORD *pMem;

    char szTempString[64];

    char szTimeString[512] = "\0"; /* enough for 20 tracks */

    MCI_OPEN_PARMS mciOpenParms;

    MCI_SET_PARMS mciSetParms;

    MCI_STATUS_PARMS mciStatusParms;

    /* Open the compact disc 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 have to close it; just return error.

         */

        return dwReturn;

    }

    /* Device opened successfully. Get the device ID. */

    wDeviceID = mciOpenParms.wDeviceID;

    /* Set the time format to minute/second/frame 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

     * we can display (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 0xFFFFFFFF;

    }

    /*

     * For each track, get and save the starting position and

     * build a string containing starting positions.

     */

    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 0;

}


Recording With Waveform Audio Devices

MCI supports recording with waveform audio devices. You can insert or overwrite recorded information in an existing file or record into a new file. To open an existing file for recording, open a waveform device and device element as you would open them for playback. To record into a new file, open the device but specify a zero-length filename for the device element.

When MCI creates a new file for recording, the waveform 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 MCI_SET command message to change the format.

To begin recording, use the MCI_RECORD command message along with the MCI_RECORD_PARMS structure.

If you record to an existing file, you can use the MCI_TO and MCI_FROM flags to specify beginning and ending points for recording. For example, if you record to an existing file 20 seconds long, and you begin recording at 5 seconds and end recording at 10 seconds, you will have a recording 25 seconds long. It will contain 5 seconds of the original recording followed by the 5 seconds of new recording, and will end with the remaining 15 seconds of the original recording.

If you don't specify an ending position, recording continues until you send an MCI_STOP command message, or until the driver runs out of free disk space. If you record to a new file, you can omit the MCI_FROM flag or set it to 0 to start recording at the beginning of a new file. You can specify an ending position to terminate recording when recording to a new file.

If you record in overwrite mode to an existing file, you can use the MCI_TO and MCI_FROM flags to specify beginning and ending points of the waveform section that is to be overwritten. For example, if you record to an existing file 20 seconds long, and you begin recording at 5 seconds and end recording at 10 seconds, you still have a recording 20 seconds long. However, the section beginning at 5 seconds and ending at 10 seconds has been replaced.

Saving a Recorded File

When recording is complete, use the MCI_SAVE command message along with the MCI_SAVE_PARMS structure to save the recording before closing the device.

If you close the device without saving, the recorded data is lost.

Checking Input Levels on PCM Devices

To get the level of the input signal before recording on a pulse code modulated (PCM) waveform input device, use the MCI_STATUS command message. Specify the MCI_STATUS_ITEM flag and set the dwItem member in the MCI_STATUS_PARMS structure to MCI_WAVE_STATUS_LEVEL. The average input signal level is returned in the dwReturn member of the MCI_STATUS_PARMS structure. 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).

Example of Recording With a Waveform Audio Device

The following example function opens a waveform audio device with a new file, records for the specified time, plays the recording, and prompts the user to specify whether the recording should be saved as a file.

/*

 * Uses the MCI_OPEN, MCI_RECORD, MCI_SAVE commands to record and

 * save a waveform audio file. Returns 0L on success; otherwise,

 * 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 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;

    }

    /* 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 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 = 0;

    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 0;

    }

    /*

     * Save the recording to a file named TEMPFILE.WAV. Wait for

     * the operation to finish 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 0;

}


Using the MCI MIDI Sequencer

The MCI MIDI sequencer plays standard MIDI files and Resource Interchange File Format (RIFF) MIDI files (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.

There are currently three variations of standard MIDI files. The MCI sequencer plays only two of these: format 0 and format 1 MIDI files.

Note:	When the MCI MIDI sequencer encounters a MIDI file not marked as being authored for Windows, it displays a dialog box informing the user. MIDI files authored for Windows should be marked with the MARKMIDI utility program. For additional information about MARKMIDI, see Using the MARKMIDI Utility.

Querying for Sequence Division Types

The division type of a MIDI sequence refers to the technique used to represent the time between MIDI events in the sequence. Use the MCI_STATUS command message and set the dwItem member of the MCI_STATUS_PARMS structure to MCI_SEQ_STATUS_DIVTYPE to determine the division type of a sequence.

If the MCI_STATUS command message succeeds, the dwReturn member of the MCI_STATUS_PARMS structure contains 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 frames per second (fps)

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 can't change the division type of a sequence by using the MCI sequencer.

Querying and Setting the Tempo

Use the MCI_STATUS command message and set the dwItem member of the MCI_STATUS_PARMS structure to MCI_SEQ_STATUS_TEMPO to get the tempo of a sequence. If the MCI_STATUS command message succeeds, the dwReturn member of the MCI_STATUS_PARMS structure contains the current tempo.

To change tempo, use the MCI_SET command message with the MCI_SEQ_SET_PARMS structure. Specify the MCI_SEQ_SET_TEMPO flag and set the value of 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, Querying for Sequence Division Types.

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


The MIDI Mapper

The MIDI Mapper's standard patch services provide device-independent MIDI file playback for applications. You don't need to understand exactly how the MIDI Mapper works to use these services. The MIDI Mapper can be used with the MCI MIDI sequencer or with low-level MIDI output services.

To learn more about the MIDI Mapper or about authoring standard MIDI files for Windows, read this section to become familiar with how the MIDI Mapper works.


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 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 specify 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 can't 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

^ 1The high-order four bits represent the status value. The low-order four bits represent the channel information.

^ 2Patch maps affect only controller 7 (main volume).

^ 3System messages are sent to all devices listed in a channel map.


Authoring MIDI Files

The "MIDI 1.0 Detailed Specification" does not define any standard patch assignments for synthesizers. Therefore, when you create a MIDI file, it won't be reproduced correctly unless it is played back on the same MIDI synthesizer setup used to create it. For example, if you create a piano concerto for your Yamaha® DX7 and try to play it back on a Roland® LAPC-1, it may be played with a flute instead of a piano.

To enable MIDI files to be a viable format for representing music in multimedia computing, Windows provides MIDI authoring guidelines. These guidelines include a list of standard patch assignments and standard key assignments for percussion instruments. Using the MIDI Mapper, MIDI files authored in accordance with these guidelines can be played on any multimedia computer with internal or external MIDI synthesizers.


About Base-Level and Extended Synthesizers

Although it is difficult to clearly quantify distinctions between synthesizers, it is important to have some guidelines so you can create MIDI files that will play on all multimedia computers. The terms used to distinguish synthesizers for the purpose of authoring MIDI files are base-level synthesizer and extended synthesizer.

The distinctions between base-level and extended synthesizers are made solely on the number of instruments and notes the synthesizer can play, not on the quality or the cost of the synthesizer. Following are the minimum capabilities of base-level and extended synthesizers.

Synthesizer	Melodic instruments		Percussive instruments
	Number	Polyphony	Number	Polyphony
Base-level	3 instruments	6 notes	3 instruments	3 notes
Extended	9 instruments	16 notes	8 instruments	16 notes
Polyphony is the number of notes the synthesizer can play simultaneously. The polyphony expressed above applies to each group of instruments--melodic and percussive. For example, a base-level synthesizer is capable of playing six notes distributed among three melodic instruments and three notes distributed among three percussive instruments. Each melodic instrument is on a different MIDI channel; the percussive instruments are key-based--all on a single MIDI channel.

All multimedia computers provide at least a base-level synthesizer. Users can enhance their computer by adding internal or external synthesizers, which can be either base-level or extended synthesizers. When adding a synthesizer, the user must configure the MIDI Mapper to use the new device. If the MIDI Mapper is not configured, the instrument sounds will be incorrect when MIDI files are played, unless the application has the ability to send output directly to an internal synthesizer or output port. The MIDI Control Panel option allows a user to configure the MIDI Mapper as needed.


Authoring Guidelines for MIDI Files

Follow these guidelines to author device-independent MIDI files for Windows:

Author for both base-level and extended synthesizer setups.

Use MIDI channels 13 through 16 for base-level synthesizer data (reserve channel 16 for key-based percussion instruments).

Use MIDI channels 1 through 10 for extended synthesizer data (reserve channel 10 for key-based percussion instruments).

Prioritize MIDI data by putting crucial data in the lower-numbered channels.

Limit the polyphony of nonpercussive channels to a total of 6 notes for base-level data and 16 notes for extended data.

Limit the polyphony of percussive channels to a total of 3 notes for base-level data and 16 notes for extended data.

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.

Use the MARKMIDI utility program to mark MIDI files authored for Windows.

The following illustration summarizes the use of the 16 MIDI channels in a standard MIDI file authored for Windows.

Prioritizing MIDI Data

Synthesizers don't always fall cleanly into the base-level and extended designations defined earlier. It's up to the user to determine how to use synthesizers that are capable of more than the base-level requirements but do not fully meet the extended requirements. For this reason, it's important to prioritize the melodic data by putting the most critical data in lower-numbered channels. For example, a user may have a synthesizer capable of playing six melodic instruments with 12-note polyphony. The user can use this device as an extended synthesizer by setting up the MIDI Mapper to play only the first six melodic channels and ignore any information on channels 7, 8, and 9.


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 the MARKMIDI Utility

The MARKMIDI utility program marks MIDI files as following the authoring guidelines for Windows MIDI files. The program does not verify that the file is authored correctly; it only marks the file by adding a sequencer-specific meta-event to the first track chunk. MARKMIDI has the following command syntax.

MARKMIDI src-filename dest-filename

If the MCI MIDI sequencer is used to play a MIDI file not marked by MARKMIDI, it displays a dialog box informing the user that the file is not authored for Windows.

Note:	Do not use MARKMIDI to mark MIDI files unless the files were authored according to the guidelines presented in this topic. If your application uses MIDI files not authored to these guidelines, the application must instruct users to install or create the proper maps by using the MIDI Mapper Control Panel application. For example, if your application uses MIDI files following the General MIDI channel recommendations, your users should create or install a General MIDI map for their synthesizers.


Low-Level Audio Overview

Low-Level Audio

This topic explains how to use the low-level audio services of Microsoft® Windows™ to manage playback and recording of waveform and Musical Instrument Digital Interface (MIDI) audio.

For an overview of Microsoft® Windows™ audio services, see Introduction to Audio. For a discussion of high-level audio services, see, High-Level Audio.

The following topics discuss the low-level audio services:

Function Prefixes

Using Low-Level Audio Services

Querying Audio Devices

Opening and Closing Device Drivers

Allocating and Preparing Audio Data Blocks

Managing Audio Data Blocks

Using the MMTIME Structure

Handling Errors With Audio Functions

Playing Waveform Audio

Waveform Output Data Types

Querying Waveform Output Devices

Opening Waveform Output Devices

Specifying Waveform Data Formats

Writing Waveform Data

Getting the Current Playback Position

Stopping, Pausing, and Restarting Playback

Closing Waveform Output Devices

Changing Waveform Playback Volume

Changing Pitch and Playback Rate

Recording Waveform Audio

Waveform Input Data Types

Querying Waveform Input Devices

Opening Waveform Input Devices

Managing Waveform Recording

Playing MIDI Audio

MIDI Output Data Types

Querying MIDI Output Devices

Opening MIDI Output Devices

Sending MIDI Messages

Sending Buffered Messages

Sending MIDI Messages Using Running-Status

Resetting MIDI Output

Changing Internal MIDI Synthesizer Volume

Preloading Patches With Internal MIDI Synthesizers

Using the MIDI Mapper With Low-Level MIDI Functions

Recording MIDI Audio

MIDI Input Data Types

Querying MIDI Input Devices

Opening MIDI Input Devices

Managing MIDI Recording

Receiving Time-Stamped MIDI Messages

Receiving Running-Status Messages

Auxiliary Audio Devices

Querying Auxiliary Audio Devices

Changing Auxiliary Audio-Device Volume

Audio Clipboard Formats

You should have a basic knowledge of digital audio and MIDI before reading this topic. If you need additional information on these subjects, see Introduction to Audio.


Function Prefixes

Low-level audio function names begin with the following prefixes.

Prefix	Description

aux	Auxiliary audio functions

midi	MIDI audio functions

wave	Waveform audio functions


Using Low-Level Audio Services

Low-level audio services control different types of audio devices, including waveform, MIDI, and auxiliary audio devices. Many of the concepts for using low-level services apply to more than one type of device. This section presents general information on using low-level audio services. It covers the following topics:

Querying audio devices

Opening and closing device drivers

Allocating and preparing audio data blocks

Managing audio data blocks

Using the MMTIME structure

Handling errors

Subsequent sections in this topic discuss the use of specific types of audio devices.


Querying Audio Devices

Before playing or recording audio, you must determine the capabilities of the audio hardware present in the system. Audio capability can vary from one multimedia computer to the next; applications should not make assumptions about the audio hardware present in a given system.

Getting the Number of Devices

The Win32 application programming interface (API) provides the following functions to determine how many devices of a certain type are available in a given system.

Function	Description

auxGetNumDevs	Retrieves the number of auxiliary audio devices present in the 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.

waveInGetNumDevs	Retrieves the number of waveform input devices present in the system.

waveOutGetNumDevs	Retrieves the number of waveform 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 given system. Device identifiers range from zero to one less than the number of devices present. For example, if there are two MIDI output devices in a system, valid device identifiers are 0 and 1.

Getting the Capabilities of a Device

After you determine how many devices of a certain type are present in a system, you can inquire about the capabilities of each device. The Win32 API provides the following functions to determine the capabilities of audio devices.

Function	Description

auxGetDevCaps	Retrieves the capabilities of a given auxiliary audio device.

midiInGetDevCaps	Retrieves the capabilities of a given MIDI input device.

midiOutGetDevCaps	Retrieves the capabilities of a given MIDI output device.

waveInGetDevCaps	Retrieves the capabilities of a given waveform input device.

waveOutGetDevCaps	Retrieves the capabilities of a given waveform output device.

Each of these functions takes a pointer to a structure that it fills with information on the capabilities of a specified device. Following are the structures that correspond to each of the device-inquiry functions.

Function	Structure

auxGetDevCaps	AUXCAPS

midiInGetDevCaps	MIDIINCAPS

midiOutGetDevCaps	MIDIOUTCAPS

waveInGetDevCaps	WAVEINCAPS

waveOutGetDevCaps	WAVEOUTCAPS


Opening and Closing Device Drivers

After getting the capabilities of an audio device, you must open the device before you can use it. Audio devices aren't guaranteed to be shareable, so a particular device might not be available when you request it. If this happens, you should notify the user and allow the user to try to open the device again. When you open an audio device, be sure to close it as soon as you finish using it.

The Win32 API provides the following functions to open and close different types of audio devices.

Function	Description

midiInOpen	Opens a specified MIDI input device for recording.

midiInClose	Closes a specified MIDI input device.

midiOutOpen	Opens a MIDI output device for playback.

midiOutClose	Closes a specified MIDI output device.

waveInOpen	Opens a waveform input device for recording.

waveInClose	Closes a specified waveform input device.

waveOutOpen	Opens a waveform output device for playback.

waveOutClose	Closes a specified waveform output device.

These functions are discussed in detail later in this topic.

About Device Handles

Each function that opens an audio device takes as parameters a device identifier, a pointer to a memory location, and some parameters unique to each type of device. The memory location is filled with a device handle. Use this device handle of identify the open audio device when calling other audio functions.

The distinction between audio-device identifiers and audio-device handles is subtle, but very important. Don't confuse the two in your application. Following are the differences between device identifiers and device handles.

Device identifiers are determined implicitly from the number of devices present in a system, which is obtained by using the device-numbering functions (auxGetNumDevs, midiInGetNumDevs, and so on).

Device handles are returned when device drivers are opened by using the device-opening functions (midiInOpen, midiOutOpen, and so on)

The only functions that take device identifiers as parameters are the device-capabilities functions (waveOutGetDevCaps, midiInGetDevCaps, and so on), the device-opening functions, and volume functions (waveOutGetVolume, waveOutSetVolume, and so on). All other functions take device handles.

There are no functions for opening and closing auxiliary audio devices. Auxiliary audio devices don't need to be opened and closed like MIDI and waveform devices because there is no continuous data transfer associated with them. All auxiliary audio functions take device identifiers to identify devices.


Allocating and Preparing Audio Data Blocks

Some low-level audio functions require applications to allocate data blocks to pass to the device drivers for playback or recording purposes. Each of these functions uses a structure (or header) to describe its data block. The following table identifies these functions and their associated header structures. (The MMSYSTEM.H file defines the data structures for these headers.)

Function	Header structure	Purpose

waveOutWrite	WAVEHDR	Waveform playback

waveInAddBuffer	WAVEHDR	Waveform recording

midiOutLongMsg	MIDIHDR	MIDI system-exclusive playback

midiInAddBuffer	MIDIHDR	MIDI system-exclusive recording

Before you use one of the functions listed above to pass a data block to a device driver, you must allocate memory for the data block according to the guidelines discussed in the following sections of this topic.

Allocating Memory for Audio Data Blocks

Before preparing a data block, you must allocate memory for the data block and the header structure that describes the data block.

To allocate memory, use the GlobalAlloc function with the GMEM_MOVEABLE flag to get a handle of the memory object. Then pass this handle of the GlobalLock function to get a pointer to the memory object.

To free a data block, use GlobalUnlock and GlobalFree.

Preparing Audio Data Blocks

Before you pass an audio data block to a device driver, you must prepare the data block by passing it to a header-preparation function. 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 a header clean-up function before any allocated memory can be freed.

Windows provides the following functions for preparing and cleaning up audio data blocks.

Function	Description

midiInPrepareHeader	Prepares a MIDI-input data block.

midiInUnprepareHeader	Cleans up the preparation on a MIDI-input data block.

midiOutPrepareHeader	Prepares a MIDI-output data block.

midiOutUnprepareHeader	Cleans up the preparation on a MIDI-output data block.

waveInPrepareHeader	Prepares a waveform-input data block.

waveInUnprepareHeader	Cleans up the preparation on a waveform-input data block.

waveOutPrepareHeader	Prepares a waveform-output data block.

waveOutUnprepareHeader	Cleans up the preparation on a waveform-output data block.


Managing Audio Data Blocks

Unless the audio 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. This is true for waveform input and output, and for MIDI system-exclusive input messages. Regular MIDI channel messages don't require data blocks for input or output.

Even if a single data block is used, applications 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 three ways to determine when a device driver is finished with a data block:

Specify a window to receive a message sent by the driver when it 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.

Poll a bit in the dwFlags member of the WAVEHDR or MIDIHDR data structure sent with each data block.

If an application doesn't 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. Use a double-buffering scheme to stay at least one data block ahead of the device driver.

Note:	To get time-stamped MIDI input data, you must use a callback function.

Using a Window to Process Driver Messages

The easiest type of callback function to use to process driver messages is a window callback. To use a window callback, specify the CALLBACK_WINDOW flag in the dwFlags parameter and a window handle as the dwCallback parameter of the device-opening function. Driver messages will be sent to the window-procedure function for the window identified by the handle in dwCallback.

Messages sent to the window function are specific to the audio device type used. For details on these messages, see the sections later in this topic on using window messages for each specific audio device type.

Using a Callback Function to Process Driver Messages

You can also write your own low-level callback function to process messages sent by the device driver. To use a low-level callback function, specify the CALLBACK_FUNCTION flag in the dwFlags parameter and the address of the callback in the dwCallback parameter of the device-opening function.

Messages sent to a callback function are similar to messages sent to a window, except that they have two doubleword parameters instead of one unsigned-integer and one doubleword parameter. For details on these messages, see the sections later in this topic about using low-level callbacks for each specific audio device type.

Callback functions for the low-level audio services are often called from another thread running asynchronously from the application's thread. It is therefore important to use critical sections to protect data shared between the callback routine and the rest of the application. For more information about critical sections, see Synchronization.

There are several differences between callback functions for the low-level audio services under Windows NT and under Windows 3.1:

Under Windows 3.1, a low-level audio callback function is called at interrupt time. The call to a low-level audio callback function occurs on a separate thread under Windows NT.

Under Windows 3.1, a low-level audio callback function has to be in a dynamic link library. Under Windows NT, there is no such restriction.

Under Windows 3.1, a low-level audio callback function must be exported in a .DEF file. Under Windows NT, that is not necessary.

If source code must be compatible with Windows 3.1, it should follow the Windows 3.1 rules as noted briefly above and specified more fully in the Windows 3.1 documentation.

One other item should be noted carefully. There is a limited set of APIs that a Windows 3.1 low-level audio callback function may call. In Win32, that strict limitation has been removed. However, it is strongly recommended that a Windows NT low-level audio callback function restrain its calls to a similar set of APIs. Here is the Windows NT recommended list:

EnterCriticalSection	Release Semaphore

LeaveCriticalSection	SetEvent

midiOutLongMsg	timeGetSystemTime

midiOutShortMsg	timeGetTime

OutputDebugString	timeKillEvent

PostMessage	timeSetEvent

PostThreadMessage	" "

If an application's low-level audio callback function does stray from this list, it should be careful not to call APIs that take a long time to complete.

In particular, calling wave and midi APIs may result in a deadlock.

If a Win32 low-level audio callback shares data with other code, a Critical Section  or similar mutual exclusion mechanism should be used to protect the integrity of the data.

Use one of the following techniques to pass instance data from an application to a low-level callback function residing in a dynamic link library:

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 and MIDIHDR structures that identify 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.

Managing Data Blocks by Polling

In addition to using a callback function, you can poll the dwFlags member of a WAVEHDR or MIDIHDR structure to determine when an audio device is finished with a data block. There are times when it's better to poll dwFlags rather than wait for a window to receive messages from the drivers. For example, immediately after you call the waveOutReset function to release pending data blocks, you can poll to be sure that the data blocks are indeed done before proceeding to call the waveOutUnprepareHeader function and free the memory for the data block.

MMSYSTEM.H defines two flags for testing the dwFlags member: WHDR_DONE for a WAVEHDR structure, and MHDR_DONE for a MIDIHDR structure.


Using the MMTIME Structure

Windows uses a structure called MMTIME to represent time. Low-level audio functions that use MMTIME include waveInGetPosition and waveOutGetPosition. The timeGetSystemTime function also uses MMTIME to represent system time.

Setting the Time Format

MMTIME can represent time in one or more different formats including milliseconds, samples, Society of Motion Picture and Television Engineers (SMPTE), 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 the wType member to indicate your requested time format. Be sure to check wType after the call to see if the requested time format is supported. 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. MMSYSTEM.H defines the following flags for the wType member of the MMTIME structure.

Flag	Description

TIME_MS	Milliseconds

TIME_SAMPLES	Number of waveform audio samples

TIME_BYTES	Number of waveform audio bytes

TIME_SMPTE	SMPTE time

TIME_MIDI	MIDI song-position pointer

For details on using MMTIME with the waveOutGetPosition function, see Getting the Current Playback Position.

Getting the System Time

Use the timeGetSystemTime or timeGetTime function to get the system time. System time is defined as the time (in milliseconds) since Windows was started. For more information on timeGetSystemTime and timeGetTime, see Multimedia Timers.


Handling Errors With Audio Functions

Low-level audio functions return a nonzero error code. The multimedia extensions provide a set of functions that convert these error codes into a textual description of the error. The application must still look at the error value itself to determine how to proceed, but textual descriptions of errors can be used in dialog boxes describing errors to users.

The following functions can be used to get textual descriptions of low-level audio errors.

Function	Description

midiInGetErrorText	Retrieves a textual description of a specified MIDI input error.

midiOutGetErrorText	Retrieves a textual description of a specified MIDI output error.

waveInGetErrorText	Retrieves a textual description of a specified waveform input error.

waveOutGetErrorText	Retrieves a textual description of a specified waveform output error.

The only low-level audio functions that don't return error codes are the device-numbering functions (auxGetNumDevs, midiInGetNumDevs, and so on). 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 Waveform Audio

If your application plays waveform audio, you can use the Media Control Interface (MCI) to control waveform output devices. If the MCI waveform playback services don't meet the needs of your application, you can manage waveform playback by using the low-level waveform services.


Waveform Output Data Types

The MMSYSTEM.H header file defines data types and function prototypes for all of the audio functions. You must include this header file in any source-code module that uses these functions. MMSYSTEM.H defines the following data types for the waveform output functions.

Type	Description

HWAVEOUT	Handle of an open waveform output device.

WAVEOUTCAPS	Structure used to inquire about the capabilities of a particular waveform output device.

WAVEFORMAT	Structure that specifies the data formats supported by a particular waveform output device. This structure is also used for waveform input devices.

WAVEHDR	Structure that is a header for a block of waveform output data. This structure is also used for waveform input devices.


Querying Waveform Output Devices

Before playing a waveform, call the waveOutGetDevCaps function to determine the waveform output capabilities of the playback device as described earlier in this topic. This function takes a pointer to a WAVEOUTCAPS structure, which it fills with information about the capabilities of a given 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 WAVEOUTCAPS structure provides information on the standard waveform formats and features supported by the device driver.

Determining Standard Format Support

The dwFormats member of the WAVEOUTCAPS structure specifies the standard waveform formats supported by a device. The MMSYSTEM.H header file defines the following standard waveform format identifiers for the dwFormats member.

Format identifier	Waveform format

WAVE_FORMAT_1M08	8-bit mono at 11.025 kHz

WAVE_FORMAT_1S08	8-bit stereo at 11.025 kHz

WAVE_FORMAT_1M16	16-bit mono at 11.025 kHz

WAVE_FORMAT_1S16	16-bit stereo at 11.025 kHz

WAVE_FORMAT_2M08	8-bit mono at 22.05 kHz

WAVE_FORMAT_2S08	8-bit stereo at 22.05 kHz

WAVE_FORMAT_2M16	16-bit mono at 22.05 kHz

WAVE_FORMAT_2S16	16-bit stereo at 22.05 kHz

WAVE_FORMAT_4M08	8-bit mono at 44.1 kHz

WAVE_FORMAT_4S08	8-bit stereo at 44.1 kHz

WAVE_FORMAT_4M16	16-bit mono at 44.1 kHz

WAVE_FORMAT_4S16	16-bit stereo at 44.1 kHz

The value of the dwFormats member is the result of a logical OR operation on the flags listed above.

This information on standard-format support also applies to the WAVEINCAPS structure used with waveform input devices. For information about the WAVEINCAPS structure, see Querying Waveform Input Devices.

To determine whether a specific format is supported by a device, use the waveOutOpen function with the WAVE_FORMAT_QUERY flag as shown in the next section.

Determining Nonstandard Format Support

Waveform devices can support nonstandard formats not listed in the preceding table. To see whether a particular format (standard or nonstandard) is supported by a device, you can call the waveOutOpen function with the WAVE_FORMAT_QUERY flag. The WAVE_FORMAT_QUERY flag tells waveOutOpen to check whether the requested format is supported. The wave device is not actually opened. The requested format is specified by the structure pointed to by the lpFormat parameter passed to waveOutOpen. For information about setting up this structure, see Specifying Waveform Data Formats. The following example uses this technique to determine whether a given waveform device supports a given format.

/*

 * Determines whether the given waveform output device supports

 * a given wave-form format. Returns 0 if the format is supported,

 * WAVEERR_BADFORMAT if the format is not supported, and one of

 * the MMSYSERR_ error codes if there are other errors in opening

 * the given waveform device.

 */

UINT IsFormatSupported(LPPCMWAVEFORMAT lpPCMWaveFormat,

    UINT wDeviceID)

{

    return (waveOutOpen(

            NULL,                           // NULL for query

            wDeviceID,                      // device identifier

            (LPWAVEFORMAT)lpPCMWaveFormat,  // requested format

            NULL,                           // no callback

            NULL,                           // no instance data

            WAVE_FORMAT_QUERY));            // query only

}

This technique to determine nonstandard format support also applies to waveform input devices. The only difference is that the waveInOpen function is used in place of waveOutOpen to query for format support.

Note:	To determine whether a particular waveform-data format is supported by any of the waveform devices in a system, use the technique illustrated in the previous example, but specify the WAVE_MAPPER constant for the wDeviceID parameter. For more information about using the WAVE_MAPPER constant, see Selecting a Waveform Output Device.

Determining Capabilities of Waveform Output Devices

Waveform output devices vary in the capabilities they support. The dwSupport member of the WAVEOUTCAPS structure indicates whether a given device supports capabilities such as volume and pitch changes. MMSYSTEM.H defines the following flags for the dwSupport member.

Flag	Description

WAVECAPS_PITCH	Pitch-change support

WAVECAPS_PLAYBACKRATE	Playback-rate-change support

WAVECAPS_VOLUME	Volume-control support

WAVECAPS_LRVOLUME	Individual volume-control support for both left and right channels

The dwSupport member is a logical OR of the flags listed in the preceding table.

For more information about playback volume levels, see Changing Waveform Playback Volume. For more information about pitch and playback rates, see Changing Pitch and Playback Rate.


Opening Waveform Output Devices

Use the waveOutOpen function to open a waveform 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.

Selecting a Waveform Output Device

Some multimedia computers have multiple waveform output devices. Unless you know you want to open a specific waveform output device in a system, you should use the WAVE_MAPPER constant for the device identifier when you open a device. The waveOutOpen function chooses the device in the system best capable of playing the given data format.


Specifying Waveform Data Formats

When you call the waveOutOpen function to open a device driver for playback or determine whether the driver supports a particular data format, use the lpFormat parameter to specify a pointer to a structure containing the requested waveform data format.

The WAVEFORMAT structure specifies format information common to all types of waveform data formats. Currently the only format supported is pulse code modulated (PCM), but in the future other types such as adaptive differential pulse code modualtion (ADPCM) may be supported.

In addition to the general information in the WAVEFORMAT structure, specific information is needed to describe a PCM waveform data format completely. For PCM waveform data, the PCMWAVEFORMAT structure includes a WAVEFORMAT structure along with an additional member containing PCM-specific information.

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 given 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);

Getting Format Information From a WAVE File

The easiest way to get waveform-format information from a WAVE file is by using the multimedia file input and output (I/O) services. To do this, use the mmioDescend function to locate the "fmt" chunk containing the format information and the mmioRead function to read the format chunk directly into the proper format structure. (Chunks are the basic building blocks of RIFF files.) The following example illustrates this technique. For more information about multimedia file I/O, see Multimedia File Input and Output.

void GetFormatInfo(void)

{

    HMMIO       hmmio;

    MMCKINFO    mmckinfoParent;

    MMCKINFO    mmckinfoSubchunk;

    DWORD       dwFmtSize;

    HANDLE      hFormat;

    WAVEFORMAT  *pFormat;

        .

        .

        .

    /* Open the given file for reading using buffered I/O. */

        ...

    /*

     * Locate a "RIFF" chunk with a "WAVE" form type

     * to make sure it's a WAVE file.

     */

        ...

    /*

     * Now, 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)) {

        MessageBox(hwndApp, "WAVE file is corrupted.",

            NULL, MB_OK | MB_ICONEXCLAMATION);

        mmioClose(hmmio, 0);

        return;

    }

    /*

     * Get the size of the format chunk;

     * allocate and lock memory for it.

     */

    dwFmtSize = mmckinfoSubchunk.cksize;

    hFormat = LocalAlloc(LMEM_MOVEABLE, dwFmtSize);

    if (hFormat == NULL) {

        MessageBox(hwndApp, "Out of memory.",

            NULL, MB_OK | MB_ICONEXCLAMATION);

        mmioClose(hmmio, 0);

        return;

    }

    pFormat = (WAVEFORMAT *) LocalLock(hFormat);

    if (pFormat == NULL) {

        MessageBox(hwndApp, "Failed to lock memory for format chunk.",

            NULL, MB_OK | MB_ICONEXCLAMATION);

        LocalFree(hFormat);

        mmioClose(hmmio, 0);

        return;

    }

    /* Read the format chunk. */

    if (mmioRead(hmmio, (LPSTR)pFormat,

                dwFmtSize) != (LRESULT)dwFmtSize) {

        MessageBox(hwndApp, "Failed to read format chunk.",

            NULL, MB_OK | MB_ICONEXCLAMATION);

        LocalUnlock(hFormat);

        LocalFree(hFormat);

        mmioClose(hmmio, 0);

        return;

    }

    /* Make sure it's a PCM file. */

    if (pFormat->wFormatTag != WAVE_FORMAT_PCM) {

        LocalUnlock(hFormat);

        LocalFree(hFormat);

        mmioClose(hmmio, 0);

        MessageBox(hwndApp, "The file is not a PCM file.",

            NULL, MB_OK | MB_ICONEXCLAMATION);

        return;

    }

    /*

     * Make sure the system has a waveform output

     * device capable of playing this format.

     */

    if (waveOutOpen(&hWaveOut, WAVE_MAPPER, (LPWAVEFORMAT)pFormat,

                NULL, 0L, WAVE_FORMAT_QUERY)) {

        LocalUnlock(hFormat);

        LocalFree(hFormat);

        mmioClose(hmmio, 0);

        MessageBox(hwndApp,

            "The waveform device can't play this format.",

            NULL, MB_OK | MB_ICONEXCLAMATION);

        return;

    }

    .

    .

    .

}


Writing Waveform Data

After successfully opening a waveform output device driver, you can begin waveform playback.

The waveOutWrite function writes a data block to a waveform output device. Use the WAVEHDR structure to specify the waveform data block you are sending. This structure contains a pointer to a locked data block, the length of the data block, and assorted flags.

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 system for the completion of each data block so that you know when to send additional blocks. For details about different techniques for monitoring data block completion, see Managing Audio Data Blocks.

Example of Writing Waveform Data

The following example illustrates the steps required to allocate and set up a WAVEHDR data structure and write a block of data to a waveform output device.

/*

 * Global variables. Must be visible to window-procedure function

 *  so it can unlock and free the data block after it has been played.

 */

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. The memory

     * for waveform data must be globally allocated with

     * GMEM_MOVEABLE and GMEM_SHARE flags.

     */

    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. This memory must

     * also be globally allocated with GMEM_MOVEABLE and

     * GMEM_SHARE flags.

     */

    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;

    }

    .

    .

    .

}

PCM Waveform Data Format

The lpData member in the WAVEHDR structure points to the waveform 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 data.

Data format	Maximum value	Minimum value	Midpoint value

8-bit PCM	255 (0xFF)	0	128 (0x80)

16-bit PCM	32767 (0x7FFF)	-32768 (0x8000)	0

The order of the data bytes varies between 8-bit and 16-bit, and between mono and stereo formats. The following tables show data packing for the first four words of different PCM waveform data formats.

Data packing for 8-bit mono PCM:

Sample 1	Sample 2	Sample 3	Sample 4

Channel 0	Channel 0	Channel 0	Channel 0

Data packing for 8-bit stereo PCM:

             Sample 1	             Sample 2

Channel 0 (left)	Channel 1 (right)	Channel 0 (left)	"Channel 1 (right)"

Low-order byte	High-order byte	Low-order byte	High-order byte

Data packing for 16-bit mono PCM:

Sample 1	Sample 2

Channel  0  low byte	Channel  0  high byte	Channel  0  low byte	Channel  0  high byte

Data packing for 16-bit stereo PCM:

Sample 1
Channel 0 (left)  low byte	Channel 0 (left)  high byte	Channel 1 (right)  low byte	Channel 1 (right)  high byte
Waveform Looping

Waveform looping is controlled by the dwLoops and dwFlags members in the WAVEHDR structures passed to the device with waveOutWrite. 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. To specify the number of loops, use the dwLoops member in the WAVEHDR structure for the first block in the loop.

You can stop waveform looping with the waveOutBreakLoop function. The blocks making up the loop are played to the end before the loop is stopped.

Using Window Messages to Manage Waveform Playback

The following messages can be sent to a window-procedure function for managing waveform playback.

Message	Description

MM_WOM_CLOSE	Sent when the device is closed using waveOutClose.

MM_WOM_DONE	Sent when the device driver is finished with a data block sent using waveOutWrite.

MM_WOM_OPEN	Sent when the device is opened using waveOutOpen.

A wParam and lParam parameter is associated with each of these messages. The wParam parameter always specifies a handle of the open waveform device. For the MM_WOM_DONE message, lParam specifies a pointer to a WAVEHDR structure identifying the completed data block. The lParam parameter is unused for the MM_WOM_CLOSE and MM_WOM_OPEN messages.

The most useful message is 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 don't need to process the MM_WOM_OPEN and MM_WOM_CLOSE messages.

The following example shows how to process the MM_WOM_DONE message. The 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 function. */

LRESULT WndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam)

{

    switch (msg) {

        .

        .

        .

        case MM_WOM_DONE:

        /* A data block has been played and can now be freed. */

            waveOutUnprepareHeader((HWAVEOUT) wParam,

                (LPWAVEHDR) lParam, sizeof(WAVEHDR) );

            GlobalUnlock(hData);

            GlobalFree(hData);

            waveOutClose((HWAVEOUT) wParam);

            break;

    }

    return DefWindowProc(hWnd,msg,wParam,lParam);

}

Using a Low-Level Callback Function to Manage Waveform Playback

The syntax of the low-level callback function for waveform output devices is as follows:

void CALLBACK waveOutCallback(hWaveOut, wMsg,

     dwInstance, dwParam1, dwParam2)

The following messages can be sent in the wMsg parameter of waveform output callback functions.

Message	Description

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.

These messages are similar to the messages sent to window-procedure functions, the parameters are different. A handle of the open waveform device is passed as a parameter to the callback function, along with the doubleword of instance data that was passed using waveOutOpen.

The callback function has two message-dependent parameters: dwParam1 and dwParam2. For the WOM_DONE message, dwParam1 specifies a pointer to a WAVEHDR structure identifying the completed data block and dwParam2 is not used. For the WOM_OPEN and WOM_CLOSE messages, neither of the parameters is used.

After the driver is finished with a data block, you can clean up and free the data block, as described in Allocating and Preparing Audio Data Blocks. Because of the suggested restrictions on low-level audio callback functions, it is better to not do this from within the callback. See Using a Callback Function to Process Driver Messages for details about suggested restrictions on using callback functions.


Getting the Current Playback Position

While a waveform is playing, you can monitor the current playback position within the waveform. The Win32 API provides the waveOutGetPosition function for this purpose.

This function takes three parameters: a handle of a waveform output device, a pointer to an MMTIME structure, and an unsigned integer specifying the size of the MMTIME structure.

For waveform devices, the preferred time format in which to represent the current position is samples. Thus the current position of a waveform device is specified as the number of samples for one channel from the beginning of the waveform.

To query the current position of a waveform device, set the wType member of the MMTIME structure to TIME_SAMPLES and pass the structure to waveOutGetPosition.


Stopping, Pausing, and Restarting Playback

You can stop or pause playback while a waveform is playing. Once playback has been paused, you can restart it. The Win32 API provides the following functions for controlling waveform playback.

Function	Description

waveOutPause	Pauses playback on a waveform output device.

waveOutReset	Stops playback on a waveform output device and marks all pending data blocks as done.

waveOutRestart	Resumes playback on a paused waveform output device.

Use the waveOutPause function to pause a waveform device that is currently playing. To resume playback on a paused device, use the waveOutRestart function. These functions take a single parameter: the waveform output device handle returned by the waveOutOpen function. Pausing a waveform device may not be instantaneous--the driver can finish playing the current block before pausing playback.

Typically, as soon as the first waveform data block is sent by using the waveOutWrite function, the waveform device begins playing. If you don't want the waveform to start playing immediately, call waveOutPause before calling waveOutWrite. When you want to begin playing the waveform, call waveOutRestart.

To stop a waveform from playing, use the waveOutReset function. This function differs from waveOutPause in that it also marks all pending data blocks as being done. You can not use waveOutRestart to restart a device that has been stopped by using waveOutReset. You must use waveOutWrite to send the first data block to resume playback on the device.


Closing Waveform Output Devices

After waveform playback is complete, call the waveOutClose function to close the waveform device. If waveOutClose is called while a waveform is playing, the close operation fails and the function returns an error code indicating that the device was not closed. If you don't want to wait for playback to end before closing the device, call the waveOutReset function before closing. This stops playback and allows the device to be closed. Be sure to clean up the preparation on all data blocks before closing the waveform output device.


Changing Waveform Playback Volume

Windows provides the following functions to query and set the volume level of waveform output devices.

Function	Description

waveOutGetVolume	Gets the volume level of the specified waveform device.

waveOutSetVolume	Sets the volume level of the specified waveform device.

Not all waveform devices support volume changes. Some devices support individual volume control on both the left and right channels. See Determining Capabilities of Waveform Output Devices for information about how to determine the volume-control capabilities of waveform devices.

Note:	Unless your application is designed to be a master volume-control application providing the user with volume control for all audio devices in a system, be sure that your application opens an audio device before changing its volume. Also, be sure your application queries the volume level before changing it and restores the volume level to its previous level as soon as possible.

Volume is specified in a doubleword value of which the high-order 16 bits specify the relative volume of the right channel, and the low-order 16 bits specify the relative volume of the left (or mono) channel.

For devices that don't support left- and right-channel volume control, the low-order 16 bits specify the volume level, and the high-order 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.

The waveOutGetVolume function returns the volume as a doubleword value at an address specified by a pointer parameter.


Changing Pitch and Playback Rate

Some waveform output devices can vary the pitch and the playback rate of waveform data. Not all waveform devices support pitch and playback-rate changes. See Determining Capabilities of Waveform Output Devices for information about how to determine if a particular waveform device supports pitch and playback-rate changes.

Following are the differences between changing pitch and playback rate:

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 pitch and playback rates.

Function	Description

waveOutGetPitch	Gets the pitch for the specified waveform output device.

waveOutGetPlaybackRate	Gets the playback rate for the specified waveform output device.

waveOutSetPitch	Sets the pitch for the specified waveform output device.

waveOutSetPlaybackRate	Sets the playback rate for the specified waveform output device.

The pitch and playback rates are changed by a factor specified with a fixed-point number packed into a doubleword value. The high-order 16 bits specify the integer part, and the low-order 16 bits specify the fractional part of the number. 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-recording services don't meet the needs of your application, you can handle waveform recording using the low-level waveform services.


Waveform Input Data Types

The MMSYSTEM.H header file defines data types and function prototypes for all of the audio functions. You must include this header file in any source-code module that uses these functions. MMSYSTEM.H defines the following data types for waveform-input functions.

Type	Description

HWAVEIN	Handle of an open waveform input device.

WAVEINCAPS	Data structure used to inquire about the capabilities of a particular waveform input device.

WAVEFORMAT	Structure that specifies the data formats supported by a particular waveform input device. This structure is also used for waveform output devices.

WAVEHDR	Structure that is a header for a block of waveform input data. This structure is also used for waveform output devices.


Querying Waveform Input Devices

Before recording a waveform, you should call the waveInGetDevCaps function to determine the waveform input capabilities of the system. This function takes a pointer to a WAVEINCAPS structure that it fills with information about the capabilities of a given 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 formats that the device supports.


Opening Waveform Input Devices

Use the waveInOpen function to open a waveform 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.

Selecting a Waveform Input Device

Some multimedia computers will have multiple waveform input devices. Unless you know you want to open a specific waveform input device in a system, you should use the WAVE_MAPPER constant for the device identifier when you open a device. The waveOutOpen function will choose the device in the system best able to record in the given data format.


Managing Waveform Recording

Once you open a waveform input device, you can begin recording waveform data. Waveform data is recorded into application-supplied buffers specified by a WAVEHDR structure. This is the same structure used for waveform playback described in Writing Waveform Data. Memory for the WAVEHDR structure and its accompanying data buffer must be allocated and prepared, as shown in Allocating and Preparing Audio Data Blocks.

Windows provides the following functions to manage waveform recording:

Function	Description

waveInAddBuffer	Sends a buffer to the device driver so it can be filled with recorded waveform data.

waveInReset	Stops waveform recording and marks all pending buffers as done.

waveInStart	Starts waveform recording.

waveInStop	Stops waveform recording.

Use the waveInAddBuffer function to send data buffers to the device driver. As the buffers are filled with recorded waveform data, the application is notified with either a window message or with a callback message, depending on the flag specified when the device was opened.

Use the waveInStart function to begin recording. Before beginning to record, send at least one buffer to the driver or incoming data may be lost. To stop waveform recording, use the waveInStop function.

Before closing the device by using the waveOutClose function, call the waveOutReset function to mark any pending data blocks as being done.

Using Window Messages to Manage Waveform Recording

The following messages can be sent to a window-procedure function for managing waveform recording.

Message	Description

MM_WIM_CLOSE	Sent when the device is closed using the waveInClose function.

MM_WIM_DATA	Sent when the device driver is finished with a data buffer sent using the waveInAddBuffer function.

MM_WIM_OPEN	Sent when the device is opened using the waveInOpen function.

There is a wParam and lParam parameter associated with each of these messages. The wParam parameter always specifies a handle of the open waveform device. The lParam parameter is unused for the MM_WIM_CLOSE and MM_WIM_OPEN messages.

For the MM_WIM_DATA message, lParam specifies a pointer to a WAVEHDR structure that identifies the data buffer. This data buffer may not be completely filled with waveform data, because 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 MM_WIM_DATA. Unless you need to allocate memory or initialize variables, you probably don't need to use the MM_WIM_OPEN and MM_WIM_CLOSE messages. When the device driver is finished with a data block, you can clean up and free the data block as described in Allocating and Preparing Audio Data Blocks.

Using a Low-Level Callback Function to Manage Waveform Recording

The syntax of the low-level callback function for waveform input devices is as follows.

void CALLBACK waveInCallback(hWaveIn, wMsg,

    dwInstance, dwParam1, dwParam2)

The following messages can be sent in the wMsg parameter of waveform input callback functions.

Message	Description

WIM_CLOSE	Sent when the device is closed using the waveInClose function.

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

These messages resemble messages sent to window-procedure functions, but their parameters are different. A handle of an open waveform device is passed as a parameter to the callback function, along with the doubleword value of instance data that was passed using waveInOpen.

The callback function has two message-dependent parameters: dwParam1 and dwParam2. For the WIM_CLOSE and WIM_OPEN messages, these parameters are not used. For the WIM_DONE message, dwParam1 specifies a pointer to a WAVEHDR structure identifying the completed data block and dwParam2 is not used.

After the driver is finished with a data block, you can clean up and free the data block. Because of the suggested restrictions of low-level audio callback functions, it is better not to do this within the callback function. It is better to set events or semaphores and do this outside of the callback function. See Using a Callback Function to Process Driver Messages for details about the suggested restrictions on using callback functions.


Playing MIDI Audio

To play MIDI files, use the MCI sequencer. If the MCI sequencer services don't meet the needs of your application, you can manage MIDI playback using the low-level MIDI services.


MIDI Output Data Types

The MMSYSTEM.H header file defines data types and function prototypes for all low-level audio functions. You must include this header file in any source module that uses these functions. MMSYSTEM.H defines the following data types for low-level MIDI output function:

Type	Description

HMIDIOUT	Handle of a MIDI output device.

MIDIHDR	Structure is a header for a block of MIDI system-exclusive data. This structure is used for input as well as output.

MIDIOUTCAPS	Structure used to inquire about the capabilities of a particular MIDI output device.


Querying MIDI Output Devices

Before playing MIDI audio, you should call the midiOutGetDevCaps function to determine the capabilities of the MIDI output hardware present in the system. This function takes a pointer to a MIDIOUTCAPS structure that it fills with information about the capabilities of a given 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 MIDIOUTCAPS structure provides information on the device technology, the number of voices and notes supported, the MIDI channels that the device responds to, and features supported by the driver.

Determining the Technology of the Device

MIDI output devices can be either internal synthesizers or external MIDI output ports. The wTechnology member specifies the technology of the device. MMSYSTEM.H defines the following flags to identify device technology.

Flag	Description

MOD_MIDIPORT	The device is an external MIDI output port.

MOD_SQSYNTH	Device is an internal square-wave synthesizer.

MOD_FMSYNTH	Device is an internal FM synthesizer.

MOD_SYNTH	Device is an internal synthesizer (generic).

MOD_MAPPER	Device is the MIDI Mapper.

Determining Capabilities of Internal Synthesizers

If the device is an internal synthesizer, additional device information is available in the wVoices, wNotes, and wChannelMask members of the MIDIOUTCAPS structure. If the device is an external output port, these members are unused.

The wVoices member specifies the number of voices the device supports. Each voice can have a different sound or timbre. Voices are differentiated by MIDI channel. For example, a four-voice synthesizer uses four MIDI channels. The wNotes member specifies the polyphony of the device--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.

The dwSupport member of the MIDIOUTCAPS structure indicates whether the device driver supports volume changes and patch caching. MMSYSTEM.H defines the following flags for the dwSupport member.

Flag	Description

MIDICAPS_VOLUME	Indicates the driver supports volume control.

MIDICAPS_LRVOLUME	Indicates the driver supports individual volume control for the left and right channels.

MIDICAPS_CACHE	Indicates the driver supports patch caching.

Volume changes are only supported by internal synthesizer devices. External MIDI output ports don't support volume changes. For information about changing volume, see Changing Internal MIDI Synthesizer Volume.


Opening MIDI Output Devices

Use the midiOutOpen function to open a MIDI 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.


Sending MIDI Messages

Once you open a MIDI output device, you can begin sending it MIDI messages by using the following functions.

Function	Description

midiOutLongMsg	Sends a buffer of MIDI data to the specified MIDI output device. Use this function to send multiple MIDI events, including system-exclusive messages, to a MIDI device.

midiOutShortMsg	Sends a MIDI message to a specified MIDI output device. This function can use running status by omitting the status byte.

midiOutReset	Turns off all notes on all channels for a specified MIDI output device. Any pending system-exclusive buffers are marked as done and returned to the application.

Use midiOutShortMsg to send any MIDI message (except for system-exclusive messages). This function takes an HMIDIOUT parameter specifying the MIDI output device to which to send the message, and a doubleword value for the MIDI message. The message is packed into the doubleword value as follows.

Word	Byte	Contents

High-order word	High-order byte	Not used

Low-order byte	MIDI data 2 (optional)

Low-order word	High-order Byte	MIDI data 1 (optional)

Low-order byte	MIDI status

The two MIDI data bytes are optional, depending on the MIDI status byte. The following example uses midiOutShortMsg to send a given MIDI event to a given MIDI output device.

/* Sends a given MIDI event to the given output device */

UINT sendMIDIEvent(hMidiOut, bStatus, bData1, bData2)

HMIDIOUT hMidiOut;      // handle of the output device

BYTE bStatus;           // MIDI status byte

BYTE bData1;            // first MIDI data byte

BYTE bData2;            // second MIDI data byte

{

    union {

        DWORD dwData;

        BYTE bData[4];

    } u;

    /* Construct the MIDI message */

    u.bData[0] = bStatus;

    u.bData[1] = bData1;

    u.bData[2] = bData2;

    u.bData[3] = 0;

    /* Send the message */

    return midiOutShortMsg(hMidiOut, u.dwData);

}

Note:	MIDI output drivers are not required to verify data before sending it to an output port. It is up to applications to ensure that only valid data is sent using the midiOutShortMsg function.


Sending Buffered 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 one or more messages, including system-exclusive messages, to MIDI output devices.

Use the MIDIHDR structure to specify MIDI system-exclusive data blocks. This structure contains a pointer to a locked data block, the data-block length, and assorted flags.

Memory for the MIDIHDR structure and the data block pointed to by lpData must be allocated and prepared, as shown in Allocating and Preparing Audio Data Blocks.

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. (If your application uses a callback function or callback window, it will receive the MOM_DONE message when the driver finishes with the data block.) For information on different techniques for monitoring data-block completion, see Managing Audio 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 Window Messages to Manage Buffered Playback

The following messages can be sent to a window-procedure function for managing MIDI system-exclusive playback.

Message	Description

MM_MOM_CLOSE	Sent when the device is closed using the midiOutClose function.

MM_MOM_DONE	Sent when the device driver is finished with a data block sent using the midiOutLongMsg function.

MM_MOM_OPEN	Sent when the device is opened using the midiOutOpen function.

A wParam and lParam parameter is associated with each of these messages. The wParam parameter always specifies a handle of the open MIDI device. For the MM_MOM_DONE message, lParam specifies a pointer to a MIDIHDR structure identifying the completed data block. The lParam parameter is unused for the MM_MOM_CLOSE and MM_MOM_OPEN messages.

The most useful message is the MM_MOM_DONE message. Unless you need to allocate memory or initialize variables, you probably don't need to process the MM_MOM_OPEN and MM_MOM_CLOSE messages. When playback of a data block is completed, you can clean up and free the data block as described in Allocating and Preparing Audio Data Blocks.

Using a Callback to Manage Buffered Playback

This syntax of the low-level callback function for MIDI output devices is as follows.

void CALLBACK midiOutCallback(hMidiOut, wMsg,

    dwInstance, dwParam1, dwParam2)

The following messages can be sent to the wMsg parameter of MIDI output callback functions.

Message	Description

MOM_CLOSE	Sent when the device is closed using the midiOutClose function.

MOM_DONE	Sent when the device driver is finished with a data block sent using the midiOutLongMsg function.

MOM_OPEN	Sent when the device is opened 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 value of instance data passed using midiOutOpen.

The callback function has two message-dependent parameters: dwParam1 and dwParam2. For the MOM_OPEN and MOM_CLOSE messages, these parameters are not used. For the MOM_DONE message, dwParam1 specifies a pointer to a MIDIHDR structure identifying the completed data block and dwParam2 is not used.

After the driver is finished with a data block, you can clean up and free the data block. Because of the suggested restrictions on low-level audio callback functions, it is better not to do this from within the callback function. See Using a Callback Function to Process Driver Messages for details about the suggested restrictions on using callback functions.


Sending MIDI Messages Using Running-Status

The MIDI 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. You can send MIDI messages using running status by using the midiOutShortMsg function by packing the message into a doubleword value as follows.

Word	Byte	Contents

High-order word	High-order byte	Not used

Low-order byte	Not used

Low-order word	High-order Byte	MIDI data 2 (optional)

Low-order byte	MIDI data 1


Resetting MIDI Output

The midiOutReset function will turn off all notes, and mark any pending system-exclusive buffers as done and return them to the application. It may 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 may 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.


Changing Internal MIDI Synthesizer Volume

Windows provides the following functions to query and set the volume level of internal MIDI synthesizer devices.

Function	Description

midiOutGetVolume	Gets 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 the right channels. See Determining Capabilities of Waveform Output Devices for information about how to determine whether a particular device supports volume changes.

Note:	Unless your application is designed to be a master volume-control application providing the user with volume control for all audio devices in a system, be sure your application opens an audio device before changing its volume. Also be sure your application queries 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; the high-order 16 bits specify the relative volume of the right channel, and the low-order 16 bits specify the relative volume of the left channel.

For devices that don't support individual volume changes on both the left and right channels, the low-order 16 bits specify the volume level, and the high-order 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 from volume level 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

When querying volume levels using midiOutGetVolume, the volume is returned in a doubleword location specified by a pointer parameter.


Preloading Patches With Internal MIDI Synthesizers

Some internal MIDI synthesizer devices can't 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.

Function	Description

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.

The midiOutCachePatches function takes a pointer to a PATCHARRAY to indicate the patches to be cached.

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, set element 0 of the array to 0x0101.

The midiOutCacheDrumPatches function takes a pointer to a KEYARRAY to indicate the key-based percussion patches to be cached.

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, set element 60 of the array to 0x8200.


Using the MIDI Mapper With Low-Level MIDI Functions

The MIDI Mapper provides standard patch services for device-independent playback of MIDI files. Applications that use MIDI files for audio should use the MIDI Mapper. For information about the MIDI Mapper and about authoring device-independent MIDI files, see High-Level Audio.

To use the MIDI Mapper, open it by using the midiOutOpen function with the wDeviceID parameter set to the constant MIDIMAPPER. You can then send MIDI messages to the MIDI Mapper by using the midiOutShortMsg or midiOutLongMsg function.


Recording MIDI Audio

To record MIDI audio data, you must use low-level MIDI input functions. MCI does not currently provide a device handler for recording MIDI audio.


MIDI Input Data Types

The MMSYSTEM.H header file defines data types and function prototypes for all of the low-level audio functions. MMSYSTEM.H defines the following data types for low-level MIDI input functions.

Type	Description

HMIDIIN	A handle of a MIDI input device.

MIDIHDR	A structure that is a header for a block of MIDI system-exclusive data. This structure is used for input as well as output.

MIDIINCAPS	A structure used to inquire about the capabilities of a MIDI input device.


Querying MIDI Input Devices

Before recording MIDI audio, you should call the midiInGetDevCaps function to determine the capabilities of the MIDI input hardware present in the system. This function takes a pointer to a MIDIINCAPS structure that it fills with information about the capabilities of a 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

Use the midiInOpen function to open a MIDI 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.


Managing MIDI Recording

Once you open a MIDI input device, you can begin recording MIDI data. Win32 provides the following functions for managing MIDI recording.

Function	Description

midiInAddBuffer	Sends a buffer to the device driver so it can be filled with recorded 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.

Use the midiInAddBuffer function to send data buffers to the device driver for recording system-exclusive messages. Before you use midiInAddBuffer, you must allocate and prepare memory for the MIDIHDR data structure and the data block pointed to by the lpData member. For information about allocating and preparing this memory, see Allocating and Preparing Audio Data Blocks.

Use the midiInStart function to begin recording. To record system-exclusive messages, send at least one buffer to the driver with midiInAddBuffer before starting to record. As the buffers are filled with recorded data, the application is notified by one of the techniques discussed in Managing Audio Data Blocks.

To stop recording, use the midiInStop function. Before closing the device by using the midiInClose function, call midiInReset to mark any pending data blocks as being done. Before freeing the memory used by a data block, call the midiInUnprepareHeader function to clean up the preparation performed previously.

You must use either a window-procedure function or a low-level callback function to receive MIDI data. If you want time-stamped data, you must use a low-level callback function.

To record system-exclusive messages, you must supply the device driver with data buffers. These buffers are specified by a MIDIHDR structure. This is the same structure used for MIDI buffered playback as described in Sending Buffered Messages. Memory for the MIDIHDR structure and its accompanying data buffer must be allocated and prepared as shown in Allocating and Preparing Audio Data Blocks.

Using Window Messages to Manage MIDI Recording

The following messages can be sent to a window-procedure function for managing MIDI recording.

Message	Description

MM_MIM_CLOSE	Sent when the device is closed 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 data buffer sent using the midiInAddBuffer function is filled with system-exclusive data.

MM_MIM_LONGERROR	Sent when an invalid MIDI system-exclusive message is received.

MM_MIM_OPEN	Sent when the device is opened using the midiInOpen function.

A wParam and an lParam parameter are associated with each of these messages. The wParam parameter always specifies a handle of the open MIDI device. The lParam parameter is unused for the MM_MIM_CLOSE and MM_MIM_OPEN messages.

For the MM_MIM_DATA message, lParam specifies the received MIDI data. This data is packed into a doubleword value as follows.

Word	Byte	Contents

High-order word	High-order byte

Low-order byte	MIDI data 2 (optional)

Low-order word	High-order Byte	MIDI data 1 (optional)

Low-order byte	MIDI status

For the MM_MIM_LONGDATA message, lParam specifies a pointer to a MIDIHDR structure that identifies the data buffer for system-exclusive messages. The data buffer might not be completely filled--you usually don't know the size of the system-exclusive messages before recording them, so you must allocate a buffer large enough for the largest expected message. Use the dwBytesRecorded member of the MIDIHDR structure to determine the amount of valid data present in the buffer.

Using a Low-Level Callback Function to Manage MIDI Recording

This syntax of the low-level callback function for MIDI input devices is as follows:

void CALLBACK midiInCallback(hMidiIn, wMsg,

    dwInstance, dwParam1, dwParam2)

The following messages can be sent in the wMsg parameter of MIDI input callback functions.

Message	Description

MIM_CLOSE	Sent when the device is closed 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_LONGERROR	Sent when an invalid MIDI system-exclusive message is received.

MIM_LONGDATA	Sent when either a complete MIDI system-exclusive message is received, or when a data buffer is filled with system-exclusive data.

MIM_OPEN	Sent when the device is opened 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, along with the doubleword value of instance data that was passed using the midiInOpen value.

The callback has two message-dependent parameters: dwParam1 and dwParam2. For the MIM_OPEN and MIM_CLOSE messages, these parameters are unused.

For the MIM_DATA message, dwParam1 specifies the received MIDI data and dwParam2 specifies a time stamp for the data. The data is packed into a doubleword value, as shown in the previous section on using window messages.

For the MIM_LONGDATA message, dwParam1 specifies a pointer to a MIDIHDR structure that identifies the data buffer for system-exclusive messages. As with the MIM_DATA message, dwParam2 specifies a time stamp for the data. The data buffer may not be completely filled. Use the dwBytesRecorded member of the MIDIHDR structure to determine the amount of valid data present in the buffer.

After the device driver is finished with a data block, you can clean up and free the data block. Because of the suggested restrictions on low-level audio callback functions, it is better not to do this from within the callback function. It is better to set events or semaphores and do this outside of the callback function. See Using a Callback Function to Process Driver Messages for details about the suggested restrictions on using callback functions.


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 the message was received. MIDI time stamps are defined as the time the first byte of the message was received and are specified in milliseconds. The midiInStart function resets the time stamps for a device to zero.

As stated earlier, to receive time stamps with MIDI input, you must use a low-level 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 MIDI 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 to complete messages--you always receive complete MIDI messages from a MIDI input device driver.


Auxiliary Audio Devices

Auxiliary audio devices are audio devices whose output is mixed with the 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-ROM drive.

Control for auxiliary audio devices is provided by a software-controlled audio mixer. The mixer can reside on the motherboard of a multimedia computer, or it can be on an add-in sound card. The following illustration shows the conceptual audio-signal routing in a multimedia computer.

In this multimedia computer, there are two auxiliary audio devices: the CD-ROM and the external audio input. The external audio input is an input jack that allows the user to connect other audio devices.


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 on a particular auxiliary audio device, use the auxGetDevCaps function. This function takes a pointer to an AUXCAPS structure that it fills with information about the capabilities of a given device.

Determining Auxiliary Audio Device Types

The MMSYSTEM.H header file defines the following flags for the wTechnology member of the AUXCAPS structure to determine the device type of an auxiliary audio device.

Flag	Description

AUXCAPS_CDAUDIO	The device is an internal CD-ROM drive.

AUXCAPS_AUXIN	The device is an auxiliary audio input jack.

Determining Capabilities of Auxiliary Audio Devices

The dwSupport member of the AUXCAPS structure indicates whether the device driver supports volume changes. The MMSYSTEM.H header file defines the following flags for the dwSupport member.

Flag	Description

AUXCAPS_VOLUME	Volume-control support

AUXCAPS_LRVOLUME	Individual volume-control support for both the left and right channels


Changing Auxiliary Audio-Device Volume

Windows provides the following functions to query and set the volume for auxiliary audio devices.

Function	Description

auxGetVolume	Gets the volume level of the specified auxiliary audio device.

auxSetVolume	Sets the volume level of the specified auxiliary audio device.

Not all auxiliary audio devices support volume changes. Some devices can support individual volume changes on both the left and the right channels. See Determining Capabilities of Waveform Output Devices for information about how to determine whether a particular device supports volume changes.

Note:	Unless your application is designed to be a master volume-control application providing the user with volume control for all audio devices in a system, you should open an audio device before changing its volume. Also be sure your application queries the volume level before changing it and restores the volume level to its previous level as soon as possible.

The volume level is specified (as it was in the waveform and MIDI volume-control functions) in a doubleword value with the high-order 16 bits specifying the relative volume of the right channel and the low-order 16 bits specifying the relative volume of the left channel. For devices that don't support individual volume control on both the left and right channels, the low-order 16 bits specify the volume level, and the high-order 16 bits are ignored.

Values for the volume level range from 0x0 (silence) to 0xFFFF (maximum volume) and are interpreted logarithmically. This means the perceived volume increase is the same from volume level 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

When querying volume levels with the auxGetVolume function, the volume is returned in a doubleword location specified by a pointer parameter.


Audio Clipboard Formats

In addition to the standard and nonstandard waveform formats previously presented in this topic, there are two Clipboard formats that can be used 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 wave files.


Multimedia Timers

About Multimedia Timers

This topic shows you how to add joystick input capabilities to your application and how to control event timing. The joystick services can receive control signals from up to two joysticks. Timer services provide improved timer resolution and accuracy. Intel®-based systems have an accuracy of up to 16 milliseconds and MIPS®-based systems have an accuracy of up to 10 milliseconds.

The following topics discuss timer services:

Timer Services

Timer Data Types

Using Timer Services

Getting the System Time

Determining Maximum and Minimum Event Periods

Establishing Minimum Timer Resolution

Starting Timer Events

Canceling a Timer Event

Using Timer Callbacks

Joystick Services

Joystick Data Types

Using Joystick Services

Determining Joystick Capabilities

Methods for Checking Joystick Status

Capturing Joystick Messages to a Window Function

Processing Joystick Messages

Releasing the Joystick

Setting the Movement Threshold

Polling the Joystick

Using Joystick Messages

The functions and data structures associated with the joystick and timer-interrupt services are defined in MMSYSTEM.H and WINMM.LIB.


Timer Services

The multimedia timer services provided with the Microsoft® Win32™ application programming interface (API) let applications schedule timed periodic or one-time asynchronous events. Unlike the timer services that post WM_TIMER messages to a message queue, the multimedia timer services call a callback function.


Timer Data Types

The MMSYSTEM.H header file defines data types and function prototypes for timer functions. You must include this header file in any source-code module that uses timer services. MMSYSTEM.H defines the following new data types.

Type	Description

MMTIME	A structure for representing time in one of several formats.

TIMECAPS	A structure for querying timer capabilities.


Using Timer Services

Timer services let an application request and receive timer messages at application-specified intervals. Real-time multimedia applications can use the following functions to control the pace of data and synchronized presentations.

Function	Description

timeBeginPeriod	Establishes the minimum timer resolution an application will use.

timeEndPeriod	Clears a minimum timer resolution previously set using timeBeginPeriod.

timeGetDevCaps	Returns information about the capabilities of the timer services.

timeGetTime	Returns the system time in milliseconds.

timeGetSystemTime	Fills an MMTIME structure with the system time in milliseconds.

timeSetEvent	Creates a timer event that executes a specific action at a specific time or at periodic intervals.

timeKillEvent	Cancels a timer event previously created using timeSetEvent.


Getting the System Time

An application can get the current system time using the timeGetTime or timeGetSystemTime function. The system time is the count of milliseconds since the Microsoft® Windows™ operating system was started. The timeGetTime function returns the system time, and the timeGetSystemTime function fills an MMTIME structure with the system time.


Determining Maximum and Minimum Event Periods

You can use the timeGetDevCaps function to determine the minimum and maximum timer-event periods provided by the timer services. These values vary across computers and can vary depending on the mode in which Windows is running.


Establishing Minimum Timer Resolution

Before starting timer events, your application must establish the minimum timer resolution that it intends to use. It must clear this value after finishing with the timer-event services.

Use the timeBeginPeriod and timeEndPeriod functions to set and clear the minimum timer-event resolution for your application. You must match a call to timeBeginPeriod with a corresponding 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.


Starting Timer Events

To initialize and start timer events, use the timeSetEvent function. This function returns a timer identifier that can be used to stop or identify timer events.

The timeSetEvent function returns a timer identifier if successful or NULL if unsuccessful. Interrupt timers are a scarce resource, and periodic timers with resolution less than 100 milliseconds consume a significant portion of CPU time. For periodic timers, you must pair calls to timeSetEvent with calls to timeKillEvent. For more information, see Canceling a Timer Event.

The lpFunction parameter contains the address of the function to be called when the timer event takes place.

Since the callback function is accessed at interrupt time, it must adhere to strict programming guidelines. Timer-callback functions follow the same programming guidelines as callback functions for the low-level audio services. For information about writing low-level audio callback functions, see Low-Level Audio. For more information about timer callback functions, see TimeProc.


Canceling a Timer Event

You can cancel an active timer event at any time. Be sure to cancel any outstanding timers before freeing the module containing the callback function. To cancel a timer event, use the timeKillEvent function.


Using Timer Callbacks

This section describes how an application can use the timer services. First, the application calls the timeGetDevCaps function to determine the minimum and maximum resolution supported by the timer services. Before setting up any timer events, the application uses the timeBeginPeriod function to establish the minimum timer resolution it will use, as shown in the following example:

#define TARGET_RESOLUTION 1  /* Try for 1-millisecond accuracy. */

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);

To start the timer event, the application specifies the amount of time before the callback occurs, the required resolution, the address of the callback function, and user data to supply with the callback. The application can use a function like the following to start a one-time timer event.

UINT SetTimerCallback(NPSEQ npSeq,           /* Sequencer data */

                      UINT msInterval)       /* Event interval */

{

    npSeq->wTimerID = timeSetEvent(

         msInterval,           /* Delay                        */

         wTimerRes,            /* Resolution (global variable) */

         (LPTIMECALLBACK) OneShotTimer, /* Callback function   */

         (DWORD) npSeq,               /* User data             */

         TIME_ONESHOT);               /* Event type (one-time) */

    if (npSeq->wTimerID != 0)

        return TIMERR_NOCANDO;

    else

        return TIMERR_NOERROR;

}

The following callback function is used for the one-shot timer.

void PASCAL OneShotTimer(UINT wTimerID, UINT msg,

    DWORD dwUser, DWORD dw1, DWORD dw2)

{

    NPSEQ npSeq;            /* Pointer to sequencer data   */

    npSeq = (NPSEQ) dwUser;

    npSeq->wTimerID = 0;    /* Invalidate unused timer id  */

    TimerIntRoutine(npSeq); /* Handle interrupt-time tasks */

    UNREFERENCED_PARAMETER(dw1);

    UNREFERENCED_PARAMETER(dw2);

    UNREFERENCED_PARAMETER(msg);

    UNREFERENCED_PARAMETER(wTimerID);

}

Before freeing the dynamic-link library (DLL) that contains the callback function, the application cancels any outstanding timers. To cancel one timer event, it can call the following function.

void DestroyTimer(NPSEQ npSeq)

{

    if (npSeq->wTimerID) {      /* If timer event is pending */

        timeKillEvent(npSeq->wTimerID);  /* Cancel the event */

        npSeq->wTimerID = 0;

    }

}

Finally, to cancel the minimum timer resolution it established, the application calls timeEndPeriod as follows.

timeEndPeriod(wTimerRes);


Joystick Services

The joystick is an input device that provides position information. It is an additional supported input device, not a replacement for the mouse. All absolute-position devices, including touch screens, digitizing tablets, and light pens, can use the joystick services to provide position and button information to applications.

The joystick services are loaded when Windows is started. The joystick services can monitor two joysticks, each with two- or three-axis movement, and up to four buttons. Applications access the joystick services through the set of functions described in this section.

Note:	The driver for the IBM® Game Adapter supports two 2-axis joysticks or one 3-axis joystick.


Joystick Data Types

The MMSYSTEM.H header file defines new data types and function prototypes for joystick functions. MMSYSTEM.H defines the following new data types.

Type	Description

JOYCAPS	A structure that contains joystick capability information.

JOYINFO	A structure that contains joystick position and button information.


Using Joystick Services

Joystick services include functions to query each joystick for its capabilities, to poll each joystick for position and button information, and to receive messages in response to joystick events. Your application can use the following joystick functions to accept input from one or two joysticks.

Function	Description

joyGetNumDevs	Returns the number of joysticks supported by the joystick services.

joyGetDevCaps	Returns joystick capabilities.

joyGetPos	Returns joystick position and button information.

joySetCapture	Causes joystick input to be sent to a specified window at regular intervals or when the joystick state changes.

joyReleaseCapture	Releases the joystick captured using joySetCapture.

joyGetThreshold	Returns the movement threshold of a joystick.

joySetThreshold	Sets the movement threshold of a joystick.


Determining Joystick Capabilities

The various joysticks in use today can support two or three axes and a variety of button configurations. Also, joysticks support different ranges of motion and polling frequencies. Joystick drivers can support either one or two joysticks. Two functions allow you to determine the capabilities of the joystick services and joystick devices installed on a system.

Getting the Driver Capabilities

You can use the joyGetNumDevs function to determine the number of joystick devices supported by the joystick services. This function returns the number of supported joysticks, or zero if there is no joystick support. The value returned is not necessarily the number of joysticks attached to the system. To determine whether a joystick is attached, call the joyGetPos function for the device. The function returns JOYERR_UNPLUGGED if the specified device is disconnected.

The following example determines whether the joystick services are available and then determines 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;

    /* Decide which joystick to use */

    if(bDev1Attached || bDev2Attached)

        wDeviceID = bDev1Attached ? JOYSTICKID1 : JOYSTICKID2;

    else

        return ERR_NODEVICE;

Getting the Joystick Capabilities

You can use the joyGetDevCaps function to obtain the specific capabilities of each joystick attached to a given system. This function fills a JOYCAPS structure with the range of each axis on the joystick, the number of buttons, and the maximum and minimum polling frequency.


Methods for Checking Joystick Status

An application can receive information from the joystick in one of two ways:

By processing joystick messages from a captured joystick

By polling the joystick directly

The message-processing method can be simpler to use; your application is sent messages that indicate the position of the stick and the state of the buttons (pressed or released).


Capturing Joystick Messages to a Window Function

You can capture joystick input to a window function; your application then receives joystick messages at specified intervals or when the user manipulates the joystick. The messages are described in the following section.

Only one application can capture joystick messages from a given joystick. Capturing joystick messages does not, however, prevent your application (or other applications) from polling the joystick using joyGetPos. If joyGetPos is called while joystick input is captured, joystick events occurring close to the time of the joyGetPos call may not be accurately reported to the capture window.

The joySetCapture function captures joystick input to a window function you specify. To release the joystick, call the joyReleaseCapture function.

To capture messages from two joysticks attached to the system, you must call joySetCapture twice, once for each joystick. Your window then receives separate messages for each device.

You cannot capture an unplugged joystick. The joySetCapture function returns zero if successful; it returns JOYERR_UNPLUGGED if the specified device is unplugged.

Note:	The joystick services set up a Windows timer event with each call to joySetCapture.

Set the period parameter for joySetCapture to a value that falls within the minimum and maximum resolution range for the joystick. To determine the minimum and maximum resolution of the joystick, call the joyGetDevCaps function, which fills the wPeriodMin and wPeriodMax members in the JOYCAPS structure.

If the specified period value is outside the range of valid resolution values for the joystick, the joystick services use the minimum or maximum resolution value, whichever is closer to the specified period.


Processing Joystick Messages

The following joystick messages can be sent to a window function. Numerals 1 and 2 in these messages correspond to the joystick initiating the message. MM_JOY1 messages are sent to the window function if your application requests input from the first joystick, and MM_JOY2 messages are sent if your application requests input from the second joystick. All messages report nonexistent buttons as released.

Messages	Description

MM_JOY1MOVE, MM_JOY2MOVE

Report a change in the x-axis and/or y-axis position of the joystick. The wParam parameter contains a combination of JOY_BUTTON bit flags specifying which buttons were pressed. The low-order word of lParam contains the x-position of the joystick, and the high-order word contains the y-position.

MM_JOY1ZMOVE, MM_JOY2ZMOVE

Report a change in the z-axis position of a 3-axis joystick. The wParam parameter contains a combination of JOY_BUTTON bit flags specifying which buttons were pressed. The low-order word of lParam contains the x-position of the joystick, and the high-order word contains the y-position.

MM_JOY1BUTTONUP, MM_JOY2BUTTONUP, MM_JOY1BUTTONDOWN, MM_JOY2BUTTONDOWN

Report that a joystick button has been pressed or released. The wParam parameter contains one JOY_BUTTONCHG bit flag specifying which button changed state and a combination of JOY_BUTTON bit flags specifying the current button states. The low-order word of lParam contains the x-position of the joystick, and the high-order word contains the y-position.

The joystick services use the following bit flags, passed in the wParam parameter of the window function, to report the state of the joystick buttons.

Flag	Description

JOY_BUTTON1	Set when button 1 is pressed.

JOY_BUTTON1CHG	Set when button 1 has changed state.

JOY_BUTTON2	Set when button 2 is pressed.

JOY_BUTTON2CHG	Set when button 2 has changed state.

JOY_BUTTON3	Set when button 3 is pressed.

JOY_BUTTON3CHG	Set when button 3 has changed state.

JOY_BUTTON4	Set when button 4 is pressed.

JOY_BUTTON4CHG	Set when button 4 has changed state.

The MM_JOYMOVE messages use the JOY_BUTTON flags to report the state (pressed or released) of all buttons on the specified joystick.

The MM_JOYBUTTONUP and MM_JOYBUTTONDOWN messages use the JOY_BUTTON flags to report the state (pressed or released) of all buttons on the specified joystick. Also, they use JOY_BUTTONCHG flags to indicate which button changed state, thereby generating the message.

For example, if the user presses and holds buttons 1 and 2 and then moves the stick, a window function may receive the following messages.

Message	wParam Flags

MM_JOY1BUTTONDOWN	JOY_BUTTON1 | JOY_BUTTON1CHG

MM_JOY1BUTTONDOWN	JOY_BUTTON1 | JOY_BUTTON2 | JOY_BUTTON2CHG

MM_JOY1MOVE	JOY_BUTTON1 | JOY_BUTTON2

A window function may receive the following messages when the user presses and releases button 3 without moving the stick.

Message	wParam Flags

MM_JOY1BUTTONDOWN	JOY_BUTTON3 | JOY_BUTTON3CHG

MM_JOY1BUTTONUP	JOY_BUTTON3CHG


Releasing the Joystick

When your application no longer needs to receive periodic joystick messages, it should release the joystick by using the joyReleaseCapture function. If your application does not release the joystick before ending, the joystick is released shortly after the capture window is destroyed.


Setting the Movement Threshold

You can change the movement threshold of the joystick by calling the joySetThreshold function. The movement threshold is the number of device units that the stick must be moved before an MM_JOYMOVE message is sent to the window that has captured the device.


Polling the Joystick

You can poll the joystick for position and button information. For example, an application may poll the joystick to get baseline position values; the Joystick Control Panel application uses this technique when calibrating the joystick. The joyGetPos function allows you to poll the joystick for position and button information.

Note:	Calling joyGetPos while joystick input is captured can prevent the joystick services from accurately reporting joystick events to the capture window.


Using Joystick Messages

The remainder of this topic presents examples from a simple joystick game that performs the useful function of shooting holes in the desktop: it gets position and button-state information from the joystick services and, when a user presses the joystick buttons, plays waveform resources and paints bullet holes on the screen.

Most of the joystick-control code is in the main window function. In the following WM_CREATE case of the message handler, the application captures input from joystick 1.

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;

In response to the MM_JOY1MOVE messages, the application changes the position of the cursor and, if either button is pressed, draws a hole in the desktop.

case MM_JOY1MOVE :

    if((UINT) wParam & (JOY_BUTTON1 | JOY_BUTTON2))

        DrawFire(hWnd);

    DrawSight(lParam);  /* Calculate new cursor position */

    break;

In response to the MM_JOY1BUTTONDOWN messages, the application uses sndPlaySound to play a waveform audio file.

case MM_JOY1BUTTONDOWN :

    if((UINT) wParam & JOY_BUTTON1) {

        sndPlaySound(lpButton1,

                     SND_LOOP | SND_ASYNC | SND_MEMORY);

        DrawFire(hWnd);

    }

    else if(wParam & JOY_BUTTON2) {

        sndPlaySound(lpButton2,

                     SND_ASYNC | SND_MEMORY |  SND_LOOP);

        DrawFire(hWnd);

    }

    break;

By specifying the SND_LOOP and SND_ASYNC flags with sndPlaySound, the JOYTOY application repeats the waveform playback until the button is released.

When a button is released, the window function receives a MM_JOY1BUTTONUP message, and handles it with the following statement.

case MM_JOY1BUTTONUP:

    sndPlaySound(NULL, 0);

    break;

This sequence stops the waveform-audio playback.


Multimedia File I/O Overview

About the Multimedia File Input/Output Services

Most multimedia applications require file input/output (I/O)--the ability to create, read, and write disk files. The multimedia file I/O services provided by the Microsoft® Win32™ application programming interface (API) offer buffered and unbuffered file I/O and support for standard Resource Interchange File Format (RIFF) files. The services are extensible with custom I/O procedures.

The following topics discuss the multimedia file I/O services:

Comparison With C Run-time and Windows File I/O

Function Prefixes

Data Types

Performing Basic File I/O

Opening a File

Creating and Deleting Files

Reading and Writing a File

Seeking to a New Position in a File

Performing Buffered File I/O

Deciding When to Use Buffered File I/O

Opening a File for Buffered File I/O

I/O Buffer Control Functions

Working With RIFF Files

About RIFF Files

Generating Four-Character Codes

Creating RIFF Chunks

Navigating RIFF Files

Example of RIFF File I/O

Directly Accessing a File I/O Buffer

Getting Information on the File I/O Buffer

Reading and Writing the File I/O Buffer

Advancing the File I/O Buffer

Example of Accessing a File I/O Buffer

Ending Direct Access of a File I/O Buffer

Performing File I/O on Memory Files

Opening Memory Files

Using Custom I/O Procedures

Opening a File Using a Custom I/O Procedure

Writing an I/O Procedure

Installing an I/O Procedure

The multimedia file I/O services provide support for the following file I/O operations:

Basic unbuffered and buffered file I/O

RIFF file I/O

Direct access to the file I/O buffer

Memory files

Custom storage system I/O using application-supplied I/O procedures

Most applications only need 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 a CD-ROM in real time, can optimize performance by using services to directly access the file I/O buffer. Applications that access custom storage systems can provide their own I/O procedure that reads and writes elements of the storage system. A storage system is a method of physically storing data in a file, such as a file-archival system or a database storage system.


Comparison With C Run-time and Windows File I/O

Comparison With Other File I/O

You might ask why you need another set of file I/O services, when you already have the services of the C run-time and Win32 API libraries. The multimedia file I/O services offer the following advantages over other file I/O services:

They are a part of the system software, so they don't increase the size of your application, like linking to the C run-time libraries

They provide more functionality than the Win32 services, such as support for buffered I/O, RIFF files, memory files, and custom storage systems

In addition, the multimedia file I/O services are optimized for performance-intensive applications.


Function Prefixes

All multimedia file I/O function names begin with the mmio prefix. Similarly, all multimedia file I/O message names begin with the MMIOM_ prefix.


Data Types

The MMSYSTEM.H header file defines data types and function prototypes for all multimedia file I/O functions. You must include this header file in any source-code module that uses these functions. MMSYSTEM.H depends on declarations made in WINDOWS.H, so you must first include the WINDOWS.H header file. MMSYSTEM.H defines the following data types for the multimedia file I/O functions.

Type	Description

FOURCC	A four-character code identifying an element of a RIFF file.

HMMIO	A handle of an open file.

MMCKINFO	A structure containing information about a chunk in a RIFF file.

MMIOINFO	A structure used to maintain the current state of a file accessed using the multimedia file I/O services.

MMIOPROC	A custom multimedia file I/O procedure.


Performing Basic File Input/Output

Using the basic I/O services is similar to using the C run-time file I/O services. Files must be opened before they can be read or written. After reading or writing, the file must be closed. You can change the current read/write location by seeking to a specified position in an open file. The following table lists the basic file I/O functions.

Function	Description

mmioClose	Closes an open file.

mmioOpen	Opens a file for reading or writing or both and returns a handle of the open file.

mmioRead	Reads a specified number of bytes from an open file.

mmioSeek	Changes the current position for reading or writing in an open file.

mmioWrite	Writes a specified number of bytes to an open file.

These file I/O functions provide the core of the multimedia file I/O services--you can use them for buffered and unbuffered I/O, as well as for I/O to RIFF files, memory files, and custom storage systems.


Opening a File

Before doing any I/O operations to a file, you must first open the file by using the mmioOpen function. The mmioOpen function returns a file handle that you use to identify the open file when calling other file I/O functions.

Note:	Do not use HMMIO file handles with Windows or C run-time file I/O functions.

There are options you can use with the mmioOpen function for operations beyond basic file I/O. By specifying an MMIOINFO structure with the lpmmioinfo parameter you can open memory files, specify a custom I/O procedure, or supply a buffer for buffered I/O. These topics are discussed later in this topic. First, this topic discusses the most basic use of mmioOpen--opening files for basic unbuffered file I/O.

To open a file for basic I/O operations, set the lpmmioinfo parameter of mmioOpen to NULL. For example, the following example opens a file named C:\SAMPLES\SAMPLE1.TXT for reading, and checks the return value for errors.

HMMIO hFile;

    .

    .

    .

if ((hFile = mmioOpen("C:\\SAMPLES\\SAMPLE1.TXT",

        NULL, MMIO_READ)) != NULL) /* File opened successfully */

    return TRUE;

else

        /* File cannot be opened. */

    return FALSE;

Options for Opening a File

When you open a file, you must specify whether you are opening the file for reading, writing, or both reading and writing. In addition, you can specify other options, such as to create or delete a new file. Use the dwFlags parameter of mmioOpen to specify options for opening a file.

Following are the basic options for opening a file using mmioOpen:

Flag	Description

MMIO_READ	Opens a file for reading only.

MMIO_WRITE	Opens a file for writing only.

MMIO_READWRITE	Opens a file for reading and writing.

MMIO_CREATE	Creates a new file (if the file already exists, it truncates it to zero length).

MMIO_DELETE	Deletes a file.

MMIO_ALLOCBUF	Opens a file for buffered I/O.

The MMIO_READ, MMIO_WRITE, and MMIO_READWRITE flags are read/write privilege flags. These flags are mutually exclusive--specify only one when opening a file. If you don't specify one of these flags, mmioOpen opens the file for reading only.

The MMIO_CREATE and MMIO_DELETE flags are also mutually exclusive. You can specify one of the read/write privilege flags with the MMIO_CREATE flag. You can't specify any additional flags with the MMIO_DELETE flag.

For information on using the MMIO_ALLOCBUF flag, see Performing Buffered File Input/Output, later in this topic.

In addition to the basic options for opening a file, there are sharing options you can use for opening files so they can be opened and accessed by more than one process. Following are the sharing options for opening a file using mmioOpen.

Flag	Description

MMIO_COMPAT	Opens a file in compatibility mode.

MMIO_EXCLUSIVE	Opens a file in exclusive mode.

MMIO_DENYWRITE	Opens a file and denies other processes write access to the file.

MMIO_DENYREAD	Opens a file and denies other processes read access to the file.

MMIO_DENYNONE	Opens a file without denying other processes read or write access to the file.


Creating and Deleting Files

To create a new file, specify the MMIO_CREATE option with the mmioOpen function. For example, the following example creates a new file and opens it for both reading and writing.

HMMIO hFile;

    .

    .

    .

hFile = mmioOpen("NEWFILE.TXT",

                  NULL, MMIO_CREATE | MMIO_READWRITE);

if (hFile != NULL)

        /* File created successfully. */

    return TRUE;

else

        /* File could not be created. */

    return FALSE;

Note:	If the file you are creating already exists, it will be truncated to zero length.

To delete a file, specify the MMIO_DELETE flag with the mmioOpen function. Once you delete a file, it can't be recovered. If the file deletion is the result of a request from a user, always query the user to be sure the user wants to delete the specified file before you actually delete it.


Reading and Writing a File

To read and write to open files, use the mmioRead and mmioWrite functions. Each of these functions takes an HMMIO file handle, a pointer to a buffer, and a parameter specifying the number of bytes to read or write.

See Example of RIFF File I/O, later in this topic, for an example using mmioRead to read from a file.


Seeking to a New Position in a File

The current position or file pointer in a file is the location where the next read or write operation will occur. To change the current position in an open file, use the mmioSeek function.

The return value is the new position, specified in bytes from the beginning of the file. If an error occurs, the return value is -1. If you seek to an invalid location in a file, such as past the end of the file, mmioSeek may not return an error, but subsequent I/O operations can fail.


Performing Buffered File Input/Output

Most of the overhead in file I/O involves accessing the media (the physical device). If you are reading or writing many small blocks of information, the media device can spend a lot of time seeking the physical location on the media for each read or write operation. In this case, better performance is achieved by using buffered file I/O. 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 only accesses the media when the buffer must be filled from or written to the disk.


Deciding When to Use Buffered File I/O

It's difficult to provide exact metrics telling you when you need to use buffered I/O. It depends on how many read and write operations you perform on a file, and on the size of these read and write operations. A general guideline is to use buffered I/O if you are doing many small I/O operations (less than 2 kilobytes each). But this rule isn't absolute--it's best to understand exactly how your program uses file I/O and experiment to optimize file I/O for your program's requirements.


Opening a File for Buffered File I/O

The multimedia file I/O manager provides several ways to set up and use buffered file I/O. The main distinction between these different approaches is whether the file I/O manager or the application allocates the buffer--either the file I/O manager or the application can allocate the I/O buffer. Unless you want to access the I/O buffer directly or open a memory file, let the file I/O manager allocate the buffer. For more information about accessing an I/O buffer directly and using memory files, see Directly Accessing a File Input/Output Buffer, and Performing File Input/Output on Memory Files, both later in this topic.

A buffer allocated by the file I/O manager is called an internal buffer. To open a file for buffered I/O using an internal buffer, specify the MMIO_ALLOCBUF flag with the mmioOpen function when you open the file. Once a file is opened for buffered I/O, the buffer is essentially transparent to the application. You can read, write, and seek the same way as with unbuffered I/O.


I/O Buffer Control Functions

The multimedia file I/O services also include some functions that give you more control over the file I/O buffer. Using the following functions, you can force the contents of an I/O buffer to be written to disk, enable buffered I/O on a file opened for unbuffered I/O, change the size of an I/O buffer, and supply your own I/O buffer.

Function	Description

mmioFlush	Writes the contents of the I/O buffer to disk.

mmioSetBuffer	Changes the size of the I/O buffer, and allows applications to supply their own buffer.

Flushing an I/O Buffer

Flushing an I/O buffer means writing the contents of the buffer to disk. You don't have to call the mmioFlush function to flush an I/O buffer--the buffer is automatically flushed when you close a file using the mmioClose function. If you don't close a file immediately after writing to it, you flush the buffer to ensure the information is written to disk.

Note:	If you run out of disk space, mmioFlush may fail, even if the preceding mmioWrite calls were successful. Similarly, mmioClose may fail when it is flushing its I/O buffer.

Changing the Size of the Internal I/O 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 size of the buffer. You can also use mmioSetBuffer to enable buffering on a file opened for unbuffered I/O.

The following example opens a file named SAMPLE.TXT for unbuffered I/O, and then enables buffered I/O with an internal 16K buffer.

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

        return FALSE;

    else

            /* Buffer allocated successfully. */

        return TRUE;

}

else

        /* File cannot be opened. */

    return FALSE;

Supplying Your Own I/O Buffer

You can also use mmioSetBuffer to supply your own buffer for use as a memory file. For details on using memory files, see Performing File Input/Output on Memory Files.


Working With RIFF Files

The preferred format for multimedia files is the Resource Interchange File Format (RIFF). The RIFF format is a tagged-file structure.

The multimedia file I/O services provide the following functions to support file I/O to RIFF files.

Function	Description

mmioAscend	Ascends out of a RIFF file chunk to the next chunk in the file.

mmioCreateChunk	Creates a new chunk in a RIFF file.

mmioDescend	Descends into a RIFF file chunk beginning at the current file position, or searches for a specified chunk.

mmioFOURCC	Converts four individual characters into a four-character code.

mmioStringToFOURCC	Converts a null-terminated string into a four-character code.

These functions work with the basic buffered and unbuffered file I/O services--you can open, read, and write RIFF files the same as other file types.


About RIFF Files

The basic building block of a RIFF file is called a chunk. Each chunk consists of the following fields:

A four-character code specifying the chunk identifier

A doubleword specifying the size of the data field in the chunk

A data field

The only chunks allowed to contain other chunks (subchunks) are those with a chunk identifier of "RIFF" or "LIST". 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

"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 (WAVE files) have a form type of "WAVE". The following illustration shows a "RIFF" chunk containing two subchunks.

"LIST" Chunks

"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 containing a "LIST" chunk and one other subchunk (the "LIST" chunk contains two subchunks).


Generating Four-Character Codes

A four-character code is a 32-bit quantity representing a sequence of one to four ASCII alphanumeric characters, padded on the right with blank characters. The data type for a four-character code is FOURCC. Use the mmioFOURCC function to convert four characters to a four-character code, as shown in the following example, which generates a four-character code for "WAVE":

FOURCC fourccID;

    .

    .

    .

fourccID = mmioFOURCC('W', 'A', 'V', 'E');

To convert a null-terminated string into a four-character code, use the mmioStringToFOURCC function, as shown in the following example, which also generates a four-character code for "WAVE":

FOURCC fourccID;

    .

    .

    .

fourccID = mmioStringToFOURCC("WAVE", 0);

The second parameter in mmioStringToFOURCC specifies options 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 (four-character codes identifying file-extension names must be all uppercase).


Creating RIFF Chunks

To create a new chunk, use the mmioCreateChunk function to write a chunk header at the current position in an open file.

The following example creates a new chunk with a chunk ID 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're creating a "RIFF" or "LIST" chunk, you must specify the form type in the fccType field of the MMCKINFO structure. In the previous example, the form type is "RDIB".

If you know the size of the data field in a new chunk, you can set the cksize member in 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 the mmioAscend function to mark the end of the chunk, it will be rewritten automatically to reflect the correct size of the data field.

After you create a new chunk using mmioCreateChunk, 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).


Navigating RIFF Files

RIFF files consist of nested chunks of data. Multimedia file I/O services include two functions you can use to navigate between chunks in a RIFF file: mmioAscend and mmioDescend. You might think of 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.

Descending Into a Chunk

The mmioDescend function descends into a chunk or searches for a chunk, beginning at the current file position.

The mmioDescend function fills an MMCKINFO structure with information on the chunk. This information includes the chunk identifier, the size of the data field, and the form type, or list type if the chunk is a "RIFF" or "LIST" chunk.

Searching for a Chunk

To search for a chunk in an open RIFF file, specify the MMIO_FINDCHUNK flag in the wFlags parameter of mmioDescend. Set the ckid member of the MMCKINFO structure referenced by lpck to the four-character code of the chunk you want to search for.

If you are searching for a "RIFF" or "LIST" chunk, you don't need to set the ckid member of the MMCKINFO structure--mmioDescend sets this member for you. Set the fccType member to the four-character code of the form type or list type of the chunk.

The following example searches for a "RIFF" chunk with a form type of "WAVE" to verify that the file that has just been opened is a WAVE 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 WAVE file.

 */

mmckinfoParent.fccType = mmioFOURCC('W', 'A', 'V', 'E');

if (mmioDescend(hmmio, (LPMMCKINFO) &mmckinfoParent,

                NULL, MMIO_FINDRIFF))

        /* The file is not a WAVE file. */

    return FALSE;

else

        /* The file is a WAVE file. */

    return TRUE;

If the chunk you are searching for is a subchunk enclosed by a parent chunk (as are all chunks other than "RIFF" chunks), you should identify the parent chunk with the lpckParent parameter. In this case, mmioDescend will only search within the specified parent chunk.

The following example searches for the "fmt " chunk in the "RIFF" chunk descended into by 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. */

    return FALSE;

}

else {

        /* "fmt " chunk found. */

    return TRUE;

}

If you do not specify a parent chunk, the current file position should be at the beginning of a chunk before you call mmioDescend to search for a chunk. If you do specify a parent chunk, the current file position can be anywhere in the parent chunk.

If the search for a subchunk fails, the current file position is undefined. You can use the mmioSeek function and the dwDataOffset field of the MMCKINFO structure for the enclosing parent chunk to seek back to the beginning of the parent chunk, as in the following example:

mmioSeek(hmmio, mmckinfoParent.dwDataOffset + 4, SEEK_SET);

Since the dwDataOffset member specifies the offset to the beginning of the data portion of the chunk, you must seek four bytes past dwDataOffset to set the file position to be after the form type.

Ascending Out of a Chunk

After you descend into a chunk and read the data in the chunk, you can move the file position to the beginning of the next chunk by ascending out of the chunk by using the mmioAscend function.

For example, the following statement ascends out of the "fmt " subchunk descended into by the previous example, illustrating searching for a subchunk:

/* Ascend out of the "fmt " subchunk.

 */

mmioAscend(hmmio, &mmckinfoSubchunk, 0);


Example of RIFF File I/O

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 WAVE waveform audio file backwards. */

void ReversePlay(void)

{

    char        szFileName[128];           /* filename of file to open */

    HMMIO       hmmio;                    /* file handle for open file */

    MMCKINFO    mmckinfoParent;  /* parent chunk information structure */

    MMCKINFO    mmckinfoSubchunk; /* subchunk information structure    */

    DWORD       dwFmtSize;        /* size of "fmt" chunk               */

    DWORD       dwDataSize;       /* size of "data" chunk              */

    WAVEFORMAT  *pFormat;         /* pointer to memory for "fmt" chunk */

    ...

    /* Get the filename from the edit control. */

     ...

    /*

     * Open the given file for reading with buffered I/O

     * using the default internal buffer.

     */

    hmmio = mmioOpen(szFileName, NULL, MMIO_READ | MMIO_ALLOCBUF);

    if(hmmio == NULL){

        Error("Failed to open file.");

        return;

    }

    /*

     * Locate a "RIFF" chunk with a "WAVE" form type

     * to make sure the file is a WAVE file.

     */

    mmckinfoParent.fccType = mmioFOURCC('W', 'A', 'V', 'E');

    if (mmioDescend(hmmio, (LPMMCKINFO) &mmckinfoParent, NULL,

                    MMIO_FINDRIFF)) {

        Error("This is not a WAVE file.");

        mmioClose(hmmio, 0);

        return;

    }

    /*

     * Find the "fmt " chunk (form type "fmt "); it must be

     * a subchunk of the "RIFF" parent chunk.

     */

    mmckinfoSubchunk.ckid = mmioFOURCC('f', 'm', 't', ' ');

    if (mmioDescend(hmmio, &mmckinfoSubchunk, &mmckinfoParent,

                    MMIO_FINDCHUNK)) {

        Error("WAVE 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) != (LRESULT)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.

     */

    mmckinfoSubchunk.ckid = mmioFOURCC('d', 'a', 't', 'a');

    if (mmioDescend(hmmio, &mmckinfoSubchunk, &mmckinfoParent,

                    MMIO_FINDCHUNK)) {

        Error("WAVE 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 output device. */

    ...

    /* Allocate and lock memory for the waveform data. */

    ...

    /* Read the waveform data subchunk. */

    if(mmioRead(hmmio, (HPSTR) lpData,

            dwDataSize) != (LRESULT)dwDataSize) {

        Error("Failed to read data chunk.");

        ...

        mmioClose(hmmio, 0);

        return;

    }

    /* Close the file. */

    mmioClose(hmmio, 0);

    /* Reverse the sound and play it. */

    ...

}


Directly Accessing a File Input/Output Buffer

Applications that are performance sensitive, such as applications that must stream data in real time from a CD-ROM, can optimize file I/O performance by accessing the file I/O buffer directly. Exercise care if you choose to do this--by accessing the file I/O buffer directly, you bypass some of the safeguards and error checking provided by the file I/O manager.

The multimedia file I/O services provide the following functions to support direct I/O buffer access.

Function	Description

mmioAdvance	Fills and/or flushes the I/O buffer of a file set up for direct I/O buffer access.

mmioGetInfo	Retrieves information on the file I/O buffer of a file opened for buffered I/O.

mmioSetInfo	Changes information on the file I/O buffer of a file opened for buffered I/O.

To access a file I/O buffer directly, open the file for buffered I/O as described in "Performing Buffered File I/O." You can use the internal file I/O buffer or supply your own buffer by using the mmioSetBuffer function.


Getting Information on the File I/O Buffer

Use the mmioGetInfo function to get information on a file I/O buffer, such as the buffer size and address.


Reading and Writing the File I/O Buffer

There are three members in the MMIOINFO structure used for reading and writing the file I/O buffer: pchNext, pchEndRead, and pchEndWrite. The pchNext field points to the next location in the buffer to read or write. You must increment pchNext as you read and write the buffer. The pchEndRead field identifies the last valid character you can read from the buffer. Likewise, pchEndWrite identifies the last location in the buffer you can write. To be precise, both pchEndRead and pchEndWrite point to the memory location following the last valid data in the buffer.


Advancing the File I/O Buffer

When you reach the end of the file I/O buffer, you must advance the buffer to fill it from the disk (if you are reading), and flush it to the disk (if you are writing). Use the mmioAdvance function to advance a file I/O buffer.

The mmioAdvance function advances the buffer by (pchNext - cchBuffer) bytes. All data in the buffer before pchNext is assumed to have been read already, while all data from pchNext to pchEndRead will be considered unread. So, when mmioAdvance is called, all data before pchNext will be overwritten. The buffer must not be treated as an array and pchNext must be incremented until pchNext equals pchEndRead.

The following illustrations show how the file I/O buffer is advanced as a file is read or written.

Using the mmioAdvance Function

To fill a file I/O buffer from disk, call mmioAdvance with the MMIO_READ flag. If there is not enough data remaining in the file to fill the buffer, the pchEndRead member in the MMIOINFO structure points to the location following the last valid byte in the buffer.

To flush a buffer to disk, first set the MMIO_DIRTY flag in the dwFlags member of the MMIOINFO structure. Then call mmioAdvance with the MMIO_WRITE flag.


Example of Accessing a File I/O Buffer

The following example is based on the ReversePlay example function discussed earlier in this topic. In this example, direct-buffer access is used to read waveform data from a file.

HMMIO    hmmio;

MMIOINFO mmioinfo;

DWORD    dwDataSize;

DWORD    dwCount;

HPSTR    hptr;

    .

    .

    .

/* Get information on the file I/O buffer. */

if (mmioGetInfo(hmmio, &mmioinfo, 0)) {

    Error("Failed to get I/O buffer info");

    mmioClose(hmmio, 0);

    return FALSE;

}

/*

 * 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 FALSE;

        }

    }

    /* Get a character from the buffer. */

    *hptr++ = *mmioinfo.pchNext++;

}

/* End direct buffer access and close the file. */

mmioSetInfo(hmmio, &mmioinfo, 0);

mmioClose(hmmio, 0);


Ending Direct Access of a File I/O Buffer

When you finish accessing a file I/O buffer, pass the MMIOINFO structure filled by the mmioGetInfo function to the mmioSetInfo function to stop direct-buffer access. 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.


Performing File Input/Output on Memory Files

The multimedia file I/O services let you to 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 file memory images as if they were disk-based files. You can also use memory files with the Clipboard.


Opening Memory Files

Like 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 non-expandable. 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 mmioOpen 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 as follows:

Set the pIOProc member to NULL.

Set the fccIOProc member to FOURCC_MEM.

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.

Set the cchBuffer member to the initial size of the memory block.

Set the adwInfo[0] member to the minimum expansion size of the memory block. For a non-expandable memory file, set adwInfo[0] to NULL.

Set all other members to zero.

Allocating Memory for Memory Files

There are no restrictions on allocating memory for use as a non-expandable memory file. You can use static memory or stack memory, or you can use locally allocated or globally allocated memory. For expandable memory files, you must use memory allocated using the GlobalAlloc function and locked using the GlobalLock function.


Using Custom Input/Output Procedures

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. There are predefined I/O procedures for standard Microsoft® Windows™ files and for memory files. In the future, there will be a predefined I/O procedure for accessing elements of compound files. Compound files consist of a number of individual files, called file elements, bound together in one physical file.

You can supply a custom I/O procedure for accessing a unique storage system such as a database or file archive. This I/O procedure is private to your application.

The multimedia file I/O services provide the following functions to support custom I/O procedures:

Function	Description

mmioInstallIOProc	Installs, removes, or locates an I/O procedure.

mmioSendMessage	Sends a custom message to the I/O procedure associated with a file.


Opening a File Using a Custom I/O Procedure

Before learning about how to write an I/O procedure, it's helpful to understand how to use one. To open a file using a custom I/O procedure, use the mmioOpen function as you would to open any other file. Use a plus sign (+) in the filename to separate the name of the physical file from the name of the element of the file you want to open. For example, the following statement 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 looks at the preceding filename extension to determine which I/O procedure to associate with the file. In the previous example, the file I/O manager will attempt to use the I/O procedure associated with the .ARC filename extension. If no I/O procedure is installed, the mmioOpen function returns an error.


Writing an I/O Procedure

An I/O procedure is a message-processing function supplied by an application. An I/O procedure function has the following syntax:

LRESULT IOProc(lpmmioinfo, wMsg, lParam1, lParam2)

The lpmmioinfo parameter specifies a pointer to an MMIOINFO structure associated with the file being accessed.

The wMsg parameter is of type UINT and specifies the message being sent by the file I/O manager to the I/O procedure.

The lParam1 parameter is of type LPARAM and specifies 32 bits of message-dependent information.

The lParam2 parameter is of type LPARAM and specifies 32 bits of message-dependent information.

The return value is message-dependent. If the I/O procedure does not recognize a message, it should return zero.

I/O Procedure Messages

I/O procedures must respond to the MMIOM_CLOSE, MMIOM_OPEN, MMIOM_READ, MMIOM_WRITE, MMIOM_SEEK, MMIOM_RENAME, and MMIOM_WRITEFLUSH messages. Each of these messages has two parameters.

You can also create custom messages and send them to your I/O procedure using the mmioSendMessage function. If you define your own messages, be sure they are defined at or above the MMIOM_USER message. For example, the following example defines a message named MMIOM_MYMESSAGE:

#define   MMIOM_MYMESSAGE         MMIOM_USER + 0

Using the MMIOINFO Structure

In addition to processing messages, an I/O procedure must maintain the lDiskOffset member in the MMIOINFO structure referenced by the lpmmioinfo parameter. 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.


Installing an I/O Procedure

Use mmioInstallIOProc to install, remove, or locate an I/O procedure.

For example, to install an I/O procedure associated with the filename extension ARC, use the following statement:

mmioInstallIOProc (mmioFOURCC('A', 'R', 'C', ' '),

                   (LPMMIOPROC)lpmmioproc, MMIO_INSTALLPROC);

Note:	Be sure to remove any I/O procedures you've installed before closing your application.

Installing an I/O Procedure Using MmioOpen

When you install an I/O procedure by using the mmioInstallIOProc function, the procedure remains installed until you remove it. The I/O procedure will be used for any file you open if 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 only used with a file opened by 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 using mmioOpen, use the lpmmioinfo parameter to reference an MMIOINFO structure as follows:

Set the fccIOProc member to NULL.

Set the pIOProc member to the procedure-instance address of the I/O procedure.

Set all other members to zero (unless you are opening a memory file, or directly reading or writing to the file I/O buffer).


Common Dialog Box Library Overview

About Common Dialog Boxes

Common dialog boxes make it easier to develop applications for the Microsoft® Windows™ operating system. A common dialog box is a dialog box an application displays by calling a single function rather than by supplying a dialog box procedure and a resource file containing a dialog box template. The dynamic-link library COMDLG32.DLL provides a default procedure and a template for each type of common dialog box. Each default dialog box procedure processes messages and notifications for a common dialog box and its controls. A default dialog box template defines the appearance of a common dialog box and its controls.

The following topics discuss Win32 common dialog boxes:

Terms

The Color Dialog Box

The Font Dialog Box

The Open and Save As Dialog Boxes

The Print and Print Setup Dialog Boxes

The Find and Replace Dialog Boxes

Setting the Required Stack Size

Using the Color Dialog Box to Display Basic Colors

Using the Color Dialog Box to Display Custom Colors

Displaying the Font Dialog Box in Your Application

Displaying the Open Dialog Box in Your Application

Displaying the Save As Dialog Box in Your Application

Monitoring List Box Controls in an Open or Save As Dialog Box

Monitoring Filenames in an Open or Save As Dialog Box

Displaying a Print Dialog Box for the Default Printer

Displaying the Find Dialog Box

Displaying the Replace Dialog Box

Processing Dialog Box Messages for a Find or Replace Dialog Box

Customizing Common Dialog Boxes

Appropriate and Inappropriate Customizations

Hook Functions and Custom Dialog Box Templates

Displaying the Custom Dialog Box

Supporting and Processing Help for the Common Dialog Boxes

Error Detection

Common dialog boxes, in addition to simplifying the development of Windows applications, are helpful to users because they provide a standard set of controls for performing certain operations. As Windows developers begin using common dialog boxes in their applications, users will find that after they master common dialog boxes in one application, they can easily perform the same operations in other applications.

This topic describes the various common dialog boxes and includes example code to help you use common dialog boxes in your Windows-based applications.

Following are the types of common dialog boxes in the order in which they are presented in this topic:

Name	Description

Color	Displays available colors as well as controls that allow the user to define custom colors.

Font	Displays lists of fonts and point sizes that correspond to available fonts; after the user selects a font, the dialog box displays sample text rendered with that font.

Open	Displays a list of filenames matching any specified extensions, directories, and drives. By selecting one of the listed filenames, the user indicates the file an application should open.

Save As	Displays a list of filenames matching any specified extensions, directories, and drives. By selecting one of the listed filenames, the user indicates the file an application should save.

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

Print Setup	Displays the current printer configuration and provides options for setting the paper orientation, size, and source (when the printer driver supports these options). The Print Setup dialog box can be called directly, or opened from within the Print dialog box.

Find	Displays an edit control in which the user can type a string for which the application should search. The user can specify the direction of the search, whether the application should match the case of the specified string, and whether the string to match is an entire word.

Replace	Displays two edit controls in which 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.


The Color Dialog Box

The Color dialog box contains controls that enable a user to select and create colors.

Following is a Color dialog box.

The Basic Colors control displays up to 48 colors. The actual number of colors displayed is determined by the display driver. For example, a VGA driver displays 48 colors, and a monochrome display driver displays only 16. With the Basic Colors control, the user can select a displayed color.

To display the Custom Colors control, the user clicks the Define Custom Colors button. The Custom Colors control displays custom colors. The user can select one of the 16 rectangles in this control and then create a new color by using one of the following methods:

Specifying red, green, and blue (RGB) values by using the Red, Green, and Blue edit controls, and then choosing the Add to Custom Colors button to display the new color in the selected rectangle.

Moving the cursor in the color spectrum control (at the upper right of the dialog box) to select hue and saturation values; moving the cursor in the luminosity control (the rectangle to the right of the spectrum control); and then choosing the Add to Custom Colors button to display the new color in the selected rectangle.

Specifying hue, saturation, and luminosity (HSL) values by using the Hue, Sat, and Lum edit controls and then choosing the Add to Custom Colors button to display the new color in the selected rectangle.

The Color|Solid control displays the dithered and solid colors that correspond to the user's selection. (A dithered color is a color created by combining one or more pure or solid colors.) The Flags member of the CHOOSECOLOR structure contains a flag bit that, when set, displays a Help button.

An application can display the Color dialog box in one of two ways: fully open or partially open. When the Color dialog box is displayed partially open, the user cannot change the custom colors.

Color Models Used by the Color Dialog Box

The Color dialog box uses two models for specifying colors: the RGB model and the HSL model. Regardless of the model used, internal storage is accomplished by use of the RGB model.

RGB Color Model

The RGB model is used to designate colors for displays and other devices that emit light. Valid red, green, and blue values are in the range 0 through 255, with 0 indicating minimum intensity and 255 indicating maximum intensity. The following illustration shows how the primary colors red, green, and blue can be combined to produce four additional colors. (With display devices, the color black results when the red, green, and blue values are set to 0; in display technology, black is the absence of all colors.)

Following are eight colors and their associated RGB values.

Color	RGB values

Red	255, 0, 0

Green	0, 255, 0

Blue	0, 0, 255

Cyan	0, 255, 255

Magenta	255, 0, 255

Yellow	255, 255, 0

White	255, 255, 255

Black	0, 0, 0

Windows stores internal colors as 32-bit RGB values. The high-order byte of the high-order word is reserved; the low-order byte of the high-order word specifies the intensity of the blue component; the high-order byte of the low-order word specifies the intensity of the green component; and the low-order byte of the low-order word specifies the intensity of the red component.

HSL Color Model

The Color dialog box provides controls for specifying HSL values. The following illustration shows the color spectrum control and the vertical luminosity control that appear in the Color dialog box and shows the ranges of values the user can specify with these controls.

In the Color dialog box, the saturation and luminosity values must be in the range 0 through 240 and the hue value must be in the range 0 through 239.

Converting HSL Values to RGB Values

The dialog box procedure provided in COMDLG32.DLL for the Color dialog box contains code that converts HSL values to the corresponding RGB values. Following are several colors and their associated HSL and RGB values:

Color	HSL values	RGB values

Red	(0, 240, 120)	(255, 0, 0)

Yellow	(40, 240, 120)	(255, 255, 0)

Green	(80, 240, 120)	(0, 255, 0)

Cyan	(120, 240, 120)	(0, 255, 255)

Blue	(160, 240, 120)	(0, 0, 255)

Magenta	(200, 240, 120)	(255, 0, 255)

White	(0, 0, 240)	(255, 255, 255)

Black	(0, 0, 0)	(0, 0, 0)


The Font Dialog Box

The Font dialog box contains controls that allow a user to choose a font, a font style (such as bold, italic, or regular), a point size, and an effect (such as underline, strikeout, or a text color).

Following is a Font dialog box.


The Open and Save As Dialog Boxes

The Open dialog box and the Save As dialog box are similar in appearance. Each contains controls that enable a user to specify the location and name of a file or a set of files. In the case of the Open dialog box, the user selects the file or files to be opened; in the case of the Save As dialog box, the user selects the file or files to be saved.

Following is an Open dialog box.

Following is a Save As dialog box.


The Print and Print Setup Dialog Boxes

A Print dialog box contains controls that allow a user to configure a printer for a particular print job. The user can make such selections as print quality, page range, and number of copies (if the printer supports multiple copies).

Following is a Print dialog box.

Choosing the Setup button in the Print dialog box displays the following Print Setup dialog box for a PostScript printer.

The Print Setup dialog box provides controls that enable the user to reconfigure the selected printer.

Device Drivers and the Print Dialog Box

The Print dialog box differs from other common dialog boxes in that part of its dialog box procedure resides in COMDLG32.DLL and part in a printer driver. A printer driver is a program that configures a printer, converts graphics device interface (GDI) commands to low-level printer commands, and stores commands for a particular print job in a printer's queue.

A printer driver exports a function called ExtDeviceMode that displays a dialog box and its controls. In previous versions of Windows, an application called the LoadLibrary function to load a device driver and the GetProcAddress function to obtain the address of the ExtDeviceMode function. This is no longer necessary with the Windows common dialog box interface. Instead of calling LoadLibrary and GetProcAddress, a Windows application can call a single function, PrintDlg, to display the Print dialog box and begin a print job. The code for PrintDlg resides in COMDLG32.DLL. The dialog box that appears when an application calls PrintDlg differs slightly from the dialog box that appears when the application calls directly into the device driver. The functionality is very similar in spite of the different appearance.


The Find and Replace Dialog Boxes

The Find dialog box and the Replace dialog box are similar in appearance. You can use the Find dialog box to add string-search capabilities to your application and the Replace dialog box to add both string-search and string-substitution capabilities.

The Find and the Replace dialog boxes differ from the other common dialog boxes in that they are modeless. This means the user can switch between the dialog box and the window that created that dialog box.

Following is the Find dialog box.

Following is the Replace dialog box.


Setting the Required Stack Size

Applications using the common dialog boxes should specify at least 8K for the stack size, as shown in the following example:

NAME         Generic

DESCRIPTION  'Sample Application for Microsoft Windows'

EXETYPE      WINDOWS

STUB         'WINSTUB.EXE'

CODE  PRELOAD MOVEABLE DISCARDABLE

DATA  PRELOAD MOVEABLE MULTIPLE

HEAPSIZE     1024

STACKSIZE    8192 ; increased stack size for common dialog boxes

EXPORTS

        MainWndProc   @1

        About         @2


Using the Color Dialog Box to Display Basic Colors

You can have your application display the Color dialog box so a user can select one color from a list of basic screen colors. This section describes how you can provide code and structures in your application that make this possible.

Initializing the CHOOSECOLOR Structure

Before displaying a Color dialog box, an application must initialize a CHOOSECOLOR structure. This structure should be global or declared as a static variable. The members of this structure contain information about such items as the following:

Structure size

Which window owns the dialog box

Whether the application is customizing the common dialog box

The hook function and custom dialog box template to use for a customized version of the Color dialog box

RGB values for the selected basic color

If your application does not customize the dialog box and you want the user to be able to select a single color from the basic colors, initialize the CHOOSECOLOR structure in the following manner:

/* Color variables */

CHOOSECOLOR cc;     /* common dialog box structure */

COLORREF acrCustClr[16] = { RGB(255, 255, 255), RGB(239, 239, 239),

                            RGB(223, 223, 223), RGB(207, 207, 207),

                            RGB(191, 191, 191), RGB(175, 175, 175),

                            RGB(159, 159, 159), RGB(143, 143, 143),

                            RGB(127, 127, 127), RGB(111, 111, 111),

                            RGB(95, 95, 95), RGB(79, 79, 79),

                            RGB(63, 63, 63), RGB(47, 47, 47),

                            RGB(31, 31, 31), RGB(15, 15, 15)

                           }; /* array of gray colors */

                    /* Initialize necessary members. */

                    cc.lStructSize = sizeof(CHOOSECOLOR);

                    cc.hwndOwner = hwnd;

                    cc.lpCustColors = (LPDWORD) acrCustClr;

                    cc.Flags = CC_PREVENTFULLOPEN;

                    /* Call the ChooseColor function. */

                    if (ChooseColor(&cc)){

.

. /* Use cc.lpCustColors to select the user's requested color. */

.

                    }

In the previous example, the array pointed to by the lpCustColors member contains 16 doubleword RGB values that specify the color white, and the CC_PREVENTFULLOPEN flag is set in the Flags member to disable the Define Custom Colors button and prevent the user from selecting a custom color.

Calling the ChooseColor Function

After you initialize the structure, call the ChooseColor function. If the function succeeds and the user chooses the OK button to close the dialog box, the rgbResult member contains the RGB values for the basic color the user selected.


Using the Color Dialog Box to Display Custom Colors

You can have your application display the Color dialog box so the user can create and select a custom color. This section describes how you can provide code and structures in your application that make this possible.

Initializing the CHOOSECOLOR Structure

Before displaying a Color dialog box, an application must initialize a CHOOSECOLOR structure. This structure should be global or declared as a static variable. The members of this structure contain information about such items as the following:

Structure size

Which window owns the dialog box

Whether the application is customizing the common dialog box

The hook function and custom dialog box template to use for a customized version of the Color dialog box

RGB values for the custom color control

If your application does not customize the dialog box and you want the user to be able to create and select custom colors, initialize the CHOOSECOLOR structure in the following manner.

/* Color variables */

CHOOSECOLOR cc;     /* common dialog box structure */

COLORREF acrCustClr[16] = { RGB(255, 255, 255), RGB(239, 239, 239),

                            RGB(223, 223, 223), RGB(207, 207, 207),

                            RGB(191, 191, 191), RGB(175, 175, 175),

                            RGB(159, 159, 159), RGB(143, 143, 143),

                            RGB(127, 127, 127), RGB(111, 111, 111),

                            RGB(95, 95, 95), RGB(79, 79, 79),

                            RGB(63, 63, 63), RGB(47, 47, 47),

                            RGB(31, 31, 31), RGB(15, 15, 15)

                           }; /* array of gray colors */

                    /* Initialize the necessary members. */

                    cc.lStructSize = sizeof(CHOOSECOLOR);

                    cc.hwndOwner = hwnd;

                    cc.lpCustColors = (LPDWORD) acrCustClr;

                    cc.Flags = CC_FULLOPEN;

In the previous example, the array pointed to by lpCustColors contains sixteen 32-bit RGB values that specify 16 scales of gray, and the CC_FULLOPEN flag is set in the Flags member to display the complete Color dialog box.

Calling the ChooseColor Function

After you initialize the structure, you should call ChooseColor, as shown in the following code:

                    /* Call the ChooseColor() function. */

                    if (ChooseColor(&cc)){

.

. /* Use cc.lpCustColors to select the user's requested color. */

.

                    }

If the function succeeds and the user chooses the OK button to close the dialog box, the lpCustColors member points to an array that contains the RGB values for the custom colors requested by the user.

You can give your application more control over custom colors by creating a new message identifier for the string defined by the COLOROKSTRING constant. The application creates the new message identifier by calling the RegisterWindowMessage function and passing this constant as the single parameter. After calling RegisterWindowMessage, the application receives a message immediately before the dialog box closes. The lParam parameter of this message contains a pointer to the CHOOSECOLOR structure. The application can use the lpCustColors member of this structure to check the current color. If the application returns a nonzero value when it processes this message, the dialog box does not close.

Similarly, you can have your application create a new message identifier for the string defined by the SETRGBSTRING constant. The application's hook function can use the message identifier returned by calling RegisterWindowMessage with the SETRGBSTRING constant to set a color in the dialog box. For example, the following line of code sets the color selection to blue.

SendMessage(hwndDlg, wSetRGBMsg, 0, (LPARAM) RGB(0, 0, 255));

In this example, wSetRGBMsg is the message identifier returned by RegisterWindowMessage. The lParam parameter of the SendMessage function is set to the RGB values of the desired color. The wParam parameter is not used.

You can have your application specify any valid RGB values in this call to SendMessage. If the RGB values match one of the basic colors, the operating system selects the basic color and updates the spectrum and luminosity controls. If the RGB values do not match one of the basic colors, the system updates the spectrum and luminosity controls, but the basic color selection remains unchanged.

Note that if the Color dialog box is not fully open and the application sends RGB values that do not match one of the basic colors, the operating system does not update the dialog box. Updates are unnecessary because the spectrum and luminosity controls are not visible when the dialog box is only partially open.

For more information about processing registered window messages, see Displaying the Find Dialog Box.


Displaying the Font Dialog Box in Your Application

The Font dialog box appears after you initialize the members in a CHOOSEFONT structure and call the ChooseFont function. This structure should be global or declared as a static variable. The members of the CHOOSEFONT structure contain information about the following items:

The attributes of the font that initially appears in the dialog box.

The attributes of the font the user selected.

The point size of the font the user selected.

Whether the list of fonts corresponds to a printer, a screen, or both.

Whether the available fonts listed are TrueType only.

Whether the Effects box should appear in the dialog box.

Whether dialog box messages should be processed by an application-defined hook function.

Whether the point sizes of the selectable fonts should be limited to a specified range.

Whether the dialog box displays only what-you-see-is-what-you-get (WYSIWYG) fonts. (These fonts are resident on both the screen and the printer.)

The color ChooseFont uses to render text in the Sample box the first time the application displays the dialog box.

The color the user selected for text output.

To display the Font dialog box, include the following steps in your application:

1	If the application requires printer fonts, retrieve a device-context (DC) handle for the printer and use this handle of set the hDC member of the CHOOSEFONT structure. (If the Font dialog box displays only screen fonts, this member should be set to NULL.)

2	Set the appropriate flags in the Flags member of the CHOOSEFONT structure. This setting must include CF_SCREENFONTS, CF_PRINTERFONTS, or CF_BOTH.

3	Set the rgbColors member of the CHOOSEFONT structure if the default color (black) is not appropriate.

4	Set the nFontType member of the CHOOSEFONT structure by using the appropriate constant.

5	Set the nSizeMin and nSizeMax members of the CHOOSEFONT structure if the CF_LIMITSIZE value is specified in the Flags member.

6	Call the ChooseFont function.

The following example initializes the CHOOSEFONT structure, calls ChooseFont, and uses the requested font to draw text on the display.

/* Font variables */

CHOOSEFONT cf;      /* common dialog box structure */

LOGFONT lf;         /* logical-font structure */

HDC hdc;            /* display DC handle */

HFONT hfont;        /* new logical-font handle */

HFONT hfontOld;     /* original logical-font handle */

COLORREF crOld;     /* original text color */

                    /* Initialize the necessary members. */

                    cf.lStructSize = sizeof (CHOOSEFONT);

                    cf.hwndOwner = hwnd;

                    cf.lpLogFont = &lf;

                    cf.Flags = CF_SCREENFONTS | CF_EFFECTS;

                    cf.rgbColors = RGB(0, 255, 255);

                    cf.nFontType = SCREEN_FONTTYPE;

                    /*

                     * Display the dialog box, allow the user to

                     * choose a font, and render the text in the

                     * window with that selection.

                     */

                    if (ChooseFont(&cf)){

                        hdc = GetDC(hwnd);

                        hfont = CreateFontIndirect(cf.lpLogFont);

                        hfontOld = SelectObject(hdc, hfont);

                        crOld = SetTextColor(hdc, cf.rgbColors);

                        TextOut(hdc, 50, 150,

                            "AaBbCcDdEeFfGgHh", 16);

                        SetTextColor(hdc, crOld);

                        SelectObject(hdc, hfontOld);

                        DeleteObject(hfont);

                        ReleaseDC(hwnd, hdc);

                        }

An application can also use the WM_CHOOSEFONT_GETLOGFONT message to retrieve the current LOGFONT structure for the Font dialog box before the user closes the dialog box.


Displaying the Open Dialog Box in Your Application

The Open dialog box appears after you initialize the members of an OPENFILENAME structure and call the GetOpenFileName function.

Before you call GetOpenFileName, structure members contain such data as the name of the directory and the filter that appears in the dialog box. (A filter is a filename extension. The common dialog box code uses the extension to filter appropriate filenames from a directory.) After the call, structure members contain such data as the name of the selected file and the number of characters in that filename.

To display an Open dialog box, include the following steps in your application:

1	Store the valid filters in a character array.

2	Set the lpstrFilter member to point to this array.

3	Set the nFilterIndex member to the value of the index that identifies the default filter.

4	Set the lpstrFile member to point to an array that contains the initial filename and receives the selected filename.

5	Set the nMaxFile member to the value that specifies the length of the filename array.

6	Set the lpstrFileTitle member to point to a buffer that receives the title of the selected file.

7	Set the nMaxFileTitle member to specify the length of the buffer.

8	Set the lpstrInitialDir member to point to a string that specifies the initial directory. (If this member does not point to a valid string, it must be set to 0 or point to a string set to NULL.)

9	Set the lpstrTitle member to point to a string specifying the name that appears in the title bar of the dialog box. (If this pointer is NULL, the title is Open.)

10	Initialize the lpstrDefExt member to point to the default extension. (This extension can be 0, 1, 2, or 3 characters long.)

11	Call the GetOpenFileName function.

The following example initializes an OPENFILENAME structure, calls GetOpenFileName, and opens the file by using the lpstrFile member of the structure. The OPENFILENAME structure should be global or declared as a static variable.

OPENFILENAME ofn;       /* common dialog box structure */

char szDirName[256];    /* directory string */

char szFile[256];       /* filename string */

char szFileTitle[256];  /* file-title string */

char szFilter[256];     /* filter string */

char chReplace;         /* string separator for szFilter */

int i, cbString;        /* integer count variables */

HANDLE hf;              /* file handle */

.

.

.

                    /*

                     * Retrieve the system directory name and

                     * store it in szDirName.

                     */

                     GetSystemDirectory(szDirName, sizeof(szDirName));

                    /* Place the terminating null character in the szFile. */

                     szFile[0] = '\0';

                    /* Load the filter string from the .RC file. */

                     cbString = LoadString(hinst, IDS_FILTERSTRING,

                                    szFilter, sizeof(szFilter));

                    /*

                     * Add a terminating null character to the filter string.

                     */

                     chReplace = szFilter[cbString - 1];

                     for (i = 0; szFilter[i] != '\0'; i++){

                         if (szFilter[i] == chReplace)

                            szFilter[i] = '\0';

                        }

                    /* Set the members of the OPENFILENAME structure. */

                    ofn.lStructSize = sizeof(OPENFILENAME);

                    ofn.hwndOwner = hwnd;

                    ofn.lpstrFilter = szFilter;

                    ofn.nFilterIndex = 1;

                    ofn.lpstrFile = szFile;

                    ofn.nMaxFile = sizeof(szFile);

                    ofn.lpstrFileTitle = szFileTitle;

                    ofn.nMaxFileTitle = sizeof(szFileTitle);

                    ofn.lpstrInitialDir = szDirName;

                    ofn.Flags = OFN_SHOWHELP | OFN_PATHMUSTEXIST |

                        OFN_FILEMUSTEXIST;

                    /* Display the Open dialog box. */

                    if (GetOpenFileName(&ofn)) {

                        /* Open the file. */

                        hf = CreateFile(ofn.lpstrFile, GENERIC_READ,

                                 0, (LPSECURITY_ATTRIBUTES) NULL,

                                 OPEN_EXISTING,

                                 FILE_ATTRIBUTE_NORMAL,

                                 (HANDLE) NULL);

.

. /* Perform the necessary file operations. */

.

                        /* Close the file. */

                        CloseHandle(hf);

                       } /* end if */

The string referred to by the IDS_FILTERSTRING constant in the preceding example is defined as follows in the resource-definition file:

STRINGTABLE

BEGIN

    IDS_FILTERSTRING "Bitmap File(*.BMP)|*.bmp|"

END

The vertical bars in this string are used as wildcards. After the LoadString function is used to retrieve the string, the wildcards are replaced with NULL. The wildcard can be any unique character and must be included as the last character in the string. Initializing strings in this manner guarantees that the parts of the string are contiguous in memory and that the string is terminated with two null characters.

An application that can open files over a network can create a new message identifier for the string defined by the SHAREVISTRING constant. The application creates the new message identifier by calling the RegisterWindowMessage function and passing this constant as the single parameter. After calling RegisterWindowMessage, the application is notified whenever a sharing violation occurs during a call to the OpenFile function. For more information about processing registered window messages, see Displaying the Find Dialog Box.


Displaying the Save As Dialog Box in Your Application

The Save As dialog box appears after you initialize the members of an OPENFILENAME structure and call the GetSaveFileName function.

Before you call GetSaveFileName, structure members contain such data as the name of the initial directory and a filter string. After the call, structure members contain such data as the name of the file to be saved and the number of characters in that filename.

The following example initializes an OPENFILENAME structure, calls GetSaveFileName, and saves the file. The OPENFILENAME structure should be global or declared as a static variable.

OPENFILENAME ofn;       /* common dialog box structure */

char szDirName[256];    /* directory string */

char szFile[256];       /* filename string */

char szFileTitle[256];  /* file-title string */

char szFilter[256];     /* filter string */

char chReplace;         /* string separator for szFilter */

int i, cbString;        /* integer count variables */

HANDLE hf;              /* file handle */

                    /*

                     * Retrieve the system directory name and

                     * store it in szDirName.

                     */

                     GetSystemDirectory(szDirName, sizeof(szDirName));

                    /* Place the terminating null character in szFile. */

                     szFile[0] = '\0';

                    /* Load the filter string from the .RC file. */

                     cbString = LoadString(hinst, IDS_FILTERSTRING,

                         szFilter, sizeof(szFilter));

                    /*

                     * Add a terminating null character to the filter string.

                     */

                     chReplace = szFilter[cbString - 1];

                     for (i = 0; szFilter[i] != '\0'; i++){

                         if (szFilter[i] == chReplace)

                            szFilter[i] = '\0';

                        }

                    /* Set the members of the OPENFILENAME structure. */

                    ofn.lStructSize = sizeof(OPENFILENAME);

                    ofn.hwndOwner = hwnd;

                    ofn.lpstrFilter = szFilter;

                    ofn.nFilterIndex = 1;

                    ofn.lpstrFile = szFile;

                    ofn.nMaxFile = sizeof(szFile);

                    ofn.lpstrFileTitle = szFileTitle;

                    ofn.nMaxFileTitle = sizeof(szFileTitle);

                    ofn.lpstrInitialDir = szDirName;

                    ofn.Flags = OFN_SHOWHELP | OFN_OVERWRITEPROMPT;

                    /* Display the Save As dialog box. */

                    if (GetSaveFileName(&ofn)) {

.

. /* Perform the necessary file operations. */

.

                        /* Close the file. */

                        CloseHandle(hf);

                       } /* end if */

The string referred to by the IDS_FILTERSTRING constant in the preceding example is defined in the resource-definition file. It is used in exactly the same way as the IDS_FILTERSTRING constant discussed in Displaying the Open Dialog Box in Your Application.


Monitoring List Box Controls in an Open or Save As Dialog Box

An application can monitor list box selections to process and display data in custom controls. For example, an application can use a custom control to display the total length, in bytes, of all files selected in the File Name box. One method the application can use to obtain this value is to recompute the total count of bytes each time the user selects a file or cancels the selection of a file. A faster method is for the application to use the LBSELCHSTRING message to identify a new selection and add the corresponding file length to the value that appears in the custom control. (Note that, in this example, the custom control is a standard Windows control that you identify in a resource file template for one of the common dialog boxes.)

An application registers the selection-change message with the RegisterWindowMessage function. After the application registers the message, it uses this function's return value to identify messages from the dialog box. The message is processed in the application-defined hook function for the common dialog box. The wParam parameter of each message identifies the list box in which the selection occurred. The low-order word of the lParam parameter identifies the list box item. The high-order word of the lParam parameter is one of the following values.

Value	Meaning

CD_LBSELCHANGE	The item identified by the low-order word of lParam was the item in a single-selection list box.

CD_LBSELSUB	The item identified by the low-order word of lParam is no longer selected in a multiple-selection list box.

CD_LBSELADD	The item identified by the low-order word of lParam was selected from a multiple-selection list box.

CD_LBSELNOITEMS	No items exist in a multiple-selection list box.

For an example that registers a common dialog box message, see Displaying the Find Dialog Box.


Monitoring Filenames in an Open or Save As Dialog Box

An application can alter the normal processing of an Open or Save As dialog box by monitoring the filename the user types and by performing other unique operations. For example, one application could prevent the user from closing the dialog box if the selected filename is prohibited; another application could enable the user to select multiple filenames.

To monitor filenames, register the FILEOKSTRING message. Do this by calling the RegisterWindowMessage function and passing the message name as its single parameter. After the message has been registered, the dialog box procedure in COMDLG32.DLL uses it to signal that the user has selected a filename and chosen the OK button and that the dialog box has checked the filename and is ready to return. The dialog box procedure signals these actions by sending the message to the application's hook function. After receiving the message, the hook function should return a value to the dialog box procedure that called it. If the hook function did not process the message, it should return 0; if the hook function did process the message and the dialog box should close, the hook function should return 0; if the hook function did process the message but the dialog box should not close, the hook function should return 1. All other return values are reserved.


Displaying a Print Dialog Box for the Default Printer

To display a Print dialog box for the default printer, initialize a PRINTDLG structure and then call the PrintDlg function.

The members of the PRINTDLG structure can contain information about the following items:

The printer device context

Values that should appear in the dialog box controls

The hook function and custom dialog box template to use for a customized version of the Print dialog box or Print Setup dialog box

To display a Print dialog box for the currently installed printer, include the following steps in your application:

1	Set the PD_RETURNDC flag in the Flags member of the PRINTDLG structure. (This flag should be set only if the application requires a device-context handle.)

2	Initialize the lStructSize, hDevMode, and hDevNames members.

3	Call the PrintDlg function and pass a pointer to the PRINTDLG structure just initialized.

Setting the PD_RETURNDC flag causes PrintDlg to display the Print dialog box and return a handle identifying a printer device context in the hDC member of the PRINTDLG structure. (The application passes the device-context handle as the first parameter to the graphics device interface (GDI) functions that render output on the printer.)


Displaying the Find Dialog Box

The Find dialog box contains controls that allow a user to specify the following:

The string that the application should find

Whether the string specifies a complete word or part of a word

Whether the application should match the case of the specified string

The direction the application should search (preceding or following the current cursor location)

Whether the application should resume the search, searching for the next occurrence of the string

To display the Find dialog box, initialize a FINDREPLACE structure and call the FindText function. Members of the FINDREPLACE structure contain information about the following items:

Which window owns the dialog box

How the application should perform the search

A character buffer to receive the string

To initialize the FINDREPLACE structure, perform the following tasks:

1	Set the lStructSize member by using the sizeof operator.

2	Set the hwndOwner member by using the handle that identifies the owner window of the dialog box.

3	If you are customizing the Find dialog box, set the hInstance member to identify the instance of the module that contains your custom dialog box template.

4	Set the Flags member to indicate the selection state of the dialog box options. (For example, setting the FR_NOUPDOWN flag disables the Up and Down buttons, setting the FR_NOWHOLEWORD flag disables the Match Whole Word Only check box, and setting the FR_NOMATCHCASE flag disables the Match Case check box.)

5	If you are supplying a custom dialog box template or hook function, set additional flags in the Flags member.

6	Set the lpstrFindWhat member to point to the buffer receiving the string to be found.

7	Set the wFindWhatLen member to specify the size, in bytes, of the buffer pointed to by lpstrFindWhat.

8	Set the lCustData member with any custom data your application may need to access.

9	If your application customizes the Find dialog box, set the lpfnHook member to point to your hook function.

10	If your application uses a custom dialog box template, set the lpTemplateName member to point to the string that identifies the template.

The following example initializes the FINDREPLACE structure and then calls FindText. This structure should be global or declared as a static variable.

/* Find/Replace variables */

FINDREPLACE fr;         /* common dialog box structure */

FINDREPLACE FAR* lpfr;  /* pointer to common dialog box structure */

CHAR szFindWhat[80];    /* buffer receiving string to be found */

HWND hdlg;              /* handle identifying dialog window */

UINT uFindReplaceMsg;   /* value returned by RegisterMessage() */

                    /* Initialize the necessary members. */

                    fr.lStructSize = sizeof(FINDREPLACE);

                    fr.hwndOwner = hwnd;

                    fr.lpstrFindWhat = szFindWhat;

                    fr.wFindWhatLen = sizeof(szFindWhat);

                    /* Display the modeless Find dialog box. */

                    hdlg = FindText(&fr);


Displaying the Replace Dialog Box

The Replace dialog box is similar to the Find dialog box. However, the Replace dialog box has no Direction check box and has three additional controls that enable the user to specify the following:

The replacement string

Whether the application should replace the occurrence of the string currently highlighted

Whether the application should replace all occurrences of the string

To display the Replace dialog box, initialize a FINDREPLACE structure and call the ReplaceText function.


Processing Dialog Box Messages for a Find or Replace Dialog Box

The Find and Replace dialog boxes differ from the other common dialog boxes in two respects: First, they are modeless; and second, their respective dialog box procedures send messages to the application that calls the FindText or ReplaceText function. These messages contain data specified by the user in the dialog box controls, such as the direction the application should search for a string, whether the application should match the case of the specified string, and whether the application should match the entire string.

To process messages from a Find or Replace dialog box, an application must register the dialog box's unique message, FINDMSGSTRING.

The application registers this message with the RegisterWindowMessage function. After the application registers the message, it uses the function's return value to identify messages from the Find or Replace dialog box. The following example registers the message with RegisterWindowMessage:

/* Register the FindReplace message. */

uFindReplaceMsg = RegisterWindowMessage(FINDMSGSTRING);

After the application registers this message, it can process messages for the Find or Replace dialog box by using the RegisterWindowMessage return value. The following example processes messages for the Find dialog box and then calls its own SearchFile function to locate the string of text. If the user is closing the dialog box (that is, if the Flags member of the FINDREPLACE structure is FR_DIALOGTERM), the handle is invalidated and the procedure returns zero.

if (message == uFindReplaceMsg){

    /*

     * Extract a pointer to the FINDREPLACE

     * structure from lParam.

     */

     lpfr = (FINDREPLACE FAR*) lParam;

    /*

     * If the system has set the FR_DIALOGTERM

     * flag, invalidate the handle identifying

     * the dialog box.

     */

     if (lpfr->Flags & FR_DIALOGTERM){

        hdlg = NULL;

        return 0;

        }

    /*

     * If the dialog box is still valid, call the

     * application-defined search routine (SearchFile) to

     * search for the requested string.

     */

     SearchFile((BOOL) (lpfr->Flags & FR_DOWN),

        (BOOL) (lpfr->Flags & FR_MATCHCASE));

     return 0;

     }


Customizing Common Dialog Boxes

A custom common dialog box is a common dialog box altered to suit a particular Windows-based application. The customization may be complex and include the hiding of original controls, the addition of new controls, or a change in the size of the original dialog box; or it may be simple, involving the alteration of a single existing control.

If you want to customize a common dialog box, you must provide a special hook function and, in most cases, a custom dialog box template. Customizations of this kind require a significant amount of additional code--displaying a customized common dialog box is not as simple as initializing the members of a structure and calling a single function.

Applications that subclass controls in any of the common dialog boxes must do so while processing the WM_INITDIALOG message in the application's hook function. This allows the application to receive the control-specific messages first, because it will have subclassed the control after the common dialog box has installed its subclassing procedures. (The previous hook function should be called for all messages not handled by the application's subclass function, as is standard for subclassing.)

An application cannot subclass a control by defining a local class to override a specific control type. This is because the data segment would not be initialized correctly when the class was called--the data segment would be the common dialog box's data segment, not the application's data segment.


Appropriate and Inappropriate Customizations

From the user's perspective, the chief benefit of the common dialog box is its consistent appearance and functionality from application to application. Therefore, it becomes important that you customize a common dialog box only when it is absolutely necessary for an application. Otherwise, the consistent appearance and simple coding interface are lost. Appropriate customizations leave intact as many of the original controls as possible. Increasing the size of the dialog box or adding new controls in available space that already appears in the dialog box would be an appropriate customization. Hiding original controls or otherwise changing the intended functionality of the original controls would be less appropriate customization.


Hook Functions and Custom Dialog Box Templates

Each common dialog box uses the dialog box procedure and dialog box template provided for it in COMDLG32.DLL. The dialog box procedure processes messages and notifications for the common dialog box and its controls. The dialog box template defines the appearance of the dialog box--its dimensions, its location, and the dimensions and locations of controls that appear within it.

In addition to the procedure and template provided, a custom dialog box requires a hook function that you provide and, usually, a custom version of the dialog box template.

The Hook Function

The dialog box procedure provided in COMDLG32.DLL for a common dialog box calls the application's hook function if the application sets the appropriate flag and pointer in the structure for that common dialog box. The structure for each common dialog box contains a Flags member that specifies whether the application defines a hook function and contains an lpfnHook member that points to the hook function, if one exists. If the application sets the Flags member to indicate that a hook function exists, it must also set the lpfnHook member. The following example sets the Flags and lpfnHook members of an OPENFILENAME structure to support an application's hook function.

#include <windows.h>    /* required for all Windows applications       */

#include <commdlg.h>    /* required for all common dialog box functions*/

#include <dlgs.h>

#include "generic.h"    /* specific to this application                */

OPENFILENAME ofn;       /* common dialog box structure */

char szDirName[256];    /* directory string */

char szFile[256];       /* filename string */

char szFileTitle[256];  /* file-title string */

char szFilter[256];     /* filter string */

char chReplace;         /* string separator for szFilter */

int i, cbString;        /* integer count variables */

DWORD cBufLen;          /* dword count */

DWORD cTmp;             /* dword count */

HANDLE hf;              /* original file handle */

HANDLE hfBackup;        /* backup file handle */

char szBuffer[256];     /* character buffer */

char szChar[256];       /* character buffer */

char* pszBackupFile;    /* pointer to backup filename */

BOOL fBackup;           /* TRUE if user checked "backup" box */

/* Retrieve the system directory name. */

GetSystemDirectory((LPSTR)szDirName, sizeof(szDirName));

/* Place the terminating null character in the szFile. */

szFile[0] = '\0';

/* Load the filter string from the .RC file. */

cbString = LoadString(hinst, IDS_FILTERSTRING,

               szFilter, sizeof(szFilter));

/* Add a terminating null character to the string. */

chReplace = szFilter[cbString - 1];

for (i = 0; szFilter[i] != '\0'; i++) {

    if (szFilter[i] == chReplace)

        szFilter[i] = '\0';

    }

/* Initialize the required OPENFILENAME members. */

ofn.lStructSize = sizeof(OPENFILENAME);

ofn.hwndOwner = hwnd;

ofn.hInstance = hinst;

ofn.lpstrFilter = szFilter;

ofn.nFilterIndex = 1;

ofn.lpstrFile = szFile;

ofn.nMaxFile = sizeof(szFile);

ofn.lpstrFileTitle = szFileTitle;

ofn.nMaxFileTitle = sizeof(szFileTitle);

ofn.lpstrInitialDir = szDirName;

ofn.Flags = OFN_SHOWHELP | OFN_PATHMUSTEXIST |

            OFN_FILEMUSTEXIST | OFN_ENABLEHOOK |

            OFN_ENABLETEMPLATE;

ofn.lpfnHook = FileOpenHookProc;

ofn.lpTemplateName = "FILEOPEN";

In the previous example, the address of the application-defined hook function is assigned to the lpfnHook member of the OPENFILENAME structure. The hook function processes any messages or notifications the custom dialog box requires. With the exception of one message (WM_INITDIALOG), the hook function receives messages and notifications before the dialog box procedure provided in COMDLG32.DLL receives them. In the case of WM_INITDIALOG, the hook function receives the message after the dialog box procedure. When the hook function finishes processing a message, it returns a value that indicates whether the dialog box procedure provided in COMDLG32.DLL should also process the message. If the dialog box procedure should process the message, the return value is FALSE; if the dialog box procedure should ignore the message, the return value is TRUE.

To process the message from the OK button after the dialog box procedure processes it, an application must post a message to itself when the OK message is received. When the application receives the message it has posted, the common dialog box procedure will have finished processing messages for the dialog box. This technique is particularly useful when working with the Find and Replace dialog boxes, because the Flags member of the FINDREPLACE structure does not reflect changes to the dialog box until after the messages have been processed by COMDLG32.DLL.

The following example shows a hook function for a custom Open dialog box.

UINT FAR PASCAL FileOpenHookProc(HWND hdlg, UINT msg, WPARAM wParam,

    LPARAM lParam)

{

    switch (msg) {

        case WM_INITDIALOG: /* Received <after> commdlg is processed. */

            return TRUE;

        case WM_COMMAND:

            /* Use IsDlgButtonChecked to set lCustData. */

            if (wParam == IDOK)

                /* Set the "backup file" flag. */

                fBackup = (DWORD) IsDlgButtonChecked(hdlg, ID_CUSTCHX);

            return FALSE; /* Allow standard processing. */

            break;

        default:

            return FALSE;

    } /* end switch */

    return FALSE;

}

This hook function tests a custom check box when the user chooses the OK button. If the check box is selected, the hook function sets a global variable to a nonzero value; otherwise it sets this variable to zero.

A hook function should never call the EndDialog function. Instead, if a hook function contains code that abnormally terminates a common dialog box, this code should pass the IDABORT value to the dialog box procedure by using the PostMessage function, as shown in the following example.

PostMessage(hDlg, WM_COMMAND, IDABORT, (LONG) FALSE);

When a hook function posts the IDABORT value, the common dialog box function returns the value contained in the low-order word of the lParam parameter. For example, if the hook function for GetOpenFileName called the PostMessage function with (LONG) 100 as the last parameter, GetOpenFileName would return 100.

A hook function must be exported in an application's module-definition (.DEF) file, as shown in the following example.

NAME         Generic       ; application's module name

DESCRIPTION  'Sample Microsoft Windows Application'

EXETYPE      WINDOWS       ; required for all Windows applications

STUB         'WINSTUB.EXE' ; Generates error message if the

                           ; application is run without Windows

CODE  PRELOAD MOVEABLE DISCARDABLE

DATA  PRELOAD MOVEABLE MULTIPLE

HEAPSIZE     1024

STACKSIZE    8192

EXPORTS

        MainWndProc   @1   ; name of window processing function

        About         @2   ; name of "About" processing function

        FileOpenHookProc @3; name of common dialog box callback

Customizing a Dialog Box Template

The dialog box template provided in COMDLG32.DLL for each common dialog box contains the data the dialog box procedure uses to display that common dialog box. Most applications that customize a common dialog box also need to create a custom dialog box template to use instead of the dialog box template in COMDLG32.DLL. (A custom dialog box template is not required for all custom dialog boxes. A template would not be necessary, for instance, if an application changed a dialog box in a relatively minor way and only in an unusual situation.)

A developer should create a custom dialog box template by modifying the appropriate dialog box template in COMDLG32.DLL. Following are the template filenames and the names of their corresponding common dialog boxes.

Template filename	Corresponding dialog box

COLOR.DLG	Color

FILEOPEN.DLG	Open (single selection)

FILEOPEN.DLG	Open (multiple selection)

FINDTEXT.DLG	Find

FINDTEXT.DLG	Replace

FONT.DLG	Font

PRNSETUP.DLG	Print

PRNSETUP.DLG	Print Setup

The following example is from a custom dialog box template created for an Open dialog box.

FILEOPEN DIALOG LOADONCALL MOVEABLE DISCARDABLE

36, 24,  264, 134

CAPTION "Open"

STYLE WS_CAPTION | WS_SYSMENU | WS_POPUP | DS_MODALFRAME

FONT 8, "Helv"

BEGIN

    LTEXT "File &Name:", stc3,    6,    6,  76,  10

    CONTROL "", edt1, "edit", ES_LEFT | ES_AUTOHSCROLL | WS_BORDER |

            WS_TABSTOP | WS_CHILD | ES_OEMCONVERT | ES_LOWERCASE,

            6,    16,  90,  12

    CONTROL "", lst1, "listbox", LBS_SORT | LBS_NOTIFY | LBS_DISABLENOSCROLL |

              WS_VSCROLL | WS_BORDER | WS_TABSTOP | LBS_EXTENDEDSEL

            | LBS_HASSTRINGS | LBS_OWNERDRAWFIXED,

            6,   32,  90,  68

    LTEXT "&Directories:", -1, 110,   6,  92,   9

    LTEXT "", stc1,            110,  16,  92,   9, SS_NOPREFIX

    CONTROL "", lst2, "listbox",

            LBS_SORT | LBS_HASSTRINGS | LBS_NOTIFY | LBS_DISABLENOSCROLL

            | WS_VSCROLL | WS_CHILD | WS_BORDER | WS_TABSTOP

            | LBS_OWNERDRAWFIXED,

            110,  32,  92,  68

    LTEXT "List Files of &Type:", stc2, 6,  102,  90,   9

    CONTROL "", cmb1, "combobox", CBS_DROPDOWNLIST | CBS_AUTOHSCROLL |

            WS_BORDER | WS_VSCROLL | WS_TABSTOP | WS_CHILD,

            6,  112,  90,  36

    LTEXT "Dri&ves:", stc4,      110, 102,  92,  9

    CONTROL "", cmb2, "combobox",

            CBS_SORT | CBS_HASSTRINGS | CBS_OWNERDRAWFIXED | CBS_DROPDOWNLIST

            | WS_CHILD | CBS_AUTOHSCROLL | WS_BORDER | WS_VSCROLL

            | WS_TABSTOP,

            110, 112,  92, 68

    DEFPUSHBUTTON "OK", IDOK,      208,   6,  50,  14, WS_GROUP

    PUSHBUTTON "Cancel", IDCANCEL, 208,  24,  50,  14, WS_GROUP

    PUSHBUTTON "&Help", pshHelp,   208,  46,  50,  14, WS_GROUP

    PUSHBUTTON "Net&work...", psh14,   208,  114,  50,  14, WS_GROUP

    AUTOCHECKBOX "&Read Only", chx1,   208,  68,  50,  12,

                        WS_TABSTOP | WS_GROUP

    AUTOCHECKBOX "&Backup File", ID_CUSTCHX, 208, 86, 50, 12,

                        BS_AUTOCHECKBOX | WS_CHILD | WS_TABSTOP | WS_GROUP

END

The last entry supports the addition of a new Backup File check box immediately below the existing Read Only check box.

The custom template should be added to the application's resource file. You must use all of the unique control identifiers (that is, all identifiers whose values are other than -1) in the template, even if the dialog box does not use those controls. If you do not want to display all of the controls, you can specify coordinates for them outside the dialog box. You should also disable the unwanted buttons and remove unnecessary tab stops.


Displaying the Custom Dialog Box

After your application creates the hook function and the dialog box template, it should set the members of the structure for the common dialog box being customized and call the appropriate function to display the custom dialog box.

The following example calls the GetOpenFileName function and creates a backup file if the user selected the Backup File check box in the custom Open dialog box.

/* Process the requested file. */

if (GetOpenFileName(&ofn)) {

    /*

     * If the user checked the Backup File Check box,

     * create a backup file.

     */

    if (fBackup) {

    /* Open the requested file. */

    hf = CreateFile(ofn.lpstrFile, GENERIC_READ,

             0, (LPSECURITY_ATTRIBUTES) NULL,

             OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL,

             (HANDLE) NULL);

        /* Process the extension (if it exists). */

        if (ofn.nFileExtension) {

            for(i = 0; i < (int)ofn.nFileExtension;

                i++)

                szChar[i] = *ofn.lpstrFile++;

            } /* end if */

        else {

            i = 0;

            while (*ofn.lpstrFile != '\0')

                szChar[i++] = *ofn.lpstrFile++;

            szChar[i] = '.';

            } /* end else */

        /* Create the backup filename string. */

        pszBackupFile = lstrcat(szChar, "BAK");

        /* Create the backup file. */

        hfBackup = CreateFile(pszBackupFile, GENERIC_WRITE,

                       0, (LPSECURITY_ATTRIBUTES) NULL,

                       CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL,

                       (HANDLE) NULL);

        /*

         * Copy the contents of the original file

         * to the new file.

         */

        ReadFile(hf, szBuffer, 256, &cBufLen,

            NULL);

        while (cBufLen == 256) {

            WriteFile(hfBackup, szBuffer, 256, &cBufLen,

               NULL);

            ReadFile(hf, szBuffer, 256, &cBufLen,

               NULL);

            }

        WriteFile(hfBackup, szBuffer, cBufLen, &cTmp,

            NULL);

        /* Close the files. */

        CloseHandle(hfBackup);

        CloseHandle(hf);

     } /* end if */

 } /* end if */


Supporting and Processing Help for the Common Dialog Boxes

An application can display a Help button in any of the common dialog boxes by setting the appropriate flag in the Flags member of the structure for a specific common dialog box. Following are the structures for the common dialog boxes and the Help flag that corresponds to each structure.

Structure	Flag value

OPENFILENAME	OFN_SHOWHELP

CHOOSECOLOR	CC_SHOWHELP

FINDREPLACE	FR_SHOWHELP

CHOOSEFONT	CF_SHOWHELP

PRINTDLG	PD_SHOWHELP

If an application displays the Help button, it must process the user's request for help. This can be done either in one of the application's window procedures or in a hook function.

If the application processes the request for help in one of the application's window procedures, it must first create a new message identifier for the string defined by the HELPMSGSTRING constant. The application creates the new message identifier by calling the RegisterWindowMessage function and passing this constant as the single parameter. (For more information about processing registered window messages, see Displaying the Find Dialog Box.) In addition to creating a new message identifier, the application must set the hwndOwner member of the appropriate structure for the common dialog box so this member contains the handle of the dialog box's owner window. After the message identifier is created and the hwndOwner member is set, the dialog box procedure notifies the window procedure of the owner window whenever the user chooses the Help button.

The following example processes a user's request for help in the window procedure of its owner window. The if statement should be in the default: section of the switch statement that processes messages.

  MyHelpMsg = RegisterWindowMessage(HELPMSGSTRING);

            .

            .

            .

  if (message == MyHelpMsg)

     WinHelp(hWnd, "appfile.hlp", HELP_CONTEXT, ID_MY_CONTEXT);

If the application processes the request for help in a hook function, it should test for the following condition in the WM_COMMAND message.

wParam == pshHelp

When this condition is true, the hook function should call the WinHelp function, as shown in the preceding example. (To process Help in a hook function, you must include the header file DLGS.H in the source file that contains the hook-function code.)


Error Detection

Whenever a common dialog box function fails, an application can call the CommDlgExtendedError function to find out the cause of the failure. CommDlgExtendedError returns an error value that identifies the cause of the most recent error.

Six constants are defined in the CDERR.H header file that identify the ranges of error values for categories of errors returned by CommDlgExtendedError. Following are these constants in ascending order by value range.

Constant	Description

CDERR_GENERALCODES	General error codes for common dialog boxes. These errors are in the range 0x0000 through 0x0FFF.

PDERR_PRINTERCODES	Error codes for the Print common dialog box. These errors are in the range 0x1000 through 0x1FFF.

CFERR_CHOOSEFONTCODES	Error codes for the Font common dialog box. These errors are in the range 0x2000 through 0x2FFF.

FNERR_FILENAMECODES	Error codes for the Open and Save As common dialog boxes. These errors are in the range 0x3000 through 0x3FFF.

FRERR_FINDREPLACECODES	Error codes for the Find and Replace common dialog boxes. These errors are in the range 0x4000 through 0x4FFF.

CCERR_CHOOSECOLORCODES	Error codes for the Color common dialog box. These errors are in the range 0x5000 through 0x5FFF.


Dynamic Data Exchange Management Library Overview

The following topics discuss the concepts of DDE and describe how to use the DDE Management Library to add DDE functionality to an application:

Terms

About DDEML

Client and Server Interaction

Transactions and the DDE Callback Function

Service Names, Topic Names, and Item Names

System Topic

Initialization

Callback Function

String Management

Name Service

Service-Name Registration

Service-Name Filter

Conversation Management

Single Conversations

Multiple Conversations

Data Management

Transaction Management

Request Transaction

Poke Transaction

Advise Transaction

Execute Transaction

Synchronous and Asynchronous Transactions

Transaction Control

Transaction Classes

Transaction Summary

Error Detection

Monitoring Applications


Basic Concepts

About DDEML

In Microsoft® Windows™, dynamic data exchange (DDE) is 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 between applications sending updates to one another as new data becomes available.

DDE differs from the clipboard data-transfer mechanism that is also part of the Windows operating system. One difference is that the clipboard is almost always used as a one-time response to a specific action by the user--such as choosing the Paste command from a menu. Although DDE may also be initiated by a user, it typically continues without the user's further involvement.

The DDEML provides an application programming interface (API) that simplifies the task of adding DDE capability to a Windows application. Instead of sending, posting, and processing DDE messages directly, an application uses the functions provided by the DDEML to manage DDE conversations. A DDE conversation is the interaction between client and server applications. The DDEML also provides a facility for managing the strings and data shared among DDE applications. Instead of using atoms and pointers to shared memory objects, DDE applications create and exchange string handles, which identify strings, and data handles, which identify DDE objects. The DDEML provides a service that enables a server application to register the service names it supports. The service names are broadcast to other applications in the system, which use the names to connect to the server. The DDEML also ensures compatibility among DDE applications by requiring them to implement the DDE protocol in a consistent manner.

Existing applications using the message-based DDE protocol are fully compatible with those that use the DDEML. That is, an application using message-based DDE can establish conversations and perform transactions with applications using the DDEML. Instead of using DDE messages in your new application, take advantage of the DDEML and the many improvements it offers.

To use the API elements of the DDEML, you must include the DDEML.H header file in your source files, link with USER32.LIB, and ensure that DDEML.DLL resides in the system's path.


Client and Server Interaction

DDE always occurs between a client application and a server application. The DDE client application initiates the exchange by establishing a conversation with the server to send transactions to the server. A transaction is a request for data or services. The DDE server application responds to transactions by providing data or services to the client. A server can have many clients at the same time, and a client can request data from multiple servers. An application can also be both a client and a server. Either the client or the server can terminate the conversation at any time.

For example, a graphics application might contain a bar graph that represents a corporation's quarterly profits, and the data for the bar graph might be contained in a spreadsheet application. To obtain the latest profit figures, the graphics application (the client) establishes a conversation with the spreadsheet application (the server). The graphics application then sends a transaction to the spreadsheet application, requesting the latest profit figures.


Transactions and the DDE Callback Function

The DDEML notifies an application about DDE activity that affects the application by sending transactions to the application's DDE callback function. A DDE transaction is similar to a message--it is a named constant accompanied by other parameters that contain additional information about the transaction.

The DDEML passes a transaction to an application-defined DDE callback function that carries out an action appropriate to the type of transaction. For example, when a client application attempts to establish a conversation with a server application, the client calls the DdeConnect function. This causes the DDEML to send an XTYP_CONNECT transaction to the server's DDE callback function. The callback function can allow the conversation by returning TRUE to the DDEML, or it can deny the conversation by returning FALSE.

For a detailed discussion of transactions, see Transaction Management.


Service Names, Topic Names, and Item Names

A DDE server uses a three-level hierarchy--service name (called "application name" in previous DDE documentation), topic name, and item name--to uniquely identify a unit of data the server can exchange during a conversation.

A service name is a string a server application responds to when a client attempts to establish a conversation with the server. A client must specify this service name to establish a conversation with the server. Although a server can respond to many service names, most servers respond to only one name.

A topic name is a string that identifies a logical data context. For servers that operate on file-based documents, topic names are typically filenames; for other servers, they are other application-specific strings. A client must specify a topic name along with a server's service name when it attempts to establish a conversation with a server.

An item name is a string that identifies a unit of data a server can pass to a client during a transaction. For example, an item name might identify an integer, a string, several paragraphs of text, or a bitmap.

These names enable the client to establish a conversation with a server and to receive data from the server.


System Topic

The System topic provides a context for information of general interest to any DDE client. It is recommended that server applications support the System topic at all times. The System topic is defined in the DDEML header file as SZDDESYS_TOPIC.

To determine which servers are present and the kinds of information they can provide, a client application can, upon starting, request a conversation on the System topic, setting the device name to NULL. Such wildcard conversations are costly in terms of system performance; keep them to a minimum.

For more information about initiating DDE conversations, see Conversation Management.

A server must support the following item names within the System topic and any other item names useful to a client.

Item	Description

SZDDE_ITEM_ITEMLIST	A list of the items supported under a non-System topic. (This list may vary from moment to moment and from topic to topic.)

SZDDESYS_ITEM_FORMATS	A tab-delimited list of strings representing all clipboard formats potentially supported by the service application. Strings that represent predefined clipboard formats are equivalent to the CF_ constant names with the "CF_" prefix removed. For example, the CF_TEXT format is represented by the string "TEXT". These strings must be in uppercase letters to further identify them as predefined formats. The list of formats must appear in the order of most rich in content to least rich in content.

SZDDESYS_ITEM_HELP	User-readable information of general interest. It must contain, at a minimum, information on how to use the server application's DDE features. This may include, but is not limited to, how to specify items within topics, what execute strings the server can perform, what poke transactions are allowed, and pointers to help on other System topic items.

SZDDESYS_ITEM_RTNMSG	Supporting detail for the most recently used WM_DDE_ACK message. This is useful when more than 8 bits of application-specific return data are required.

SZDDESYS_ITEM_STATUS	An indication of the current status of the server. Typically, this item supports only the CF_TEXT format and contains the Ready or Busy string.

SZDDESYS_ITEM_SYSITEMS	A list of the items supported under the System topic by this server.

SZDDESYS_ITEM_TOPICS	A list of the topics supported by the server at the current time. (This list may vary from moment to moment.)

These item names are string constants defined in the DDEML header files. To obtain string handles for these strings, an application must use the DDEML string-management functions, just as it would for any other string in a DDEML application. For more information about managing strings, see String Management.


Initialization

Before calling any other DDEML function, an application must call the DdeInitialize function. DdeInitialize obtains an instance identifier for the application, registers the application's DDE callback function with the DDEML, and specifies the transaction-filter flags for the callback function.

Each instance of an application or a dynamic-link library (DLL) must pass its instance identifier as the idInst parameter to any other DDEML function that requires it. The purpose of multiple DDEML instances is to support DLLs that must use the DDEML at the same time an application is using it. An application must not use more than one instance of the DDEML.

Transaction filters optimize system performance by preventing the DDEML from passing unwanted transactions to the application's DDE callback function. An application sets the transaction filters when it calls DdeInitialize. An application must specify a transaction-filter flag for each type of transaction that it does not process in its callback function. An application can change its transaction filters with a subsequent call to DdeInitialize. For a complete list of transaction-filter flags, see the description of DdeInitialize in the Microsoft Win32 Programmer's Reference, Volume 3.

For more information about transactions, see Transaction Management.

The following example shows how to initialize an application to use the DDEML:

DWORD idInst = 0;

HINSTANCE hinst;

.

.

.

DdeInitialize(&idInst,         /* receives instance identifier */

    (PFNCALLBACK) DdeCallback, /* address of callback function */

    CBF_FAIL_EXECUTES |        /* filter XTYPE_EXECUTE         */

    CBF_SKIP_ALLNOTIFICATIONS, /* filter notifications         */

    0);

.

.

.

An application must call the DdeUninitialize function when it must no longer use the DDEML. This function terminates any conversations currently open for the application and frees the DDEML resources the system allocated for the application.


Callback Function

An application that uses the DDEML must provide a callback function that processes the DDE events affecting the application. The DDEML notifies an application of such events by sending transactions to the application's DDE callback function. The transactions a callback function receives depend on the callback-filter flags the application specified in DdeInitialize and whether the application is a client, a server, or both. The following example shows the general structure of a callback function for a typical client application.

HDDEDATA CALLBACK DdeCallback(uType, uFmt, hconv, hsz1,

    hsz2, hdata, dwData1, dwData2)

UINT uType;       /* transaction type                 */

UINT uFmt;        /* clipboard data format            */

HCONV hconv;      /* handle of conversation           */

HSZ hsz1;         /* handle of string                 */

HSZ hsz2;         /* handle of string                 */

HDDEDATA hdata;   /* handle of global memory object   */

DWORD dwData1;    /* transaction-specific data        */

DWORD dwData2;    /* transaction-specific data        */

{

    switch (uType) {

        case XTYP_REGISTER:

        case XTYP_UNREGISTER:

            .

            .

            .

            return (HDDEDATA) NULL;

        case XTYP_ADVDATA:

            .

            .

            .

            return (HDDEDATA) DDE_FACK;

        case XTYP_XACT_COMPLETE:

            .

            .

            .

            return (HDDEDATA) NULL;

        case XTYP_DISCONNECT:

            .

            .

            .

            return (HDDEDATA) NULL;

        default:

            return (HDDEDATA) NULL;

    }

}

The uType parameter specifies the transaction type sent to the callback function by the DDEML. The values of the remaining parameters depend on the transaction type. The transaction types and the events that generate them are described in the following sections of this topic. For detailed information about each transaction type, see Transaction Management.


String Management

To carry out a DDE task, many DDEML functions require access to strings. For example, a client must specify a service name and a topic name when it calls the DdeConnect function to request a conversation with a server. An application specifies a string by passing a string handle rather than a pointer in a DDEML function. A string handle is a doubleword value, assigned by the system, that identifies a string.

An application can obtain a string handle for a particular string by calling the DdeCreateStringHandle function. This function registers the string with the system and returns a string handle to the application. The application can pass the handle to DDEML functions that must access the string. The following example obtains string handles for the System topic string and the service-name string.

HSZ hszServName;

HSZ hszSysTopic;

.

.

.

hszServName = DdeCreateStringHandle(

    idInst,         /* instance identifier    */

    "MyServer",     /* string to register     */

    CP_WINANSI);    /* Windows ANSI code page */

hszSysTopic = DdeCreateStringHandle(

    idInst,         /* instance identifier    */

    SZDDESYS_TOPIC, /* System topic           */

    CP_WINANSI);    /* Windows ANSI code page */

.

.

.

The idInst parameter in the preceding example specifies the instance identifier obtained by the DdeInitialize function.

An application's DDE callback function receives one or more string handles during most DDE transactions. For example, a server receives two string handles during the XTYP_REQUEST transaction: One identifies a string specifying a topic name; the other identifies a string specifying an item name. An application can obtain the length of the string that corresponds to a string handle and copy the string to an application-defined buffer by calling the DdeQueryString function, as the following example demonstrates.

DWORD idInst;

DWORD cb;

HSZ hszServ;

PSTR pszServName;

.

.

.

cb = DdeQueryString(idInst, hszServ, (LPSTR) NULL, 0,

    CP_WINANSI) + 1;

pszServName = (PSTR) LocalAlloc(LPTR, (WORD) cb);

DdeQueryString(idInst, hszServ, pszServName, cb, CP_WINANSI);

.

.

.

An instance-specific string handle cannot be mapped from string handle to string and back to string handle. For instance, in the following example, DdeQueryString creates a string from a string handle and then 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 ! */

.

.

.

A string handle passed to an application's DDE callback function becomes invalid when the callback function returns. An application can save a string handle for use after the callback function returns by using the DdeKeepStringHandle function.

When an application calls DdeCreateStringHandle, the system enters the specified string into a string table and generates a handle that it uses to access the string. The system also maintains a usage count for each string in the string table.

When an application calls DdeCreateStringHandle and specifies a string that already exists in the table, the system increments the usage count rather than adding another occurrence of the string. (An application can also increment the usage count by using DdeKeepStringHandle.) When an application calls the DdeFreeStringHandle function, the system decrements the usage count.

A string is removed from the table when its usage count equals zero. Because more than one application can obtain the handle of a particular string, an application must not free a string handle more times than it has created or retained the handle. Otherwise, the application could cause the string to be removed from the table, denying other applications access to the string.

The DDEML string-management functions are based on the Windows atom manager and are subject to the same size restrictions as are atoms.


Name Service

The DDEML makes it possible for a server application to register the service names that it supports and to prevent the DDEML from sending XTYP_CONNECT transactions for unsupported service names to the server's DDE callback function. The remaining topics in this section describe this service.


Service-Name Registration

By registering its service names with the DDEML, a server informs other DDE applications in the system that a new server is available. A server registers a service name by calling the DdeNameService function and specifying a string handle that identifies the name. In response, the DDEML sends an XTYP_REGISTER transaction to the callback function of each DDEML application in the system (except those that specified the CBF_SKIP_REGISTRATIONS filter flag in the DdeInitialize function). The XTYP_REGISTER transaction passes two string handles to a callback function: The first identifies the string specifying the base service name; the second identifies the string specifying the instance-specific service. A client typically uses the base service name in a list of available servers, so the user can select a server from the list. The client uses the instance-specific service name to establish a conversation with a specific instance of a server application, if more than one instance is running.

A server can use DdeNameService to unregister a service name. This causes the DDEML to send XTYP_UNREGISTER transactions to the other DDE applications in the system, informing them that they can no longer use the name to establish conversations.

A server must call DdeNameService to register its service names soon after calling DdeInitialize. A server must unregister its service names just before calling the DdeUninitialize function.


Service-Name Filter

DdeNameService, in addition to registering service names, enables a server to turn its service-name filter on or off. When a server turns off its service-name filter, the DDEML sends the XTYP_CONNECT transaction to the server's DDE callback function whenever any client calls the DdeConnect function, regardless of the service name specified in the function. When a server turns on its service-name filter, the DDEML sends the XTYP_CONNECT transaction to the server only when DdeConnect specifies a service name the server has specified in a call to DdeNameService.

By default, the service-name filter is on when an application calls DdeInitialize. This prevents the DDEML from sending the XTYP_CONNECT transaction to a server before the server has created the string handles it needs. A server can turn off its service-name filter by specifying the DNS_FILTEROFF flag in a call to DdeNameService. The DNS_FILTERON flag turns on the filter.


Conversation Management

A conversation between a client and a server is always established at the request of the client. When a conversation is established, each partner receives a handle that identifies the conversation. The partners use this handle in other DDEML functions to send transactions and manage the conversation. A client can request a conversation with a single server, or it can request multiple conversations with one or more servers.

The remaining topics in this section describe how an application establishes new conversations and gets information about existing conversations.


Single Conversations

A client application requests a single conversation with a server by calling the DdeConnect function and specifying string handles that identify the strings containing the service name of the server and the topic name of interest. The DDEML responds by sending the XTYP_CONNECT transaction to the DDE callback function of each server application that either has registered a service name that matches the one specified in DdeConnect or has turned service-name filtering off by calling DdeNameService. A server can also filter the XTYP_CONNECT transactions by specifying the CBF_FAIL_CONNECTIONS filter flag in the DdeInitialize function. During the XTYP_CONNECT transaction, the DDEML passes the service name and the topic name to the server. The server must examine the names and return TRUE if it supports the service name and topic name pair or FALSE if it does not.

If no server responds positively to the client's request to connect, the client receives NULL from DdeConnect and no conversation is established. If a server does return TRUE, a conversation is established and the client receives a conversation handle--a doubleword value that identifies the conversation. The client uses the handle in subsequent DDEML calls to obtain data from the server. The server receives the XTYP_CONNECT_CONFIRM transaction (unless the server specified the CBF_FAIL_CONFIRMS filter flag). This transaction passes the conversation handle to the server.

The following example requests a conversation on the System topic with a server that recognizes the service name MyServer. The hszServName and hszSysTopic parameters are previously created string handles.

HCONV hConv;

HWND hwndParent;

HSZ hszServName;

HSZ hszSysTopic;

.

.

.

hConv = DdeConnect(

    idInst,               /* instance identifier        */

    hszServName,          /* service-name string handle */

    hszSysTopic,          /* System-topic string handle */

    (PCONVCONTEXT) NULL); /* use default context        */

if (hConv == NULL) {

    MessageBox(hwndParent, "MyServer is unavailable.",

        (LPSTR) NULL, MB_OK);

    return FALSE;

}

.

.

.

In the preceding example, DdeConnect causes the DDE callback function of the MyServer application to receive an XTYP_CONNECT transaction.

In the following example, the server responds to the XTYP_CONNECT transaction by comparing the topic-name string handle the DDEML passed to the server with each element in the array of topic-name string handles the server supports. If the server finds a match, it establishes the conversation.

#define CTOPICS 5

HSZ hsz1;                  /* string handle passed by DDEML  */

HSZ ahszTopics[CTOPICS];   /* array of supported topics      */

int i;                     /* loop counter                   */

.

. /* Use switch statement to examine transaction types. */

.

case XTYP_CONNECT:

    for (i = 0; i < CTOPICS; i++) {

        if (hsz1 == ahszTopics[i])

            return TRUE;   /* establish a conversation       */

    }

    return FALSE; /* topic not supported; deny conversation  */

.

. /* Process other transaction types. */

.

If the server returns TRUE in response to the XTYP_CONNECT transaction, the DDEML sends an XTYP_CONNECT_CONFIRM transaction to the server's DDE callback function. The server can obtain the handle for the conversation by processing this transaction.

A client can establish a wildcard conversation by specifying NULL for the service-name string handle, the topic-name string handle, or both in a call to DdeConnect. If at least one of the string handles is NULL, the DDEML sends the XTYP_WILDCONNECT transaction to the callback functions of all DDE applications (except those that filter the XTYP_WILDCONNECT transaction). Each server application should respond by returning a data handle that identifies a null-terminated array of HSZPAIR structures. If the server application has not called DdeNameService to register its service names, and if filtering is on, the server does not receive XTYP_WILDCONNECT transactions. For more information about data handles, see Data Management.

The array must contain one structure for each service name and topic name pair that matches the pair specified by the client. The DDEML selects one of the pairs to establish a conversation and returns to the client a handle that identifies the conversation. The DDEML sends the XTYP_CONNECT_CONFIRM transaction to the server (unless the server filters this transaction). The following example shows a typical server response to the XTYP_WILDCONNECT transaction.

#define CTOPICS 2

UINT uType;

HSZPAIR ahszp[(CTOPICS + 1)];

HSZ ahszTopicList[CTOPICS];

HSZ hszServ, hszTopic;

WORD i, j;

if (uType == XTYP_WILDCONNECT) {

     /*

      * Scan the topic list and create an array of HSZPAIR

      * structures.

      */

    j = 0;

    for (i = 0; i < CTOPICS; i++) {

        if (hszTopic == (HSZ) NULL ||

                hszTopic == ahszTopicList[i]) {

            ahszp[j].hszSvc = hszServ;

            ahszp[j++].hszTopic = ahszTopicList[i];

        }

    }

    /*

     * End the list with an HSZPAIR structure that contains NULL

     * string handles as its members.

     */

    ahszp[j].hszSvc = NULL;

    ahszp[j++].hszTopic = NULL;

    /*

     * Return a handle to a global memory object containing the

     * HSZPAIR structures.

     */

    return DdeCreateDataHandle(

        idInst,          /* instance identifier     */

        (LPBYTE) &ahszp, /* points to HSZPAIR array */

        sizeof(HSZ) * j, /* length of the array     */

        0,               /* start at the beginning  */

        (HSZ) NULL,      /* no item-name string     */

        0,               /* return the same format  */

        0);              /* let the system own it   */

}

Either the client or the server can terminate a conversation at any time by calling the DdeDisconnect function. This causes the callback function of the partner in the conversation to receive the XTYP_DISCONNECT transaction (unless the partner specified the CBF_SKIP_DISCONNECTS filter flag). Typically, an application responds to the XTYP_DISCONNECT transaction by using the DdeQueryConvInfo function to obtain information about the conversation that terminated. After the callback function returns from processing the XTYP_DISCONNECT transaction, the conversation handle is no longer valid.

A client application that receives an XTYP_DISCONNECT transaction in its DDE callback function can attempt to reestablish the conversation by calling the DdeReconnect function. The client must call DdeReconnect from within its DDE callback function.


Multiple Conversations

A client application can use the DdeConnectList function to determine whether any servers of interest are available in the system. A client specifies a service name and topic name when it calls DdeConnectList, causing the DDEML to broadcast the XTYP_WILDCONNECT transaction to the DDE callback functions of all servers that match the service name (except those that filter the transaction). A server's callback function should return a data handle that identifies a null-terminated array of HSZPAIR structures. The array should contain one structure for each service name and topic name pair that matches the pair specified by the client. The DDEML establishes a conversation for each HSZPAIR structure filled by the server and returns a conversation-list handle to the client. The server receives the conversation handle by way of the XTYP_CONNECT_CONFIRM transaction (unless the server filters this transaction).

A client can specify NULL for the service name, topic name, or both when it calls DdeConnectList. If the service name is NULL, all servers in the system that support the specified topic name respond. A conversation is established with each responding server, including multiple instances of the same server. If the topic name is NULL, a conversation is established on each topic recognized by each server that matches the service name.

A client can use the DdeQueryNextServer and DdeQueryConvInfo functions to identify the servers that respond to DdeConnectList. DdeQueryNextServer returns the next conversation handle in a conversation list; DdeQueryConvInfo fills a CONVINFO structure with information about the conversation. The client can keep the conversation handles that it needs and discard the rest from the conversation list.

The following example uses DdeConnectList to establish conversations with all servers that support the System topic and then uses the DdeQueryNextServer and DdeQueryConvInfo functions to obtain the servers' service-name string handles and store them in a buffer.

HCONVLIST hconvList; /* conversation list       */

DWORD idInst;        /* instance identifier     */

HSZ hszSystem;       /* System topic            */

HCONV hconv = NULL;  /* conversation handle     */

CONVINFO ci;         /* holds conversation data */

UINT cConv = 0;      /* count of conv. handles  */

HSZ *pHsz, *aHsz;    /* point to string handles */

/* Connect to all servers that support the System topic. */

hconvList = DdeConnectList(idInst, NULL, hszSystem, NULL, NULL);

/* Count the number of handles in the conversation list. */

while ((hconv = DdeQueryNextServer(hconvList, hconv)) != NULL)

    cConv++;

/* Allocate a buffer for the string handles. */

hconv = NULL;

aHsz = (HSZ *) LocalAlloc(LMEM_FIXED, cConv * sizeof(HSZ));

/* Copy the string handles to the buffer. */

pHsz = aHsz;

while ((hconv = DdeQueryNextServer(hconvList, hconv)) != NULL) {

    DdeQueryConvInfo(hconv, QID_SYNC, (PCONVINFO) &ci);

    DdeKeepStringHandle(idInst, ci.hszSvcPartner);

    *pHsz++ = ci.hszSvcPartner;

}

.

. /* Use the handles; converse with the servers. */

.

/* Free the memory and terminate the conversations. */

LocalFree((HANDLE) aHsz);

DdeDisconnectList(hconvList);

An application can terminate an individual conversation in a conversation list by calling the DdeDisconnect function. An application can terminate all conversations in a conversation list by calling the DdeDisconnectList function. Both functions cause the DDEML to send XTYP_DISCONNECT transactions to each partner's DDE callback function. DdeDisconnectList sends an XTYP_DISCONNECT transaction for each conversation handle in the list.

A client can use DdeConnectList to retrieve a list of the conversation handles in a conversation list by passing an existing conversation-list handle to DdeConnectList. The enumeration process removes the handles of terminated conversations from the list, and nonduplicate conversations that fit the specified service name and topic name are added.

If DdeConnectList specifies an existing conversation-list handle, the function creates a new conversation list that contains the handles of any new conversations and the handles from the existing list.

If duplicate conversations exist, DdeConnectList attempts to prevent duplicate conversation handles in a conversation list. A duplicate conversation is a second conversation with the same server on the same service name and topic name. Two such conversations would have different handles, yet they would identify the same conversation.


Data Management

Because DDE uses memory objects to pass data from one application to another, the DDEML provides a set of functions that DDE applications can use to create and manage DDE objects.

All transactions that involve the exchange of data require the application supplying the data to create a local buffer containing the data and then to call the DdeCreateDataHandle function. This function allocates a DDE object, copies the data from the buffer to the object, and returns a data handle of the application. A data handle is a doubleword value that the DDEML uses to provide access to data in the DDE object. To share the data in a DDE object, an application passes the data handle to the DDEML, and the DDEML passes the handle to the DDE callback function of the application that is receiving the data transaction.

The following example shows how to create a DDE object and obtain a handle of the object. During the XTYP_ADVREQ transaction, the callback function converts the current time to an ASCII string, copies the string to a local buffer, and then creates a DDE object that contains the string. The callback function returns the handle of the DDE object to the DDEML, which passes the handle to the client application.

typedef struct tagTIME

  {

    INT     hour;   /* 0 - 11 hours for analog clock */

    INT     hour12; /* 12-hour format */

    INT     hour24; /* 24-hour format */

    INT     minute;

    INT     second;

    INT     ampm;   /* 0 - AM , 1 - PM */

  } TIME;

HDDEDATA EXPENTRY DdeCallback(uType, uFmt, hconv, hsz1, hsz2,

    hdata, dwData1, dwData2)

UINT uType;

UINT uFmt;

HCONV hconv;

HSZ hsz1;

HSZ hsz2;

HDDEDATA hdata;

DWORD dwData1;

DWORD dwData2;

{

    CHAR szBuf[32];

    switch (uType) {

    case XTYP_ADVREQ:

    case XTYP_REQUEST:

        if ((hsz1 == hszTime && hsz2 == hszNow) &&

                (uFmt == CF_TEXT)) {

            /* Copy the formatted string to a buffer. */

            itoa(tmTime.hour, szBuf, 10);

            lstrcat(szBuf, ":");

            if (tmTime.minute < 10)

                lstrcat(szBuf, "0");

            itoa(tmTime.minute, &szBuf[lstrlen(szBuf)], 10);

            lstrcat(szBuf, ":");

            if (tmTime.second < 10)

                strcat(szBuf, "0");

            itoa(tmTime.second, &szBuf[lstrlen(szBuf)], 10);

            szBuf[lstrlen(szBuf)] = '\0';

            /* Create a global object and return its data handle. */

            return (DdeCreateDataHandle(

                idInst,

                (LPBYTE) szBuf,     /* instance identifier   */

                lstrlen(szBuf) + 1, /* source buffer         */

                0,                  /* offset from beginning */

                hszNow,             /* item-name string      */

                CF_TEXT,            /* clipboard format      */

                0));                /* no creation flags     */

        } else

            return (HDDEDATA) NULL;

    .

    . /* Process other transactions. */

    .

    }

}

The receiving application obtains a pointer to the DDE object by passing the data handle to the DdeAccessData function. The pointer returned by DdeAccessData provides read-only access. The application should use the pointer to review the data and then call the DdeUnaccessData function to invalidate the pointer. The application can copy the data to a local buffer by using the DdeGetData function.

The following example obtains a pointer to the DDE object identified by the hData parameter, copies the contents to a local buffer, and then invalidates the pointer.

HDDEDATA hdata;

LPBYTE lpszAdviseData;

DWORD cbDataLen;

DWORD i;

char szData[32];

.

.

.

case XTYP_ADVDATA:

    lpszAdviseData = DdeAccessData(hdata, &cbDataLen);

    for (i = 0; i < cbDataLen; i++)

        szData[i] = *lpszAdviseData++;

    DdeUnaccessData(hdata);

    return (HDDEDATA) TRUE;

.

.

.

Usually, when an application that created a data handle passes that handle to the DDEML, the handle becomes invalid in the creating application. This is fine if the application must share data with only a single application. If an application must share the same data with multiple applications, however, the creating application should specify the HDATA_APPOWNED flag in DdeCreateDataHandle. Doing so gives ownership of the DDE object to the creating application and prevents the DDEML from invalidating the data handle. The application can pass the data handle any number of times, but must call DdeCreateDataHandle only once.

If an application specifies the HDATA_APPOWNED flag in the afCmd parameter of DdeCreateDataHandle, it must call the DdeFreeDataHandle function to free the memory handle, regardless of whether it passed the handle to the DDEML. Before it terminates, an application must call DdeFreeDataHandle to free any data handle that it created but did not pass to the DDEML.

If an application has not yet passed the handle of a DDE object to the DDEML, the application can add data to the object or overwrite data in the object by using the DdeAddData function. Typically, an application uses DdeAddData to fill an uninitialized DDE object. After an application passes a data handle to the DDEML, the DDE object identified by the handle cannot be changed; it can only be freed.


Transaction Management

After establishing a conversation with a server, a client can send transactions to obtain data and services from the server. The remaining topics in this section describe the types of transactions that clients can use to interact with a server.


Request Transaction

A client application can use the XTYP_REQUEST transaction to request a data item from a server application. The client calls the DdeClientTransaction function, specifying XTYP_REQUEST as the transaction type and specifying the data item the application needs.

The DDEML passes the XTYP_REQUEST transaction to the server, specifying the topic name, item name, and data format requested by the client. If the server supports the requested topic, item, and format, the server should return a data handle that identifies the current value of the item. The DDEML passes this handle to the client as the return value from DdeClientTransaction. The server should return NULL if it does not support the topic, item, or format requested.

DdeClientTransaction uses the lpdwResult parameter to return a transaction-status flag to the client. If the server does not process the XTYP_REQUEST transaction, DdeClientTransaction returns NULL, and lpdwResult points to the DDE_FNOTPROCESSED or DDE_FBUSY flag. If the DDE_FNOTPROCESSED flag is returned, the client cannot determine why the server did not process the transaction.

If a server does not support the XTYP_REQUEST transaction, it should specify the CBF_FAIL_REQUESTS filter flag in the DdeInitialize function. This prevents the DDEML from sending this transaction to the server.


Poke Transaction

A client can send unsolicited data to a server by using DdeClientTransaction to send an XTYP_POKE transaction to a server's callback function.

The client application first creates a buffer that contains the data to send to the server and then passes a pointer to the buffer as a parameter to DdeClientTransaction. Alternatively, the client can use the DdeCreateDataHandle function to obtain a data handle that identifies the data and then pass the handle to DdeClientTransaction. In either case, the client also specifies the topic name, item name, and data format when it calls DdeClientTransaction.

The DDEML passes the XTYP_POKE transaction to the server, specifying the topic name, item name, and data format that the client requested. To accept the data item and format, the server should return DDE_FACK. To reject the data, the server should return DDE_FNOTPROCESSED. If the server is too busy to accept the data, the server should return DDE_FBUSY.

When DdeClientTransaction returns, the client can use the lpdwResult parameter to access the transaction-status flag. If the flag is DDE_FBUSY, the client should send the transaction again later.

If a server does not support the XTYP_POKE transaction, it should specify the CBF_FAIL_POKES filter flag in DdeInitialize. This prevents the DDEML from sending this transaction to the server.


Advise Transaction

A client application can use the DDEML to establish one or more links to items in a server application. When such a link has been established, the server sends periodic updates about the linked item to the client (typically, whenever the value of the item associated with the server application changes). This establishes an advise loop between the two applications that remains in place until the client ends it.

There are two kinds of advise loops: "hot" and "warm." In a hot advise loop, the server immediately sends a data handle that identifies the changed value. In a warm advise loop, the server notifies the client that the value of the item has changed but does not send the data handle until the client requests it.

A client can request a hot advise loop with a server by specifying the XTYP_ADVSTART transaction type in a call to DdeClientTransaction. To request a warm advise loop, the client must combine the XTYPF_NODATA flag with the XTYP_ADVSTART transaction type. In either event, the DDEML passes the XTYP_ADVSTART transaction to the server's DDE callback function. The server's DDE callback function should examine the parameters that accompany the XTYP_ADVSTART transaction (including the requested format, topic name, and item name) and then return TRUE to allow the advise loop or FALSE to deny it.

After an advise loop has been established, the server application should call the DdePostAdvise function whenever the value of the item associated with the requested item name changes. This results in an XTYP_ADVREQ transaction being sent to the server's own DDE callback function. The server's DDE callback function should return a data handle that identifies the new value of the data item. The DDEML then notifies the client that the specified item has changed by sending the XTYP_ADVDATA transaction to the client's DDE callback function.

If the client requested a hot advise loop, the DDEML passes the data handle for the changed item to the client during the XTYP_ADVDATA transaction. Otherwise, the client can send an XTYP_REQUEST transaction to obtain the data handle.

It is possible for a server to send updates faster than a client can process the new data. This can be a problem for a client that must perform lengthy processing operations on the data. In this case, the client should specify the XTYPF_ACKREQ flag when it requests an advise loop. This causes the server to wait for the client to acknowledge that it has received and processed a data item before the server sends the next data item. Advise loops that are established with the XTYPF_ACKREQ flag are more robust with fast servers but may occasionally miss updates. Advise loops established without the XTYPF_ACKREQ flag are guaranteed not to miss updates as long as the client keeps up with the server.

A client can end an advise loop by specifying the XTYP_ADVSTOP transaction type in a call to DdeClientTransaction.

If a server does not support advise loops, it should specify the CBF_FAIL_ADVISES filter flag in the DdeInitialize function. This prevents the DDEML from sending the XTYP_ADVSTART and XTYP_ADVSTOP transactions to the server.


Execute Transaction

A client can use the XTYP_EXECUTE transaction to cause a server to execute a command or a series of commands.

To execute a server command, the client first creates a buffer that contains a command string for the server to execute and then passes either a pointer to the buffer or a data handle identifying the buffer when it calls DdeClientTransaction. Other required parameters include the conversation handle, the item-name string handle, the format specification, and the XTYP_EXECUTE transaction type. When an application creates a data handle for passing execute data, the application must specify NULL for the hszItem parameter of the DdeCreateDataHandle function and zero for the uFmt parameter.

The DDEML passes the XTYP_EXECUTE transaction to the server's DDE callback function and specifies the format name, conversation handle, topic name, and data handle identifying the command string. If the server supports the command, it should use the DdeAccessData function to obtain a pointer to the command string, execute the command, and then return DDE_FACK. If the server does not support the command or cannot complete the transaction, it should return DDE_FNOTPROCESSED. The server should return DDE_FBUSY if it is too busy to complete the transaction.

In general, a server's callback function should process the XTYP_EXECUTE transaction before returning. Exceptions to this include the following:

1	When the command passed with the XTYP_EXECUTE transaction requests the server to terminate, the server's should not terminate until its callback function returns from processing XTYP_EXECUTE.

2	If the server must perform an operation such as processing a dialog box or a DDE transaction that might cause DDEML recursion problems, the server should return CBR_BLOCK to block the execute transaction, perform the operation, and then resume processing the execute transaction.

When DdeClientTransaction returns, the client can use the lpdwResult parameter to access the transaction-status flag. If the flag is DDE_FBUSY, the client should send the transaction again later.

If a server does not support the XTYP_EXECUTE transaction, it should specify the CBF_FAIL_EXECUTES filter flag in the DdeInitialize function. Doing so prevents the DDEML from sending this transaction to the server.


Synchronous and Asynchronous Transactions

A client can send either synchronous or asynchronous transactions. In a synchronous transaction, the client specifies a time-out value that indicates the maximum amount of time it will wait for the server to process the transaction. DdeClientTransaction does not return until the server processes the transaction, the transaction fails, or the time-out value expires. The client specifies the time-out value when it calls DdeClientTransaction.

During a synchronous transaction, the client enters a modal loop while waiting for the transaction to be processed. The client can still process user input but cannot send another synchronous transaction until DdeClientTransaction returns.

A client sends an asynchronous transaction by specifying the TIMEOUT_ASYNC flag in DdeClientTransaction. The function returns after the transaction has begun, passing a transaction identifier to the client. When the server finishes processing the asynchronous transaction, the DDEML sends an XTYP_XACT_COMPLETE transaction to the client. One of the parameters that the DDEML passes to the client during the XTYP_XACT_COMPLETE transaction is the transaction identifier. By comparing this transaction identifier with the identifier returned by DdeClientTransaction, the client identifies which asynchronous transaction the server has finished processing.

A client can use the DdeSetUserHandle function as an aid in processing an asynchronous transaction. This function makes it possible for a client to associate an application-defined doubleword value with a conversation handle and a transaction identifier. The client can use the DdeQueryConvInfo function during the XTYP_XACT_COMPLETE transaction to obtain the application-defined doubleword value. Because of this, an application need not maintain a list of active transaction identifiers.

When a client successfully completes a request for data using a synchronous transaction, the DDEML has no way to tell when the client has finished using the data received. The client application must pass the data handle received to the DdeFreeDataHandle function, notifying the DDEML that the handle will no longer be used. Data handles returned by synchronous transactions are effectively owned by the client.

If a server does not process an asynchronous transaction in a timely manner, the client can abandon the transaction by calling the DdeAbandonTransaction function. The DDEML releases all resources associated with the transaction and discards the results of the transaction when the server finishes processing it. A time-out during a synchronous transaction effectively cancels the transaction.

The asynchronous transaction method is provided for applications that must send a high volume of DDE transactions while simultaneously performing a substantial amount of processing, such as performing calculations. The asynchronous method is also useful in applications that must stop processing DDE transactions temporarily so they can complete other tasks without interruption. In most other situations, an application should use the synchronous method.

Synchronous transactions are simpler to maintain and are faster than asynchronous transactions. However, only one synchronous transaction can be performed at a time, whereas many asynchronous transactions can be performed simultaneously. With synchronous transactions, a slow server can cause a client to remain idle while it is waiting for a response. Also, synchronous transactions cause the client to enter a modal loop that could bypass message filtering in the application's own message loop.

Message filtering is not bypassed if the client has set a MSGF_DDEMGR message filter. The main danger of the synchronous transaction modal loop is that a modal loop created by a dialog box can interfere with its operation. Asynchronous transactions should always be used when the DDEML is being used by a dynamic-link library (DLL).


Transaction Control

An application can suspend transactions to its DDE callback function--either those transactions associated with a specific conversation handle or all transactions regardless of the conversation handle. This is useful when an application receives a transaction that requires lengthy processing. In such a case, the application could return CBR_BLOCK to suspend future transactions associated with the transaction's conversation handle, leaving the application free to process other conversations.

When processing has been completed, the application calls the DdeEnableCallback function to resume transactions associated with the suspended conversation. Calling DdeEnableCallback causes the DDEML to resend the transaction that resulted in the application suspending the conversation. Therefore, the application should store the result of the transaction in such a way that it can obtain and return the result without reprocessing the transaction.

An application can suspend all transactions associated with a specific conversation handle by specifying the handle and the EC_DISABLE flag in a call to DdeEnableCallback. By specifying a NULL handle, an application can suspend all transactions for all conversations.

When a conversation has been suspended, the DDEML saves transactions for the conversation in a transaction queue. When the application reenables the conversation, the DDEML removes the saved transactions from the queue and passes each transaction to the appropriate callback function. The capacity of the transaction queue is large, but an application should reenable a suspended conversation as soon as possible to avoid losing transactions.

An application can resume usual transaction processing by specifying the EC_ENABLEALL flag in DdeEnableCallback. For a more controlled resumption of transaction processing, the application can specify the EC_ENABLEONE flag. This removes one transaction from the transaction queue and passes it to the appropriate callback function; after that transaction has been processed, any conversations are again disabled.

If the EC_ENABLEONE flag and a conversation handle are specified in the call to DdeEnableCallback, only that conversation is blocked after the transaction has been processed. If a NULL conversation handle is specified, all conversations are blocked after a transaction has been processed in any conversation.


Transaction Classes

The DDEML has four classes of transactions. Each class is identified by a constant that begins with the XCLASS_ prefix. The classes are defined in the DDEML header file. The class constant is combined with the transaction-type constant and is passed to the DDE callback function of the receiving application.

A transaction's class determines the return value that a callback function is expected to return if it processes the transaction. The following table shows the return values and transaction types associated with each of the four transaction classes.

Class	Return value	Transaction
XCLASS_BOOL	TRUE or FALSE	XTYP_ADVSTART XTYP_CONNECT
XCLASS_DATA	A data handle, CBR_BLOCK, or NULL	XTYP_ADVREQ XTYP_REQUEST XTYP_WILDCONNECT
XCLASS_FLAGS	A transaction flag: DDE_FACK, DDE_FBUSY, or DDE_FNOTPROCESSED	XTYP_ADVDATA XTYP_EXECUTE XTYP_POKE
XCLASS_NOTIFICATION	None	XTYP_ADVSTOP XTYP_CONNECT_CONFIRM XTYP_DISCONNECT XTYP_ERROR XTYP_REGISTER XTYP_UNREGISTER XTYP_XACT_COMPLETE


Transaction Summary

The following table shows each DDE transaction type, the receiver of each type, and a description of the activity that causes the DDEML to generate each type.

Transaction type	Receiver	Cause
XTYP_ADVDATA	Client	A server responded to an XTYP_ADVREQ transaction by returning a data handle.
XTYP_ADVREQ	Server	A server called the DdePostAdvise function, indicating that the value of a data item in an advise loop had changed.
XTYP_ADVSTART	Server	A client specified the XTYP_ADVSTART transaction type in a call to the DdeClientTransaction function.
XTYP_ADVSTOP	Server	A client specified the XTYP_ADVSTOP transaction type in a call to DdeClientTransaction.
XTYP_CONNECT	Server	A client called the DdeConnect function and specified a service name and topic name supported by the server.
XTYP_CONNECT_CONFIRM	Server	The server returned TRUE in response to an XTYP_CONNECT or XTYP_WILDCONNECT transaction.
XTYP_DISCONNECT	Client/Server	A partner in a conversation called the DdeDisconnect function, causing both partners to receive this transaction.
XTYP_ERROR	Client/Server	A critical error has occurred. The DDEML may not have sufficient resources to continue.
XTYP_EXECUTE	Server	A client specified the XTYP_EXECUTE transaction type in a call to DdeClientTransaction.
XTYP_MONITOR	DDE monitoring application	A DDE event occurred in the system. For more information about DDE monitoring applications, see Monitoring Applications.
XTYP_POKE	Server	A client specified the XTYP_POKE transaction type in a call to DdeClientTransaction.
XTYP_REGISTER	Client/Server	A server application used the DdeNameService function to register a service name.
XTYP_REQUEST	Server	A client specified the XTYP_REQUEST transaction type in a call to DdeClientTransaction.
XTYP_UNREGISTER	Client/Server	A server application used DdeNameService to unregister a service name.
XTYP_WILDCONNECT	Server	A client called the DdeConnect or DdeConnectList function, specifying NULL for the service name, the topic name, or both.
XTYP_XACT_COMPLETE	Client	An asynchronous transaction, sent when the client specified the TIMEOUT_ASYNC flag in a call to DdeClientTransaction, has concluded.


Error Detection

Whenever a DDEML function fails, an application can call the DdeGetLastError function to determine the cause of the failure. DdeGetLastError returns an error value that specifies the cause of the most recent error.


Monitoring Applications

You can use the application programming interface (API) elements of the DDEML to create an application that monitors DDE activity in the system. Like any DDEML application, a DDE monitoring application contains a DDE callback function. The DDEML notifies a monitoring application's DDE callback function whenever a DDE event occurs, passing information about the event to the callback function. The application typically displays the information in a window or writes it to a file.

To receive notifications from the DDEML, an application must have registered as a DDE monitor by specifying the APPCLASS_MONITOR flag in a call to the DdeInitialize function. In this same call, the application can specify one or more monitor flags to indicate the types of events of which the DDEML is to notify the application's callback function. The following table describes each of the monitor flags an application can specify:

Flag	Meaning

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 DDEML error occurs.

MF_HSZ_INFO	Notifies the callback function whenever a DDEML 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.

The following example shows how to register a DDE monitoring application so that its DDE callback function receives notifications of all DDE events:

DWORD idInst;

PFNCALLBACK lpDdeProc;

hInst = hInstance;

lpDdeProc = (PFNCALLBACK) MakeProcInstance(

    (FARPROC) DDECallback,  /* points to callback function      */

    hInstance);             /* instance handle                  */

if (DdeInitialize(

        (LPDWORD) &idInst,  /* instance identifier              */

        lpDdeProc,          /* points to callback function      */

        APPCLASS_MONITOR |  /* this is a monitoring application */

        MF_CALLBACKS     |  /* monitor callback functions       */

        MF_CONV          |  /* monitor conversation data        */

        MF_ERRORS        |  /* monitor DDEML errors             */

        MF_HSZ_INFO      |  /* monitor data-handle activity     */

        MF_LINKS         |  /* monitor advise loops             */

        MF_POSTMSGS      |  /* monitor posted DDE messages      */

        MF_SENDMSGS,        /* monitor sent DDE messages        */

        0))                 /* reserved                         */

    return FALSE;

The DDEML informs a monitoring application of a DDE event by sending an XTYP_MONITOR transaction to the application's DDE callback function. During this transaction, the DDEML passes a monitor flag that specifies the type of DDE event that has occurred and a handle of a DDE object that contains detailed information about the event. The DDEML provides a set of structures that the application can use to extract the information from the DDE object. There is a corresponding structure for each type of DDE event. The following table describes each of these structures.

Structure	Description

MONCBSTRUCT	Contains information about a transaction.

MONCONVSTRUCT	Contains information about a conversation.

MONERRSTRUCT	Contains information about the latest DDE error.

MONLINKSTRUCT	Contains information about an advise loop.

MONHSZSTRUCT	Contains information about a string handle.

MONMSGSTRUCT	Contains information about a DDE message that was sent or posted.

The following example shows the DDE callback function of a DDE monitoring application that formats information about each string handle event and then displays the information in a window. The function uses the MONHSZSTRUCT structure to extract the information from the DDE object.

HDDEDATA CALLBACK DDECallback(uType, uFmt, hconv, hsz1, hsz2,

    hdata, dwData1, dwData2)

UINT uType;

UINT uFmt;

HCONV hconv;

HSZ hsz1;

HSZ hsz2;

HDDEDATA hdata;

DWORD dwData1;

DWORD dwData2;

{

    LPVOID lpData;

    CHAR *szAction;

    CHAR szBuf[256];

    DWORD cb;

    switch (uType) {

        case XTYP_MONITOR:

            /* Obtain a pointer to the global memory object. */

            if (lpData = DdeAccessData(hdata, &cb)) {

                /* Examine the monitor flag. */

                switch (dwData2) {

                    case MF_HSZ_INFO:

#define PHSZS ((MONHSZSTRUCT FAR *)lpData)

                        /*

                         * The global memory object contains

                         * string-handle data. Use the MONHSZSTRUCT

                         * structure to access the data.

                         */

                        switch (PHSZS->fsAction) {

                            /*

                             * Examine the action flags to

                             * determine the action performed on

                             * the handle.

                             */

                            case MH_CREATE:

                                szAction = "Created";

                                break;

                            case MH_KEEP:

                                szAction = "Incremented";

                                break;

                            case MH_DELETE:

                                szAction = "Deleted";

                                break;

                            case MH_CLEANUP:

                                szAction = "Cleaned up";

                                break;

                            default:

                                DdeUnaccessData(hdata);

                                return (HDDEDATA) 0;

                        }

                        /* Write formatted output to a buffer. */

                        wsprintf(szBuf,

                            "Handle %s, Task: %x, Hsz: %lx(%s)",

                            (LPSTR) szAction, PHSZS->hTask,

                            PHSZS->hsz, (LPSTR) PHSZS->str);

                        .

                        . /* Display text or write to a file. */

                        .

                        break;

#undef PHSZS

                    .

                    . /* Process other MF_* flags. */

                    .

                    default:

                        break;

                }

            }

            /* Free the global memory object. */

            DdeUnaccessData(hdata);

            break;

        default:

            break;

    }

    return (HDDEDATA) 0;

}


Shell Library Overview

About the Shell Library

This topic describes features of the shell for the Microsoft® Windows™ operating system. The following features are supported by the dynamic-link library SHELL.DLL:

The drag-drop feature

Associations (used) to find and start applications

Extraction of icons from executable files

The header file for the functions that support these features is SHELLAPI.H. The library is SHELL32.LIB.

The following topics discuss the Win32 shell library:

Terms

Using the Shell Features

Using the Drag-Drop Feature

Using Associations to Find and Start Applications

Extracting Icons From Executable Files

Functions


Using the Shell Features

This section describes how to implement the shell features in your applications.


Using the Drag-Drop Feature

When an application implements the drag-drop feature, a user can select one or more files in File Manager, drag them to an open application, and drop them there. The application in which the files were dropped receives a message it can use to retrieve the filenames and the coordinates of the point at which the files were dropped.

An application that can accept dropped files from File Manager calls the DragAcceptFiles function for one or more of its windows. When the user releases the mouse button to drop a file or files in the window specified in the call to DragAcceptFiles, File Manager sends the application a WM_DROPFILES message. (File Manager does not send the WM_DROPFILES message to an application unless the application calls DragAcceptFiles.) WM_DROPFILES contains a handle of a structure the application can query to retrieve the name of the dropped file and the coordinates of the cursor when the file was dropped. The application can use the DragQueryFile function to retrieve a count of the files that were dropped and their names. The DragQueryPoint function returns the window coordinates of the cursor when the user released the mouse button.

To free the memory allocated by the system for the WM_DROPFILES message, an application calls the DragFinish function when it is finished.

For example, an application can call the DragAcceptFiles function when it starts and call a drag-drop function when it receives a WM_DROPFILES message, as shown in the following example.

case WM_CREATE:

    DragAcceptFiles(hwnd, TRUE);

    break;

case WM_DROPFILES:

    DragFunc(hwnd, wParam); /* application-defined function */

    break;

case WM_DESTROY:

    DragAcceptFiles(hwnd, FALSE);

    break;

The following example uses the DragQueryPoint function to determine where to begin to write text. The first call to the DragQueryFile function determines the number of dropped files. The loop writes the name of each file, beginning at the point returned by DragQueryPoint.

POINT pt;

WORD cFiles, a;

char lpszFile[80];

DragQueryPoint((HANDLE) wParam, &pt);

cFiles = DragQueryFile((HANDLE) wParam, 0xFFFF, (LPSTR) NULL, 0);

for(a = 0; a < cFiles; pt.y += 20, a++) {

    DragQueryFile((HANDLE) wParam, a, lpszFile, sizeof(lpszFile));

    TextOut(hdc, pt.x, pt.y, lpszFile, lstrlen(lpszFile));

}

DragFinish((HANDLE) wParam);


Using Associations to Find and Start Applications

File Manager includes an Associate dialog box that makes it possible for users to associate a filename extension with a specific application. File Manager stores these associations in the registry (under HKEY_CURRENT_USER\Software\Description\Microsoft\Windows NT\CurrentVersion\Extensions). If a file has a filename extension that is associated with an application, that application starts automatically whenever a user double-clicks that file in File Manager.

Using the FindExecutable and ShellExecute functions, applications can take advantage of such associations to find and start applications or open and print files.

An application can use the FindExecutable function to retrieve the name and handle of the executable file that is associated with a specified filename. The ShellExecute function either opens or prints a specified file, depending on the value of its lpszOp parameter. To open a document file, the function relies on the association of the filename extension.


Extracting Icons from Executable Files

An application can use the ExtractIcon function to retrieve the handle of an icon from a specified executable file, dynamic-link library, or icon file. The following example uses the DragQueryPoint function to retrieve the coordinates of the point where a file was dropped, the DragQueryFile function to retrieve the filename of a dropped file, and the ExtractIcon function to retrieve the handle of the first icon in the file, if any.

POINT pt;

WORD cFiles;

HDC hdc;

char lpszFile[80];

HANDLE hCurrentInst, hicon;

DragQueryPoint((HANDLE) wParam, &pt);

cFiles = DragQueryFile((HANDLE) wParam, 0xFFFF, NULL, NULL);

if(cFiles > 1) {

    TextOut(hdc, pt.x, pt.y,

        "Please drop only one icon file.", 31);

    return FALSE;

}

else {

    DragQueryFile((HANDLE) wParam, 0, lpszFile, sizeof(lpszFile));

    hCurrentInst = (HINSTANCE) GetWindowLong(hwnd, GWL_HINSTANCE);

    hicon = ExtractIcon(hCurrentInst, lpszFile, 0);

    if (hicon == NULL)

        TextOut(hdc, pt.x, pt.y, "No icons found.", 15);

    else if (hicon == (HICON) 1)

        TextOut(hdc, pt.x, pt.y,

            "File must be .EXE, .ICO, or .DLL.", 33);

    else

        DrawIcon(hdc, pt.x, pt.y, hicon);

}

DragFinish((HANDLE) wParam);


Functions

The following functions are used to implement shell features.

DragAcceptFiles

DragFinish

DragQueryFile

DragQueryPoint

ExtractAssociatedIcon

ExtractIcon

FindExecutable

ShellAbout

ShellExecute


Screen Saver Library Overview

About Screen Savers

The Microsoft® Win32™ application programming interface (API) supports special applications called screen savers that start when the mouse and keyboard have been idle for a period of time. Screen savers exist for two main reasons:

To avoid phosphor burn caused by static images on a screen

To conceal sensitive information left on a screen

The following topics discuss screen savers:

Using the Screen Saver Functions

Creating a Screen Saver

Supporting the Configuration Dialog Box

Supporting the Screen-Saver's Window Procedure

Creating a Module-Definition File

Installing New Screen Savers

Adding Help

Functions

The Desktop application in Windows Control Panel lets users select from a list of screen savers, specify how much time should elapse before the screen saver is started, configure screen savers, and preview screen savers. Screen savers are loaded automatically when Windows starts or when a user activates the screen saver feature by using Control Panel.

Once a screen saver is chosen, Windows monitors keystrokes and mouse movements, starting the screen saver after a period of inactivity. However, Windows does not start the screen saver if any of the following conditions exist:

The active application is not a Windows-based application.

A computer-based training (CBT) window is present.

The active application returns a nonzero value in response to the WM_SYSCOMMAND message sent with the SC_SCREENSAVE identifier.

Screen savers contain specific exported functions, resource definitions, and variable declarations. The static-link library SCRNSAVE.LIB contains the main function and other startup code required for a screen saver. When a screen saver starts, the startup code in SCRNSAVE.LIB creates a full-screen window. The window class for this window is declared as follows.

WNDCLASS cls;

cls.hCursor        = NULL;

cls.hIcon          = LoadIcon(hInst, MAKEINTATOM(ID_APP));

cls.lpszMenuName   = NULL;

cls.lpszClassName  = "WindowsScreenSaverClass";

cls.hbrBackground  = GetStockObject(BLACK_BRUSH);

cls.hInstance      = hInst;

cls.style          = CS_VREDRAW | CS_HREDRAW

                     | CS_SAVEBITS | CS_DBLCLKS;

cls.lpfnWndProc    = (WNDPROC)ScreenSaverProc;

cls.cbWndExtra     = 0;

cls.cbClsExtra     = 0;

To create a screen saver, most developers create a source-code module containing three required functions and link them with SCRNSAVE.LIB. A screen saver module is responsible only for configuring itself and for providing visual effects.

One of the three required functions in a screen saver module is ScreenSaverProc. This function processes specific messages and passes any unprocessed messages back to SCRNSAVE.LIB. Some of the typical messages processed by ScreenSaverProc are shown in the following table.

Message	Meaning

WM_CREATE	Retrieve any initialization data from the file REGEDIT.INI. Set a window timer for the screen saver window. Perform any other required initialization.

WM_ERASEBKGND	Erase the screen saver window and prepare for subsequent drawing operations.

WM_TIMER	Perform drawing operations.

WM_DESTROY	Destroy the timer(s) created when the application processed the WM_CREATE message. Perform any additional required cleanup.

ScreenSaverProc passes unprocessed messages to SCRNSAVE.LIB by calling the DefScreenSaverProc function. The following table describes how this function processes various messages.

Message	Action

WM_SETCURSOR	Sets the cursor to the null cursor, removing it from the screen.

WM_PAINT	Paints the screen background.

WM_LBUTTONDOWN	Terminates the screen saver.

WM_MBUTTONDOWN	Terminates the screen saver.

WM_RBUTTONDOWN	Terminates the screen saver.

WM_KEYDOWN	Terminates the screen saver.

WM_MOUSEMOVE	Terminates the screen saver.

WM_ACTIVATE	If wParam is FALSE, terminates the screen saver.

The second required function in a screen saver module is ScreenSaverConfigureDialog. This function displays a dialog box that enables the user to configure the screen saver. (Thus, an application must provide a corresponding dialog box template.) Windows displays the configuration dialog box when the user chooses the Setup button in the Screen Saver box in the Desktop application in Control Panel. The data entered by the user with the configuration dialog box is stored in the REGEDIT.INI file.

The third required function in a screen saver module is RegisterDialogClasses. This function must be called by all screen saver applications. However, applications that do not require special windows or custom controls in the configuration dialog box can simply return TRUE. Applications requiring custom controls or special windows should use this function to register the corresponding window classes.

In addition to creating a module that supports the three functions just described, a screen saver should supply an icon. This icon is visible only when the screen saver is run as a stand-alone application. (To be run by Control Panel, a screen saver must have the .SCR filename extension; to be run as a stand-alone application, it must have the .EXE filename extension.) The icon must be identified in the screen saver's resource file by the constant ID_APP, which is defined in the header file SCRNSAVE.H.

One final requirement is a screen saver description string. The resource file for a screen saver must contain a descriptive string that Control Panel displays as the screen saver name. The description string must be the first string in the resource file's string table (identified with the ordinal value 1).


Using the Screen Saver Functions

This section uses example code taken from a screen saver application to illustrate the following tasks:

Creating a screen saver

Creating a screen saver dialog box template

Supporting the screen saver window procedure

Creating a module-definition file

It also describes how to install new screen savers and add Help for a screen saver application.


Creating a Screen Saver

This section contains example code taken from a screen saver application. At intervals ranging from 1 through 10 seconds, this application repaints the screen with one of four colors: white, light gray, dark gray, and black. The application paints the screen each time it receives a WM_TIMER message. The user can adjust the interval at which this message is sent by displaying the application's configuration dialog box and adjusting a single horizontal scroll bar. The following illustration shows this dialog box.


Supporting the Configuration Dialog Box

Supporting the Configuration Dialog Box

Most screen savers provide a configuration dialog box to let the user specify customization data such as unique colors, drawing speeds, line thicknesses, fonts, and so on. To support the configuration dialog box, the application must provide the necessary dialog box template and must also support the ScreenSaverConfigureDialog function. Following is the dialog box template for the sample application.

DLG_SCRNSAVECONFIGURE DIALOG 6, 18, 160, 63

LANGUAGE LANG_NEUTRAL, SUBLANG_NEUTRAL

STYLE DS_MODALFRAME | WS_POPUP | WS_VISIBLE | WS_CAPTION | WS_SYSMENU

CAPTION "Sample Screen-Saver Setup"

FONT 8, "MS Sans Serif"

BEGIN

    GROUPBOX        "Redraw Speed", 101, 0, 6, 98, 40

    SCROLLBAR       ID_SPEED, 5, 31, 89, 10

    LTEXT           "Fast", 103, 6, 21, 20, 8

    LTEXT           "Slow", 104, 75, 21, 20, 8

    PUSHBUTTON      "OK", ID_OK, 117, 10, 40, 14

    PUSHBUTTON      "Cancel", ID_CANCEL, 117, 32, 40, 14

END

You must define the constant used to identify the dialog box template by using the decimal value 2003, as in the following example.

#define  DLG_SCRNSAVECONFIGURE 2003

The following example shows the ScreenSaverConfigureDialog function found in the sample application.

#define MINVEL  1               /* minimum redraw-speed value    */

#define MAXVEL  10              /* maximum redraw-speed value    */

#define DEFVEL  5               /* default redraw-speed value    */

LONG    lSpeed = DEFVEL;        /* redraw-speed variable         */

extern HINSTANCE hMainInstance; /* screen saver instance handle  */

CHAR   szAppName[80];           /* .INI section name             */

CHAR   szTemp[20];              /* temporary array of characters */

CHAR   szRedrawSpeed[] = "Redraw Speed";   /* .INI speed entry   */

BOOL WINAPI ScreenSaverConfigureDialog(hDlg, message, wParam, lParam)

HWND  hDlg;

UINT  message;

DWORD wParam;

LONG  lParam;

{

    static HWND hSpeed; /* handle of speed scroll bar */

    static HWND hOK;    /* handle of OK push button */

    switch(message)

    {

        case WM_INITDIALOG:

            /* Retrieve the application-name string from the .RC file. */

            LoadString(hMainInstance, idsAppName, szAppName, 40);

            /* Retrieve the .INI (or registry) filename. */

            LoadString(hMainInstance, idsIniFile, szIniFile, MAXFILELEN);

            /* Retrieve any redraw-speed data from the registry. */

            lSpeed = GetPrivateProfileInt(szAppName, szRedrawSpeed,

                DEFVEL, szIniFile);

            /*

             * If the initialization file does not contain an entry

             * for this screen saver, use the default value.

             */

            if(lSpeed > MAXVEL || lSpeed < MINVEL)

                lSpeed = DEFVEL;

            /* Initialize the redraw-speed scroll bar control. */

            hSpeed = GetDlgItem(hDlg, ID_SPEED);

            SetScrollRange(hSpeed, SB_CTL, MINVEL, MAXVEL, FALSE);

            SetScrollPos(hSpeed, SB_CTL, lSpeed, TRUE);

            /* Retrieve a handle of the OK push button control. */

            hOK = GetDlgItem(hDlg, ID_OK);

            return TRUE;

        case WM_HSCROLL:

            /*

             * Process scroll bar input, adjusting the lSpeed

             * value as appropriate.

             */

            switch (LOWORD(wParam))

                {

                    case SB_PAGEUP:

                        --lSpeed;

                    break;

                    case SB_LINEUP:

                        --lSpeed;

                    break;

                    case SB_PAGEDOWN:

                        ++lSpeed;

                    break;

                    case SB_LINEDOWN:

                        ++lSpeed;

                    break;

                    case SB_THUMBPOSITION:

                        lSpeed = HIWORD(wParam);

                    break;

                    case SB_BOTTOM:

                        lSpeed = MINVEL;

                    break;

                    case SB_TOP:

                        lSpeed = MAXVEL;

                    break;

                    case SB_THUMBTRACK:

                    case SB_ENDSCROLL:

                        return TRUE;

                    break;

                }

                if ((int) lSpeed <= MINVEL)

                    lSpeed = MINVEL;

                if ((int) lSpeed >= MAXVEL)

                    lSpeed = MAXVEL;

                SetScrollPos((HWND) lParam, SB_CTL, lSpeed, TRUE);

            break;

        case WM_COMMAND:

            switch(LOWORD(wParam))

            {

                case ID_OK:

                    /*

                    * Write the current redraw-speed variable to

                    * the .INI file.

                    */

                    wsprintf(szTemp, "%ld", lSpeed);

                    WritePrivateProfileString(szAppName, szRedrawSpeed,

                        szTemp, szIniFile);

                case ID_CANCEL:

                    EndDialog(hDlg, LOWORD(wParam) == ID_OK);

                return TRUE;

            }

    }

    return FALSE;

}

In addition to providing the dialog box template and supporting the ScreenSaverConfigureDialog function, an application must also support the RegisterDialogClasses function. This function registers any nonstandard window classes required by the screen saver. Because the sample application used only standard window classes in its dialog box procedure, this function simply returns TRUE, as in the following example.

BOOL WINAPI RegisterDialogClasses(hInst)

HANDLE  hInst;

{

    return TRUE;

}


Supporting the Screen Saver Window Procedure

Supporting the Screen Saver Window Procedure

Each screen saver must support a window procedure named ScreenSaverProc. Like most window procedures, ScreenSaverProc processes a set of specific messages and passes any unprocessed messages to a default procedure. However, instead of passing them to the DefWindowProc function, ScreenSaverProc passes unprocessed messages to the DefScreenSaverProc function. Another difference between ScreenSaverProc and a normal window procedure is that the handle passed to ScreenSaverProc identifies the entire desktop rather than a client window. The following example shows the ScreenSaverProc window procedure for the sample screen saver.

#define MINVEL  1               /* minimum redraw-speed value    */

#define MAXVEL  10              /* maximum redraw-speed value    */

#define DEFVEL  5               /* default redraw-speed value    */

LONG    lSpeed = DEFVEL;        /* redraw-speed variable         */

extern HINSTANCE hMainInstance; /* screen saver instance handle  */

CHAR   szAppName[80];           /* .INI section name             */

CHAR   szTemp[20];              /* temporary array of characters */

CHAR   szRedrawSpeed[] = "Redraw Speed";   /* .INI speed entry   */

BOOL WINAPI ScreenSaverConfigureDialog(hDlg, message, wParam, lParam)

HWND  hDlg;

UINT  message;

DWORD wParam;

LONG  lParam;

{

    static HWND hSpeed; /* handle of speed scroll bar */

    static HWND hOK;    /* handle of OK push button */

    switch(message)

    {

        case WM_INITDIALOG:

            /* Retrieve the application-name string from the .RC file. */

            LoadString(hMainInstance, idsAppName, szAppName, 40);

            /* Retrieve the .INI (or registry) filename. */

            LoadString(hMainInstance, idsIniFile, szIniFile, MAXFILELEN);

            /* Retrieve any redraw-speed data from the registry. */

            lSpeed = GetPrivateProfileInt(szAppName, szRedrawSpeed,

                DEFVEL, szIniFile);

            /*

             * If the initialization file does not contain an entry

             * for this screen saver, use the default value.

             */

            if(lSpeed > MAXVEL || lSpeed < MINVEL)

                lSpeed = DEFVEL;

            /* Initialize the redraw-speed scroll bar control. */

            hSpeed = GetDlgItem(hDlg, ID_SPEED);

            SetScrollRange(hSpeed, SB_CTL, MINVEL, MAXVEL, FALSE);

            SetScrollPos(hSpeed, SB_CTL, lSpeed, TRUE);

            /* Retrieve a handle of the OK push button control. */

            hOK = GetDlgItem(hDlg, ID_OK);

            return TRUE;

        case WM_HSCROLL:

            /*

             * Process scroll bar input, adjusting the lSpeed

             * value as appropriate.

             */

            switch (LOWORD(wParam))

                {

                    case SB_PAGEUP:

                        --lSpeed;

                    break;

                    case SB_LINEUP:

                        --lSpeed;

                    break;

                    case SB_PAGEDOWN:

                        ++lSpeed;

                    break;

                    case SB_LINEDOWN:

                        ++lSpeed;

                    break;

                    case SB_THUMBPOSITION:

                        lSpeed = HIWORD(wParam);

                    break;

                    case SB_BOTTOM:

                        lSpeed = MINVEL;

                    break;

                    case SB_TOP:

                        lSpeed = MAXVEL;

                    break;

                    case SB_THUMBTRACK:

                    case SB_ENDSCROLL:

                        return TRUE;

                    break;

                }

                if ((int) lSpeed <= MINVEL)

                    lSpeed = MINVEL;

                if ((int) lSpeed >= MAXVEL)

                    lSpeed = MAXVEL;

                SetScrollPos((HWND) lParam, SB_CTL, lSpeed, TRUE);

            break;

        case WM_COMMAND:

            switch(LOWORD(wParam))

            {

                case ID_OK:

                    /*

                    * Write the current redraw-speed variable to

                    * the .INI file.

                    */

                    wsprintf(szTemp, "%ld", lSpeed);

                    WritePrivateProfileString(szAppName, szRedrawSpeed,

                        szTemp, szIniFile);

                case ID_CANCEL:

                    EndDialog(hDlg, LOWORD(wParam) == ID_OK);

                return TRUE;

            }

    }

    return FALSE;

}

LONG WINAPI ScreenSaverProc(hwnd, message, wParam, lParam)

HWND  hwnd;

UINT  message;

DWORD wParam;

LONG  lParam;

{

static HDC          hdc;    /* device-context handle */

static RECT         rc;     /* RECT structure */

static UINT         uTimer; /* timer identifier */

    switch(message)

    {

        case WM_CREATE:

            /* Retrieve the application-name string from the .RC file. */

            LoadString(hMainInstance, idsAppName, szAppName, 40);

            /* Retrieve the .INI (or registry) filename. */

            LoadString(hMainInstance, idsIniFile, szIniFile, MAXFILELEN);

            /* Retrieve any redraw-speed data from the registry. */

            lSpeed = GetPrivateProfileInt(szAppName, szRedrawSpeed,

                DEFVEL, szIniFile);

           /*

            * Set a timer for the screen saver window using the

            * redraw-rate stored in REGEDIT.INI.

            */

            uTimer = SetTimer(hwnd, 1, lSpeed * 1000, NULL);

            break;

        case WM_ERASEBKGND:

           /*

            * The WM_ERASEBKGND message is issued before the

            * WM_TIMER message, allowing the screen saver to

            * paint the background as appropriate.

            */

            hdc = GetDC(hwnd);

            GetClientRect (hwnd, &rc);

            FillRect (hdc, &rc, GetStockObject(BLACK_BRUSH));

            ReleaseDC(hwnd,hdc);

            break;

        case WM_TIMER:

           /*

            * The WM_TIMER message is issued at (lSpeed * 1000)

            * intervals, where lSpeed == .001 seconds. This

            * code repaints the entire desktop with a white,

            * light gray, dark gray, or black brush each

            * time a WM_TIMER message is issued.

            */

            hdc = GetDC(hwnd);

            GetClientRect(hwnd, &rc);

            if (i++ <= 4)

                FillRect(hdc, &rc, GetStockObject(i));

            else

                (i = 0);

            ReleaseDC(hwnd,hdc);

            break;

        case WM_DESTROY:

           /*

            * When the WM_DESTROY message is issued, the screen saver

            * must destroy any of the timers that were set at WM_CREATE

            * time.

            */

            if (uTimer)

                KillTimer(hwnd, uTimer);

            break;

    }

   /*

    * DefScreenSaverProc processes any messages

    * ignored by ScreenSaverProc.

    */

    return DefScreenSaverProc(hwnd, message, wParam, lParam);

}


Creating a Module-Definition File

Creating a Module-Definition File

The ScreenSaverProc and ScreenSaverConfigureDialog functions must be exported in the application's module-definition file; however, the RegisterDialogClasses function should not be exported. The following example shows the module-definition file for the sample application.

NAME    SSTEST.SCR

DESCRIPTION 'SCRNSAVE : Test'

STUB    'WINSTUB.EXE'

EXETYPE WINDOWS

CODE    MOVEABLE

DATA    MOVEABLE MULTIPLE

HEAPSIZE  1024

STACKSIZE 4096

EXPORTS

        ScreenSaverProc

        ScreenSaverConfigureDialog


Installing New Screen Savers

When compiling the list of available screen savers, Control Panel searches the Windows startup directory for files with the .SCR extension. Because screen savers are standard Windows executable files with .EXE extensions, you must rename them so they have .SCR extensions and copy them to the correct directory.


Adding Help

The configuration dialog box for a screen saver typically includes a Help button. Screen saver applications can check for the Help button identifier and call the WinHelp function in the same way Help is provided in other Windows-based applications.


Functions

Following are the functions used with screen savers.

DefScreenSaverProc

RegisterDialogClasses

ScreenSaverConfigureDialog

ScreenSaverProc


File Installation Library Overview

About File Installation

The Microsoft® Windows NT™ file installation library makes it easier for applications to install files properly and enables setup programs to analyze files currently installed.

The functions included in the file installation library determine where a file should be installed, identify conflicts with currently installed files, and perform the installation process. These functions enable installation programs to avoid the following problems:

Installing older versions of components over newer versions

Changing the language in a mixed-language system without notification

Installing multiple copies of a library in different directories

Copying files to network directories shared by multiple users

The file installation library also includes functions that enable applications to query a version resource for information about a file and present the information in a clear format. This information includes the file's purpose, author, version number, and so on.

Version information can be added to any Microsoft® Windows™ file that can have Windows resources, such as a dynamic-link library (DLL), an executable file, or a font file. To add the information, a developer must create a version resource and add the resource to the file by using a resource compiler.

The file installation library (VER.DLL) and header file (VER.H) are available only for Windows-based applications.

The following topics discuss the file installation library:

Creating an Installation Program

Functions


Creating an Installation Program

An installation program typically has the following goals:

To place files in the correct location.

To notify the user if the installation program is replacing an existing file with a version that is significantly different--for example, replacing a German-language file with an English-language file, or replacing a newer file with an older file.

When writing the installation program, the developer must have the following information for each file on the installation disk(s):

The name and location of the file (referred to as the source file).

The name of the equivalent file on the user's hard disk (referred to as the destination file). This name is usually the same as the filename on the installation disk.

The sharing status of the file--that is, whether the file is private to the application being installed or could be shared by multiple applications.

For each file on the installation disk(s), the installation program must, at a minimum, call the VerFindFile and VerInstallFile functions. These functions are described briefly in the following paragraphs.

The installation program can use VerFindFile with the destination-file name to determine where the file should be copied on the disk. This function can also be used to specify whether the file is private to the application or can be shared. If a problem occurs in finding the file, VerFindFile returns an error value. For example, if Windows is using the destination file, VerFindFile returns VFF_FILEINUSE. The installation program must notify the user of the problem and respond to the user's decision to continue or to end the installation.

VerInstallFile copies the source file to a temporary file in the directory specified by VerFindFile. If necessary, VerInstallFile expands the file by using the functions in the data decompression library, LZEXPAND.DLL.

VerInstallFile compares the version information of the temporary file to that of the destination file. If the two differ, VerInstallFile returns one or more error values. For example, it returns VIF_SRCOLD if the temporary file is older than the destination file and VIF_DIFFLANG if the files have different language identifiers or code-page values. The installation program must notify the user of the problem and respond to the user's decision to continue or to end the installation.

Some VerInstallFile errors are recoverable. That is, the installation program can call VerInstallFile again, specifying the VIFF_FORCEINSTALL option, to install the file regardless of the version conflict. If VerInstallFile returns VIF_TEMPFILE and the user chooses not to force the installation, the installation program should delete the temporary file.

VerInstallFile could encounter a nonrecoverable error when attempting to force installation, even though the error did not exist previously. For example, the file could be locked by another user before the installation program tried to force installation. If an installation program attempts to force installation after a non-recoverable error, VerInstallFile fails. The installation program must contain routines to recover from this type of error.

The recommended solution is to display for all errors a common dialog box with the buttons Install, Skip, and Install All. The Install All button should prevent the installation program from prompting the user about similar errors by including the VIFF_FORCEINSTALL option in all subsequent uses of VerInstallFile. For nonrecoverable errors, the Install and Install All buttons should be disabled.

To display a useful error message to the user, the installation program usually must retrieve information from the version resources of the conflicting files. The file installation library provides four functions the installation program can use for this purpose: the GetFileVersionInfoSize, GetFileVersionInfo, VerQueryValue, and VerLanguageName functions. GetFileVersionInfoSize returns the size of the version information. GetFileVersionInfo uses information retrieved by GetFileVersionInfoSize to retrieve a structure that contains the version information. VerQueryValue retrieves a specific member from that structure.

For example, if VerInstallFile returns the VIF_DIFFTYPE error, the installation program should use the GetFileVersionInfoSize, GetFileVersionInfo, and VerQueryValue functions on the temporary and destination files to obtain the general type of each file. If the languages of the files conflict, the installation program should also use VerLanguageName to translate the binary language identifier into a text representation of the language. (For example, 0x040C translates to the string French.)

If VerInstallFile returns a file error, such as VIF_ACCESSVIOLATION, the installation program should use the GetLastError function to retrieve the most recent error value. The program should translate this value into an informative message to display to the user. The program must not yield control between the calls to VerInstallFile and GetLastError.


Functions

Following are the functions used for file installation.

GetFileVersionInfo

GetFileVersionInfoSize

VerFindFile

VerInstallFile

VerLanguageName

VerQueryValue

GetFileResource (obsolete)

GetFileResourceSize (obsolete)


Data Decompression Library Overview

The following topics discuss Win32 data compression:

Data Compression

Data Decompression

Using the Data Decompression Library

Decompressing a Single File

Decompressing Multiple Files

Reading Bytes from Compressed Files

Functions


Data Compression

Data compression is an operation that reduces the size of a file by minimizing redundant data. In a file that contains text, redundant data can be frequently occurring characters, such as the space character, or common vowels, such as the letters e and a; it can also be frequently occurring character strings. Data compression creates a compressed version of a file by minimizing this redundant data.

Each type of data-compression algorithm minimizes redundant data in a unique manner. For example, the Huffman encoding algorithm assigns a code to characters in a file based on how frequently those characters occur. Another compression algorithm, called run-length encoding, generates a two-part value for repeated characters: the first part specifies the number of times the character is repeated, and the second part identifies the character. Another compression algorithm, known as the Lempel-Ziv algorithm, converts variable-length strings into fixed-length codes that consume less space than the original strings.

To compress large applications or data files, you can run COMPRESS.EXE from the command line. COMPRESS.EXE uses the Lempel-Ziv compression algorithm.


Data Decompression

Applications can call the functions in LZEXPAND.DLL to decompress files compressed by using COMPRESS.EXE. The functions can also process uncompressed files without attempting to decompress them. To use these functions, applications must include the LZEXPAND.H header file.

The following table describes each function found in LZEXPAND.DLL.

Function	Purpose

CopyLZFile	This function is obsolete. It is provided only for backwards compatibility. Win32 applications should use the LZCopy function.

GetExpandedName	Retrieves the original name of a compressed file, if the /r option was used during compression of the file.

LZClose	Closes a file that was opened when the application called the LZOpenFile function.

LZCopy	Copies a source file to a destination file. If the source file is compressed, this function creates a decompressed destination file. If the source file is not compressed, this function duplicates the original file. This function is intended for single-file copy operations.

LZDone	This function is obsolete. It is provided only for backwards compatibility. Win32 applications should not use this function.

LZInit	Creates structures used for decompressing files.

LZOpenFile	Opens a file and returns a handle that identifies it.

LZRead	Reads a specified number of bytes from a file. If the file is compressed, this function decompresses the bytes before copying them to the destination buffer.

LZSeek	Positions the file pointer within the decompressed image of a compressed file. The application calls this function to position the pointer before calling the LZRead function.

LZStart	This function is obsolete. It is provided only for backwards compatibility. Win32 applications should not use it.


Using the Data Decompression Library

Functions in LZEXPAND.DLL can be used to decompress single or multiple files. They can also be used to decompress compressed files a portion at a time.


Decompressing a Single File

An application can decompress a single compressed file by performing the following tasks.

1	Open the source file by calling the LZOpenFile function.

2	Open the destination file by calling LZOpenFile.

3	Copy the source file to the destination file by calling the LZCopy function and passing the handles returned by LZOpenFile.

4	Close the files by calling the LZClose function.


Decompressing Multiple Files

An application can decompress multiple files by performing the following tasks.

1	Open the source files by calling the LZOpenFile function.

2	Open the destination files by calling LZOpenFile.

3	Copy the source files to the destination files by calling the LZCopy function.

4	Close the files by calling the LZClose function.


Reading Bytes from Compressed Files

In addition to decompressing a complete file in a single operation, an application can decompress a compressed file a portion at a time by using the LZSeek and LZRead functions. These functions are particularly useful when it is necessary to extract parts of large files. For example, a font manufacturer may have compressed files containing font metrics in addition to character data. To use the information in these files, an application would need to decompress the file; however, most applications would use only part of the file at any particular time. To get information about font metrics, the application would extract data from the header. To get information from the text, the application would reposition the file pointer by calling LZSeek and extract character data by calling LZRead.


Functions

Following are the functions used to decompress files.

GetExpandedName

LZClose

LZCopy

LZInit

LZOpenFile

LZRead

LZSeek


Control Panel Applications Overview

About Control Panel

This topic describes  Microsoft® Windows™ Control Panel (CONTROL.EXE) and explains how to create a Control Panel application and add it to Control Panel.

Control Panel provides a window for running applications used to configure the Windows environment. A number of standard applications are included with Windows. However, additional applications can be created and added to Control Panel. You can use this capability to modify environmental factors unique to specific hardware and software. The following illustration shows the Control Panel window.

An application is contained in a dynamic-link library (DLL). A DLL can support more than one Control Panel application.

Control Panel loads Control Panel application libraries in this order:

1	The library containing the standard Control Panel applications.

2	Libraries with the .CPL filename extension residing in the Windows SYSTEM directory.

3	Libraries specified by the MMCPL key of the HKEY_CURRENT_USER key in the registry.

4	Libraries with the .CPL filename extension residing in the same directory as the CONTROL.EXE file.

The following topics discuss Win32 control-panel applications:

Starting a Control Panel Application

Creating a Control Panel Application

Creating the Entry-Point Function

Initializing the Application

Responding to User Actions

Closing the Application and the Dynamic-Link Library

Example of a Control Panel Application

Setting Up a New Application

Functions and Structures


Starting a Control Panel Application

There are three ways to start a Control Panel application:

The user can open Control Panel and start an application by double-clicking the application icon.

The user or an application can open Control Panel by using a command-line argument that specifies the filename of the application to start. When the application closes, Control Panel also closes.

An application can send a WM_CPL_LAUNCH message to Control Panel while Control Panel is running. When the Control Panel application closes, Control Panel sends back a WM_CPL_LAUNCHED confirmation message.

The following code sample shows how an application can start Control Panel and the Sound application by using the WinExec function and a command-line argument.

WinExec("control.exe sound", SW_SHOWNORMAL)

When Control Panel starts, it immediately displays the Sound application. After the Sound application is closed, Control Panel closes.

The following code sample shows a function that starts a Control Panel application by using the WM_CPL_LAUNCH message.

#include <windows.h>    /* required for all Windows applications */

HANDLE hinst;

BOOL StartApplet(LPSTR lpszName, HWND hwndMine)

{

    HGLOBAL hglbAppletName;   /* handle of application name     */

    HWND hwndCPL;             /* handle of Control Panel window */

    LPSTR lpszAppletName;     /* name of application            */

    BOOL fStartedCPL = FALSE; /* application started?           */

    CHAR szName[] = "printers.cpl"; /* application name         */

    /*

     * Allocate a shareable memory block to hold the

     * application name string.

     */

    hglbAppletName = GlobalAlloc(GMEM_MOVEABLE,

        lstrlen(szName) + 1);

    if (hglbAppletName == NULL)

        return FALSE;

    lpszAppletName = GlobalLock(hglbAppletName);

    lstrcpy(lpszAppletName, szName);

    GlobalUnlock(hglbAppletName);

    /*

     * Get the Control Panel window handle and start Control Panel,

     * if necessary.

     */

    if ((hwndCPL = FindWindow("CtlPanelClass",

            "Control Panel")) == NULL) {

        WinExec("control.exe", SW_SHOWNA);

        hwndCPL = FindWindow("CtlPanelClass", "Control Panel");

        if (hwndCPL == NULL) {

            GlobalFree(hglbAppletName);

            return FALSE;

        }

        fStartedCPL = TRUE;

    }

    /* Start the application and end Control Panel, if started. */

    SendMessage(hwndCPL, WM_CPL_LAUNCH, (WPARAM) hwndMine,

        (LPARAM) lpszAppletName);

    if (fStartedCPL)

        SendMessage(hwndCPL, WM_CLOSE, 0, 0);

    GlobalFree(hglbAppletName);

    return TRUE;

}


Creating a Control Panel Application

A Control Panel application must reside in a DLL that includes a standard entry-point function named CPlApplet. The application must include the CPL.H header file for the definition of Control Panel messages. Control Panel communicates with the DLL by sending the following CPL messages to the CPlApplet function.

Message	Description

CPL_DBLCLK	Sent when the user double-clicks an application icon. In response to this message, the DLL starts its configuration process, usually displaying a dialog box.

CPL_EXIT	Sent after the last CPL_STOP message and immediately before Control Panel calls the FreeLibrary function for the DLL. In response to this message, the DLL frees any remaining memory and prepares to close.

CPL_GETCOUNT	Sent after the CPL_INIT message, to prompt the DLL to return a number indicating how many applications it services.

CPL_INIT	Sent immediately after the DLL is loaded, to prompt the DLL to perform initialization procedures, including memory allocation.

CPL_INQUIRE	Sent after the CPL_GETCOUNT message, to prompt the DLL to provide information about each application. The handler for this message is a good place to include any initialization required by individual applications.

CPL_NEWINQUIRE	Sent to a Control Panel DLL to request information about an application the DLL supports. The CPL_NEWINQUIRE message is the same as the CPL_INQUIRE message except that its second parameter (lParam2) is a pointer to a NEWCPLINFO structure instead of a CPLINFO structure. Use CPL_NEWINQUIRE instead of CPL_INQUIRE in new applications.

CPL_SELECT	Sent when the user selects an application icon.

CPL_STOP	Sent once for each application before Control Panel closes. In response to this message, the DLL frees any memory associated with the individual application for which the message is sent.


Creating the Entry-Point Function

Control Panel communicates with an application DLL through the CPlApplet function. Make sure to export this function by listing it in the EXPORTS statement of your module-definition (.DEF) file. The CPlApplet function handles the messages listed previously, performing three main tasks.

Task	Result

Initializing the application (CPL_INIT, CPL_NEWINQUIRE)

Allocates necessary memory and gives Control Panel the information for displaying the application icon.

Running the application (CPL_DBLCLK)

Passes control to a dialog box and its associated message processor.

Closing the application (CPL_STOP, CPL_EXIT)

Frees any memory allocated and prepares to close.

The CPlApplet function has the following syntax:

LONG CALLBACK* CPlApplet(hwndCPL, uMsg, lParam1, lParam2)

The hwndCPL parameter contains the handle of the Control Panel window. The uMsg parameter contains one of the CPL messages listed previously. The lParam1 and lParam2 parameters contain message-dependent values.


Initializing the Application

To initialize a Control Panel application, Control Panel sends the CPL_INIT message first to the CPlApplet function, which prompts the application DLL to perform initialization procedures. If initialization succeeds, CPlApplet returns nonzero.

If CPlApplet returns zero in response to the CPL_INIT message, Control Panel calls the FreeLibrary function and ends communication with the application DLL. This is the only way an application can notify Control Panel of initialization problems and prevent the application from being loaded.

If initialization succeeds, Control Panel sends the CPL_GETCOUNT message. The CPlApplet function responds by returning the number of applications serviced by the application DLL. This number determines how many icons Control Panel displays for the DLL.

After Control Panel finds out the number of applications serviced by the DLL, it sends the CPL_NEWINQUIRE message once for each application. The lParam1 parameter specifies the application number--0 for the first application and CPL_GETCOUNT - 1 for the last application.

Control Panel passes a far pointer to a NEWCPLINFO structure in the lParam2 parameter. The NEWCPLINFO structure has the following form.

typedef struct tagNEWCPLINFO /* ncpli */

{

    DWORD dwSize;          /* length of structure, in bytes     */

    DWORD dwFlags;         /* setup flags                       */

    DWORD dwHelpContext;   /* help-context number               */

    LONG  lData;           /* application-defined data          */

    HICON hIcon;           /* handle of icon (owned by CPL.EXE) */

    char  szName[32];      /* short-name string                 */

    char  szInfo[64];      /* description string (status line)  */

    char  szHelpFile[128]; /* path to help file                 */

} NEWCPLINFO;

The CPlApplet function must fill in the NEWCPLINFO structure. The function must assign values for the dwSize, hIcon, szName, and szInfo members for the structure size, application icon, short name, and description, respectively. To add a keyboard accelerator for the application, precede the selected accelerator character in the szName string with an ampersand. If the application DLL supports context-sensitive Help, the CPlApplet function should also assign the values for the dwHelpContext and szHelpFile members. The lData member can be used for application-defined data.

Note:	The CPL_NEWINQUIRE message and NEWCPLINFO structure replace the CPL_INQUIRE message and CPLINFO structure. The latter have been retained for backward compatibility with Windows 3.x. If the application DLL does not respond to the CPL_NEWINQUIRE message, Control Panel sends it the CPL_INQUIRE message. Then the lParam2 parameter points to a CPLINFO structure rather than to a NEWCPLINFO structure.


Responding to User Actions

Control Panel sends the CPL_SELECT or CPL_DBLCLK message when the user selects or double-clicks an application icon. For each message, Control Panel passes the application number in the lParam1 parameter and the lData value in the lParam2 parameter.

Typically, an application DLL does not respond to the CPL_SELECT message. Upon receiving the CPL_DBLCLK message, the application transfers control to the appropriate dialog box.


Closing the Application and the Dynamic-Link Library

Before closing, Control Panel sends the CPL_STOP message once for each application in the DLL. lParam1 and lParam2 sent with the CPL_STOP message correspond to the application number and the lData value. After Control Panel sends the last CPL_STOP message, it sends a CPL_EXIT message and then calls the FreeLibrary function to free the DLL.

When the CPL_STOP and CPL_EXIT cases are executed, the DLL frees memory that it allocated. Typically, the DLL frees memory associated with individual applications when the CPL_STOP case is executed and frees any other allocated memory when the CPL_EXIT case is executed. The DLL also unregisters any private window classes that it registered during the CPL_INIT message.


Example of a Control Panel Application

The following code sample shows the CPlApplet function for a DLL containing three Control Panel applications that set preferences for a component stereo system attached to the computer.

The sample uses an application-defined StereoApplets array that contains three structures, each corresponding to one of the Control Panel applications. Each structure contains all the information required by the CPL_INQUIRE message, as well as the dialog box template and dialog box procedure required by the CPL_DBLCLK message. The code demonstrates how to fill the structures in the StereoApplets array.

#define NUM_APPLETS 3

typedef struct tagApplets

{

    int icon;         /* icon resource identifier                */

    int namestring;   /* name-string resource identifier         */

    int descstring;   /* description-string resource identifier  */

    int dlgtemplate;  /* dialog box template resource identifier */

    DLGPROC dlgfn;    /* dialog box procedure                    */

} APPLETS;

APPLETS StereoApplets[NUM_APPLETS] =

{

    AMP_ICON, AMP_NAME, AMP_DESC, AMP_DLG, AmpDlgProc,

    TUNER_ICON, TUNER_NAME, TUNER_DESC, TUNER_DLG, TunerDlgProc,

    TAPE_ICON, TAPE_NAME, TAPE_DESC, TAPE_DLG, TapeDlgProc,

};

This code defines the CPlApplet function for the preceding example.

LONG CALLBACK CPlApplet(hwndCPL, uMsg, lParam1, lParam2)

HWND hwndCPL;      /* handle of Control Panel window */

UINT uMsg;         /* message                        */

LPARAM lParam1;    /* first message parameter        */

LPARAM lParam2;    /* second message parameter       */

{

    int i;

    LPNEWCPLINFO lpNewCPlInfo;

    i = (int) lParam1;

    switch (uMsg) {

        case CPL_INIT: /* first message, sent once  */

            hinst = GetModuleHandle("ecp.cpl");

            return TRUE;

        case CPL_GETCOUNT: /* second message, sent once */

            return NUM_APPLETS;

            break;

        case CPL_NEWINQUIRE: /* third message, sent once per app */

            lpNewCPlInfo = (LPNEWCPLINFO) lParam2;

            lpNewCPlInfo->dwSize = (DWORD) sizeof(NEWCPLINFO);

            lpNewCPlInfo->dwFlags = 0;

            lpNewCPlInfo->dwHelpContext = 0;

            lpNewCPlInfo->lData = 0;

            lpNewCPlInfo->hIcon = LoadIcon(hinst,

                (LPCTSTR) MAKEINTRESOURCE(StereoApplets[i].icon));

            lpNewCPlInfo->szHelpFile[0] = '\0';

            LoadString(hinst, StereoApplets[i].namestring,

                lpNewCPlInfo->szName, 32);

            LoadString(hinst, StereoApplets[i].descstring,

                lpNewCPlInfo->szInfo, 64);

            break;

        case CPL_SELECT: /* application icon selected */

            break;

        case CPL_DBLCLK: /* application icon double-clicked */

            MessageBeep(MB_ICONEXCLAMATION);

            DialogBox(hinst,

                MAKEINTRESOURCE(StereoApplets[i].dlgtemplate),

                hwndCPL, StereoApplets[i].dlgfn);

            break;

        case CPL_STOP: /* sent once per app. before CPL_EXIT */

            break;

        case CPL_EXIT: /* sent once before FreeLibrary called */

            break;

        default:

            break;

    }

    return 0;

}


Setting Up a New Application

There are three ways to register an application DLL with Control Panel:

List the DLL in the MMCPL key of the HKEY_CURRENT_USER key in the registry. Use this method when the DLL is part of a system library and processes more than just messages from Control Panel.

Assign the DLL a .CPL filename extension and add it to the directory that contains the CONTROL.EXE file.

Assign the DLL a .CPL filename extension and add it to the Windows SYSTEM directory.


Functions and Messages

Following are the functions and messages used by Control Panel applications.

Functions

CPlApplet

Messages

CPL_DBLCLK

CPL_EXIT

CPL_GETCOUNT

CPL_INIT

CPL_INQUIRE

CPL_NEWINQUIRE

CPL_SELECT

CPL_STOP

WM_CPL_LAUNCH

WM_CPL_LAUNCHED


File Manager Extensions Overview

About File Manager Extensions

In Microsoft® Windows™, a File Manager extension is a dynamic-link library (DLL) that adds a menu and buttons to File Manager. A File Manager extension can also display (in the status bar) Help text for the buttons.

File Manager maintains a list of extensions in an initialization file and loads the extensions when starting. An extension DLL contains an entry point that processes menu commands and notification messages sent by File Manager. Up to five extension DLLs can be installed at any one time. This topic describes how to create and install extensions for File Manager.

The following topics discuss File Manager extensions:

Creating a File Manager Extension

Creating the Entry-Point Function

Loading the Extension

Adding Custom Buttons

Processing Menu Selections

Initializing the Extension Menu

Updating the Extension Menu

Processing File Selections

Quitting the Extension DLL

Installing Extensions

Extension Messages

Processing Commands and Messages from File Manager

Adding the Undelete Command


Creating a File Manager Extension

A File Manager extension must reside in a DLL that includes a standard entry point, the FMExtensionProc callback function. The extension must include the WFEXT.H header file that defines File Manager messages and structures. File Manager communicates with the extension DLL by sending the following messages to the DLL's FMExtensionProc function.

Message	Meaning

1-99	User has selected an item from the extension-supplied menu. The value is the identifier of the selected menu item.

FMEVENT_HELPSTRING	User is selecting an extension menu or toolbar command item. File Manager wants the extension to supply a helpstring.

FMEVENT_HELPMENUITEM	User has pressed F1 while selecting an extension menu or toolbar command item. File Manager wants the extension to call WinHelp appropriately for the command item.

FMEVENT_INITMENU	User has selected the extension's menu. The extension should initialize items in the menu.

FMEVENT_LOAD	File Manager is loading the extension DLL and prompts the DLL for information about the menu that the DLL supplies.

FMEVENT_SELCHANGE	Selection in the File Manager directory window or Search Results window has changed.

FMEVENT_TOOLBARLOAD	File Manager is creating the toolbar and prompts the extension DLL for information about any buttons the DLL adds to the toolbar.

FMEVENT_UNLOAD	File Manager is unloading the extension DLL.

FMEVENT_USER_REFRESH	User has chosen the Refresh command from the Window menu. The extension should update items in the menu, if necessary.


Creating the Entry-Point Function

Creating the Entry-Point Function

File Manager communicates with an extension DLL through the FMExtensionProc callback function. Make sure to export this function by listing it in the EXPORTS statement of your extension's module-definition (.DEF) file. The FMExtensionProc function handles the messages listed in the preceding section by performing the tasks listed in the following table.

Task	Action

Initializing the extension (FMEVENT_LOAD)	Provides File Manager with the name and handle of the menu and saves the menu-item delta value.

Initializing the menu (FMEVENT_INITMENU)	Initializes all top-level menu items and the items in any submenus.

Initializing the toolbar (FMEVENT_TOOLBARLOAD)	Provides File Manager with information about the buttons to add to the toolbar, including the command identifier, Help string identifier, styles, and bitmap identifier.

Processing menu selections	Carries out commands that the user chooses from the extension's menu.

Processing file selections (FMEVENT_SELCHANGE)	Queries File Manager for information about the file that the user has selected from the directory window or Search Results window.

Updating items in the menu (FMEVENT_USER_REFRESH)	Modifies the menu as appropriate when the user chooses File Manager's Refresh command from the Window menu.

Providing menu item help strings (FMEVENT_HELPSTRING)	Provides File Manager with a help string for a specified command in a specified menu. File Manager displays this string in the area at the bottom left of the window.

Passing menu item help requests on to WinHelp (FMEVENT_HELPMENUITEM)	Provides WinHelp with the window passed by File Manager and menu item information,

Quitting the extension DLL (FMEVENT_UNLOAD)	Frees any memory allocated and prepares to exit.

The FMExtensionProc function is defined as follows.

LONG WINAPI FMExtensionProc(hwnd, wMsg, lParam)

HWND hwnd;

WORD wMsg;

LONG lParam;

The hwnd parameter identifies the File Manager window. An extension should use this window handle to specify the parent window for any dialog box or message box it must display. It should also use this handle to send query messages to File Manager. The uMsg parameter contains one of the File Manager messages listed previously. The lParam parameter contains a message-dependent value. The return value from the FMExtensionProc function depends on the value of the uMsg parameter.

The menu added to File Manager may be a hierarchical (cascaded) menu and may contain grayed, disabled, or checked menu items in addition to command items. Menu items should be text only; owner-drawn menus and bitmap menus are not supported. Changing the bitmap for check marks is not supported.

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 on the part of File Manager. It is not necessary for the extension to send the FM_REFRESH_WINDOWS message to notify File Manager to repaint its directory windows. For more information about FM_REFRESH_WINDOWS, see Extension Messages.


Loading the Extension

Loading the Extension

File Manager first sends the FMEVENT_LOAD message to the FMExtensionProc function. The lParam parameter accompanying the FMEVENT_LOAD message points to an FMS_LOAD structure that File Manager uses to obtain information about the extension-supplied menu, including the menu name and menu handle.

File Manager also uses the FMS_LOAD structure to pass the menu-item delta value to the extension. To avoid conflicts with its own menu-item identifiers, File Manager renumbers the menu-item identifiers in an extension-supplied menu by adding the delta value to each identifier. An extension DLL that must modify its menu after File Manager has loaded it must use the delta value. For example, to delete a menu item, the extension DLL finds the sum of the delta value and the menu-item identifier and passes it as the idItem parameter to the DeleteMenu function.

If an extension returns FALSE in response to this message, File Manager calls the FreeLibrary function and ends any communication with the extension DLL. This is the only place where an extension can notify File Manager of initialization problems and thus prevent the extension from being loaded.


Adding Custom Buttons

Adding Custom Buttons

A File Manager extension can add custom buttons to the File Manager toolbar by returning button information in response to the FMEVENT_TOOLBARLOAD message. File Manager sends this message to the FMExtensionProc function of the extension only if the extension successfully installed a custom menu during the processing of the FMEVENT_LOAD message. Use custom buttons as accelerator keys for menu commands specified in the custom menu.

When FMExtensionProc receives the FMEVENT_TOOLBARLOAD message, the lParam parameter points to an FMS_TOOLBARLOAD structure. The File Manager extension must copy information about the custom buttons to the structure, including the number of buttons and a specifier for the bitmap containing the button images (either the identifier for a bitmap resource or a handle to a memory bitmap). The extension must also include the address of an array of EXT_BUTTON structures, each of which must contain a command identifier for the corresponding button. If the button is an accelerator for a menu command, the button identifier and corresponding menu-command identifier must be equal.

The bitmap containing the button images must be a bitmap resource or a memory bitmap. The extension must copy either the resource identifier or the memory bitmap's handle to the FMS_TOOLBARLOAD structure; and, in the case of a bitmap resource, the resource must be in the extension's executable file.

The bitmap must contain one image for each specified button. The bitmap height is always 15 pixels; the width is always a multiple of 16 pixels because each button image must be 16 pixels wide. Button images are concatenated from left to right. For example, the image of the first button specified in the array of EXT_BUTTON structures must be the leftmost image in the bitmap.

An extension can provide a line of Help text for a button by specifying the identifier of a string resource in the idsHelp member of the EXT_BUTTON structure. When the user selects the button, File Manager retrieves the string resource and displays it on the toolbar.


Processing Menu Selections

Processing Menu Selections

The menu resource that you define for your extension's menu must use menu-item identifiers in the range 1 through 99. When the user selects an item, the extension receives a command notification that is the identifier of the selected item as defined in the resource-definition file (which has the .RC filename extension). The command notification is not the sum of the delta value and the identifier. An extension DLL's FMExtensionProc function carries out commands by processing command notifications.


Initializing the Extension Menu

Initializing the Extension Menu

Whenever the user selects the extension's main menu item from File Manager's menu bar, File Manager sends the FMEVENT_INITMENU message to the extension DLL. An extension can use this message to initialize its menu items. For example, an extension can add check marks, disable items, or gray items during this message.

When the user selects submenus within the extension's menu, File Manager does not send the FMEVENT_INITMENU message. An extension DLL must initialize all items at the same time, including those in submenus.


Updating the Extension Menu

Updating the Extension Menu

When the user chooses the Refresh command from the Window menu, File Manager sends an FMEVENT_USER_REFRESH message to an extension DLL. The extension can use this opportunity to update its menu items.


Processing File Selections

Processing File Selections

When the user selects a filename in the directory window or in the Search Results window, File Manager sends the FMEVENT_SELCHANGE message to an extension DLL. The extension can use this opportunity to send a query message to File Manager to obtain more information about the user's selection. For more information, see Extension Messages.

Because the user can change the selection often, the extension should return promptly after processing the FMEVENT_SELCHANGE message to avoid slowing the user's selection process.


Quitting the Extension DLL

Quitting the Extension Dynamic-Link Library

When File Manager quits, it sends the FMEVENT_UNLOAD message to each extension DLL and then calls the FreeLibrary function to free the DLLs. Each DLL should free any memory that it has allocated.


Installing Extensions

File Manager installs extensions that have settings in the [AddOns] section of the WINFILE.INI initialization file. Each setting contains an entry and a value. An entry consists of a string that represents the name of an extension. The value assigned to the entry consists of a string that specifies the path to the extension DLL. An application can use the WritePrivateProfileString function to add a setting to WINFILE.INI. The following example shows a setting in WINFILE.INI.

[AddOns]

MyExtension=C:\NT\SYSTEM\MYEXT.DLL

File Manager does not display an error message if it cannot find an extension DLL, so an extension DLL can be deleted in order to uninstall it. Even so, an application that installs an extension DLL should provide an uninstall option to remove the extension's setting from the WINFILE.INI file.


Extension Messages

An extension can send the following window messages to retrieve relevant information from File Manager. File Manager is guaranteed to respond correctly only to messages sent from the FMExtensionProc function.

Message	Description

FM_GETDRIVEINFO	File Manager returns drive information from the active window. An extension provides a pointer to an FMS_GETDRIVEINFO structure; File Manager fills the structure with drive information.

FM_GETFILESEL	File Manager returns information about a selected file from the active File Manager window (either the directory window or the Search Results window). An extension provides a pointer to an FMS_GETFILESEL structure; File Manager fills the structure with file information.

FM_GETFILESELLFN	Same as the FM_GETFILESEL message except that the selected file may have a long filename.

FM_GETFOCUS	File Manager returns a value that identifies the type of window with input focus.

FM_GETSELCOUNT	File Manager returns the count of selected files in the directory and Search Results windows.

FM_GETSELCOUNTLFN	Same as the FM_GETSELCOUNT message except that the count includes files with long filenames.

FM_REFRESH_WINDOWS	File Manager repaints either its active window or all of its windows. This message is similar to File Manager's Refresh command on the Window menu.

FM_RELOAD_EXTENSIONS	File Manager reloads all extensions. First, File Manager unloads all extensions, sending an FMEVENT_UNLOAD message to each extension. Then, it reloads the extensions, sending an FMEVENT_LOAD message to each extension. The FM_RELOAD_EXTENSIONS message allows an extension to uninstall itself by removing its setting from the WINFILE.INI file; this action causes File Manager to reload the remaining extensions. Other applications and programs (for example, installation programs) can also post this message by calling the PostMessage function.


Processing Commands and Messages from File Manager

The following code shows the FMExtensionProc function for a sample extension DLL. It demonstrates how an extension processes the menu commands and notification messages sent by File Manager.

HINSTANCE hinst;

HMENU hmenu;

WORD wMenuDelta;

BOOL fMultiple = FALSE;

BOOL fLFN = FALSE;

LONG WINAPI FMExtensionProc(hwnd, wMsg, lParam)

HWND hwnd;

WORD wMsg;

LONG lParam;

{

    CHAR szBuf[200];

    INT count;

    switch (wMsg) {

   case FMEVENT_LOAD:

       #define lpload  ((LPFMS_LOAD) lParam)

       /* Save the menu-item delta value. */

       wMenuDelta = lpload->wMenuDelta;

       /* Fill the FMS_LOAD structure. */

       lpload->dwSize = sizeof(FMS_LOAD);

       lstrcpy(lpload->szMenuName, "&Extension");

       /* Return the handle of the menu. */

       hinst = GetModuleHandle("ext.dll");

       lpload->hMenu = GetSubMenu(LoadMenu(hinst,

      MAKEINTRESOURCE(MYMENU)), 0);

       return (LONG)TRUE;

   case FMEVENT_UNLOAD:

       /* Perform any cleanup procedures here. */

       break;

   case FMEVENT_INITMENU:

       /* Copy the menu handle. */

       hmenu = (HMENU) lParam;

       /*

             * Add check marks to menu items as appropriate.

             * Add menu-item delta values to menu-item

             * identifiers to specify the menu items to check.

        */

       CheckMenuItem(hmenu, wMenuDelta + IDM_MULTIPLE,

      fMultiple ? MF_BYCOMMAND | MF_CHECKED :

             MF_BYCOMMAND | MF_UNCHECKED);

       CheckMenuItem(hmenu, wMenuDelta + IDM_LFN,

      fLFN ? MF_BYCOMMAND | MF_CHECKED :

             MF_BYCOMMAND | MF_UNCHECKED);

       break;

   case FMEVENT_TOOLBARLOAD:

   {

       static EXT_BUTTON extbtn[] = {

          {1, 0, 0},

       };

            /* Fill the FMS_TOOLBARLOAD structure. */

       #define lptbld ((LPFMS_TOOLBARLOAD) lParam)

       lptbld->dwSize = sizeof(FMS_TOOLBARLOAD);

       lptbld->lpButtons = (LPEXT_BUTTON) &extbtn;

       lptbld->cButtons = 1;

       lptbld->cBitmaps = 1;

       lptbld->idBitmap = ID_BUTTONBITMAP;

       return (LONG)TRUE;

   }

   case FMEVENT_USER_REFRESH:

            MessageBox(hwnd, "User refresh event",

                "Hey!", MB_OK);

       break;

   case FMEVENT_SELCHANGE:

       break;

        /*

         * The following messages are generated when the user

         * chooses items from the extension menu.

         */

   case FMEVENT_HELPSTRING:

       #define lphs ((LPFMS_HELPSTRING)lParam)

       if (lphs->idCommand == -1)

          lstrcpy(lphs->szHelp, "Help for extension menu");

       else

          wsprintf(lphs->szHelp, "Help for item %d", lphs->idCommand);

       break;

   case FMEVENT_HELPMENUITEM:

       wsprintf(szBuf, "Help for %d", lParam);

       MessageBox(hwnd, szBuf, "WinHelp call", MB_OK);

       /*

        * Use: WinHelp(hwnd, "ExtHelp.hlp", HELP_CONTEXT, lParam);

        */

       break;

   case IDM_GETFOCUS:

       wsprintf(szBuf, "Focus %d", (INT) SendMessage(hwnd,

      FM_GETFOCUS, 0, 0));

       MessageBox(hwnd, szBuf, "Focus", MB_OK);

       break;

   case IDM_GETCOUNT:

       count = (INT) SendMessage(hwnd,

                fLFN ? FM_GETSELCOUNTLFN : FM_GETSELCOUNT,

                0, 0);

       wsprintf(szBuf, "%d files selected", count);

       MessageBox(hwnd, szBuf, "Selection Count", MB_OK);

       break;

   case IDM_GETFILE:

   {

       FMS_GETFILESEL file;

       count = (INT) SendMessage(hwnd,

      fLFN ? FM_GETSELCOUNTLFN : FM_GETSELCOUNT,

      FMFOCUS_DIR, 0);

       while (count >= 1) {

                /*

                 * Selection indices are zero-based (0 is

                 * first).

                 */

      count--;

      SendMessage(hwnd, FM_GETFILESEL, count,

          (LONG) (LPFMS_GETFILESEL) &file);

      wsprintf(szBuf, "file %s\nSize %ld",

          (LPSTR) file.szName, file.dwSize);

                MessageBox(hwnd, szBuf, "File Information",

                    MB_OK);

      if (!fMultiple)

         break;

       }

       break;

   }

   case IDM_GETDRIVE:

   {

       FMS_GETDRIVEINFO drive;

       SendMessage(hwnd, FM_GETDRIVEINFO, 0,

      (LONG) (LPFMS_GETDRIVEINFO)&drive);

       wsprintf(szBuf,

                "%s\nFree %ld\nTotal %ld\nVolume %s\nShare %s",

      (LPSTR) drive.szPath, drive.dwFreeSpace,

      drive.dwTotalSpace, (LPSTR) drive.szVolume,

      (LPSTR) drive.szShare);

       MessageBox(hwnd, szBuf, "Drive Info", MB_OK);

       break;

   }

   case IDM_LFN:

       MessageBox(hwnd, "IDM_LFN", "Hi", MB_OK);

       fLFN = !fLFN;

       break;

   case IDM_MULTIPLE:

       MessageBox(hwnd, "IDM_MULTIPLE", "Hi", MB_OK);

       fMultiple = !fMultiple;

       break;

   case IDM_REFRESH:

   case IDM_REFRESHALL:

       SendMessage(hwnd, FM_REFRESH_WINDOWS,

      wMsg == IDM_REFRESHALL, 0);

       break;

   case IDM_RELOAD:

       PostMessage(hwnd, FM_RELOAD_EXTENSIONS, 0, 0);

       break;

    }

    return 0L;

}


Adding the Undelete Command

File Manager supports a hook for adding an Undelete command to the File menu (below the Delete command). If an "undelete" dynamic-link library is specified in the WINFILE.INI file, File Manager adds the Undelete command to the File menu when starting. When the user chooses the Undelete command, File Manager calls the DLL.

The [settings] section of the WINFILE.INI file should include a reference to the undelete DLL, as follows.

[settings]

UNDELETE.DLL=C:\MYDIR\OTHER.DLL

An undelete DLL must include a standard entry point, the UndeleteFile function. This function must be exported by specifying the name of the function in the EXPORTS statement of the DLL's module-definition (.DEF) file.

The UndeleteFile function is defined as follows:

DWORD APIENTRY UndeleteFile(hwndParent, lpszDir)

HWND hwndParent;

LPSTR lpszDir;

The hwndParent parameter identifies the parent window for any dialog boxes the DLL creates. The lpszDir parameter specifies the initial directory to be used (for example, C:\TEMP).


Shell Dynamic Data Exchange Interface

The following topics discuss the Shell Dynamic Data Exchange Interface:

Program Manager Initialization

Terms

Settings Key

Groups Key

Restrictions Key

Command-String Interface

CreateGroup

ShowGroup

DeleteGroup

Reload

AddItem

ReplaceItem

DeleteItem

ExitProgman

Requesting Group Information


About Program Manager Initialization

This topic describes the dynamic data exchange (DDE) interface of Program Manager (PROGMAN.EXE). Program Manager is a shell--that is, an application that enables users to group, start, and otherwise control other applications for the Microsoft® Windows™ operating system.

Program Manager starts automatically when the user starts Windows and runs as long as Windows is in use. When it starts, Program Manager displays one or more windows within its main window. Each window contains icons that correspond to logically related Windows-based applications. For example, the Accessories window contains icons for Windows Write, Paintbrush, Notepad, and other accessory applications.

Program Manager stores initialization and configuration information in the registry. This information is stored under the Settings, Groups, and Restrictions keys in the following section of the registry:

HKEY_CURRENT_USER\Software\Microsoft\WindowsNT\CurrentVersion\Program Manager

Additional information is stored in the Program Groups key in the following section of the registry:

HKEY_LOCAL_MACHINE\SOFTWARE


Settings Key

The Settings key contains information that Program Manager uses to configure its environment. The following entries appear in the Settings key.

Entry	Description

MinOnRun	Specifies whether to minimize Program Manager when an application is started.

AutoArrange	Specifies whether Program Manager should automatically arrange icons within groups.

SaveSettings	Specifies whether to save the position of the Program Manager window when Program Manager terminates.

DISPLAY.DRV	Specifies the filename of the display driver in use when Program Manager last terminated. When Program Manager starts, it compares this value to the filename of the display driver currently in use. If the names are different, Program Manager re-extracts the application icons.

Window	Specifies the location and dimensions of the Program Manager window.

Order	Specifies the order that the groups listed in the Groups key appear in the Program Manager window.

Startup	Specifies the name of the startup group. Program Manager automatically starts the applications in the startup group whenever it starts.


Groups Key

The windows that appear in the Program Manager window correspond to group files. From the user's perspective, a group file is a collection of icons that represent logically related applications, but from the programmer's perspective, a group file is actually a collection of data. This data includes the color information for the icons (AND and XOR masks), an offset to the resource header of each icon, the ideal resolution for displaying each icon, the name of the executable (.EXE) file that contains the application, and so on.

There are two types of groups: common and personal. A common group is shared among multiple users through network connections; a personal group is not shared. Program Manager stores information about personal groups under the Groups key. It stores information about common groups under the HKEY_LOCAL_MACHINE\SOFTWARE key.

The Groups key of the registry identifies the names of the group files that Program Manager displays as unique windows or icons. The groups must be numbered, but they need not be listed in any particular order. Program Manager never changes the number of an existing group.


Restrictions Key

The Restrictions key controls whether certain features of Program Manager are enabled or disabled. The following entries can appear in the Restrictions key.

Entry	Description

NoRun	Specifies whether to disable the Run command on the File menu. If this entry is set to 1, the Run command is disabled. If this entry is set to 0, the Run command is enabled. The default is 0 if no value is specified.

NoClose	Specifies whether to prevent the user from closing Program Manager through the File menu, the System menu, the ALT+F4 key combination, or the Task List. If this entry is set to 1, closing is prevented. If this entry is set to 0, closing is allowed. The default is 0 if no value is specified.

EditLevel	Controls the extent to which the user can modify read-write groups. (Shared read-only groups cannot be modified.) This entry can be set to one of the following values.

Value	Action

0	Allows any modifications to the group. This is the default value.

1	Prevents the user from creating, deleting, or renaming groups.

2	Prevents the user from creating, deleting, or renaming groups and from creating or deleting items in a group.

3	Prevents the user from creating, deleting, or renaming groups; from creating or deleting items in a group; and from changing command lines for items in a group.

4	Prevents the user from changing any property of an item in a group; from creating, deleting, or renaming groups; from creating or deleting items in a group; and from changing command lines for items in a group.

NoFileMenu	Specifies whether to disable the File menu and all of its commands. If this entry is set to 1, the File menu is disabled. If this entry is set to 0, the menu is enabled. The default setting is 0 if no value is specified.

NoSaveSettings	Specifies whether to disable the Save Settings on Exit command on the Options menu. If this entry is set to 1, the Save Settings on Exit command is disabled. If this entry is set to 0, the command is enabled. The default setting is 0 if no value is specified.

Setting the value of NoRun to 1 and the value of EditLevel to 3 prevents a user from using Program Manager to run any applications not already in a program group.


Command-String Interface

Program Manager has a DDE command-string interface that allows other applications to create, display, delete, and reload groups; add items to groups; replace items in groups; delete items from groups; and close Program Manager. The following commands perform these actions:

AddItem	ExitProgman

CreateGroup	Reload

DeleteGroup	ReplaceItem

DeleteItem	ShowGroup

For example, the setup program for an application can use these commands to instruct Program Manager to install the application's icon in a group.

Multiple commands can be concatenated; each command must be contained in square brackets, and parameters must be contained in parentheses and separated by commas. Quotation marks must delimit arguments that contain spaces, brackets, or parentheses. For example, the following set of commands adds WINAPP.EXE to the Windows Applications group:

[CreateGroup("Windows Applications")]

[ShowGroup("My Group",1)]

[AddItem(winapp.exe,Win App,winapp.exe,2)]

To use these commands, an application must first initiate a DDE conversation with Program Manager. The application and topic names for the conversation are both PROGMAN. Then the application sends the WM_DDE_EXECUTE message, specifying the appropriate command and its parameters.

Note:	The user can configure Windows to use a shell other than Program Manager as the default. Therefore, do not design an application that assumes Program Manager will be available for a DDE conversation.

The following sections describe Program Manager DDE command strings in detail. In the syntax blocks in the following sections, brackets enclose optional parameters.


CreateGroup

The syntax for the CreateGroup command has this form:

CreateGroup(GroupName[,CommonGroupFlag])

The CreateGroup command instructs Program Manager to create a new group or activate the window of an existing group.

Following are the parameters for this command:

GroupName	Identifies the group to be created or activated. This parameter is a string. If a group already exists with the name specified by GroupName, CreateGroup activates the group window.

CommonGroupFlag	Specifies whether the new group is a common group or a personal group. If this parameter is 1, a common group is created; if it is 0, a personal group is created. To create a common group, the user currently logged on must have administrative privileges. If this parameter is 1 but the user does not have administrative privileges, the command fails. The default value of this parameter is 1 (common group) if no value is specified and if the user has administrative privileges. The default value is 0 (personal group) if no value is specified and the user does not have administrative privileges.

Note:	If the second parameter of the CreateGroup command specifies the path of the group file (as was required in Windows version 3.1), the parameter is ignored.


ShowGroup

The syntax for the ShowGroup command has this form:

ShowGroup(GroupName,ShowCommand[,CommonGroupFlag])

The ShowGroup command instructs Program Manager to minimize, maximize, or restore the window of an existing group.

Following are the parameters for this command:

GroupName	Identifies the group window to be minimized, maximized, or restored.

ShowCommand	Specifies the action Program Manager is to perform on the group window. This parameter is an integer. It must have one of the following values.

Value	Action

1	Activates and displays the group window. If the window is minimized or maximized, Windows restores it to its original size and position.

2	Activates the group window and displays it as an icon.

3	Activates the group window and displays it as a maximized window.

4	Displays the group window in its most recent size and position. The window that is currently active remains active.

5	Activates the group window and displays it in its current size and position.

6	Minimizes the group window.

7	Displays the group window as an icon. The currently active window remains active.

8	Displays the group window in its current state. The currently active window remains active.

CommonGroupFlag	Specifies whether the group is a common group or a personal group. If this parameter is 1, the group being minimized, maximized, or restored is a common group; if it is 0, the group is a personal group. This parameter defaults to 1 (common group) if no value is specified. To minimize, maximize, or restore a common group, the user currently logged on must have administrative privileges. If this parameter is 1 but the user does not have administrative privileges, the command fails.


DeleteGroup

The syntax for the DeleteGroup command has this form:

DeleteGroup(GroupName[,CommonGroupFlag])

The DeleteGroup command instructs Program Manager to delete an existing group.

Following are the parameters for this command:

GroupName	Identifies the group to be deleted.

CommonGroupFlag	Specifies whether the group is a common group or a personal group. If this parameter is 1, the group being deleted is a common group; if it is 0, the group is a personal group. This parameter defaults to 1 (common group) if no value is specified. To delete a common group, the user currently logged on must have administrative privileges. If this parameter is 1 but the user does not have administrative privileges, the command fails.

Note:	If the second parameter of the DeleteGroup command specifies the path of the group file (as was required in Windows version 3.1), the parameter is ignored.


Reload

The syntax for the Reload command has this form:

Reload(GroupName[,CommonGroupFlag])

The ReloadGroup command instructs Program Manager to remove and reload an existing group. An application that modifies group files can use this command to cause Program Manager to update the groups when it has finished making modifications.

Following are the parameters for this command:

GroupName	Identifies the group to be removed and reloaded. If no value is specified for the GroupName parameter, Program Manager unloads all groups and reloads the groups specified in the Groups key of the registry. The Settings and Restrictions keys are not reread.

CommonGroupFlag	Specifies whether the group is a common group or a personal group. If this parameter is 1, the group being reloaded is a common group; if it is 0, the group is a personal group. This parameter defaults to 1 (common group) if no value is specified. To reload a common group, the user currently logged on must have administrative privileges. If this parameter is 1 but the user does not have administrative privileges, the command fails.


AddItem

The syntax for the AddItem command has this form:

AddItem(CmdLine[,

    Name[,IconPath[,IconIndex[,xPos,yPos[,DefDir[,

    HotKey,[,fMinimize] ] ] ] ] ] ])

The AddItem command instructs Program Manager to add an icon to an existing group. There is a limit of 50 items per group.

Following are the parameters for this command:

CmdLine	Specifies the full command line required to run the application. This parameter is a string. At a minimum, this string is the name of the executable file for the application. It can also include the full path of the application and any parameters required by the application.

Name	Specifies the title that is displayed below the icon in the group window.

IconPath	Identifies the filename for the icon to be displayed in the group window. This parameter is a string. This file can be either a Windows-based executable file or an icon file. If no value is specified for the IconPath parameter, Program Manager uses the first icon in the file specified by the CmdLine parameter if that file is an executable file. If CmdLine specifies an associated file, Program Manager uses the first icon of the associated executable file. The association is taken from the registry. If CmdLine specifies neither an executable file nor an associated executable file, Program Manager uses a default icon.

IconIndex	Specifies the index of the icon in the file identified by the IconPath parameter. The IconIndex parameter is an integer. PROGMAN.EXE contains five built-in icons that can be used for programs not written for Windows.

xPos	Specifies the horizontal position of the icon in the group window. This parameter is an integer. Both the xPos and yPos parameters must be used to specify the position of the icon. If the position is not specified, Program Manager places the icon in the next available space.

yPos	Specifies the vertical position of the icon in the group window. This parameter is an integer. Both the xPos and yPos parameters must be used to specify the position of the icon. If the position is not specified, Program Manager places the icon in the next available space.

DefDir	Specifies the name of the default (or working) directory. This parameter is a string.

HotKey	Identifies a hot (or shortcut) key that is specified by the user.

fMinimize	Specifies whether an application window is to be minimized when first displayed.


ReplaceItem

The syntax for the ReplaceItem command has this form:

ReplaceItem(ItemName)

The ReplaceItem command instructs Program Manager to delete an item and record the position of the deleted item. Program Manager adds a new item (specified by the next AddItem command) at this recorded position.

Following is the parameter for this command:

ItemName	Specifies the item to be deleted. Its position is recorded by Program Manager.


DeleteItem

The syntax for the DeleteItem command has this form:

DeleteItem(ItemName)

The DeleteItem command instructs Program Manager to delete an item from the currently active group.

Following is the parameter for this command:

ItemName	Specifies the item to be deleted from the currently active group.


ExitProgman

The syntax for the ExitProgman command has this form:

ExitProgman(bSaveGroups)

If Program Manager was started by another application, the ExitProgman command instructs Program Manager to terminate and, optionally, save its group information.

Following is the parameter for this command:

bSaveGroups	Specifies a Boolean value that, if it is nonzero, causes Program Manager to save its group information before closing. If bSaveGroups is zero, Program Manager does not save its group information.


Requesting Group Information

Program Manager can provide information about its groups to an application. Applications can request this information from Program Manager by using the PROGMAN topic.

An application can obtain a list of Program Manager groups by issuing a request for the Group item. Program Manager provides the list in CF_TEXT format. The list consists of group-name strings separated by carriage returns.

An application can use a group name as an item name to request information about the group. Program Manager provides this information in CF_TEXT format. The fields of group information are separated by commas. The first line of the information contains the group name (in quotation marks), the path of the group file, and the number of items in the group. Each subsequent line contains information about an item in the group, including the command line (in quotation marks), the default directory, the icon path, the position in the group, the icon index, the shortcut key (in numeric form), and the minimize flag.


Interprocess Communications Options

About Interprocess Communications

As computer users become more sophisticated, they demand more power from the applications they use. To meet this demand, developers add more features to their applications, and the applications become larger. At some point, these large applications can become unmanageable, both from a development standpoint and from a user-interface point of view. Therefore, developers now tend to produce highly focused applications that do a good job on a limited number of features and then to enable those applications to communicate and share data with other specialized applications. No longer can any one application meet all user expectations; the age of cooperating and communicating applications has arrived.

The Microsoft® Win32™ application programming interface (API) provides a rich set of mechanisms for facilitating communications and data sharing between applications. Collectively, the activities enabled by these mechanisms are called interprocess communications (IPC). In addition to facilitating the division of labor among several specialized processes, some forms of IPC can distribute the computational load among cooperating computers on a network.

Typically, cooperating and communicating applications can be categorized as clients or servers. A client is an application or a process that requests a service from some other process. A server is an application or a process that responds to a client request. Many applications act as both a client and a server, depending on the situation. For example, a word processing application might act as a client in requesting a summary table of manufacturing costs from a spreadsheet application acting as a server. The spreadsheet application, in turn, might act as a client in requesting the latest inventory levels from an automated inventory control application.

Development Considerations

If a developer decides that an application would benefit from IPC, the developer must consider some of the following questions before deciding which of the available IPC methods to use:

Should the application be able to communicate with other applications running on other computers on a network, or is it sufficient for the application to communicate only with applications on the local computer? In other words, does the application need to be networkable? Some IPC methods work either on the local computer or over a network; others work only on the local computer.

Should the application be able to communicate with applications running on other computers that may be running under different operating systems (that is, MS-DOS®, Microsoft® Windows™ Version 3.x, UNIX®)? In other words, must the application be interoperable?

Should the user of the application have to choose the other application(s) with which the application communicates, or can the application implicitly find its cooperating partners?

Should the application communicate with many different applications in a general way, such as allowing cut and paste operations with any other application, or should its communications requirements be limited to a restricted set of interactions with specific other applications? Applications that communicate in a general way are called loosely coupled; applications that have a more strictly defined interaction are called tightly coupled.

Is performance a critical aspect of the application? All IPC mechanisms include some amount of communications overhead.

Should the application be a Windows-based application, or will character-mode functionalities be sufficient? Some IPC mechanisms discussed in this topic do not work in character-mode-only applications. The clipboard, dynamic data exchange (DDE), and object linking and embedding (OLE) all require that the application have at least one window.

The answers to these questions determine whether an application can benefit by using one or more of the IPC mechanisms available in the Win32 API. This topic discusses the strengths and weaknesses of each of the Win32 IPC mechanisms.

File Mapping

File mapping enables a process to treat the content of a file as if it were a block of memory in the process's address space. Therefore, instead of using file input and output (I/O) operations, the process can use simple pointer operations to examine and modify the contents of the file.

The Win32 API enables two or more processes to access the same file-mapping object. Each process receives a pointer to memory in its own address space. With this pointer, the process can read or modify the contents of the file.

There are three ways an application can share a file-mapping object created in one process with another process:

Inheritance. The first process creates the file-mapping object and then allows the handle of the object to be inherited by a child process.

Named file mapping. The first process creates the file-mapping object with a well-known name (which can be different from the filename). The second process opens the file-mapping object by specifying the well-known name. Alternatively, the first process can create a file-mapping object with a unique name and communicate that name to the second process through some other IPC mechanism (named pipe, mailslot, and so on).

Handle duplication. The first process creates the file-mapping object and then passes the handle of the object to the second process. The second process then duplicates the handle to gain access to the shared memory. The original process can communicate the file-mapping handle to the second process through one of the other IPC mechanisms described in this topic (named pipe, mailslot, and so on).

When two or more processes have read-write access to a shared memory block, they must use some sort of synchronization object, such as a semaphore, to prevent data corruption in a multitasking environment.

File mapping is quite efficient and also provides operating-system-supported security attributes that can help prevent unauthorized data corruption. File mapping can be used only between processes on a local computer; it cannot be used over a network. An application can, however, create a file-mapping object to a file on a remotely mounted volume. For example, if a remote server is mounted as the F drive, an application can create a file-mapping object to a file on that volume. However, a process running on a remote server cannot share a file-mapping object with a process running on a local computer.

Key Point:	File mapping is an efficient way for two or more processes on the same computer to share data, but the developer must provide synchronization between the processes.

Shared Memory

The Win32 API uses a special case of file mapping to provide shared memory access between processes. If you specify the system swapping file when creating a file-mapping object, the file-mapping object is treated as a shared memory block. Other processes can access the same block of memory by opening the same file-mapping object, as described in File Mapping Overview.

Because shared memory is implemented with file mapping, it supports security access attributes and can operate only between processes running on the same computer.

Key Point:	Shared memory in the Win32 API is implemented by using file mapping. All characteristics of file mapping apply to shared memory.

Anonymous Pipes

An anonymous (or unnamed) pipe enables related processes to transfer information back and forth as if they were reading from and writing to a file. Typically, anonymous pipes are used for redirecting the standard input and output (I/O) of a child process so that it can exchange data with its parent process.

To use an anonymous pipe, the parent process typically creates the pipe and then allows its read and write handles to be inherited by a child process. The parent process writes data to the pipe; the child process can read the data from the other end of the pipe. Likewise, the child process can write data to the pipe and the parent process can read the data from its end of the pipe. A parent process can also create two or more child processes that inherit the read and write handles to an anonymous pipe. Those child processes can use that pipe to communicate with each other directly, without going through the parent process.

Anonymous pipes cannot be used over a network, nor can they be used between unrelated processes. For information about a pipe mechanism that can be used with unrelated processes and over a network, see Named Pipes.

Key Point:	Anonymous pipes provide an efficient way to redirect standard I/O to child processes on the same computer.

Named Pipes

Like anonymous pipes, named pipes are used to transfer data back and forth between processes. Unlike anonymous pipes, however, named pipes can operate between unrelated processes and across a network between computers. Typically, a server process creates a named pipe with a well-known name. Client processes that can get the name of the pipe can open the other end of the pipe, subject to access restrictions specified by the pipe's creator. After they are connected, the server and client can exchange data by performing read and write operations on the pipe. Alternatively, the pipe creator can create a pipe and let a child process inherit the handle to the pipe, or it can create a pipe with a unique name and communicate that name to the client through some other IPC mechanism (such as a mailslot maintained by the client).

Key Point:	Named pipes provide a relatively simple programming interface that makes transferring data across a network no more difficult than transferring data between two processes on the same computer.

Mailslots

Mailslots provide a one-way interprocess communications capability. Any process can create a mailslot and become a mailslot server. Other processes, called mailslot clients, can gain access to the mailslot by its name and send messages to the mailslot server process. A process can be both a mailslot server and a mailslot client, so two-way IPC is possible with multiple mailslots.

Incoming messages are always appended to the mailslot. The mailslot saves the messages until the creating process has a chance to read them.

Mailslots are similar to named pipes, but with a somewhat simplified programming interface and the added ability to broadcast messages to all computers in a specified network domain. A mailslot client can send a message to a mailslot on its local computer, to a mailslot on another computer, or to all mailslots with the same name on all computers in a specified network domain. Messages broadcast to a domain can be no longer than 400 bytes; messages sent to a single mailslot are limited only by the maximum message size specified by the creator of the mailslot (which can be unlimited).

Key Point:	Mailslots offer an easy way for applications to send and receive short messages. They also provide the ability to broadcast messages across all computers in a network domain.

Clipboard

The clipboard provides a mechanism for the well-established cut-copy-paste model for simple data sharing between Windows-based applications. It enables an application to read or write data in many different standard and application-defined formats.

The clipboard acts as a central depository for data sharing among applications. When a user performs a cut or copy operation in an application, the application puts the selected data on the clipboard in one or more formats. Any other application can then retrieve the data from the clipboard, choosing from the available formats. The clipboard is a very loosely coupled exchange medium, wherein the two applications need only agree on the data format.

The clipboard mechanism works between applications on the same computer or on different computers on a network. It also works for Windows-based applications only, although 16-bit Windows 3.x applications running with the Microsoft® Windows NT™ operating system can exchange clipboard data with 32-bit applications written for Windows NT.

Key Point:	All Windows-based applications should support the clipboard for those data formats that they understand. For example, a text editor or word processor should at least be able to produce and accept clipboard data in pure text format.

Dynamic Data Exchange

Dynamic data exchange (DDE) is a protocol for interprocess communications that enables applications to exchange data in a variety of formats. Applications can use DDE for one-time data exchanges or for ongoing exchanges in which the applications update one another as new data becomes available.

The data formats used by DDE are the same as those used for the Windows clipboard IPC mechanism. DDE can be thought of as an extension of the clipboard mechanism. The clipboard is almost always used for a one-time response to a user command, such as choosing the Paste command from a menu. DDE is also usually initiated by a user command, but it often continues to function without further user interaction.

Three types of data exchange are possible with DDE:

Cold link: The exchange is a one-time data transfer, like the clipboard.

Warm link: A server notifies the client when data changes, and the client must then request new data.

Hot link: A server sends data updates to the client when data changes.

DDE exchanges can occur between applications running on the same computer or on different computers on a network.

Key Point:	Most major Windows-based applications support DDE. Like the clipboard, DDE support enables an application to exchange data in a variety of standard formats with other Windows-based applications that support DDE. A developer can also define custom DDE data formats for special-purpose IPC between applications with more tightly coupled communications requirements.

Object Linking and Embedding

Object linking and embedding (OLE) applications manage compound documents--that is, documents made up of data from a variety of different applications. OLE provides services that make it easy for applications to call on other applications for data editing. For example, an OLE-aware word processor could embed a graph from a spreadsheet. The user could start the spreadsheet automatically from within the word processor by choosing the embedded chart for editing. The OLE libraries would take care of starting the spreadsheet and presenting the graph for editing. When the user quit the spreadsheet, the graph would be updated in the original word processor document. Contrast this with a DDE link involving a spreadsheet graph in a word processor document. With DDE, the user would have to explicitly start the spreadsheet and open the graph document in order to make changes. With OLE, the spreadsheet appears to be an extension of the word processor.

Like an application using DDE, an OLE-aware application can communicate with a wide variety of other Windows-based applications. Because the OLE protocol includes all necessary context information, the application will be able to hold OLE conversations with all other OLE applications--even those that have yet to be written.

Key Point:	OLE supports compound documents and enables an application to include embedded or linked data that, when chosen, automatically starts another application for data editing. This enables the application to be extended by any other OLE-aware application.

Dynamic-Link Libraries

It is possible to build a Win32 dynamic-link library (DLL) so that its global data is shared with all processes that call the DLL. Therefore, cooperating processes can call the DLL to examine and modify global data owned by the DLL. For example, process A calls a DLL function with data that the DLL stores in its global data space. Process B calls another DLL function that retrieves that data. Of course, because of the multitasking nature of the Win32 API, the DLL would have to use a semaphore or another synchronization object to control access to the shared memory.

Although shared global data can be used in a DLL, Win32 file mapping is recommended for shared memory. File mapping is more efficient and provides the additional benefit of access protection. (For example, a client can be limited to read-only access to a file-mapping object.)

Key Point:	Although a developer can use shared global data segments in a DLL to allow two or more applications to share data, it is preferable to use Windows NT file-mapping functions to create shared memory.

Remote Procedure Call

The Win32 API provides remote procedure calls (RPC) to enable applications to call functions remotely. With RPC, communication with other processes becomes as easy as calling a function. RPC operates between processes on a single computer or on different computers on a network. One way to think of RPC is as a DLL that works on a network.

The RPC provided by the Win32 API is compliant with the Open Software Foundation (OSF) Distributed Computing Environment (DCE). This means that RPC applications written by using the Win32 API are able to communicate with other RPC applications running with other operating systems that support DCE. RPC automatically supports data conversion to account for different hardware architectures and for byte-ordering between dissimilar environments.

The Win32 development kit includes RPC libraries that support MS-DOS-hosted RPC clients. With this facility, a Windows NT server can provide service to many MS-DOS clients through RPC.

RPC clients and servers are tightly coupled but still maintain high performance. Windows NT makes extensive use of RPC to facilitate a client-server relationship between different parts of the operating system.

Key Point:	RPC provides IPC with a function interface, with support for automatic data conversion and for communications with other operating systems. Using RPC, a developer can create high-performance, tightly coupled distributed applications.

The Netbios Function

The Win32 API provides the Netbios function to process low-level network control functions. This capability is provided primarily for applications written using the IBM NetBIOS system that must be ported to Windows. It is highly recommended that a developer writing a new application use the other IPC mechanisms described in this topic rather than the low-level Netbios function. The IPC mechanisms provided in the Win32 API encapsulate and hide an enormous amount of raw NetBIOS functionality that the developer would otherwise have to implement.

Consider, for example, the following list of NetBIOS actions that would be necessary to emulate a Win32 mailslot:

On the server end

Add the name to the local table.

Listen for the session connection.

Read the data upon connection.

Append the data to the message queue.

Close the session.

Listen for another session connection.

Allow the queued messages to be retrieved.

On the client side

Open the session.

Write the data.

Close the session.

Key Point:	The Netbios function is provided only for porting an existing application written using the IBM NetBIOS system or for those applications that need specialized access to low-level network functionality. For most applications, it is better to use the higher-level IPC mechanisms available in the Win32 API.

Summary

It is likely that an application will support IPC by using several of the mechanisms described in this topic. For example, all Windows-based applications should provide at least minimal support for the clipboard. In addition, DDE and OLE may offer the application an opportunity to communicate in a loosely coupled way with a wide variety of applications that support these protocols. The great strength of these loosely coupled mechanisms is that a developer can enable an application to share data with other applications without knowing anything about the applications themselves. By supporting the protocols for the clipboard, DDE, and OLE, the developer is assured of a growing number of applications with which the application can share data. As new applications are written that support these protocols, the developer's application will be ready to communicate with them.

As an application becomes more sophisticated, a developer may find it advantageous to break up the application into tightly coupled cooperating processes that use shared memory, pipes, or RPC to communicate. These tightly coupled mechanisms can provide high-performance extensions to the application. But when adding these more specialized IPC methods, the developer should not abandon the more loosely coupled IPC methods that allow the application to share data in a general way with most other Windows-based applications.


Error Codes

Alphabetical List of Error Codes

Numerical List of Error Codes


Alphabetical List of Error Codes

Error Code	Description

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_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_ADAP_HDW_ERR

A network adapter hardware error occurred.

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_RUNNING_LKG

The system is currently running with the last-known-good configuration.

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_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_CANCEL_VIOLATION

A lock request was not outstanding for the supplied cancel region.

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_CONNECTION_UNAVAIL

The device is not currently connected but is a remembered connection.

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_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_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_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

End of tape mark was reached during an operation.

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_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_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_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_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_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_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_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_PRIMARY_GROUP

Indicates a particular Security ID cannot be assigned as the primary group of an object.

ERROR_INVALID_PRINTER_COMMAND

The printer command is invalid.

ERROR_INVALID_PRINTER_NAME

The printer name 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_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_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_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_LOGON_FAILURE

The attempted logon is invalid. This is due to either a bad username 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_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_META_EXPANSION_TOO_LONG

The global filename characters * or ? are entered incorrectly, or too many global filename characters are specified.

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_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_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_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_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_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_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_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_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_PARTITION_FAILURE

Tape could not be partitioned.

ERROR_PASSWORD_EXPIRED

The user account's password has expired.

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_POSSIBLE_DEADLOCK

A potential deadlock condition has been detected.

ERROR_PRINT_CANCELLED

File waiting to be printed was deleted.

ERROR_PRINTER_ALREADY_EXISTS

The printer already exists.

ERROR_PRINTER_DRIVER_ALREADY_INSTALLED

The specified printer driver is already installed.

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_READ_FAULT

The system cannot read from the specified device.

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_NOT_ENOUGH_QUOTA

Not enough quota is available to process this command.

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_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_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 an 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_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_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_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_STACK_OVERFLOW

Recursion too deep, stack overflowed.

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_SWAPERROR

Error accessing paging file.

ERROR_SYSTEM_TRACE

System trace information not specified in your CONFIG.SYS file, or tracing is not allowed.

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

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_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_BIND

An attempt to bind with the server failed.

RPC_S_CANNOT_SUPPORT

The requested operation is not supported.

RPC_S_CANT_CREATE_ENDPOINT

The endpoint cannot be created.

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_NAF_IF

The network address family 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_INTERFACES_EXPORTED

No interfaces were exported.

RPC_S_NO_MORE_BINDINGS

There are no more bindings.

RPC_S_NO_MORE_MEMBERS

There are no more members.

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_NOTHING_TO_UNEXPORT

There is nothing to unexport.

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_SERVER_NOT_LISTENING

The server is not listening for remote procedure calls.

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


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

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

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

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

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

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

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

1729L RPC_S_CANNOT_BIND

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

1738L RPC_S_SERVER_NOT_LISTENING

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

1754L RPC_S_NO_INTERFACES_EXPORTED

1755L RPC_S_INCOMPLETE_NAME

1756L RPC_S_INVALID_VERS_OPTION

1757L RPC_S_NO_MORE_MEMBERS

1758L RPC_S_NOTHING_TO_UNEXPORT

1759L RPC_S_INTERFACE_NOT_FOUND

1760L RPC_S_ENTRY_ALREADY_EXISTS

1761L RPC_S_ENTRY_NOT_FOUND

1762L RPC_S_NAME_SERVICE_UNAVAILABLE

1763L RPC_S_INVALID_NAF_IF

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

1898L RPC_S_GROUP_MEMBER_NOT_FOUND

1899L EPT_S_CANT_CREATE

1900L RPC_S_INVALID_OBJECT

2138L ERROR_NO_NETWORK

2202L ERROR_BAD_USERNAME

2250L ERROR_NOT_CONNECTED

2401L ERROR_OPEN_FILES

2404L ERROR_DEVICE_IN_USE

6118L ERROR_NO_BROWSER_SERVERS_FOUND


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
ERROR_ACCESS_DENIED  5L  winerror.h

Access is denied.


FN_ERROR_ACCESS_DENIED
ERROR_ACCESS_DENIED  5L  winerror.h


ERROR_ACCOUNT_DISABLED
ERROR_ACCOUNT_DISABLED  1331L  winerror.h

The referenced account is currently disabled and cannot be logged on to.


FN_ERROR_ACCOUNT_DISABLED
ERROR_ACCOUNT_DISABLED  1331L  winerror.h


ERROR_ACCOUNT_EXPIRED
ERROR_ACCOUNT_EXPIRED  1793L  winerror.h

The user's account has expired.


FN_ERROR_ACCOUNT_EXPIRED
ERROR_ACCOUNT_EXPIRED  1793L  winerror.h


ERROR_ACCOUNT_RESTRICTION
ERROR_ACCOUNT_RESTRICTION  1327L  winerror.h

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


FN_ERROR_ACCOUNT_RESTRICTION
ERROR_ACCOUNT_RESTRICTION  1327L  winerror.h


ERROR_ADAP_HDW_ERR
ERROR_ADAP_HDW_ERR  57L  winerror.h

A network adapter hardware error occurred.


FN_ERROR_ADAP_HDW_ERR
ERROR_ADAP_HDW_ERR  57L  winerror.h


ERROR_ALIAS_EXISTS
ERROR_ALIAS_EXISTS  1379L  winerror.h

The specified alias already exists.


FN_ERROR_ALIAS_EXISTS
ERROR_ALIAS_EXISTS  1379L  winerror.h


ERROR_ALLOTTED_SPACE_EXCEEDED
ERROR_ALLOTTED_SPACE_EXCEEDED  1344L  winerror.h

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.


FN_ERROR_ALLOTTED_SPACE_EXCEEDED
ERROR_ALLOTTED_SPACE_EXCEEDED  1344L  winerror.h


ERROR_ALREADY_ASSIGNED
ERROR_ALREADY_ASSIGNED  85L  winerror.h

The local device name is already in use.


FN_ERROR_ALREADY_ASSIGNED
ERROR_ALREADY_ASSIGNED  85L  winerror.h


ERROR_ALREADY_EXISTS
ERROR_ALREADY_EXISTS  183L  winerror.h

Attempt to create file that already exists.


FN_ERROR_ALREADY_EXISTS
ERROR_ALREADY_EXISTS  183L  winerror.h


ERROR_ALREADY_RUNNING_LKG
ERROR_ALREADY_RUNNING_LKG  1074L  winerror.h

The system is currently running with the last-known-good configuration.


FN_ERROR_ALREADY_RUNNING_LKG
ERROR_ALREADY_RUNNING_LKG  1074L  winerror.h


ERROR_ARENA_TRASHED
ERROR_ARENA_TRASHED  7L  winerror.h

The storage control blocks were destroyed.


FN_ERROR_ARENA_TRASHED
ERROR_ARENA_TRASHED  7L  winerror.h


ERROR_ARITHMETIC_OVERFLOW
ERROR_ARITHMETIC_OVERFLOW  534L  winerror.h

Arithmetic result exceeded 32-bits.


FN_ERROR_ARITHMETIC_OVERFLOW
ERROR_ARITHMETIC_OVERFLOW  534L  winerror.h


ERROR_ATOMIC_LOCKS_NOT_SUPPORTED
ERROR_ATOMIC_LOCKS_NOT_SUPPORTED  174L  winerror.h

The file system does not support atomic changing of the lock type.


FN_ERROR_ATOMIC_LOCKS_NOT_SUPPORTED
ERROR_ATOMIC_LOCKS_NOT_SUPPORTED  174L  winerror.h


ERROR_AUTODATASEG_EXCEEDS_64k
ERROR_AUTODATASEG_EXCEEDS_64k  199L  winerror.h

The operating system cannot run this application program.


FN_ERROR_AUTODATASEG_EXCEEDS_64k
ERROR_AUTODATASEG_EXCEEDS_64k  199L  winerror.h


ERROR_BAD_ARGUMENTS
ERROR_BAD_ARGUMENTS  160L  winerror.h

The argument string passed to DosExecPgm is incorrect.


FN_ERROR_BAD_ARGUMENTS
ERROR_BAD_ARGUMENTS  160L  winerror.h


ERROR_BAD_COMMAND
ERROR_BAD_COMMAND  22L  winerror.h

The device does not recognize the command.


FN_ERROR_BAD_COMMAND
ERROR_BAD_COMMAND  22L  winerror.h


ERROR_BAD_DESCRIPTOR_FORMAT
ERROR_BAD_DESCRIPTOR_FORMAT  1361L  winerror.h

Indicates a security descriptor is not in the required format (absolute or self-relative).


FN_ERROR_BAD_DESCRIPTOR_FORMAT
ERROR_BAD_DESCRIPTOR_FORMAT  1361L  winerror.h


ERROR_BAD_DEV_TYPE
ERROR_BAD_DEV_TYPE  66L  winerror.h

The network resource type is incorrect.


FN_ERROR_BAD_DEV_TYPE
ERROR_BAD_DEV_TYPE  66L  winerror.h


ERROR_BAD_DEVICE
ERROR_BAD_DEVICE  1200L  winerror.h

The specified device name is invalid.


FN_ERROR_BAD_DEVICE
ERROR_BAD_DEVICE  1200L  winerror.h


ERROR_BAD_DRIVER_LEVEL
ERROR_BAD_DRIVER_LEVEL  119L  winerror.h

The system does not support the requested command.


FN_ERROR_BAD_DRIVER_LEVEL
ERROR_BAD_DRIVER_LEVEL  119L  winerror.h


ERROR_BAD_ENVIRONMENT
ERROR_BAD_ENVIRONMENT  10L  winerror.h

The environment is incorrect.


FN_ERROR_BAD_ENVIRONMENT
ERROR_BAD_ENVIRONMENT  10L  winerror.h


ERROR_BAD_EXE_FORMAT
ERROR_BAD_EXE_FORMAT  193L  winerror.h

%1 is not a valid Windows-based application.


FN_ERROR_BAD_EXE_FORMAT
ERROR_BAD_EXE_FORMAT  193L  winerror.h


ERROR_BAD_FORMAT
ERROR_BAD_FORMAT  11L  winerror.h

An attempt was made to load a program with an incorrect format.


FN_ERROR_BAD_FORMAT
ERROR_BAD_FORMAT  11L  winerror.h


ERROR_BAD_IMPERSONATION_LEVEL
ERROR_BAD_IMPERSONATION_LEVEL  1346L  winerror.h

A specified impersonation level is invalid. Also used to indicate a required impersonation level was not provided.


FN_ERROR_BAD_IMPERSONATION_LEVEL
ERROR_BAD_IMPERSONATION_LEVEL  1346L  winerror.h


ERROR_BAD_INHERITANCE_ACL
ERROR_BAD_INHERITANCE_ACL  1340L  winerror.h

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.


FN_ERROR_BAD_INHERITANCE_ACL
ERROR_BAD_INHERITANCE_ACL  1340L  winerror.h


ERROR_BAD_LENGTH
ERROR_BAD_LENGTH  24L  winerror.h

The program issued a command but the command length is incorrect.


FN_ERROR_BAD_LENGTH
ERROR_BAD_LENGTH  24L  winerror.h


ERROR_BAD_LOGON_SESSION_STATE
ERROR_BAD_LOGON_SESSION_STATE  1365L  winerror.h

The logon session is not in a state consistent with the requested operation.


FN_ERROR_BAD_LOGON_SESSION_STATE
ERROR_BAD_LOGON_SESSION_STATE  1365L  winerror.h


ERROR_BAD_NET_NAME
ERROR_BAD_NET_NAME  67L  winerror.h

The network name cannot be found.


FN_ERROR_BAD_NET_NAME
ERROR_BAD_NET_NAME  67L  winerror.h


ERROR_BAD_NET_RESP
ERROR_BAD_NET_RESP  58L  winerror.h

The specified server cannot perform the requested operation.


FN_ERROR_BAD_NET_RESP
ERROR_BAD_NET_RESP  58L  winerror.h


ERROR_BAD_NETPATH
ERROR_BAD_NETPATH  53L  winerror.h

The network path was not found.


FN_ERROR_BAD_NETPATH
ERROR_BAD_NETPATH  53L  winerror.h


ERROR_BAD_PATHNAME
ERROR_BAD_PATHNAME  161L  winerror.h

The specified path name is invalid.


FN_ERROR_BAD_PATHNAME
ERROR_BAD_PATHNAME  161L  winerror.h


ERROR_BAD_PIPE
ERROR_BAD_PIPE  230L  winerror.h

The pipe state is invalid.


FN_ERROR_BAD_PIPE
ERROR_BAD_PIPE  230L  winerror.h


ERROR_BAD_PROFILE
ERROR_BAD_PROFILE  1206L  winerror.h

The network connection profile is damaged.


FN_ERROR_BAD_PROFILE
ERROR_BAD_PROFILE  1206L  winerror.h


ERROR_BAD_PROVIDER
ERROR_BAD_PROVIDER  1204L  winerror.h

The specified network provider name is invalid.


FN_ERROR_BAD_PROVIDER
ERROR_BAD_PROVIDER  1204L  winerror.h


ERROR_BAD_REM_ADAP
ERROR_BAD_REM_ADAP  60L  winerror.h

The remote adapter is not compatible.


FN_ERROR_BAD_REM_ADAP
ERROR_BAD_REM_ADAP  60L  winerror.h


ERROR_BAD_THREADID_ADDR
ERROR_BAD_THREADID_ADDR  159L  winerror.h

The address for the thread ID is incorrect.


FN_ERROR_BAD_THREADID_ADDR
ERROR_BAD_THREADID_ADDR  159L  winerror.h


ERROR_BAD_TOKEN_TYPE
ERROR_BAD_TOKEN_TYPE  1349L  winerror.h

The type of token object is inappropriate for its attempted use.


FN_ERROR_BAD_TOKEN_TYPE
ERROR_BAD_TOKEN_TYPE  1349L  winerror.h


ERROR_BAD_UNIT
ERROR_BAD_UNIT  20L  winerror.h

The system cannot find the specified device.


FN_ERROR_BAD_UNIT
ERROR_BAD_UNIT  20L  winerror.h


ERROR_BAD_USERNAME
ERROR_BAD_USERNAME  2202L  winerror.h

The specified user name is invalid.


FN_ERROR_BAD_USERNAME
ERROR_BAD_USERNAME  2202L  winerror.h


ERROR_BAD_VALIDATION_CLASS
ERROR_BAD_VALIDATION_CLASS  1348L  winerror.h

The requested validation information class is invalid.


FN_ERROR_BAD_VALIDATION_CLASS
ERROR_BAD_VALIDATION_CLASS  1348L  winerror.h


ERROR_BADDB
ERROR_BADDB  1009L  winerror.h

The configuration registry database is damaged.


FN_ERROR_BADDB
ERROR_BADDB  1009L  winerror.h


ERROR_BADKEY
ERROR_BADKEY  1010L  winerror.h

The configuration registry key is invalid.


FN_ERROR_BADKEY
ERROR_BADKEY  1010L  winerror.h


ERROR_BEGINNING_OF_MEDIA
ERROR_BEGINNING_OF_MEDIA  1102L  winerror.h

The beginning of the tape or partition was encountered.


FN_ERROR_BEGINNING_OF_MEDIA
ERROR_BEGINNING_OF_MEDIA  1102L  winerror.h


ERROR_BOOT_ALREADY_ACCEPTED
ERROR_BOOT_ALREADY_ACCEPTED  1076L  winerror.h

The current boot has already been accepted for use as the last-known-good control set.


FN_ERROR_BOOT_ALREADY_ACCEPTED
ERROR_BOOT_ALREADY_ACCEPTED  1076L  winerror.h


ERROR_BROKEN_PIPE
ERROR_BROKEN_PIPE  109L  winerror.h

The pipe was ended.


FN_ERROR_BROKEN_PIPE
ERROR_BROKEN_PIPE  109L  winerror.h


ERROR_BUFFER_OVERFLOW
ERROR_BUFFER_OVERFLOW  111L  winerror.h

The file name is too long.


FN_ERROR_BUFFER_OVERFLOW
ERROR_BUFFER_OVERFLOW  111L  winerror.h


ERROR_BUS_RESET
ERROR_BUS_RESET  1111L  winerror.h

The I/O bus was reset.


FN_ERROR_BUS_RESET
ERROR_BUS_RESET  1111L  winerror.h


ERROR_BUSY
ERROR_BUSY  170L  winerror.h

The requested resource is in use.


FN_ERROR_BUSY
ERROR_BUSY  170L  winerror.h


ERROR_BUSY_DRIVE
ERROR_BUSY_DRIVE  142L  winerror.h

The system cannot perform a JOIN or SUBST at this time.


FN_ERROR_BUSY_DRIVE
ERROR_BUSY_DRIVE  142L  winerror.h


ERROR_CALL_NOT_IMPLEMENTED
ERROR_CALL_NOT_IMPLEMENTED  120L  winerror.h

The Application Program Interface (API) entered will only work in Windows/NT mode.


FN_ERROR_CALL_NOT_IMPLEMENTED
ERROR_CALL_NOT_IMPLEMENTED  120L  winerror.h


ERROR_CAN_NOT_COMPLETE
ERROR_CAN_NOT_COMPLETE  1003L  winerror.h

Cannot complete function for some reason.


FN_ERROR_CAN_NOT_COMPLETE
ERROR_CAN_NOT_COMPLETE  1003L  winerror.h


ERROR_CANCEL_VIOLATION
ERROR_CANCEL_VIOLATION  173L  winerror.h

A lock request was not outstanding for the supplied cancel region.


FN_ERROR_CANCEL_VIOLATION
ERROR_CANCEL_VIOLATION  173L  winerror.h


ERROR_CANNOT_COPY
ERROR_CANNOT_COPY  266L  winerror.h

The Copy API cannot be used.


FN_ERROR_CANNOT_COPY
ERROR_CANNOT_COPY  266L  winerror.h


ERROR_CANNOT_FIND_WND_CLASS
ERROR_CANNOT_FIND_WND_CLASS  1407L  winerror.h

Cannot find window class.


FN_ERROR_CANNOT_FIND_WND_CLASS
ERROR_CANNOT_FIND_WND_CLASS  1407L  winerror.h


ERROR_CANNOT_IMPERSONATE
ERROR_CANNOT_IMPERSONATE  1368L  winerror.h

Indicates that an attempt was made to impersonate via a named pipe was not yet read from.


FN_ERROR_CANNOT_IMPERSONATE
ERROR_CANNOT_IMPERSONATE  1368L  winerror.h


ERROR_CANNOT_MAKE
ERROR_CANNOT_MAKE  82L  winerror.h

The directory or file cannot be created.


FN_ERROR_CANNOT_MAKE
ERROR_CANNOT_MAKE  82L  winerror.h


ERROR_CANNOT_OPEN_PROFILE
ERROR_CANNOT_OPEN_PROFILE  1205L  winerror.h

Unable to open the network connection profile.


FN_ERROR_CANNOT_OPEN_PROFILE
ERROR_CANNOT_OPEN_PROFILE  1205L  winerror.h


ERROR_CANT_ACCESS_DOMAIN_INFO
ERROR_CANT_ACCESS_DOMAIN_INFO  1351L  winerror.h

Indicates a domain controller could not be contacted or that objects within the domain are protected and necessary information could not be retrieved.


FN_ERROR_CANT_ACCESS_DOMAIN_INFO
ERROR_CANT_ACCESS_DOMAIN_INFO  1351L  winerror.h


ERROR_CANT_DISABLE_MANDATORY
ERROR_CANT_DISABLE_MANDATORY  1310L  winerror.h

A mandatory group cannot be disabled.


FN_ERROR_CANT_DISABLE_MANDATORY
ERROR_CANT_DISABLE_MANDATORY  1310L  winerror.h


ERROR_CANT_OPEN_ANONYMOUS
ERROR_CANT_OPEN_ANONYMOUS  1347L  winerror.h

An attempt was made to open an anonymous level token. Anonymous tokens cannot be opened.


FN_ERROR_CANT_OPEN_ANONYMOUS
ERROR_CANT_OPEN_ANONYMOUS  1347L  winerror.h


ERROR_CANTOPEN
ERROR_CANTOPEN  1011L  winerror.h

The configuration registry key cannot be opened.


FN_ERROR_CANTOPEN
ERROR_CANTOPEN  1011L  winerror.h


ERROR_CANTREAD
ERROR_CANTREAD  1012L  winerror.h

The configuration registry key cannot be read.


FN_ERROR_CANTREAD
ERROR_CANTREAD  1012L  winerror.h


ERROR_CANTWRITE
ERROR_CANTWRITE  1013L  winerror.h

The configuration registry key cannot be written.


FN_ERROR_CANTWRITE
ERROR_CANTWRITE  1013L  winerror.h


ERROR_CHILD_MUST_BE_VOLATILE
ERROR_CHILD_MUST_BE_VOLATILE  1021L  winerror.h

An attempt was made to create a stable subkey under a volatile parent key.


FN_ERROR_CHILD_MUST_BE_VOLATILE
ERROR_CHILD_MUST_BE_VOLATILE  1021L  winerror.h


ERROR_CHILD_NOT_COMPLETE
ERROR_CHILD_NOT_COMPLETE  129L  winerror.h

The %1 application cannot be run in Windows mode.


FN_ERROR_CHILD_NOT_COMPLETE
ERROR_CHILD_NOT_COMPLETE  129L  winerror.h


ERROR_CHILD_WINDOW_MENU
ERROR_CHILD_WINDOW_MENU  1436L  winerror.h

Child windows can't have menus.


FN_ERROR_CHILD_WINDOW_MENU
ERROR_CHILD_WINDOW_MENU  1436L  winerror.h


ERROR_CIRCULAR_DEPENDENCY
ERROR_CIRCULAR_DEPENDENCY  1059L  winerror.h

Circular service dependency was specified.


FN_ERROR_CIRCULAR_DEPENDENCY
ERROR_CIRCULAR_DEPENDENCY  1059L  winerror.h


ERROR_CLASS_ALREADY_EXISTS
ERROR_CLASS_ALREADY_EXISTS  1410L  winerror.h

Class already exists.


FN_ERROR_CLASS_ALREADY_EXISTS
ERROR_CLASS_ALREADY_EXISTS  1410L  winerror.h


ERROR_CLASS_DOES_NOT_EXIST
ERROR_CLASS_DOES_NOT_EXIST  1411L  winerror.h

Class does not exist.


FN_ERROR_CLASS_DOES_NOT_EXIST
ERROR_CLASS_DOES_NOT_EXIST  1411L  winerror.h


ERROR_CLASS_HAS_WINDOWS
ERROR_CLASS_HAS_WINDOWS  1412L  winerror.h

Class still has open windows.


FN_ERROR_CLASS_HAS_WINDOWS
ERROR_CLASS_HAS_WINDOWS  1412L  winerror.h


ERROR_CLIPBOARD_NOT_OPEN
ERROR_CLIPBOARD_NOT_OPEN  1418L  winerror.h

Thread doesn't have clipboard open.


FN_ERROR_CLIPBOARD_NOT_OPEN
ERROR_CLIPBOARD_NOT_OPEN  1418L  winerror.h


ERROR_CONNECTION_UNAVAIL
ERROR_CONNECTION_UNAVAIL  1201L  winerror.h

The device is not currently connected but is a remembered connection.


FN_ERROR_CONNECTION_UNAVAIL
ERROR_CONNECTION_UNAVAIL  1201L  winerror.h


ERROR_CONTROL_ID_NOT_FOUND
ERROR_CONTROL_ID_NOT_FOUND  1421L  winerror.h

Control ID not found.


FN_ERROR_CONTROL_ID_NOT_FOUND
ERROR_CONTROL_ID_NOT_FOUND  1421L  winerror.h


ERROR_COUNTER_TIMEOUT
ERROR_COUNTER_TIMEOUT  1121L  winerror.h

A serial I/O operation completed because the time-out period expired. (The IOCTL_SERIAL_XOFF_COUNTER did not reach zero.)


FN_ERROR_COUNTER_TIMEOUT
ERROR_COUNTER_TIMEOUT  1121L  winerror.h


ERROR_CRC
ERROR_CRC  23L  winerror.h

Data error (cyclic redundancy check).


FN_ERROR_CRC
ERROR_CRC  23L  winerror.h


ERROR_CURRENT_DIRECTORY
ERROR_CURRENT_DIRECTORY  16L  winerror.h

The directory cannot be removed.


FN_ERROR_CURRENT_DIRECTORY
ERROR_CURRENT_DIRECTORY  16L  winerror.h


ERROR_DATABASE_DOES_NOT_EXIST
ERROR_DATABASE_DOES_NOT_EXIST  1065L  winerror.h

The database specified does not exist.


FN_ERROR_DATABASE_DOES_NOT_EXIST
ERROR_DATABASE_DOES_NOT_EXIST  1065L  winerror.h


ERROR_DC_NOT_FOUND
ERROR_DC_NOT_FOUND  1425L  winerror.h

Invalid HDC passed to ReleaseDC.


FN_ERROR_DC_NOT_FOUND
ERROR_DC_NOT_FOUND  1425L  winerror.h


ERROR_DEPENDENT_SERVICES_RUNNING
ERROR_DEPENDENT_SERVICES_RUNNING  1051L  winerror.h

A stop control has been sent to a service which other running services are dependent on.


FN_ERROR_DEPENDENT_SERVICES_RUNNING
ERROR_DEPENDENT_SERVICES_RUNNING  1051L  winerror.h


ERROR_DESTROY_OBJECT_OF_OTHER_THREAD
ERROR_DESTROY_OBJECT_OF_OTHER_THREAD  1435L  winerror.h

Cannot destroy object created by another thread.


FN_ERROR_DESTROY_OBJECT_OF_OTHER_THREAD
ERROR_DESTROY_OBJECT_OF_OTHER_THREAD  1435L  winerror.h


ERROR_DEV_NOT_EXIST
ERROR_DEV_NOT_EXIST  55L  winerror.h

The specified network resource is no longer available.


FN_ERROR_DEV_NOT_EXIST
ERROR_DEV_NOT_EXIST  55L  winerror.h


ERROR_DEVICE_ALREADY_REMEMBERED
ERROR_DEVICE_ALREADY_REMEMBERED  1202L  winerror.h

An attempt was made to remember a device that was previously remembered.


FN_ERROR_DEVICE_ALREADY_REMEMBERED
ERROR_DEVICE_ALREADY_REMEMBERED  1202L  winerror.h


ERROR_DEVICE_IN_USE
ERROR_DEVICE_IN_USE  2404L  winerror.h

The device is in use by an active process and cannot be disconnected.


FN_ERROR_DEVICE_IN_USE
ERROR_DEVICE_IN_USE  2404L  winerror.h


ERROR_DEVICE_NOT_PARTITIONED
ERROR_DEVICE_NOT_PARTITIONED  1107L  winerror.h

Tape partition information could not be found when loading a tape.


FN_ERROR_DEVICE_NOT_PARTITIONED
ERROR_DEVICE_NOT_PARTITIONED  1107L  winerror.h


ERROR_DIR_NOT_EMPTY
ERROR_DIR_NOT_EMPTY  145L  winerror.h

The directory is not empty.


FN_ERROR_DIR_NOT_EMPTY
ERROR_DIR_NOT_EMPTY  145L  winerror.h


ERROR_DIR_NOT_ROOT
ERROR_DIR_NOT_ROOT  144L  winerror.h

The directory is not a subdirectory of the root directory.


FN_ERROR_DIR_NOT_ROOT
ERROR_DIR_NOT_ROOT  144L  winerror.h


ERROR_DIRECT_ACCESS_HANDLE
ERROR_DIRECT_ACCESS_HANDLE  130L  winerror.h

Attempt to use a file handle to an open disk partition for an operation other than raw disk I/O.


FN_ERROR_DIRECT_ACCESS_HANDLE
ERROR_DIRECT_ACCESS_HANDLE  130L  winerror.h


ERROR_DIRECTORY
ERROR_DIRECTORY  267L  winerror.h

The directory name is invalid.


FN_ERROR_DIRECTORY
ERROR_DIRECTORY  267L  winerror.h


ERROR_DISCARDED
ERROR_DISCARDED  157L  winerror.h

The segment is already discarded and cannot be locked.


FN_ERROR_DISCARDED
ERROR_DISCARDED  157L  winerror.h


ERROR_DISK_CHANGE
ERROR_DISK_CHANGE  107L  winerror.h

Program stopped because alternate disk was not inserted.


FN_ERROR_DISK_CHANGE
ERROR_DISK_CHANGE  107L  winerror.h


ERROR_DISK_CORRUPT
ERROR_DISK_CORRUPT  1393L  winerror.h

The disk structure is damaged and nonreadable.


FN_ERROR_DISK_CORRUPT
ERROR_DISK_CORRUPT  1393L  winerror.h


ERROR_DISK_FULL
ERROR_DISK_FULL  112L  winerror.h

There is not enough space on the disk.


FN_ERROR_DISK_FULL
ERROR_DISK_FULL  112L  winerror.h


ERROR_DISK_OPERATION_FAILED
ERROR_DISK_OPERATION_FAILED  1127L  winerror.h

While accessing the hard disk, a disk operation failed even after retries.


FN_ERROR_DISK_OPERATION_FAILED
ERROR_DISK_OPERATION_FAILED  1127L  winerror.h


ERROR_DISK_RECALIBRATE_FAILED
ERROR_DISK_RECALIBRATE_FAILED  1126L  winerror.h

While accessing the hard disk, a recalibrate operation failed, even after retries.


FN_ERROR_DISK_RECALIBRATE_FAILED
ERROR_DISK_RECALIBRATE_FAILED  1126L  winerror.h


ERROR_DISK_RESET_FAILED
ERROR_DISK_RESET_FAILED  1128L  winerror.h

While accessing the hard disk, a disk controller reset was needed, but even that failed.


FN_ERROR_DISK_RESET_FAILED
ERROR_DISK_RESET_FAILED  1128L  winerror.h


ERROR_DLL_INIT_FAILED
ERROR_DLL_INIT_FAILED  1114L  winerror.h

A DLL initialization routine failed.


FN_ERROR_DLL_INIT_FAILED
ERROR_DLL_INIT_FAILED  1114L  winerror.h


ERROR_DOMAIN_EXISTS
ERROR_DOMAIN_EXISTS  1356L  winerror.h

The specified domain already exists.


FN_ERROR_DOMAIN_EXISTS
ERROR_DOMAIN_EXISTS  1356L  winerror.h


ERROR_DOMAIN_LIMIT_EXCEEDED
ERROR_DOMAIN_LIMIT_EXCEEDED  1357L  winerror.h

An attempt to exceed the limit on the number of domains per server for this release.


FN_ERROR_DOMAIN_LIMIT_EXCEEDED
ERROR_DOMAIN_LIMIT_EXCEEDED  1357L  winerror.h


ERROR_DOMAIN_TRUST_INCONSISTENT
ERROR_DOMAIN_TRUST_INCONSISTENT  1810L  winerror.h

The name or security ID (SID) of the domain specified is inconsistent with the trust information for that domain.


FN_ERROR_DOMAIN_TRUST_INCONSISTENT
ERROR_DOMAIN_TRUST_INCONSISTENT  1810L  winerror.h


ERROR_DRIVE_LOCKED
ERROR_DRIVE_LOCKED  108L  winerror.h

The disk is in use or locked by another process.


FN_ERROR_DRIVE_LOCKED
ERROR_DRIVE_LOCKED  108L  winerror.h


ERROR_DUP_DOMAINNAME
ERROR_DUP_DOMAINNAME  1221L  winerror.h

The workgroup or domain name is already in use by another computer on the network.


FN_ERROR_DUP_DOMAINNAME
ERROR_DUP_DOMAINNAME  1221L  winerror.h


ERROR_DUP_NAME
ERROR_DUP_NAME  52L  winerror.h

A duplicate name exists on the network.


FN_ERROR_DUP_NAME
ERROR_DUP_NAME  52L  winerror.h


ERROR_DUPLICATE_SERVICE_NAME
ERROR_DUPLICATE_SERVICE_NAME  1078L  winerror.h

The name is already in use as either a service name or a service display name.


FN_ERROR_DUPLICATE_SERVICE_NAME
ERROR_DUPLICATE_SERVICE_NAME  1078L  winerror.h


ERROR_DYNLINK_FROM_INVALID_RING
ERROR_DYNLINK_FROM_INVALID_RING  196L  winerror.h

The operating system cannot run this application program.


FN_ERROR_DYNLINK_FROM_INVALID_RING
ERROR_DYNLINK_FROM_INVALID_RING  196L  winerror.h


ERROR_EA_ACCESS_DENIED
ERROR_EA_ACCESS_DENIED  994L  winerror.h

Access to the EA is denied.


FN_ERROR_EA_ACCESS_DENIED
ERROR_EA_ACCESS_DENIED  994L  winerror.h


ERROR_EA_FILE_CORRUPT
ERROR_EA_FILE_CORRUPT  276L  winerror.h

The EA file on the mounted file system is damaged.


FN_ERROR_EA_FILE_CORRUPT
ERROR_EA_FILE_CORRUPT  276L  winerror.h


ERROR_EA_LIST_INCONSISTENT
ERROR_EA_LIST_INCONSISTENT  255L  winerror.h

The EAs are inconsistent.


FN_ERROR_EA_LIST_INCONSISTENT
ERROR_EA_LIST_INCONSISTENT  255L  winerror.h


ERROR_EA_TABLE_FULL
ERROR_EA_TABLE_FULL  277L  winerror.h

The EA table in the EA file on the mounted file system is full.


FN_ERROR_EA_TABLE_FULL
ERROR_EA_TABLE_FULL  277L  winerror.h


ERROR_EAS_DIDNT_FIT
ERROR_EAS_DIDNT_FIT  275L  winerror.h

The EAs did not fit in the buffer.


FN_ERROR_EAS_DIDNT_FIT
ERROR_EAS_DIDNT_FIT  275L  winerror.h


ERROR_EAS_NOT_SUPPORTED
ERROR_EAS_NOT_SUPPORTED  282L  winerror.h

The mounted file system does not support extended attributes.


FN_ERROR_EAS_NOT_SUPPORTED
ERROR_EAS_NOT_SUPPORTED  282L  winerror.h


ERROR_END_OF_MEDIA
ERROR_END_OF_MEDIA  1100L  winerror.h

End of tape mark was reached during an operation.


FN_ERROR_END_OF_MEDIA
ERROR_END_OF_MEDIA  1100L  winerror.h


ERROR_ENVVAR_NOT_FOUND
ERROR_ENVVAR_NOT_FOUND  203L  winerror.h

The system could not find the environment option entered.


FN_ERROR_ENVVAR_NOT_FOUND
ERROR_ENVVAR_NOT_FOUND  203L  winerror.h


ERROR_EOM_OVERFLOW
ERROR_EOM_OVERFLOW  1129L  winerror.h

Physical end of tape encountered.


FN_ERROR_EOM_OVERFLOW
ERROR_EOM_OVERFLOW  1129L  winerror.h


ERROR_EVENTLOG_CANT_START
ERROR_EVENTLOG_CANT_START  1501L  winerror.h

No event log file could be opened, so the event logging service did not start.


FN_ERROR_EVENTLOG_CANT_START
ERROR_EVENTLOG_CANT_START  1501L  winerror.h


ERROR_EVENTLOG_FILE_CHANGED
ERROR_EVENTLOG_FILE_CHANGED  1503L  winerror.h

The event log file has changed between reads.


FN_ERROR_EVENTLOG_FILE_CHANGED
ERROR_EVENTLOG_FILE_CHANGED  1503L  winerror.h


ERROR_EVENTLOG_FILE_CORRUPT
ERROR_EVENTLOG_FILE_CORRUPT  1500L  winerror.h

One of the Eventlog logfiles is damaged.


FN_ERROR_EVENTLOG_FILE_CORRUPT
ERROR_EVENTLOG_FILE_CORRUPT  1500L  winerror.h


ERROR_EXCEPTION_IN_SERVICE
ERROR_EXCEPTION_IN_SERVICE  1064L  winerror.h

An exception occurred in the service when handling the control request.


FN_ERROR_EXCEPTION_IN_SERVICE
ERROR_EXCEPTION_IN_SERVICE  1064L  winerror.h


ERROR_EXCL_SEM_ALREADY_OWNED
ERROR_EXCL_SEM_ALREADY_OWNED  101L  winerror.h

The exclusive semaphore is owned by another process.


FN_ERROR_EXCL_SEM_ALREADY_OWNED
ERROR_EXCL_SEM_ALREADY_OWNED  101L  winerror.h


ERROR_EXE_MARKED_INVALID
ERROR_EXE_MARKED_INVALID  192L  winerror.h

The operating system cannot run %1.


FN_ERROR_EXE_MARKED_INVALID
ERROR_EXE_MARKED_INVALID  192L  winerror.h


ERROR_EXTENDED_ERROR
ERROR_EXTENDED_ERROR  1208L  winerror.h

An extended error has occurred.


FN_ERROR_EXTENDED_ERROR
ERROR_EXTENDED_ERROR  1208L  winerror.h


ERROR_FAIL_I24
ERROR_FAIL_I24  83L  winerror.h

Fail on INT 24.


FN_ERROR_FAIL_I24
ERROR_FAIL_I24  83L  winerror.h


ERROR_FAILED_SERVICE_CONTROLLER_CONNECT
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT  1063L  winerror.h

The service process could not connect to the service controller.


FN_ERROR_FAILED_SERVICE_CONTROLLER_CONNECT
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT  1063L  winerror.h


ERROR_FILE_CORRUPT
ERROR_FILE_CORRUPT  1392L  winerror.h

The file or directory is damaged and nonreadable.


FN_ERROR_FILE_CORRUPT
ERROR_FILE_CORRUPT  1392L  winerror.h


ERROR_FILE_EXISTS
ERROR_FILE_EXISTS  80L  winerror.h

The file exists.


FN_ERROR_FILE_EXISTS
ERROR_FILE_EXISTS  80L  winerror.h


ERROR_FILE_INVALID
ERROR_FILE_INVALID  1006L  winerror.h

The volume for a file was externally altered and the opened file is no longer valid.


FN_ERROR_FILE_INVALID
ERROR_FILE_INVALID  1006L  winerror.h


ERROR_FILE_NOT_FOUND
ERROR_FILE_NOT_FOUND  2L  winerror.h

The system cannot find the file specified.


FN_ERROR_FILE_NOT_FOUND
ERROR_FILE_NOT_FOUND  2L  winerror.h


ERROR_FILEMARK_DETECTED
ERROR_FILEMARK_DETECTED  1101L  winerror.h

A tape access reached a filemark.


FN_ERROR_FILEMARK_DETECTED
ERROR_FILEMARK_DETECTED  1101L  winerror.h


ERROR_FILENAME_EXCED_RANGE
ERROR_FILENAME_EXCED_RANGE  206L  winerror.h

The file name or extension is too long.


FN_ERROR_FILENAME_EXCED_RANGE
ERROR_FILENAME_EXCED_RANGE  206L  winerror.h


ERROR_FLOPPY_BAD_REGISTERS
ERROR_FLOPPY_BAD_REGISTERS  1125L  winerror.h

The floppy disk controller returned inconsistent results in its registers.


FN_ERROR_FLOPPY_BAD_REGISTERS
ERROR_FLOPPY_BAD_REGISTERS  1125L  winerror.h


ERROR_FLOPPY_ID_MARK_NOT_FOUND
ERROR_FLOPPY_ID_MARK_NOT_FOUND  1122L  winerror.h

No ID address mark was found on the floppy disk.


FN_ERROR_FLOPPY_ID_MARK_NOT_FOUND
ERROR_FLOPPY_ID_MARK_NOT_FOUND  1122L  winerror.h


ERROR_FLOPPY_WRONG_CYLINDER
ERROR_FLOPPY_WRONG_CYLINDER  1123L  winerror.h

Mismatch between the floppy disk sector ID field and the floppy disk controller track address.


FN_ERROR_FLOPPY_WRONG_CYLINDER
ERROR_FLOPPY_WRONG_CYLINDER  1123L  winerror.h


ERROR_FLOPPY_UNKNOWN_ERROR
ERROR_FLOPPY_UNKNOWN_ERROR  1124L  winerror.h

The floppy disk controller reported an error that is not recognized by the floppy disk driver.


FN_ERROR_FLOPPY_UNKNOWN_ERROR
ERROR_FLOPPY_UNKNOWN_ERROR  1124L  winerror.h


ERROR_FULLSCREEN_MODE
ERROR_FULLSCREEN_MODE  1007L  winerror.h

The requested operation cannot be performed in full-screen mode.


FN_ERROR_FULLSCREEN_MODE
ERROR_FULLSCREEN_MODE  1007L  winerror.h


ERROR_GEN_FAILURE
ERROR_GEN_FAILURE  31L  winerror.h

A device attached to the system is not functioning.


FN_ERROR_GEN_FAILURE
ERROR_GEN_FAILURE  31L  winerror.h


ERROR_GENERIC_NOT_MAPPED
ERROR_GENERIC_NOT_MAPPED  1360L  winerror.h

Indicates generic access types were contained in an access mask that should already be mapped to non-generic access types.


FN_ERROR_GENERIC_NOT_MAPPED
ERROR_GENERIC_NOT_MAPPED  1360L  winerror.h


ERROR_GLOBAL_ONLY_HOOK
ERROR_GLOBAL_ONLY_HOOK  1429L  winerror.h

This hook can only be set globally.


FN_ERROR_GLOBAL_ONLY_HOOK
ERROR_GLOBAL_ONLY_HOOK  1429L  winerror.h


ERROR_GROUP_EXISTS
ERROR_GROUP_EXISTS  1318L  winerror.h

The specified group already exists.


FN_ERROR_GROUP_EXISTS
ERROR_GROUP_EXISTS  1318L  winerror.h


ERROR_HANDLE_DISK_FULL
ERROR_HANDLE_DISK_FULL  39L  winerror.h

The disk is full.


FN_ERROR_HANDLE_DISK_FULL
ERROR_HANDLE_DISK_FULL  39L  winerror.h


ERROR_HANDLE_EOF
ERROR_HANDLE_EOF  38L  winerror.h

Reached End Of File.


FN_ERROR_HANDLE_EOF
ERROR_HANDLE_EOF  38L  winerror.h


ERROR_HOOK_NEEDS_HMOD
ERROR_HOOK_NEEDS_HMOD  1428L  winerror.h

Cannot set non-local hook without an module handle.


FN_ERROR_HOOK_NEEDS_HMOD
ERROR_HOOK_NEEDS_HMOD  1428L  winerror.h


ERROR_HOOK_NOT_INSTALLED
ERROR_HOOK_NOT_INSTALLED  1431L  winerror.h

Hook is not installed.


FN_ERROR_HOOK_NOT_INSTALLED
ERROR_HOOK_NOT_INSTALLED  1431L  winerror.h


ERROR_HOTKEY_ALREADY_REGISTERED
ERROR_HOTKEY_ALREADY_REGISTERED  1409L  winerror.h

Hotkey is already registered.


FN_ERROR_HOTKEY_ALREADY_REGISTERED
ERROR_HOTKEY_ALREADY_REGISTERED  1409L  winerror.h


ERROR_HOTKEY_NOT_REGISTERED
ERROR_HOTKEY_NOT_REGISTERED  1419L  winerror.h

Hotkey is not registered.


FN_ERROR_HOTKEY_NOT_REGISTERED
ERROR_HOTKEY_NOT_REGISTERED  1419L  winerror.h


ERROR_HWNDS_HAVE_DIFFERENT_PARENT

All DeferWindowPos HWNDs must have same parent.


ERROR_ILL_FORMED_PASSWORD
ERROR_ILL_FORMED_PASSWORD  1324L  winerror.h

When trying to update a password, this return status indicates the value provided for the new password contains values not allowed in passwords.


FN_ERROR_ILL_FORMED_PASSWORD
ERROR_ILL_FORMED_PASSWORD  1324L  winerror.h


ERROR_INFLOOP_IN_RELOC_CHAIN
ERROR_INFLOOP_IN_RELOC_CHAIN  202L  winerror.h

The operating system cannot run %1.


FN_ERROR_INFLOOP_IN_RELOC_CHAIN
ERROR_INFLOOP_IN_RELOC_CHAIN  202L  winerror.h


ERROR_INSUFFICIENT_BUFFER
ERROR_INSUFFICIENT_BUFFER  122L  winerror.h

The data area passed to a system call is too small.


FN_ERROR_INSUFFICIENT_BUFFER
ERROR_INSUFFICIENT_BUFFER  122L  winerror.h


ERROR_INTERNAL_DB_CORRUPTION
ERROR_INTERNAL_DB_CORRUPTION  1358L  winerror.h

This error indicates the requested operation cannot be completed due to a catastrophic media failure or on-disk data structure corruption.


FN_ERROR_INTERNAL_DB_CORRUPTION
ERROR_INTERNAL_DB_CORRUPTION  1358L  winerror.h


ERROR_INTERNAL_DB_ERROR
ERROR_INTERNAL_DB_ERROR  1383L  winerror.h

The Local Security Authority (LSA) database contains in internal inconsistency.


FN_ERROR_INTERNAL_DB_ERROR
ERROR_INTERNAL_DB_ERROR  1383L  winerror.h


ERROR_INTERNAL_ERROR
ERROR_INTERNAL_ERROR  1359L  winerror.h

This error indicates the SAM server has encounterred an internal consistency error in its database. This catastrophic failure prevents further operation of SAM.


FN_ERROR_INTERNAL_ERROR
ERROR_INTERNAL_ERROR  1359L  winerror.h


ERROR_INVALID_ACCEL_HANDLE
ERROR_INVALID_ACCEL_HANDLE  1403L  winerror.h

Invalid accelerator-table handle.


FN_ERROR_INVALID_ACCEL_HANDLE
ERROR_INVALID_ACCEL_HANDLE  1403L  winerror.h


ERROR_INVALID_ACCESS
ERROR_INVALID_ACCESS  12L  winerror.h

The access code is invalid.


FN_ERROR_INVALID_ACCESS
ERROR_INVALID_ACCESS  12L  winerror.h


ERROR_INVALID_ACCOUNT_NAME
ERROR_INVALID_ACCOUNT_NAME  1315L  winerror.h

The name provided is not a properly formed account name.


FN_ERROR_INVALID_ACCOUNT_NAME
ERROR_INVALID_ACCOUNT_NAME  1315L  winerror.h


ERROR_INVALID_ACL
ERROR_INVALID_ACL  1336L  winerror.h

Indicates the ACL structure is not valid.


FN_ERROR_INVALID_ACL
ERROR_INVALID_ACL  1336L  winerror.h


ERROR_INVALID_ADDRESS
ERROR_INVALID_ADDRESS  487L  winerror.h

Attempt to access invalid address.


FN_ERROR_INVALID_ADDRESS
ERROR_INVALID_ADDRESS  487L  winerror.h


ERROR_INVALID_AT_INTERRUPT_TIME
ERROR_INVALID_AT_INTERRUPT_TIME  104L  winerror.h

Cannot request exclusive semaphores at interrupt time.


FN_ERROR_INVALID_AT_INTERRUPT_TIME
ERROR_INVALID_AT_INTERRUPT_TIME  104L  winerror.h


ERROR_INVALID_BLOCK
ERROR_INVALID_BLOCK  9L  winerror.h

The storage control block address is invalid.


FN_ERROR_INVALID_BLOCK
ERROR_INVALID_BLOCK  9L  winerror.h


ERROR_INVALID_BLOCK_LENGTH
ERROR_INVALID_BLOCK_LENGTH  1106L  winerror.h

When accessing a new tape of a multivolume partition, the current block size is incorrect.


FN_ERROR_INVALID_BLOCK_LENGTH
ERROR_INVALID_BLOCK_LENGTH  1106L  winerror.h


ERROR_INVALID_CATEGORY
ERROR_INVALID_CATEGORY  117L  winerror.h

The IOCTL call made by the application program is incorrect.


FN_ERROR_INVALID_CATEGORY
ERROR_INVALID_CATEGORY  117L  winerror.h


ERROR_INVALID_COMBOBOX_MESSAGE
ERROR_INVALID_COMBOBOX_MESSAGE  1422L  winerror.h

Invalid Message, combo box doesn't have an edit control.


FN_ERROR_INVALID_COMBOBOX_MESSAGE
ERROR_INVALID_COMBOBOX_MESSAGE  1422L  winerror.h


ERROR_INVALID_COMPUTERNAME
ERROR_INVALID_COMPUTERNAME  1210L  winerror.h

The format of the specified computer name is invalid.


FN_ERROR_INVALID_COMPUTERNAME
ERROR_INVALID_COMPUTERNAME  1210L  winerror.h


ERROR_INVALID_CURSOR_HANDLE
ERROR_INVALID_CURSOR_HANDLE  1402L  winerror.h

The cursor handle is invalid.


FN_ERROR_INVALID_CURSOR_HANDLE
ERROR_INVALID_CURSOR_HANDLE  1402L  winerror.h


ERROR_INVALID_DATA
ERROR_INVALID_DATA  13L  winerror.h

The data is invalid.


FN_ERROR_INVALID_DATA
ERROR_INVALID_DATA  13L  winerror.h


ERROR_INVALID_DATATYPE
ERROR_INVALID_DATATYPE  1804L  winerror.h

The specified datatype is invalid.


FN_ERROR_INVALID_DATATYPE
ERROR_INVALID_DATATYPE  1804L  winerror.h


ERROR_INVALID_DOMAINNAME
ERROR_INVALID_DOMAINNAME  1212L  winerror.h

The format of the specified domain name is invalid.


FN_ERROR_INVALID_DOMAINNAME
ERROR_INVALID_DOMAINNAME  1212L  winerror.h


ERROR_INVALID_DOMAIN_ROLE
ERROR_INVALID_DOMAIN_ROLE  1354L  winerror.h

Indicates the requested operation cannot be completed with the domain in its present role.


FN_ERROR_INVALID_DOMAIN_ROLE
ERROR_INVALID_DOMAIN_ROLE  1354L  winerror.h


ERROR_INVALID_DOMAIN_STATE
ERROR_INVALID_DOMAIN_STATE  1353L  winerror.h

Indicates the domain is in the wrong state to perform the desired operation.


FN_ERROR_INVALID_DOMAIN_STATE
ERROR_INVALID_DOMAIN_STATE  1353L  winerror.h


ERROR_INVALID_DRIVE
ERROR_INVALID_DRIVE  15L  winerror.h

The system cannot find the specified drive.


FN_ERROR_INVALID_DRIVE
ERROR_INVALID_DRIVE  15L  winerror.h


ERROR_INVALID_DWP_HANDLE
ERROR_INVALID_DWP_HANDLE  1405L  winerror.h

The DeferWindowPos handle is invalid.


FN_ERROR_INVALID_DWP_HANDLE
ERROR_INVALID_DWP_HANDLE  1405L  winerror.h


ERROR_INVALID_EA_HANDLE
ERROR_INVALID_EA_HANDLE  278L  winerror.h

The specified EA handle is invalid.


FN_ERROR_INVALID_EA_HANDLE
ERROR_INVALID_EA_HANDLE  278L  winerror.h


ERROR_INVALID_EA_NAME
ERROR_INVALID_EA_NAME  254L  winerror.h

The specified EA name is invalid.


FN_ERROR_INVALID_EA_NAME
ERROR_INVALID_EA_NAME  254L  winerror.h


ERROR_INVALID_EDIT_HEIGHT
ERROR_INVALID_EDIT_HEIGHT  1424L  winerror.h

Height must be less than 256.


FN_ERROR_INVALID_EDIT_HEIGHT
ERROR_INVALID_EDIT_HEIGHT  1424L  winerror.h


ERROR_INVALID_ENVIRONMENT
ERROR_INVALID_ENVIRONMENT  1805L  winerror.h

The Environment specified is invalid.


FN_ERROR_INVALID_ENVIRONMENT
ERROR_INVALID_ENVIRONMENT  1805L  winerror.h


ERROR_INVALID_EVENT_COUNT
ERROR_INVALID_EVENT_COUNT  151L  winerror.h

The number of specified semaphore events is incorrect.


FN_ERROR_INVALID_EVENT_COUNT
ERROR_INVALID_EVENT_COUNT  151L  winerror.h


ERROR_INVALID_EVENTNAME
ERROR_INVALID_EVENTNAME  1211L  winerror.h

The format of the specified event name is invalid.


FN_ERROR_INVALID_EVENTNAME
ERROR_INVALID_EVENTNAME  1211L  winerror.h


ERROR_INVALID_EXE_SIGNATURE
ERROR_INVALID_EXE_SIGNATURE  191L  winerror.h

%1 cannot be run in Windows/NT mode.


FN_ERROR_INVALID_EXE_SIGNATURE
ERROR_INVALID_EXE_SIGNATURE  191L  winerror.h


ERROR_INVALID_FILTER_PROC
ERROR_INVALID_FILTER_PROC  1427L  winerror.h

The filter proc is invalid.


FN_ERROR_INVALID_FILTER_PROC
ERROR_INVALID_FILTER_PROC  1427L  winerror.h


ERROR_INVALID_FLAG_NUMBER
ERROR_INVALID_FLAG_NUMBER  186L  winerror.h

The flag passed is incorrect.


FN_ERROR_INVALID_FLAG_NUMBER
ERROR_INVALID_FLAG_NUMBER  186L  winerror.h


ERROR_INVALID_FLAGS
ERROR_INVALID_FLAGS  1004L  winerror.h

The flags are invalid.


FN_ERROR_INVALID_FLAGS
ERROR_INVALID_FLAGS  1004L  winerror.h


ERROR_INVALID_FUNCTION
ERROR_INVALID_FUNCTION  1L  winerror.h

The function is incorrect.


FN_ERROR_INVALID_FUNCTION
ERROR_INVALID_FUNCTION  1L  winerror.h


ERROR_INVALID_GROUP_ATTRIBUTES
ERROR_INVALID_GROUP_ATTRIBUTES  1345L  winerror.h

The specified attributes are invalid, or incompatible with the attributes for the group as a whole.


FN_ERROR_INVALID_GROUP_ATTRIBUTES
ERROR_INVALID_GROUP_ATTRIBUTES  1345L  winerror.h


ERROR_INVALID_GROUPNAME
ERROR_INVALID_GROUPNAME  1209L  winerror.h

The format of the specified group name is invalid.


FN_ERROR_INVALID_GROUPNAME
ERROR_INVALID_GROUPNAME  1209L  winerror.h


ERROR_INVALID_GW_COMMAND
ERROR_INVALID_GW_COMMAND  1443L  winerror.h

The GW_* command is invalid.


FN_ERROR_INVALID_GW_COMMAND
ERROR_INVALID_GW_COMMAND  1443L  winerror.h


ERROR_INVALID_HANDLE
ERROR_INVALID_HANDLE  6L  winerror.h

The internal file identifier is incorrect.


FN_ERROR_INVALID_HANDLE
ERROR_INVALID_HANDLE  6L  winerror.h


ERROR_INVALID_HOOK_FILTER
ERROR_INVALID_HOOK_FILTER  1426L  winerror.h

The hook filter type is invalid.


FN_ERROR_INVALID_HOOK_FILTER
ERROR_INVALID_HOOK_FILTER  1426L  winerror.h


ERROR_INVALID_HOOK_HANDLE
ERROR_INVALID_HOOK_HANDLE  1404L  winerror.h

The hook handle is invalid.


FN_ERROR_INVALID_HOOK_HANDLE
ERROR_INVALID_HOOK_HANDLE  1404L  winerror.h


ERROR_INVALID_ICON_HANDLE
ERROR_INVALID_ICON_HANDLE  1414L  winerror.h

The icon handle is invalid.


FN_ERROR_INVALID_ICON_HANDLE
ERROR_INVALID_ICON_HANDLE  1414L  winerror.h


ERROR_INVALID_ID_AUTHORITY
ERROR_INVALID_ID_AUTHORITY  1343L  winerror.h

The value provided is an invalid value for an identifier authority.


FN_ERROR_INVALID_ID_AUTHORITY
ERROR_INVALID_ID_AUTHORITY  1343L  winerror.h


ERROR_INVALID_INDEX
ERROR_INVALID_INDEX  1413L  winerror.h

The index is invalid.


FN_ERROR_INVALID_INDEX
ERROR_INVALID_INDEX  1413L  winerror.h


ERROR_INVALID_LB_MESSAGE
ERROR_INVALID_LB_MESSAGE  1432L  winerror.h

The message for single-selection list box is invalid.


FN_ERROR_INVALID_LB_MESSAGE
ERROR_INVALID_LB_MESSAGE  1432L  winerror.h


ERROR_INVALID_LEVEL
ERROR_INVALID_LEVEL  124L  winerror.h

The system call level is incorrect.


FN_ERROR_INVALID_LEVEL
ERROR_INVALID_LEVEL  124L  winerror.h


ERROR_INVALID_LIST_FORMAT
ERROR_INVALID_LIST_FORMAT  153L  winerror.h

The list is not correct.


FN_ERROR_INVALID_LIST_FORMAT
ERROR_INVALID_LIST_FORMAT  153L  winerror.h


ERROR_INVALID_LOGON_HOURS
ERROR_INVALID_LOGON_HOURS  1328L  winerror.h

The user account has time restrictions and cannot be logged onto at this time.


FN_ERROR_INVALID_LOGON_HOURS
ERROR_INVALID_LOGON_HOURS  1328L  winerror.h


ERROR_INVALID_LOGON_TYPE
ERROR_INVALID_LOGON_TYPE  1367L  winerror.h

Indicates an invalid value has been provided for LogonType has been requested.


FN_ERROR_INVALID_LOGON_TYPE
ERROR_INVALID_LOGON_TYPE  1367L  winerror.h


ERROR_INVALID_MEMBER
ERROR_INVALID_MEMBER  1388L  winerror.h

A new member could not be added to an alias because the member has the wrong account type.


FN_ERROR_INVALID_MEMBER
ERROR_INVALID_MEMBER  1388L  winerror.h


ERROR_INVALID_MENU_HANDLE
ERROR_INVALID_MENU_HANDLE  1401L  winerror.h

The menu handle is invalid.


FN_ERROR_INVALID_MENU_HANDLE
ERROR_INVALID_MENU_HANDLE  1401L  winerror.h


ERROR_INVALID_MESSAGE
ERROR_INVALID_MESSAGE  1002L  winerror.h

Window can't handle sent message.


FN_ERROR_INVALID_MESSAGE
ERROR_INVALID_MESSAGE  1002L  winerror.h


ERROR_INVALID_MESSAGEDEST
ERROR_INVALID_MESSAGEDEST  1218L  winerror.h

The format of the specified message destination is invalid.


FN_ERROR_INVALID_MESSAGEDEST
ERROR_INVALID_MESSAGEDEST  1218L  winerror.h


ERROR_INVALID_MESSAGENAME
ERROR_INVALID_MESSAGENAME  1217L  winerror.h

The format of the specified message name is invalid.


FN_ERROR_INVALID_MESSAGENAME
ERROR_INVALID_MESSAGENAME  1217L  winerror.h


ERROR_INVALID_MINALLOCSIZE
ERROR_INVALID_MINALLOCSIZE  195L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_MINALLOCSIZE
ERROR_INVALID_MINALLOCSIZE  195L  winerror.h


ERROR_INVALID_MODULETYPE
ERROR_INVALID_MODULETYPE  190L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_MODULETYPE
ERROR_INVALID_MODULETYPE  190L  winerror.h


ERROR_INVALID_MSGBOX_STYLE
ERROR_INVALID_MSGBOX_STYLE  1438L  winerror.h

The message box style is invalid.


FN_ERROR_INVALID_MSGBOX_STYLE
ERROR_INVALID_MSGBOX_STYLE  1438L  winerror.h


ERROR_INVALID_NAME
ERROR_INVALID_NAME  123L  winerror.h

The file name, directory name, or volume label is syntactically incorrect.


FN_ERROR_INVALID_NAME
ERROR_INVALID_NAME  123L  winerror.h


ERROR_INVALID_NETNAME
ERROR_INVALID_NETNAME  1214L  winerror.h

The format of the specified network name is invalid.


FN_ERROR_INVALID_NETNAME
ERROR_INVALID_NETNAME  1214L  winerror.h


ERROR_INVALID_ORDINAL
ERROR_INVALID_ORDINAL  182L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_ORDINAL
ERROR_INVALID_ORDINAL  182L  winerror.h


ERROR_INVALID_OWNER
ERROR_INVALID_OWNER  1307L  winerror.h

Indicates a particular Security ID cannot be assigned as the owner of an object.


FN_ERROR_INVALID_OWNER
ERROR_INVALID_OWNER  1307L  winerror.h


ERROR_INVALID_PARAMETER
ERROR_INVALID_PARAMETER  87L  winerror.h

The parameter is incorrect.


FN_ERROR_INVALID_PARAMETER
ERROR_INVALID_PARAMETER  87L  winerror.h


ERROR_INVALID_PASSWORD
ERROR_INVALID_PASSWORD  86L  winerror.h

The specified network password is incorrect.


FN_ERROR_INVALID_PASSWORD
ERROR_INVALID_PASSWORD  86L  winerror.h


ERROR_INVALID_PASSWORDNAME
ERROR_INVALID_PASSWORDNAME  1216L  winerror.h

The format of the specified password is invalid.


FN_ERROR_INVALID_PASSWORDNAME
ERROR_INVALID_PASSWORDNAME  1216L  winerror.h


ERROR_INVALID_PRIMARY_GROUP
ERROR_INVALID_PRIMARY_GROUP  1308L  winerror.h

Indicates a particular Security ID cannot be assigned as the primary group of an object.


FN_ERROR_INVALID_PRIMARY_GROUP
ERROR_INVALID_PRIMARY_GROUP  1308L  winerror.h


ERROR_INVALID_PRINTER_COMMAND
ERROR_INVALID_PRINTER_COMMAND  1803L  winerror.h

The printer command is invalid.


FN_ERROR_INVALID_PRINTER_COMMAND
ERROR_INVALID_PRINTER_COMMAND  1803L  winerror.h


ERROR_INVALID_PRINTER_NAME
ERROR_INVALID_PRINTER_NAME  1801L  winerror.h

The printer name is invalid.


FN_ERROR_INVALID_PRINTER_NAME
ERROR_INVALID_PRINTER_NAME  1801L  winerror.h


ERROR_INVALID_PRIORITY
ERROR_INVALID_PRIORITY  1800L  winerror.h

The specified priority is invalid.


FN_ERROR_INVALID_PRIORITY
ERROR_INVALID_PRIORITY  1800L  winerror.h


ERROR_INVALID_SCROLLBAR_RANGE
ERROR_INVALID_SCROLLBAR_RANGE  1448L  winerror.h

Scrollbar range greater than 0x7FFF.


FN_ERROR_INVALID_SCROLLBAR_RANGE
ERROR_INVALID_SCROLLBAR_RANGE  1448L  winerror.h


ERROR_INVALID_SECURITY_DESCR
ERROR_INVALID_SECURITY_DESCR  1338L  winerror.h

Indicates the SECURITY_DESCRIPTOR structure is invalid.


FN_ERROR_INVALID_SECURITY_DESCR
ERROR_INVALID_SECURITY_DESCR  1338L  winerror.h


ERROR_INVALID_SEGDPL
ERROR_INVALID_SEGDPL  198L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_SEGDPL
ERROR_INVALID_SEGDPL  198L  winerror.h


ERROR_INVALID_SEGMENT_NUMBER
ERROR_INVALID_SEGMENT_NUMBER  180L  winerror.h

The system detected a segment number that is incorrect.


FN_ERROR_INVALID_SEGMENT_NUMBER
ERROR_INVALID_SEGMENT_NUMBER  180L  winerror.h


ERROR_INVALID_SEPARATOR_FILE
ERROR_INVALID_SEPARATOR_FILE  1799L  winerror.h

The specified separator file is invalid.


FN_ERROR_INVALID_SEPARATOR_FILE
ERROR_INVALID_SEPARATOR_FILE  1799L  winerror.h


ERROR_INVALID_SERVER_STATE
ERROR_INVALID_SERVER_STATE  1352L  winerror.h

Indicates the Sam Server was in the wrong state to perform the desired operation.


FN_ERROR_INVALID_SERVER_STATE
ERROR_INVALID_SERVER_STATE  1352L  winerror.h


ERROR_INVALID_SERVICE_ACCOUNT
ERROR_INVALID_SERVICE_ACCOUNT  1057L  winerror.h

The account name is invalid or does not exist.


FN_ERROR_INVALID_SERVICE_ACCOUNT
ERROR_INVALID_SERVICE_ACCOUNT  1057L  winerror.h


ERROR_INVALID_SERVICE_CONTROL
ERROR_INVALID_SERVICE_CONTROL  1052L  winerror.h

The requested control is not valid for this service


FN_ERROR_INVALID_SERVICE_CONTROL
ERROR_INVALID_SERVICE_CONTROL  1052L  winerror.h


ERROR_INVALID_SERVICE_LOCK
ERROR_INVALID_SERVICE_LOCK  1071L  winerror.h

The specified service database lock is invalid.


FN_ERROR_INVALID_SERVICE_LOCK
ERROR_INVALID_SERVICE_LOCK  1071L  winerror.h


ERROR_INVALID_SERVICENAME
ERROR_INVALID_SERVICENAME  1213L  winerror.h

The format of the specified service name is invalid.


FN_ERROR_INVALID_SERVICENAME
ERROR_INVALID_SERVICENAME  1213L  winerror.h


ERROR_INVALID_SHARENAME
ERROR_INVALID_SHARENAME  1215L  winerror.h

The format of the specified share name is invalid.


FN_ERROR_INVALID_SHARENAME
ERROR_INVALID_SHARENAME  1215L  winerror.h


ERROR_INVALID_SHOWWIN_COMMAND
ERROR_INVALID_SHOWWIN_COMMAND  1449L  winerror.h

The ShowWindow command is invalid.


FN_ERROR_INVALID_SHOWWIN_COMMAND
ERROR_INVALID_SHOWWIN_COMMAND  1449L  winerror.h


ERROR_INVALID_SID
ERROR_INVALID_SID  1337L  winerror.h

Indicates the SID structure is invalid.


FN_ERROR_INVALID_SID
ERROR_INVALID_SID  1337L  winerror.h


ERROR_INVALID_SIGNAL_NUMBER
ERROR_INVALID_SIGNAL_NUMBER  209L  winerror.h

The signal being posted is incorrect.


FN_ERROR_INVALID_SIGNAL_NUMBER
ERROR_INVALID_SIGNAL_NUMBER  209L  winerror.h


ERROR_INVALID_SPI_VALUE
ERROR_INVALID_SPI_VALUE  1439L  winerror.h

The SPI_* parameter is invalid.


FN_ERROR_INVALID_SPI_VALUE
ERROR_INVALID_SPI_VALUE  1439L  winerror.h


ERROR_INVALID_STACKSEG
ERROR_INVALID_STACKSEG  189L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_STACKSEG
ERROR_INVALID_STACKSEG  189L  winerror.h


ERROR_INVALID_STARTING_CODESEG
ERROR_INVALID_STARTING_CODESEG  188L  winerror.h

The operating system cannot run %1.


FN_ERROR_INVALID_STARTING_CODESEG
ERROR_INVALID_STARTING_CODESEG  188L  winerror.h


ERROR_INVALID_SUB_AUTHORITY
ERROR_INVALID_SUB_AUTHORITY  1335L  winerror.h

Indicates the sub-authority value is invalid for the particular use.


FN_ERROR_INVALID_SUB_AUTHORITY
ERROR_INVALID_SUB_AUTHORITY  1335L  winerror.h


ERROR_INVALID_TARGET_HANDLE
ERROR_INVALID_TARGET_HANDLE  114L  winerror.h

The target internal file identifier is incorrect.


FN_ERROR_INVALID_TARGET_HANDLE
ERROR_INVALID_TARGET_HANDLE  114L  winerror.h


ERROR_INVALID_THREAD_ID
ERROR_INVALID_THREAD_ID  1444L  winerror.h

The thread ID is invalid.


FN_ERROR_INVALID_THREAD_ID
ERROR_INVALID_THREAD_ID  1444L  winerror.h


ERROR_INVALID_USER_BUFFER
ERROR_INVALID_USER_BUFFER  1784L  winerror.h

The supplied user buffer is invalid for the requested operation.


FN_ERROR_INVALID_USER_BUFFER
ERROR_INVALID_USER_BUFFER  1784L  winerror.h


ERROR_INVALID_VERIFY_SWITCH
ERROR_INVALID_VERIFY_SWITCH  118L  winerror.h

The verify-on-write switch parameter value is incorrect.


FN_ERROR_INVALID_VERIFY_SWITCH
ERROR_INVALID_VERIFY_SWITCH  118L  winerror.h


ERROR_INVALID_WINDOW_HANDLE
ERROR_INVALID_WINDOW_HANDLE  1400L  winerror.h

The window handle invalid.


FN_ERROR_INVALID_WINDOW_HANDLE
ERROR_INVALID_WINDOW_HANDLE  1400L  winerror.h


ERROR_INVALID_WORKSTATION
ERROR_INVALID_WORKSTATION  1329L  winerror.h

The user account is restricted and cannot be used to log on from the source workstation.


FN_ERROR_INVALID_WORKSTATION
ERROR_INVALID_WORKSTATION  1329L  winerror.h


ERROR_IO_DEVICE
ERROR_IO_DEVICE  1117L  winerror.h

The request could not be performed because of an I/O device error.


FN_ERROR_IO_DEVICE
ERROR_IO_DEVICE  1117L  winerror.h


ERROR_IO_INCOMPLETE
ERROR_IO_INCOMPLETE  996L  winerror.h

Overlapped IO event not in signaled state.


FN_ERROR_IO_INCOMPLETE
ERROR_IO_INCOMPLETE  996L  winerror.h


ERROR_IO_PENDING
ERROR_IO_PENDING  997L  winerror.h

Overlapped IO operation in progress.


FN_ERROR_IO_PENDING
ERROR_IO_PENDING  997L  winerror.h


ERROR_IOPL_NOT_ENABLED
ERROR_IOPL_NOT_ENABLED  197L  winerror.h

The operating system is not presently configured to run this application.


FN_ERROR_IOPL_NOT_ENABLED
ERROR_IOPL_NOT_ENABLED  197L  winerror.h


ERROR_IRQ_BUSY
ERROR_IRQ_BUSY  1119L  winerror.h

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.


FN_ERROR_IRQ_BUSY
ERROR_IRQ_BUSY  1119L  winerror.h


ERROR_IS_JOIN_PATH
ERROR_IS_JOIN_PATH  147L  winerror.h

Not enough resources are available to process this command.


FN_ERROR_IS_JOIN_PATH
ERROR_IS_JOIN_PATH  147L  winerror.h


ERROR_IS_JOIN_TARGET
ERROR_IS_JOIN_TARGET  133L  winerror.h

A JOIN or SUBST command cannot be used for a drive that contains previously joined drives.


FN_ERROR_IS_JOIN_TARGET
ERROR_IS_JOIN_TARGET  133L  winerror.h


ERROR_IS_JOINED
ERROR_IS_JOINED  134L  winerror.h

An attempt was made to use a JOIN or SUBST command on a drive that is already joined.


FN_ERROR_IS_JOINED
ERROR_IS_JOINED  134L  winerror.h


ERROR_IS_SUBST_PATH
ERROR_IS_SUBST_PATH  146L  winerror.h

The path specified is being used in a substitute.


FN_ERROR_IS_SUBST_PATH
ERROR_IS_SUBST_PATH  146L  winerror.h


ERROR_IS_SUBST_TARGET
ERROR_IS_SUBST_TARGET  149L  winerror.h

An attempt was made to join or substitute a drive for which a directory on the drive is the target of a previous substitute.


FN_ERROR_IS_SUBST_TARGET
ERROR_IS_SUBST_TARGET  149L  winerror.h


ERROR_IS_SUBSTED
ERROR_IS_SUBSTED  135L  winerror.h

An attempt was made to use a JOIN or SUBST command on a drive already substituted.


FN_ERROR_IS_SUBSTED
ERROR_IS_SUBSTED  135L  winerror.h


ERROR_ITERATED_DATA_EXCEEDS_64k
ERROR_ITERATED_DATA_EXCEEDS_64k  194L  winerror.h

The operating system cannot run %1.


FN_ERROR_ITERATED_DATA_EXCEEDS_64k
ERROR_ITERATED_DATA_EXCEEDS_64k  194L  winerror.h


ERROR_JOIN_TO_JOIN
ERROR_JOIN_TO_JOIN  138L  winerror.h

The system tried to join a drive to a directory on a joined drive.


FN_ERROR_JOIN_TO_JOIN
ERROR_JOIN_TO_JOIN  138L  winerror.h


ERROR_JOIN_TO_SUBST
ERROR_JOIN_TO_SUBST  140L  winerror.h

The system tried to join a drive to a directory on a substituted drive.


FN_ERROR_JOIN_TO_SUBST
ERROR_JOIN_TO_SUBST  140L  winerror.h


ERROR_JOURNAL_HOOK_SET
ERROR_JOURNAL_HOOK_SET  1430L  winerror.h

The journal hook is already installed.


FN_ERROR_JOURNAL_HOOK_SET
ERROR_JOURNAL_HOOK_SET  1430L  winerror.h


ERROR_KEY_DELETED
ERROR_KEY_DELETED  1018L  winerror.h

Illegal operation attempted on a registry key that has been marked for deletion.


FN_ERROR_KEY_DELETED
ERROR_KEY_DELETED  1018L  winerror.h


ERROR_KEY_HAS_CHILDREN
ERROR_KEY_HAS_CHILDREN  1020L  winerror.h

An attempt was made to create a symbolic link in a registry key that already has subkeys or values.


FN_ERROR_KEY_HAS_CHILDREN
ERROR_KEY_HAS_CHILDREN  1020L  winerror.h


ERROR_LABEL_TOO_LONG
ERROR_LABEL_TOO_LONG  154L  winerror.h

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.


FN_ERROR_LABEL_TOO_LONG
ERROR_LABEL_TOO_LONG  154L  winerror.h


ERROR_LAST_ADMIN
ERROR_LAST_ADMIN  1322L  winerror.h

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.


FN_ERROR_LAST_ADMIN
ERROR_LAST_ADMIN  1322L  winerror.h


ERROR_LB_WITHOUT_TABSTOPS
ERROR_LB_WITHOUT_TABSTOPS  1434L  winerror.h

This list box doesn't support tab stops.


FN_ERROR_LB_WITHOUT_TABSTOPS
ERROR_LB_WITHOUT_TABSTOPS  1434L  winerror.h


ERROR_LISTBOX_ID_NOT_FOUND
ERROR_LISTBOX_ID_NOT_FOUND  1416L  winerror.h

List box ID not found.


FN_ERROR_LISTBOX_ID_NOT_FOUND
ERROR_LISTBOX_ID_NOT_FOUND  1416L  winerror.h


ERROR_LM_CROSS_ENCRYPTION_REQUIRED
ERROR_LM_CROSS_ENCRYPTION_REQUIRED  1390L  winerror.h

An attempt was made to change a user password in the security account manager without providing the required LM cross-encrypted password.


FN_ERROR_LM_CROSS_ENCRYPTION_REQUIRED
ERROR_LM_CROSS_ENCRYPTION_REQUIRED  1390L  winerror.h


ERROR_LOCAL_USER_SESSION_KEY
ERROR_LOCAL_USER_SESSION_KEY  1303L  winerror.h

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.


FN_ERROR_LOCAL_USER_SESSION_KEY
ERROR_LOCAL_USER_SESSION_KEY  1303L  winerror.h


ERROR_LOCK_FAILED
ERROR_LOCK_FAILED  167L  winerror.h

Attempt to lock a region of a file failed.


FN_ERROR_LOCK_FAILED
ERROR_LOCK_FAILED  167L  winerror.h


ERROR_LOCK_VIOLATION
ERROR_LOCK_VIOLATION  33L  winerror.h

The process cannot access the file because another process has locked a portion of the file.


FN_ERROR_LOCK_VIOLATION
ERROR_LOCK_VIOLATION  33L  winerror.h


ERROR_LOCKED
ERROR_LOCKED  212L  winerror.h

The segment is locked and cannot be reallocated.


FN_ERROR_LOCKED
ERROR_LOCKED  212L  winerror.h


ERROR_LOG_FILE_FULL
ERROR_LOG_FILE_FULL  1502L  winerror.h

The event log file is full.


FN_ERROR_LOG_FILE_FULL
ERROR_LOG_FILE_FULL  1502L  winerror.h


ERROR_LOGON_FAILURE
ERROR_LOGON_FAILURE  1326L  winerror.h

The attempted logon is invalid. This is due to either a bad username or authentication information.


FN_ERROR_LOGON_FAILURE
ERROR_LOGON_FAILURE  1326L  winerror.h


ERROR_LOGON_NOT_GRANTED
ERROR_LOGON_NOT_GRANTED  1380L  winerror.h

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.


FN_ERROR_LOGON_NOT_GRANTED
ERROR_LOGON_NOT_GRANTED  1380L  winerror.h


ERROR_LOGON_SESSION_COLLISION
ERROR_LOGON_SESSION_COLLISION  1366L  winerror.h

The logon session ID is already in use.


FN_ERROR_LOGON_SESSION_COLLISION
ERROR_LOGON_SESSION_COLLISION  1366L  winerror.h


ERROR_LOGON_SESSION_EXISTS
ERROR_LOGON_SESSION_EXISTS  1363L  winerror.h

An attempt was made to start a new session manager or LSA logon session with an ID already in use.


FN_ERROR_LOGON_SESSION_EXISTS
ERROR_LOGON_SESSION_EXISTS  1363L  winerror.h


ERROR_LOGON_TYPE_NOT_GRANTED
ERROR_LOGON_TYPE_NOT_GRANTED  1385L  winerror.h

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.


FN_ERROR_LOGON_TYPE_NOT_GRANTED
ERROR_LOGON_TYPE_NOT_GRANTED  1385L  winerror.h


ERROR_LUIDS_EXHAUSTED
ERROR_LUIDS_EXHAUSTED  1334L  winerror.h

Indicates there are no more LUID to allocate.


FN_ERROR_LUIDS_EXHAUSTED
ERROR_LUIDS_EXHAUSTED  1334L  winerror.h


ERROR_MAX_THRDS_REACHED
ERROR_MAX_THRDS_REACHED  164L  winerror.h

No more threads can be created in the system.


FN_ERROR_MAX_THRDS_REACHED
ERROR_MAX_THRDS_REACHED  164L  winerror.h


ERROR_MEDIA_CHANGED
ERROR_MEDIA_CHANGED  1110L  winerror.h

Media in drive may have changed.


FN_ERROR_MEDIA_CHANGED
ERROR_MEDIA_CHANGED  1110L  winerror.h


ERROR_MEMBER_IN_ALIAS
ERROR_MEMBER_IN_ALIAS  1378L  winerror.h

The specified account name is not a member of the alias.


FN_ERROR_MEMBER_IN_ALIAS
ERROR_MEMBER_IN_ALIAS  1378L  winerror.h


ERROR_MEMBER_IN_GROUP
ERROR_MEMBER_IN_GROUP  1320L  winerror.h

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.


FN_ERROR_MEMBER_IN_GROUP
ERROR_MEMBER_IN_GROUP  1320L  winerror.h


ERROR_MEMBER_NOT_IN_ALIAS
ERROR_MEMBER_NOT_IN_ALIAS  1377L  winerror.h

The specified account name is not a member of the alias.


FN_ERROR_MEMBER_NOT_IN_ALIAS
ERROR_MEMBER_NOT_IN_ALIAS  1377L  winerror.h


ERROR_MEMBER_NOT_IN_GROUP
ERROR_MEMBER_NOT_IN_GROUP  1321L  winerror.h

The specified user account is not a member of the specified group account.


FN_ERROR_MEMBER_NOT_IN_GROUP
ERROR_MEMBER_NOT_IN_GROUP  1321L  winerror.h


ERROR_MEMBERS_PRIMARY_GROUP
ERROR_MEMBERS_PRIMARY_GROUP  1374L  winerror.h

Indicates a member cannot be removed from a group because the group is currently the member's primary group.


FN_ERROR_MEMBERS_PRIMARY_GROUP
ERROR_MEMBERS_PRIMARY_GROUP  1374L  winerror.h


ERROR_META_EXPANSION_TOO_LONG
ERROR_META_EXPANSION_TOO_LONG  208L  winerror.h

The global filename characters * or ? are entered incorrectly, or too many global filename characters are specified.


FN_ERROR_META_EXPANSION_TOO_LONG
ERROR_META_EXPANSION_TOO_LONG  208L  winerror.h


ERROR_MOD_NOT_FOUND
ERROR_MOD_NOT_FOUND  126L  winerror.h

The specified module cannot be found.


FN_ERROR_MOD_NOT_FOUND
ERROR_MOD_NOT_FOUND  126L  winerror.h


ERROR_MORE_DATA
ERROR_MORE_DATA  234L  winerror.h

More data is available.


FN_ERROR_MORE_DATA
ERROR_MORE_DATA  234L  winerror.h


ERROR_MORE_WRITES
ERROR_MORE_WRITES  1120L  winerror.h

A serial I/O operation was completed by another write to the serial port. (The IOCTL_SERIAL_XOFF_COUNTER reached zero.)


FN_ERROR_MORE_WRITES
ERROR_MORE_WRITES  1120L  winerror.h


ERROR_MR_MID_NOT_FOUND
ERROR_MR_MID_NOT_FOUND  317L  winerror.h

The system cannot find message for message number 0x%1 in message file for %2.


FN_ERROR_MR_MID_NOT_FOUND
ERROR_MR_MID_NOT_FOUND  317L  winerror.h


ERROR_NEGATIVE_SEEK
ERROR_NEGATIVE_SEEK  131L  winerror.h

An attempt was made to move the file pointer before the beginning of the file.


FN_ERROR_NEGATIVE_SEEK
ERROR_NEGATIVE_SEEK  131L  winerror.h


ERROR_NESTING_NOT_ALLOWED
ERROR_NESTING_NOT_ALLOWED  215L  winerror.h

Can't nest calls to LoadModule.


FN_ERROR_NESTING_NOT_ALLOWED
ERROR_NESTING_NOT_ALLOWED  215L  winerror.h


ERROR_NETLOGON_NOT_STARTED
ERROR_NETLOGON_NOT_STARTED  1792L  winerror.h

An attempt was made to logon, but the network logon service was not started.


FN_ERROR_NETLOGON_NOT_STARTED
ERROR_NETLOGON_NOT_STARTED  1792L  winerror.h


ERROR_NET_WRITE_FAULT
ERROR_NET_WRITE_FAULT  88L  winerror.h

A write fault occurred on the network.


FN_ERROR_NET_WRITE_FAULT
ERROR_NET_WRITE_FAULT  88L  winerror.h


ERROR_NETNAME_DELETED
ERROR_NETNAME_DELETED  64L  winerror.h

The specified network name is no longer available.


FN_ERROR_NETNAME_DELETED
ERROR_NETNAME_DELETED  64L  winerror.h


ERROR_NETWORK_ACCESS_DENIED
ERROR_NETWORK_ACCESS_DENIED  65L  winerror.h

Network access is denied.


FN_ERROR_NETWORK_ACCESS_DENIED
ERROR_NETWORK_ACCESS_DENIED  65L  winerror.h


ERROR_NETWORK_BUSY
ERROR_NETWORK_BUSY  54L  winerror.h

The network is busy.


FN_ERROR_NETWORK_BUSY
ERROR_NETWORK_BUSY  54L  winerror.h


ERROR_NO_BROWSER_SERVERS_FOUND
ERROR_NO_BROWSER_SERVERS_FOUND  6118L  winerror.h

The list of servers for this workgroup is not currently available


FN_ERROR_NO_BROWSER_SERVERS_FOUND
ERROR_NO_BROWSER_SERVERS_FOUND  6118L  winerror.h


ERROR_NO_DATA
ERROR_NO_DATA  232L  winerror.h

Pipe close in progress.


FN_ERROR_NO_DATA
ERROR_NO_DATA  232L  winerror.h


ERROR_NO_DATA_DETECTED
ERROR_NO_DATA_DETECTED  1104L  winerror.h

During a tape access, the end of the data marker was reached.


FN_ERROR_NO_DATA_DETECTED
ERROR_NO_DATA_DETECTED  1104L  winerror.h


ERROR_NO_IMPERSONATION_TOKEN
ERROR_NO_IMPERSONATION_TOKEN  1309L  winerror.h

An attempt was made to operate on an impersonation token by a thread was not currently impersonating a client.


FN_ERROR_NO_IMPERSONATION_TOKEN
ERROR_NO_IMPERSONATION_TOKEN  1309L  winerror.h


ERROR_NO_INHERITANCE
ERROR_NO_INHERITANCE  1391L  winerror.h

Indicates an ACL contains no inheritable components.


FN_ERROR_NO_INHERITANCE
ERROR_NO_INHERITANCE  1391L  winerror.h


ERROR_NO_LOG_SPACE
ERROR_NO_LOG_SPACE  1019L  winerror.h

System could not allocate required space in a registry log.


FN_ERROR_NO_LOG_SPACE
ERROR_NO_LOG_SPACE  1019L  winerror.h


ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT
ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT  1807L  winerror.h

The account used is an interdomain trust account. Use your normal user account or remote user account to access this server.


FN_ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT
ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT  1807L  winerror.h


ERROR_NOLOGON_SERVER_TRUST_ACCOUNT
ERROR_NOLOGON_SERVER_TRUST_ACCOUNT  1809L  winerror.h

The account used is an server trust account. Use your normal user account or remote user account to access this server.


FN_ERROR_NOLOGON_SERVER_TRUST_ACCOUNT
ERROR_NOLOGON_SERVER_TRUST_ACCOUNT  1809L  winerror.h


ERROR_NO_LOGON_SERVERS
ERROR_NO_LOGON_SERVERS  1311L  winerror.h

There are currently no logon servers available to service the logon request.


FN_ERROR_NO_LOGON_SERVERS
ERROR_NO_LOGON_SERVERS  1311L  winerror.h


ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT
ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT  1808L  winerror.h

The account used is a workstation trust account. Use your normal user account or remote user account to access this server.


FN_ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT
ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT  1808L  winerror.h


ERROR_NO_MEDIA_IN_DRIVE
ERROR_NO_MEDIA_IN_DRIVE  1112L  winerror.h

Tape query failed because of no media in drive.


FN_ERROR_NO_MEDIA_IN_DRIVE
ERROR_NO_MEDIA_IN_DRIVE  1112L  winerror.h


ERROR_NO_MORE_FILES
ERROR_NO_MORE_FILES  18L  winerror.h

There are no more files.


FN_ERROR_NO_MORE_FILES
ERROR_NO_MORE_FILES  18L  winerror.h


ERROR_NO_MORE_ITEMS
ERROR_NO_MORE_ITEMS  259L  winerror.h

No more data is available.


FN_ERROR_NO_MORE_ITEMS
ERROR_NO_MORE_ITEMS  259L  winerror.h


ERROR_NO_MORE_SEARCH_HANDLES
ERROR_NO_MORE_SEARCH_HANDLES  113L  winerror.h

No more internal file identifiers available.


FN_ERROR_NO_MORE_SEARCH_HANDLES
ERROR_NO_MORE_SEARCH_HANDLES  113L  winerror.h


ERROR_NO_NET_OR_BAD_PATH
ERROR_NO_NET_OR_BAD_PATH  1203L  winerror.h

No network provider accepted the given network path.


FN_ERROR_NO_NET_OR_BAD_PATH
ERROR_NO_NET_OR_BAD_PATH  1203L  winerror.h


ERROR_NO_NETWORK
ERROR_NO_NETWORK  1222L  winerror.h

The network is not present or not started.


FN_ERROR_NO_NETWORK
ERROR_NO_NETWORK  1222L  winerror.h


ERROR_NO_PROC_SLOTS
ERROR_NO_PROC_SLOTS  89L  winerror.h

The system cannot start another process at this time.


FN_ERROR_NO_PROC_SLOTS
ERROR_NO_PROC_SLOTS  89L  winerror.h


ERROR_NO_QUOTAS_FOR_ACCOUNT
ERROR_NO_QUOTAS_FOR_ACCOUNT  1302L  winerror.h

No system quota limits are specifically set for this account.


FN_ERROR_NO_QUOTAS_FOR_ACCOUNT
ERROR_NO_QUOTAS_FOR_ACCOUNT  1302L  winerror.h


ERROR_NO_SCROLLBARS
ERROR_NO_SCROLLBARS  1447L  winerror.h

Window does not have scroll bars.


FN_ERROR_NO_SCROLLBARS
ERROR_NO_SCROLLBARS  1447L  winerror.h


ERROR_NO_SECURITY_ON_OBJECT
ERROR_NO_SECURITY_ON_OBJECT  1350L  winerror.h

Indicates an attempt was made to operate on the security of an object that does not have security associated with it.


FN_ERROR_NO_SECURITY_ON_OBJECT
ERROR_NO_SECURITY_ON_OBJECT  1350L  winerror.h


ERROR_NO_SHUTDOWN_IN_PROGRESS
ERROR_NO_SHUTDOWN_IN_PROGRESS  1116L  winerror.h

An attempt to abort the shutdown of the system failed because no shutdown was in progress.


FN_ERROR_NO_SHUTDOWN_IN_PROGRESS
ERROR_NO_SHUTDOWN_IN_PROGRESS  1116L  winerror.h


ERROR_NO_SIGNAL_SENT
ERROR_NO_SIGNAL_SENT  205L  winerror.h

No process in the command subtree has a signal handler.


FN_ERROR_NO_SIGNAL_SENT
ERROR_NO_SIGNAL_SENT  205L  winerror.h


ERROR_NO_SPOOL_SPACE
ERROR_NO_SPOOL_SPACE  62L  winerror.h

Space to store the file waiting to be printed is not available on the server.


FN_ERROR_NO_SPOOL_SPACE
ERROR_NO_SPOOL_SPACE  62L  winerror.h


ERROR_NO_SUCH_ALIAS
ERROR_NO_SUCH_ALIAS  1376L  winerror.h

The specified alias does not exist.


FN_ERROR_NO_SUCH_ALIAS
ERROR_NO_SUCH_ALIAS  1376L  winerror.h


ERROR_NO_SUCH_DOMAIN
ERROR_NO_SUCH_DOMAIN  1355L  winerror.h

The specified domain does not exist.


FN_ERROR_NO_SUCH_DOMAIN
ERROR_NO_SUCH_DOMAIN  1355L  winerror.h


ERROR_NO_SUCH_GROUP
ERROR_NO_SUCH_GROUP  1319L  winerror.h

The specified group does not exist.


FN_ERROR_NO_SUCH_GROUP
ERROR_NO_SUCH_GROUP  1319L  winerror.h


ERROR_NO_SUCH_LOGON_SESSION
ERROR_NO_SUCH_LOGON_SESSION  1312L  winerror.h

A specified logon session does not exist. It may already have been terminated.


FN_ERROR_NO_SUCH_LOGON_SESSION
ERROR_NO_SUCH_LOGON_SESSION  1312L  winerror.h


ERROR_NO_SUCH_MEMBER
ERROR_NO_SUCH_MEMBER  1387L  winerror.h

A new member cannot be added to an alias because the member does not exist.


FN_ERROR_NO_SUCH_MEMBER
ERROR_NO_SUCH_MEMBER  1387L  winerror.h


ERROR_NO_SUCH_PACKAGE
ERROR_NO_SUCH_PACKAGE  1364L  winerror.h

A specified authentication package is unknown.


FN_ERROR_NO_SUCH_PACKAGE
ERROR_NO_SUCH_PACKAGE  1364L  winerror.h


ERROR_NO_SUCH_PRIVILEGE
ERROR_NO_SUCH_PRIVILEGE  1313L  winerror.h

A specified privilege does not exist.


FN_ERROR_NO_SUCH_PRIVILEGE
ERROR_NO_SUCH_PRIVILEGE  1313L  winerror.h


ERROR_NO_SUCH_USER
ERROR_NO_SUCH_USER  1317L  winerror.h

The specified user does not exist.


FN_ERROR_NO_SUCH_USER
ERROR_NO_SUCH_USER  1317L  winerror.h


ERROR_NO_SYSTEM_MENU
ERROR_NO_SYSTEM_MENU  1437L  winerror.h

Window does not have system menu.


FN_ERROR_NO_SYSTEM_MENU
ERROR_NO_SYSTEM_MENU  1437L  winerror.h


ERROR_NO_TOKEN
ERROR_NO_TOKEN  1008L  winerror.h

An attempt was made to reference a token that does not exist.


FN_ERROR_NO_TOKEN
ERROR_NO_TOKEN  1008L  winerror.h


ERROR_NO_TRUST_LSA_SECRET
ERROR_NO_TRUST_LSA_SECRET  1786L  winerror.h

The workstation does not have a trust secret.


FN_ERROR_NO_TRUST_LSA_SECRET
ERROR_NO_TRUST_LSA_SECRET  1786L  winerror.h


ERROR_NO_TRUST_SAM_ACCOUNT
ERROR_NO_TRUST_SAM_ACCOUNT  1787L  winerror.h

The domain controller does not have an account for this workstation.


FN_ERROR_NO_TRUST_SAM_ACCOUNT
ERROR_NO_TRUST_SAM_ACCOUNT  1787L  winerror.h


ERROR_NO_UNICODE_TRANSLATION
ERROR_NO_UNICODE_TRANSLATION  1113L  winerror.h

No mapping for the Unicode character exists in the target multi-byte code page.


FN_ERROR_NO_UNICODE_TRANSLATION
ERROR_NO_UNICODE_TRANSLATION  1113L  winerror.h


ERROR_NO_USER_SESSION_KEY
ERROR_NO_USER_SESSION_KEY  1394L  winerror.h

There is no user session key for the specified logon session.


FN_ERROR_NO_USER_SESSION_KEY
ERROR_NO_USER_SESSION_KEY  1394L  winerror.h


ERROR_NO_VOLUME_LABEL
ERROR_NO_VOLUME_LABEL  125L  winerror.h

The disk has no volume label.


FN_ERROR_NO_VOLUME_LABEL
ERROR_NO_VOLUME_LABEL  125L  winerror.h


ERROR_NO_WILDCARD_CHARACTERS
ERROR_NO_WILDCARD_CHARACTERS  1417L  winerror.h

No wildcard characters found.


FN_ERROR_NO_WILDCARD_CHARACTERS
ERROR_NO_WILDCARD_CHARACTERS  1417L  winerror.h


ERROR_NOACCESS
ERROR_NOACCESS  998L  winerror.h

Invalid access to memory location.


FN_ERROR_NOACCESS
ERROR_NOACCESS  998L  winerror.h


ERROR_NON_MDICHILD_WINDOW
ERROR_NON_MDICHILD_WINDOW  1445L  winerror.h

DefMDIChildProc called with a non-MDI child window.


FN_ERROR_NON_MDICHILD_WINDOW
ERROR_NON_MDICHILD_WINDOW  1445L  winerror.h


ERROR_NONE_MAPPED
ERROR_NONE_MAPPED  1332L  winerror.h

None of the information to be mapped has been translated.


FN_ERROR_NONE_MAPPED
ERROR_NONE_MAPPED  1332L  winerror.h


ERROR_NOT_ALL_ASSIGNED
ERROR_NOT_ALL_ASSIGNED  1300L  winerror.h

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.


FN_ERROR_NOT_ALL_ASSIGNED
ERROR_NOT_ALL_ASSIGNED  1300L  winerror.h


ERROR_NOT_CHILD_WINDOW
ERROR_NOT_CHILD_WINDOW  1442L  winerror.h

Window is not a child window.


FN_ERROR_NOT_CHILD_WINDOW
ERROR_NOT_CHILD_WINDOW  1442L  winerror.h


ERROR_NOT_CONNECTED
ERROR_NOT_CONNECTED  2250L  winerror.h

This network connection does not exist.


FN_ERROR_NOT_CONNECTED
ERROR_NOT_CONNECTED  2250L  winerror.h


ERROR_NOT_CONTAINER
ERROR_NOT_CONTAINER  1207L  winerror.h

Cannot enumerate a non-container.


FN_ERROR_NOT_CONTAINER
ERROR_NOT_CONTAINER  1207L  winerror.h


ERROR_NOT_DOS_DISK
ERROR_NOT_DOS_DISK  26L  winerror.h

The specified disk cannot be accessed.


FN_ERROR_NOT_DOS_DISK
ERROR_NOT_DOS_DISK  26L  winerror.h


ERROR_NOT_ENOUGH_MEMORY
ERROR_NOT_ENOUGH_MEMORY  8L  winerror.h

Not enough storage is available to process this command.


FN_ERROR_NOT_ENOUGH_MEMORY
ERROR_NOT_ENOUGH_MEMORY  8L  winerror.h


ERROR_NOT_ENOUGH_SERVER_MEMORY
ERROR_NOT_ENOUGH_SERVER_MEMORY  1130L  winerror.h

Not enough server storage is available to process this command.


FN_ERROR_NOT_ENOUGH_SERVER_MEMORY
ERROR_NOT_ENOUGH_SERVER_MEMORY  1130L  winerror.h


ERROR_NOT_JOINED
ERROR_NOT_JOINED  136L  winerror.h

The system attempted to delete the JOIN of a drive not previously joined.


FN_ERROR_NOT_JOINED
ERROR_NOT_JOINED  136L  winerror.h


ERROR_NOT_LOCKED
ERROR_NOT_LOCKED  158L  winerror.h

The segment is already unlocked.


FN_ERROR_NOT_LOCKED
ERROR_NOT_LOCKED  158L  winerror.h


ERROR_NOT_LOGON_PROCESS
ERROR_NOT_LOGON_PROCESS  1362L  winerror.h

The requested action is restricted for use by logon processes only. The calling process has not registered as a logon process.


FN_ERROR_NOT_LOGON_PROCESS
ERROR_NOT_LOGON_PROCESS  1362L  winerror.h


ERROR_NOT_OWNER
ERROR_NOT_OWNER  288L  winerror.h

Attempt to release mutex not owned by caller.


FN_ERROR_NOT_OWNER
ERROR_NOT_OWNER  288L  winerror.h


ERROR_NOT_READY
ERROR_NOT_READY  21L  winerror.h

The drive is not ready.


FN_ERROR_NOT_READY
ERROR_NOT_READY  21L  winerror.h


ERROR_NOT_REGISTRY_FILE
ERROR_NOT_REGISTRY_FILE  1017L  winerror.h

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.


FN_ERROR_NOT_REGISTRY_FILE
ERROR_NOT_REGISTRY_FILE  1017L  winerror.h


ERROR_NOT_SAME_DEVICE
ERROR_NOT_SAME_DEVICE  17L  winerror.h

The system cannot move the file to a different disk drive.


FN_ERROR_NOT_SAME_DEVICE
ERROR_NOT_SAME_DEVICE  17L  winerror.h


ERROR_NOT_SUBSTED
ERROR_NOT_SUBSTED  137L  winerror.h

The system attempted to delete the substitution of a drive not previously substituted.


FN_ERROR_NOT_SUBSTED
ERROR_NOT_SUBSTED  137L  winerror.h


ERROR_NOT_SUPPORTED
ERROR_NOT_SUPPORTED  50L  winerror.h

The network request is not supported.


FN_ERROR_NOT_SUPPORTED
ERROR_NOT_SUPPORTED  50L  winerror.h


ERROR_NOTIFY_ENUM_DIR
ERROR_NOTIFY_ENUM_DIR  1022L  winerror.h

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.


FN_ERROR_NOTIFY_ENUM_DIR
ERROR_NOTIFY_ENUM_DIR  1022L  winerror.h


ERROR_NT_CROSS_ENCRYPTION_REQUIRED
ERROR_NT_CROSS_ENCRYPTION_REQUIRED  1386L  winerror.h

An attempt was made to change a user password in the security account manager without providing the necessary NT cross-encrypted password.


FN_ERROR_NT_CROSS_ENCRYPTION_REQUIRED
ERROR_NT_CROSS_ENCRYPTION_REQUIRED  1386L  winerror.h


ERROR_NULL_LM_PASSWORD
ERROR_NULL_LM_PASSWORD  1304L  winerror.h

The Windows NT password is too complex to be converted to a Windows-networking password. The Windows-networking password returned is a NULL string.


FN_ERROR_NULL_LM_PASSWORD
ERROR_NULL_LM_PASSWORD  1304L  winerror.h


ERROR_OPEN_FAILED
ERROR_OPEN_FAILED  110L  winerror.h

The system cannot open the specified device or file.


FN_ERROR_OPEN_FAILED
ERROR_OPEN_FAILED  110L  winerror.h


ERROR_OPEN_FILES
ERROR_OPEN_FILES  2401L  winerror.h

There are open files or requests pending on this connection.


FN_ERROR_OPEN_FILES
ERROR_OPEN_FILES  2401L  winerror.h


ERROR_OPERATION_ABORTED
ERROR_OPERATION_ABORTED  995L  winerror.h

The I/O operation was aborted due to either thread exit or application request.


FN_ERROR_OPERATION_ABORTED
ERROR_OPERATION_ABORTED  995L  winerror.h


ERROR_OUT_OF_PAPER
ERROR_OUT_OF_PAPER  28L  winerror.h

The printer is out of paper.


FN_ERROR_OUT_OF_PAPER
ERROR_OUT_OF_PAPER  28L  winerror.h


ERROR_OUT_OF_STRUCTURES
ERROR_OUT_OF_STRUCTURES  84L  winerror.h

Storage to process this request is not available.


FN_ERROR_OUT_OF_STRUCTURES
ERROR_OUT_OF_STRUCTURES  84L  winerror.h


ERROR_OUTOFMEMORY
ERROR_OUTOFMEMORY  14L  winerror.h

Not enough storage is available to complete this operation.


FN_ERROR_OUTOFMEMORY
ERROR_OUTOFMEMORY  14L  winerror.h


ERROR_PARTITION_FAILURE
ERROR_PARTITION_FAILURE  1105L  winerror.h

Tape could not be partitioned.


FN_ERROR_PARTITION_FAILURE
ERROR_PARTITION_FAILURE  1105L  winerror.h


ERROR_PASSWORD_EXPIRED
ERROR_PASSWORD_EXPIRED  1330L  winerror.h

The user account's password has expired.


FN_ERROR_PASSWORD_EXPIRED
ERROR_PASSWORD_EXPIRED  1330L  winerror.h


ERROR_PASSWORD_RESTRICTION
ERROR_PASSWORD_RESTRICTION  1325L  winerror.h

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.


FN_ERROR_PASSWORD_RESTRICTION
ERROR_PASSWORD_RESTRICTION  1325L  winerror.h


ERROR_PATH_BUSY
ERROR_PATH_BUSY  148L  winerror.h

The specified path cannot be used at this time.


FN_ERROR_PATH_BUSY
ERROR_PATH_BUSY  148L  winerror.h


ERROR_PATH_NOT_FOUND
ERROR_PATH_NOT_FOUND  3L  winerror.h

The system cannot find the specified path.


FN_ERROR_PATH_NOT_FOUND
ERROR_PATH_NOT_FOUND  3L  winerror.h


ERROR_PIPE_BUSY
ERROR_PIPE_BUSY  231L  winerror.h

All pipe instances busy.


FN_ERROR_PIPE_BUSY
ERROR_PIPE_BUSY  231L  winerror.h


ERROR_PIPE_CONNECTED
ERROR_PIPE_CONNECTED  535L  winerror.h

There is a process on other end of the pipe.


FN_ERROR_PIPE_CONNECTED
ERROR_PIPE_CONNECTED  535L  winerror.h


ERROR_PIPE_LISTENING
ERROR_PIPE_LISTENING  536L  winerror.h

Waiting for a process to open the other end of the pipe.


FN_ERROR_PIPE_LISTENING
ERROR_PIPE_LISTENING  536L  winerror.h


ERROR_PIPE_NOT_CONNECTED
ERROR_PIPE_NOT_CONNECTED  233L  winerror.h

No process on other end of pipe.


FN_ERROR_PIPE_NOT_CONNECTED
ERROR_PIPE_NOT_CONNECTED  233L  winerror.h


ERROR_POPUP_ALREADY_ACTIVE
ERROR_POPUP_ALREADY_ACTIVE  1446L  winerror.h

Pop-up menu already active.


FN_ERROR_POPUP_ALREADY_ACTIVE
ERROR_POPUP_ALREADY_ACTIVE  1446L  winerror.h


ERROR_POSSIBLE_DEADLOCK
ERROR_POSSIBLE_DEADLOCK  1131L  winerror.h

A potential deadlock condition has been detected.


FN_ERROR_POSSIBLE_DEADLOCK
ERROR_POSSIBLE_DEADLOCK  1131L  winerror.h


ERROR_PRINT_CANCELLED
ERROR_PRINT_CANCELLED  63L  winerror.h

File waiting to be printed was deleted.


FN_ERROR_PRINT_CANCELLED
ERROR_PRINT_CANCELLED  63L  winerror.h


ERROR_PRINTER_ALREADY_EXISTS
ERROR_PRINTER_ALREADY_EXISTS  1802L  winerror.h

The printer already exists.


FN_ERROR_PRINTER_ALREADY_EXISTS
ERROR_PRINTER_ALREADY_EXISTS  1802L  winerror.h


ERROR_PRINTER_DRIVER_ALREADY_INSTALLED
ERROR_PRINTER_DRIVER_ALREADY_INSTALLED  1795L  winerror.h

The specified printer driver is already installed.


FN_ERROR_PRINTER_DRIVER_ALREADY_INSTALLED
ERROR_PRINTER_DRIVER_ALREADY_INSTALLED  1795L  winerror.h


ERROR_PRINTQ_FULL
ERROR_PRINTQ_FULL  61L  winerror.h

The printer queue is full.


FN_ERROR_PRINTQ_FULL
ERROR_PRINTQ_FULL  61L  winerror.h


ERROR_PRIVATE_DIALOG_INDEX
ERROR_PRIVATE_DIALOG_INDEX  1415L  winerror.h

Using private DIALOG window words.


FN_ERROR_PRIVATE_DIALOG_INDEX
ERROR_PRIVATE_DIALOG_INDEX  1415L  winerror.h


ERROR_PRIVILEGE_NOT_HELD
ERROR_PRIVILEGE_NOT_HELD  1314L  winerror.h

A required privilege is not held by the client.


FN_ERROR_PRIVILEGE_NOT_HELD
ERROR_PRIVILEGE_NOT_HELD  1314L  winerror.h


ERROR_PROC_NOT_FOUND
ERROR_PROC_NOT_FOUND  127L  winerror.h

The specified procedure could not be found.


FN_ERROR_PROC_NOT_FOUND
ERROR_PROC_NOT_FOUND  127L  winerror.h


ERROR_PROCESS_ABORTED
ERROR_PROCESS_ABORTED  1067L  winerror.h

The process terminated unexpectedly.


FN_ERROR_PROCESS_ABORTED
ERROR_PROCESS_ABORTED  1067L  winerror.h


ERROR_READ_FAULT
ERROR_READ_FAULT  30L  winerror.h

The system cannot read from the specified device.


FN_ERROR_READ_FAULT
ERROR_READ_FAULT  30L  winerror.h


ERROR_REDIR_PAUSED
ERROR_REDIR_PAUSED  72L  winerror.h

The specified printer or disk device has been paused.


FN_ERROR_REDIR_PAUSED
ERROR_REDIR_PAUSED  72L  winerror.h


ERROR_REDIRECTOR_HAS_OPEN_HANDLES
ERROR_REDIRECTOR_HAS_OPEN_HANDLES  1794L  winerror.h

The redirector is in use and cannot be unloaded.


FN_ERROR_REDIRECTOR_HAS_OPEN_HANDLES
ERROR_REDIRECTOR_HAS_OPEN_HANDLES  1794L  winerror.h


ERROR_REGISTRY_CORRUPT
ERROR_REGISTRY_CORRUPT  1015L  winerror.h

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.


FN_ERROR_REGISTRY_CORRUPT
ERROR_REGISTRY_CORRUPT  1015L  winerror.h


ERROR_REGISTRY_IO_FAILED
ERROR_REGISTRY_IO_FAILED  1016L  winerror.h

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.


FN_ERROR_REGISTRY_IO_FAILED
ERROR_REGISTRY_IO_FAILED  1016L  winerror.h


ERROR_REGISTRY_RECOVERED
ERROR_REGISTRY_RECOVERED  1014L  winerror.h

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.


FN_ERROR_REGISTRY_RECOVERED
ERROR_REGISTRY_RECOVERED  1014L  winerror.h


ERROR_RELOC_CHAIN_XEEDS_SEGLIM
ERROR_RELOC_CHAIN_XEEDS_SEGLIM  201L  winerror.h

The operating system cannot run %1.


FN_ERROR_RELOC_CHAIN_XEEDS_SEGLIM
ERROR_RELOC_CHAIN_XEEDS_SEGLIM  201L  winerror.h


ERROR_REM_NOT_LIST
ERROR_REM_NOT_LIST  51L  winerror.h

The remote computer is not available.


FN_ERROR_REM_NOT_LIST
ERROR_REM_NOT_LIST  51L  winerror.h


ERROR_REMOTE_SESSION_LIMIT_EXCEEDED
ERROR_REMOTE_SESSION_LIMIT_EXCEEDED  1220L  winerror.h

An attempt was made to establish a session to a Lan Manager server, but there are already too many sessions established to that server.


FN_ERROR_REMOTE_SESSION_LIMIT_EXCEEDED
ERROR_REMOTE_SESSION_LIMIT_EXCEEDED  1220L  winerror.h


ERROR_REQ_NOT_ACCEP
ERROR_REQ_NOT_ACCEP  71L  winerror.h

The network request was not accepted.


FN_ERROR_REQ_NOT_ACCEP
ERROR_REQ_NOT_ACCEP  71L  winerror.h


ERROR_NOT_ENOUGH_QUOTA
ERROR_NOT_ENOUGH_QUOTA  1816L  winerror.h

Not enough quota is available to process this command.


FN_ERROR_NOT_ENOUGH_QUOTA
ERROR_NOT_ENOUGH_QUOTA  1816L  winerror.h


ERROR_RESOURCE_DATA_NOT_FOUND
ERROR_RESOURCE_DATA_NOT_FOUND  1812L  winerror.h

The specified image file did not contain a resource section.


FN_ERROR_RESOURCE_DATA_NOT_FOUND
ERROR_RESOURCE_DATA_NOT_FOUND  1812L  winerror.h


ERROR_RESOURCE_LANG_NOT_FOUND
ERROR_RESOURCE_LANG_NOT_FOUND  1815L  winerror.h

The specified resource language ID cannot be found in the image file.


FN_ERROR_RESOURCE_LANG_NOT_FOUND
ERROR_RESOURCE_LANG_NOT_FOUND  1815L  winerror.h


ERROR_RESOURCE_NAME_NOT_FOUND
ERROR_RESOURCE_NAME_NOT_FOUND  1814L  winerror.h

The specified resource name can not be found in the image file.


FN_ERROR_RESOURCE_NAME_NOT_FOUND
ERROR_RESOURCE_NAME_NOT_FOUND  1814L  winerror.h


ERROR_RESOURCE_TYPE_NOT_FOUND
ERROR_RESOURCE_TYPE_NOT_FOUND  1813L  winerror.h

The specified resource type can not be found in the image file.


FN_ERROR_RESOURCE_TYPE_NOT_FOUND
ERROR_RESOURCE_TYPE_NOT_FOUND  1813L  winerror.h


ERROR_REVISION_MISMATCH
ERROR_REVISION_MISMATCH  1306L  winerror.h

Indicates two revision levels are incompatible.


FN_ERROR_REVISION_MISMATCH
ERROR_REVISION_MISMATCH  1306L  winerror.h


ERROR_RING2_STACK_IN_USE
ERROR_RING2_STACK_IN_USE  207L  winerror.h

The ring 2 stack is in use.


FN_ERROR_RING2_STACK_IN_USE
ERROR_RING2_STACK_IN_USE  207L  winerror.h


ERROR_RING2SEG_MUST_BE_MOVABLE
ERROR_RING2SEG_MUST_BE_MOVABLE  200L  winerror.h

The code segment cannot be greater than or equal to 64KB.


FN_ERROR_RING2SEG_MUST_BE_MOVABLE
ERROR_RING2SEG_MUST_BE_MOVABLE  200L  winerror.h


ERROR_RXACT_COMMIT_FAILURE
ERROR_RXACT_COMMIT_FAILURE  1370L  winerror.h

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


FN_ERROR_RXACT_COMMIT_FAILURE
ERROR_RXACT_COMMIT_FAILURE  1370L  winerror.h


ERROR_RXACT_INVALID_STATE
ERROR_RXACT_INVALID_STATE  1369L  winerror.h

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


FN_ERROR_RXACT_INVALID_STATE
ERROR_RXACT_INVALID_STATE  1369L  winerror.h


ERROR_SAME_DRIVE
ERROR_SAME_DRIVE  143L  winerror.h

The system cannot join or substitute a drive to or for a directory on the same drive.


FN_ERROR_SAME_DRIVE
ERROR_SAME_DRIVE  143L  winerror.h


ERROR_SCREEN_ALREADY_LOCKED
ERROR_SCREEN_ALREADY_LOCKED  1440L  winerror.h

Screen already locked.


FN_ERROR_SCREEN_ALREADY_LOCKED
ERROR_SCREEN_ALREADY_LOCKED  1440L  winerror.h


ERROR_SECRET_TOO_LONG
ERROR_SECRET_TOO_LONG  1382L  winerror.h

The length of an secret exceeds the maximum length allowed. The length and number of secrets is limited to satisfy the United States State Department export restrictions.


FN_ERROR_SECRET_TOO_LONG
ERROR_SECRET_TOO_LONG  1382L  winerror.h


ERROR_SECTOR_NOT_FOUND
ERROR_SECTOR_NOT_FOUND  27L  winerror.h

The drive cannot find the requested sector.


FN_ERROR_SECTOR_NOT_FOUND
ERROR_SECTOR_NOT_FOUND  27L  winerror.h


ERROR_SEEK
ERROR_SEEK  25L  winerror.h

The drive cannot locate a specific area or track on the disk.


FN_ERROR_SEEK
ERROR_SEEK  25L  winerror.h


ERROR_SEEK_ON_DEVICE
ERROR_SEEK_ON_DEVICE  132L  winerror.h

The file pointer cannot be set on the specified device or file.


FN_ERROR_SEEK_ON_DEVICE
ERROR_SEEK_ON_DEVICE  132L  winerror.h


ERROR_SEM_IS_SET
ERROR_SEM_IS_SET  102L  winerror.h

The semaphore is set and cannot be closed.


FN_ERROR_SEM_IS_SET
ERROR_SEM_IS_SET  102L  winerror.h


ERROR_SEM_NOT_FOUND
ERROR_SEM_NOT_FOUND  187L  winerror.h

The specified system semaphore name was not found.


FN_ERROR_SEM_NOT_FOUND
ERROR_SEM_NOT_FOUND  187L  winerror.h


ERROR_SEM_OWNER_DIED
ERROR_SEM_OWNER_DIED  105L  winerror.h

The previous ownership of this semaphore has ended.


FN_ERROR_SEM_OWNER_DIED
ERROR_SEM_OWNER_DIED  105L  winerror.h


ERROR_SEM_TIMEOUT
ERROR_SEM_TIMEOUT  121L  winerror.h

The semaphore timeout period has expired.


FN_ERROR_SEM_TIMEOUT
ERROR_SEM_TIMEOUT  121L  winerror.h


ERROR_SEM_USER_LIMIT
ERROR_SEM_USER_LIMIT  106L  winerror.h

Insert the disk for drive 1.


FN_ERROR_SEM_USER_LIMIT
ERROR_SEM_USER_LIMIT  106L  winerror.h


ERROR_SERIAL_NO_DEVICE
ERROR_SERIAL_NO_DEVICE  1118L  winerror.h

No serial device was successfully initialized. The serial driver will unload.


FN_ERROR_SERIAL_NO_DEVICE
ERROR_SERIAL_NO_DEVICE  1118L  winerror.h


ERROR_SERVER_DISABLED
ERROR_SERVER_DISABLED  1341L  winerror.h

The GUID allocation server is already disabled at the moment.


FN_ERROR_SERVER_DISABLED
ERROR_SERVER_DISABLED  1341L  winerror.h


ERROR_SERVER_HAS_OPEN_HANDLES
ERROR_SERVER_HAS_OPEN_HANDLES  1811L  winerror.h

The server is in use and cannot be unloaded.


FN_ERROR_SERVER_HAS_OPEN_HANDLES
ERROR_SERVER_HAS_OPEN_HANDLES  1811L  winerror.h


ERROR_SERVER_NOT_DISABLED
ERROR_SERVER_NOT_DISABLED  1342L  winerror.h

The GUID allocation server is already enabled at the moment.


FN_ERROR_SERVER_NOT_DISABLED
ERROR_SERVER_NOT_DISABLED  1342L  winerror.h


ERROR_SERVICE_ALREADY_RUNNING
ERROR_SERVICE_ALREADY_RUNNING  1056L  winerror.h

An instance of the service is already running.


FN_ERROR_SERVICE_ALREADY_RUNNING
ERROR_SERVICE_ALREADY_RUNNING  1056L  winerror.h


ERROR_SERVICE_CANNOT_ACCEPT_CTRL
ERROR_SERVICE_CANNOT_ACCEPT_CTRL  1061L  winerror.h

The service cannot accept control messages at this time.


FN_ERROR_SERVICE_CANNOT_ACCEPT_CTRL
ERROR_SERVICE_CANNOT_ACCEPT_CTRL  1061L  winerror.h


ERROR_SERVICE_DATABASE_LOCKED
ERROR_SERVICE_DATABASE_LOCKED  1055L  winerror.h

The service database is locked.


FN_ERROR_SERVICE_DATABASE_LOCKED
ERROR_SERVICE_DATABASE_LOCKED  1055L  winerror.h


ERROR_SERVICE_DEPENDENCY_DELETED
ERROR_SERVICE_DEPENDENCY_DELETED  1075L  winerror.h

The dependency service does not exist or has been marked for deletion.


FN_ERROR_SERVICE_DEPENDENCY_DELETED
ERROR_SERVICE_DEPENDENCY_DELETED  1075L  winerror.h


ERROR_SERVICE_DEPENDENCY_FAIL
ERROR_SERVICE_DEPENDENCY_FAIL  1068L  winerror.h

The dependency service or group failed to start.


FN_ERROR_SERVICE_DEPENDENCY_FAIL
ERROR_SERVICE_DEPENDENCY_FAIL  1068L  winerror.h


ERROR_SERVICE_DISABLED
ERROR_SERVICE_DISABLED  1058L  winerror.h

The specified service is disabled and cannot be started.


FN_ERROR_SERVICE_DISABLED
ERROR_SERVICE_DISABLED  1058L  winerror.h


ERROR_SERVICE_DOES_NOT_EXIST
ERROR_SERVICE_DOES_NOT_EXIST  1060L  winerror.h

The specified service does not exist as an installed service.


FN_ERROR_SERVICE_DOES_NOT_EXIST
ERROR_SERVICE_DOES_NOT_EXIST  1060L  winerror.h


ERROR_SERVICE_EXISTS
ERROR_SERVICE_EXISTS  1073L  winerror.h

The specified service already exists.


FN_ERROR_SERVICE_EXISTS
ERROR_SERVICE_EXISTS  1073L  winerror.h


ERROR_SERVICE_LOGON_FAILED
ERROR_SERVICE_LOGON_FAILED  1069L  winerror.h

The service did not start due to a logon failure.


FN_ERROR_SERVICE_LOGON_FAILED
ERROR_SERVICE_LOGON_FAILED  1069L  winerror.h


ERROR_SERVICE_MARKED_FOR_DELETE
ERROR_SERVICE_MARKED_FOR_DELETE  1072L  winerror.h

The specified service has been marked for deletion.


FN_ERROR_SERVICE_MARKED_FOR_DELETE
ERROR_SERVICE_MARKED_FOR_DELETE  1072L  winerror.h


ERROR_SERVICE_NEVER_STARTED
ERROR_SERVICE_NEVER_STARTED  1077L  winerror.h

No attempts to start the service have been made since the last boot.


FN_ERROR_SERVICE_NEVER_STARTED
ERROR_SERVICE_NEVER_STARTED  1077L  winerror.h


ERROR_SERVICE_NO_THREAD
ERROR_SERVICE_NO_THREAD  1054L  winerror.h

A thread could not be created for the service.


FN_ERROR_SERVICE_NO_THREAD
ERROR_SERVICE_NO_THREAD  1054L  winerror.h


ERROR_SERVICE_NOT_ACTIVE
ERROR_SERVICE_NOT_ACTIVE  1062L  winerror.h

The service has not been started.


FN_ERROR_SERVICE_NOT_ACTIVE
ERROR_SERVICE_NOT_ACTIVE  1062L  winerror.h


ERROR_SERVICE_REQUEST_TIMEOUT
ERROR_SERVICE_REQUEST_TIMEOUT  1053L  winerror.h

The service did not respond to the start or control request in a timely fashion.


FN_ERROR_SERVICE_REQUEST_TIMEOUT
ERROR_SERVICE_REQUEST_TIMEOUT  1053L  winerror.h


ERROR_SERVICE_SPECIFIC_ERROR
ERROR_SERVICE_SPECIFIC_ERROR  1066L  winerror.h

The service has returned a service-specific error code.


FN_ERROR_SERVICE_SPECIFIC_ERROR
ERROR_SERVICE_SPECIFIC_ERROR  1066L  winerror.h


ERROR_SERVICE_START_HANG
ERROR_SERVICE_START_HANG  1070L  winerror.h

After starting, the service hung in a start-pending state.


FN_ERROR_SERVICE_START_HANG
ERROR_SERVICE_START_HANG  1070L  winerror.h


ERROR_SESSION_CREDENTIAL_CONFLICT
ERROR_SESSION_CREDENTIAL_CONFLICT  1219L  winerror.h

The credentials supplied conflict with an existing set of credentials.


FN_ERROR_SESSION_CREDENTIAL_CONFLICT
ERROR_SESSION_CREDENTIAL_CONFLICT  1219L  winerror.h


ERROR_SETCOUNT_ON_BAD_LB
ERROR_SETCOUNT_ON_BAD_LB  1433L  winerror.h

LB_SETCOUNT sent to non-lazy list box.


FN_ERROR_SETCOUNT_ON_BAD_LB
ERROR_SETCOUNT_ON_BAD_LB  1433L  winerror.h


ERROR_SETMARK_DETECTED
ERROR_SETMARK_DETECTED  1103L  winerror.h

A tape access reached a setmark.


FN_ERROR_SETMARK_DETECTED
ERROR_SETMARK_DETECTED  1103L  winerror.h


ERROR_SHARING_BUFFER_EXCEEDED
ERROR_SHARING_BUFFER_EXCEEDED  36L  winerror.h

Too many files opened for sharing.


FN_ERROR_SHARING_BUFFER_EXCEEDED
ERROR_SHARING_BUFFER_EXCEEDED  36L  winerror.h


ERROR_SHARING_PAUSED
ERROR_SHARING_PAUSED  70L  winerror.h

The remote server is paused or is in the process of being started.


FN_ERROR_SHARING_PAUSED
ERROR_SHARING_PAUSED  70L  winerror.h


ERROR_SHARING_VIOLATION
ERROR_SHARING_VIOLATION  32L  winerror.h

The process cannot access the file because it is being used by another process.


FN_ERROR_SHARING_VIOLATION
ERROR_SHARING_VIOLATION  32L  winerror.h


ERROR_SHUTDOWN_IN_PROGRESS
ERROR_SHUTDOWN_IN_PROGRESS  1115L  winerror.h

A system shutdown is in progress.


FN_ERROR_SHUTDOWN_IN_PROGRESS
ERROR_SHUTDOWN_IN_PROGRESS  1115L  winerror.h


ERROR_SIGNAL_PENDING
ERROR_SIGNAL_PENDING  162L  winerror.h

A signal is already pending.


FN_ERROR_SIGNAL_PENDING
ERROR_SIGNAL_PENDING  162L  winerror.h


ERROR_SIGNAL_REFUSED
ERROR_SIGNAL_REFUSED  156L  winerror.h

The recipient process has refused the signal.


FN_ERROR_SIGNAL_REFUSED
ERROR_SIGNAL_REFUSED  156L  winerror.h


ERROR_SOME_NOT_MAPPED
ERROR_SOME_NOT_MAPPED  1301L  winerror.h

Some of the information to be mapped has not been translated.


FN_ERROR_SOME_NOT_MAPPED
ERROR_SOME_NOT_MAPPED  1301L  winerror.h


ERROR_SPECIAL_ACCOUNT
ERROR_SPECIAL_ACCOUNT  1371L  winerror.h

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.


FN_ERROR_SPECIAL_ACCOUNT
ERROR_SPECIAL_ACCOUNT  1371L  winerror.h


ERROR_SPECIAL_GROUP
ERROR_SPECIAL_GROUP  1372L  winerror.h

The requested operation cannot be performed on the specified group because it is a built-in special group.


FN_ERROR_SPECIAL_GROUP
ERROR_SPECIAL_GROUP  1372L  winerror.h


ERROR_SPECIAL_USER
ERROR_SPECIAL_USER  1373L  winerror.h

The requested operation cannot be performed on the specified user because it is a built-in special user.


FN_ERROR_SPECIAL_USER
ERROR_SPECIAL_USER  1373L  winerror.h


ERROR_STACK_OVERFLOW
ERROR_STACK_OVERFLOW  1001L  winerror.h

Recursion too deep, stack overflowed.


FN_ERROR_STACK_OVERFLOW
ERROR_STACK_OVERFLOW  1001L  winerror.h


ERROR_SUBST_TO_JOIN
ERROR_SUBST_TO_JOIN  141L  winerror.h

The system attempted to SUBST a drive to a directory on a joined drive.


FN_ERROR_SUBST_TO_JOIN
ERROR_SUBST_TO_JOIN  141L  winerror.h


ERROR_SUBST_TO_SUBST
ERROR_SUBST_TO_SUBST  139L  winerror.h

The system attempted to substitute a drive to a directory on a substituted drive.


FN_ERROR_SUBST_TO_SUBST
ERROR_SUBST_TO_SUBST  139L  winerror.h


ERROR_SUCCESS
ERROR_SUCCESS  0L  winerror.h

The operation was successfully completed.


FN_ERROR_SUCCESS
ERROR_SUCCESS  0L  winerror.h


ERROR_SWAPERROR
ERROR_SWAPERROR  999L  winerror.h

Error accessing paging file.


FN_ERROR_SWAPERROR
ERROR_SWAPERROR  999L  winerror.h


ERROR_SYSTEM_TRACE
ERROR_SYSTEM_TRACE  150L  winerror.h

System trace information not specified in your CONFIG.SYS file, or tracing is not allowed.


FN_ERROR_SYSTEM_TRACE
ERROR_SYSTEM_TRACE  150L  winerror.h


ERROR_THREAD_1_INACTIVE
ERROR_THREAD_1_INACTIVE  210L  winerror.h

The signal handler cannot be set.


FN_ERROR_THREAD_1_INACTIVE
ERROR_THREAD_1_INACTIVE  210L  winerror.h


ERROR_TLW_WITH_WSCHILD
ERROR_TLW_WITH_WSCHILD  1406L  winerror.h

CreateWindow failed, creating top-level window with WS_CHILD style.


FN_ERROR_TLW_WITH_WSCHILD
ERROR_TLW_WITH_WSCHILD  1406L  winerror.h


ERROR_TOKEN_ALREADY_IN_USE
ERROR_TOKEN_ALREADY_IN_USE  1375L  winerror.h

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.


FN_ERROR_TOKEN_ALREADY_IN_USE
ERROR_TOKEN_ALREADY_IN_USE  1375L  winerror.h


ERROR_TOO_MANY_CMDS
ERROR_TOO_MANY_CMDS  56L  winerror.h

The network BIOS command limit has been reached.


FN_ERROR_TOO_MANY_CMDS
ERROR_TOO_MANY_CMDS  56L  winerror.h


ERROR_TOO_MANY_CONTEXT_IDS
ERROR_TOO_MANY_CONTEXT_IDS  1384L  winerror.h

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.


FN_ERROR_TOO_MANY_CONTEXT_IDS
ERROR_TOO_MANY_CONTEXT_IDS  1384L  winerror.h


ERROR_TOO_MANY_LUIDS_REQUESTED
ERROR_TOO_MANY_LUIDS_REQUESTED  1333L  winerror.h

The number of LUID requested cannot be allocated with a single allocation.


FN_ERROR_TOO_MANY_LUIDS_REQUESTED
ERROR_TOO_MANY_LUIDS_REQUESTED  1333L  winerror.h


ERROR_TOO_MANY_MODULES
ERROR_TOO_MANY_MODULES  214L  winerror.h

Too many dynamic link modules are attached to this program or dynamic link module.


FN_ERROR_TOO_MANY_MODULES
ERROR_TOO_MANY_MODULES  214L  winerror.h


ERROR_TOO_MANY_MUXWAITERS
ERROR_TOO_MANY_MUXWAITERS  152L  winerror.h

Too many semaphores are already set.


FN_ERROR_TOO_MANY_MUXWAITERS
ERROR_TOO_MANY_MUXWAITERS  152L  winerror.h


ERROR_TOO_MANY_NAMES
ERROR_TOO_MANY_NAMES  68L  winerror.h

The name limit for the local computer network adapter card exceeded.


FN_ERROR_TOO_MANY_NAMES
ERROR_TOO_MANY_NAMES  68L  winerror.h


ERROR_TOO_MANY_OPEN_FILES
ERROR_TOO_MANY_OPEN_FILES  4L  winerror.h

The system cannot open the file.


FN_ERROR_TOO_MANY_OPEN_FILES
ERROR_TOO_MANY_OPEN_FILES  4L  winerror.h


ERROR_TOO_MANY_POSTS
ERROR_TOO_MANY_POSTS  298L  winerror.h

Too many posts made to a semaphore.


FN_ERROR_TOO_MANY_POSTS
ERROR_TOO_MANY_POSTS  298L  winerror.h


ERROR_TOO_MANY_SECRETS
ERROR_TOO_MANY_SECRETS  1381L  winerror.h

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.


FN_ERROR_TOO_MANY_SECRETS
ERROR_TOO_MANY_SECRETS  1381L  winerror.h


ERROR_TOO_MANY_SEM_REQUESTS
ERROR_TOO_MANY_SEM_REQUESTS  103L  winerror.h

The semaphore cannot be set again.


FN_ERROR_TOO_MANY_SEM_REQUESTS
ERROR_TOO_MANY_SEM_REQUESTS  103L  winerror.h


ERROR_TOO_MANY_SEMAPHORES
ERROR_TOO_MANY_SEMAPHORES  100L  winerror.h

Cannot create another system semaphore.


FN_ERROR_TOO_MANY_SEMAPHORES
ERROR_TOO_MANY_SEMAPHORES  100L  winerror.h


ERROR_TOO_MANY_SESS
ERROR_TOO_MANY_SESS  69L  winerror.h

The network BIOS session limit exceeded.


FN_ERROR_TOO_MANY_SESS
ERROR_TOO_MANY_SESS  69L  winerror.h


ERROR_TOO_MANY_SIDS
ERROR_TOO_MANY_SIDS  1389L  winerror.h

Too many SIDs specified.


FN_ERROR_TOO_MANY_SIDS
ERROR_TOO_MANY_SIDS  1389L  winerror.h


ERROR_TOO_MANY_TCBS
ERROR_TOO_MANY_TCBS  155L  winerror.h

Cannot create another thread.


FN_ERROR_TOO_MANY_TCBS
ERROR_TOO_MANY_TCBS  155L  winerror.h


ERROR_TRUST_FAILURE
ERROR_TRUST_FAILURE  1790L  winerror.h

The network logon failed.


FN_ERROR_TRUST_FAILURE
ERROR_TRUST_FAILURE  1790L  winerror.h


ERROR_TRUSTED_DOMAIN_FAILURE
ERROR_TRUSTED_DOMAIN_FAILURE  1788L  winerror.h

The trust relationship between the primary domain and the trusted domain failed.


FN_ERROR_TRUSTED_DOMAIN_FAILURE
ERROR_TRUSTED_DOMAIN_FAILURE  1788L  winerror.h


ERROR_TRUSTED_RELATIONSHIP_FAILURE
ERROR_TRUSTED_RELATIONSHIP_FAILURE  1789L  winerror.h

The trust relationship between this workstation and the primary domain failed.


FN_ERROR_TRUSTED_RELATIONSHIP_FAILURE
ERROR_TRUSTED_RELATIONSHIP_FAILURE  1789L  winerror.h


ERROR_UNABLE_TO_LOCK_MEDIA
ERROR_UNABLE_TO_LOCK_MEDIA  1108L  winerror.h

Attempt to lock the eject media mechanism failed.


FN_ERROR_UNABLE_TO_LOCK_MEDIA
ERROR_UNABLE_TO_LOCK_MEDIA  1108L  winerror.h


ERROR_UNABLE_TO_UNLOAD_MEDIA
ERROR_UNABLE_TO_UNLOAD_MEDIA  1109L  winerror.h

Unload media failed.


FN_ERROR_UNABLE_TO_UNLOAD_MEDIA
ERROR_UNABLE_TO_UNLOAD_MEDIA  1109L  winerror.h


ERROR_UNEXP_NET_ERR
ERROR_UNEXP_NET_ERR  59L  winerror.h

An unexpected network error occurred.


FN_ERROR_UNEXP_NET_ERR
ERROR_UNEXP_NET_ERR  59L  winerror.h


ERROR_UNKNOWN_PORT
ERROR_UNKNOWN_PORT  1796L  winerror.h

The specified port is unknown.


FN_ERROR_UNKNOWN_PORT
ERROR_UNKNOWN_PORT  1796L  winerror.h


ERROR_UNKNOWN_PRINTPROCESSOR
ERROR_UNKNOWN_PRINTPROCESSOR  1798L  winerror.h

The print processor is unknown.


FN_ERROR_UNKNOWN_PRINTPROCESSOR
ERROR_UNKNOWN_PRINTPROCESSOR  1798L  winerror.h


ERROR_UNKNOWN_PRINTER_DRIVER
ERROR_UNKNOWN_PRINTER_DRIVER  1797L  winerror.h

The printer driver is unknown.


FN_ERROR_UNKNOWN_PRINTER_DRIVER
ERROR_UNKNOWN_PRINTER_DRIVER  1797L  winerror.h


ERROR_UNKNOWN_REVISION
ERROR_UNKNOWN_REVISION  1305L  winerror.h

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.


FN_ERROR_UNKNOWN_REVISION
ERROR_UNKNOWN_REVISION  1305L  winerror.h


ERROR_UNRECOGNIZED_MEDIA
ERROR_UNRECOGNIZED_MEDIA  1785L  winerror.h

The disk media is not recognized. It may not be formatted.


FN_ERROR_UNRECOGNIZED_MEDIA
ERROR_UNRECOGNIZED_MEDIA  1785L  winerror.h


ERROR_UNRECOGNIZED_VOLUME
ERROR_UNRECOGNIZED_VOLUME  1005L  winerror.h

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.


FN_ERROR_UNRECOGNIZED_VOLUME
ERROR_UNRECOGNIZED_VOLUME  1005L  winerror.h


ERROR_USER_EXISTS
ERROR_USER_EXISTS  1316L  winerror.h

The specified user already exists.


FN_ERROR_USER_EXISTS
ERROR_USER_EXISTS  1316L  winerror.h


ERROR_VC_DISCONNECTED
ERROR_VC_DISCONNECTED  240L  winerror.h

The session was canceled.


FN_ERROR_VC_DISCONNECTED
ERROR_VC_DISCONNECTED  240L  winerror.h


ERROR_WAIT_NO_CHILDREN
ERROR_WAIT_NO_CHILDREN  128L  winerror.h

There are no child processes to wait for.


FN_ERROR_WAIT_NO_CHILDREN
ERROR_WAIT_NO_CHILDREN  128L  winerror.h


ERROR_WINDOW_NOT_COMBOBOX
ERROR_WINDOW_NOT_COMBOBOX  1423L  winerror.h

The window is not a combo box.


FN_ERROR_WINDOW_NOT_COMBOBOX
ERROR_WINDOW_NOT_COMBOBOX  1423L  winerror.h


ERROR_WINDOW_NOT_DIALOG
ERROR_WINDOW_NOT_DIALOG  1420L  winerror.h

The window is not a valid dialog window.


FN_ERROR_WINDOW_NOT_DIALOG
ERROR_WINDOW_NOT_DIALOG  1420L  winerror.h


ERROR_WINDOW_OF_OTHER_THREAD
ERROR_WINDOW_OF_OTHER_THREAD  1408L  winerror.h

Invalid window, belongs to other thread.


FN_ERROR_WINDOW_OF_OTHER_THREAD
ERROR_WINDOW_OF_OTHER_THREAD  1408L  winerror.h


ERROR_WRITE_FAULT
ERROR_WRITE_FAULT  29L  winerror.h

The system cannot write to the specified device.


FN_ERROR_WRITE_FAULT
ERROR_WRITE_FAULT  29L  winerror.h


ERROR_WRITE_PROTECT
ERROR_WRITE_PROTECT  19L  winerror.h

The media is write protected.


FN_ERROR_WRITE_PROTECT
ERROR_WRITE_PROTECT  19L  winerror.h


ERROR_WRONG_DISK
ERROR_WRONG_DISK  34L  winerror.h

The wrong disk is in the drive. Insert %2 (Volume Serial Number: %3) into drive %1.


FN_ERROR_WRONG_DISK
ERROR_WRONG_DISK  34L  winerror.h


ERROR_WRONG_PASSWORD
ERROR_WRONG_PASSWORD  1323L  winerror.h

When trying to update a password, this return status indicates the value provided as the current password is incorrect.


FN_ERROR_WRONG_PASSWORD
ERROR_WRONG_PASSWORD  1323L  winerror.h


LZERROR_BADINHANDLE
LZERROR_BADINHANDLE  (-1)    lzexpand.h

Invalid input handle.


FN_LZERROR_BADINHANDLE
LZERROR_BADINHANDLE  (-1)    lzexpand.h


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.


RPC_S_ADDRESS_ERROR
RPC_S_ADDRESS_ERROR  1768L  winerror.h

An addressing error occurred in the server.


FN_RPC_S_ADDRESS_ERROR
RPC_S_ADDRESS_ERROR  1768L  winerror.h


RPC_S_ALREADY_LISTENING
RPC_S_ALREADY_LISTENING  1713L  winerror.h

The server is already listening.


FN_RPC_S_ALREADY_LISTENING
RPC_S_ALREADY_LISTENING  1713L  winerror.h


RPC_S_ALREADY_REGISTERED
RPC_S_ALREADY_REGISTERED  1711L  winerror.h

The object UUID already registered.


FN_RPC_S_ALREADY_REGISTERED
RPC_S_ALREADY_REGISTERED  1711L  winerror.h


RPC_S_BINDING_HAS_NO_AUTH
RPC_S_BINDING_HAS_NO_AUTH  1746L  winerror.h

The binding does not contain any authentication information.


FN_RPC_S_BINDING_HAS_NO_AUTH
RPC_S_BINDING_HAS_NO_AUTH  1746L  winerror.h


RPC_S_CALL_FAILED
RPC_S_CALL_FAILED  1726L  winerror.h

The remote procedure call failed.


FN_RPC_S_CALL_FAILED
RPC_S_CALL_FAILED  1726L  winerror.h


RPC_S_CALL_FAILED_DNE
RPC_S_CALL_FAILED_DNE  1727L  winerror.h

The remote procedure call failed and did not execute.


FN_RPC_S_CALL_FAILED_DNE
RPC_S_CALL_FAILED_DNE  1727L  winerror.h


RPC_S_CALL_IN_PROGRESS
RPC_S_CALL_IN_PROGRESS  1791L  winerror.h

A remote procedure call is already in progress for this thread.


FN_RPC_S_CALL_IN_PROGRESS
RPC_S_CALL_IN_PROGRESS  1791L  winerror.h


RPC_S_CANNOT_BIND

An attempt to bind with the server failed.


RPC_S_CANNOT_SUPPORT
RPC_S_CANNOT_SUPPORT  1764L  winerror.h

The requested operation is not supported.


FN_RPC_S_CANNOT_SUPPORT
RPC_S_CANNOT_SUPPORT  1764L  winerror.h


RPC_S_CANT_CREATE_ENDPOINT
RPC_S_CANT_CREATE_ENDPOINT  1720L  winerror.h

The endpoint cannot be created.


FN_RPC_S_CANT_CREATE_ENDPOINT
RPC_S_CANT_CREATE_ENDPOINT  1720L  winerror.h


RPC_S_DUPLICATE_ENDPOINT
RPC_S_DUPLICATE_ENDPOINT  1740L  winerror.h

The endpoint is a duplicate.


FN_RPC_S_DUPLICATE_ENDPOINT
RPC_S_DUPLICATE_ENDPOINT  1740L  winerror.h


RPC_S_ENTRY_ALREADY_EXISTS
RPC_S_ENTRY_ALREADY_EXISTS  1760L  winerror.h

The entry already exists.


FN_RPC_S_ENTRY_ALREADY_EXISTS
RPC_S_ENTRY_ALREADY_EXISTS  1760L  winerror.h


RPC_S_ENTRY_NOT_FOUND
RPC_S_ENTRY_NOT_FOUND  1761L  winerror.h

The entry is not found.


FN_RPC_S_ENTRY_NOT_FOUND
RPC_S_ENTRY_NOT_FOUND  1761L  winerror.h


RPC_S_FP_DIV_ZERO
RPC_S_FP_DIV_ZERO  1769L  winerror.h

A floating point operation at the server caused a divide by zero.


FN_RPC_S_FP_DIV_ZERO
RPC_S_FP_DIV_ZERO  1769L  winerror.h


RPC_S_FP_OVERFLOW
RPC_S_FP_OVERFLOW  1771L  winerror.h

A floating point overflow occurred at the server.


FN_RPC_S_FP_OVERFLOW
RPC_S_FP_OVERFLOW  1771L  winerror.h


RPC_S_FP_UNDERFLOW
RPC_S_FP_UNDERFLOW  1770L  winerror.h

A floating point underflow occurred at the server.


FN_RPC_S_FP_UNDERFLOW
RPC_S_FP_UNDERFLOW  1770L  winerror.h


RPC_S_GROUP_MEMBER_NOT_FOUND
RPC_S_GROUP_MEMBER_NOT_FOUND  1898L  winerror.h

The group member was not found.


FN_RPC_S_GROUP_MEMBER_NOT_FOUND
RPC_S_GROUP_MEMBER_NOT_FOUND  1898L  winerror.h


RPC_S_INCOMPLETE_NAME
RPC_S_INCOMPLETE_NAME  1755L  winerror.h

The entry name is incomplete.


FN_RPC_S_INCOMPLETE_NAME
RPC_S_INCOMPLETE_NAME  1755L  winerror.h


RPC_S_INTERFACE_NOT_FOUND
RPC_S_INTERFACE_NOT_FOUND  1759L  winerror.h

The interface was not found.


FN_RPC_S_INTERFACE_NOT_FOUND
RPC_S_INTERFACE_NOT_FOUND  1759L  winerror.h


RPC_S_INTERNAL_ERROR
RPC_S_INTERNAL_ERROR  1766L  winerror.h

An internal error occurred in RPC.


FN_RPC_S_INTERNAL_ERROR
RPC_S_INTERNAL_ERROR  1766L  winerror.h


RPC_S_INVALID_AUTH_IDENTITY
RPC_S_INVALID_AUTH_IDENTITY  1749L  winerror.h

The security context is invalid.


FN_RPC_S_INVALID_AUTH_IDENTITY
RPC_S_INVALID_AUTH_IDENTITY  1749L  winerror.h


RPC_S_INVALID_BINDING
RPC_S_INVALID_BINDING  1702L  winerror.h

The binding handle is invalid.


FN_RPC_S_INVALID_BINDING
RPC_S_INVALID_BINDING  1702L  winerror.h


RPC_S_INVALID_BOUND
RPC_S_INVALID_BOUND  1734L  winerror.h

The array bounds are invalid.


FN_RPC_S_INVALID_BOUND
RPC_S_INVALID_BOUND  1734L  winerror.h


RPC_S_INVALID_ENDPOINT_FORMAT
RPC_S_INVALID_ENDPOINT_FORMAT  1706L  winerror.h

The endpoint format is invalid.


FN_RPC_S_INVALID_ENDPOINT_FORMAT
RPC_S_INVALID_ENDPOINT_FORMAT  1706L  winerror.h


RPC_S_INVALID_NAF_IF

The network address family is invalid.


RPC_S_INVALID_NAME_SYNTAX
RPC_S_INVALID_NAME_SYNTAX  1736L  winerror.h

The name syntax is invalid.


FN_RPC_S_INVALID_NAME_SYNTAX
RPC_S_INVALID_NAME_SYNTAX  1736L  winerror.h


RPC_S_INVALID_NET_ADDR
RPC_S_INVALID_NET_ADDR  1707L  winerror.h

The network address is invalid.


FN_RPC_S_INVALID_NET_ADDR
RPC_S_INVALID_NET_ADDR  1707L  winerror.h


RPC_S_INVALID_NETWORK_OPTIONS
RPC_S_INVALID_NETWORK_OPTIONS  1724L  winerror.h

The network options are invalid.


FN_RPC_S_INVALID_NETWORK_OPTIONS
RPC_S_INVALID_NETWORK_OPTIONS  1724L  winerror.h


RPC_S_INVALID_OBJECT
RPC_S_INVALID_OBJECT  1900L  winerror.h

The object universal unique identifier (UUID) is the nil UUID.


FN_RPC_S_INVALID_OBJECT
RPC_S_INVALID_OBJECT  1900L  winerror.h


RPC_S_INVALID_RPC_PROTSEQ
RPC_S_INVALID_RPC_PROTSEQ  1704L  winerror.h

The RPC protocol sequence is invalid.


FN_RPC_S_INVALID_RPC_PROTSEQ
RPC_S_INVALID_RPC_PROTSEQ  1704L  winerror.h


RPC_S_INVALID_STRING_BINDING
RPC_S_INVALID_STRING_BINDING  1700L  winerror.h

The string binding is invalid.


FN_RPC_S_INVALID_STRING_BINDING
RPC_S_INVALID_STRING_BINDING  1700L  winerror.h


RPC_S_INVALID_STRING_UUID
RPC_S_INVALID_STRING_UUID  1705L  winerror.h

The string UUID is invalid.


FN_RPC_S_INVALID_STRING_UUID
RPC_S_INVALID_STRING_UUID  1705L  winerror.h


RPC_S_INVALID_TAG
RPC_S_INVALID_TAG  1733L  winerror.h

The tag is invalid.


FN_RPC_S_INVALID_TAG
RPC_S_INVALID_TAG  1733L  winerror.h


RPC_S_INVALID_TIMEOUT
RPC_S_INVALID_TIMEOUT  1709L  winerror.h

The timeout value is invalid.


FN_RPC_S_INVALID_TIMEOUT
RPC_S_INVALID_TIMEOUT  1709L  winerror.h


RPC_S_INVALID_VERS_OPTION
RPC_S_INVALID_VERS_OPTION  1756L  winerror.h

The version option is invalid.


FN_RPC_S_INVALID_VERS_OPTION
RPC_S_INVALID_VERS_OPTION  1756L  winerror.h


RPC_S_MAX_CALLS_TOO_SMALL
RPC_S_MAX_CALLS_TOO_SMALL  1742L  winerror.h

The maximum number of calls is too small.


FN_RPC_S_MAX_CALLS_TOO_SMALL
RPC_S_MAX_CALLS_TOO_SMALL  1742L  winerror.h


RPC_S_NAME_SERVICE_UNAVAILABLE
RPC_S_NAME_SERVICE_UNAVAILABLE  1762L  winerror.h

The name service is unavailable.


FN_RPC_S_NAME_SERVICE_UNAVAILABLE
RPC_S_NAME_SERVICE_UNAVAILABLE  1762L  winerror.h


RPC_S_NO_BINDINGS
RPC_S_NO_BINDINGS  1718L  winerror.h

There are no bindings.


FN_RPC_S_NO_BINDINGS
RPC_S_NO_BINDINGS  1718L  winerror.h


RPC_S_NO_CALL_ACTIVE
RPC_S_NO_CALL_ACTIVE  1725L  winerror.h

There is not a remote procedure call active in this thread.


FN_RPC_S_NO_CALL_ACTIVE
RPC_S_NO_CALL_ACTIVE  1725L  winerror.h


RPC_S_NO_CONTEXT_AVAILABLE
RPC_S_NO_CONTEXT_AVAILABLE  1765L  winerror.h

No security context is available to allow impersonation.


FN_RPC_S_NO_CONTEXT_AVAILABLE
RPC_S_NO_CONTEXT_AVAILABLE  1765L  winerror.h


RPC_S_NO_ENDPOINT_FOUND
RPC_S_NO_ENDPOINT_FOUND  1708L  winerror.h

No endpoint was found.


FN_RPC_S_NO_ENDPOINT_FOUND
RPC_S_NO_ENDPOINT_FOUND  1708L  winerror.h


RPC_S_NO_ENTRY_NAME
RPC_S_NO_ENTRY_NAME  1735L  winerror.h

The binding does not contain an entry name.


FN_RPC_S_NO_ENTRY_NAME
RPC_S_NO_ENTRY_NAME  1735L  winerror.h


RPC_S_NO_INTERFACES_EXPORTED

No interfaces were exported.


RPC_S_NO_MORE_BINDINGS
RPC_S_NO_MORE_BINDINGS  1806L  winerror.h

There are no more bindings.


FN_RPC_S_NO_MORE_BINDINGS
RPC_S_NO_MORE_BINDINGS  1806L  winerror.h


RPC_S_NO_MORE_MEMBERS
RPC_S_NO_MORE_MEMBERS  1757L  winerror.h

There are no more members.


FN_RPC_S_NO_MORE_MEMBERS
RPC_S_NO_MORE_MEMBERS  1757L  winerror.h


RPC_S_NO_PROTSEQS
RPC_S_NO_PROTSEQS  1719L  winerror.h

There are no protocol sequences.


FN_RPC_S_NO_PROTSEQS
RPC_S_NO_PROTSEQS  1719L  winerror.h


RPC_S_NO_PROTSEQS_REGISTERED
RPC_S_NO_PROTSEQS_REGISTERED  1714L  winerror.h

No protocol sequences were registered.


FN_RPC_S_NO_PROTSEQS_REGISTERED
RPC_S_NO_PROTSEQS_REGISTERED  1714L  winerror.h


RPC_S_NOT_LISTENING
RPC_S_NOT_LISTENING  1715L  winerror.h

The server is not listening.


FN_RPC_S_NOT_LISTENING
RPC_S_NOT_LISTENING  1715L  winerror.h


RPC_S_NOTHING_TO_UNEXPORT

There is nothing to unexport.


RPC_S_OBJECT_NOT_FOUND
RPC_S_OBJECT_NOT_FOUND  1710L  winerror.h

The object UUID was not found.


FN_RPC_S_OBJECT_NOT_FOUND
RPC_S_OBJECT_NOT_FOUND  1710L  winerror.h


RPC_S_OUT_OF_RESOURCES
RPC_S_OUT_OF_RESOURCES  1721L  winerror.h

Not enough resources are available to complete this operation.


FN_RPC_S_OUT_OF_RESOURCES
RPC_S_OUT_OF_RESOURCES  1721L  winerror.h


RPC_S_PROCNUM_OUT_OF_RANGE
RPC_S_PROCNUM_OUT_OF_RANGE  1745L  winerror.h

The procedure number is out of range.


FN_RPC_S_PROCNUM_OUT_OF_RANGE
RPC_S_PROCNUM_OUT_OF_RANGE  1745L  winerror.h


RPC_S_PROTOCOL_ERROR
RPC_S_PROTOCOL_ERROR  1728L  winerror.h

An RPC protocol error occurred.


FN_RPC_S_PROTOCOL_ERROR
RPC_S_PROTOCOL_ERROR  1728L  winerror.h


RPC_S_PROTSEQ_NOT_FOUND
RPC_S_PROTSEQ_NOT_FOUND  1744L  winerror.h

The RPC protocol sequence was not found.


FN_RPC_S_PROTSEQ_NOT_FOUND
RPC_S_PROTSEQ_NOT_FOUND  1744L  winerror.h


RPC_S_PROTSEQ_NOT_SUPPORTED
RPC_S_PROTSEQ_NOT_SUPPORTED  1703L  winerror.h

The RPC protocol sequence is not supported.


FN_RPC_S_PROTSEQ_NOT_SUPPORTED
RPC_S_PROTSEQ_NOT_SUPPORTED  1703L  winerror.h


RPC_S_SERVER_NOT_LISTENING

The server is not listening for remote procedure calls.


RPC_S_SERVER_OUT_OF_MEMORY
RPC_S_SERVER_OUT_OF_MEMORY  ERROR_NOT_ENOUGH_SERVER_MEMORY  rpcnterr.h

The server has insufficient memory to complete this operation.


FN_RPC_S_SERVER_OUT_OF_MEMORY
RPC_S_SERVER_OUT_OF_MEMORY  ERROR_NOT_ENOUGH_SERVER_MEMORY  rpcnterr.h


RPC_S_SERVER_TOO_BUSY
RPC_S_SERVER_TOO_BUSY  1723L  winerror.h

The server is too busy to complete this operation.


FN_RPC_S_SERVER_TOO_BUSY
RPC_S_SERVER_TOO_BUSY  1723L  winerror.h


RPC_S_SERVER_UNAVAILABLE
RPC_S_SERVER_UNAVAILABLE  1722L  winerror.h

The server is unavailable.


FN_RPC_S_SERVER_UNAVAILABLE
RPC_S_SERVER_UNAVAILABLE  1722L  winerror.h


RPC_S_STRING_TOO_LONG
RPC_S_STRING_TOO_LONG  1743L  winerror.h

The string is too long.


FN_RPC_S_STRING_TOO_LONG
RPC_S_STRING_TOO_LONG  1743L  winerror.h


RPC_S_TYPE_ALREADY_REGISTERED
RPC_S_TYPE_ALREADY_REGISTERED  1712L  winerror.h

The type UUID is already registered.


FN_RPC_S_TYPE_ALREADY_REGISTERED
RPC_S_TYPE_ALREADY_REGISTERED  1712L  winerror.h


RPC_S_UNKNOWN_AUTHN_LEVEL
RPC_S_UNKNOWN_AUTHN_LEVEL  1748L  winerror.h

The authentication level is unknown.


FN_RPC_S_UNKNOWN_AUTHN_LEVEL
RPC_S_UNKNOWN_AUTHN_LEVEL  1748L  winerror.h


RPC_S_UNKNOWN_AUTHN_SERVICE
RPC_S_UNKNOWN_AUTHN_SERVICE  1747L  winerror.h

The authentication service is unknown.


FN_RPC_S_UNKNOWN_AUTHN_SERVICE
RPC_S_UNKNOWN_AUTHN_SERVICE  1747L  winerror.h


RPC_S_UNKNOWN_AUTHN_TYPE
RPC_S_UNKNOWN_AUTHN_TYPE  1741L  winerror.h

The authentication type is unknown.


FN_RPC_S_UNKNOWN_AUTHN_TYPE
RPC_S_UNKNOWN_AUTHN_TYPE  1741L  winerror.h


RPC_S_UNKNOWN_AUTHZ_SERVICE
RPC_S_UNKNOWN_AUTHZ_SERVICE  1750L  winerror.h

The authorization service is unknown.


FN_RPC_S_UNKNOWN_AUTHZ_SERVICE
RPC_S_UNKNOWN_AUTHZ_SERVICE  1750L  winerror.h


RPC_S_UNKNOWN_IF
RPC_S_UNKNOWN_IF  1717L  winerror.h

The interface is unknown.


FN_RPC_S_UNKNOWN_IF
RPC_S_UNKNOWN_IF  1717L  winerror.h


RPC_S_UNKNOWN_MGR_TYPE
RPC_S_UNKNOWN_MGR_TYPE  1716L  winerror.h

The manager type is unknown.


FN_RPC_S_UNKNOWN_MGR_TYPE
RPC_S_UNKNOWN_MGR_TYPE  1716L  winerror.h


RPC_S_UNSUPPORTED_NAME_SYNTAX
RPC_S_UNSUPPORTED_NAME_SYNTAX  1737L  winerror.h

The name syntax is not supported.


FN_RPC_S_UNSUPPORTED_NAME_SYNTAX
RPC_S_UNSUPPORTED_NAME_SYNTAX  1737L  winerror.h


RPC_S_UNSUPPORTED_TRANS_SYN
RPC_S_UNSUPPORTED_TRANS_SYN  1730L  winerror.h

The transfer syntax is not supported by the server.


FN_RPC_S_UNSUPPORTED_TRANS_SYN
RPC_S_UNSUPPORTED_TRANS_SYN  1730L  winerror.h


RPC_S_UNSUPPORTED_TYPE
RPC_S_UNSUPPORTED_TYPE  1732L  winerror.h

The type UUID is not supported.


FN_RPC_S_UNSUPPORTED_TYPE
RPC_S_UNSUPPORTED_TYPE  1732L  winerror.h


RPC_S_UUID_NO_ADDRESS
RPC_S_UUID_NO_ADDRESS  1739L  winerror.h

No network address is available to use to construct a UUID.


FN_RPC_S_UUID_NO_ADDRESS
RPC_S_UUID_NO_ADDRESS  1739L  winerror.h


RPC_S_WRONG_KIND_OF_BINDING
RPC_S_WRONG_KIND_OF_BINDING  1701L  winerror.h

The binding handle is the incorrect type.


FN_RPC_S_WRONG_KIND_OF_BINDING
RPC_S_WRONG_KIND_OF_BINDING  1701L  winerror.h


RPC_S_ZERO_DIVIDE
RPC_S_ZERO_DIVIDE  1767L  winerror.h

The server attempted an integer divide by zero.


FN_RPC_S_ZERO_DIVIDE
RPC_S_ZERO_DIVIDE  1767L  winerror.h


RPC_X_BAD_STUB_DATA
RPC_X_BAD_STUB_DATA  1783L  winerror.h

The stub received bad data.


FN_RPC_X_BAD_STUB_DATA
RPC_X_BAD_STUB_DATA  1783L  winerror.h


RPC_X_BYTE_COUNT_TOO_SMALL
RPC_X_BYTE_COUNT_TOO_SMALL  1782L  winerror.h

The byte count is too small.


FN_RPC_X_BYTE_COUNT_TOO_SMALL
RPC_X_BYTE_COUNT_TOO_SMALL  1782L  winerror.h


RPC_X_ENUM_VALUE_OUT_OF_RANGE
RPC_X_ENUM_VALUE_OUT_OF_RANGE  1781L  winerror.h

The enumeration value is out of range.


FN_RPC_X_ENUM_VALUE_OUT_OF_RANGE
RPC_X_ENUM_VALUE_OUT_OF_RANGE  1781L  winerror.h


RPC_X_NO_MORE_ENTRIES
RPC_X_NO_MORE_ENTRIES  1772L  winerror.h

The list of servers available for auto_handle binding was exhausted.


FN_RPC_X_NO_MORE_ENTRIES
RPC_X_NO_MORE_ENTRIES  1772L  winerror.h


RPC_X_NULL_REF_POINTER
RPC_X_NULL_REF_POINTER  1780L  winerror.h

A null reference pointer was passed to the stub.


FN_RPC_X_NULL_REF_POINTER
RPC_X_NULL_REF_POINTER  1780L  winerror.h


RPC_X_SS_CANNOT_GET_CALL_HANDLE
RPC_X_SS_CANNOT_GET_CALL_HANDLE  1779L  winerror.h

The stub is unable to get the call handle.


FN_RPC_X_SS_CANNOT_GET_CALL_HANDLE
RPC_X_SS_CANNOT_GET_CALL_HANDLE  1779L  winerror.h


RPC_X_SS_CHAR_TRANS_OPEN_FAIL
RPC_X_SS_CHAR_TRANS_OPEN_FAIL  1773L  winerror.h

The file designated by DCERPCCHARTRANS cannot be opened.


FN_RPC_X_SS_CHAR_TRANS_OPEN_FAIL
RPC_X_SS_CHAR_TRANS_OPEN_FAIL  1773L  winerror.h


RPC_X_SS_CHAR_TRANS_SHORT_FILE
RPC_X_SS_CHAR_TRANS_SHORT_FILE  1774L  winerror.h

The file containing the character translation table has fewer than 512 bytes.


FN_RPC_X_SS_CHAR_TRANS_SHORT_FILE
RPC_X_SS_CHAR_TRANS_SHORT_FILE  1774L  winerror.h


RPC_X_SS_CONTEXT_DAMAGED
RPC_X_SS_CONTEXT_DAMAGED  1777L  winerror.h

The context handle changed during a call.


FN_RPC_X_SS_CONTEXT_DAMAGED
RPC_X_SS_CONTEXT_DAMAGED  1777L  winerror.h


RPC_X_SS_CONTEXT_MISMATCH
RPC_X_SS_CONTEXT_MISMATCH  ERROR_INVALID_HANDLE  rpcnterr.h

The context handle does not match any known context handles.


FN_RPC_X_SS_CONTEXT_MISMATCH
RPC_X_SS_CONTEXT_MISMATCH  ERROR_INVALID_HANDLE  rpcnterr.h


RPC_X_SS_HANDLES_MISMATCH
RPC_X_SS_HANDLES_MISMATCH  1778L  winerror.h

The binding handles passed to a remote procedure call do not match.


FN_RPC_X_SS_HANDLES_MISMATCH
RPC_X_SS_HANDLES_MISMATCH  1778L  winerror.h


RPC_X_SS_IN_NULL_CONTEXT
RPC_X_SS_IN_NULL_CONTEXT  1775L  winerror.h

A null context handle is passed as an [in] parameter.


FN_RPC_X_SS_IN_NULL_CONTEXT
RPC_X_SS_IN_NULL_CONTEXT  1775L  winerror.h


Virtual Key Codes

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 name	Value (in hex)	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

--	5B-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

--	F6-FE	Unassigned


Locale Identifiers

™. The information presented here pertains to locale identifiers, LCTYPE constants, country codes, and language identifiers.

Locale Identifiers (LCIDs)

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

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:

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:

Identifier	Sublanguage/Locale	Language Code

0x0419	Russian	RUS

The following sublanguage/locale uses an other script:

Identifier	Sublanguage/Locale	Language Code

0x0408	Greek	ELL

The following special identifiers are also defined:

Identifier	Sublanguage/Locale

0x0000	Language-Neutral

0x0400	Process Default Language


Multimedia Manufacturer and Product Identifiers

Introduction

This appendix provides lists of the manufacturer and product identifiers currently used with the Microsoft® Windows™ operating system with Multimedia Extensions. This list will grow as more manufacturers create multimedia products for Windows.

To get a current list of manufacturer and product identifiers for the Multimedia Extensions, and to register new ones, request a Multimedia Developer Registration Kit from the following group:

Microsoft Corporation

Multimedia Systems Group

Product Marketing

One Microsoft Way

Redmond, WA 98052-6399

Manufacturer Identifiers

Following are the current manufacturer identifiers for the Multimedia Extensions.

Constant	Value	Description

MM_MICROSOFT	1	Drivers developed by Microsoft Corporation

Product Identifiers

Following are the current product identifiers for the Multimedia Extensions.

Constant	Value	Description

MM_MIDI_MAPPER	1	Microsoft MIDI Mapper

MM_SNDBLST_MIDIOUT	3	Sound Blaster™ MIDI output port

MM_SNDBLST_MIDIIN	4	Sound Blaster MIDI input port

MM_SNDBLST_SYNTH	5	Sound Blaster internal synthesizer

MM_SNDBLST_WAVEOUT	6	Sound Blaster waveform output port

MM_SNDBLST_WAVEIN	7	Sound Blaster waveform input port

MM_ADLIB	9	Ad Lib® (or compatible) synthesizer

MM_MPU401_MIDIOUT	10	Roland® MPU-401 MIDI output port

MM_MPU401_MIDIIN	11	Roland MPU-401 MIDI input port

MM_PC_JOYSTICK	12	IBM® Game Control Adapter


MCI Command String Syntax Summary

Introduction

This appendix provides a summary of the syntax of the MCI command strings.

The following topics are included in this appendix:

About the Command Tables

System Command Set

Required Command Set

Basic Command Set

Animation Command Set

CD Audio Command Set

MIDI Sequencer Command Set

Videodisc Command Set

Video Overlay Command Set

Waveform Audio Command Set


About the Command Tables

Each command table has a Command column and an Arguments column. The Command column contains the MCI commands available for a device type. The Arguments column contains the options available for each MCI command. For example, the following table contains the MCI commands all devices support.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can save

| compound device

| device type

| has audio

| has video

| uses files}

close device_name

info device_name	[product]

open device_name	[alias device_alias]

[shareable]

[type device_type]

status device_name	[mode | ready]

Each command also has a notify and wait flag that does not appear in the tables. These flags can be added to any command.

The following conventions are used in the previous example and for the other MCI command tables.

Type style	Used for

Bold	A specific term intended to be used literally. When used in the command column, it represents the MCI string command. When used in the arguments column, it represents a flag. For example, the capability command and the can play flag must be typed as shown.

Italics	Placeholders for information you must provide. The MCI command or flag associated with the information must precede it. For example, to use the alias words for the device_name with the capability command, type "capability words can play."

|	Divider for mutually exclusive arguments. When multiple arguments are separated by this symbol, only one of them can be used for each command. For example, the items in the list can eject, can play, can record, can save, compound device, device type, has audio, has video, uses files are mutually exclusive and you must select only one to use with the capability command. (Do not type the | with the argument.)

{}	Required argument. You must include an argument enclosed by braces. For example, you must use one of the arguments can eject, can play, can record, can save, compound device, device type, has audio, has video, uses files with the capability command. (Do not type the braces with the argument.)

[ ]	Optional argument. For example, the alias, type and shareable flags are optional for the open command. You can use any combination of these flags. You can also use optional arguments with a required argument. (Do not type the brackets with the argument.)


System Command Set

The following table summarizes the MCI system commands. These commands are interpreted directly by MCI. System commands also support notify and wait as optional flags. You can add either or both of these flags to any system command.

Command	Arguments

break device_name	{off | on virtual key code}

sound sound_name

sysinfo device_name	{installname

| name index

| name index open

| quantity

| quantity open}


Required Command Set

The following table lists the commands recognized by all devices. Extended commands can add other options to these commands. Required commands also support notify and wait as optional flags. You can add either or both of these flags to any required command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can save

| compound device

| device type

| has audio

| has video

| uses files}

close device_name

info device_name	[product]

open device_name	[alias device_alias]

[shareable]

[type device_type]

status device_name	[mode | ready]


Basic Command Set

In addition to supporting the commands described previously, each device supports a set of commands specific to its device type. Although these commands are optional for a device, if a command is used it must support the options listed in this table as a minimum set of capabilities. Basic commands also support notify and wait as optional flags. You can add either or both of these flags to any basic command.

Command	Arguments

load device_name	{file_name}

pause device_name

play device_name	[from position]

[to position]

[insert | overwrite]

resume device_name

save device_name	[file_name]

seek device_name	{to position | to start | to end}

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[door closed | door open]

[time format milliseconds | time format ms]

status device_name	{current track

| length

| length track track_number

| mode

| number of tracks

| position

| position track track_number

| ready

| start position

| time format}

stop device name


Animation Command Set

Animation devices support the following set of commands. These devices also supporty notify and wait as optional flags. You can add either or both of these flags to any animation command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can reverse

| can save

| can stretch

| compound device

| device type

| fast play rate

| has audio

| has video

| normal play rate

| slow play rate

| uses files

| uses palettes

| windows}

close device_name

info device_name	[file | product | window text]

open device_name	[alias device_alias]

[nostatic]

[parent hwnd]

[shareable]

[style child

| style overlapped

| style popup]

[type device_type]

pause device_name

play device_name	[fast | slow | speed fps]

[from position]

[to position | reverse]

[scan]

put device_name	{destination

| destination at destination_rectangle

| source

| source at source_rectangle}

realize device_name	{background | normal}

resume device_name

seek device_name	[to position | to start | to end]

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[time format milliseconds

| time format ms

| time format frames]

status device_name	{current track

| forward

| length

| length track track_number

| media present

| mode

| number of tracks

| palette handle

| position

| position track track_number

| ready

| speed

| start position

| stretch

| time format

| window handle}

step device_name	[by frames]

stop device_name

update device_name	[at update_rect]

[hdc hdc]

where device_name	{destination | source}

window device_name	[handle window_handle | handle default]

[stretch | fixed]

[state hide

| state iconic

| state maximized

| state minimize

| state minimized

| state no action

| state no active

| state normal

| state show]

[text caption_text]


Audio CD Command Set

Audio CD devices support the following core set of commands. Audio CD devices also support notify and wait as option flags. You can add either or both of these flags to any audio CD command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can save

| compound device

| device type

| has audio

| has video

| uses files}

close device_name	[product]

info device_name

open device_name	[alias device_name]

[shareable]

pause device_name

play device_name	[from position]

[to position]

resume device_name

seek device_name	[to position to start | to end]

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[door closed | door open]

[time format milliseconds

| time format ms

| time format msf

| time format tmsf]

status device_name	{current track

| length

| length track track_number

| media present

| mode

| number of tracks

| position

| position track track_number

| ready

| start position

| time format}

stop device_name


MIDI Sequencer Command Set

The MIDI sequencer supports the following set of commands. MIDI sequencers also support notify and wait as optional flags. You can add either or both of these flags to any MIDI sequencer command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can save

| compound device

| device type

| has audio

| has video

| uses files}

close device_name

info device_name	[file | product]

open device_name	[alias device_alias]

[shareable]

[type device_type]

pause device_name

play device_name	[from position]

[to position]

record device_name	[from position]

[to position]

[insert | overwrite]

save device_name	[file_name]

seek device_name	[to position | to start | to end]

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[master MIDI

| master none

| master SMPTE]

[offset hmsf_value]

[port port_number

| port mapper

| port none]

[slave file

| slave MIDI

| slave none

| slave SMPTE]

[tempo tempo_value]

[time format milliseconds

| time format ms

| time format smpte 24

| time format smpte 25

| time format smpte 30

| time format smpte 30 drop

| time format song pointer]

status device_name	{current track

| division type

| length

| length track track_number

| master

| media present

| mode

| number of tracks

| offset

| port

| position

| position track track_number

| ready

| slave

| start position

| tempo

| time format}

stop device_name


Videodisc Command Set

Videodisc players support the following set of commands. Videodisc devices also support notify and wait as optional flags. You can add either or both of these flags to any videodisc command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can reverse

| can save

| compound device

| device type

| fast play rate

| has audio

| has video

| normal play rate

| slow play rate

| uses files}

[CAV | CLV]

close device_name

escape device_name	{command_string}

info device_name	[product]

open device_name	[alias device_alias]

[shareable]

pause device_name

play device_name	[fast | slow | speed fps]

[from position]

[scan]

[to position | reverse]

resume device_name

seek device_name	[reverse | to position | to start | to end]

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[door closed | door open]

[time format milliseconds

| time format ms

| time format frames

| time format hms

| time format track]

spin device_name	[down | up]

status device_name	{current track

| disc size

| forward

| length

| length track track_number

| media present

| media type

| mode

| number of tracks

| position

| position track track_number

| ready

| side

| speed

| start position

| time format}

step device_name	[by] position

[reverse]

stop device_name


Video Overlay Command Set

Video overlay devices support the following set of commands. Video overlay devices also support notify and wait as optional flags. You can add either or both of these flags to any video overlay command.

Command	Arguments

capability device_name	{can eject

| can freeze

| can play

| can record

| can save

| can stretch

| compound device

| device type

| has audio

| has video

| uses files

| windows}

close device_name

freeze device_name	[at rectangle]

info device_name	[product | file | window text]

load device_name	[file_name]

at  buffer_rectangle

open device_name	[alias device_alias]

[parent hwnd]

[shareable]

[style style_type

| style child

| style overlapped

| style popup]

[type device_type]

put device_name	{destination | at destination_rectangle

| frame

| frame at frame_rectangle

| source

| source at source_rectangle

| video

| video at video_rectangle}

save device_name	[file_name]

at buffer_rectangle

set device_name	[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[time format milliseconds

| time format ms]

status device_name	{current track

| length

| length track track_number

| media present

| mode

| number of tracks

| position

| position track track_number

| ready

| start position

| stretch

| time format

| window handle}

unfreeze device_name	[at freeze_rectangle]

where device_name	{destination | frame | source | video}

window device_name	[handle window_handle | handle default]

| [stretch | fixed]

[state hide

| state iconic

| state maximized

| state minimized

| state no action

| state no activate

| state normal

| state show]

[text caption_text]


Waveform Audio Command Set

Wave audio devices support the following set of commands. Wave audio devices also support notify and wait as optional flags. You can add either or both of these flags to any wave audio command.

Command	Arguments

capability device_name	{can eject

| can play

| can record

| can save

| compound device

| device type

| has audio

| has video

| inputs

| outputs

| uses files}

close device_name

cue device_name	[input | output]

delete device_name	[from position]

[to position]

info device_name	[file

| input

| output

| product]

open device_name	[alias device_alias]

[buffer buffer_size]

[shareable]

[type device_type]

pause device_name

play device_name	[from position]

[to position]

record device_name	[from position]

[to position]

[insert | overwrite]

resume device_name

save device_name	[file_name]

seek device_name	[to position | to start | to end]

set device_name	[alignment block_alignment]

[any input]

[any output]

[audio all off

| audio all on

| audio left off

| audio left on

| audio right off

| audio right on

| video off

| video on]

[bitspersample bit_count]

[bytespersec byte_rate]

[channels channel_count]

[format tag tag | format tag pcm]

[input device_number]

[output device_number]

[samplespersec sample_rate]

[timeformat milliseconds

| time format ms

| time format bytes

| time format samples]

status device_name	{alignment

| bitspersample

| bytespersec

| channels

| current track

| format tag

| input

| length

| length track track_number

| level

| media present

| mode

| number of tracks

| output

| position

| position track track_number

| ready

| samplespersec

| start position

| time format}

stop device_name


Glossary

A

ABC width	accelerator table

access mask	access time

access token	access-control entry (ACE)

access-control list (ACL)	ACE

ACL	active screen buffer

active window	active window

additive color-technology	alertable wait

alertable wait	anonymous pipe

application-defined control	application-defined resource

associations	asynchronous input/output

atom	atom name

atom table	attribute

B

background window	base class

base line	base priority

beginning-of-medium	beginning-of-partition

bezier spline	bit-count

bitmap	bitmapped image

blink time	blocking I/O

bounding rectangle	breakpoint

brush	brush origin

button	byte type pipe

C

caret	character code

check box	child process

child window	child-window identifier

chord	class cursor

class icon	class menu

click	client area

client coordinates	client

clip path	clip region

clipboard	clipboard format

clipboard owner	clipboard viewer

clipping	CMY format

code page	coherent

color common dialog-box	color palette

color plane	command item

comment	committed pages

common dialog box	common display-context

communications resource	compatible DC

compatible device-context	completion routine

console	console process

container	control

control identifier	control message

control style	coordinate space

Coordinated Universal Time (UTC)	cosmetic pen

critical section	current directory

current position	current selection

cursor	cursor handle

custom cursor	custom icon

custom resource

D

DBCS	DDE client application

DDE conversation	DDE server application

DDE transaction	dead key

deadlock	debugger

debugging event	debugging

default window procedure	desktop wallpaper

desktop window	detached process

device capabilities	device context

device coordinate-space	device-dependent bitmap

device-independent bitmap (DIB)	DIB palette

DIB pattern-brush	Digital Differential Analyzer (DDA)

directory	disabled window

discretionary access-control list	disk drive

display context	display driver

domain	double-click

drag	drag-drop

driver service	drop-down combo box

drop-down list box	drop-down list

dynamic data exchange (DDE)	dynamic priority

dynamic-link library

E

early warning	edit control

ellipse	elliptical region

embedded font	end cap

end-of-medium	end-of-partition

enhanced metafile	environment variable

erase gap	escapement

event object	exception filter

exception

F

family name	FAT

file	file handle

file mapping object	file pointer

file system	file time

file view	filemark

filled path	find common dialog-box

first-chance notification	flash time

flattened path	floating pop-up menu

font common dialog-box	font

font mapper	font table

foreground window	frame-based exception handler

frequency

G

geometric pen	global atom

global subclassing	glyph

graphic modes	graphic objects

Graphics Device Interface	group box

GUI process

H

handle	hatched brush

hidden window	high-resolution performance counter

hit testing	HLS format

hollow brush	hook chain

hook	hook procedure

hot key	hot spot

HPFS

I

icon	icon handle

iconic	image

impersonation token	import library

information context	input buffer

instance subclassing	integer atom

irregular curve	irregular shape

item name

J

join style

K

key	keyboard accelerator

keyboard focus

L

last error code	last-chance notification

line and curve attributes	line

list box	load-time linking

local atom	locally unique identifier (LUID)

log off	logfile

logical brush	logical coordinate-space

logical palette	logical volume

long filemark	LUID

M

mailslot	main window

mapping	mapping mode

matrix	maximize box

maximized window	maximum tracking size

MDI client window	MDI frame window

memory DC	memory device-context

menu bar	menu

menu handle	menu item

message	message loop

message parameters	message queue

message type pipe	metafile bits

metafile device-context	metafile

metafile handle-table	metafile header

metafile palette	metafile record

minimize box	minimized window

minimum tracking size	module definition file

mouse capture	MS-DOS Date

MS-DOS Time	multiple-selection list box

mutex object

N

named pipe	network provider

network root	non-queued message

nonclient area	nonclient area

not-signaled	notification message

NTFS	null brush

O

object (2)	object

open common dialog-box	overlapped input/output

overlapped window	owned window

owner window	owner-drawn button

owner-drawn control	owner-drawn item

P

page coordinate-space	palette animation

Panose numbers	parent processes

parent window	partition

path (2)	path bracket

path	pattern brush

pen	pen style

pen type	performance monitoring

persistent connection	physical brush

physical device	physical palette

picture frame	pie

pipe	pipe instance

pixel	playing a metafile

polygon fill-mode	polygon

polygonal region	pop-up item

pop-up menu	pop-up window

predefined control	primary domain

primary thread	primary token

print common dialog-box	print-setup common dialog-box

priority class	privilege

process	push button

Q

queued message

R

race condition	radial

radio button	raster device

rasterizer	rectangular region

reference count	reference device

reflection	region

region operations	registered clipboard format

registry	regular curve

relative identifier (RID)	release a waiting thread

render	replace common dialog-box

resource compiler	resource file

resource	resource object

resource table	resource-definition file

restored window	RGB format

RID	root directory

rotation	run-time linking

S

save-as common dialog-box	scalable font

scaling	scan code

scan line	scheduler

screen buffer	screen coordinates

scroll bar control	scroll bar

scroll box	scrolling

scrolling range	secant

security descriptor	security domain

security identifier (SID)	selection field

semaphore object	server

service	service name

setmark	share mode

shared memory	shearing

short filemark	shut down

sibling window	SID

signaled	signature

simple combo box	simple list

single-selection list box	sizing border

solid brush	source

standard cursors	standard icons

standard resource	standard scroll bar

standard VGA	static control

stock brush	stock pen

string atom	string handle

stroked path	style-names

subclass procedure	subclassing

subdirectory	subkey

subtractive color-technology	super VGA

superclass	superclass procedure

synchronization object	system access-control list

system directory	System menu

system metric	system paging file

system palette	system time

T

tape drive	tape volume

termination handler	thread

thread local storage	time-out value

timer	timeslice

title bar	token

top-level window	topic name

topmost window	transaction filter

transformation	translation

True Type font	try block

U

Unicode	user-defined pen

UTC

V

value	vector device

viewport extent	viewport

viewport origin	virtual-key code

visible region	visible window

volatile key	volume

W

wait function	waitable object

waiting for an object	waiting thread

wide-character	widened path

wildcard characters	Win32 service

window extent	window

window handle	window name

window origin	window procedure (2)

window procedure	window style

window text	Windows directory

Windows metafile	Windows time

world coordinate-space

X

x-axis

Y

y-axis

Z

Z-order position


ABC width term
ABC width

The amount of spacing required for a single glyph in a font. "A" spacing is the distance 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.


accelerator table term
accelerator table

An array of ACCEL structures, each structure defines a keyboard accelerator.


access mask term
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.


access time term
access time

The last time a file was written to, read from, or run, if the file is executable.


access token term
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, group, or alias. The privileges regulate the use of some system services and the security identifiers regulate access to objects that are protected by access-control lists. There are two kinds of access tokens: primary and impersonation. Access tokens are inherited by child processes. See also impersonation token, primary token


access-control entry (ACE) term
access-control entry (ACE)

An entry in an access-control list. 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.


access-control list (ACL) term
access-control list (ACL)

A list of security protections that apply 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 is an access-control entry (ACE). There are two types of access-control lists: discretionary and system. See also discretionary access-control list, system access-control list


ACE term
ACE

See access-control entry.


ACL term
ACL

See access-control list.


active screen buffer term
active screen buffer

The console screen buffer currently displayed in the console window. A console can have multiple screen buffers, with the process controlling the active screen buffers. Screen buffers can be accessed for reading and writing while inactive.


active window term
active window

The top-level window the user is currently working with. Windows identifies the active window by positioning it at the top of the Z-order and  highlighting its title bar and border.


active window term
active window

A top-level window of the application with which the user is currently working. Windows changes the colors of the active window's title bar and border to identify the active window.


additive color-technology term
additive color-technology

The color technology used by video displays that is based on three primary colors: red, green, and blue. 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.


alertable wait term
alertable wait

A wait operation initiated when a thread calls either the WaitForSingleObjectEx, WaitForMultipleObjectsEx, or SleepEx functions 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.


alertable wait term
alertable wait

A wait operation that is initiated when a thread calls either WaitForSingleObjectEx, WaitForMultipleObjectsEx, or SleepEx with the function's fAlertable flag is set to TRUE. In an alertable wait, the wait function will return when a ReadFileEx or WriteFileEx completion routine is queued for execution.


anonymous pipe term
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.


application-defined control term
application-defined control

A control belonging to a window class supplied by an application.


application-defined resource term
application-defined resource

A resource whose format is defined and recognized by a specific application. See also custom resource.


associations term
associations

The matching of 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 applications or open and print files.


asynchronous input/output term
asynchronous input/output

A type of I/O in which some file I/O functions to 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 complete at a later time. See also overlapped input/output.


atom term
atom

A value that refers to a character string in an atom table.


atom name term
atom name

The character string referred to by an atom.


atom table term
atom table

An operating system-defined table that stores character strings and their associated atoms.


attribute term
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.


background window term
background window

Any window created by a thread other than the foreground thread.


base class term
base class

The window class an application uses as the starting point when creating a superclass.


base line term
base line

An imaginary line where the capital letters for a given font rest.


base priority term
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.


beginning-of-medium term
beginning-of-medium

The position that you can begin recording data on a tape.


beginning-of-partition term
beginning-of-partition

The position you can begin recording data in a partition. If there is only one partition, this position is usually equivalent to the beginning-of-medium.


bezier spline term
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 term
bit-count

Specifies the number of bits of data in a color plane that represent a single pixel.


bitmap term
bitmap

An array of bits that contains data that describes the colors found in a rectangular region on the display (or the rectangular region found on a page of printer paper).


bitmapped image term
bitmapped image

A rectangular image on a video display (or page of printer paper) represented by the color data in a bitmap.


blink time term
blink time

The elapsed time, in milliseconds, to invert the caret display. This value is half of the flash time.


blocking I/O term
blocking 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 non-blocking wait mode, the functions return if their operations are not completed immediately.


bounding rectangle term
bounding rectangle

A bounding rectangle is a rectangle that defines the perimeter of a Windows or GDI object. In the case of some of the GDI objects, the dimensions of this rectangle are inclusive-exclusive when no world transformation exists, and the dimensions are inclusive-inclusive when a world transformation has been set.


breakpoint term
breakpoint

A location in a program where execution is stopped to allow the developer to examine the program's code, variables, and register values, and, as necessary, make changes, continue execution, or terminate execution.


brush term
brush

A bitmap that is used to fill the interior of closed shapes, polygons, ellipses, and paths.


brush origin term
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.


button term
button

An element of the Windows user interface that lets a user provide input to an application. Buttons are typically used in dialog boxes.


byte type pipe term
byte type pipe

A named pipe where data is written as a stream of bytes.


caret term
caret

A flashing line, block, or bitmap that typically marks the location of the insertion point in a window's client area.


character code term
character code

A value that represents a particular character in a set, such as the ASCII character set.


check box term
check box

A square box  used to let the user choose from a set of related but independent options by checking the box. 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 the automatic versions of standard and three-state check boxes, Windows is responsible for changing the state of the check box.


child process term
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 term
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 term
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 term
chord

That segment of an ellipse defined by a secant and the part of the ellipse that lies between the two points intersected by the secant. In Windows, a chord is outlined by using the current pen and filled by using the current brush.


class cursor term
class cursor

The default cursor for a window class. The class cursor is specified by the hCursor member of a WNDCLASS structure.


class icon term
class icon

The default icon for a window class. The class icon is specified by the hIcon member of a WNDCLASS structure.


class menu term
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.


click term
click

Pressing and releasing a mouse button.


client area term
client area

The part of a window where the application displays output such as text or graphics.


client coordinates term
client coordinates

Coordinates relative to the upper-left corner of a window's client area.


client term
client

In the context of mailslots, a process that writes a message to a mailslot.


clip path term
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.


clip region term
clip region

A polygon or ellipse in a window's client-area where clipped-output appears.


clipboard term
clipboard

A temporary location in memory used to transfer information between applications or within an application.


clipboard format term
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.


clipboard owner term
clipboard owner

The window associated with the information on the clipboard. It is possible for there to be no clipboard owner.


clipboard viewer term
clipboard viewer

A window that displays the current contents of the clipboard.


clipping term
clipping

The process of limiting output to part of the client area in an application's window.


CMY format term
CMY format

A color format that identifies a given color with a CMY (cyan, magenta, yellow) triplet. This format is used by printers and other ink-based devices.


code page term
code page

A mapping of 256 character codes to individual characters.


coherent term
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 term
color common dialog-box

A common dialog box that displays available colors and controls which let the user define a custom color.


color palette term
color palette

An array of colors currently available on a device.


color plane term
color plane

An array of bits that represents the red, green, blue, or intensity components for the pixels in a bitmapped image.


command item term
command item

A menu item that, when chosen, sends a command message to the window procedure of the window that owns the menu.


comment term
comment

A string of text inserted between records in a metafile.


committed pages term
committed pages

Pages 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 term
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.


common display-context term
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.


communications resource term
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.


compatible DC term
compatible DC

A virtual-device context that provides a means of storing an image which was created on a physical display. (Compatible DCs are sometimes referred to as "memory" DCs.)


compatible device-context term
compatible device-context

A special device context that treats a location in memory like a drawing surface--allowing Windows to record a bitmapped image.


completion routine term
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.


console term
console

An interface that provides input and output to character-mode applications.


console process term
console process

A process whose entry point is the main function. The executable code for a console process is created with the "-subsystem:console" and "-entry:mainCRTStartup" flags on the link line. A console process uses the Console functions or the File I/O functions for I/O, while a GUI process uses the User/GDI functions.


container term
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.


control term
control

A child window used in conjunction with another window to carryout simple input and output.


control identifier term
control identifier

A number that an application uses to uniquely identify a control.


control message term
control message

A message sent to a control to request information or request an action.


control style term
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 term
coordinate space

A planar space based on the Cartesian system. This system requires two axes which 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 (UTC) term
Coordinated Universal Time (UTC)

The standard international time used internally by Windows NT.


cosmetic pen term
cosmetic pen

A pen with dimensions specified in device units.


critical section term
critical section

An object used for synchronization of the threads of a single process. A thread uses the EnterCriticalSection function to wait for ownership of a critical section object. Only one thread at a time can own a critical section object. A thread uses the LeaveCriticalSection function to relinquish its ownership.


current directory term
current directory

The directory at the end of the active path. This is the directory where the active application started, unless explicitly changed.


current position term
current position

The starting point for any line- or curve-drawing operations.


current selection term
current selection

The portion of a document the user has marked in preparation for carrying out a command.


cursor term
cursor

A small bitmap whose location on the screen is controlled by a pointing device, such as a mouse, pen, or trackball.


cursor handle term
cursor handle

A unique value of the type HCURSOR that identifies a cursor.


custom cursor term
custom cursor

A cursor designed for use in a specific application.


custom icon term
custom icon

An icon designed for use in a specific application.


custom resource term
custom resource

See user-defined resource.


DBCS term
DBCS

Double-byte character set. Used to encode Japanese (Kanji) characters.


DDE client application term
DDE client application

An application that requests a conversation with a DDE server application, and receives data from the server during the conversation.


DDE conversation term
DDE conversation

The interaction between a DDE client and a DDE server application.


DDE server application term
DDE server application

An application that provides data to a DDE client application during a DDE conversation.


DDE transaction term
DDE transaction

An exchange of messages or data between a DDE client application and a DDE server application.


dead key term
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.


deadlock term
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.


debugger term
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 event term
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.


debugging term
debugging

Observing and correcting logical and syntactical errors in an application.


default window procedure term
default window procedure

A system-defined function that provides default processing for messages an application-defined window procedure does not process.


desktop wallpaper term
desktop wallpaper

The pattern created by the bitmap that the desktop window uses to paint the background of the screen.


desktop window term
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 term
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.


device capabilities term
device capabilities

The curve-, line-, polygon-, raster-, and text-drawing capabilities of a display or printer.


device context term
device context

A data structure defining the graphic objects, their associated attributes, and the graphic modes affecting output on a device.


device coordinate-space term
device coordinate-space

One of four coordinate spaces used for all GDI drawing operations.


device-dependent bitmap term
device-dependent bitmap

A device-dependent bitmap is an array of bits that can only be used with a particular display or printer.


device-independent bitmap (DIB) term
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.


DIB palette term
DIB palette

The logical color palette created when a DIB was created.


DIB pattern-brush term
DIB pattern-brush

A logical brush created from a device-independent bitmap (DIB).


Digital Differential Analyzer (DDA) term
Digital Differential Analyzer (DDA)

An algorithm that determines which pixels on a video display (or dots on a page of paper) are part of a line or curve.


directory term
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 term
disabled window

A window that cannot receive input from the keyboard, mouse, or other input device.


discretionary access-control list term
discretionary access-control list

An access-control list that is controlled by the owner of an object and which specifies the access particular users or groups can have to the object. See also access-control list, system access-control list


disk drive term
disk drive

A 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 term
display context

A special device context that treats each window like a separate display surface.


display driver term
display driver

A Windows dynamic link library 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.


domain term
domain

A group of workstations and servers that share a single group name.


double-click term
double-click

Pressing and releasing a mouse button twice in quick succession.


drag term
drag

Moving the mouse while holding down a mouse button.


drag-drop term
drag-drop

The act of selecting one or more files in File Manager, dragging them to an open application, and dropping them there. The application where the files are dropped receives a message it can use to retrieve the filenames and the coordinates of the point where the files were dropped.


driver service term
driver service

A service that follows the NT device driver protocols rather than using the Service Control Manager interface.


drop-down combo box term
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 box term
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.


drop-down list term
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.


dynamic data exchange (DDE) term
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 priority term
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.


dynamic-link library term
dynamic-link library

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.


early warning term
early warning

A physical mark or device-computed position just before the end-of-partition.


edit control term
edit control

An element of the Windows user interface that lets a user enter and edit text. Edit controls are typically used in dialog boxes.


ellipse term
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 term
elliptical region

A region with the shape of an ellipse.


embedded font term
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 will remain intact.)


end cap term
end cap

A geometric-pen attribute that specifies the shape of the pen. There are three end caps: flat, round, and square.


end-of-medium term
end-of-medium

The last position that you can record data on a tape.


end-of-partition term
end-of-partition

The last position that you can record data on a partition.


enhanced metafile term
enhanced metafile

One of two metafile formats. This format, used in applications written for Win32, consists of a header, a table of handles to GDI objects, a private color palette, and an array of metafile records.


environment variable term
environment variable

A symbolic variable that represents some element of the operating system, such a path, a filename, or other literal data. For example, the environment variable PATH represents the directories to search for executable files.


erase gap term
erase gap

An area of erased tape or a pattern that the device does not recognize as a mark or user data, used to locate a filemark to be overwritten.


escapement term
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.


event object term
event object

An interprocess synchronization object whose state is explicitly set to signaled by the SetEvent or PulseEvent function. A thread uses one of the wait functions to wait for an event object's state to be signaled. A manual reset event object's state must be explicitly reset to the not-signaled state by the ResetEvent function. For an auto reset event object, the wait function resets the object's state to not-signaled before returning. Event objects are also used in overlapped operations, where the state is set by the system. An event object is created by the CreateEvent function.


exception filter term
exception filter

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 operating system evaluates the filter expression to determine whether the exception handler code is executed.


exception term
exception

An event arising from the execution of an instruction in an application's code, which requires the execution of software outside the normal flow of control. Common examples of instructions that cause an exception are, attempting to access an invalid memory address, or dividing by zero.


family name term
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.)


FAT term
FAT

File Allocation Table. 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 term
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 handle term
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 term
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.


file pointer term
file pointer

Pointer to the next byte to be read or written in a file.


file system term
file system

A part of the operating system that enables you to store, access, and organize files on storage devices, such as a hard or floppy disks or tape drives. FAT, HPFS, and NTFS are examples of file systems.


file time term
file time

A 64-bit value representing the number of 100-nanosecond intervals that have elapsed since January 1st, 1601.


file view term
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 term
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 term
filled path

A path that is filled by using the brush currently selected into an application's device context.


find common dialog-box term
find common dialog-box

A common dialog box that displays an edit control where the user can type a string that the application should search.


first-chance notification term
first-chance notification

The first time the kernel notifies the debugger of an exception.


flash time term
flash time

The elapsed time, in milliseconds, to invert and restore the caret display. This value is twice the blink time.


flattened path term
flattened path

A path altered by converting each curve (in the path) into a series of line segments.


floating pop-up menu term
floating pop-up menu

A pop-up menu that is not attached to a menu bar.


font common dialog-box term
font common dialog-box

A common dialog box that displays lists of fonts and point sizes that correspond to available fonts.


font term
font

A collection of characters and symbols that share a common design.


font mapper term
font mapper

An algorithm that Windows uses to determine which available font most closely matches a requested font.


font table term
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.


foreground window term
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.


frame-based exception handler term
frame-based exception handler

A mechanism used by a programmer to explicitly 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. If an exception occurs during the execution of the guarded body, the filter expression is evaluated to determine whether the exception handler is executed. In Microsoft C, frame-based exception handlers are implemented by the try-except statement.


frequency term
frequency

With respect to the high-resolution performance counter, this is the number of counts per second. This value is processor-dependent.


geometric pen term
geometric pen

A pen with dimensions that are specified in world units. A geometric pen may possess attributes normally associated with a brush: such as a pattern and a hatch.


global atom term
global atom

An atom stored in the global atom table. The value of a global atom is unique among all other atoms in the operating system.


global subclassing term
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.


glyph term
glyph

The bitmap, collection of points, or collection of graphic commands that define a single character or symbol in a font.


graphic modes term
graphic modes

A set of modes that define how Win32 draws output with the objects found in a device context.


graphic objects term
graphic objects

The pen, brush, bitmap, color palette, region, and path associated with a device context.


Graphics Device Interface term
Graphics Device Interface

A dynamic-link library that processes graphics function calls from a Windows application and passes those calls to the appropriate device driver.


group box term
group box

A rectangle used to group other, related controls (usually check boxes or radio buttons). Because its sole purpose is to organize other controls, a group box cannot be selected.


GUI process term
GUI process

A process whose entry point is the WinMain function. The executable code for a GUI process is created with the "-subsystem:windows" and "-entry:WinMainCRTStartup" flags on the link line. A GUI process uses the User/GDI functions for I/O, while a console process uses the Console functions or the File I/O functions.


handle term
handle

A variable that identifies an object; an indirect reference to an operating system resource.


hatched brush term
hatched brush

A logical brush created from one of twenty predefined bitmaps.


hidden window term
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-resolution performance counter term
high-resolution performance counter

Hardware that provides high-resolution elapsed times.


hit testing term
hit testing

The process of detecting user input by using the position of the mouse cursor hot spot.


HLS format term
HLS format

A color format that identifies a given color with a HLS (hue, luminosity, and saturation) triplet.


hollow brush term
hollow brush

See null brush.


hook chain term
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 term
hook

A point in the Windows message-handling mechanism where an application can install a subroutine to monitor messages.


hook procedure term
hook procedure

An application-defined callback function whose address has been installed in a hook chain.


hot key term
hot key

A key combination that generates a WM_HOTKEY message.


hot spot term
hot spot

The pixel in a cursor that marks the exact screen location affected by a mouse action, such as a button press. Mouse messages include the coordinates of the hot spot.


HPFS term
HPFS

High-Performance File System. File system that supports extended attributes and long, mixed-case filenames, and improves operating system performance by implementing several levels of caching. Windows NT does not recognize the extended attributes of a file created on HPFS.


icon term
icon

A small bitmap that usually represents a minimized application. Icons may also serve as illustrations in warning messages or other windows.


icon handle term
icon handle

A unique value of the type HICON that identifies a icon.


iconic term
iconic

Minimized. If an icon represents a minimized application, the application's window is said to be iconic.


image term
image

A rectangular region on a video display that contains a graphical representation of an object.


impersonation token term
impersonation token

An access token that has been created to capture the security information of a client process. When the security information has been captured, the impersonation token can be associated with a server thread to override that thread's default security information (that is, its primary token). This enables a server to "impersonate" the client process in security operations. See also access token, primary token


import library term
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.


information context term
information context

A device context used strictly for data retrieval--it cannot be used for any drawing operations.


input buffer term
input buffer

A buffer containing a queue of input records with information about keyboard, mouse, and window size events for a console.


instance subclassing term
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.


integer atom term
integer atom

An atom that refers to an integer value.


irregular curve term
irregular curve

A curve that does not fit the perimeter of a conic section.


irregular shape term
irregular shape

A shape composed of curves and straight line segments.


item name term
item name

A string that identifies a unit of data a server can pass to a client during a transaction.


join style term
join style

A geometric-pen attribute that specifies how the ends of connected lines are joined.


Kkey term
key

An entry (or node) in the database. 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.


Kkeyboard accelerator term
keyboard accelerator

A keystroke or combination of keystrokes that sends a command message to the specified application window.


Kkeyboard focus term
keyboard focus

A property of the window currently receiving keyboard input. Only one window at a time can have the keyboard focus.


last error code term
last error code

A per-thread value set by Win32 functions when an error occurs. The last error code can be retrieved with the GetLastError function.


last-chance notification term
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.


line and curve attributes term
line and curve attributes

A width, color, style, and (in the case of lines or curves drawn with a geometric pen) end-cap, join style, and transformation.


line term
line

A set of highlighted pixels on a video display or a series of dots on a page of printer paper that is defined by two points: a starting point and an ending point.


list box term
list box

A control window that contains a list of items.


load-time linking term
load-time linking

Dynamic linking that occurs when a program (either an application or another 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, that is mapped into the address space of the process.


local atom term
local atom

An atom stored in an application's atom table. The value of a local atom is unique among other atoms in the application, but may not be unique throughout the operating system.


locally unique identifier (LUID) term
locally unique identifier (LUID)

A 64-bit value guaranteed to be unique on the operating system that generated it (until the system is restarted).


log off term
log off

To stop all processes running in the security context of the process initiating the log off.


logfile term
logfile

A configuration registry key that specifies an event-log-file name. Logfiles are subkeys of the "EventLog" registration key.


logical brush term
logical brush

A description of a bitmap. A logical brush can be selected into a device context.


logical coordinate-space term
logical coordinate-space

Another name for the world or page coordinate-space. If an application has set a world-to-page space transformation, the logical space is the world space; otherwise the logical space is the page space.


logical palette term
logical palette

An array of colors that can be selected into a device context and used for graphic output.


logical volume term
logical volume

See partition.


long filemark term
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.


LUID term
LUID

See locally unique identifier


mailslot term
mailslot

A pseudo-file used for one-way interprocess communications.


main window term
main window

The window that serves as the primary interface between the user and an application.


mapping term
mapping

A representation of the elements (or points) from a source coordinate space on a target coordinate space.


mapping mode term
mapping mode

An algorithm that specifies the size of the units used for any drawing operations associated with a particular device context.


matrix term
matrix

An n-dimensional array that is used to specify a transformation. Transformations in a two dimensional space require either a two- or three-dimensional array.


maximize box term
maximize box

An window component that, when clicked, causes Windows to enlarge the window to the size of the screen.


maximized window term
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 term
maximum tracking size

The largest window size the user can achieve by dragging the sizing border.


MDI client window term
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 provides support for creating and manipulating the child windows.


MDI frame window term
MDI frame window

The main window of a multiple document interface (MDI) application.


memory DC term
memory DC

See compatible DC.


memory device-context term
memory device-context

See compatible device-context.


menu bar term
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 a pop-up menus.


menu term
menu

A list of items that represent an application's commands. A menu item can be either a string or a bitmap.


menu handle term
menu handle

A unique value of the type HMENU used to identify a menu.


menu item term
menu item

A string or bitmap displayed in a menu. Choosing a menu item either sends a command message or invokes a pop-up menu.


message term
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.


message loop term
message loop

A program loop that retrieves messages from a thread's message queue and dispatches them to the appropriate window procedures.


message parameters term
message parameters

A pair of 32-bit values that contain information that a window procedure uses while processing a message.


message queue term
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.


message type pipe term
message type pipe

A named pipe where data is written as a stream of messages.


metafile bits term
metafile bits

The binary representation of a metafile; the bits include the header, an optional color palette, an optional text description of the metafile's contents, and the metafile records.


metafile device-context term
metafile device-context

A device-context that is used for metafile operations.


metafile term
metafile

A collection of structures that store a picture in a device independent format. (There are two metafile formats: the enhanced format and the windows format.)


metafile handle-table term
metafile handle-table

An array of handles that identify pens, brushes, fonts, and other objects used to create the picture stored in the metafile.


metafile header term
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's color 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).


metafile palette term
metafile palette

An array of RGB values that represent the colors used to create the picture stored in a metafile.


metafile record term
metafile record

A variable-length structure. (In most cases, this structure represents a GDI call that was made to create part of the picture stored in the metafile.)


minimize box term
minimize box

An window component that, when clicked, causes Windows to reduce the window to the size of an icon.


minimized window term
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 term
minimum tracking size

The smallest window size the user can achieve by dragging the window's sizing border.


module definition file term
module definition file

A text file (.DEF) that contains one or more statements that describe 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.


mouse capture term
mouse capture

Channeling mouse input to a specific window without regard to the position of the mouse-cursor hot spot.


MS-DOS Date term
MS-DOS Date

A date in the format used by MS-DOS. The date is a packed 16-bit value where bits in the value represent the day, month and year.


MS-DOS Time term
MS-DOS Time

A time in the format used by MS-DOS. The time is a packed 16-bit value where bits in the value represent the hour, minute and second.


multiple-selection list box term
multiple-selection list box

A list box in which more than one item can be selected at the same time.


mutex object term
mutex object

An interprocess synchronization object whose state is signaled when it is not owned by any thread, and not-signaled when it is owned. Only one thread at a time can own a mutex. A thread uses one of the wait functions to acquire ownership of a mutex. The ReleaseMutex function relinquishes ownership of a mutex. An mutex object is created by the CreateMutex function.


named pipe term
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.


network provider term
network provider

The supplier of a complete implementation of a networking system: for example, Microsoft LAN Manager or Novell Netware.


network root term
network root

The topmost container resource in a network hierarchy. The network root can contain the network providers on a system.


non-queued message term
non-queued message

A message sent directly to a window procedure.


nonclient area term
nonclient area

The parts of a window not the client area. A window's non-client area consists of the border, menu bar, title bar, scroll bar, System menu, Minimize button, and Maximize button.


nonclient area term
nonclient area

The portion of a window consisting of the title bar, menu bar, System menu, minimize box, maximize box, sizing border, and scroll bars, but not the client area.


not-signaled term
not-signaled

The state of an object used for synchronization in one of the wait functions is either signaled or not-signaled. A not-signaled state can prevent the wait function from returning.


notification message term
notification message

A message a control sends to its parent when events, such as input from the user, occur.


NTFS term
NTFS

New Technology File System. File system that supports object-oriented applications by treating all files as objects with user- and system-defined attributes. NTFS provides all the capabilities of FAT and HPFS without many of their limitations.


null brush term
null brush

A logical brush was created from a bitmap that matches the current window background colors. (A null brush is identical to a hollow brush.)


object (2) term
object (2)

A network resource that does not contain any further network resources. It is not necessarily possible to connect to an object.


object term
object

An internal structure that represents a system resource, such as a file, a thread, or a graphic image.


open common dialog-box term
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.


overlapped input/output term
overlapped input/output

See asynchronous input/output.


overlapped window term
overlapped window

A style of window meant to serve as an application's main window.


owned window term
owned window

A window that has an owner. Being owned affects the window's Z-order position and visibility, and can determine when the window is destroyed.


owner window term
owner window

A window that affects aspects of another window's appearance and behavior. See the definition of owned window.


owner-drawn button term
owner-drawn button

A button of type owner-drawn and 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.


owner-drawn control term
owner-drawn control

A predefined control that sends messages to its parent when it needs to be drawn.


owner-drawn item term
owner-drawn item

A menu item whose appearance is controlled by a menu's owner window rather than by Windows.


page coordinate-space term
page coordinate-space

The coordinate space in which all GDI drawing operations begin if an application has not set the world-to-page space transformation.


palette animation term
palette animation

A method of updating the colors in the logical palette.


Panose numbers term
Panose numbers

Special values specified by an application to select a particular font.


parent processes term
parent processes

A relationship between processes in a multitasking environment where one process defines the environment for a second process. The first process, or parent calls the second process, or child, and controls it. A parent process can also suspend or complete its own processing while the child process continues its operation. See also child process.


parent window term
parent window

A window that has one or more child windows.


partition term
partition

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


path (2) term
path (2)

1)A string that describes where a file or directory is located 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.


path bracket term
path bracket

One or more GDI functions embedded between a BeginPath and EndPath function. (The BeginPath function defines the start of the bracket; the EndPath function defines the end.)


path term
path

A figure filled or outlined.


pattern brush term
pattern brush

A logical brush created from an application-defined bitmap.


pen term
pen

A drawing tool used to draw lines and curves.


pen style term
pen style

One of the cosmetic- and geometric-pen attributes that defines 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.


pen type term
pen type

An attribute that determines whether the pen's dimensions are specified in world or device units.


performance monitoring term
performance monitoring

Determining the system resources an application consumes, such as processor time and memory.


persistent connection term
persistent connection

A network connection that Windows restores automatically when the user logs on.


physical brush term
physical brush

A bitmap that Windows uses to paint the interior of filled objects. A physical brush is a device driver's approximation of a logical brush.


physical device term
physical device

The fourth and final coordinate space for most 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 term
physical palette

See system palette.


picture frame term
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.)


pie term
pie

That segment of an ellipse defined by two radials and the part of the ellipse that lies between those two lines. In Windows, a pie is outlined using the current pen and filled by using the current brush.


pipe term
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 API provides both anonymous (unnamed) pipes and named pipes.


pipe instance term
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.


pixel term
pixel

The smallest definable unit on a video display. (A pixel's size is a function of video-display technology.)


playing a metafile term
playing a metafile

The process of converting the records in a metafile into respective device commands and drawing the corresponding picture on the device.


polygon fill-mode term
polygon fill-mode

An algorithm that determines the parts of a region that can be filled, painted, inverted, or clipped.


polygon term
polygon

A closed figure with straight edges. In Windows, a polygon is outlined by using the current pen and filled using the current brush.


polygonal region term
polygonal region

A region with the shape of a polygon.


pop-up item term
pop-up item

A menu item that, when chosen, displays a pop-up menu.


pop-up menu term
pop-up menu

A menu that is hidden until the user performs an action that causes Windows to display the menu.


pop-up window term
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.


predefined control term
predefined control

A control belonging to a window class supplied by Windows.


primary domain term
primary domain

The domain used by the local machine as its usual and default network environment. See also domain.


primary thread term
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.


primary token term
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 term
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.


print-setup common dialog-box term
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.


priority class term
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.


privilege term
privilege

A locally unique identifier used to regulate the use of some system services. A system manager uses privileges to control which users are able to control system resources. An application uses privileges when it changes a system-wide resource (for example, when it changes the system time or shuts down the system).


process term
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.


push button term
push button

A rounded rectangle used to let the user start or cancel an operation by "pushing" the button.


queued message term
queued message

a message queue.


race condition term
race condition

A bug in a multithread 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.


radial term
radial

A ray drawn from the center of an ellipse to the edge of that ellipse.


radio button term
radio button

A circle used to let the user choose from a set of related but mutually exclusive options by checking the button. The check mark for a radio button is a large, 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 term
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).


rasterizer term
rasterizer

A Windows dynamic-link library which converts the graphics commands and hints for TrueType glyphs into actual bitmaps that are drawn on a video display or page of paper.


rectangular region term
rectangular region

A region with the shape of a rectangle.


reference count term
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.


reference device term
reference device

The device where the original picture was created.


reflection term
reflection

A transformation that creates a mirror image of an object.


region term
region

A rectangle, polygon, ellipse (or a combination of two or more of these shapes) used by Windows applications to define a part of the client area to be painted, inverted, filled with output, or utilized for hit-testing.


region operations term
region operations

A procedure such as inversion, painting, clipping, or hit testing.


registered clipboard format term
registered clipboard format

A clipboard format registered by an application, as opposed to a standard clipboard format.


registry term
registry

The database where configuration information is registered. This database takes the place of most configuration and initialization files for Windows and new applications.


regular curve term
regular curve

A curve that defines the perimeter of a conic section.


relative identifier (RID) term
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


release a waiting thread term
release a waiting thread

The act of enabling a thread that is waiting for an object to continue its execution when the state of the object changes to signaled. This occurs when the wait conditions of a wait function have been satisfied.


render term
render

To make data available in a specific clipboard format.


replace common dialog-box term
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.


resource compiler term
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.


resource file term
resource file

A binary file created by the resource compiler that contains an application's resource data. Resource files usually have a .RES extension.


resource term
resource

Binary data that 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 object term
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.


resource table term
resource table

Data that 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.


resource-definition file term
resource-definition file

A text file that contains 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.


restored window term
restored window

A window that does not have the WS_MAXIMIZE or WS_MINIMIZE style.


RGB format term
RGB format

A color format that identifies a given color with a RGB (red, green, blue) triplet. This format is used by video displays.


RID term
RID

See relative identifier


root directory term
root directory

The topmost directory on a volume. Files and directories on a volume are organized in a tree 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).


rotation term
rotation

A transformation that rotates an object with respect to the coordinate-space origin.


run-time linking term
run-time linking

Dynamic linking that occurs when the LoadLibrary and GetProcAddress functions are used to get the starting address of a DLL function.


save-as common dialog-box term
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 that file an application should save.


scalable font term
scalable font

A TrueType font.


scaling term
scaling

A transformation that alters the apparent size of an object.


scan code term
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 term
scan line

A single row of adjacent pixels on a video display.


scheduler term
scheduler

The component of the operating system that determines which of the competing threads receives the next slice of the processor's time.


screen buffer term
screen buffer

A two-dimensional array of character records used to display output to the screen. The data for each character includes the Unicode or ANSI value of the character and attributes that control the colors of the character displayed.


screen coordinates term
screen coordinates

Coordinates relative to the upper-left corner of the screen.


scroll bar control term
scroll bar control

A predefined control window that belongs to the SCROLLBAR window class.


scroll bar term
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.


scroll box term
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.


scrolling term
scrolling

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 term
scrolling range

The minimum and maximum values that a scroll bar can report.


secant term
secant

A line drawn through two points on an ellipse.


security descriptor term
security descriptor

A structure that contains the security information associated with an object. There are two formats for security descriptors: absolute, where the security descriptor contains pointers to the information, and self-relative, where the structure and associated information are stored contiguously in memory.


security domain term
security domain

A collection of nodes in a security database that share a common set of user and group accounts.


security identifier (SID) term
security identifier (SID)

A structure of variable length that uniquely identifies a user or group on all NT implementations. Once an SID value has been assigned to a user or group, that value is never reassigned to another user or group.


selection field term
selection field

The portion of a combo box that displays the currently selected item. Choosing 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.


semaphore object term
semaphore object

An interprocess synchronization object that maintains a count between zero and some maximum value. The object's state is signaled when its count is greater than zero, and not-signaled when its count is zero. A thread uses one of the wait functions to wait for a semaphore object's state to be signaled. The wait function decreases the count by one, and returns, if the current state is signaled. The ReleaseSemaphore function increments a semaphore's count by a specified amount. A semaphore object is created by the CreateSemaphore function.


server term
server

In the context of mailslots, a process that creates a mailslot and that can read messages from it.


service term
service

An executable object 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 operating system, or it can be started on demand by the Service Control Manager. The two types of service are Win32 service and driver service.


service name term
service name

A string that a server application responds to when a client attempts to establish a conversation with the server.


setmark term
setmark

A special recorded element that contains no user data and is used to provide a segmentation scheme heirarchically superior to filemarks. The use of setmarks typically provides faster positioning on high-capacity tapes.


share mode term
share mode

A condition that indicates whether a file is to be shared for reading, writing, both, or neither.


shared memory term
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."


shearing term
shearing

A transformation that alters the apparent length and orientation of vertical or horizontal lines in an object.


short filemark term
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 of from an earlier long filemark.


shut down term
shut down

To stop all processes, flush all file-system buffers to diak, and bring the system to a condition where it is safe to turn off the machine.


sibling window term
sibling window

A child window that has the same parent window as one or more other child windows.


SID term
SID

See security identifier


signaled term
signaled

The state of an object used for synchronization in one of the wait functions is either signaled or not-signaled. A signaled state can enable the wait function to return.


signature term
signature

A 4-byte value that identifies an enhanced metafile.


simple combo box term
simple combo box

A combo box where the list box is visible at all times.


simple list term
simple list

A list in a combo box that is always visible. Combo boxes with the CBS_SIMPLE style contain simple lists.


single-selection list box term
single-selection list box

A list box in which only one item can be selected at a time.


sizing border term
sizing border

A type of window border that lets the user size the window by clicking and dragging the border.


solid brush term
solid brush

A logical brush that was created from a bitmap that contains pixels of the same color.


source term
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.


standard cursors term
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.


standard icons term
standard icons

The default icons that Windows displays in system message boxes. Standard icons include a stop sign and a circled exclamation point.


standard resource term
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 term
standard scroll bar

A scroll bar created as part of the nonclient area of an overlapped, pop-up, or child window.


standard VGA term
standard VGA

A video adapter that supports a resolution of 640 by 480 pixels and 16 simultaneous colors.


static control term
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 term
stock brush

One of seven logical brushes maintained by Windows.


stock pen term
stock pen

A cosmetic pen created and maintained by the Window Manager. There are three stock pens: a black pen, a white pen, and an invisible pen.


string atom term
string atom

An atom that refers to a character string in an atom table.


string handle term
string handle

A doubleword value, assigned by the operating system, that identifies a string passed between a DDE client and a DDE server. See also server application


stroked path term
stroked path

A path that is outlined by using the pen that is currently selected into an application's device context.


style-names term
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.)


subclass procedure term
subclass procedure

An application-defined window procedure that replaces a window's original window procedure when the window is subclassed. See also subclassing


subclassing term
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.


subdirectory term
subdirectory

A directory within another directory.


subkey term
subkey

An entry (or node) in the database subordinate to a given key. With the exception of four predefined keys, all keys are subkeys of other keys.


subtractive color-technology term
subtractive color-technology

The color technology used by ink-based printers that uses 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 term
super VGA

A video adapter that supports resolutions higher than 640 by 480 pixels and/or more than 16 simultaneous colors.


superclass term
superclass

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.


superclass procedure term
superclass procedure

An application-defined window procedure that replaces the window procedure of a window class when the class is superclassed. See also superclass


synchronization object term
synchronization object

An object whose handle can be specified in one of the wait functions. Each instance of a synchronization object has a current state--either signaled or not-signaled. A wait function uses the state of one or more specified objects to determine when the function should return. Synchronization objects include: change notification object, console input, event object, mutex object, process object, thread object, and semaphore object. More than one process can have a handle to the same synchronization object, enabling interprocess synchronization.


system access-control list term
system access-control list

An access-control list that is controlled by a system administrator and used to control the generation of audit messages. See also access-control list, discretionary access-control list


system directory term
system directory

The directory that contains Windows libraries, drivers, and font files.


System menu term
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.


system metric term
system metric

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


system paging file term
system paging file

Storage file that the kernel uses to hold pages of memory swapped out of RAM.


system palette term
system palette

An array that identifies all of the colors which 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 term
system time

The "real-time" clock format. System time uses a data structure containing individual members for the date and time.


tape drive term
tape drive

A device that reads and writes a tape.


tape volume term
tape volume

A recording medium and its physical carrier.


termination handler term
termination handler

A mechanism by which a programmer ensures that a block of termination code is executed. A termination handler consists of a guarded body of code and a termination block. Whenever the guarded body of code is processed, the termination block is guaranteed to be processed, regardless of how the flow of control leaves the guarded body (unless the thread terminates). In Microsoft C, termination handlers are implemented by the try-finally statement.


thread term
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.


thread local storage term
thread local storage

A storage method where an index can be used by multiple threads of the same process to store and retrieve a different value for each thread.


time-out value term
time-out value

The interval, in milliseconds, measured by a timer.


timer term
timer

An internal routine that causes the system to send a WM_TIMER message whenever a specified interval elapses.


timeslice term
timeslice

A unit of processor time (in clock ticks) allocated to a thread.


title bar term
title bar

An window component that displays an application-defined line of text. Typically, the text identifies the application or indicates the purpose of the window.


token term
token

See access token.


top-level window term
top-level window

A window that has no parent window.


topic name term
topic name

A string that identifies the type of data requested by a DDE client application.


topmost window term
topmost window

A window with the WS_EX_TOPMOST style. A topmost window overlaps all other non-topmost windows.


transaction filter term
transaction filter

A flag that prevents the DDEML from passing an unwanted type of transaction to an application's DDE callback function. See also dynamic data exchange


transformation term
transformation

An algorithm that alters ("transforms") the size, orientation, and shape of objects.


translation term
translation

A transformation that shifts an object farther from or closer to the coordinate-space origin.


True Type font term
True Type font

A font whose glyphs are stored as a collection of line and curve commands as well as 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.


try block term
try block

A block of guarded code in a try-except frame-based exception handler or try-finally termination handler. try is a keyword that is used by the Microsoft C compiler to implement structured exception handling.


Unicode term
Unicode

A 16-bit character set capable of encoding all known characters and used as a world-wide character encoding standard. Windows uses Unicode exclusively at the system level


user-defined pen term
user-defined pen

A cosmetic or geometric pen drawn by using a unique series of dashes, dots, or dashes and dots. (The pattern of dashes and dots is defined by the user.)


UTC term
UTC

See Coordinated Universal Time.


value term
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.


vector device term
vector device

A device that creates text and graphics output by drawing lines.


viewport extent term
viewport extent

The width or height of the viewport.


viewport term
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 origin term
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 term
virtual-key code

A device-independent value that identifies the purpose of a keystroke as interpreted by the Windows keyboard device driver.


visible region term
visible region

The part of a window's client-area visible to the user.


visible window term
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 term
volatile key

A key valid only until the next time the operating system is started.


volume term
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 which 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.


wait function term
wait function

A function that blocks the execution of the calling thread until the conditions of the wait operation have been satisfied. This can occur when the state of one or more synchronization objects is signaled, a time-out interval elapses, an I/O completion routine is queued for execution, or a message is available in the thread's input queue. The wait functions are WaitForSingleObject, WaitForMultipleObjects, WaitForSingleObjectEx, WaitForMultipleObjectsEx, and MsgWaitForMultipleObjects.


waitable object term
waitable object

A synchronization object.


waiting for an object term
waiting for an object

The act of a thread using one of the wait functions to wait for the state of a specified object to be signaled. These functions return when the object's state is signaled or when a timeout interval elapses.


waiting thread term
waiting thread

A thread whose execution is blocked while waiting for one of the wait functions to return.


wide-character term
wide-character

A synonym for Unicode; Unicode characters are two bytes wide.


widened path term
widened path

A modified path.


wildcard characters term
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 term
Win32 service

A service that conforms to the interface rules of the Service Control Manager. This enables the Service Control Manager to start the service at boot time 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 extent term
window extent

The width or height of the window.


window term
window

A rectangle in page space that is used to specify a transformation between page and device space.


window handle term
window handle

A 32-bit value, assigned by Windows, that uniquely identifies a window.


window name term
window name

A text string that identifies a window for the user.


window origin term
window origin

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 (2) term
window procedure (2)

A function associated with a window class that processes all messages sent or posted to windows of the class.


window procedure term
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 input (messages) to these windows.


window style term
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 term
window text

See window name.


Windows directory term
Windows directory

The directory that contains Windows applications, initialization files, and help files.


Windows metafile term
Windows metafile

One of two metafile formats. This format, used for applications written for Windows version 3.x., consisted of a header, and an array of metafile records.


Windows time term
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 term
world coordinate-space

The coordinate space in which all GDI drawing operations begin if an application has set the world-to-page space transformation.


x-axis term
x-axis

The axis that normally extends horizontally across a coordinate space.


y-axis term
y-axis

The axis that normally extends vertically across a coordinate space.


Z-order position term
Z-order position

The position of a window in a stack of overlapping windows.


Microsoft RPC (1.0)
Microsoft RPC Version 1.0

RPC API functions (1.0)

RPC data structures (1.0)

RPC API error codes (1.0)

RPC copyright


RPC API functions (1.0)

RpcAbnormalTermination

RpcBindingCopy

RpcBindingFree

RpcBindingFromStringBinding

RpcBindingInqAuthClient

RpcBindingInqAuthInfo

RpcBindingInqObject

RpcBindingReset

RpcBindingSetAuthInfo

RpcBindingSetObject

RpcBindingToStringBinding

RpcBindingVectorFree

RpcEndExcept

RpcEndFinally

RpcEpRegister

RpcEpRegisterNoReplace

RpcEpResolveBinding

RpcEpUnregister

RpcExcept

RpcExceptionCode

RpcFinally

RpcIfIdVectorFree

RpcIfInqId

RpcImpersonateClient

RpcMgmtEnableIdleCleanup

RpcMgmtInqComTimeout

RpcMgmtInqStats

RpcMgmtIsServerListening

RpcMgmtSetComTimeout

RpcMgmtSetServerStackSize

RpcMgmtStatsVectorFree

RpcMgmtStopServerListening

RpcMgmtWaitServerListen

RpcNetworkInqProtseqs

RpcNetworkIsProtseqValid

RpcNsBindingExport

RpcNsBindingImportBegin

RpcNsBindingImportDone

RpcNsBindingImportNext

RpcNsBindingInqEntryName

RpcNsBindingLookupBegin

RpcNsBindingLookupDone

RpcNsBindingLookupNext

RpcNsBindingSelect

RpcNsBindingUnexport

RpcNsEntryExpandName

RpcNsEntryObjectInqBegin

RpcNsEntryObjectInqDone

RpcNsEntryObjectInqNext

RpcNsGroupDelete

RpcNsGroupMbrAdd

RpcNsGroupMbrInqBegin

RpcNsGroupMbrInqDone

RpcNsGroupMbrInqNext

RpcNsGroupMbrRemove

RpcNsMgmtBindingUnexport

RpcNsMgmtEntryCreate

RpcNsMgmtEntryDelete

RpcNsMgmtEntryInqIfIds

RpcNsMgmtHandleSetExpAge

RpcNsMgmtInqExpAge

RpcNsMgmtSetExpAge

RpcNsProfileDelete

RpcNsProfileEltAdd

RpcNsProfileEltInqBegin

RpcNsProfileEltInqDone

RpcNsProfileEltInqNext

RpcNsProfileEltRemove

RpcObjectInqType

RpcObjectSetInqFn

RpcObjectSetType

RpcProtseqVectorFree

RpcRaiseException

RpcRevertToSelf

RpcServerInqBindings

RpcServerInqIf

RpcServerListen

RpcServerRegisterAuthInfo

RpcServerRegisterIf

RpcServerUnregisterIf

RpcServerUseAllProtseqs

RpcServerUseAllProtseqsIf

RpcServerUseProtseq

RpcServerUseProtseqEp

RpcServerUseProtseqIf

RpcStringBindingCompose

RpcStringBindingParse

RpcStringFree

RpcTryExcept

RpcTryFinally

RpcWinSetYieldInfo

YieldFunctionName

UuidCreate

UuidFromString

UuidToString


RPC data structures (1.0)

Authentication Level Constants

Authentication Service Constants

Authorization Service Constants

RPC AUTH IDENTITY HANDLE

RPC_AUTH_KEY_RETRIEVAL_FN

RPC_AUTHZ_HANDLE

RPC_BINDING_HANDLE

RPC_BINDING_VECTOR

RPC_IF_HANDLE

RPC_IF_ID

RPC_IF_ID_VECTOR

RPC_MGR_EPV

RPC_NS_HANDLE

PROTSEQ

RPC_PROTSEQ_VECTOR

RPC_STATS_VECTOR

String Binding

String UUID

UUID_VECTOR


RPC API error codes
RPC API error codes (1.0)

RPC_API_error_codes


RPC copyright

Microsoft RPC version 1.0 Help Database

Version 1.0.1

Jan. 27, 1993

Information in this on-line help system is subject to change without notice and does not represent a commitment on the part of Microsoft Corporation. The software and/or files described in this on-line help system are furnished under a license agreement or nondisclosure agreement. The software and/or files may be used or copied only in accordance with the terms of the agreement.  The purchaser may make one copy of the software for backup purposes.  No part of this on- line help system may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information and retrieval systems, for any purpose other than the purchaser's personal use, without the written permission of Microsoft Corporation.

Copyright (C) Microsoft Corporation, 1993.  All rights reserved.  Simultaneously published in the U.S. and Canada.

Portions of this documentation are provided under license from Digital Equipment Corporation. Copyright (C) 1990, 1992 by Digital Equipment Corporation All Rights Reserved


RPC Macros

Definition	Description
_ _RPC_API	Applied to calls made by the stub and auxiliary routines to the user application. Both functions are in the same executable program.
_ _RPC_FAR	Applied to standard macro definition for pointers. This macro definition should appear as part of the signature of all user-supplied functions.
_ _RPC_STUB	Applied to calls made from the run-time library to the stub. These calls can be considered private.
_ _RPC_USER	Applied to calls made by the run-time library to the user application. These cross the boundary between a DLL and an application.
RPC_ENTRY	Applied to calls made by the application or stub to the run-time library. This macro definition is applied to all RPC run-time API functions.


RPC Data Types and Structures

This section defines the following constants, data types, and data structures used by the Microsoft RPC version 1.0 run-time API 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_PROTSEQ_VECTOR	Count and array of protocol sequences
RPC_STATS_VECTOR	Statistics vector
RPC_STATUS	Status
SEC_ID_PAC	Security identity privilege attribute certificate
SEC_LOGIN_HANDLE	Security login handle
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 API 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 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. This constant is the highest authentication level that will always be present in the RPC run-time library.
RPC_C_AUTHN_LEVEL_PKT_PRIVACY	Authenticates all previous levels and encrypts the argument value of each remote procedure call. This constant is the highest authentication level, but it may not be available in the RPC run-time library.
See Also

RpcBindingInqAuthInfo, RpcBindingSetAuthInfo


Authentication-Service Constants

The AuthnSvc argument represents the authentication service supplied to the RpcBindingInqAuthInfo and RpcBindingSetAuthInfo run-time API 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	DCE default authentication service
RPC_C_AUTHN_NONE	0	No authentication
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 API 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

Syntax

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.

Description

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.

Usage

Client and server applications.

See Also

UUID, UUID_VECTOR


PROTSEQ

Syntax

unsigned char *  Protseq[1];

Protseq

Points to a character string identifying the network protocol used to communicate between client and server.

Description

A protocol sequence is a character string identifying the network protocols used to establish a relationship between a client and server. The protocol sequence contains a set of options that must be defined to the RPC run-time library. There are three options in this set:

•	The RPC protocol used for communications. (Available options are ncacn and ncadg.)

•	The format used in the network address supplied in the binding. (Available options are ip, dnet, and osi.)

•	The transport protocol used for communications. (Available options are tcp, udp, nsp, dna, np, and nb.)

The following predefined strings represent valid combinations:

Protocol sequence	Description
ncacn_dnet_nsp	NCA connection over DECnet: network services protocol (DECnet phase IV)
ncacn_ip_tcp	NCA connection over TCP/IP (transmission control protocol/internet protocol)
ncacn_nb_nb	NCA connection over NetBEUI over NetBIOS
ncacn_nb_tcp	NCA connection over TCP/IP over NetBIOS
ncacn_np	NCA connection over named pipes
ncacn_spx	Connection-oriented SPX
ncalrpc	Local procedure call
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 version 1.0 API 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 ncacn_dnet_nsp protocol sequence is supported only for MS-DOS, Microsoft Windows 3.x, and Microsoft Windows for Workgroups 3.1 client applications. This release of Microsoft RPC version 1.0 does not include support for the ncacn_dnet_nsp protocol sequence with Microsoft Windows NT client or server applications.

Usage

Client and server applications.

See Also

RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf, RpcStringBindingCompose, unsigned


RPC_AUTH_IDENTITY_HANDLE

Syntax

typedef void *  RPC_AUTH_IDENTITY_HANDLE;

Description

Although Microsoft RPC version 1.0 supports security-related run-time API functions, no security package is provided with this release. For specific information about security-related data types, see the documentation for your security package.

See Also

RpcBindingInqAuthInfo, RpcBindingSetAuthInfo


RPC_AUTH_KEY_RETRIEVAL_FN

Syntax

typedef void (* RPC_AUTH_KEY_RETRIEVAL_FN) (
void *  Arg,
unsigned short *  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.

Description

Although Microsoft RPC version 1.0 supports security-related run-time API functions, no security package is provided with this release. For specific information about security-related data types, see the documentation for your security package.

See Also

RpcServerRegisterAuthInfo


RPC_AUTHZ_HANDLE

Syntax

typedef void *  RPC_AUTHZ_HANDLE;

Description

Although Microsoft RPC version 1.0 supports security-related run-time API functions, no security package is provided with this release. For specific information about security-related data types, see the documentation for your security package.

See Also

RpcBindingInqAuthClient


RPC_BINDING_HANDLE

Syntax

typedef RPC_BINDING_HANDLE  handle_t;

Description

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.

Binding-Handle Use by Function

The following table contains the list of RPC run-time routines that operate on binding handles and specifies the type of binding handle allowed:

Routine	Input argument	Output argument
RpcBindingCopy	Server	Server
RpcBindingFree	Server	None
RpcBindingFromStringBinding	None	Server
RpcBindingInqAuthClient	Client	None
RpcBindingInqAuthInfo	Server	None
RpcBindingInqObject	Server or client	None
RpcBindingReset	Server	None
RpcBindingSetAuthInfo	Server	None
RpcBindingSetObject	Server	None
RpcBindingToStringBinding	Server or client	None
RpcBindingVectorFree	Server	None
RpcNsBindingExport	Server	None
RpcNsBindingImportNext	None	Server
RpcNsBindingLookupNext	None	Server
RpcNsBindingSelect	Server	Server
RpcServerInqBindings	None	Server
Usage

Client and server applications.


RPC_BINDING_VECTOR

Syntax

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

Description

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.

Usage

Client and server applications.

See Also

RPC_BINDING_HANDLE, RpcBindingFree, RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcEpUnregister, RpcNsBindingExport, RpcNsBindingLookupNext, RpcNsBindingSelect, RpcServerInqBindings


RPC_CLIENT_INTERFACE

Description

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 version 1.0 do not need this data structure.

The data structure is defined in the header file RPCDCEP.H.


RPC_DISPATCH_TABLE

Description

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 version 1.0 do not need this data structure.

The data structure is defined in the header file RPCDCEP.H.


RPC_IF_HANDLE

Syntax

typedef void *  RPC_IF_HANDLE;

Description

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.

Usage

Client and server applications.


RPC_IF_ID

Syntax

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.

Description

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.

Usage

Client and server applications.

See Also

RpcIfInqId


RPC_IF_ID_VECTOR

Syntax

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.

Description

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.

Usage

Client, server, and management applications.

See Also

RPC_IF_ID, RpcIfIdVectorFree, RpcMgmtInqIfIds, RpcNsMgmtEntryInqIfIds


RPC_MGR_EPV

Syntax

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.

Description

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.

Usage

Server applications.

See Also

RpcServerRegisterIf


RPC_NS_HANDLE

Syntax

typedef void * RPC_NS_HANDLE;

Description

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.

Usage

Client applications.

See Also

RpcNsBindingImportBegin, RpcNsBindingImportDone, RpcNsBindingImportNext, RpcNsBindingLookupBegin, RpcNsBindingLookupDone, RpcNsBindingLookupNext


RPC_OBJECT_INQ_FN

Syntax

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.

Description

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, UUID


RPC_PROTSEQ_VECTOR

Syntax

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.

Description

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.

Usage

Client and server applications.

See Also

RpcNetworkInqProtseqs, RpcProtseqVectorFree


RPC_STATS_VECTOR

Syntax

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.

Description

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.

Usage

Client, server, and management applications.

See Also

RpcMgmtInqStats, RpcMgmtStatsVectorFree


RPC_STATUS

Syntax

typedef long RPC_STATUS;  // Win32 definition
typedef unsigned short RPC_STATUS; // MS-DOS, Win16 definition

Description

The type RPC_STATUS represents a platform-specific status code type. The RPC_STATUS type is returned by most RPC API functions and is part of the RPC_OBJECT_INQ_FN function type definition.

See Also

RPC_OBJECT_INQ_FN


SEC_ID_PAC

Description

Although Microsoft RPC version 1.0 supports security-related run-time API functions, no security package is provided with this release. For specific information about security-related data types, see the documentation for your security package.

See Also

RpcBindingInqAuthClient


SEC_LOGIN_HANDLE

Description

Although Microsoft RPC version 1.0 supports security-related run-time API functions, no security package is provided with this release. For specific information about security-related data types, see the documentation for your security package.

See Also

RpcBindingSetAuthInfo


String Binding

Syntax

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 mapping object UUIDs to manager entry-point vectors, see the RPC API functions reference entry for RpcServerRegisterIf.

ProtocolSequence

Specifies the protocol sequence for making remote procedure calls. The following protocol sequences are supported by Microsoft RPC version 1.0:

•	ncacn_ip_tcp

•	ncacn_np

•	ncacn_nb_nb, ncacn_nb_tcp

•	ncacn_spx

•	ncalrpc

•	ncacn_dnet_nsp

Note   The ncacn_dnet_nsp protocol sequence is supported only for MS-DOS, Microsoft Windows 3.x, and Microsoft Windows for Workgroups 3.1 client applications. This release of Microsoft RPC version 1.0 does not include support for the ncacn_dnet_nsp protocol sequence with Microsoft Windows NT client or server applications.

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	Example
ncacn_dnet_nsp	DECnet phase IV host name  (no trailing ::)	sage
ncacn_dnet_nsp	Area and node syntax	4.120
ncacn_ip_tcp	Common internet address notation	128.10.2.30
ncacn_ip_tcp	Host name	ko
ncacn_nb_nb, ncacn_nb_tcp	Windows NT server name	marketing
ncacn_np	Windows NT server name	\\marketing
ncacn_spx	Network number and node number	~0000000108002B30612C
ncalrpc	None
The network-address field is optional. When you do not specify a network address, the string binding refers to your local host. No network address should be specified when you use the ncalrpc protocol sequence.

When the specified host name is multi-homed, the function RpcBindingFromStringBinding returns a binding handle for the first host address it finds. To specify the host address, use the common internet address notation, an area node syntax, or an NSP instead of a host name.

The string representing the NSP is a percent sign followed by the letter x followed by hexadecimal digits. No separators are allowed. Because the NSP specifies the transport to be used as part of its value, any transport options in the string binding are ignored.

Endpoint

Specifies the endpoint, or address, of the process to receive remote procedure calls. An endpoint can be preceded by the keyword endpoint=. The endpoint field is optional.

The format and content of an endpoint depend on the specified protocol sequence as follows:

Protocol sequence	Endpoint	Example
ncacn_dnet_nsp	DECnet phase IV object name	testname
ncacn_dnet_nsp	DECnet phase IV object number (must be preceded by the # character)	#17
ncacn_ip_tcp	Internet port number	1025
ncacn_nb_nb, ncacn_nb_tcp	Integer between 0 and 255. Many values between 0 and 32 are reserved by Microsoft.	100
ncacn_np	Windows NT named pipe. Name must start with "\\pipe".	\\pipe\\pipename
ncacn_spx	Integer between 1 and 65535.	5000
ncalrpc	String specifying NT object name.  The string cannot include any backslash characters.	my_object
Option

Specifies options associated with Endpoint. 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 follows:

Protocol sequence	Option name
ncacn_dnet_nsp	None
ncacn_ip_tcp	None
ncacn_nb_nb, ncacn_nb_tcp	None
ncacn_np	Security
ncacn_spx	None
ncalrpc	Security
The Security option name, supported for the ncalrpc and ncacn_np 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 NT security settings, including those set to OFF, are included in the token.
Identification	The server knows who client is but is unable to 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 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.

Description

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_dnet_nsp:took[elf_server]

obj-uuid@ncacn_dnet_nsp:took[endpoint=elf_server]

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=anonymous dynamic true]

obj-uuid@ncalrpc:

obj-uuid@ncalrpc:[object1_name_demonstrating_that_these_can_be_lengthy]

obj-uuid@ncalrpc:[object2_name,Security=anonymous dynamic true]

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 (via mail, on paper, or some other means) the string binding to the client.

Usage

Client and server applications.

See Also

RpcBindingFromStringBinding, RpcBindingToStringBinding


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

See Also

UUID


UUID

Syntax

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.

Description

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.

Usage

Client and server applications.

See Also

GUID, UUID_VECTOR


UUID_VECTOR

Syntax

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.

Description

The UUID vector data structure contains a list of UUIDs. The UUID vector contains a count member (Count), 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.

Usage

Client, server, and management applications.

See Also

RpcEpRegister, RpcEpRegisterNoReplace, RpcEpUnregister, RpcNsBindingExport, RpcNsBindingUnexport, UUID


API Function Reference

This section contains an alphabetical list of the API functions supported in Microsoft RPC version 1.0. The documentation for each function includes the correct syntax, a statement about the function's purpose, a description of its input parameters, a description of its return values, and additional comments that can help a developer use the function in an application.

All pointers passed to RPC API functions have to 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	Not supported
RpcAbnormalTermination	Determines whether termination statements are being executed due to an exception or not
RpcBindingCopy	Copies binding data and creates new handle
RpcBindingFree	Releases binding-handle resources
RpcBindingFromStringBinding	Returns handle from string representation of handle
RpcBindingInqAuthClient	Returns authentication and authorization data from authenticated client's handle
RpcBindingInqAuthInfo	Returns authentication and authorization data from handle
RpcBindingInqObject	Returns object UUID from handle
RpcBindingReset	Resets handle so host is specified but server is unspecified
RpcBindingServerFromClient	Not supported
RpcBindingSetAuthInfo	Sets authentication and authorization data into handle
RpcBindingSetObject	Sets object UUID value in handle
RpcBindingToStringBinding	Returns string representation of handle
RpcBindingVectorFree	Frees handles in vector and vector itself
RpcEndExcept	Specifies exception handling structure
RpcEndFinally	Specifies termination handling structure
RpcEpRegister	Add interface, handles to endpoint map database
RpcEpRegisterNoReplace	Add, do not replace existing, database entry
RpcEpResolveBinding	Get handle using data in endpoint map database
RpcEpUnregister	Remove specified endpoint map database entry
RpcExcept	Specifies exception handling structure
RpcExceptionCode	Returns the exception code of an exception
RpcFinally	Specifies termination handlers structure
RpcIfIdVectorFree	Frees interface ID structures in vector and vector itself
RpcIfInqId	Returns interface ID in interface specification
RpcIfRegisterAuthInfo	Not supported
RpcImpersonateClient	Specifies a binding handle on the server to a client
RpcMgmtEnableIdleCleanup	Closes idle resources on the client
RpcMgmtEpEltInqBegin	Not supported
RpcMgmtEpEltInqDone	Not supported
RpcMgmtEpEltInqNext	Not supported
RpcMgmtEpUnregister	Not supported
RpcMgmtInqComTimeout	Returns timeout value in handle
RpcMgmtInqDfltAuthnLevel	Not supported
RpcMgmtInqIfIds	Not supported
RpcMgmtInqServerPrincName	Not supported
RpcMgmtInqStats	Returns runtime statistics
RpcMgmtIsServerListening	Tells whether server is listening for calls
RpcMgmtSetAuthorizationFn	Not supported
RpcMgmtSetCancelTimeout	Not supported
RpcMgmtSetComTimeout	Sets the timeout value in handle
RpcMgmtSetServerStackSize	Specifies stack size for each server thread
RpcMgmtStatsVectorFree	Frees statistics vector
RpcMgmtStopServerListening	Tells server to stop listening for calls
RpcMgmtWaitServerListen	Performs wait operation associated with RpcServerListen
RpcNetworkInqProtseqs	Returns protocol sequences supported by the runtime and operating system
RpcNetworkIsProtseqValid	Tells whether protocol sequence is supported by the runtime and operating system
RpcNsBindingExport	Establishes name-service database entry with multiple handle and multiple objects
RpcNsBindingImportBegin	Creates import context for interface and object
RpcNsBindingImportDone	Deletes import context
RpcNsBindingImportNext	Looks up interface and object from name-service database and returns handle of compatible server
RpcNsBindingInqEntryName	Returns entry name binding handle came from
RpcNsBindingLookupBegin	Creates a lookup context for interface and object
RpcNsBindingLookupDone	Deletes the lookup context
RpcNsBindingLookupNext	Returns list of compatible handles for interface and object
RpcNsBindingSelect	Returns handle from list of compatible handles
RpcNsBindingUnexport	Removes handles for interface and object from entry in name-service database
RpcNsEntryExpandName	Expands name-service entry name
RpcNsEntryObjectInqBegin	Creates inquiry context for objects of name-service database entry
RpcNsEntryObjectInqDone	Deletes inquiry context for objects of name-service database entry
RpcNsEntryObjectInqNext	Returns one object at a time from name-service database entry
RpcNsGroupDelete	Deletes group attribute
RpcNsGroupMbrAdd	Adds entry name to group; if necessary, creates entry
RpcNsGroupMbrInqBegin	Creates inquiry context for viewing group members
RpcNsGroupMbrInqDone	Deletes inquiry context for group
RpcNsGroupMbrInqNext	Returns one entry name at a time from group
RpcNsGroupMbrRemove	Removes entry name from group
RpcNsMgmtBindingUnexport	Removes multiple handles and objects from entry in name-service database
RpcNsMgmtEntryCreate	Creates name-service database entry
RpcNsMgmtEntryDelete	Deletes name-service database entry
RpcNsMgmtEntryInqIfIds	Returns list of interfaces exported to name-service database entry
RpcNsMgmtHandleSetExpAge	Sets name-service handle's expiration age for local copies of name-service data
RpcNsMgmtInqExpAge	Returns global expiration age for local copies of name-service data
RpcNsMgmtSetExpAge	Modifies global expiration age for local copies of name-service data
RpcNsProfileDelete	Deletes profile attribute
RpcNsProfileEltAdd	Adds element to a profile; if necessary, creates the entry
RpcNsProfileEltInqBegin	Creates inquiry context for viewing elements in profile
RpcNsProfileEltInqDone	Deletes inquiry context for viewing elements in a profile
RpcNsProfileEltInqNext	Returns one element at a time from profile
RpcNsProfileEltRemove	Removes element from profile
RpcObjectInqType	Returns object type
RpcObjectSetInqFn	Registers object inquiry function
RpcObjectSetType	Assigns object type
RpcProtseqVectorFree	Frees protocol sequences in vector and vector itself
RpcRaiseException	Raises an exception code
RpcRevertToSelf	Ends impersonation and reestablish its own security
RpcServerInqBindings	Returns handles calls can be received over
RpcServerInqIf	Returns manager EPV for interface
RpcServerListen	Tells runtime to listen for calls
RpcServerRegisterAuthInfo	Registers authentication data with runtime
RpcServerRegisterIf	Registers interface with runtime
RpcServerUnregisterIf	Register interface; associate mepv with uuid
RpcServerUseAllProtseqs	Register all protocols with dynamic endpoints
RpcServerUseAllProtseqsIf	Register all protocols with IDL file endpoints
RpcServerUseProtseq	Register one protocol with dynamic endpoint
RpcServerUseProtseqEp	Register one protocol with specified endpoint
RpcServerUseProtseqIf	Register one protocol with IDL file endpoint
RpcSsDestroyClientContext	Reclaims memory resources used to maintain a context handle on the client
RpcStringBindingCompose	Combines components of string binding into string binding
RpcStringBindingParse	Returns object UUID and address parts of string binding separately
RpcStringFree	Frees character string allocated by the runtime
RpcTryExcept	See RpcExcept
RpcTryFinally	See RpcFinally
RpcWinSetYieldInfo	Yelds to other applications during remote procedure call
UuidCompare	Not supported
UuidCreate	Creates new UUID
UuidCreateNil	Not supported
UuidEqual	Not supported
UuidFromString	Converts string to UUID
UuidHash	Not supported
UuidIsNil	Not supported
UuidToString	Converts UUID to string
YieldFunctionName	A placeholder name for the application-supplied function name


DceErrorInqText

Description

The DCE RPC API function DceErrorInqText is not supported in Microsoft RPC version 1.0.


RpcAbnormalTermination

Syntax

void RpcAbnormalTermination(void);

Description

Determines whether termination statements are being executed due to an exception or not. RpcAbnormalTermination 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
Non-zero	Exception	Termination statements are  being executed due to an exception
Usage

Client, server, and management applications.

See Also

RpcFinally


RpcBindingCopy

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcBindingCopy(
RPC_BINDING_HANDLE  SourceBinding,
RPC_BINDING_HANDLE *  DestinationBinding);

Copies binding information and creates a new binding handle.

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.

Description

Note   Microsoft RPC version 1.0 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.

Usage

Client applications.

Return Codes

Return code	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

RPC_BINDING_HANDLE, RpcBindingFree


RpcBindingFree

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcBindingFree(
RPC_BINDING_HANDLE *  Binding);

Releases binding-handle resources.

Binding

Points to the server binding to free.

Description

Note   Microsoft RPC version 1.0 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.

Usage

Client and server applications.

Return Codes

Return code	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

RPC_BINDING_HANDLE, RpcBindingCopy, RpcBindingFromStringBinding, RpcBindingVectorFree, RpcNsBindingImportNext, RpcNsBindingLookupNext, RpcNsBindingSelect, RpcServerInqBindings


RpcBindingFromStringBinding

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcBindingFromStringBinding(
unsigned char *  StringBinding,
RPC_BINDING_HANDLE *  Binding);

Returns a binding handle from a string representation of a binding handle.

StringBinding

Points to a string representation of a binding handle.

Binding

Returns a pointer to the server binding handle.

Description

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.

Usage

Client applications.

Return Codes

Return code	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

RPC_BINDING_HANDLE, RpcBindingCopy, RpcBindingFree, RpcBindingToStringBinding, RpcStringBindingCompose


RpcBindingInqAuthClient

Syntax

#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);

Returns authentication and authorization information from an authenticated client's binding handle.

ClientBinding

Specifies the client binding handle of the client that made the remote procedure call.

Privs

Returns a pointer to a handle to the privileges 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. The following table shows how to cast the return value:

Value	Data	Cast
RPC_C_AUTHZ_NONE	A NULL value	None
RPC_C_AUTHZ_NAME	The calling client's principal name	(unsigned char *)
RPC_C_AUTHZ_DCE	The calling client's privilege attribute certificate	(SEC_ID_PAC *)
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 services, see the RPC data types and structures reference entry for authentication-service constants.

Specify a null value to prevent RpcBindingInqAuthClient from returning the AuthnSvc 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 possible returns, see the RPC data types and structures reference entry for authorization-service constants.

Specify a NULL value to prevent RpcBindingInqAuthClient from returning the AuthnSvc argument.

Description

Note   RpcBindingInqAuthClient requires the presence of a security DLL. The security DLL is not provided with Microsoft RPC version 1.0.

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 be built with the MIDL attribute explicit_handle specified in the attribute configuration file (ACF file). Using explicit_handle provides the ClientBinding argument as the first argument to each server manager routine.

Usage

Server applications.

Return Codes

Return code	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

auto_handle, explicit_handle, implicit_handle, RPC_AUTHZ_HANDLE, RPC_BINDING_HANDLE, RpcBindingSetAuthInfo, RpcStringFree


RpcBindingInqAuthInfo

Syntax

#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);

Returns authentication and authorization information from a binding handle.

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 the RPC data types and structures reference entry for 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 the RPC data types and structures reference entry for 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 possible returns, see the RPC data types and structures reference entry for authorization-service constants.

Specify a null value to prevent RpcBindingInqAuthInfo from returning the AuthzSvc argument.

Description

Note   RpcBindingInqAuthInfo requires the presence of a security DLL. The security DLL is not provided with Microsoft RPC version 1.0.

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.

Usage

Client applications.

Return Codes

Return code	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

RPC_AUTH_IDENTITY_HANDLE, RPC_BINDING_HANDLE, RpcBindingSetAuthInfo, RpcStringFree


RpcBindingInqObject

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcBindingInqObject(
RPC_BINDING_HANDLE  Binding,
UUID *  ObjectUuid);

Returns the object UUID from a binding handle.

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.

Description

An application calls the RpcBindingInqObject routine to see the object UUID associated with a client or server binding handle.

Usage

Client and server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
See Also

RPC_BINDING_HANDLE, RpcBindingSetObject, UUID


RpcBindingReset

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcBindingReset(
RPC_BINDING_HANDLE  Binding);

Resets a binding handle so that the host is specified but the server on that host is unspecified.

Binding

Specifies the server binding handle to reset.

Description

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.

Usage

Client applications.

Return Codes

Return code	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

RPC_BINDING_HANDLE, RpcEpRegister, RpcEpRegisterNoReplace


RpcBindingServerFromClient

Description

The DCE RPC API function RpcBindingServerFromClient is not supported in Microsoft RPC version 1.0.

See Also

RpcBindingFree, RpcBindingSetObject, RpcEpRegister


RpcBindingSetAuthInfo

Syntax

#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);

Sets authentication and authorization information into a binding handle.

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 RPC-supported authentication levels, see the RPC data types and structures reference entry for authentication-level constants.

AuthnSvc

Specifies the authentication service to use. For a list of RPC-supported authentication services, see the RPC data types and structures reference entry for 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_DCE_PRIVATE 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_DCE_PRIVATE authentication service and any authorization service, AuthIdentity should be a SEC_LOGIN_HANDLE obtained from one of following routines:

•	SEC_LOGIN_SETUP_IDENTITY

•	SEC_LOGIN_GET_CURRENT_CONTEXT

•	SEC_LOGIN_NEWGROUPS

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.

For a list of constants for the AuthzSvc argument, see the RPC data types and structures reference entry for authorization-service constants.

Description

Note   RpcBindingSetAuthInfo requires the presence of a security DLL. The security DLL is not provided with Microsoft RPC version 1.0.

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.

A client application using the IDL auto_handle attribute and wanting authenticated remote procedure calls should call the stub-support library routine RpcServerRegisterAuthInfo.

Usage

Client applications.

Return Codes

Return code	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

auto_handle, RPC_AUTH_IDENTITY_HANDLE, RPC_BINDING_HANDLE, RpcBindingInqAuthInfo, RpcServerRegisterAuthInfo


RpcBindingSetObject

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcBindingSetObject(
RPC_BINDING_HANDLE  Binding,
UUID *  ObjectUuid);

Sets the object UUID value in a binding handle.

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.

Description

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.

Usage

Client applications.

Return Codes

Return code	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

RPC_BINDING_HANDLE, RpcBindingFromStringBinding, RpcBindingInqObject, UUID


RpcBindingToStringBinding

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcBindingToStringBinding(
RPC_BINDING_HANDLE  Binding,
unsigned char * *  StringBinding);

Returns a string representation of a binding handle.

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.

Description

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.

Usage

Client and server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_INVALID_BINDING	Invalid binding handle
See Also

RPC_BINDING_HANDLE, RpcBindingFromStringBinding, RpcStringBindingParse, RpcStringFree


RpcBindingVectorFree

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcBindingVectorFree(
RPC_BINDING_VECTOR * *  BindingVector);

Frees the binding handles contained in the vector and the vector itself.

BindingVector

Points to a pointer to a vector of server binding handles. On return, the pointer is set to NULL.

Description

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.

Usage

Client and server applications.

Return Codes

Return code	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

RPC_BINDING_VECTOR, RpcNsBindingLookupNext, RpcServerInqBindings


RpcEndExcept

See

RpcExcept


RpcEndFinally

See

RpcFinally


RpcEpRegister

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcEpRegister(
RPC_IF_HANDLE  IfSpec,
RPC_BINDING_VECTOR *  BindingVector,
UUID_VECTOR *  UuidVector,
unsigned char *  Annotation);

Adds to or replaces server address information in the local endpoint-map database.

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.

Description

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_dnet_nsp, 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.

Usage

Server applications.

Return Codes

Return code	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

RPC_BINDING_VECTOR, RPC_IF_HANDLE, RpcBindingFromStringBinding, RpcEpRegisterNoReplace, RpcEpUnregister, RpcNsBindingExport, RpcServerInqBindings, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf, UUID_VECTOR


RpcEpRegisterNoReplace

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcEpRegisterNoReplace(
RPC_IF_HANDLE  IfSpec,
RPC_BINDING_VECTOR *  BindingVector,
UUID_VECTOR *  UuidVector,
unsigned char *  Annotation);

Adds server-address information to the local endpoint-map database.

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.

Description

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 take care to 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 does not need 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_dnet_nsp, 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.

Usage

Server applications.

Return Codes

Return code	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

RPC_BINDING_VECTOR, RPC_IF_HANDLE, RpcBindingFromStringBinding, RpcEpRegister, RpcEpUnregister, RpcNsBindingExport, RpcServerInqBindings, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf, UUID_VECTOR


RpcEpResolveBinding

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcEpResolveBinding(
RPC_BINDING_HANDLE  Binding,
RPC_IF_HANDLE  IfSpec);

Resolves a partially bound server binding handle into a fully bound server binding handle.

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.

Description

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.

Usage

Client and management applications.

Return Codes

Return code	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

RPC_BINDING_HANDLE, RPC_IF_HANDLE, RpcBindingFromStringBinding, RpcBindingReset, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingImportBegin, RpcNsBindingImportDone, RpcNsBindingImportNext


RpcEpUnregister

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcEpUnregister(
RPC_IF_HANDLE  IfSpec,
RPC_BINDING_VECTOR *  BindingVector,
UUID_VECTOR *  UuidVector);

Removes server-address information from the local endpoint-map database.

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.

Description

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

RPC_BINDING_VECTOR, RPC_IF_HANDLE, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingUnexport, RpcServerInqBindings, UUID_VECTOR


RpcExcept

Syntax

RpcTryExcept
{
guarded statements
}
RpcExcept(expression)
{
exception statements
}
RpcEndExcept;

Specifies exception handling.

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.

Description

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.

Usage

Client, server, and management applications.

See Also

RpcExceptionCode, RpcFinally, RpcRaiseException


RpcExceptionCode

Syntax

unsigned long
RpcExceptionCode(void);

Description

Returns the exception code of an exception. RpcExceptionCode can only be called from within the expression and exception statements of an RpcTryExcept exception handler.

Usage

Client, server, and management applications.

Return Codes

No value is returned.

See Also

RpcExcept, RpcFinally


RpcFinally

Syntax

RpcTryFinally
{
guarded statements
}
RpcFinally
{
termination statements
}
RpcEndFinally;

Specifies termination handlers.

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, execution continues with the statement following the RpcEndFinally keyword.

Description

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

Usage

Client, server, and management applications.

See Also

RpcAbnormalTermination


RpcIfIdVectorFree

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcIfIdVectorFree(
RPC_IF_ID_VECTOR * *  IfIdVec);

Frees the vector and the interface-identification structures contained in the vector.

IfIdVec

Specifies the address of a pointer to a vector of interface information. On return, the pointer is set to NULL.

Description

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.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
See Also

RPC_IF_ID_VECTOR, RpcIfInqId, RpcMgmtInqIfIds, RpcNsMgmtEntryInqIfIds


RpcIfInqId

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcIfInqId(
RPC_IF_HANDLE  RpcIfHandle,
RPC_IF_ID *  RpcIfId);

Returns the interface-identification part of an interface specification.

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.

Description

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.

Usage

Client and server applications.

Return Code

Return code	Meaning
RPC_S_OK	Success
See Also

RPC_IF_HANDLE, RPC_IF_ID, RpcServerInqIf, RpcServerRegisterIf


RpcIfRegisterAuthInfo

Description

The DCE RPC API function RpcIfRegisterAuthInfo is not supported in Microsoft RPC version 1.0.

See Also

RpcServerRegisterAuthInfo


RpcImpersonateClient

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcImpersonateClient(
RPC_BINDING_HANDLE  CallHandle);

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.

Description

A server thread that is processing client remote procedure calls can call RpcImpersonateClient to impersonate the active client.

Note   This function is supported only on the Microsoft Windows NT operating system.

Usage

Server applications.

Return Codes

Return code	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_NO_CONTEXT_AVAIL	The server does not have permission to impersonate the client
See Also

RPC_BINDING_HANDLE, RpcRevertToSelf


RpcMgmtEnableIdleCleanup

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcMgmtEnableIdleCleanup(void);

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.

Note   RpcMgmtEnableIdleCleanup is a Microsoft extension to the DCE API set.

Usage

Client applications.

Return Codes

Return code	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

Description

The DCE RPC API function RpcMgmtEpEltInqBegin is not supported in Microsoft RPC version 1.0.

See Also

RpcEpRegister


RpcMgmtEpEltInqDone

Description

The DCE RPC API function RpcMgmtEpEltInqDone is not supported in Microsoft RPC version 1.0.

See Also

RpcEpRegister


RpcMgmtEpEltInqNext

Description

The DCE RPC API function RpcMgmtEpEltInqNext is not supported in Microsoft RPC version 1.0.

See Also

RpcEpRegister


RpcMgmtEpUnregister

Description

The DCE RPC API function RpcMgmtEpUnregister is not supported in Microsoft RPC version 1.0.

See Also

RpcEpRegister, RpcEpUnregister


RpcMgmtInqComTimeout

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcMgmtInqComTimeout(
RPC_BINDING_HANDLE  Binding,
unsigned int *  Timeout);

Returns the binding-communications timeout value in a binding handle.

Binding

Specifies a binding.

Timeout

Returns a pointer to the timeout value from the Binding argument.

Description

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.

Usage

Client applications.

Return Codes

Return code	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

RPC_BINDING_HANDLE, RpcMgmtInqStats, RpcMgmtSetComTimeout


RpcMgmtInqDfltAuthnLevel

Description

The DCE RPC API function RpcMgmtInqDfltAuthnLevel is not supported in Microsoft RPC version 1.0.

See Also

RpcBindingInqAuthClient, RpcBindingSetAuthInfo


RpcMgmtInqIfIds

Description

The DCE RPC API function RpcMgmtInqIfIds is not supported in Microsoft RPC version 1.0.

See Also

RpcIfInqId, RpcNsMgmtEntryInqIfIds, RpcServerInqIf


RpcMgmtInqServerPrincName

Description

The DCE RPC API function RpcMgmtInqServerPrincName is not supported in Microsoft RPC version 1.0.

See Also

RpcBindingSetAuthInfo, RpcServerRegisterAuthInfo


RpcMgmtInqStats

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcMgmtInqStats(
RPC_BINDING_HANDLE  Binding,
RPC_STATS_VECTOR * *  Statistics);

Returns RPC run-time statistics.

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.

Description

Note   RpcMgmtInqStats operates only on the local process using Microsoft RPC version 1.0. The binding must be null.

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.

Usage

Client, server, and management applications (local only).

Return Codes

Return code	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

RPC_BINDING_HANDLE, RPC_STATS_VECTOR, RpcEpResolveBinding, RpcMgmtStatsVectorFree


RpcMgmtIsServerListening

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcMgmtIsServerListening(
RPC_BINDING_HANDLE  Binding);

Tells whether a server is listening for remote procedure calls.

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.

Description

Note   RpcMgmtIsServerListening is only available on the local process using Microsoft RPC version 1.0. The binding must be null.

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.

Usage

Client, server, and management applications (local only).

Return Codes

Return code	Meaning
RPC_S_OK	Server listening for remote procedure calls
RPC_S_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

RPC_BINDING_HANDLE, RpcEpResolveBinding, RpcServerListen


RpcMgmtSetAuthorizationFn

Description

The DCE RPC API function RpcMgmtSetAuthorizationFn is not supported in Microsoft RPC version 1.0.

See Also

RpcMgmtInqStats, RpcMgmtIsServerListening, RpcMgmtStopServerListening, RpcMgmtWaitServerListen


RpcMgmtSetCancelTimeout

Description

The DCE RPC API function RpcMgmtSetCancelTimeout is not supported in Microsoft RPC version 1.0.

See Also

RpcMgmtSetComTimeout, RpcWinSetYieldInfo


RpcMgmtSetComTimeout

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcMgmtSetComTimeout(
RPC_BINDING_HANDLE  Binding,
unsigned int  Timeout);

Sets the binding-communications timeout value in a binding handle.

Binding

Specifies the server binding handle whose timeout value is set.

Timeout

Specifies the communications timeout value.

Description

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 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 to spend establishing a client-server relationship.

Usage

Client applications.

Return Codes

Return code	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

RPC_BINDING_HANDLE, RpcMgmtInqComTimeout


RpcMgmtSetServerStackSize

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcMgmtSetServerStackSize(
unsigned int	  ThreadStackSize);

Specifies the stack size for each server thread.

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.

Description

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.

Usage

Server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_INVALID_ARG	Invalid argument
See Also

RpcServerListen


RpcMgmtStatsVectorFree

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcMgmtStatsVectorFree(
RPC_STATS_VECTOR * *  StatsVector);

Frees a statistics vector.

StatsVector

Points to a pointer to a statistics vector. On return, the pointer is set to NULL.

Description

Note   RpcMgmtStatsVectorFree is available only for server applications in Microsoft RPC version 1.0. This DCE function is not available for client applications.

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.

Usage

Server and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
See Also

RPC_STATS_VECTOR, RpcMgmtInqStats


RpcMgmtStopServerListening

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcMgmtStopServerListening(
RPC_BINDING_HANDLE  Binding);

Tells a server to stop listening for remote procedure calls.

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.

Description

Note   RpcMgmtStopServerListening is only available on the local process using Microsoft RPC version 1.0. The binding must be null.

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 applications calls RpcMgmtWaitServerListen for all calls to complete.

Usage

Client, server, and management applications (local only).

Return Codes

Return code	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

RPC_BINDING_HANDLE, RpcEpResolveBinding, RpcMgmtWaitServerListen, RpcServerListen


RpcMgmtWaitServerListen

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcMgmtWaitServerListen(void);

Description

Note   RpcMgmtWaitServerListen is a Microsoft extension to the DCE API set.

RpcMgmtWaitServerListen performs the wait operation usually associated with RpcServerListen.

When the RpcServerListen flag parameter DontWait has a non-zero 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 non-zero 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.

Usage

Server applications.

Return Codes

Return code	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

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNetworkInqProtseqs(
RPC_PROTSEQ_VECTOR * *  ProtSeqVector);

Returns all protocol sequences supported by both the RPC run-time library and the operating system.

ProtSeqVector

Returns a pointer to a pointer to a protocol sequence vector.

Description

Note   RpcNetworkInqProtseqs is available for server applications, not client applications, using Microsoft RPC version 1.0. 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.

Usage

Server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_NO_PROTSEQS	No supported protocol sequences
See Also

RPC_PROTSEQ_VECTOR, RpcProtseqVectorFree


RpcNetworkIsProtseqValid

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNetworkIsProtseqValid(
unsigned char *  Protseq);

Tells whether the specified protocol sequence is supported by both the RPC run-time library and the operating system.

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.

Description

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 RPC-supported protocol sequences, see the data types and structures reference entry for string binding.

An application calls RpcNetworkInqProtseqs to see all of the supported protocol sequences.

Usage

Client applications.

Return Codes

Return code	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

Syntax

#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);

Establishes a name-service database entry with multiple binding handles and multiple objects for a server.

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

Description

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. A server entry must have at least one binding.

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.

Usage

Server applications.

Return Codes

Return code	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

RPC_BINDING_VECTOR, RPC_IF_HANDLE, RpcBindingFromStringBinding, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingUnexport, RpcServerInqBindings, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf, UUID_VECTOR


RpcNsBindingImportBegin

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsBindingImportBegin(
unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_IF_HANDLE  IfSpec,
UUID *  ObjUuid,
RPC_NS_HANDLE *  ImportContext);

Creates an import context for an interface and an object.

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.

Description

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.

Usage

Client applications.

Return Codes

Return code	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

RPC_IF_HANDLE, RPC_NS_HANDLE, RpcNsBindingImportDone, RpcNsBindingImportNext, UUID


RpcNsBindingImportDone

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsBindingImportDone(
RPC_NS_HANDLE *  ImportContext);

Signifies that a client has finished looking for a compatible server and deletes the import context.

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.

Description

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.

Usage

Client applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
See Also

RPC_NS_HANDLE, RpcNsBindingImportBegin, RpcNsBindingImportNext


RpcNsBindingImportNext

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsBindingImportNext(
RPC_NS_HANDLE  ImportContext,
RPC_BINDING_HANDLE *  Binding);

Looks up an interface, and optionally an object, from a name-service database and returns a binding handle of a compatible server (if found).

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.

Description

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.

Usage

Client applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_NO_MORE_BINDINGS	No more bindings
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RPC_BINDING_HANDLE, RPC_NS_HANDLE, RpcBindingFree, RpcNsBindingImportBegin, RpcNsBindingImportDone, RpcNsBindingInqEntryName, RpcNsBindingLookupBegin, RpcNsBindingLookupDone, RpcNsBindingLookupNext, RpcNsBindingSelect


RpcNsBindingInqEntryName

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsBindingInqEntryName(
RPC_BINDING_HANDLE  Binding,
unsigned long  EntryNameSyntax,
unsigned char * *  EntryName);

Returns the entry name from which the binding handle came.

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.

Description

The RpcNsBindingInqEntryName 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.

Usage

Client applications.

Return Codes

Return code	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

RPC_BINDING_HANDLE, RpcBindingFromStringBinding, RpcNsBindingImportNext, RpcNsBindingLookupNext, RpcNsBindingSelect, RpcStringFree


RpcNsBindingLookupBegin

Syntax

#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);

Creates a lookup context for an interface and an object.

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.

Description

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.

Usage

Client applications.

Return Codes

Return code	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

RPC_IF_HANDLE, RPC_NS_HANDLE, RpcNsBindingLookupDone, RpcNsBindingLookupNext, UUID


RpcNsBindingLookupDone

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsBindingLookupDone(
RPC_NS_HANDLE *  LookupContext);

Signifies that a client has finished looking for compatible servers and deletes the lookup context.

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.

Description

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.

Usage

Client applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
See Also

RPC_NS_HANDLE, RpcNsBindingLookupBegin, RpcNsBindingLookupNext


RpcNsBindingLookupNext

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsBindingLookupNext(
RPC_NS_HANDLE  LookupContext,
RPC_BINDING_VECTOR * *  BindingVec);

Returns a list of compatible binding handles for a specified interface and optionally an object.

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.

Description

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.

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

Usage

Client applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_NO_MORE_BINDINGS	No more bindings
RPC_S_NAME_SERVICE_UNAVAILABLE	Name-service unavailable
See Also

RPC_BINDING_VECTOR, RPC_NS_HANDLE, RpcBindingToStringBinding, RpcBindingVectorFree, RpcNsBindingInqEntryName, RpcNsBindingLookupBegin, RpcNsBindingLookupDone, RpcNsBindingSelect, RpcStringBindingParse


RpcNsBindingSelect

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsBindingSelect(
RPC_BINDING_VECTOR *  BindingVec,
RPC_BINDING_HANDLE *  Binding);

Returns a binding handle from a list of compatible binding handles.

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.

Description

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.

Usage

Client applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_NO_MORE_BINDINGS	No more bindings
See Also

RPC_BINDING_HANDLE, RPC_BINDING_VECTOR, RpcBindingFree, RpcNsBindingLookupNext, RpcStringBindingParse


RpcNsBindingUnexport

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsBindingUnexport(
unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_IF_HANDLE  IfSpec,
UUID_VECTOR *  ObjectUuidVec);

Removes the binding handles for an interface and objects from an entry in the name-service database.

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

Description

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.

Usage

Server applications.

Return Codes

Return code	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

RPC_IF_HANDLE, RpcEpUnregister, RpcNsBindingExport, UUID_VECTOR


RpcNsEntryExpandName

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsEntryExpandName(
unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
unsigned char * *  ExpandedName);

Expands a name-service entry name.

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.

Description

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.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_INCOMPLETE_NAME	Incomplete name
See Also

RpcStringFree


RpcNsEntryObjectInqBegin

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsEntryObjectInqBegin(
unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_NS_HANDLE *  InquiryContext);

Creates an inquiry context for a name-service database entry's objects.

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.

Description

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

RPC_NS_HANDLE, RpcNsBindingExport, RpcNsEntryObjectInqDone, RpcNsEntryObjectInqNext


RpcNsEntryObjectInqDone

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsEntryObjectInqDone(
RPC_NS_HANDLE *  InquiryContext);

Deletes the inquiry context for a name-service database entry's objects.

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.

Description

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.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
See Also

RPC_NS_HANDLE, RpcNsEntryObjectInqBegin, RpcNsEntryObjectInqNext


RpcNsEntryObjectInqNext

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsEntryObjectInqNext(
RPC_NS_HANDLE  InquiryContext,
UUID *  ObjUuid);

Returns one object at a time from a name-service database entry.

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.

Description

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

RPC_NS_HANDLE, RpcNsBindingExport, RpcNsEntryObjectInqBegin, RpcNsEntryObjectInqDone, UUID


RpcNsGroupDelete

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsGroupDelete(
unsigned long  GroupNameSyntax,
unsigned char *  GroupName);

Deletes a group attribute.

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

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsGroupMbrAdd(
unsigned long  GroupNameSyntax,
unsigned char *  GroupName,
unsigned long  MemberNameSyntax,
unsigned char *  MemberName);

Adds an entry name to a group. If necessary, creates the entry.

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.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsGroupMbrInqBegin(
unsigned long  GroupNameSyntax,
unsigned char *  GroupName,
unsigned long  MemberNameSyntax,
RPC_NS_HANDLE *  InquiryContext);

Creates an inquiry context for viewing group members.

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.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

RPC_NS_HANDLE, RpcNsGroupMbrAdd, RpcNsGroupMbrInqDone, RpcNsGroupMbrInqNext


RpcNsGroupMbrInqDone

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsGroupMbrInqDone(
RPC_NS_HANDLE *  InquiryContext);

Deletes the inquiry context for a group.

InquiryContext

Points to a name-service handle to free. An argument value of NULL is returned.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_INVALID_NS_HANDLE	Invalid name-service handle
See Also

RPC_NS_HANDLE, RpcNsGroupMbrInqBegin, RpcNsGroupMbrInqNext


RpcNsGroupMbrInqNext

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsGroupMbrInqNext(
RPC_NS_HANDLE  InquiryContext,
unsigned char * *  MemberName);

Returns one entry name from a group at a time.

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.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

RPC_NS_HANDLE, RpcNsGroupMbrInqBegin, RpcNsGroupMbrInqDone, RpcStringFree


RpcNsGroupMbrRemove

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsGroupMbrRemove(
unsigned long  GroupNameSyntax,
unsigned char *  GroupName,
unsigned long  MemberNameSyntax,
unsigned char *  MemberName);

Removes an entry name from a group.

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.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

The RpcNsGroupMbrRemove routine removes a member from the RPC group attribute in the GroupName argument.

Usage

Client, server, and management applications.

Return Codes

Return code	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

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsMgmtBindingUnexport(
unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_IF_ID *  IfId,
unsigned long  VersOption,
UUID_VECTOR *  ObjectUuidVec);

Removes multiple binding handles and objects from an entry in the name-service database.

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

Description

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.

Usage

Management applications.

Return Codes

Return code	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

RPC_IF_ID, RpcMgmtEpUnregister, RpcNsBindingExport, RpcNsBindingUnexport, UUID_VECTOR


RpcNsMgmtEntryCreate

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsMgmtEntryCreate(
unsigned long  EntryNameSyntax,
unsigned char *  EntryName);

Creates a name-service database entry.

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.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Management applications.

Return Codes

Return code	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

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsMgmtEntryDelete(
unsigned long  EntryNameSyntax,
unsigned char *  EntryName);

Deletes a name-service database entry.

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.

Description

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 cause the name-service database to repeatedly remove and replace the same entry. This can lead to performance problems in replicated name-service databases.

Usage

Management applications.

Return Codes

Return code	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

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsMgmtEntryInqIfIds(
unsigned long  EntryNameSyntax,
unsigned char *  EntryName,
RPC_IF_ID_VECTOR * *  IfIdVec);

Returns the list of interfaces exported to a name-service database entry.

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.

Description

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

RPC_IF_ID_VECTOR, RpcIfIdVectorFree, RpcIfInqId, RpcNsBindingExport


RpcNsMgmtHandleSetExpAge

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsMgmtHandleSetExpAge(
RPC_NS_HANDLE  NsHandle,
unsigned long  ExpirationAge);

Sets the expiration age of a name-service handle for local copies of name-service data.

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.

Description

Note   Use RpcNsMgmtHandleSetExpAge with extreme caution.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RPC_NS_HANDLE, RpcNsBindingImportBegin, RpcNsMgmtInqExpAge, RpcNsMgmtSetExpAge


RpcNsMgmtInqExpAge

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsMgmtInqExpAge(
unsigned long *  ExpirationAge);

Returns the global expiration age for local copies of name-service data.

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

Description

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.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
See Also

RpcNsMgmtHandleSetExpAge, RpcNsMgmtSetExpAge


RpcNsMgmtSetExpAge

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsMgmtSetExpAge(
unsigned long  ExpirationAge);

Modifies the application's global expiration age for local copies of name-service data.

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.

Description

Note   Use RpcNsMgmtSetExpAge with extreme caution.

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. Furthermore, if your application is using a remote name-service server, a small expiration age can adversely affect network performance for all applications.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_NAME_SERVICE_UNAVAILABLE	Name service unavailable
See Also

RpcNsMgmtHandleSetExpAge


RpcNsProfileDelete

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsProfileDelete(
unsigned long  ProfileNameSyntax,
unsigned char *  ProfileName);

Deletes a profile attribute.

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.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

Syntax

#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);

Adds an element to a profile. If necessary, creates the entry.

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.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

RPC_IF_ID, RpcIfInqId, RpcNsMgmtEntryCreate, RpcNsProfileEltRemove


RpcNsProfileEltInqBegin

Syntax

#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);

Creates an inquiry context for viewing the elements in a profile.

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.

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

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

RPC_IF_ID, RPC_NS_HANDLE, RpcIfInqId, RpcNsProfileEltInqDone, RpcNsProfileEltInqNext


RpcNsProfileEltInqDone

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsProfileEltInqDone(
RPC_NS_HANDLE *  InquiryContext);

Deletes the inquiry context for viewing the elements in a profile.

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.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
See Also

RPC_NS_HANDLE, RpcNsProfileEltInqBegin, RpcNsProfileEltInqNext


RpcNsProfileEltInqNext

Syntax

#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);

Returns one element at a time from a profile.

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.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

RPC_IF_ID, RPC_NS_HANDLE, RpcNsProfileEltInqBegin, RpcNsProfileEltInqDone, RpcStringFree


RpcNsProfileEltRemove

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcNsProfileEltRemove(
unsigned long  ProfileNameSyntax,
unsigned char *  ProfileName,
RPC_IF_ID *  IfId,
unsigned long  MemberNameSyntax,
unsigned char *  MemberName);

Removes an element from a profile.

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.

Description

Note   This DCE function is not supported by the Microsoft Locator version 1.0.

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.

Usage

Client, server, and management applications.

Return Codes

Return code	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

RPC_IF_ID, RpcNsProfileDelete, RpcNsProfileEltAdd


RpcObjectInqType

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcObjectInqType(
UUID *  ObjUuid,
UUID *  TypeUuid);

Returns the type of an object.

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.

Description

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 the reference entry for 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
Usage

Server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_OBJECT_NOT_FOUND	Object not found
See Also

RpcObjectSetInqFn, RpcObjectSetType, UUID


RpcObjectSetInqFn

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcObjectSetInqFn(
RPC_OBJECT_INQ_FN  InquiryFn);

Registers an object-inquiry function. A null value turns off a previously registered object-inquiry function.

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.

Description

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.

Usage

Server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
See Also

RPC_OBJECT_INQ_FN, RpcObjectInqType, RpcObjectSetType


RpcObjectSetType

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcObjectSetType(
UUID *  ObjUuid,
UUID *  TypeUuid);

Assigns the type of an object.

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.

Description

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 the reference entry for 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.

Usage

Server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_INVALID_OBJECT	Invalid object
RPC_S_ALREADY_REGISTERED	Object already registered
See Also

RpcServerRegisterIf, UUID


RpcProtseqVectorFree

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcProtseqVectorFree(
RPC_PROTSEQ_VECTOR * *  ProtSeqVector);

Frees the protocol sequences contained in the vector and the vector itself.

ProtSeqVector

Points to a pointer to a vector of protocol sequences. On return, the pointer is set to NULL.

Description

Note   RpcProtseqVectorFree is available for server applications, not client applications, using Microsoft RPC version 1.0.

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.

Usage

Server applications.

Return Code

Return code	Meaning
RPC_S_OK	Success
See Also

RPC_PROTSEQ_VECTOR, RpcNetworkInqProtseqs


RpcRaiseException

Syntax

void RPC_ENTRY
RpcRaiseException (
RPC_STATUS  Exception);

Use RpcRaiseException to raise an exception. RpcRaiseException does not return to the caller.

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_BUFFER_TOO_SMALL	Insufficient buffer
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_DUPLICATE_ENDPOINT	Endpoint is duplicate
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_MORE_BINDINGS	No more bindings
RPC_S_NO_MORE_MEMBERS	No more members
RPC_S_NO_NS_PRIVILEGE	No privilege for name-service operation
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_LISTENING	Server not listening
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_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_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_CANNOT_GET_CALL_HANDLE	The stub is unable to 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
Description

RpcRaiseException raises an exception; this exception can then be handled by the exception handler.

Return Codes

No value is returned.

See Also

RPC_STATUS, RpcAbnormalTermination, RpcExcept, RpcFinally


RpcRevertToSelf

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcRevertToSelf (void);

Description

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.

Note   RpcRevertToSelf is supported only on the Microsoft Windows NT operating system.

Usage

Server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_NO_CALL_ACTIVE	Server does not have a client to impersonate
RPC_S_CANNOT_SUPPORT	Not supported for this operating system, this transport, or this security subsystem
See Also

RpcImpersonateClient


RpcServerInqBindings

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerInqBindings(
RPC_BINDING_VECTOR * *  BindingVector);

Returns the binding handles over which remote procedure calls can be received.

BindingVector

Returns a pointer to a pointer to a vector of server binding handles.

Description

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.

Usage

Server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_NO_BINDINGS	No bindings
See Also

RPC_BINDING_VECTOR, RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingExport, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcServerInqIf

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerInqIf(
RPC_IF_HANDLE  IfSpec,
UUID *  MgrTypeUuid,
RPC_MGR_EPV * *  MgrEpv);

Returns the manager entry-point vector (EPV) registered for an interface.

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.

Description

A server application calls the RpcServerInqIf routine to determine the manager EPV for a registered interface and manager type UUID.

Usage

Server applications.

Return Codes

Return Code	Meaning
RPC_S_OK	Success
RPC_S_UNKNOWN_IF	Unknown interface
RPC_S_UNKNOWN_MGR_TYPE	Unknown manager type
See Also

RPC_IF_HANDLE, RPC_MGR_EPV, RpcServerRegisterIf, UUID


RpcServerListen

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerListen(
unsigned int	  MinimumCallThreads,
unsigned int	  MaxCalls,
unsigned int	  DontWait);

Tells the RPC run-time library to listen for remote procedure calls.

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 API function processing. A value of zero indicates that RpcServerListen should not return until RpcMgmtStopServerListening has been called and all remote calls have completed.

Description

Note   The Microsoft RPC version 1.0 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. (In Microsoft RPC version 1.0, the client cannot make a remote call to RpcMgmtStopServerListening.)

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 API function. You can use the RpcMgmtWaitServerListen routine to perform the "wait" operation usually associated with RpcServerListen.

Usage

Server applications.

Return Codes

Return code	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, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcServerRegisterAuthInfo

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerRegisterAuthInfo(
unsigned char *  ServerPrincName,
unsigned long  AuthnSvc,
RPC_AUTH_KEY_RETRIEVAL_FN  GetKeyFn,
void *  Arg);

Registers authentication information with the RPC run-time library.

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. The following table details the RPC run-time behavior for key acquisition for each authentication service:

Authentication service	GetKeyFn	Arg	Run-time behavior
RPC_C_AUTHN_NONE	Ignored	Ignored	No authentication performed
RPC_C_AUTHN_DCE_PRIVATE	NULL	NULL	Uses default method of encryption-key acquisition from default key table
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_DCE_PUBLIC	Ignored	Ignored	Reserved for future use
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.

Description

Note   RpcServerRegisterAuthInfo requires the presence of a security DLL. The security DLL is not provided with Microsoft RPC version 1.0.

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.

Usage

Server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_UNKNOWN_AUTHN_SERVICE	Unknown authentication service
See Also

RPC_AUTH_KEY_RETRIEVAL_FN, RpcBindingSetAuthInfo


RpcServerRegisterIf

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerRegisterIf(
RPC_IF_HANDLE  IfSpec,
UUID *  MgrTypeUuid,
RPC_MGR_EPV *  MgrEpv);

Registers an interface with the RPC run-time library.

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.

Description

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 of the server. This binding handle must be compatible for the client.

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.

Specifying the Manager EPV

If the routine names used by a manager correspond to those of the interface definition, you can register this manager using the default EPV of the interface generated by the MIDL compiler. You can also register a manager using a server-application-supplied EPV.

The Default Manager EPV

By default, the MIDL compiler uses the procedure names from an interface's IDL file to generate a manager EPV, which the compiler places directly into the server stub. This default EPV is statically initialized using the procedure names declared in the interface definition.

To register a manager using the default EPV, specify NULL as the value of the MgrEpv argument (a null EPV).

Server-Supplied Manager EPVs

A server can (and sometimes must) create and register a non-null manager EPV for an interface. To select a server-application-supplied EPV, pass a non-null EPV whose value has been declared by the server as the value of the MgrEpv argument. A non-null value for the MgrEpv argument always overrides a default EPV in the server stub.

The MIDL compiler automatically generates a manager EPV data type (RPC_MGR_EPV) for a server application to use in constructing manager EPVs. A manager EPV must contain exactly one entry point (function address) for each procedure defined in the IDL file.

A server must supply a non-null EPV in the following cases:

•	When the names of manager routines differ from the procedure names declared in the interface definition.

•	When the server uses the default EPV for registering another implementation of the interface.

A server declares a manager EPV by initializing a variable of type
if-name_SERVER_EPV for each implementation of the interface.

Registering Only One Manager of an Interface

When a server offers only one implementation of an interface, the server calls the RpcServerRegisterIf routine only once. In the simplest case, the server uses the default manager EPV. (The exception is when the manager uses routine names that differ from those declared in the interface.)

For the simple case, you supply the following values in the RpcServerRegisterIf call:

•	Manager EPVs

To use the default EPV, you specify a null value for the MgrEpv argument.

•	Manager type UUID

When using the default EPV, you can register the interface with a nil manager type UUID by supplying either a null value or a nil UUID for the MgrTypeUuid argument. In this case, all remote procedure calls, regardless of the object UUID in their binding handle, are dispatched to the default EPV, assuming no RpcObjectSetType calls have been made.

You can also provide a non-nil manager type UUID. In this case, you must also call the RpcObjectSetType routine.

Registering Multiple Implementations of an Interface

To offer multiple implementations of an interface, a server must register each implementation by calling the RpcServerRegisterIf routine separately. For each implementation a server registers, it supplies the same IfSpec argument but a different pair of MgrTypeUuid and MgrEpv arguments.

In the case of multiple managers, use the RpcServerRegisterIf routine as follows:

•	Manager EPVs

To offer multiple implementations of an interface, a server must:

•	Create a non-null manager EPV for each additional implementation.

•	Specify a non-null value for the MgrEpv argument in the RpcServerRegisterIf routine.

Please note that the server can also register with the default manager EPV.

•	Manager type UUID

Provide a manager type UUID for each EPV of the interface. The nil type UUID (or null value) for the MgrTypeUuid argument can be specified for one of the manager EPVs. Each type UUID must be different.

Rules for Invoking Manager Routines

The RPC run-time library dispatches an incoming remote procedure call to a manager that offers the requested RPC interface. When multiple managers are registered for an interface, the RPC run-time library must select one of them. To select a manager, the RPC run-time library uses the object UUID specified by the call's binding handle.

The run-time library applies the following rules when interpreting the object UUID of a remote procedure call:

•	Nil object UUIDs

A nil object UUID is automatically assigned the nil type UUID (it is illegal to specify a nil object UUID in the RpcObjectSetType routine). Therefore, a remote procedure call whose binding handle contains a nil object UUID is automatically dispatched to the manager registered with the nil type UUID, if any.

•	Non-nil object UUIDs

In principle, a remote procedure call whose binding handle contains a non-nil object UUID should be processed by a manager whose type UUID matches the type of the object UUID. However, identifying the correct manager requires that the server has specified the type of that object UUID by calling the RpcObjectSetType routine.

If a server fails to call the RpcObjectSetType routine for a non-nil object UUID, a remote procedure call for that object UUID goes to the manager EPV that services remote procedure calls with a nil object UUID (that is, the nil type UUID).

Remote procedure calls with a non-nil object UUID in the binding handle cannot be executed if the server assigned that non-nil object UUID a type UUID by calling the RpcObjectSetType routine but did not also register a manager EPV for that type UUID by calling the RpcServerRegisterIf routine.

Object UUID of call	Server set type for object UUID?	Server registered EPV type?	Dispatching action
Nil	Not applicable	Yes	Uses the manager with the nil type UUID.
Nil	Not applicable	No	Error (RPC_S_UNSUPPORTED_TYPE); rejects the remote procedure call.
Non-nil	Yes	Yes	Uses the manager with the same type UUID.
Non-nil	No	Ignored	Uses the manager with the nil type UUID; if no manager with the nil type UUID, error (RPC_S_UNSUPPORTEDTYPE); rejects the remote procedure call.
Non-nil	Yes	No	Error (RPC_S_UNSUPPORTEDTYPE); rejects the remote procedure call.
The object UUID of the call is the object UUID found in a binding handle for a remote procedure call.

The server sets the type of the object UUID by calling RpcObjectSetType to specify the type UUID for an object.

The server registers the type for the manager EPV by calling RpcServerRegisterIf using the same type UUID.

The nil object UUID is always automatically assigned the nil type UUID. It is illegal to specify a nil object UUID in the RpcObjectSetType routine.

Dispatching a Remote Procedure Call
to a Server-Manager Routine

The following tables show the steps taken by the RPC run-time library to dispatch a remote procedure call to a server-manager routine.

Assume a simple case where the server registers the default manager EPV, as described in the following tables:

Interface registry table

Interface UUID	Manager type UUID	Entry-point vector
uuid1	Nil	Default EPV
Object registry table

Object UUID	Object type
Nil	Nil
(Any other object UUID)	Nil
Mapping the binding handle to an entry-point vector

Interface UUID (from client binding handle)	Object UUID  (from client  binding handle)	Object type (from object registry table)	Manager EPV  (from interface registry table)
uuid1	Nil	Nil	Default EPV
Same as above	uuidA	Nil	Default EPV
The following steps describe the actions taken by the RPC server run-time library:

1.	The server calls RpcServerRegisterIf to associate an interface it offers with the nil manager type UUID and with the MIDL-generated default manager EPV. This call adds an entry in the interface registry table. The interface UUID is contained in the IfSpec argument.

2.	By default, the object registry table associates all object UUIDs with the nil type UUID. In this example, the server does not call RpcObjectSetType.

3.	The server run-time library receives a remote procedure code containing the interface UUID the call belongs to and the object UUID from the call's binding handle.

See the following API function reference entries for discussions of how an object UUID is set into a binding handle:

•	RpcNsBindingImportBegin

•	RpcNsBindingLookupBegin

•	RpcBindingFromStringBinding

•	RpcBindingSetObject

4.	Using the interface UUID from the remote procedure call, the server's
run-time library locates that interface UUID in the interface registry table.

If the server did not register the interface using RpcServerRegisterIf, the remote procedure call returns to the caller with an RPC_S_UNKNOWN_IF status code.

5.	Using the object UUID from the binding handle, the server's run-time library locates that object UUID in the object registry table. In this example, all object UUIDs map to the nil object type.

6.	The server's run-time library locates the nil manager type in the interface registry table.

7.	Combining the interface UUID and nil type in the interface registry table resolves to the default EPV, which contains the server-manager routines to be executed for the interface UUID found in the remote procedure call.

Assume that the server offers multiple interfaces and multiple implementations of each interface, as described in the following tables:

Interface registry table

Interface UUID	Manager type UUID	Entry-point vector
uuid1	Nil	epv1
uuid1	uuid3	epv4
uuid2	uuid4	epv2
uuid2	uuid7	epv3
Object registry table

Object UUID	Object type
uuidA	uuid3
uuidB	uuid7
uuidC	uuid7
uuidD	uuid3
uuidE	uuid3
uuidF	uuid8
Nil	Nil
(Any other UUID)	Nil
Mapping the binding handle to an entry-point vector

Interface UUID (from client binding handle)	Object UUID (from client binding handle)	Object type  (from object registry table)	Manager EPV (from interface registry table)
uuid1	Nil	Nil	epv1
uuid1	uuidA	uuid3	epv4
uuid1	uuidD	uuid3	epv4
uuid1	uuidE	uuid3	epv4
uuid2	uuidB	uuid7	epv3
uuid2	uuidC	uuid7	epv3
The following steps describe the actions taken by the server's run-time library as depicted in the preceding tables when called by a client with interface UUID uuid2 and object UUID uuidC:

1.	The server calls RpcServerRegisterIf to associate the interfaces it offers with the different manager EPVs. The entries in the interface registry table reflect four calls of RpcServerRegisterIf to offer two interfaces, with two implementations (EPVs) for each interface.

2.	The server calls RpcObjectSetType to establish the type of each object it offers. In addition to the default association of the nil object to a nil type, all other object UUIDs not explicitly found in the object registry table also map to the nil type UUID.

In this example, the server calls the RpcObjectSetType routine six times.

3.	The server run-time library receives a remote procedure call containing the interface UUID the call belongs to and an object UUID from the call's binding handle.

4.	Using the interface UUID from the remote procedure call, the server's
run-time library locates the interface UUID in the interface registry table.

5.	Using the object UUID from the binding handle, uuidC, the server's run-time library locates the object UUID in the object registry table and finds that it maps to type uuid7.

6.	The server's run-time library locates the manager type by combining the interface UUID, uuid2, and type uuid7 in the interface registry table. This resolves to epv3, which contains the server-manager routine to be executed for the remote procedure call.

The routines in epv2 will never be executed because the server has not called the RpcObjectSetType routine to add any objects with a type UUID of uuid4 to the object registry table.

A remote procedure call with interface UUID uuid2 and object UUID uuidF returns to the caller with an RPC_S_UNKNOWN_MGR_TYPE status code because the server did not call the RpcServerRegisterIf routine to register the interface with a manager type of uuid8.

Usage

Server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_TYPE_ALREADY_REGISTERED	Type UUID already registered
See Also

RPC_IF_HANDLE, RPC_MGR_EPV, RpcBindingFromStringBinding, RpcBindingSetObject, RpcNsBindingExport, RpcNsBindingImportBegin, RpcNsBindingLookupBegin, RpcObjectSetType, RpcServerUnregisterIf, UUID


RpcServerUnregisterIf

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerUnregisterIf(
RPC_IF_HANDLE  IfSpec,
UUID *  MgrTypeUuid,
unsigned int	  WaitForCallsToComplete);

Unregisters an interface from the RPC run-time library.

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

Description

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

Server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_UNKNOWN_MGR_TYPE	Unknown manager type
RPC_S_UNKNOWN_IF	Unknown interface
See Also

RPC_IF_HANDLE, RpcServerRegisterIf, UUID


RpcServerUseAllProtseqs

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerUseAllProtseqs(
unsigned int	  MaxCalls,
void *  SecurityDescriptor);

Tells the RPC run-time library to use all supported protocol sequences for receiving remote procedure calls.

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.

Description

Note   The Microsoft RPC version 1.0 implementation of RpcServerUseAllProtseqs includes a new, additional parameter, SecurityDescriptor, that does not appear in the DCE specification.

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.

After registering protocol sequences, a server typically calls the following routines:

•	RpcServerInqBindings to obtain a vector containing all of the server's binding handles.

•	RpcEpRegister or RpcEpRegisterNoReplace to register the binding handles with the endpoint-mapping service. During implementation and debugging, server developers can communicate their binding information to clients using string bindings. This allows them to establish a client-server relationship without using the endpoint-map database or name-service database.

To establish such a relationship, use RpcBindingToStringBinding to convert one or more binding handles in the binding-handle vector to a string binding and provide, via mail, on paper, or by some other means, the string binding to the client.

•	RpcNsBindingExport to place the binding handles in the name-service database for access by any client.

•	RpcBindingVectorFree to free the vector of server binding handles.

•	RpcServerRegisterIf to register the interfaces offered by the server with the RPC run-time library. This is a required call.

•	RpcServerListen to begin receiving remote procedure call requests. This is a required call.

To selectively register protocol sequences, a server calls the RpcServerUseProtseq, RpcServerUseProtseqIf, or RpcServerUseProtseqEp routine.

Usage

Server applications.

Return Codes

Return code	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


RpcServerUseAllProtseqsIf

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerUseAllProtseqsIf(
unsigned int  MaxCalls,
RPC_IF_HANDLE  IfSpec,
void *  SecurityDescriptor);

Tells the RPC run-time library to use all the specified protocol sequences and endpoints in the interface specification for receiving remote procedure calls.

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.

Description

Note   The Microsoft RPC version 1.0 implementation of RpcServerUseAllProtseqsIf includes a new, additional parameter, SecurityDescriptor, that does not appear in the DCE specification.

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 RpcServerUseAllProtseqs for the list of routines a server typically calls after calling RpcServerUseAllProtseqsIf.

To register selected protocol sequences specified in the IDL file, a server calls the RpcServerUseProtseqIf routine.

Usage

Server applications.

Return Codes

Return code	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

RPC_IF_HANDLE, RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingExport, RpcServerInqBindings, RpcServerListen, RpcServerRegisterIf, RpcServerUseAllProtseqs, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcServerUseProtseq

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerUseProtseq(
unsigned char *  ProtSeq,
unsigned int  MaxCalls,
void *  SecurityDescriptor);

Tells the RPC run-time library to use the specified protocol sequence for receiving remote procedure calls.

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.

Description

Note   The Microsoft RPC version 1.0 implementation of RpcServerUseProtseq includes a new, additional parameter, SecurityDescriptor, that does not appear in the DCE specification.

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 RpcServerUseAllProtseqs for the list of routines a server typically calls after calling RpcServerUseProtseq.

To register all protocol sequences, a server calls the RpcServerUseAllProtseqs routine.

Usage

Server applications.

Return Codes

Return code	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, RpcServerRegisterIf, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseqEp, RpcServerUseProtseqIf


RpcServerUseProtseqEp

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerUseProtseqEp(
unsigned char *  Protseq,
unsigned int	  MaxCalls,
unsigned char *  Endpoint,
void *  SecurityDescriptor);

Tells the RPC run-time library to use the specified protocol sequence combined with the specified endpoint for receiving remote procedure calls.

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.

Description

Note   The Microsoft RPC version 1.0 implementation of RpcServerUseProtseqEp includes a new, additional parameter, SecurityDescriptor, that does not appear in the DCE specification.

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 RpcServerUseAllProtseqs for the list of routines a server typically calls after calling RpcServerUseProtseqEp.

Usage

Server applications.

Return Codes

Return code	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


RpcServerUseProtseqIf

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcServerUseProtseqIf(
unsigned char *  Protseq,
unsigned int	  MaxCalls,
RPC_IF_HANDLE  IfSpec,
void *  SecurityDescriptor);

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.

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.

Description

Note   The Microsoft RPC version 1.0 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 RpcServerUseAllProtseqs for the list of routines a server typically calls after calling RpcServerUseProtseqIf.

To register all protocol sequences from the IDL file, a server calls the RpcServerUseAllProtseqsIf routine.

Usage

Server applications.

Return Codes

Return code	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

RPC_IF_HANDLE, RpcBindingVectorFree, RpcEpRegister, RpcEpRegisterNoReplace, RpcNsBindingExport, RpcServerInqBindings, RpcServerListen, RpcServerRegisterIf, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp


RpcSsDestroyClientContext

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcSsDestroyClientContext(
void * *  ContextHandle
);

Destroys a context handle no longer needed by the client without contacting the server.

ContextHandle

Specifies the context handle to be destroyed. The handle is set to NULL before RpcSsDestroyClientContext returns.

Description

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.

Usage

Client applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_X_SS_CONTEXT_MISMATCH	Invalid context handle
See Also

RpcBindingReset


RpcStringBindingCompose

Syntax

#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);

Combines the components of a string binding into a string binding.

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 more information, see the RPC data types and structures reference entry for string binding.

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.

Description

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

Usage

Client and server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_INVALID_STRING_UUID	String representation of the UUID not valid.
See Also

RpcBindingFromStringBinding, RpcBindingToStringBinding, RpcStringBindingParse, RpcStringFree


RpcStringBindingParse

Syntax

#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);

Returns the object UUID part and the address parts of a string binding as separate strings.

StringBinding

Points to a NULL-terminated string representation of a binding.

ObjUuid

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

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.

Description

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.

Usage

Client and server applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_INVALID_STRING_BINDING	Invalid string binding
See Also

RpcBindingFromStringBinding, RpcBindingToStringBinding, RpcStringBindingCompose, RpcStringFree


RpcStringFree

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
RpcStringFree(
unsigned char * *  String);

Frees a character string allocated by the RPC run-time library.

String

Points to a pointer to the character string to free.

Description

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.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
See Also

RpcBindingToStringBinding, RpcNsBindingInqEntryName, RpcStringBindingParse


RpcTryExcept

See

RpcExcept


RpcTryFinally

See

RpcFinally


RpcWinSetYieldInfo

Syntax

#include <rpc.h>
RPC_STATUS
RpcWinSetYieldInfo(HWND	hWnd,
BOOL  fCustomYield,
WORD  wMsg,
DWORD  dwOtherInfo);

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. The address passed as the parameter must be created using the MakeProcInstance function. The callback function syntax is documented as YieldFunctionName. For more information about MakeProcInstance, see your Windows API reference documentation.

Description

RpcWinSetYieldInfo configures Microsoft Windows 3.x client applications to yield to other applications during remote procedure calls. RpcWinSetYieldInfo 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.

RpcWinSetYieldInfo can be called more than once by an application. Each call simply replaces the information stored in the previous calls.

Yielding is not necessary for Win32 applications. Environments that support Win32 applications are preemptively multitasked and are multithreaded. For efficiency, a Win32-only application should not call RpcWinSetYieldInfo.

Usage

Client applications.

Return Codes

Return code	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


UuidCompare

Description

The DCE RPC API function UuidCompare is not supported in Microsoft RPC version 1.0.

See Also

UuidCreate


UuidCreate

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
UuidCreate(
UUID *  Uuid);

Creates a new UUID.

Uuid

Returns a pointer to the created UUID.

Description

An application calls the UuidCreate routine to create a new UUID.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_UUID_NO_ADDRESS	Cannot get Ethernet or token-ring hardware address for this computer
See Also

UUID, UuidFromString, UuidToString


UuidCreateNil

Description

The DCE RPC API function UuidCreateNil is not supported in Microsoft RPC version 1.0.

See Also

UuidCreate


UuidEqual

Description

The DCE RPC API function UuidEqual is not supported in Microsoft RPC version 1.0.

See Also

UuidCreate


UuidFromString

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
UuidFromString(
unsigned char *  StringUuid,
UUID *  Uuid);

Converts a string to a UUID.

StringUuid

Points to a string representation of a UUID.

Uuid

Returns a pointer to a UUID in binary form.

Description

An application calls the UuidFromString routine to convert a string UUID to a binary UUID.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_INVALID_STRING_UUID	The string UUID is invalid
See Also

UUID, UuidToString


UuidHash

Description

The DCE RPC API function UuidHash is not supported in Microsoft RPC version 1.0.

See Also

UuidCreate


UuidIsNil

Description

The DCE RPC API function UuidIsNil is not supported in Microsoft RPC version 1.0.

See Also

UuidCreate


UuidToString

Syntax

#include <rpc.h>
RPC_STATUS RPC_ENTRY
UuidToString(
UUID *  Uuid,
unsigned char * *  StringUuid);

Converts a UUID to a string.

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.

Description

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.

Usage

Client, server, and management applications.

Return Codes

Return code	Meaning
RPC_S_OK	Success
RPC_S_OUT_OF_MEMORY	No memory
See Also

RpcStringFree, UUID, UuidFromString


YieldFunctionName

Syntax

BOOL FAR PASCAL	YieldFunctionName(void);

Description

YieldFunctionName is a placeholder name for the application-supplied function name provided as a parameter to the RpcWinSetYieldInfo routine.

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 will likely 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


BLANK PAGE

IMPORTANT: This text will appear on screen, but will not print on a PostScript printer.

This page should be the last one in this file; it was inserted by running the InsertBlankPage macro.

Do not type any additional text on this page!


RPC Error Codes

RPC API functions can return the following Win32 error codes:

Manifest	Description
EPT_S_CANT_CREATE	The endpoint-map database cannot 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-map database.
RPC_S_ACCESS_DENIED	The user does not have sufficient privilege to complete the operation.
RPC_S_ADDRESS_ERROR	An addressing error has occurred on the server.
RPC_S_ALREADY_LISTENING	The server is already listening.
RPC_S_ALREADY_REGISTERED	The object UUID has already been registered.
RPC_S_BINDING_HAS_NO_AUTH	The binding does not contain any authentication information.
RPC_S_BUFFER_TOO_SMALL	The buffer used to transmit data is too small.
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_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 has caused a divide by zero.
RPC_S_FP_OVERFLOW	A floating-point overflow has 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 has not been found.
RPC_S_INCOMPLETE_NAME	The entry name is incomplete.
RPC_S_INTERFACE_NOT_FOUND	The interface has not been found.
RPC_S_INTERNAL_ERROR	An internal error has occurred in a remote procedure call.
RPC_S_INVALID_ARG	The specified argument is not valid.
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_LEVEL	The level parameter is invalid.
RPC_S_INVALID_NAF_IF	The network-address family 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 is invalid.
RPC_S_INVALID_RPC_PROTSEQ	The RPC protocol sequence is invalid.
RPC_S_INVALID_SECURITY_DESC	The security descriptor is not in the valid format.
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 discriminant value does not match any of the case values. There is no default case.
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 no 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 has been found.
RPC_S_NO_ENTRY_NAME	The binding does not contain an entry name.
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	There are no more bindings.
RPC_S_NO_MORE_ELEMENTS	There are no more elements.
RPC_S_NO_MORE_MEMBERS	There are no more members.
RPC_S_NO_NS_PRIVILEGE	There is no privilege for a  name-service operation.
RPC_S_NO_PRINC_NAME	No principal name is registered.
RPC_S_NO_PROTSEQS	There are no protocol sequences.
RPC_S_NO_PROTSEQS_REGISTERED	No protocol sequences have been registered.
RPC_S_NOT_ALL_OBJS_UNEXPORTED	Not all objects are unexported.
RPC_S_NOT_LISTENING	The server is not listening.
RPC_S_NOTHING_TO_EXPORT	There is nothing to export.
RPC_S_OBJECT_NOT_FOUND	The object UUID has not been found.
RPC_S_OK	The call has completed successfully.
RPC_S_OUT_OF_MEMORY	The needed memory is not available.
RPC_S_OUT_OF_RESOURCES	Not enough resources are available to complete this operation.
RPC_S_OUT_OF_THREADS	The RPC run-time library was not able to create another thread.
RPC_S_PROCNUM_OUT_OF_RANGE	The procedure number is out of range.
RPC_S_PROTOCOL_ERROR	An RPC protocol error has occurred.
RPC_S_PROTSEQ_NOT_FOUND	The RPC protocol sequence has not been found.
RPC_S_PROTSEQ_NOT_SUPPORTED	The RPC protocol sequence is not supported.
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 has already been 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_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_NO_ADDRESS	No network address is available for constructing a UUID.
RPC_S_WRONG_KIND_OF_BINDING	The binding handle is not the correct type.
RPC_S_ZERO_DIVIDE	The server has attempted an integer divide by zero.
RPC_X_BAD_STUB_DATA	The stub has received bad data.
RPC_X_BYTE_COUNT_TOO_SMAL	The 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 constant must be less than 65535.
RPC_X_INVALID_BOUND	The specified bounds of an array are inconsistent.
RPC_X_INVALID_TAG	The discriminant value does not match any of the case values. There is no default case.
RPC_X_NO_MEMORY	Insufficient memory is available.
RPC_X_NO_MORE_ENTRIES	The list of servers available for the auto_handle binding has been exhausted.
RPC_X_NULL_REF_POINTER	A null reference pointer has been 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. Only raised on the client side.
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 in an in parameter position.


BLANK PAGE

IMPORTANT: This text will appear on screen, but will not print on a PostScript printer.

This page should be the last one in this file; it was inserted by running the InsertBlankPage macro.

Do not type any additional text on this page!


GetFileResource function
GetFileResource (Win32)

The GetFileResource function is not supported in the Win32 API.


GetFileResourceSize function
GetFileResourceSize (Win32)

The GetFileResourceSize function is not supported in the Win32 API.


GetFileVersionInfo function
GetFileVersionInfo (Win32)

BOOL GetFileVersionInfo(lpszFile, dwHandle, cbBuf, lpvData)

LPTSTR lpszFile;	/* address of filename	*/
DWORD dwHandle;	/* ignored	*/
DWORD cbBuf;	/* size of buffer	*/
LPVOID lpvData;	/* address of buffer for file-version info.	*/

The GetFileVersionInfo function returns version information about the specified file.

As with the other file installation functions, GetFileVersionInfo will only work with Win32 file images. Sixteen-bit Windows file images are not supported.

Parameter	Description

lpszFile	Points to the null-terminated string that specifies the filename.

dwHandle	This parameter is ignored.

cbBuf	Specifies the size of the buffer identified by lpvData. The GetFileVersionInfoSize function returns the buffer size required to hold the file-version information. If the buffer is not large enough, the file-version information is truncated to the size of the buffer.

lpvData	Points to the buffer that receives the file-version information. This parameter is used in a subsequent call to the VerQueryValue function. The data specified by this parameter is always in Unicode format.

Returns

If the function succeeds, the return value is TRUE; otherwise it is FALSE. To get extended error information, use the GetLastError function.

See Also

GetFileVersionInfoSize, VerQueryValue, VS_VERSION_INFO


GetFileVersionInfoSize function
GetFileVersionInfoSize (Win32)

DWORD GetFileVersionInfoSize(lpszFile, lpdwHandle)

LPTSTR lpszFile;	/* address of filename	*/
LPDWORD lpdwHandle;	/* always set to zero	*/

The GetFileVersionInfoSize function determines whether it can retrieve version information from the specified file. If version information is available, GetFileVersionInfoSize returns the size of the buffer required to hold the information.

As with the other file installation functions, GetFileVersionInfoSize will only work with Win32 file images. Sixteen-bit Windows file images are not supported.

Parameter	Description

lpszFile	Points to the null-terminated string that specifies the filename.

lpdwHandle	Points to a variable that this function sets to zero.

Returns

If the function succeeds, the return value is the buffer size, in characters, required to hold the version information. If the function fails, the return value is zero. To get extended error information, use the GetLastError function.

See Also

GetFileVersionInfo, VerQueryValue


GetSystemDir function
GetSystemDir (Win32)

The GetSystemDir function is not supported in the Win32 API. For Win32 applications, use the GetSystemDirectory function to determine the system directory.

See Also

GetSystemDirectory


GetWindowsDir function
GetWindowsDir (Win32)

The GetWindowsDir function is not supported in the Win32 API. Win32 applications can use the GetWindowsDirectory function to determine the Windows directory.

See Also

GetWindowsDirectory


VerFindFile function
VerFindFile (Win32)

DWORD VerFindFile(dwFlags, szFileName, szWinDir, szAppDir, szCurDir, lpuCurDirLen, szDestDir, lpuDestDirLen)

DWORD dwFlags;	/* is this a shared file?	*/
LPTSTR szFileName;	/* file to install	*/
LPTSTR szWinDir;	/* Windows directory	*/
LPTSTR szAppDir;	/* directory for file being installed	*/
LPTSTR szCurDir;	/* current working directory	*/
PUINT lpuCurDirLen;	/* size of string in szCurDir	*/
LPTSTR szDestDir;	/* recommended destination directory	*/
PUINT lpuDestDirLen;	/* size of string in szDestDir	*/

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. Sixteen-bit Windows file images are not supported.

Parameter	Description

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 for future use by Microsoft.

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.

Returns

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 for future use by Microsoft.

Comments

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

VerInstallFile


VerInstallFile function
VerInstallFile (Win32)

DWORD VerInstallFile(dwFlags, szSrcFileName, szDestFileName, szSrcDir, szDestDir, szCurDir, szTmpFile, lpuTmpFileLen)

DWORD dwFlags;	/* installation type	*/
LPTSTR szSrcFileName;	/* file to install	*/
LPTSTR szDestFileName;	/* new name of file to install	*/
LPTSTR szSrcDir;	/* directory for file being installed	*/
LPTSTR szDestDir;	/* directory in which to install file	*/
LPTSTR szCurDir;	/* current working directory	*/
LPTSTR szTmpFile;	/* temp. file used during install	*/
PUINT lpuTmpFileLen;	/* size of string in szTmpFile	*/

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 Win32T file images. Sixteen-bit Windows file images are not supported.

Parameter	Description

dwFlags	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 for future use by Microsoft.

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.

Returns

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 for future use by Microsoft.

Comments

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 function
VerLanguageName (Win32)

DWORD VerLanguageName(idLang, lpszLang, cbLang)

DWORD idLang;	/* Microsoft language identifier	*/
LPTSTR lpszLang;	/* address of buffer for language string	*/
DWORD cbLang;	/* size of buffer	*/

The VerLanguageName function converts the specified binary Microsoft language identifier into a text representation of the language.

Parameter	Description

idLang	Specifies the binary Microsoft language identifier. For example, VerLanguageName translates 0x040A into Castilian Spanish. If VerLanguageName does not recognize the identifier, the lpszLang parameter points to a default string ("Language-Neutral"). For a complete list of the language identifiers supported by the Win32 API, see the following Comments section.

lpszLang	Points to the buffer to receive the null-terminated string representing the language specified by the idLang parameter.

cbLang	Indicates the size of the buffer, in characters, pointed to by lpszLang.

Returns

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.

Comments

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.

Following are the possible language identifiers and their corresponding languages:

Identifier	Language

0x0000	Language-Neutral

0x0400	Process Default Language

0x0401	Arabic

0x0402	Bulgarian

0x0403	Catalan

0x0404	Traditional Chinese

0x0804	Simplified Chinese

0x0405	Czech

0x0406	Danish

0x0407	German

0x0807	Swiss German

0x0408	Greek

0x0409	U.S. English

0x0809	U.K. English

0x0C09	Australian English

0x1009	Canadian English

0x040A	Castilian Spanish

0x080A	Mexican Spanish

0x0C0A	Modern Spanish

0x040B	Finnish

0x040C	French

0x080C	Belgian French

0x0C0C	Canadian French

0x100C	Swiss French

0x040D	Hebrew

0x040E	Hungarian

0x040F	Icelandic

0x0410	Italian

0x0810	Swiss Italian

0x0411	Japanese

0x0412	Korean

0x0413	Dutch

0x0813	Belgian Dutch

0x0414	Norwegian--Bokmål

0x0814	Norwegian--Nynorsk

0x0415	Polish

0x0416	Brazilian Portuguese

0x0816	Portuguese

0x0417	Rhaeto-Romanic

0x0418	Romanian

0x0419	Russian

0x041A	Croato-Serbian (Latin)

0x081A	Serbo-Croatian (Cyrillic)

0x041B	Slovak

0x041C	Albanian

0x041D	Swedish

0x041E	Thai

0x041F	Turkish

0x0420	Urdu

0x0421	Bahasa


VerQueryValue function
VerQueryValue (Win32)

BOOL VerQueryValue(pBlock, lpSubBlock, lplpBuffer, puLen)

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

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. Sixteen-bit Windows file images are not supported.

Parameter	Description

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

Returns

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.

Comments

Windows NT 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_VERSION_INFO


File Installation Library

GetFileResource	Obsolete

GetFileResourceSize	Obsolete

GetFileVersionInfo	Returns version information about a file

GetFileVersionInfoSize	Returns the size of a file's version information

GetSystemDir	Obsolete

GetWindowsDir	Obsolete

VerFindFile	Determines where to install a file

VerInstallFile	Installs a file

VerLanguageName	Converts a binary language ID into a string

VerQueryValue	Returns version information about a block